diff options
Diffstat (limited to 'docs-xml/Samba3-HOWTO/TOSHARG-AccessControls.xml')
| -rw-r--r-- | docs-xml/Samba3-HOWTO/TOSHARG-AccessControls.xml | 1710 |
1 files changed, 1710 insertions, 0 deletions
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-AccessControls.xml b/docs-xml/Samba3-HOWTO/TOSHARG-AccessControls.xml new file mode 100644 index 00000000000..48f439deadc --- /dev/null +++ b/docs-xml/Samba3-HOWTO/TOSHARG-AccessControls.xml @@ -0,0 +1,1710 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> + +<chapter id="AccessControls"> +<chapterinfo> + &author.jht; + &author.jeremy; + <author>&person.jelmer;<contrib>drawing</contrib></author> + <pubdate>May 10, 2003</pubdate> +</chapterinfo> +<title>File, Directory, and Share Access Controls</title> + +<para> +<indexterm><primary>ACLs</primary></indexterm> +<indexterm><primary>share</primary></indexterm> +<indexterm><primary>network access controls</primary></indexterm> +<indexterm><primary>unauthorized access</primary></indexterm> +Advanced MS Windows users are frequently perplexed when file, directory, and share manipulation of +resources shared via Samba do not behave in the manner they might expect. MS Windows network +administrators are often confused regarding network access controls and how to +provide users with the access they need while protecting resources from unauthorized access. +</para> + +<para> +<indexterm><primary>file access permissions</primary></indexterm> +<indexterm><primary>directory access permissions</primary></indexterm> +Many UNIX administrators are unfamiliar with the MS Windows environment and in particular +have difficulty in visualizing what the MS Windows user wishes to achieve in attempts to set file +and directory access permissions. +</para> + +<para> +<indexterm><primary>bridge</primary></indexterm> +<indexterm><primary>directory controls</primary></indexterm> +<indexterm><primary>directory permissions</primary></indexterm> +<indexterm><primary></primary></indexterm> +The problem lies in the differences in how file and directory permissions and controls work +between the two environments. This difference is one that Samba cannot completely hide, even +though it does try to bridge the chasm to a degree. +</para> + +<para> +<indexterm><primary>Extended Attributes</primary></indexterm> +<indexterm><primary>ACLs</primary><secondary>POSIX</secondary></indexterm> +<indexterm><primary>Access Control List</primary></indexterm> +<indexterm><primary>commercial Linux products</primary></indexterm> +POSIX Access Control List technology has been available (along with extended attributes) +for UNIX for many years, yet there is little evidence today of any significant use. This +explains to some extent the slow adoption of ACLs into commercial Linux products. MS Windows +administrators are astounded at this, given that ACLs were a foundational capability of the now +decade-old MS Windows NT operating system. +</para> + +<para> +<indexterm><primary>network administrator</primary></indexterm> +The purpose of this chapter is to present each of the points of control that are possible with +Samba-3 in the hope that this will help the network administrator to find the optimum method +for delivering the best environment for MS Windows desktop users. +</para> + +<para> +<indexterm><primary>interoperability</primary></indexterm> +<indexterm><primary>data interchange</primary></indexterm> +This is an opportune point to mention that Samba was created to provide a means of interoperability +and interchange of data between differing operating environments. Samba has no intent to change +UNIX/Linux into a platform like MS Windows. Instead the purpose was and is to provide a sufficient +level of exchange of data between the two environments. What is available today extends well +beyond early plans and expectations, yet the gap continues to shrink. +</para> + +<sect1> +<title>Features and Benefits</title> + + <para> + Samba offers much flexibility in file system access management. These are the key access control + facilities present in Samba today: + </para> + + <itemizedlist> + <title>Samba Access Control Facilities</title> + <listitem><para> + <indexterm><primary>permissions</primary><secondary>UNIX file and directory</secondary></indexterm> + <emphasis>UNIX File and Directory Permissions</emphasis> + </para> + + <para> +<indexterm><primary>UNIX file system access controls</primary></indexterm> +<indexterm><primary>access controls</primary></indexterm> +<indexterm><primary>permissions and controls</primary></indexterm> + Samba honors and implements UNIX file system access controls. Users + who access a Samba server will do so as a particular MS Windows user. + This information is passed to the Samba server as part of the logon or + connection setup process. Samba uses this user identity to validate + whether or not the user should be given access to file system resources + (files and directories). This chapter provides an overview for those + to whom the UNIX permissions and controls are a little strange or unknown. + </para> + </listitem> + + <listitem><para> + <emphasis>Samba Share Definitions</emphasis> + </para> + + <para> +<indexterm><primary>share settings</primary></indexterm> + In configuring share settings and controls in the &smb.conf; file, + the network administrator can exercise overrides to native file + system permissions and behaviors. This can be handy and convenient + to effect behavior that is more like what MS Windows NT users expect, + but it is seldom the <emphasis>best</emphasis> way to achieve this. + The basic options and techniques are described herein. + </para> + </listitem> + + <listitem><para> + <emphasis>Samba Share ACLs</emphasis> + <indexterm><primary>ACLs</primary><secondary>share</secondary></indexterm> + </para> + + <para> +<indexterm><primary>ACLs on shares</primary></indexterm> + Just as it is possible in MS Windows NT to set ACLs on shares + themselves, so it is possible to do in Samba. + Few people make use of this facility, yet it remains one of the + easiest ways to affect access controls (restrictions) and can often + do so with minimum invasiveness compared with other methods. + </para> + </listitem> + + <listitem><para> + <indexterm><primary>ACLs</primary><secondary>POSIX</secondary></indexterm> + <indexterm><primary>ACLs</primary><secondary>Windows</secondary></indexterm> + <emphasis>MS Windows ACLs through UNIX POSIX ACLs</emphasis> + </para> + + <para> +<indexterm><primary>native ACLs</primary></indexterm> + The use of POSIX ACLs on UNIX/Linux is possible only if the underlying + operating system supports them. If not, then this option will not be + available to you. Current UNIX technology platforms have native support + for POSIX ACLs. There are patches for the Linux kernel that also provide + this support. Sadly, few Linux platforms ship today with native ACLs and + extended attributes enabled. This chapter has pertinent information + for users of platforms that support them. + </para> + </listitem> + </itemizedlist> + +</sect1> + +<sect1> +<title>File System Access Controls</title> + +<para> +Perhaps the most important recognition to be made is the simple fact that MS Windows NT4/200x/XP +implement a totally divergent file system technology from what is provided in the UNIX operating system +environment. First we consider what the most significant differences are, then we look +at how Samba helps to bridge the differences. +</para> + + <sect2> + <title>MS Windows NTFS Comparison with UNIX File Systems</title> + + <para> + <indexterm><primary>NTFS</primary></indexterm> + <indexterm><primary>File System</primary></indexterm> + <indexterm><primary>File System</primary><secondary>UNIX</secondary></indexterm> + <indexterm><primary>File System</primary><secondary>Windows</secondary></indexterm> + Samba operates on top of the UNIX file system. This means it is subject to UNIX file system conventions + and permissions. It also means that if the MS Windows networking environment requires file system + behavior, that differs from UNIX file system behavior then somehow Samba is responsible for emulating + that in a transparent and consistent manner. + </para> + + <para> + It is good news that Samba does this to a large extent, and on top of that, provides a high degree + of optional configuration to override the default behavior. We look at some of these overrides, + but for the greater part we stay within the bounds of default behavior. Those wishing to explore + the depths of control ability should review the &smb.conf; man page. + </para> + + <para>The following compares file system features for UNIX with those of MS Windows NT/200x: + <indexterm><primary>File System</primary><secondary>feature comparison</secondary></indexterm> + + </para> + + <variablelist> + <varlistentry> + <term>Name Space</term> + <listitem> + <para> + MS Windows NT4/200x/XP file names may be up to 254 characters long, and UNIX file names + may be 1023 characters long. In MS Windows, file extensions indicate particular file types; + in UNIX this is not so rigorously observed because all names are considered arbitrary. + </para> + <para> + What MS Windows calls a folder, UNIX calls a directory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Case Sensitivity</term> + <listitem> + <para> + <indexterm><primary>8.3 file names</primary></indexterm> + <indexterm><primary>File System</primary><secondary>case sensitivity</secondary></indexterm> + MS Windows file names are generally uppercase if made up of 8.3 (8-character file name + and 3 character extension. File names that are longer than 8.3 are case preserving and case + insensitive. + </para> + + <para> + UNIX file and directory names are case sensitive and case preserving. Samba implements the + MS Windows file name behavior, but it does so as a user application. The UNIX file system + provides no mechanism to perform case-insensitive file name lookups. MS Windows does this + by default. This means that Samba has to carry the processing overhead to provide features + that are not native to the UNIX operating system environment. + </para> + + <para> + Consider the following. All are unique UNIX names but one single MS Windows file name: + <screen> + MYFILE.TXT + MyFile.txt + myfile.txt + </screen></para> + + <para> + So clearly, in an MS Windows file namespace these three files cannot co-exist, but in UNIX + they can. + </para> + + <para> + So what should Samba do if all three are present? That which is lexically first will be + accessible to MS Windows users; the others are invisible and unaccessible &smbmdash; any + other solution would be suicidal. The Windows client will ask for a case-insensitive file + lookup, and that is the reason for which Samba must offer a consistent selection in the + event that the UNIX directory contains multiple files that would match a case insensitive + file listing. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>Directory Separators</term> + <listitem><para> + <indexterm><primary>Directory Separators</primary></indexterm> + MS Windows and DOS use the backslash <constant>\</constant> as a directory delimiter, and UNIX uses + the forward-slash <constant>/</constant> as its directory delimiter. This is handled transparently by Samba. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>Drive Identification</term> + <listitem><para> + <indexterm><primary>Drive Identification</primary></indexterm> + MS Windows products support a notion of drive letters, like <command>C:</command>, to represent + disk partitions. UNIX has no concept of separate identifiers for file partitions; each + such file system is mounted to become part of the overall directory tree. + The UNIX directory tree begins at <constant>/</constant> just as the root of a DOS drive is specified as + <constant>C:\</constant>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>File Naming Conventions</term> + <listitem><para> + <indexterm><primary>File Naming Conventions</primary></indexterm> + MS Windows generally never experiences file names that begin with a dot (<constant>.</constant>), while in UNIX these + are commonly found in a user's home directory. Files that begin with a dot (<constant>.</constant>) are typically + startup files for various UNIX applications, or they may be files that contain + startup configuration data. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>Links and Short-Cuts</term> + <listitem><para> + <indexterm><primary>Links</primary><secondary>hard</secondary></indexterm> + <indexterm><primary>Links</primary><secondary>soft</secondary></indexterm> + <indexterm><primary>Shortcuts</primary></indexterm> + MS Windows make use of <emphasis>links and shortcuts</emphasis> that are actually special types of files that will + redirect an attempt to execute the file to the real location of the file. UNIX knows of file and directory + links, but they are entirely different from what MS Windows users are used to. + </para> + + <para> + Symbolic links are files in UNIX that contain the actual location of the data (file or directory). An + operation (like read or write) will operate directly on the file referenced. Symbolic links are also + referred to as <quote>soft links.</quote> A hard link is something that MS Windows is not familiar with. It allows + one physical file to be known simultaneously by more than one file name. + </para></listitem> + </varlistentry> + </variablelist> + + <para> + There are many other subtle differences that may cause the MS Windows administrator some temporary discomfort + in the process of becoming familiar with UNIX/Linux. These are best left for a text that is dedicated to the + purpose of UNIX/Linux training and education. + </para> + + </sect2> + + <sect2> + <title>Managing Directories</title> + + <para> +<indexterm><primary>create</primary></indexterm> +<indexterm><primary>delete</primary></indexterm> +<indexterm><primary>rename</primary></indexterm> + There are three basic operations for managing directories: <command>create</command>, <command>delete</command>, + <command>rename</command>. <link linkend="TOSH-Accesstbl">Managing Directories with UNIX and + Windows</link> compares the commands in Windows and UNIX that implement these operations. + </para> + + <table frame="all" id="TOSH-Accesstbl"> + <title>Managing Directories with UNIX and Windows</title> + <tgroup align="center" cols="3"> + <thead> + <row><entry>Action</entry><entry>MS Windows Command</entry><entry>UNIX Command</entry></row> + </thead> + + <tbody> + <row><entry>create</entry><entry>md folder</entry><entry>mkdir folder</entry></row> + <row><entry>delete</entry><entry>rd folder</entry><entry>rmdir folder</entry></row> + <row><entry>rename</entry><entry>rename oldname newname</entry><entry>mv oldname newname</entry></row> + </tbody> + </tgroup> + </table> + + </sect2> + + <sect2> + <title>File and Directory Access Control</title> + + <para> + <indexterm><primary>ACLs</primary><secondary>File System</secondary></indexterm> +<indexterm><primary>POSIX ACLs</primary></indexterm> +<indexterm><primary>EAs</primary></indexterm> + The network administrator is strongly advised to read basic UNIX training manuals and reference materials + regarding file and directory permissions maintenance. Much can be achieved with the basic UNIX permissions + without having to resort to more complex facilities like POSIX ACLs or extended attributes (EAs). + </para> + + <para> + UNIX/Linux file and directory access permissions involves setting three primary sets of data and one control set. + A UNIX file listing looks as follows: +<screen> +&prompt;<userinput>ls -la</userinput> +total 632 +drwxr-xr-x 13 maryo gnomes 816 2003-05-12 22:56 . +drwxrwxr-x 37 maryo gnomes 3800 2003-05-12 22:29 .. +dr-xr-xr-x 2 maryo gnomes 48 2003-05-12 22:29 muchado02 +drwxrwxrwx 2 maryo gnomes 48 2003-05-12 22:29 muchado03 +drw-rw-rw- 2 maryo gnomes 48 2003-05-12 22:29 muchado04 +d-w--w--w- 2 maryo gnomes 48 2003-05-12 22:29 muchado05 +dr--r--r-- 2 maryo gnomes 48 2003-05-12 22:29 muchado06 +drwsrwsrwx 2 maryo gnomes 48 2003-05-12 22:29 muchado08 +---------- 1 maryo gnomes 1242 2003-05-12 22:31 mydata00.lst +--w--w--w- 1 maryo gnomes 7754 2003-05-12 22:33 mydata02.lst +-r--r--r-- 1 maryo gnomes 21017 2003-05-12 22:32 mydata04.lst +-rw-rw-rw- 1 maryo gnomes 41105 2003-05-12 22:32 mydata06.lst +&prompt; +</screen> + </para> + + <para> + The columns represent (from left to right) permissions, number of hard links to file, owner, group, size + (bytes), access date, time of last modification, and file name. + </para> + + <para> + An overview of the permissions field is shown in <link linkend="access1">Overview of UNIX permissions + field</link>. + </para> + + <figure id="access1"> + <title>Overview of UNIX permissions field.</title> + <imagefile scale="40">access1</imagefile> + </figure> + + <para> + Any bit flag may be unset. An unset bit flag is the equivalent of "cannot" and is represented + as a <quote>-</quote> character (see <link linkend="access2"/>) +<indexterm><primary>read</primary></indexterm> +<indexterm><primary>write</primary></indexterm> +<indexterm><primary>execute</primary></indexterm> +<indexterm><primary>user</primary></indexterm> +<indexterm><primary>group</primary></indexterm> +<indexterm><primary>other</primary></indexterm> + </para> + +<example id="access2"> +<title>Example File</title> +<programlisting> +-rwxr-x--- Means: + ^^^ The owner (user) can read, write, execute + ^^^ the group can read and execute + ^^^ everyone else cannot do anything with it. +</programlisting> +</example> + + + <para> +<indexterm><primary>character device</primary></indexterm> +<indexterm><primary>block device</primary></indexterm> +<indexterm><primary>pipe device</primary></indexterm> +<indexterm><primary>UNIX Domain Socket</primary></indexterm> + Additional possibilities in the [type] field are c = character device, b = block device, p = pipe device, + s = UNIX Domain Socket. + </para> + + <para> +<indexterm><primary>read</primary></indexterm> +<indexterm><primary>write</primary></indexterm> +<indexterm><primary>execute</primary></indexterm> +<indexterm><primary>SGID</primary></indexterm> +<indexterm><primary>SUID</primary></indexterm> + The letters <constant>rwxXst</constant> set permissions for the user, group, and others as read (r), write (w), + execute (or access for directories) (x), execute only if the file is a directory or already has execute + permission for some user (X), set user (SUID) or group ID (SGID) on execution (s), sticky (t). + </para> + + <para> +<indexterm><primary>sticky bit</primary></indexterm> +<indexterm><primary>unlinked</primary></indexterm> +<indexterm><primary>/tmp</primary></indexterm> +<indexterm><primary>world-writable</primary></indexterm> + When the sticky bit is set on a directory, files in that directory may be unlinked (deleted) or renamed only by root or their owner. + Without the sticky bit, anyone able to write to the directory can delete or rename files. The sticky bit is commonly found on + directories, such as <filename>/tmp</filename>, that are world-writable. + </para> + + <para> +<indexterm><primary>write</primary></indexterm> +<indexterm><primary>read</primary></indexterm> +<indexterm><primary>setting up directories</primary></indexterm> +<indexterm><primary>set user id</primary><see>SUID</see></indexterm> +<indexterm><primary>set group id</primary><see>SGID</see></indexterm> + When the set user or group ID bit (s) is set on a directory, then all files created within it will be owned by the user and/or + group whose `set user or group' bit is set. This can be helpful in setting up directories for which it is desired that + all users who are in a group should be able to write to and read from a file, particularly when it is undesirable for that file + to be exclusively owned by a user whose primary group is not the group that all such users belong to. + </para> + + <para> + When a directory is set <constant>d-wx--x---</constant>, the owner can read and create (write) files in it, but because + the (r) read flags are not set, files cannot be listed (seen) in the directory by anyone. The group can read files in the + directory but cannot create new files. If files in the directory are set to be readable and writable for the group, then + group members will be able to write to (or delete) them. + </para> + + <sect3> + <title>Protecting Directories and Files from Deletion</title> + + <para> +<indexterm><primary>protect files</primary></indexterm> +<indexterm><primary>protect directories</primary></indexterm> +<indexterm><primary>access controls</primary></indexterm> +<indexterm><primary>capability to delete</primary></indexterm> + People have asked on the Samba mailing list how is it possible to protect files or directories from deletion by users. + For example, Windows NT/2K/XP provides the capacity to set access controls on a directory into which people can + write files but not delete them. It is possible to set an ACL on a Windows file that permits the file to be written to + but not deleted. Such concepts are foreign to the UNIX operating system file space. Within the UNIX file system + anyone who has the ability to create a file can write to it. Anyone who has write permission on the + directory that contains a file and has write permission for it has the capability to delete it. + </para> + + <para> +<indexterm><primary>directory permissions</primary></indexterm> +<indexterm><primary>delete a file</primary></indexterm> +<indexterm><primary>write access</primary></indexterm> + For the record, in the UNIX environment the ability to delete a file is controlled by the permissions on + the directory that the file is in. In other words, a user can delete a file in a directory to which that + user has write access, even if that user does not own the file. + </para> + + <para> +<indexterm><primary>file system capabilities</primary></indexterm> +<indexterm><primary>inheritance</primary></indexterm> +<indexterm><primary>POSIX ACLs</primary></indexterm> +<indexterm><primary>extended attributes</primary></indexterm> + Of necessity, Samba is subject to the file system semantics of the host operating system. Samba is therefore + limited in the file system capabilities that can be made available through Windows ACLs, and therefore performs + a "best fit" translation to POSIX ACLs. Some UNIX file systems do, however support, a feature known + as extended attributes. Only the Windows concept of <emphasis>inheritance</emphasis> is implemented by Samba through + the appropriate extended attribute. + </para> + + <para> +<indexterm><primary>extended attributes</primary></indexterm> +<indexterm><primary>immutible</primary></indexterm> +<indexterm><primary>chattr</primary></indexterm> +<indexterm><primary>CAP_LINUX_IMMUTABLE</primary></indexterm> + The specific semantics of the extended attributes are not consistent across UNIX and UNIX-like systems such as Linux. + For example, it is possible on some implementations of the extended attributes to set a flag that prevents the directory + or file from being deleted. The extended attribute that may achieve this is called the <constant>immutible</constant> bit. + Unfortunately, the implementation of the immutible flag is NOT consistent with published documentation. For example, the + man page for the <command>chattr</command> on SUSE Linux 9.2 says: +<screen> +A file with the i attribute cannot be modified: it cannot be deleted +or renamed, no link can be created to this file and no data can be +written to the file. Only the superuser or a process possessing the +CAP_LINUX_IMMUTABLE capability can set or clear this attribute. +</screen> + A simple test can be done to check if the immutible flag is supported on files in the file system of the Samba host + server. + </para> + + <procedure> + <title>Test for File Immutibility Support</title> + + <step><para> + Create a file called <filename>filename</filename>. + </para></step> + + <step><para> + Login as the <constant>root</constant> user, then set the immutibile flag on a test file as follows: +<screen> +&rootprompt; chattr +i `filename' +</screen> + </para></step> + + <step><para> + Login as the user who owns the file (not root) and attempt to remove the file as follows: +<screen> +mystic:/home/hannibal > rm filename +</screen> + It will not be possible to delete the file if the immutible flag is correctly honored. + </para></step> + </procedure> + + <para> + On operating systems and file system types that support the immutible bit, it is possible to create directories + that cannot be deleted. Check the man page on your particular host system to determine whether or not + immutable directories are writable. If they are not, then the entire directory and its contents will effectively + be protected from writing (file creation also) and deletion. + </para> + + </sect3> + + </sect2> + +</sect1> + +<sect1> +<title>Share Definition Access Controls</title> + + + <para> + <indexterm><primary>permissions</primary><secondary>share</secondary></indexterm> + The following parameters in the &smb.conf; file sections define a share control or affect access controls. + Before using any of the following options, please refer to the man page for &smb.conf;. + </para> + + <sect2> + <title>User- and Group-Based Controls</title> + + <para> + User- and group-based controls can prove quite useful. In some situations it is distinctly desirable to + force all file system operations as if a single user were doing so. The use of the + <smbconfoption name="force user"/> and <smbconfoption name="force group"/> behavior will achieve this. + In other situations it may be necessary to use a paranoia level of control to ensure that only particular + authorized persons will be able to access a share or its contents. Here the use of the + <smbconfoption name="valid users"/> or the <smbconfoption name="invalid users"/> parameter may be useful. + </para> + + <para> + As always, it is highly advisable to use the easiest to maintain and the least ambiguous method for + controlling access. Remember, when you leave the scene, someone else will need to provide assistance, and + if he or she finds too great a mess or does not understand what you have done, there is risk of + Samba being removed and an alternative solution being adopted. + </para> + + <para> + <link linkend="ugbc">User and Group Based Controls</link> enumerates these controls. + </para> + + <table frame='all' pgwide='0' id="ugbc"><title>User- and Group-Based Controls</title> + <tgroup cols='2'> + <colspec align="left"/> + <colspec align="justify" colwidth="1*"/> + <thead> + <row> + <entry align="center">Control Parameter</entry> + <entry align="center">Description, Action, Notes</entry> + </row> + </thead> + <tbody> + <row> + <entry><smbconfoption name="admin users"/></entry> + <entry><para> + List of users who will be granted administrative privileges on the share. + They will do all file operations as the superuser (root). + Users in this list will be able to do anything they like on the share, + irrespective of file permissions. + </para></entry> + </row> + <row> + <entry><smbconfoption name="force group"/></entry> + <entry><para> + Specifies a UNIX group name that will be assigned as the default primary group + for all users connecting to this service. + </para></entry> + </row> + <row> + <entry><smbconfoption name="force user"/></entry> + <entry><para> + Specifies a UNIX username that will be assigned as the default user for all users connecting to this service. + This is useful for sharing files. Incorrect use can cause security problems. + </para></entry> + </row> + <row> + <entry><smbconfoption name="guest ok"/></entry> + <entry><para> + If this parameter is set for a service, then no password is required to connect to the service. Privileges will be + those of the guest account. + </para></entry> + </row> + <row> + <entry><smbconfoption name="invalid users"/></entry> + <entry><para> + List of users that should not be allowed to login to this service. + </para></entry> + </row> + <row> + <entry><smbconfoption name="only user"/></entry> + <entry><para> + Controls whether connections with usernames not in the user list will be allowed. + </para></entry> + </row> + <row> + <entry><smbconfoption name="read list"/></entry> + <entry><para> + List of users that are given read-only access to a service. Users in this list + will not be given write access, no matter what the read-only option is set to. + </para></entry> + </row> + <row> + <entry><smbconfoption name="username"/></entry> + <entry><para> + Refer to the &smb.conf; man page for more information; this is a complex and potentially misused parameter. + </para></entry> + </row> + <row> + <entry><smbconfoption name="valid users"/></entry> + <entry><para> + List of users that should be allowed to login to this service. + </para></entry> + </row> + <row> + <entry><smbconfoption name="write list"/></entry> + <entry><para> + List of users that are given read-write access to a service. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + </sect2> + + <sect2> + <title>File and Directory Permissions-Based Controls</title> + + <para> + Directory permission-based controls, if misused, can result in considerable difficulty in diagnosing the causes of + misconfiguration. Use them sparingly and carefully. By gradually introducing each, one at a time, undesirable side + effects may be detected. In the event of a problem, always comment all of them out and then gradually reintroduce + them in a controlled way. + </para> + + <para> + Refer to <link linkend="fdpbc">File and Directory Permission Based Controls</link> for information + regarding the parameters that may be used to set file and directory permission-based access controls. + </para> + + <table frame='all' id="fdpbc"><title>File and Directory Permission-Based Controls</title> + <tgroup cols='2'> + <colspec align="left"/> + <colspec align="justify" colwidth="1*"/> + <thead> + <row> + <entry align="center">Control Parameter</entry> + <entry align="center">Description, Action, Notes</entry> + </row> + </thead> + <tbody> + <row> + <entry><smbconfoption name="create mask"/></entry> + <entry><para> + Refer to the &smb.conf; man page. + </para></entry> + </row> + <row> + <entry><smbconfoption name="directory mask"/></entry> + <entry><para> + The octal modes used when converting DOS modes to UNIX modes when creating UNIX directories. + See also directory security mask. + </para></entry></row> + <row> + <entry><smbconfoption name="dos filemode"/></entry> + <entry><para> + Enabling this parameter allows a user who has write access to the file to modify the permissions on it. + </para></entry> + </row> + <row> + <entry><smbconfoption name="force create mode"/></entry> + <entry><para> + This parameter specifies a set of UNIX-mode bit permissions that will always be set on a file created by Samba. + </para></entry> + </row> + <row> + <entry><smbconfoption name="force directory mode"/></entry> + <entry><para> + This parameter specifies a set of UNIX-mode bit permissions that will always be set on a directory created by Samba. + </para></entry> + </row> + <row> + <entry><smbconfoption name="force directory security mode"/></entry> + <entry><para> + Controls UNIX permission bits modified when a Windows NT client is manipulating UNIX permissions on a directory. + </para></entry> + </row> + <row> + <entry><smbconfoption name="force security mode"/></entry> + <entry><para> + Controls UNIX permission bits modified when a Windows NT client manipulates UNIX permissions. + </para></entry> + </row> + <row> + <entry><smbconfoption name="hide unreadable"/></entry> + <entry><para> + Prevents clients from seeing the existence of files that cannot be read. + </para></entry> + </row> + <row> + <entry><smbconfoption name="hide unwriteable files"/></entry> + <entry><para> + Prevents clients from seeing the existence of files that cannot be written to. Unwritable directories are shown as usual. + </para></entry> + </row> + <row> + <entry><smbconfoption name="nt acl support"/></entry> + <entry><para> + This parameter controls whether smbd will attempt to map UNIX permissions into Windows NT ACLs. + </para></entry> + </row> + <row> + <entry><smbconfoption name="security mask"/></entry> + <entry><para> + Controls UNIX permission bits modified when a Windows NT client is manipulating the UNIX permissions on a file. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + </sect2> + + <sect2> + <title>Miscellaneous Controls</title> + + <para> + The parameter documented in <link linkend="mcoc">Other Controls</link> are often used by administrators + in ways that create inadvertent barriers to file access. Such are the consequences of not understanding the + full implications of &smb.conf; file settings. + </para> + + <table frame='all' id="mcoc"><title>Other Controls</title> + <tgroup cols='2'> + <colspec align="justify" colwidth="1*"/> + <colspec align="justify" colwidth="1*"/> + <thead> + <row> + <entry align="center">Control Parameter</entry> + <entry align="center">Description, Action, Notes</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <smbconfoption name="case sensitive"/>, + <smbconfoption name="default case"/>, + <smbconfoption name="short preserve case"/> + </entry> + <entry><para> + This means that all file name lookup will be done in a case-sensitive manner. + Files will be created with the precise file name Samba received from the MS Windows client. + </para></entry> + </row> + <row> + <entry><smbconfoption name="csc policy"/></entry> + <entry><para> + Client-side caching policy parallels MS Windows client-side file caching capabilities. + </para></entry> + </row> + <row> + <entry><smbconfoption name="dont descend"/></entry> + <entry><para> + Allows specifying a comma-delimited list of directories that the server should always show as empty. + </para></entry> + </row> + <row> + <entry><smbconfoption name="dos filetime resolution"/></entry> + <entry><para> + This option is mainly used as a compatibility option for Visual C++ when used against Samba shares. + </para></entry> + </row> + <row> + <entry><smbconfoption name="dos filetimes"/></entry> + <entry><para> + DOS and Windows allow users to change file timestamps if they can write to the file. POSIX semantics prevent this. + This option allows DOS and Windows behavior. + </para></entry> + </row> + <row> + <entry><smbconfoption name="fake oplocks"/></entry> + <entry><para> + Oplocks are the way that SMB clients get permission from a server to locally cache file operations. If a server grants an + oplock, the client is free to assume that it is the only one accessing the file, and it will aggressively cache file data. + </para></entry> + </row> + <row> + <entry> + <smbconfoption name="hide dot files"/>, + <smbconfoption name="hide files"/>, + <smbconfoption name="veto files"/> + </entry> + <entry><para> + Note: MS Windows Explorer allows override of files marked as hidden so they will still be visible. + </para></entry> + </row> + <row> + <entry><smbconfoption name="read only"/></entry> + <entry><para> + If this parameter is yes, then users of a service may not create or modify files in the service's directory. + </para></entry> + </row> + <row> + <entry><smbconfoption name="veto files"/></entry> + <entry><para> + List of files and directories that are neither visible nor accessible. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + </sect2> + +</sect1> + +<sect1> +<title>Access Controls on Shares</title> + + + <para> +<indexterm><primary>per-share access control</primary></indexterm> +<indexterm><primary>Everyone - Full Control</primary></indexterm> +<indexterm><primary>specific restrictions</primary></indexterm> +<indexterm><primary>share access</primary></indexterm> + <indexterm><primary>permissions</primary><secondary>share ACLs</secondary></indexterm> + This section deals with how to configure Samba per-share access control restrictions. + By default, Samba sets no restrictions on the share itself. Restrictions on the share itself + can be set on MS Windows NT4/200x/XP shares. This can be an effective way to limit who can + connect to a share. In the absence of specific restrictions, the default setting is to allow + the global user <constant>Everyone - Full Control</constant> (full control, change and read). + </para> + + <para> +<indexterm><primary>access control</primary></indexterm> +<indexterm><primary>MMC</primary></indexterm> +<indexterm><primary>Computer Management</primary></indexterm> + At this time Samba does not provide a tool for configuring access control settings on the share + itself the only way to create those settings is to use either the NT4 Server Manager or the Windows 200x + Microsoft Management Console (MMC) for Computer Management. There are currently no plans to provide + this capability in the Samba command-line tool set. + </para> + + <para> +<indexterm><primary>share_info.tdb</primary></indexterm> +<indexterm><primary>/usr/local/samba/var</primary></indexterm> +<indexterm><primary>tdbdump</primary></indexterm> +<indexterm><primary>tdb files</primary></indexterm> + Samba stores the per-share access control settings in a file called <filename>share_info.tdb</filename>. + The location of this file on your system will depend on how Samba was compiled. The default location + for Samba's tdb files is under <filename>/usr/local/samba/var</filename>. If the <filename>tdbdump</filename> + utility has been compiled and installed on your system, then you can examine the contents of this file + by executing <command>tdbdump share_info.tdb</command> in the directory containing the tdb files. + </para> + + <sect2> + <title>Share Permissions Management</title> + + <para> + The best tool for share permissions management is platform-dependent. Choose the best tool for your environment. + </para> + + <sect3> + <title>Windows NT4 Workstation/Server</title> + <para> +<indexterm><primary>manage share permissions</primary></indexterm> +<indexterm><primary>share permissions</primary></indexterm> +<indexterm><primary>NT Server Manager</primary></indexterm> +<indexterm><primary>Windows NT4</primary></indexterm> + The tool you need to manage share permissions on a Samba server from a Windows NT4 Workstation or Server + is the NT Server Manager. Server Manager is shipped with Windows NT4 Server products but not with Windows + NT4 Workstation. You can obtain the NT Server Manager for MS Windows NT4 Workstation from the Microsoft + web site <ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;173673">support</ulink> section. + </para> + + <procedure> + <title>Instructions</title> + + <step><para> + Launch the <application>NT4 Server Manager</application> and click on the Samba server you want to + administer. From the menu select <guimenu>Computer</guimenu>, then click on + <guimenuitem>Shared Directories</guimenuitem>. + </para></step> + + <step><para> + Click on the share that you wish to manage and click the <guilabel>Properties</guilabel> tab, then click + the <guilabel>Permissions</guilabel> tab. Now you can add or change access control settings as you wish. + </para></step> + </procedure> + + </sect3> + + <sect3> + <title>Windows 200x/XP</title> + + <para> +<indexterm><primary>Windows NT4/200x/XP</primary></indexterm> +<indexterm><primary>ACLs on share</primary></indexterm> +<indexterm><primary>Sharing</primary></indexterm> +<indexterm><primary>Permissions</primary></indexterm> + On <application>MS Windows NT4/200x/XP</application> system, ACLs on the share itself are set using native + tools, usually from File Manager. For example, in Windows 200x, right-click on the shared folder, + then select <guimenuitem>Sharing</guimenuitem>, then click on <guilabel>Permissions</guilabel>. The default + Windows NT4/200x permission allows "Everyone" full control on the share. + </para> + + <para> +<indexterm><primary>Computer Management</primary></indexterm> +<indexterm><primary>MMC</primary></indexterm> +<indexterm><primary>tool</primary></indexterm> + MS Windows 200x and later versions come with a tool called the <application>Computer Management</application> + snap-in for the MMC. This tool is located by clicking on <guimenu>Control Panel -> + Administrative Tools -> Computer Management</guimenu>. + </para> + + <procedure> + <title>Instructions</title> + <step><para> + After launching the MMC with the Computer Management snap-in, click the menu item <guimenuitem>Action</guimenuitem> + and select <guilabel>Connect to another computer</guilabel>. If you are not logged onto a domain you will be prompted + to enter a domain login user identifier and a password. This will authenticate you to the domain. + If you are already logged in with administrative privilege, this step is not offered. + </para></step> + + <step><para> + If the Samba server is not shown in the <guilabel>Select Computer</guilabel> box, type in the name of the target + Samba server in the field <guilabel>Name:</guilabel>. Now click the on <guibutton>[+]</guibutton> next to + <guilabel>System Tools</guilabel>, then on the <guibutton>[+]</guibutton> next to + <guilabel>Shared Folders</guilabel> in the left panel. + </para></step> + + <step><para> +<indexterm><primary>Share Permissions</primary></indexterm> + In the right panel, double-click on the share on which you wish to set access control permissions. + Then click the tab <guilabel>Share Permissions</guilabel>. It is now possible to add access control entities + to the shared folder. Remember to set what type of access (full control, change, read) you + wish to assign for each entry. + </para></step> + </procedure> + + <warning> + <para> + Be careful. If you take away all permissions from the <constant>Everyone</constant> user without removing + this user, effectively no user will be able to access the share. This is a result of what is known as + ACL precedence. Everyone with <emphasis>no access</emphasis> means that <constant>MaryK</constant> who is + part of the group <constant>Everyone</constant> will have no access even if she is given explicit full + control access. + </para> + </warning> + + </sect3> + </sect2> + +</sect1> + +<sect1> +<title>MS Windows Access Control Lists and UNIX Interoperability</title> + + <sect2> + <title>Managing UNIX Permissions Using NT Security Dialogs</title> + + + <para> + <indexterm><primary>permissions</primary><secondary>file/directory ACLs</secondary></indexterm> + Windows NT clients can use their native security settings dialog box to view and modify the + underlying UNIX permissions. + </para> + + <para> + This ability is careful not to compromise the security of the UNIX host on which Samba is running and + still obeys all the file permission rules that a Samba administrator can set. + </para> + + <para> + Samba does not attempt to go beyond POSIX ACLs, so the various finer-grained access control + options provided in Windows are actually ignored. + </para> + + <note> + <para> + All access to UNIX/Linux system files via Samba is controlled by the operating system file access controls. + When trying to figure out file access problems, it is vitally important to find the identity of the Windows + user as it is presented by Samba at the point of file access. This can best be determined from the + Samba log files. + </para> + </note> + </sect2> + + <sect2> + <title>Viewing File Security on a Samba Share</title> + + <para> + From an NT4/2000/XP client, right-click on any file or directory in a Samba-mounted drive letter + or UNC path. When the menu pops up, click on the <guilabel>Properties</guilabel> entry at the bottom + of the menu. This brings up the file <constant>Properties</constant> dialog box. Click on the + <guilabel>Security</guilabel> tab and you will see three buttons: <guibutton>Permissions</guibutton>, + <guibutton>Auditing</guibutton>, and <guibutton>Ownership</guibutton>. The <guibutton>Auditing</guibutton> + button will cause either an error message <errorname>"A requested privilege is not held by the client"</errorname> + to appear if the user is not the NT administrator, or a dialog intended to allow an administrator + to add auditing requirements to a file if the user is logged on as the NT administrator. This dialog is + nonfunctional with a Samba share at this time, because the only useful button, the <guibutton>Add</guibutton> + button, will not currently allow a list of users to be seen. + </para> + + </sect2> + + <sect2> + <title>Viewing File Ownership</title> + + <para> + Clicking on the <guibutton>Ownership</guibutton> button brings up a dialog box telling you who owns + the given file. The owner name will be displayed like this: + <screen> + <constant>SERVER\user (Long name)</constant> + </screen> + <replaceable>SERVER</replaceable> is the NetBIOS name of the Samba server, <replaceable>user</replaceable> + is the username of the UNIX user who owns the file, and <replaceable>(Long name)</replaceable> is the + descriptive string identifying the user (normally found in the GECOS field of the UNIX password database). + Click on the <guibutton>Close</guibutton> button to remove this dialog. + </para> + + <para> + If the parameter <smbconfoption name="nt acl support"/> is set to <constant>false</constant>, + the file owner will be shown as the NT user <emphasis>Everyone</emphasis>. + </para> + + <para> +<indexterm><primary>Take Ownership</primary></indexterm> + The <guibutton>Take Ownership</guibutton> button will not allow you to change the ownership of this file to + yourself (clicking it will display a dialog box complaining that the user as whom you are currently logged onto + the NT client cannot be found). The reason for this is that changing the ownership of a file is a privileged + operation in UNIX, available only to the <emphasis>root</emphasis> user. Because clicking on this button causes + NT to attempt to change the ownership of a file to the current user logged into the NT client, this will + not work with Samba at this time. + </para> + + <para> +<indexterm><primary>chown</primary></indexterm> +<indexterm><primary>ownership</primary></indexterm> +<indexterm><primary>Seclib</primary></indexterm> + There is an NT <command>chown</command> command that will work with Samba and allow a user with administrator + privilege connected to a Samba server as root to change the ownership of files on both a local NTFS file system + or remote mounted NTFS or Samba drive. This is available as part of the <application>Seclib</application> NT + security library written by Jeremy Allison of the Samba Team and is downloadable from the main Samba FTP site. + </para> + + </sect2> + + <sect2> + <title>Viewing File or Directory Permissions</title> + + <para> + The third button is the <guibutton>Permissions</guibutton> button. Clicking on it brings up a dialog box + that shows both the permissions and the UNIX owner of the file or directory. The owner is displayed like this: + </para> + + <para><command><replaceable>SERVER</replaceable>\ + <replaceable>user</replaceable> + <replaceable>(Long name)</replaceable></command></para> + + <para><replaceable>SERVER</replaceable> is the NetBIOS name of the Samba server, + <replaceable>user</replaceable> is the username of the UNIX user who owns the file, and + <replaceable>(Long name)</replaceable> is the descriptive string identifying the user (normally found in the + GECOS field of the UNIX password database).</para> + + <para> + If the parameter <smbconfoption name="nt acl support"/> is set to <constant>false</constant>, + the file owner will be shown as the NT user <constant>Everyone</constant>, and the permissions will be + shown as NT <emphasis>Full Control</emphasis>. + </para> + + + <para> + The permissions field is displayed differently for files and directories. Both are discussed next. + </para> + + <sect3> + <title>File Permissions</title> + + <para> + The standard UNIX user/group/world triplet and the corresponding <constant>read, write, + execute</constant> permissions triplets are mapped by Samba into a three-element NT ACL with the + <quote>r</quote>, <quote>w</quote>, and <quote>x</quote> bits mapped into the corresponding NT + permissions. The UNIX world permissions are mapped into the global NT group <constant>Everyone</constant>, followed + by the list of permissions allowed for the UNIX world. The UNIX owner and group permissions are displayed as an NT + <guiicon>user</guiicon> icon and an NT <guiicon>local group</guiicon> icon, respectively, followed by the list + of permissions allowed for the UNIX user and group. + </para> + + <para> + Because many UNIX permission sets do not map into common NT names such as <constant>read</constant>, + <constant>change</constant>, or <constant>full control</constant>, usually the permissions will be prefixed + by the words <constant>Special Access</constant> in the NT display list. + </para> + + <para> + But what happens if the file has no permissions allowed for a particular UNIX user group or world component? + In order to allow <emphasis>no permissions</emphasis> to be seen and modified, Samba then overloads the NT + <constant>Take Ownership</constant> ACL attribute (which has no meaning in UNIX) and reports a component with + no permissions as having the NT <command>O</command> bit set. This was chosen, of course, to make it look + like a zero, meaning zero permissions. More details on the decision behind this action are given below. + </para> + + </sect3> + + <sect3> + <title>Directory Permissions</title> + + <para> + Directories on an NT NTFS file system have two different sets of permissions. The first set is the ACL set on the + directory itself, which is usually displayed in the first set of parentheses in the normal <constant>RW</constant> + NT style. This first set of permissions is created by Samba in exactly the same way as normal file permissions are, described + above, and is displayed in the same way. + </para> + + <para> + The second set of directory permissions has no real meaning in the UNIX permissions world and represents the <constant> + inherited</constant> permissions that any file created within this directory would inherit. + </para> + + <para> + Samba synthesizes these inherited permissions for NT by returning as an NT ACL the UNIX permission mode that a new file + created by Samba on this share would receive. + </para> + + </sect3> + + </sect2> + + <sect2> + <title>Modifying File or Directory Permissions</title> + + <para> + Modifying file and directory permissions is as simple as changing the displayed permissions in the dialog box + and clicking on <guibutton>OK</guibutton>. However, there are limitations that a user needs to be aware of, + and also interactions with the standard Samba permission masks and mapping of DOS attributes that also need to + be taken into account. + </para> + + <para> + If the parameter <smbconfoption name="nt acl support"/> is set to <constant>false</constant>, any attempt to + set security permissions will fail with an <errorname>"Access Denied" </errorname> message. + </para> + + <para> + The first thing to note is that the <guibutton>Add</guibutton> button will not return a list of users in Samba + (it will give an error message saying <errorname>"The remote procedure call failed and did not + execute"</errorname>). This means that you can only manipulate the current user/group/world permissions listed + in the dialog box. This actually works quite well because these are the only permissions that UNIX actually + has. + </para> + + <para> + If a permission triplet (either user, group, or world) is removed from the list of permissions in the NT + dialog box, then when the <guibutton>OK</guibutton> button is pressed, it will be applied as <emphasis>no + permissions</emphasis> on the UNIX side. If you view the permissions again, the <emphasis>no + permissions</emphasis> entry will appear as the NT <command>O</command> flag, as described above. This allows + you to add permissions back to a file or directory once you have removed them from a triplet component. + </para> + + <para> + Because UNIX supports only the <quote>r</quote>, <quote>w</quote>, and <quote>x</quote> bits of an NT ACL, if + other NT security attributes such as <constant>Delete Access</constant> are selected, they will be ignored + when applied on the Samba server. + </para> + + <para> + When setting permissions on a directory, the second set of permissions (in the second set of parentheses) is + by default applied to all files within that directory. If this is not what you want, you must uncheck the + <guilabel>Replace permissions on existing files</guilabel> checkbox in the NT dialog before clicking on + <guibutton>OK</guibutton>. + </para> + + <para> + If you wish to remove all permissions from a user/group/world component, you may either highlight the + component and click on the <guibutton>Remove</guibutton> button or set the component to only have the special + <constant>Take Ownership</constant> permission (displayed as <command>O</command>) highlighted. + </para> + + </sect2> + +<?latex \newpage ?> + <sect2> + <title>Interaction with the Standard Samba <quote>create mask</quote> Parameters</title> + + <para>There are four parameters that control interaction with the standard Samba <parameter>create mask</parameter> parameters: + + + <itemizedlist> + <listitem><para><smbconfoption name="security mask"/></para></listitem> + <listitem><para><smbconfoption name="force security mode"/></para></listitem> + <listitem><para><smbconfoption name="directory security mask"/></para></listitem> + <listitem><para><smbconfoption name="force directory security mode"/></para></listitem> + </itemizedlist> + + </para> + + <para> + When a user clicks on <guibutton>OK</guibutton> to apply the + permissions, Samba maps the given permissions into a user/group/world + r/w/x triplet set, and then checks the changed permissions for a + file against the bits set in the + <smbconfoption name="security mask"/> parameter. Any bits that + were changed that are not set to <emphasis>1</emphasis> in this parameter are left alone + in the file permissions.</para> + + <para> + Essentially, zero bits in the <smbconfoption name="security mask"/> + may be treated as a set of bits the user is <emphasis>not</emphasis> + allowed to change, and one bits are those the user is allowed to change. + </para> + + <para> + If not explicitly set, this parameter defaults to the same value as + the <smbconfoption name="create mask"/> parameter. To allow a user to modify all the + user/group/world permissions on a file, set this parameter to 0777. + </para> + + <para> + Next Samba checks the changed permissions for a file against the bits set in the + <smbconfoption name="force security mode"/> parameter. Any bits + that were changed that correspond to bits set to <emphasis>1</emphasis> in this parameter + are forced to be set.</para> + + <para> + Essentially, bits set in the <parameter>force security mode</parameter> parameter + may be treated as a set of bits that, when modifying security on a file, the user + has always set to be <emphasis>on</emphasis>.</para> + + <para> + If not explicitly set, this parameter defaults to the same value + as the <smbconfoption name="force create mode"/> parameter. + To allow a user to modify all the user/group/world permissions on a file + with no restrictions, set this parameter to 000. The + <smbconfoption name="security mask"/> and <parameter>force + security mode</parameter> parameters are applied to the change + request in that order.</para> + + <para> + For a directory, Samba performs the same operations as + described above for a file except it uses the parameter <parameter> + directory security mask</parameter> instead of <parameter>security + mask</parameter>, and <parameter>force directory security mode + </parameter> parameter instead of <parameter>force security mode + </parameter>.</para> + + <para> + The <smbconfoption name="directory security mask"/> parameter + by default is set to the same value as the <parameter>directory mask + </parameter> parameter and the <parameter>force directory security + mode</parameter> parameter by default is set to the same value as + the <smbconfoption name="force directory mode"/> parameter. + In this way Samba enforces the permission restrictions that + an administrator can set on a Samba share, while still allowing users + to modify the permission bits within that restriction.</para> + + <para> + If you want to set up a share that allows users full control + in modifying the permission bits on their files and directories and + does not force any particular bits to be set <emphasis>on</emphasis>, + then set the following parameters in the &smb.conf; file in that + share-specific section: + </para> + +<?latex \newpage ?> + <smbconfblock> + <smbconfoption name="security mask">0777</smbconfoption> + <smbconfoption name="force security mode">0</smbconfoption> + <smbconfoption name="directory security mask">0777</smbconfoption> + <smbconfoption name="force directory security mode">0</smbconfoption> + </smbconfblock> + +</sect2> + +<sect2> + <title>Interaction with the Standard Samba File Attribute Mapping</title> + + <note> + <para> + Samba maps some of the DOS attribute bits (such as <quote>read-only</quote>) + into the UNIX permissions of a file. This means there can + be a conflict between the permission bits set via the security + dialog and the permission bits set by the file attribute mapping. + </para> + </note> + + <para> + If a file has no UNIX read access for the owner, it will show up + as <quote>read-only</quote> in the standard file attributes tabbed dialog. + Unfortunately, this dialog is the same one that contains the security information + in another tab. + </para> + + <para> + What this can mean is that if the owner changes the permissions + to allow himself or herself read access using the security dialog, clicks on + <guibutton>OK</guibutton> to get back to the standard attributes tab + dialog, and clicks on <guibutton>OK</guibutton> on that dialog, then + NT will set the file permissions back to read-only (as that is what + the attributes still say in the dialog). This means that after setting + permissions and clicking on <guibutton>OK</guibutton> to get back to the + attributes dialog, you should always press <guibutton>Cancel</guibutton> + rather than <guibutton>OK</guibutton> to ensure that your changes + are not overridden. + </para> + + </sect2> + + <sect2> + <title>Windows NT/200X ACLs and POSIX ACLs Limitations</title> + + <para> + Windows administrators are familiar with simple ACL controls, and they typically + consider that UNIX user/group/other (ugo) permissions are inadequate and not + sufficiently fine-grained. + </para> + + <para> + Competing SMB implementations differ in how they handle Windows ACLs. Samba handles + Windows ACLs from the perspective of UNIX file system administration and thus adopts + the limitations of POSIX ACLs. Therefore, where POSIX ACLs lack a capability of the + Windows NT/200X ACLs, the POSIX semantics and limitations are imposed on the Windows + administrator. + </para> + + <para> + POSIX ACLs present an interesting challenge to the UNIX administrator and therefore + force a compromise to be applied to Windows ACLs administration. POSIX ACLs are not + covered by an official standard; rather, the latest standard is a draft standard + 1003.1e revision 17. This is the POSIX document on which the Samba implementation has + been implemented. + </para> + + <para> + UNIX vendors differ in the manner in which POSIX ACLs are implemented. There are a + number of Linux file systems that support ACLs. Samba has to provide a way to make + transparent all the differences between the various implementations of POSIX ACLs. + The pressure for ACLs support in Samba has noticeably increased the pressure to + standardize ACLs support in the UNIX world. + </para> + + <para> + Samba has to deal with the complicated matter of handling the challenge of the Windows + ACL that implements <emphasis>inheritance</emphasis>, a concept not anticipated by POSIX + ACLs as implemented in UNIX file systems. Samba provides support for <emphasis>masks</emphasis> + that permit normal ugo and ACLs functionality to be overrided. This further complicates + the way in which Windows ACLs must be implemented. + </para> + + <sect3> + <title>UNIX POSIX ACL Overview</title> + + <para> + In examining POSIX ACLs we must consider the manner in which they operate for + both files and directories. File ACLs have the following significance: +<screen> +# 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) +</screen> + Directory ACLs have the following signficance: +<screen> +# 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) +</screen> + </para> + + </sect3> + + <sect3> + <title>Mapping of Windows File ACLs to UNIX POSIX ACLs</title> + + <para> + Microsoft Windows NT4/200X ACLs must of necessity be mapped to POSIX ACLs. + The mappings for file permissions are shown in <link linkend="fdsacls">How + Windows File ACLs Map to UNIX POSIX File ACLs</link>. + The # character means this flag is set only when the Windows administrator + sets the <constant>Full Control</constant> flag on the file. + </para> + + <table frame='all' pgwide='0' id="fdsacls"><title>How Windows File ACLs Map to UNIX POSIX File ACLs</title> + <tgroup cols='2'> + <colspec align="left"/> + <colspec align="center"/> + <thead> + <row> + <entry align="left">Windows ACE</entry> + <entry align="center">File Attribute Flag</entry> + </row> + </thead> + <tbody> + <row> + <entry><para>Full Control</para></entry> + <entry><para>#</para></entry> + </row> + <row> + <entry><para>Traverse Folder/Execute File</para></entry> + <entry><para>x</para></entry> + </row> + <row> + <entry><para>List Folder/Read Data</para></entry> + <entry><para>r</para></entry> + </row> + <row> + <entry><para>Read Attributes</para></entry> + <entry><para>r</para></entry> + </row> + <row> + <entry><para>Read Extended Attribures</para></entry> + <entry><para>r</para></entry> + </row> + <row> + <entry><para>Create Files/Write Data</para></entry> + <entry><para>w</para></entry> + </row> + <row> + <entry><para>Create Folders/Append Data</para></entry> + <entry><para>w</para></entry> + </row> + <row> + <entry><para>Write Attributes</para></entry> + <entry><para>w</para></entry> + </row> + <row> + <entry><para>Write Extended Attributes</para></entry> + <entry><para>w</para></entry> + </row> + <row> + <entry><para>Delete Subfolders and Files</para></entry> + <entry><para>w</para></entry> + </row> + <row> + <entry><para>Delete</para></entry> + <entry><para>#</para></entry> + </row> + <row> + <entry><para>Read Permissions</para></entry> + <entry><para>all</para></entry> + </row> + <row> + <entry><para>Change Permissions</para></entry> + <entry><para>#</para></entry> + </row> + <row> + <entry><para>Take Ownership</para></entry> + <entry><para>#</para></entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + As can be seen from the mapping table, there is no one-to-one mapping capability, and therefore + Samba must make a logical mapping that will permit Windows to operate more-or-less the way + that is intended by the administrator. + </para> + + <para> + In general the mapping of UNIX POSIX user/group/other permissions will be mapped to + Windows ACLs. This has precedence over the creation of POSIX ACLs. POSIX ACLs are necessary + to establish access controls for users and groups other than the user and group that + own the file or directory. + </para> + + <para> + The UNIX administrator can set any directory permission from within the UNIX environment. + The Windows administrator is more restricted in that it is not possible from within + Windows Explorer to remove read permission for the file owner. + </para> + + </sect3> + + <sect3> + <title>Mapping of Windows Directory ACLs to UNIX POSIX ACLs</title> + + <para> + Interesting things happen in the mapping of UNIX POSIX directory permissions and + UNIX POSIX ACLs to Windows ACEs (Access Control Entries, the discrete components of + an ACL) are mapped to Windows directory ACLs. + </para> + + <para> + Directory permissions function in much the same way as shown for file permissions, but + there are some notable exceptions and a few peculiarities that the astute administrator + will want to take into account in the setting up of directory permissions. + </para> + + </sect3> + + </sect2> +</sect1> + +<sect1> +<title>Common Errors</title> + +<para> +File, directory, and share access problems are common topics on the mailing list. The following +are examples recently taken from the mailing list. +</para> + + + <sect2> + <title>Users Cannot Write to a Public Share</title> + + <para> + The following complaint has frequently been voiced on the Samba mailing list: + <quote> + We are facing some troubles with file/directory permissions. I can log on the domain as admin user (root), + and there's a public share on which everyone needs to have permission to create/modify files, but only + root can change the file, no one else can. We need to constantly go to the server to + <userinput>chgrp -R users *</userinput> and <userinput>chown -R nobody *</userinput> to allow + other users to change the file. + </quote> + </para> + + <para> + Here is one way the problem can be solved: + </para> + + <procedure> + <step> + <para> + Go to the top of the directory that is shared. + </para> + </step> + + <step> + <para> + Set the ownership to whatever public user and group you want +<screen> +&prompt;find `directory_name' -type d -exec chown user:group {}\; +&prompt;find `directory_name' -type d -exec chmod 2775 {}\; +&prompt;find `directory_name' -type f -exec chmod 0775 {}\; +&prompt;find `directory_name' -type f -exec chown user:group {}\; +</screen> + </para> + + <note><para> + The above will set the <constant>SGID bit</constant> on all directories. Read your + UNIX/Linux man page on what that does. This ensures that all files and directories + that are created in the directory tree will be owned by the current user and will + be owned by the group that owns the directory in which it is created. + </para></note> + </step> + <step> + <para> + Directory is <replaceable>/foodbar</replaceable>: +<screen> +&prompt;<userinput>chown jack:engr /foodbar</userinput> +</screen> + </para> + + <note> + <para>This is the same as doing:</para> +<screen> +&prompt;<userinput>chown jack /foodbar</userinput> +&prompt;<userinput>chgrp engr /foodbar</userinput> +</screen> + </note> + </step> + <step> + <para>Now type: + +<screen> +&prompt;<userinput>chmod 2775 /foodbar</userinput> +&prompt;<userinput>ls -al /foodbar/..</userinput> +</screen> + </para> + + <para>You should see: +<screen> +drwxrwsr-x 2 jack engr 48 2003-02-04 09:55 foodbar +</screen> + </para> + </step> + <step> + + <para>Now type: +<screen> +&prompt;<userinput>su - jill</userinput> +&prompt;<userinput>cd /foodbar</userinput> +&prompt;<userinput>touch Afile</userinput> +&prompt;<userinput>ls -al</userinput> +</screen> + </para> + + <para> + You should see that the file <filename>Afile</filename> created by Jill will have ownership + and permissions of Jack, as follows: +<screen> +-rw-r--r-- 1 jill engr 0 2007-01-18 19:41 Afile +</screen> + </para> + </step> + + <step> + <para> + If the user that must have write permission in the directory is not a member of the group + <emphasis>engr</emphasis> set in the &smb.conf; entry for the share: + <smbconfblock> +<smbconfoption name="force group">engr</smbconfoption> + </smbconfblock> + </para> + </step> + </procedure> + </sect2> + + + <sect2> + <title>File Operations Done as <emphasis>root</emphasis> with <emphasis>force user</emphasis> Set</title> + + <para> + When you have a user in <smbconfoption name="admin users"/>, Samba will always do file operations for + this user as <emphasis>root</emphasis>, even if <smbconfoption name="force user"/> has been set. + </para> + </sect2> + + <sect2> + <title>MS Word with Samba Changes Owner of File</title> + + <para> + <emphasis>Question:</emphasis> <quote>When user B saves a word document that is owned by user A, + the updated file is now owned by user B. Why is Samba doing this? How do I fix this?</quote> + </para> + + <para> + <emphasis>Answer:</emphasis> Word does the following when you modify/change a Word document: MS Word creates a new document with + a temporary name. Word then closes the old document and deletes it, then renames the new document to the original document name. + There is no mechanism by which Samba can in any way know that the new document really should be owned by the owners + of the original file. Samba has no way of knowing that the file will be renamed by MS Word. As far as Samba is able + to tell, the file that gets created is a new file, not one that the application (Word) is updating. + </para> + + <para> + There is a workaround to solve the permissions problem. It involves understanding how you can manage file + system behavior from within the &smb.conf; file, as well as understanding how UNIX file systems work. Set on the directory + in which you are changing Word documents: <command>chmod g+s `directory_name'.</command> This ensures that all files will + be created with the group that owns the directory. In &smb.conf; share declaration section set: + </para> + + <para> + <smbconfblock> + <smbconfoption name="force create mode">0660</smbconfoption> + <smbconfoption name="force directory mode">0770</smbconfoption> + </smbconfblock> + </para> + + <para> + These two settings will ensure that all directories and files that get created in the share will be readable/writable by the + owner and group set on the directory itself. + </para> + + </sect2> + +</sect1> + +</chapter> |