Difference between revisions of "Setting up a Share Using Windows ACLs"

m (Updated links)
(Rewrote documentation. Clearer structure, removed unneccessary and incorrect details, revalidated content, added missing steps, explained where ACLs are stored in the back end, etc.)
Line 1: Line 1:
 
= Introduction =
 
= Introduction =
  
On every Samba host you can, as on any MS Windows OS, share a folder to make it accessible for other users. There's no difference if this host is a Samba [[Active_Directory_Domain_Controller|Active Directory Domain Controller]], a [[Setting_up_Samba_as_a_Domain_Member|Domain Member]] or a [[Setting_up_Samba_as_a_Standalone_Server|Standalone Server]]. File shares can be setup in two ways: Set [[Setting_up_a_Share_Using_POSIX_ACLs|completely via smb.conf parameters and POSIX ACLs]] or to be managed using Windows tools and ACLs. The latter is described in this documentation.
+
Extended access control lists (ACL) enable you to set permissions on shares, files, and directories using Windows ACLs and applications. Samba supports shares using extended ACLs on:
 +
* Domain members
 +
* Active Directory (AD) domain controllers (DC)
 +
* NT4 primary domain controller (PDC)
 +
* NT4 backup domain controllers (BDC)
 +
* Standalone hosts
  
'''Important note:''' Samba Active Directory Domain Controllers have extended ACL support enabled globally, to enable management of share permissions and ACLs via Windows!
+
As an alternative to extended ACLs, you can set up shares using POSIX ACLs. For details, see [[Setting_up_a_Share_Using_POSIX_ACLs|Setting up a Share Using POSIX ACLs]].
  
  
Line 9: Line 14:
  
  
= Preparatory work =
+
= Preparing the Host =
  
== File system support ==
+
Before you are able to create a share, set up Samba. For details, see:
 +
* [[Setting_up_Samba_as_a_Domain_Member|Setting up Samba as a Domain Member]]
 +
* [[Active_Directory_Domain_Controller|Setting up Samba as AD DC]]
 +
* [[Setting_up_Samba_as_an_NT4_PDC_(Quick_Start)|Setting up Samba as an NT4 PDC (Quick Start)]]
 +
* [[Setting_up_Samba_as_an_NT4_BDC|Setting up Samba as an NT4 BDC]]
 +
* [[Setting_up_Samba_as_a_Standalone_Server|Setting up Samba as a Standalone Server]]
  
Check that the filesystem, the share will reside on, supports the "user" and "system" xattr name spaces. It also requires ACL and XATTR support. See [[File_System_Support|File system support]] for further details.
 
  
  
 +
== File System Support ==
  
== Samba ACL support ==
+
The file system the share will be created on, must support:
 +
* user and system <code>xattr</code> name spaces.
 +
* extended access control lists (ACL).
  
Make sure, Samba was compiled with ACL support. Check with the following command:
+
For further details, see [[File_System_Support|File system support]].
 +
 
 +
 
 +
 
 +
== Samba Extended ACL Support ==
 +
 
 +
To create a share with extended access control list (ACL) support, the <code>smbd</code> service must been built with ACL support enabled. On a Samba hosts working as an Active Directory (AD) domain controller (DC), extended ACL support is always enabled.
 +
 
 +
To verify if Samba has been built with ACL support, enter:
  
 
  # smbd -b | grep HAVE_LIBACL
 
  # smbd -b | grep HAVE_LIBACL
 
     HAVE_LIBACL
 
     HAVE_LIBACL
  
If "HAVE_LIBACL" is not found, then Samba was compiled without extended ACL support. If you compiled Samba yourself, see [[Samba_Dependencies_Required_to_Build_Samba|Samba Dependencies Required to Build Samba]].
+
If no output is displayed:
 +
* Samba was built using the <code>--with-acl-support=no</code> parameter.
 +
* The Samba <code>configure</code> script was unable to locate the required libraries for ACL support. For details, see [[Samba_Dependencies_Required_to_Build_Samba|Samba Dependencies Required to Build Samba]].
 +
 
 +
 
 +
 
  
  
 +
== Enable Extended ACL Support in the <code>smb.conf</code> File ==
  
== Enable extended ACL support in smb.conf ==
+
To configure shares using extended access control lists (ACL), you must enable the the support in the <code>smb.conf</code> file. To enable extended ACL support globally, add the following settings to the <code>[global]</code> section of your <code>smb.conf</code> file:
  
''Only add The following lines to a Domain Member. Do not add them to a Domain Controller, they are already set in its code.''
+
vfs objects = acl_xattr
 +
map acl inherit = yes
 +
store dos attributes = yes
  
Add the following to your [global] section of your smb.conf:
+
{{Imbox
 +
| type = important
 +
| text = On a Samba Active Directory (AD) domain controller (DC), extended ACL support is automatically enabled globally. You must not enable the support manually.
 +
}}
  
        vfs objects = acl_xattr
+
Alternatively, to enable extended ACL support only for a specific share, add the parameters to the share's section.
        map acl inherit = yes
 
        store dos attributes = yes
 
  
See the smb.conf man page for further details on the parameters.
+
For further details about the parameters, see the <code>smb.conf(5)</code> man page.
  
== SeDiskOperatorPrivilege ==
 
  
Accounts that should be able to configure share permissions, require the privilege "SeDiskOperatorPrivilege". To view the current privilege list on a host, run
 
  
# net rpc rights list accounts -U'SAMDOM\administrator'
+
== Granting the <code>SeDiskOperatorPrivilege</code> Privilege ==
  
You may have the following error with the previous command:
+
Only users and groups having the <code>SeDiskOperatorPrivilege</code> privilege granted can configure share permissions. To grant the privilege to the <code>Domain Admins</code> group, enter:
  
  Could not connect to server 127.0.0.1
+
  # net rpc rights grant "SAMDOM\Domain Admins" SeDiskOperatorPrivilege -U "SAMDOM\administrator"
  Connection failed: NT_STATUS_CANT_ACCESS_DOMAIN_INFO
+
  Enter SAMDOM\administrator's password:
 +
Successfully granted rights.
  
If that's the case, retry by specifying a domain controller with the -I option:
+
{{Imbox
 +
| type = note
 +
| text = It is recommended to grant the permission to a group instead of individual accounts. This enables you to add and revoke the privilege by updating the group membership.
 +
}}
  
# net rpc rights list accounts -U'SAMDOM\administrator' -I dc1.samdom.example.com
+
To list all users and groups having the <code>SeDiskOperatorPrivilege</code> privilege granted, enter:
  
In the following, we will grant the privilege to the group "Domain Admins", but before doing this, make sure that the group is available to the local OS by [[Name_service_switch_(NSS)|NSS]]; usually via [[Winbindd|Winbindd]]:
+
# net rpc rights list privileges SeDiskOperatorPrivilege -U "SAMDOM\administrator"
 +
SeDiskOperatorPrivilege:
 +
  BUILTIN\Administrators
 +
  SAMDOM\Domain Admins
  
# getent group "Domain Admins"
 
domain admins:x:10001:
 
  
If you don't get an output showing the queried name and its ID, there may be something wrong in your [[Name_service_switch_(NSS)|NSS configuration]] or if you are using Winbindd with [[Idmap_config_ad|RFC2307 (idmap_ad)]], you might not have an ID assigned (see [[User_and_group_management|User and group management]] for how to administer Unix Attributes in an AD). If the "Domain Admins" group is available to the OS, you can grant the SeDiskOperatorPrivilege privilege to (add the "-I dc1.samdom.example.com" if you had the previous error with NT_STATUS_CANT_ACCESS_DOMAIN_INFO):
 
  
# net rpc rights grant 'SAMDOM\Domain Admins' SeDiskOperatorPrivilege -U'SAMDOM\administrator'
 
Enter SAMDOM\administrator's password:
 
Successfully granted rights.
 
  
= Adding a new share =
 
  
* Create the new shared folder, if it doesn't already exist
+
= Adding a Share =
  
# mkdir -p /srv/samba/Demo/
+
To share the <code>/srv/samba/Demo/</code> folder using the <code>Demo</code> share name:
  
* In order to allow a user or group to modify permissions, "Full control" is required. If you haven't modified it, the default value of "acl map full control" is "yes", this defines that "rwx" (read-write-execute) is mapped to "Full control". Accordingly to allow members of the "Domain Admins" group to edit permissions via Windows, we need to set the following:
+
* Create the folder:
  
  # chmod g=rwx /srv/samba/Demo/
+
  # mkdir -p /srv/samba/Demo/
# chgrp "Domain Admins" /srv/samba/Demo/
 
  
* Add the new share to your smb.conf. No further parameters other than the following are required or suggested (e. g. "force user/group" is not compatible with the vfs objects "acl_xattr" and can cause "Access denied" errors)!
+
* Add the <code>[Demo]</code> share definition to your <code>smb.conf</code> file:
  
 
  [Demo]
 
  [Demo]
Line 83: Line 109:
 
         read only = no
 
         read only = no
  
* Reload Samba
+
{{Imbox
 +
| type = important
 +
| text = Do not set additional share parameters, such as <code>force user</code>. Adding them to the share definition can prevent you from configuring or using the share.
 +
}}
 +
 
 +
: Further share-specific settings and file system permissions are set using the Windows utilities.
 +
 
 +
* Reload the Samba configuration:
  
 
  # smbcontrol all reload-config
 
  # smbcontrol all reload-config
Line 91: Line 124:
  
  
= Setup share permissions (optional) =
+
= Setting Share Permissions and ACLs =
 +
 
 +
When you configure a share with extended access control lists (ACL) support, you set the share permissions using Windows utilities instead of adding parameters to the share section in the <code>smb.conf</code> file.
  
* Log on to a Windows machine, using an account that is a member of the "Domain Admins" group
+
To set permissions and ACLs on the <code>Demo</code> share:
  
* Open the Start Menu, search for "Computer Management" and open the program
+
* Log on to a Windows host using an account that has the <code>SeDiskOperatorPrivilege</code> privilege granted.
  
* In the menu bar go to "Action" / "Connect to another computer"
+
* Click <code>Start</code>, enter <code>Computer Management</code>, and start the application.
  
* Enter the name of the Samba host on which you want to edit the share permissions
+
* Select <code>Action</code> / <code>Connect to another computer</code>.
  
* Navigate to "System Tools" / "Shared Folders" / "Shares" and select the desired share
+
* Enter the name of the Samba host.
 +
 
 +
* Open the <code>System Tools</code> / <code>Shared Folders</code> / <code>Shares</code> menu entry.
  
 
:[[Image:Computer_Management_Shares.png]]
 
:[[Image:Computer_Management_Shares.png]]
  
* Right-click to the share name and choose "Properties"
+
* Right-click to the share and select <code>Properties</code>.
 
 
* Go to the "Share Permissions" tab and define who is allowed to connect to the share
 
  
 +
* Select the <code>Share Permissions</code> tab and set the share permissions. For example:
 
:[[Image:Demo_Share_Permissions.png]]
 
:[[Image:Demo_Share_Permissions.png]]
  
* Save the changes by closing the windows with "OK"
+
: Samba stores share permissions in the <code>/usr/local/samba/var/locks/share_info.tdb</code> database.
  
 +
* Select the <code>Security</code> tab.
  
 +
* Click the <code>Edit</code> button and set the file system ACLs on the share's root directory. For example:
  
 +
:[[Image:Demo_Share_Security.png]]
  
 +
: For details where the ACLs are stored, see [[#File_System_ACLs_in_the_Back_End|File System ACLs in the Back End]].
  
= Set ACLs on the root of a share =
+
* Click <code>OK</code> to close the <code>Permissions for Demo</code> window.
  
* Log on to a Windows machine, using an account that is a member of the "Domain Admins" group
+
* Click <code>OK</code> to store the updated settings.
  
* Open the Start Menu, search for "Computer Management" and open the program
+
For further details about configuring share permissions and ACLs, see the Windows documentation.
  
* In the menu bar go to "Action" / "Connect to another computer"
 
  
* Enter the name of the Samba host on which you want to edit the share permissions
 
  
* Navigate to "System Tools" / "Shared Folders" / "Shares" and select the desired share
 
  
:[[Image:Computer_Management_Shares.png]]
 
  
* Right-click to the share name and choose "Properties"
+
= Setting ACLs on a Folder =
  
* Go to the "Security" tab, click the "Edit" button and configure the desired Windows ACLs
+
To set file system permissions on a folder located on a share that uses extended access control lists (ACL):
  
:[[Image:Demo_Share_Security.png]]
+
* Log on to a Windows host using an account that has <code>Full control</code> on the folder you want to modify the file system ACLs.
  
* Save the changes by closing the windows with "OK"
+
* Navigate to the folder.
  
 +
* Right-click to the folder and select <code>Properties</code>.
  
 +
* Select the <code>Security</code> tab and click the <code>Edit</code> button.
  
 +
* Set the permission. For example:
  
 +
:[[Image:Folder_Permissions.png]]
  
= Set ACLs on subfolders of a share =
+
: For details where the ACLs are stored, see [[#File_System_ACLs_in_the_Back_End|File System ACLs in the Back End]].
 
 
* Log on to a Windows machine, using an account that is a member of the "Domain Admins" group
 
  
* Navigate to the folder of which you want to change the permissions
+
* Click <code>OK</code> to close the <code>Permissions for Folder</code> window.
  
* Right-click to the folder and choose "Properties"
+
* Click <code>OK</code> to store the updated settings.
  
* Go to the "Security" tab and click the "Edit" button.
+
For further details about setting ACLs, see the Windows documentation.
  
* Change the permissions to your needs
 
  
:[[Image:Folder_Permissions.png]]
 
  
* Save the changes by closing the windows with "OK"
 
  
  
 +
= File System ACLs in the Back End =
  
 +
Samba stores the file system permissions in extended file system access control lists (ACL) and in an extended attribute. For example:
  
 +
* To list the extended ACLs of the <code>/srv/samba/Demo/</code> directory, enter:
  
= Troubleshooting =
+
# getfacl /srv/samba/Demo/
 +
# file: srv/samba/Demo/
 +
# owner: root
 +
# group: root
 +
user::rwx
 +
user:root:rwx
 +
group::---
 +
group:root:---
 +
group:domain\040users:rwx
 +
group:domain\040admins:rwx
 +
mask::rwx
 +
other::---
 +
default:user::rwx
 +
default:user:root:rwx
 +
default:group::---
 +
default:group:root:---
 +
default:group:domain\040users:rwx
 +
default:group:domain\040admins:rwx
 +
default:mask::rwx
 +
default:other::---
  
In certain situations, configuration parameters which were commonly used on [[Setting_up_a_Share_Using_POSIX_ACLs|shares with POSIX ACLs]], such as "force group" or "force user", may lead to "Access denied" errors when trying to set permissions on a new share or other complications, such as losing the ability to even see the "Security" tab. You may find, even after correcting the issues, that the problems may persist, even after removing and re-adding the share properly. In such cases, it may be helpful to manually wipe out all ACLs on the share and recursively re-grant full control to the Domain Admins group with the setfacl command as follows (need to run as root):
+
* To list the <code>user.SAMBA_PAI</code> extended attribute of the <code>/srv/samba/Demo/</code> directory, enter:
  
  # setfacl -R -b /srv/samba/Demo/
+
  # getfattr -d /srv/samba/Demo/
  # setfacl -R -b /srv/samba/Demo/*
+
  # file: srv/samba/Demo/
  # setfacl -R -m default:group:"Domain Admins":rwx /srv/samba/Demo/
+
  user.SAMBA_PAI=0sAgScBwAHAAABAAAAAAAAAAAAAAAC/////wABAAAAAAAAAAAAAAABEScAAAABECcAAAABAAAAAAAAAAAAAAAC/////wABAAAAAAAAAAAAAAMBEScAAAMBECcAAA==
  
 +
The previous example of file system ACLs and the extended attribute is mapped to the following Windows ACLs:
  
 +
{| class="wikitable"
 +
!Principal
 +
!Permissions
 +
!Applies to
 +
|-
 +
|Domain Users (SAMDOM\Domain Users)
 +
|Modify, Read & execute, List folder contents, Read, Write
 +
|(This folder, subfolders and files)
 +
|-
 +
|Domain Admins (SAMDOM\Domain Admins)
 +
|Full control
 +
|(This folder, subfolders and files)
 +
|}
  
  
  
= Related documentation =
 
  
The following documentation discusses related topics:
 
  
* [[User_home_drives|Setting up home drives]]
+
= Troubleshooting =
  
* [[Implementing_roaming_profiles|Implementing Windows roaming profiles]]
+
For troubleshooting, see:
 +
* [[Troubleshooting_Samba_Domain_Members|Troubleshooting Samba Domain Members]]
 +
* [[Samba_AD_DC_Troubleshooting|Samba AD DC Troubleshooting]]

Revision as of 18:09, 15 January 2017

Introduction

Extended access control lists (ACL) enable you to set permissions on shares, files, and directories using Windows ACLs and applications. Samba supports shares using extended ACLs on:

  • Domain members
  • Active Directory (AD) domain controllers (DC)
  • NT4 primary domain controller (PDC)
  • NT4 backup domain controllers (BDC)
  • Standalone hosts

As an alternative to extended ACLs, you can set up shares using POSIX ACLs. For details, see Setting up a Share Using POSIX ACLs.



Preparing the Host

Before you are able to create a share, set up Samba. For details, see:


File System Support

The file system the share will be created on, must support:

  • user and system xattr name spaces.
  • extended access control lists (ACL).

For further details, see File system support.


Samba Extended ACL Support

To create a share with extended access control list (ACL) support, the smbd service must been built with ACL support enabled. On a Samba hosts working as an Active Directory (AD) domain controller (DC), extended ACL support is always enabled.

To verify if Samba has been built with ACL support, enter:

# smbd -b | grep HAVE_LIBACL
   HAVE_LIBACL

If no output is displayed:



Enable Extended ACL Support in the smb.conf File

To configure shares using extended access control lists (ACL), you must enable the the support in the smb.conf file. To enable extended ACL support globally, add the following settings to the [global] section of your smb.conf file:

vfs objects = acl_xattr
map acl inherit = yes
store dos attributes = yes

Alternatively, to enable extended ACL support only for a specific share, add the parameters to the share's section.

For further details about the parameters, see the smb.conf(5) man page.


Granting the SeDiskOperatorPrivilege Privilege

Only users and groups having the SeDiskOperatorPrivilege privilege granted can configure share permissions. To grant the privilege to the Domain Admins group, enter:

# net rpc rights grant "SAMDOM\Domain Admins" SeDiskOperatorPrivilege -U "SAMDOM\administrator"
Enter SAMDOM\administrator's password:
Successfully granted rights.

To list all users and groups having the SeDiskOperatorPrivilege privilege granted, enter:

# net rpc rights list privileges SeDiskOperatorPrivilege -U "SAMDOM\administrator"
SeDiskOperatorPrivilege:
  BUILTIN\Administrators
  SAMDOM\Domain Admins



Adding a Share

To share the /srv/samba/Demo/ folder using the Demo share name:

  • Create the folder:
# mkdir -p /srv/samba/Demo/
  • Add the [Demo] share definition to your smb.conf file:
[Demo]
       path = /srv/samba/Demo/
       read only = no
Further share-specific settings and file system permissions are set using the Windows utilities.
  • Reload the Samba configuration:
# smbcontrol all reload-config



Setting Share Permissions and ACLs

When you configure a share with extended access control lists (ACL) support, you set the share permissions using Windows utilities instead of adding parameters to the share section in the smb.conf file.

To set permissions and ACLs on the Demo share:

  • Log on to a Windows host using an account that has the SeDiskOperatorPrivilege privilege granted.
  • Click Start, enter Computer Management, and start the application.
  • Select Action / Connect to another computer.
  • Enter the name of the Samba host.
  • Open the System Tools / Shared Folders / Shares menu entry.
Computer Management Shares.png
  • Right-click to the share and select Properties.
  • Select the Share Permissions tab and set the share permissions. For example:
Demo Share Permissions.png
Samba stores share permissions in the /usr/local/samba/var/locks/share_info.tdb database.
  • Select the Security tab.
  • Click the Edit button and set the file system ACLs on the share's root directory. For example:
Demo Share Security.png
For details where the ACLs are stored, see File System ACLs in the Back End.
  • Click OK to close the Permissions for Demo window.
  • Click OK to store the updated settings.

For further details about configuring share permissions and ACLs, see the Windows documentation.



Setting ACLs on a Folder

To set file system permissions on a folder located on a share that uses extended access control lists (ACL):

  • Log on to a Windows host using an account that has Full control on the folder you want to modify the file system ACLs.
  • Navigate to the folder.
  • Right-click to the folder and select Properties.
  • Select the Security tab and click the Edit button.
  • Set the permission. For example:
Folder Permissions.png
For details where the ACLs are stored, see File System ACLs in the Back End.
  • Click OK to close the Permissions for Folder window.
  • Click OK to store the updated settings.

For further details about setting ACLs, see the Windows documentation.



File System ACLs in the Back End

Samba stores the file system permissions in extended file system access control lists (ACL) and in an extended attribute. For example:

  • To list the extended ACLs of the /srv/samba/Demo/ directory, enter:
# getfacl /srv/samba/Demo/
# file: srv/samba/Demo/
# owner: root
# group: root
user::rwx
user:root:rwx
group::---
group:root:---
group:domain\040users:rwx
group:domain\040admins:rwx
mask::rwx
other::---
default:user::rwx
default:user:root:rwx
default:group::---
default:group:root:---
default:group:domain\040users:rwx
default:group:domain\040admins:rwx
default:mask::rwx
default:other::---
  • To list the user.SAMBA_PAI extended attribute of the /srv/samba/Demo/ directory, enter:
# getfattr -d /srv/samba/Demo/
# file: srv/samba/Demo/
user.SAMBA_PAI=0sAgScBwAHAAABAAAAAAAAAAAAAAAC/////wABAAAAAAAAAAAAAAABEScAAAABECcAAAABAAAAAAAAAAAAAAAC/////wABAAAAAAAAAAAAAAMBEScAAAMBECcAAA==

The previous example of file system ACLs and the extended attribute is mapped to the following Windows ACLs:

Principal Permissions Applies to
Domain Users (SAMDOM\Domain Users) Modify, Read & execute, List folder contents, Read, Write (This folder, subfolders and files)
Domain Admins (SAMDOM\Domain Admins) Full control (This folder, subfolders and files)



Troubleshooting

For troubleshooting, see: