== MIGRATION & INTEGRATION ==
'''Samba-3: Windows file and directory ACLs''' <<BR>>
John H Terpstra, CTO, Primastasys Inc. <<BR>>
20 Apr 2005

'''TABLE OF CONTENTS'''

 * Abstract
 * UNIX File and Directory Access Control
 * POSIX Access Control Lists
 * Conditions That Impact Availability of ACLs in Samba/UNIX
 * Windows NT/200X ACLs
 * Guidelines for the use of Windows ACLs with a Samba File Server
 * Conclusion

'''Abstract:''' Human nature is inclined towards the familiar, and whether a familiar method of solving a problem is the best or not makes little  difference if it has become our norm. The dental mechanic is inclined to use tools of the trade no matter what the problem may be, so it is not unusual to visit a dental laboratory to find the chairs held together with dental resin.

The parallel to this is that the Windows networking engineer will solve all file and directory access challenges with Windows ACLs, and the UNIX administrator will find this predilection both unnatural and awkward. Despite these opposing perspectives it is necessary to deal with them in an environment where Samba is used to provide Windows file and print services.

This article discusses the parallels between files and directories in the Windows and the UNIX worlds, creates understanding of the challenge to the transparent interoperability and proposes some simple solutions to common problems. Often the most natural solution is not the most manageable or appropriate one.

'''UNIX File and Directory Access Control'''

When UNIX was first created the necessity for multi-user use and operation made it necessary to produce an environment in which strict access controls could be affected so that both the memory address space used by concurrently executing applications are protected from each other, but that the file systems could also afford a level of access control necessary for secure system operation. The creators of the UNIX operating system were simple folk who could delight in the elegance of simple, but effective solutions.

It was reasoned that there are in principle three ways that control of access to a file or a directory might be established. It was determined that every file should have an owner, a group owner, and yet it may be necessary for everyone (anyone) to access it also. These names are generally rendered as user/group/others, or ugo for short. The implementation of UNIX file and directory access control is permitted or prevented depending on three flags: the read flag, the write flag, and the execute flag. They are represented as follows:

{{{
   type  user   group  other
   #     r w x  r w x  r w x
}}}

The type flag can be one of:

 * l = symbolic link
 * d = directory
 * b = block device
 * c = character device
 * p = fifo device
 * s = unix domain socket

The UNIX file and directory permissions may be set using the operating system tool chmod as shown here:

{{{chmod 0640 a_file}}}

The permissions can be set as shown using the octal values: r=4,w=2,x=1 (an octal number begins with the value "0").

The same permissions can be set using the following command:

{{{chmod u=rw,g=r,o-rwx a_file}}}

Note: There are no spaces between the u and the x.

The "r" means the user, group, or others entity has read privilege. The "w" means this entity has write and delete privilege, and the "x" means the entity has execute privilege. The same permission applies to a directory with the exception that "x" permission gives the entity directory listing permission.

Within the UNIX operating system, a directory is a file that contains references to the files within it. A directory is a special type of file that is of type "d."

There are three further bits that must be mentioned: the SUID, SGID and the sticky bit. The Samba-HOWTO-Collection (The Official Samba-3 HOWTO and Reference Guide) documents what these mean and how they may be used.

UNIX file system access controls are simple, but effective. Every UNIX user has a UID (user ID), a primary GID (group ID), a specified home directory and a specified command shell. Users may also be members of multiple groups, though older UNIX systems set limits on the number of groups a user may be a member of. For example, Solaris has a limit of 16 groups and some older UNIX implementations have a limit of 8 groups. Group memberships other than the primary group are called secondary groups. The use of secondary groups poses some difficulty with older versions of Samba. More recent versions permit multiple secondary group membership up to the limit of the host operating system.

Within the UNIX environment a new file will always be owned by the user and the primary group that is set for that user in the user account database (typically /etc/passwd).

Within UNIX it is not possible to have groups that are members of groups.


'''POSIX Access Control Lists'''

It was argued by some that the ugo access control method did not permit sufficiently fine-grained control for the advanced UNIX administrator. This led to the development and implementation of the POSIX (portable operating system interoperability standards) Access Control List (ACL) capabilities. Unfortunately, there is no universally recognized standard for UNIX ACLs; the one implemented by Samba is Draft standard 1003.1e revision 17. It specifies an application programming interface (API). The various differing ways vendors have implemented the POSIX ACL standards means that Samba must maintain its own interface layer that maps POSIX ACL system calls to the correct one for the host UNIX operating system. The pressure for Samba to support Windows ACLs has put pressure on the standardization of ACLs.

POSIX ACLs provide a meta-file extension of the UNIX ugo permissions. While designed to be simple in concept and in use, ACLs can quickly lead to great complications. ACLs can be set on files and on directories. The only modes of access each Access Control Entry (ACE) in an ACL supports are: read, write and execute (rwx).

Like ugo permissions, a reset value "-" for an access mode means deny, and a set value means permit. ACLs add the capabilities of setting inheritance and mask controls on files and directories. Masks override group permissions.

There are two -- and only two -- conditions that would warrant the creation of a POSIX ACL on a file or a directory:

 1. To provide an access exception for a user who is not a member of the primary group, or to provide and access exception for a group other than the owner-group.
 1. To specifically exclude particular users who are a member of the owner-group from accessing the file or directory.

One of the big challenges in the use of POSIX ACLs is backup and recovery of a backup. The UNIX tools cpio and tar do not permit POSIX ACLs to be backed up. The pax, star and dump tools do permit this, but few UNIX administrators are aware of these tools. Some UNIX systems with ACL support do not have the tools, or administrators do not use them.

This means that UNIX POSIX ACLs can easily get lost in the event of a major system failure that necessitates recovery from a backup medium. The potential for loss of essential file system meta-data must be considered a liability of use.

A POSIX file ACL can be obtained by executing: {{{getfacl a_file}}}<<BR>>
It has the following structure:

{{{
# file: testfile <- the file name 
# owner: jeremy <-- the file owner 
# group: users  <-- the POSIX group owner 
user::rwx    <-- perms for the file owner (user) 
user:tpot:r-x  <-- perms for the additional user tpot 
group::r--    <-- perms for the file group owner (group)
group:engrs:r-- <-- perms for the additonal group engineers 
mask:rwx     <-- the mask that is ANDed with groups 
other::---    <-- perms applied to everyone else (other)
}}}

A directory ACL is obtained the same way and has the following structure:

{{{
# file: testdir    <-- the directory name 
# owner: jeremy    <-- the directory owner 
# group: jeremy    <-- the POSIX group owner 
user::rwx       <-- directory perms for owner (user) 
group::rwx      <-- directory perms for owning group (group)
mask::rwx       <-- the mask that is ANDed with group perms 
other:r-x       <-- perms applied to everyone else (other) 
default:user::rwx   <-- inherited owner perms 
default:user:tpot:rwx <-- inherited extra perms for user tpot 
default:group::r-x  <-- inherited group perms 
default:mask:rwx   <-- inherited default mask
default:other:---   <-- inherited permissions for everyone (other)
}}}

'''Conditions That Impact Availability of ACLs in Samba/UNIX'''

Those who subscribe to the Samba mailing list will occasionally witness the consternation of administrators who are unable to create ACLs on the Samba host server from within the Windows Explorer. In all cases to date the problem has been a simple oveersight, either through lack of knowledge or through a simple little bit of information that was lost or forgotten during installation.

There are five parameters that must be met for Windows ACLs to function with Samba servers:

 * kernel support
 * file system support
 * support libraries installed
 * file system mounted with ACL support
 * Samba compiled and linked with ACL support

(a) Kernel ACL Support

Kernel support for POSIX ACLs is native to most relatively current generation UNIX systems. This is not the case for many Linux systems. The Linux-2.4.x series kernel does not have native ACLs support and requires the addition of the BestBits ACLs patch before this functionality can be obtained. Linux-2.6.x kernels do have native ACLs support, but it must be selected and built into the currently generated kernel for this to function. The Linux-2.6.x kernel configuration file entries to enable ACLs are as follows:

{{{
CONFIG_EXT2_FS_POSIX_ACL=y
CONFIG_EXT3_FS_POSIX_ACL=y
CONFIG_REISERFS_FS_POSIX_ACL=y
CONFIG_JFS_POSIX_ACL=y
CONFIG_FS_POSIX_ACL=y
CONFIG_XFS_POSIX_ACL=y
CONFIG_NFS_ACL=y
CONFIG_NFSD_ACL=y
CONFIG_NFS_ACL_SUPPORT=y
}}}

These settings were obtained from the {{{/usr/src/linux/.config}}} file, and they highlight the filesystem types for which ACLs can be either enabled or disabled.

(b) File System Type Must Have ACL Support

The Linux file systems ext2fs, ext3fs, reiserfs, jfs, xfs, and nfs can all be ACL enabled. Such enablement is determined as shown above by having this support in the Linux kernel. UNIX system users should verify that support for ACLs is available in the file system type that is being used.

(c) ACL Support Library Availability and Samba ACLs Enablement

Linux systems require the installation of particular libraries. For example the linux-2.6.x kernel requires, for ACLs support, the availability of the libacl.so and libattr.so libraries. The RPM packages that provide these libraries are respectively called: libacl-2.2.25 and libattr-2.4.16. When Samba is compiled on a Linux system the respective development libraries must also be installed prior to compilation. Support for ACLs in the Samba executables can be validated by executing:

{{{
merlin: # > smbd -b | grep ACL
  HAVE_SYS_ACL_H
  HAVE_POSIX_ACLS
}}}

(d) File Systems Mounted with ACLs Support

UNIX/Linux systems that are ACL enabled may have file systems that have been mounted without ACL support. The best way to verify that mounted file systems have ACL support enabled can be done by executing:

{{{
merlin: # > mount
/dev/mapper/system-ROOT on / type reiserfs (rw,acl,user_xattr)
/dev/hda1 on /boot type reiserfs (rw,acl,user_xattr)
/dev/sda5 on /data type reiserfs (rw,acl,user_xattr)
/dev/mapper/system-VAR on /var type reiserfs (rw,acl,user_xattr)
/dev/hdb1 on /data2 type reiserfs (rw,acl,user_xattr)
frodo:/home on /home type nfs (rw,soft,rsize=8192,wsize=8192,posix,acl,addr=192.168.1.1)
frodo:/home2 on /home2 type nfs (rw,soft,rsize=8192,wsize=8192,posix,acl,addr=192.168.1.1)
nfsd on /proc/fs/nfsd type nfsd (rw)
}}}

The above response from the mount query confirms that ACLs are supported on all mounted file systems, including NFS mounts.

When all the above conditions have been validated a simple test for ACL support can be conducted by executing the following:

{{{
merlin: # > touch testfile
merlin: # > setfacl -m user:bin:rwx testfile
merlin: # > getfacl testfile# file: testfile
# owner: root
# group: root
user::rwx
user:bin:rwx <==== This ACE proves that ACLs are supported
group::rwx
mask::rwx
other::r--
}}}

All things being equal, so to speak, ACLs support should now be possible through Samba. The next consideration in the use of Windows NT/200X ACLs by Windows workstation client users requires an understanding of how they are mapped to POSIX ACLs.

'''Windows NT/200X ACLs'''

The following table provides a summary of the 14 key ACE flags that are supported in Windows 2000 and later products (for example, Windows XP Professional):

||'''Windows ACE'''||'''File Attribute Flag'''||
||Full Control||#||
||Traverse Folder/Execute File||x||
||List Folder/Read Data||r||
||Read Attributes||r||
||Read Extended Attributes||r||
||Create Files/Write Data||w||
||Create Folders/Append Data||w||
||Write Attributes||w||
||Write Extended Attributes||w||
||Delete Subfolders and Files||w||
||Delete||#||
||Read Permissions ||all||
||Change Permissions||#||
||Take Ownership||#||

In this table, the # character means this flag is selected only when the Full Control flag is set. The File Attribute Flag shown in the right column shows how the Windows ACE flags are mapped to UNIX POSIX ACL permissions of rwx for users/groups/others (ugo) and for the extended POSIX ACLs described earlier. The reference to "all" means that read permission can not be denied for the owner and group owner of a UNIX file or directory.

As can be seen from the table, many Windows ACE flags have no equivalent in the UNIX operating system space. The Samba Team was thus compelled to map the flags in a sensible manner so as to achieve the net desired capability to copy files and directories with preservation of Windows ACL controls. The net result, however, is that files copied from a Windows 200X server to a Samba server will lose some ACL information. This is inconsequential so long as the files are then not copied back to the Windows 200X server.

Windows ACLS are familiar to Windows network administrators because they are the sole tool available for access control to files, directories and shares. Windows NT/200X systems have no concept of an inherent scheme of ownership by a user/group/other triplet. Windows files do have a concept of an owner, but not a group owner. Access control is entirely implemented by way of ACLs.

In fact, it is entirely possible under Windows to remove all ACEs from the ACL. In earlier versions of Windows (3.10) it was possible for the Windows administrator to do so, with the result that even the administrator then could not access the affected files. The recovery of dis-accessed files on such systems required giving the administrator appropriate rights and privileges to permit the dis-accessed files to be reclaimed. Such problem is not possible within the UNIX operating system environment. Fortunately, since Windows NT4 the administrator by default has the ability to recover dis-accessed files.

Windows ACLs are horribly complicated compared with the simplicity of UNIX file and directory permissions and POSIX extended ACLs. Windows ACLs were designed from a computing science perspective to provide such complex capabilities that most Windows administrators fail to correctly understand how best to use them. Furthermore, few Windows programmers understand how to correctly use the ACL API, resulting in most Windows applications not making use of ACLs as they could.

Windows ACLs are highly specific with complex orders of precedence. One common mistake that is made by new users is to implement the following specification (as a manager might prescibe it):

 * Everyone should be denied access to XYZ folder and files
 * Engineers should have read access
 * Managers should have write access

Faulty implementation:

 * Everyone (No Access)
 * Engineers (read only)
 * Managers (Full Control)

The problem with this specification is that all Engineers and Managers are members of the Everyone group and will be denied access because the global denial ACE has higher precedence than the permission ACEs. It was necessary only to specify the ACEs for Engineers and for Managers. The complexity of such an ACL is readily avoided with POSIX ACLs under UNIX and therefore also with Samba since it transparently passes all access controls through to the host operating system.

'''Guidelines for the use of Windows ACLs with a Samba File Server'''

It is useful to consider what will happen when a Windows file is copied to a Samba server that has ACL support.

Let us assume that a file that has the following ACL is copied by the user "root" from a Windows server to a Samba server. It is necessary that the domain user "root" must have a relative identifier (RID) of 500 so that this account is acknowledged under Windows as the domain administrator.

The ACL on this hypothetical file has the following ACEs:

 * Owner: jht
 * jht has Full Control
 * Domain users have read control
 * Accountants have read and write control
 * Technicians have Full Control


When appropriately copied to the Samba server (using a tool such as robocopy) the file attributes on the UNIX host server will be:

{{{
 owner:jht:rwx
 owner group:Domain Admins:rw-
 group:Domain Users:r--
 group:Accountants:rw-
 group:Technicians:rwx
}}}

If the user "jht" did not exist at the time the file was copied it will be owned by the "root" account (the valid account that created the file).

The above information will be stored in an extended POSIX ACL. What will hopefully be obvious by now, is that the use of an extended POSIX ACL can be avoided entirely by setting the owner/group/other permissions to: {{{-rw-rw-r-- jht Technicians}}}

{{{
i.e.: owner:jht:rw-
      group owner:Technicians:r-
      other::r--
}}}

By creating a security setting on the share via the MMC console from a Windows client, an ACL can be created so that only Accountants and Technicians can attach to the share. The resulting solution avoids that need to use an extended POSIX ACL and yet has the same access control as the original Windows ACL, but the benefit is that UNIX server file access overhead will be much lower than compared with the overhead of processing the complex ACL that was created by a simple robocopy transfer of the file.

A factor that is not often realized by inexperienced Windows network administrators (and certainly missed by many users) is that the copying of Windows files using the Windows Explorer fails to copy the originating file ACL, instead a new one is created from that which is inherited from the directory on the target server. This happens in a pure Windows environment as well as with Samba.

'''Conclusion'''

When the use of Windows ACLs in a Samba server environment is properly thought out, it is possible to significantly simplify system management overheads as well as to streamline access controls. The result is a higher performance network that confers improved ability for disaster recovery.

The effort required to become familiar with proper ACLs management can be well rewarded, and may help the Samba administrator to avoid potentially confusing and/or confrontational problems.