<html> <body bgcolor="#ffffff"> <img src="samba2_xs.gif" border="0" alt=" " height="100" width="76" hspace="10" align="left" /> <h1 class="head0">Chapter 8. Advanced Disk Shares</h1> <p>This chapter continues our discussion of configuring Samba from <a href="ch06.html">Chapter 6</a>. We will cover some more advanced issues regarding the integration of Unix and Windows filesystems, including hidden files, Unix links, file permissions, name mangling, case sensitivity of filenames, file locking, opportunistic locking (oplocks), connection scripts, supporting Microsoft Dfs (Distributed filesystem) shares, and using NIS home directories.</p> <div class="sect1"><a name="samba2-CHP-8-SECT-1"/> <h2 class="head1">Filesystem Differences</h2> <p>One of the biggest issues for which Samba has to correct is the difference between Unix and Microsoft filesystems. This includes items such as handling symbolic links, hidden files, and dot files. In addition, file permissions can also be a headache if not properly accounted for.</p> <div class="sect2"><a name="samba2-CHP-8-SECT-1.1"/> <h3 class="head2">Hiding and Vetoing Files</h3> <p><a name="INDEX-1"/><a name="INDEX-2"/>Sometimes you need to ensure that a user cannot see or access a file at all. Other times, you don't want to keep users from accessing a file—you just want to hide it when they view the contents of the directory. On Windows systems, an attribute of files allows them to be hidden from a folder listing. With Unix, the traditional way of hiding files in a directory is to use a <a name="INDEX-3"/><a name="INDEX-4"/>dot (.) as the first character in the filename. This prevents items such as configuration files from being seen when performing an ordinary <em class="emphasis">ls</em> command. Keeping a user from accessing a file at all, however, involves working with permissions on files and directories.</p> <p>The first option we should discuss is the Boolean <tt class="literal">hide</tt><a name="INDEX-5"/><a name="INDEX-6"/> <tt class="literal">dot</tt> <tt class="literal">files</tt>. When it is set to <tt class="literal">yes</tt>, Samba reports files beginning with a period (.) as having their hidden attribute set. If the user has chosen to show all hidden files while browsing (e.g., using the Folder Options menu item under the View menu in Windows 98), he will still be able to see the files, although his icons will appear "ghosted," or slightly grayed-out. If the client is configured not to show hidden files, the files will not appear at all.</p> <p>Instead of simply hiding files beginning with a dot, you can also specify a string pattern to Samba for files to hide, using the <tt class="literal">hide</tt><a name="INDEX-7"/> <tt class="literal">files</tt> option. For example, let's assume you specified the following in our example <tt class="literal">[data]</tt> share:</p> <blockquote><pre class="code">[data] hide files = /*.java/*README*/</pre></blockquote> <p>Each entry for this option must begin, end, or be separated from another with a slash ( / ) character, even if only one pattern is listed. This convention allows spaces to appear in filenames. The slashes have nothing to do with Unix directories; they are instead acting as delimiters for the <tt class="literal">hide</tt> <tt class="literal">files</tt> values.</p> <p>If you want to prevent users from seeing files completely, you can instead use the <tt class="literal">veto</tt><a name="INDEX-8"/> <tt class="literal">files</tt> option. This option, which takes the same syntax as the <tt class="literal">hide</tt> <tt class="literal">files</tt> option, specifies a list of files that should never be seen by the user. For example, let's change the <tt class="literal">[data]</tt> share to the following:</p> <blockquote><pre class="code">[data] veto files = /*.java/*README*/</pre></blockquote> <p>The syntax of this option is identical to the <tt class="literal">hide</tt> <tt class="literal">files</tt> configuration option: each entry must begin, end, or be separated from another with a slash (<tt class="literal">/</tt>) character, even if only one pattern is listed. If you do so, files that match the pattern, such as <em class="filename">hello.java</em> and <em class="filename">README.txt,</em> will simply disappear from the directory, and the user cannot access them through SMB.</p> <p><a name="INDEX-9"/>We need to address one other question. What happens if the user tries to delete a directory that contains vetoed files? This is where the <tt class="literal">delete</tt><a name="INDEX-10"/> <tt class="literal">veto</tt> <tt class="literal">files</tt> option comes in. If this Boolean option is set to <tt class="literal">yes</tt>, the user can delete both the regular files and the vetoed files in the directory, and the directory itself is removed. If the option is set to <tt class="literal">no</tt>, the user cannot delete the vetoed files, and consequently the directory is not deleted either. From the user's perspective, the directory appears empty, but cannot be removed.</p> <p>The <tt class="literal">dont</tt><a name="INDEX-11"/> <tt class="literal">descend</tt> directive specifies a list of directories whose contents Samba should not make visible. Note that we say <em class="emphasis">contents</em>, not the directory itself. Users can enter a directory marked as such, but they are prohibited from descending the directory tree any farther—they always see an empty folder. For example, let's use this option with a more basic form of the share that we defined earlier in the chapter:</p> <blockquote><pre class="code">[data] dont descend = config defaults</pre></blockquote> <p>In addition, let's assume that the <em class="filename">/home/samba/data</em> directory has the following contents:</p> <blockquote><pre class="code">drwxr-xr-x 6 tom users 1024 Jun 13 09:24 . drwxr-xr-x 8 root root 1024 Jun 10 17:53 .. -rw-r--r-- 2 tom users 1024 Jun 9 11:43 README drwxr-xr-x 3 tom users 1024 Jun 13 09:28 config drwxr-xr-x 3 tom users 1024 Jun 13 09:28 defaults drwxr-xr-x 3 tom users 1024 Jun 13 09:28 market</pre></blockquote> <p>If the user then connects to the share, she would see the directories in the share. However, the contents of the <em class="filename">/config</em> and <em class="filename">/defaults</em> directories would appear empty to her, even if other folders or files existed in them. In addition, users cannot write any data to the folder (which prevents them from creating a file or folder with the same name as one that is already there but invisible). If a user attempts to do so, she will receive an "Access Denied" message. The <tt class="literal">dont</tt> <tt class="literal">descend</tt> option is an administrative option—not a security option—and is not a substitute for good file permissions. <a name="INDEX-12"/><a name="INDEX-13"/></p> </div> <div class="sect2"><a name="samba2-CHP-8-SECT-1.2"/> <h3 class="head2">Links</h3> <p><a name="INDEX-14"/>When a client tries to open a symbolic link on a Samba server share, Samba attempts to follow the link to find the real file and let the client open it, as if the user were on a Unix machine. If you don't want to allow this, set the <tt class="literal">follow</tt> <tt class="literal">symlinks</tt> option like this:</p> <blockquote><pre class="code">[data] follow symlinks = no</pre></blockquote> <p>You can test this by setting up and trying to access a symbolic link. Create a directory on the Unix server inside the share, acting as the user under which you will log in to Samba. Enter the following commands:</p> <blockquote><pre class="code">$ <tt class="userinput"><b>echo "This is a test" >hello.txt</b></tt> $ <tt class="userinput"><b>ln -s hello.txt hello-link.txt</b></tt></pre></blockquote> <p>This results in the text file <em class="filename">hello.txt</em> and a symbolic link to it called <em class="filename">hello-link.txt</em>. Normally, if you double-click either one, you will receive a file that has the text "This is a test" inside of it. However, with the <tt class="literal">follow</tt> <tt class="literal">symlinks</tt><a name="INDEX-15"/> option set to <tt class="literal">no</tt>, you will receive an error dialog if you double-click <em class="filename">hello-link.txt</em>.</p> <p>The <tt class="literal">wide</tt><a name="INDEX-16"/> <tt class="literal">links</tt> option, if set to <tt class="literal">no</tt>, prevents the client user from following symbolic links that point outside the shared directory tree. For example, let's assume that we modified the <tt class="literal">[data]</tt> share as follows:</p> <blockquote><pre class="code">[data] follow symlinks = yes wide links = no</pre></blockquote> <p>As long as the <tt class="literal">follow</tt><a name="INDEX-17"/> <tt class="literal">symlinks</tt> option is disabled, Samba will refuse to follow any symbolic links outside the current share tree. If we create a file outside the share (for example, in someone's home directory) and then create a link to it in the share as follows:</p> <blockquote><pre class="code">ln -s ~tom/datafile ./datafile</pre></blockquote> <p>the client cannot open the file in Tom's home directory.</p> </div> <div class="sect2"><a name="samba2-CHP-8-SECT-1.3"/> <h3 class="head2">Filesystem Options</h3> <p><a href="ch08.html#samba2-CHP-8-TABLE-1">Table 8-1</a> <a name="INDEX-18"/><a name="INDEX-19"/>shows a breakdown of the options we discussed earlier. We recommend the defaults for most, except those listed in the following descriptions.</p> <a name="samba2-CHP-8-TABLE-1"/><h4 class="head4">Table 8-1. Filesystem configuration options</h4><table border="1"> <tr> <th> <p>Option</p> </th> <th> <p>Parameters</p> </th> <th> <p>Function</p> </th> <th> <p>Default</p> </th> <th> <p>Scope</p> </th> </tr> <tr> <td> <p><tt class="literal">dont descend</tt></p> </td> <td> <p>string (list of directories)</p> </td> <td> <p>Indicates a list of directories whose contents Samba should make invisible to clients.</p> </td> <td> <p>None</p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">follow</tt> <tt class="literal">symlinks</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>If set to <tt class="literal">no</tt>, will not honor symbolic links.</p> </td> <td> <p><tt class="literal">yes</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">getwd cache</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>If set to <tt class="literal">yes</tt>, will use a cache for <tt class="literal">getwd( )</tt> calls.</p> </td> <td> <p><tt class="literal">yes</tt></p> </td> <td> <p>Global</p> </td> </tr> <tr> <td> <p><tt class="literal">wide links</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>If set to <tt class="literal">yes</tt>, will follow symbolic links outside the share.</p> </td> <td> <p><tt class="literal">yes</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">hide dot files</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>If set to <tt class="literal">yes</tt>, treats Unix hidden files as hidden files in Windows.</p> </td> <td> <p><tt class="literal">yes</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">hide files</tt></p> </td> <td> <p>string (list of files)</p> </td> <td> <p>List of file patterns to treat as hidden.</p> </td> <td> <p>None</p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">veto files</tt></p> </td> <td> <p>string (list of files)</p> </td> <td> <p>List of file patterns to never show.</p> </td> <td> <p>None</p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">delete veto</tt> <tt class="literal">files</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>If set to <tt class="literal">yes</tt>, will delete files matched by <tt class="literal">veto files</tt> when the directory they reside in is deleted.</p> </td> <td> <p><tt class="literal">no</tt></p> </td> <td> <p>Share</p> </td> </tr> </table> <div class="sect3"><a name="samba2-CHP-8-SECT-1.3.1"/> <h3 class="head3">dont descend</h3> <p>The <tt class="literal">dont</tt><a name="INDEX-20"/> <tt class="literal">descend</tt> option can be used to specify various directories that should appear empty to the client. Note that the directory itself will still appear. However, Samba will not show any of the contents of the directory to the client user. This is not a good option to use as a security feature; it is really meant only as a convenience to keep users from casually browsing into directories that might have sensitive files. See our example earlier in this section.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-1.3.2"/> <a name="INDEX-21"/><h3 class="head3">follow symlinks</h3> <p>This option controls whether Samba will follow a symbolic link in the Unix operating system to the target or if it should return an error to the client user. If the option is set to <tt class="literal">yes</tt>, the target of the link will be interpreted as the file. If set to <tt class="literal">no</tt>, an error will be generated if the symbolic link is accessed.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-1.3.3"/> <a name="INDEX-22"/><h3 class="head3">getwd cache</h3> <p>This global option specifies whether Samba should use a local cache for the Unix <em class="emphasis">getwd( )</em> ( get current working directory) system call. You can override the default value of <tt class="literal">yes</tt> as follows:</p> <blockquote><pre class="code">[global] getwd cache = no</pre></blockquote> <p>Setting this option to <tt class="literal">no</tt> can significantly increase the time it takes to resolve the working directory, especially if the <tt class="literal">wide</tt> <tt class="literal">links</tt> option is set to <tt class="literal">no</tt>. You should normally not need to alter this option.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-1.3.4"/> <a name="INDEX-23"/><h3 class="head3">wide links</h3> <p>This option specifies whether the client user can follow symbolic links that point outside the shared directory tree. This includes any files or directories at the other end of the link, as long as the permissions are correct for the user. The default value for this option is <tt class="literal">yes</tt>. Note that this option will not be honored if the <tt class="literal">follow</tt> <tt class="literal">symlinks</tt> options is set to <tt class="literal">no</tt>. Setting this option to <tt class="literal">no</tt> slows <em class="emphasis">smbd</em> considerably because it will have to check each link it encounters.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-1.3.5"/> <h3 class="head3">hide dot files</h3> <p>The <tt class="literal">hide</tt><a name="INDEX-24"/><a name="INDEX-25"/> <tt class="literal">dot</tt> <tt class="literal">files</tt> option hides any files on the server that begin with a dot (.) character to mimic the functionality behind several shell commands that are present on Unix systems. Like <tt class="literal">hide</tt> <tt class="literal">files</tt>, those files that begin with a dot have the DOS hidden attribute set, which doesn't guarantee that a client cannot view them. The default value for this option is <tt class="literal">yes</tt>.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-1.3.6"/> <h3 class="head3">hide files</h3> <p>The <tt class="literal">hide</tt><a name="INDEX-26"/> <tt class="literal">files</tt> option provides one or more directory or filename patterns to Samba. Any file matching this pattern will be treated as a hidden file from the perspective of the client. Note that this simply means that the DOS hidden attribute is set, which might or might not mean that the user can actually see it while browsing.</p> <p>Each entry in the list must begin, end, or be separated from another entry with a slash (<tt class="literal">/</tt>) character, even if only one pattern is listed. This allows spaces to appear in the list. Asterisks can be used as a wildcard to represent zero or more characters. Questions marks can be used to represent exactly one character. For example:</p> <blockquote><pre class="code">hide files = /.jav*/README.???/</pre></blockquote> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-1.3.7"/> <a name="INDEX-27"/><h3 class="head3">veto files</h3> <p>More stringent than the hidden files state is the state provided by the <tt class="literal">veto</tt> <tt class="literal">files</tt> configuration option. Samba won't even admit these files exist. You cannot list or open them from the client. This should not be used as a means of implementing security. It is actually a mechanism to keep PC programs from deleting special files, such as ones used to store the resource fork of a Macintosh file on a Unix filesystem. If both Windows and Macs are sharing the same files, this can prevent ill-advised power users from removing files the Mac users need.</p> <p>The syntax of this option is identical to that of the <tt class="literal">hide</tt> <tt class="literal">files</tt> configuration option: each entry must begin, end, or be separated from another with a slash ( / ) character, even if only one pattern is listed. Asterisks can be used as a wildcard to represent zero or more characters. Question marks can be used to represent exactly one character. For example:</p> <blockquote><pre class="code">veto files = /*config/*default?/</pre></blockquote> <p>This option is primarily administrative and is not a substitute for good file permissions.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-1.3.8"/> <a name="INDEX-28"/><h3 class="head3">delete veto files</h3> <p>This option tells Samba to delete vetoed files when a user attempts to delete the directory in which they reside. The default value is <tt class="literal">no</tt>. This means that if a user tries to delete a directory that contains a vetoed file, the file (and the directory) will not be deleted. Instead, the directory remains and appears empty from the perspective of the user. If set to <tt class="literal">yes</tt>, the directory and the vetoed files will be deleted. <a name="INDEX-29"/><a name="INDEX-30"/></p> </div> </div> </div> <div class="sect1"><a name="samba2-CHP-8-SECT-2"/> <h2 class="head1">File Permissions and Attributes on MS-DOS and Unix</h2> <p><a name="INDEX-31"/><a name="INDEX-32"/><a name="INDEX-33"/>Originally, DOS was not intended to be a multiuser, networked operating system. Unix, on the other hand, was designed for multiple users from the start. Consequently, Samba must not only be aware of, but also provide special solutions for, inconsistencies and gaps in coverage between the two filesystems. One of the biggest gaps is how Unix and DOS handle permissions on files.</p> <p>Let's take a look at how Unix assigns permissions. All Unix files have read, write, and execute bits for three classifications of users: owner, group, and world. These permissions can be seen at the extreme lefthand side when an <em class="emphasis">ls -al</em> command is issued in a Unix directory. For example:</p> <blockquote><pre class="code">-rwxr--r-- 1 tom users 2014 Apr 13 14:11 access.conf</pre></blockquote> <p>Windows, on the other hand, has four principal bits that it uses with any file: read-only, system, hidden, and archive. You can view these bits by right-clicking the file and choosing the Properties menu item. You should see a dialog similar to <a href="ch08.html#samba2-CHP-8-FIG-1">Figure 8-1</a>.<a name="FNPTR-1"/><a href="#FOOTNOTE-1">[1]</a></p> <div class="figure"><a name="samba2-CHP-8-FIG-1"/><img src="figs/sam2_0801.gif"/></div><h4 class="head4">Figure 8-1. DOS and Windows file properties</h4> <p>The definition of each bit follows:</p> <dl> <dt><b>Read-only</b></dt> <dd> <p>The file's contents can be read by a user but cannot be written to.</p> </dd> <dt><b>System</b></dt> <dd> <p>This file has a specific purpose required by the operating system.</p> </dd> <dt><b>Hidden</b></dt> <dd> <p>This file has been marked to be invisible to the user, unless the operating system is explicitly set to show it.</p> </dd> <dt><b>Archive</b></dt> <dd> <p>This file has been touched since the last DOS backup was performed on it.</p> </dd> </dl> <p>Note that there is no bit to specify that a file is executable. DOS and Windows NT filesystems identify executable files by giving them the extensions <em class="filename">.exe</em>, <em class="filename">.com</em>, <em class="filename">.cmd</em>, or <em class="filename">.bat</em>.</p> <p>Consequently, there is no use for any of the three Unix executable bits that are present on a file in a Samba disk share. DOS files, however, have their own attributes that need to be preserved when they are stored in a Unix environment: the archive, system, and hidden bits. Samba can preserve these bits by reusing the executable permission bits of the file on the Unix side—if it is instructed to do so. Mapping these bits, however, has an unfortunate side effect: if a Windows user stores a file in a Samba share, and you view it on Unix with the <em class="emphasis">ls -al</em> command, some of the executable bits won't mean what you'd expect them to.</p> <p>Three Samba options decide whether the bits are mapped: <tt class="literal">map</tt><a name="INDEX-34"/> <tt class="literal">archive</tt>, <tt class="literal">map</tt><a name="INDEX-35"/> <tt class="literal">system</tt> , and <tt class="literal">map</tt><a name="INDEX-36"/> <tt class="literal">hidden</tt>. These options map the archive, system, and hidden attributes to the owner, group, and world execute bits of the file, respectively. You can add these options to the <tt class="literal">[data]</tt> share, setting each of their values as follows:</p> <blockquote><pre class="code">[data] map archive = yes map system = yes map hidden = yes</pre></blockquote> <p>After that, try creating a file in the share under Unix—such as <em class="emphasis">hello.java</em>—and change the permissions of the file to 755. With these Samba options set, you should be able to check the permissions on the Windows side and see that each of the three values has been checked in the Properties dialog box. What about the read-only attribute? By default, Samba sets this whenever a file does not have the Unix owner write permission bit set. In other words, you can set this bit by changing the permissions of the file to 555.</p> <p>The default value of the <tt class="literal">map</tt> <tt class="literal">archive</tt> option is <tt class="literal">yes</tt>, while the other two options have a default value of <tt class="literal">no</tt>. This is because many programs do not work properly if the archive bit is not stored correctly for DOS and Windows files. The system and hidden attributes, however, are not critical for a program's operation and are left to the discretion of the administrator.</p> <p><a href="ch08.html#samba2-CHP-8-FIG-2">Figure 8-2</a> summarizes the <a name="INDEX-37"/><a name="INDEX-38"/>Unix permission bits and illustrates how Samba maps those bits to DOS attributes. Note that the group read/write and world read/write bits do not directly translate to a DOS attribute, but they still retain their original Unix definitions on the Samba server.</p> <div class="figure"><a name="samba2-CHP-8-FIG-2"/><img src="figs/sam2_0802.gif"/></div><h4 class="head4">Figure 8-2. How Samba and Unix view the permissions of a file</h4> <div class="sect2"><a name="samba2-CHP-8-SECT-2.1"/> <h3 class="head2">Creation Masks</h3> <p><a name="INDEX-39"/>File and directory creation masks are similar to <a name="INDEX-40"/>umasks you have probably encountered while working with Unix systems. They are used to help define the permissions that will be assigned to a file or directory at the time it is created. Samba's masks work differently in that the bits that can be set are set in the creation mask, while in Unix umasks, the bits <em class="emphasis">cannot</em> be set are set in the umask. We think you will find Samba's method to be much more intuitive. Once in a while you might need to convert between a Unix umask and the equivalent Samba mask. It is simple: one is just the bitwise complement of the other. For example, an octal umask of 0022 has the same effect as a Samba mask of 0755.</p> <p>Unix umasks are set on a user-by-user basis, usually while executing the GUI's or command-line shell's startup scripts. When users connect to a Samba share from a network client, these scripts are not executed, so Samba supplies the ability to set the creation masks for files and directories. By default, this is done on a share-by-share basis, although you can use the <tt class="literal">include</tt> parameter in the Samba configuration file (as explained in <a href="ch06.html">Chapter 6</a>) to assign masks on a user-by-user basis, thus matching conventional Unix behavior.</p> <p>To show how Samba's create masks work, suppose we have a Windows Me user connecting to his Unix home directory through Samba, and Samba is configured with <tt class="literal">create</tt> <tt class="literal">mask</tt> <tt class="literal">=</tt> <tt class="literal">777</tt> in the <tt class="literal">[homes]</tt> share. With this value, <tt class="literal">create</tt> <tt class="literal">mask</tt> will not affect the bits that are set on new files. If the user creates a file with Wordpad, it will appear in the Unix filesystem like this:</p> <blockquote><pre class="code">$ <tt class="userinput"><b>ls -l file.doc</b></tt> -rwxrw-rw- 1 jay jay 0 Sep 21 11:02 file.doc</pre></blockquote> <p>Wordpad created the file with read/write permissions (i.e., the MS-DOS read-only attribute was not set), so Samba mapped the MS-DOS attributes to Unix read/write permissions for user, group, and other. The <a name="INDEX-41"/><a name="INDEX-42"/>execute bit is set for the owner because by default, the <tt class="literal">map</tt> <tt class="literal">archive</tt> parameter is set to <tt class="literal">yes</tt>. The other execute bits are not set because <tt class="literal">map</tt> <tt class="literal">system</tt> and <tt class="literal">map</tt> <tt class="literal">hidden</tt> are set to <tt class="literal">no</tt> by default. You can customize this behavior as you see fit, and unless you do backups from MS-DOS or Windows systems, you might want to specify <tt class="literal">map</tt> <tt class="literal">archive</tt> <tt class="literal">=</tt> <tt class="literal">no</tt> to avoid Windows files from appearing as executables on the Unix system.</p> <p>Now suppose we set <tt class="literal">create</tt><a name="INDEX-43"/> <tt class="literal">mask</tt> to have an effect. For example:</p> <blockquote><pre class="code">[homes] create mask = 664</pre></blockquote> <p>This is equivalent to a Unix umask of 113. If the user creates the Wordpad document as before, it will show up as:</p> <blockquote><pre class="code">$ <tt class="userinput"><b>ls -l file.doc</b></tt> -rw-rw-r-- 1 jay jay 0 Sep 22 16:38 file.doc</pre></blockquote> <p>Comparing this to the previous example, notice that not only has the write permission for other disappeared as we expected, but so has the execute permission for owner. This happened because the value of <tt class="literal">create</tt> <tt class="literal">mask</tt> logically ANDs the owner's permissions with a 6, which has masked off the execute bit. The lesson here is that if you want to enable any of <tt class="literal">map</tt> <tt class="literal">archive</tt>, <tt class="literal">map</tt> <tt class="literal">system</tt>, or <tt class="literal">map</tt> <tt class="literal">hidden</tt>, you must be careful not to mask off the corresponding execute bit with your <tt class="literal">create</tt> <tt class="literal">mask</tt>.</p> <p>The <tt class="literal">directory</tt><a name="INDEX-44"/> <tt class="literal">mask</tt> option works similarly, masking permissions for newly created directories. The following example will allow the permissions of a newly created directory to be, at most, 755:</p> <blockquote><pre class="code">[data] directory mask = 755</pre></blockquote> <p>Also, you can force various bits with the <tt class="literal">force</tt> <tt class="literal">create</tt> <tt class="literal">mode</tt> and <tt class="literal">force</tt> <tt class="literal">directory</tt> <tt class="literal">mode</tt> options. These options will perform a logical OR against the file and directory creation masks, ensuring that those bits that are specified will always be set. You would typically set these options globally to ensure that group and world read/write permissions have been set appropriately for new files or directories in each share.</p> <p>In the same spirit, if you wish to set explicitly the Unix user and group attributes of a file created on the Windows side, you can use the <tt class="literal">force</tt><a name="INDEX-45"/> <tt class="literal">user</tt> and <tt class="literal">force</tt><a name="INDEX-46"/> <tt class="literal">group</tt> options. For example:</p> <blockquote><pre class="code">[data] create mask = 744 directory mask = 755 force user = joe force group = accounting</pre></blockquote> <p>These options assign the same Unix username and group to every client that connects to the share. However, this occurs <em class="emphasis">after</em> the client authenticates; it does not allow free access to a share. These options are frequently used for their side effects of assigning a specific user and group to each new file or directory that is created in a share. Use these options with discretion.</p> <p>Finally, one of the capabilities of Unix that DOS lacks is the ability to delete a read-only file from a writable directory. In Unix, if a directory is writable, a read-only file in that directory can still be removed. This could permit you to delete files in any of your directories, even if the file was left by someone else.</p> <p>DOS filesystems are not designed for multiple users, and so its designers decided that read-only means "protected against accidental change, including deletion," rather than "protected against some other user on a single-user machine." So the designers of DOS prohibited removal of a read-only file. Even today, Windows filesystems exhibit the same behavior.</p> <p>Normally, this is harmless. Windows programs don't try to remove read-only files because they know it's a bad idea. However, a number of source-code control programs—which were first written for Unix—run on Windows and require the ability to delete read-only files. Samba permits this behavior with the <tt class="literal">delete</tt><a name="INDEX-47"/> <tt class="literal">readonly</tt> option. To enable this functionality, set the option to <tt class="literal">yes</tt>:</p> <a name="INDEX-48"/><blockquote><pre class="code">[data] delete readonly = yes</pre></blockquote> </div> <div class="sect2"><a name="samba2-CHP-8-SECT-2.2"/> <h3 class="head2">File and Directory Permission Options</h3> <p><a name="INDEX-49"/><a name="INDEX-50"/><a name="INDEX-51"/>The options for file and directory permissions are summarized in <a href="ch08.html#samba2-CHP-8-TABLE-2">Table 8-2</a>; each option is then described in detail.</p> <a name="samba2-CHP-8-TABLE-2"/><h4 class="head4">Table 8-2. File and directory permission options</h4><table border="1"> <tr> <th> <p>Option</p> </th> <th> <p>Parameters</p> </th> <th> <p>Function</p> </th> <th> <p>Default</p> </th> <th> <p>Scope</p> </th> </tr> <tr> <td> <p><tt class="literal">create mask</tt> <tt class="literal">(create mode)</tt></p> </td> <td> <p>numeric</p> </td> <td> <p>Maximum permissions for files created by Samba.</p> </td> <td> <p><tt class="literal">0744</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">directory mask</tt> <tt class="literal">(directory mode)</tt></p> </td> <td> <p>numeric</p> </td> <td> <p>Maximum permissions for directories created by Samba.</p> </td> <td> <p><tt class="literal">0744</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">force create mode</tt></p> </td> <td> <p>numeric</p> </td> <td> <p>Forces the specified permissions (bitwise <tt class="literal">or</tt>) for directories created by Samba.</p> </td> <td> <p><tt class="literal">0000</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">force directory</tt> <tt class="literal">mode</tt></p> </td> <td> <p>numeric</p> </td> <td> <p>Forces the specified permissions (bitwise <tt class="literal">or</tt>) for directories created by Samba.</p> </td> <td> <p><tt class="literal">0000</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">force group</tt> <tt class="literal">(group)</tt></p> </td> <td> <p>string ( group name)</p> </td> <td> <p>Effective group for a user accessing this share.</p> </td> <td> <p>None</p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">force user</tt></p> </td> <td> <p>string (username)</p> </td> <td> <p>Effective username for a user accessing this share.</p> </td> <td> <p>None</p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">delete readonly</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>Allows a user to delete a read-only file from a writable directory.</p> </td> <td> <p><tt class="literal">no</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">map archive</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>Preserve DOS archive attribute in user execute bit (0100).</p> </td> <td> <p><tt class="literal">yes</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">map system</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>Preserve DOS system attribute in group execute bit (0010).</p> </td> <td> <p><tt class="literal">no</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">map hidden</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>Preserve DOS hidden attribute in world execute bit (0001).</p> </td> <td> <p><tt class="literal">no</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">inherit permissions</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>If <tt class="literal">yes</tt>, permissions on new files and directories are inherited from parent directory.</p> </td> <td> <p>no</p> </td> <td> <p>Share</p> </td> </tr> </table> <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.1"/> <a name="INDEX-52"/><h3 class="head3">create mask</h3> <p>The argument for this option is an octal number indicating which permission flags can be set at file creation by a client in a share. The default is 0744, which means that the Unix owner can at most read, write, and optionally execute her own files, while members of the user's group and others can only read or execute them. If you need to change it for nonexecutable files, we recommend 0644, or <tt class="literal">rw-r--r--</tt>. Keep in mind that the execute bits can be used by the server to map certain DOS file attributes, as described earlier. If you're altering the create mask, those bits have to be part of the create mask as well.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.2"/> <a name="INDEX-53"/><h3 class="head3">directory mask</h3> <p>The argument for this option is an octal number indicating which permission flags can be set at directory creation by a client in a share. The default is 0744, which allows everyone on the Unix side to, at most, read and traverse the directories, but allows only you to modify them. We recommend the mask 0750, removing access by "the world."</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.3"/> <a name="INDEX-54"/><h3 class="head3">force create mode</h3> <p>This option sets the permission bits that Samba will set when a file permission change is made. It's often used to force group permissions, as mentioned previously. It can also be used to preset any of the DOS attributes we mentioned: archive (0100), system (0010), or hidden (0001).</p> <a name="samba2-CHP-8-NOTE-139"/><blockquote class="note"><h4 class="objtitle">TIP</h4> <p><a name="INDEX-55"/>When saving documents, many Windows applications rename their datafiles with a <em class="filename">.bak</em> extension and create new ones. When the files are in a Samba share, this changes their ownership and permissions so that members of the same Unix group can't edit them. Setting <tt class="literal">force</tt> <tt class="literal">create mode = 0660</tt> will keep the new file editable by members of the group.</p> </blockquote> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.4"/> <a name="INDEX-56"/><h3 class="head3">force directory mode</h3> <p>This option sets the permission bits that Samba will set when a directory permission change is made or a directory is created. It's often used to force group permissions, as mentioned previously. This option defaults to 0000 and can be used just like the <tt class="literal">force</tt> <tt class="literal">create</tt> <tt class="literal">mode</tt> to add group or other permissions if needed.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.5"/> <a name="INDEX-57"/><h3 class="head3">force group</h3> <p>This option, sometimes called <tt class="literal">group</tt>, assigns a static group ID that will be used on all connections to a share after the client has successfully authenticated. This assigns a specific group to each new file or directory created from an SMB client.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.6"/> <h3 class="head3">force user</h3> <p>The <tt class="literal">force</tt><a name="INDEX-58"/> <tt class="literal">user</tt> option assigns a static user ID that will be used on all connections to a share after the client has successfully authenticated. This assigns a specific user to each new file or directory created from an SMB client.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.7"/> <a name="INDEX-59"/><h3 class="head3">delete readonly</h3> <p>This option allows a user to delete a directory containing a read-only file. By default, DOS and Windows will not allow such an operation. You probably will want to leave this option turned off unless a program (for example, an RCS program) needs this capability; many Windows users would be appalled to find that they'd accidentally deleted a file that they had set as read-only.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.8"/> <a name="INDEX-60"/><h3 class="head3">map archive</h3> <p>The DOS archive bit is used to flag a file that has been changed since it was last archived (e.g., backed up with the DOS archive program). Setting the Samba option <tt class="literal">map</tt> <tt class="literal">archive</tt> <tt class="literal">=</tt> <tt class="literal">yes</tt> maps the DOS archive flag to the Unix execute-by-owner (0100) bit. It's best to leave this option on if your Windows users are doing their own backups or are using programs that require the archive bit. Unix lacks the notion of an archive bit entirely. Backup programs typically keep a file that lists what files were backed up on what date, so comparing file-modification dates serves the same purpose.</p> <p>Setting this option to <tt class="literal">yes</tt> causes an occasional surprise on Unix when a user notices that a datafile is marked as executable, but rarely causes harm. If a user tries to run it, he will normally get a string of error messages as the shell tries to execute the first few lines as commands. The reverse is also possible; an executable Unix program looks like it hasn't been backed up recently on Windows. But again, this is rare and usually harmless.</p> <p>For map archive to work properly, the execute bit for owner must not be masked off with the <tt class="literal">create</tt> <tt class="literal">mask</tt> parameter.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.9"/> <a name="INDEX-61"/><h3 class="head3">map system</h3> <p>The DOS system attribute indicates files that are required by the operating system and should not be deleted, renamed, or moved without special effort. Set this option only if you need to store Windows system files on the Unix fileserver. Executable Unix programs will appear to be nonremovable, special Windows files when viewed from Windows clients. This might prove mildly inconvenient if you want to move or remove one. For most sites, however, this is fairly harmless.</p> <p>For map archive to work properly, the execute bit for group must not be masked off with the <tt class="literal">create</tt> <tt class="literal">mask</tt> parameter.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.10"/> <a name="INDEX-62"/><h3 class="head3">map hidden</h3> <p>DOS uses the hidden attribute to indicate that a file should not ordinarily be visible in directory listings. Unix doesn't have such a facility; it's up to individual programs (notably, the shell) to decide what to display and what not to display. Normally, you won't have any DOS files that need to be hidden, so the best thing to do is to leave this option turned off.</p> <p>Setting this option to <tt class="literal">yes</tt> causes the server to map the hidden flag onto the executable-by-others bit (0001). This feature can produce a rather startling effect. Any Unix program that is executable by world seems to vanish when you look for it from a Windows client. If this option is not set, however, and a Windows user attempts to mark a file hidden on a Samba share, it will not work—Samba has no place to store the hidden attribute!</p> <p>For map archive to work properly, the execute bit for other must not be masked off with the <tt class="literal">create</tt> <tt class="literal">mask</tt> parameter.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.11"/> <h3 class="head3">inherit permissions</h3> <p>When the <tt class="literal">inherit</tt><a name="INDEX-63"/> <tt class="literal">permissions</tt> option is set to <tt class="literal">yes</tt>, the <tt class="literal">create</tt> <tt class="literal">mask</tt>, <tt class="literal">directory</tt> <tt class="literal">mask</tt>, <tt class="literal">force</tt> <tt class="literal">create</tt> <tt class="literal">mode</tt>, and <tt class="literal">force</tt> <tt class="literal">directory</tt> <tt class="literal">mode</tt> are ignored. The normal behavior of setting the permissions on newly created files is overridden such that the new files and directories take on permissions from their parent directory. New directories will have exactly the same permissions as the parent, and new files will inherit the read and write bits from the parent directory, while the execute bits are determined as usual by the values of the <tt class="literal">map</tt> <tt class="literal">archive</tt>, <tt class="literal">map</tt> <tt class="literal">hidden</tt>, and <tt class="literal">map</tt> <tt class="literal">system</tt> parameters.</p> <p>By default, this option is set to <tt class="literal">no</tt>. <a name="INDEX-64"/><a name="INDEX-65"/><a name="INDEX-66"/> <a name="INDEX-67"/><a name="INDEX-68"/><a name="INDEX-69"/></p> </div> </div> </div> <div class="sect1"><a name="samba2-CHP-8-SECT-3"/> <h2 class="head1">Windows NT/2000/XP ACLs</h2> <p><a name="INDEX-70"/><a name="INDEX-71"/><a name="INDEX-72"/><a name="INDEX-73"/>Unix and Windows have different <a name="INDEX-74"/>security models, and Windows NT/2000/XP has a security model that is different from Windows 95/98/Me. One area in which this is readily apparent is file protections. On Unix systems, the method used has traditionally been the 9-bit "user, group, other" system, in which read, write, and execute bits can be set separately for the owner of the file, the groups to which the owner belongs, and everyone else, respectively.</p> <p><a name="INDEX-75"/>Windows 95/98/Me has a file-protection system that is essentially no protection at all. This family of operating systems was developed from MS-DOS, which was implemented as a non-networked, single-user system. Multiuser security simply was never added. One apparent exception to this is user-level security for shared files, which we will discuss in <a href="ch09.html">Chapter 9</a>. Here, separate access permissions can be assigned to individual network client users or groups. However, user-level security on Windows 95/98/Me systems requires a Windows NT/2000 or Samba server to perform the actual authentication.</p> <p>On <a name="INDEX-76"/><a name="INDEX-77"/><a name="INDEX-78"/>Windows NT/2000/XP, user-level security is an extension of the native file security model, which involves access control lists (ACLs). This system is somewhat more extensive than the Unix security model, allowing the access rights on individual files to be set separately for any number of individual users and/or any number of arbitrary groups of users. <a href="ch08.html#samba2-CHP-8-FIG-3">Figure 8-3</a>, <a href="ch08.html#samba2-CHP-8-FIG-4">Figure 8-4</a>, and <a href="ch08.html#samba2-CHP-8-FIG-5">Figure 8-5</a> show the dialog boxes on a Windows 2000 system in which the ACL is set for a file. By right-clicking a file's icon and selecting Properties, then selecting the Security tab, we get to the dialog box shown in <a href="ch08.html#samba2-CHP-8-FIG-3">Figure 8-3</a>. Here, we can set the basic permissions for a file, which are similar to Unix permissions, although not identical.</p> <div class="figure"><a name="samba2-CHP-8-FIG-3"/><img src="figs/sam2_0803.gif"/></div><h4 class="head4">Figure 8-3. The Security tab of the file Properties dialog</h4> <p>By clicking the Advanced tab, we can bring up the dialog box shown in <a href="ch08.html#samba2-CHP-8-FIG-4">Figure 8-4</a>, which shows the list of <a name="INDEX-79"/>access control entries (ACEs) in the ACL. In this dialog, ACEs can be added to or deleted from the ACL, or an existing ACE can be viewed and modified. Each ACE either allows or denies a set of permissions for a specific user or group.</p> <div class="figure"><a name="samba2-CHP-8-FIG-4"/><img src="figs/sam2_0804.gif"/></div><h4 class="head4">Figure 8-4. The Permissions tab of the Access Control Settings dialog</h4> <div class="figure"><a name="samba2-CHP-8-FIG-5"/><img src="figs/sam2_0805.gif"/></div><h4 class="head4">Figure 8-5. Permission Entry dialog, showing the settings of an ACE</h4> <p><a href="ch08.html#samba2-CHP-8-FIG-5">Figure 8-5</a> shows the dialog box for adding an ACE. As you can see, there are more options for permissions in an ACL than with the permission bits on typical Unix systems. You can learn more about these settings in <em class="citetitle">Essential Windows NT System Administration</em>, published by O'Reilly.</p> <p>In a networked environment where a Samba server is serving files to Windows NT/2000/XP clients, Samba has to map Unix permissions for files and directories to Windows NT/2000/XP access control lists. When a Windows NT/2000/XP client accesses a shared file or directory on a Samba server, Samba translates the object's ownership, group, and permissions into an ACL and returns them to the client.</p> <p><a href="ch08.html#samba2-CHP-8-FIG-6">Figure 8-6</a> shows the Properties dialog box for the file <em class="filename">shopping_list.doc</em> that resides on the Samba server.</p> <div class="figure"><a name="samba2-CHP-8-FIG-6"/><img src="figs/sam2_0806.gif"/></div><h4 class="head4">Figure 8-6. The Properties dialog for a file on the Samba server</h4> <p>From Unix, this file appears as:</p> <blockquote><pre class="code">$ <tt class="userinput"><b>ls -l shopping_list.doc</b></tt> -rw------- 1 adilia users 49 Mar 29 11:58 shopping_list.doc</pre></blockquote> <p>Notice that because the file has read permissions for the owner, the Read-only checkbox will show as cleared, even though the user on the Windows client (who is not <tt class="literal">adilia</tt> in this example) does not have read access permissions. The checkboxes here show only DOS attributes. By clicking the Security tab, we can start to examine the ACLs, as shown in <a href="ch08.html#samba2-CHP-8-FIG-7">Figure 8-7</a>.</p> <div class="figure"><a name="samba2-CHP-8-FIG-7"/><img src="figs/sam2_0807.gif"/></div><h4 class="head4">Figure 8-7. The Security tab of the Properties dialog for a file on the Samba server</h4> <p>The owner of the file (<tt class="literal">adilia</tt>) is shown as one entry, while the group (<tt class="literal">users</tt>) and other permissions are presented as the groups called <tt class="literal">users</tt> and <tt class="literal">Everyone</tt>. Clicking one of the items in the upper windows causes the simplified view of the permissions in that item to appear in the bottom window. Here, the read/write permissions for <tt class="literal">adilia</tt> appear in a manner that makes the security model of Unix and Windows seem similar. However, clicking the Advanced . . . button brings up the additional dialog box shown in <a href="ch08.html#samba2-CHP-8-FIG-8">Figure 8-8</a>.</p> <div class="figure"><a name="samba2-CHP-8-FIG-8"/><img src="figs/sam2_0808.gif"/></div><h4 class="head4">Figure 8-8. The Access Control Settings dialog for a file on the Samba server</h4> <p>In this dialog box, we see the actual ACL of the file. The ACEs for <tt class="literal">users</tt> and <tt class="literal">Everyone</tt> are listed with Take Ownership in the Permission column. This is a trick used by Samba for ACLs that have no permissions on the Unix side. On Windows, an ACL with nothing set results in no ACL at all, so Samba sets the Take Ownership permission to make sure that all the ACLs corresponding to the Unix "user, group, other" permissions will show up on Windows. The Take Ownership permission has no corresponding Unix attribute, so the setting on Windows does not affect the actual file on the Unix system in any way. Although Windows client users might be misled into thinking they can take ownership of the file (that is, change the ownership of the file to themselves), an actual attempt to do so will fail.</p> <p>The Permissions column for the <tt class="literal">adilia</tt> ACL is listed as Special because Samba reports permissions for the file that do not correspond to settings for which Windows has a more descriptive name. Clicking the entry and then clicking the View/Edit . . . button brings up the dialog box shown in <a href="ch08.html#samba2-CHP-8-FIG-9">Figure 8-9</a>, in which the details of the ACL permissions can be viewed and perhaps modified.</p> <div class="figure"><a name="samba2-CHP-8-FIG-9"/><img src="figs/sam2_0809.gif"/></div><h4 class="head4">Figure 8-9. Permission Entry dialog for a file served by Samba</h4> <p>We say "perhaps" here because checking or unchecking boxes in this dialog box might not result in settings that Samba is able to map back into the Unix security model. When a user attempts to modify a setting (either permissions or ownership) that she does not have authority to change, or does not correspond to a valid setting on the Unix system, Samba will respond with an error dialog or by quietly ignoring the unmappable settings.</p> <p>The ACLs for a directory are slightly different. <a href="ch08.html#samba2-CHP-8-FIG-10">Figure 8-10</a> shows the ACL view after clicking the Advanced button.</p> <div class="figure"><a name="samba2-CHP-8-FIG-10"/><img src="figs/sam2_0810.gif"/></div><h4 class="head4">Figure 8-10. The Access Control Settings dialog for a directory on the Samba server</h4> <p>Here, there are two ACLs each for <tt class="literal">users</tt> and <tt class="literal">Everyone</tt>. One ACL specifies the permissions for the directory itself, and the other specifies permissions for the directory's contents. When changing settings in the View/Edit... dialog, there is an extra drop-down menu to apply the settings either to just the directory or to some combination of the directory and the files and directories it contains. If settings are applied to more than just the directory, Samba will match the behavior of a Windows server and change the permissions on the contents of the directory, as specified in the dialog.</p> <div class="sect2"><a name="samba2-CHP-8-SECT-3.1"/> <h3 class="head2">Unix ACLs</h3> <p><a name="INDEX-80"/><a name="INDEX-81"/>In most cases, users of Windows clients will find the Unix security model to be sufficient. However, in some cases, people might want the Samba server to support the full Windows ACL security model. Even if they don't need the fine-grained control over file and directory permissions, they might find Samba's translation between ACLs and Unix permissions to be a source of confusion or frustration.</p> <p>When the underlying Unix host operating system supports <a name="INDEX-82"/><a name="INDEX-83"/>POSIX.1e ACLs, Samba provides much better support of Windows NT/2000/XP ACLs. Versions of Unix that offer the necessary support include the following:</p> <ul><li> <p>Solaris 2.6 and later</p> </li><li> <p>SGI Irix</p> </li><li> <p>Linux, with Andreas Grünbacher's kernel patch from <a href="http://acl.bestbits.at">http://acl.bestbits.at</a> that adds ACL support to the Linux ext2 and ext3 filesystems</p> </li><li> <p>Linux, with the XFS filesystem</p> </li><li> <p>AIX</p> </li><li> <p>FreeBSD 5.0 and later</p> </li><li> <p>HP/UX 11.0 and later, with the JFS 3.3 filesystem layout Version 4</p> </li></ul> <p>If you are fortunate enough to have a Unix host operating system with ACL support already provided, all you need to do is recompile Samba using the <tt class="literal">--with-acl-support</tt> configure option, as we described in <a href="ch02.html">Chapter 2</a>. If you are running Linux and need to patch your kernel, things are much more complicated. We suggest you refer to the documentation that comes with the patch for details on using it.</p> </div> <div class="sect2"><a name="samba2-CHP-8-SECT-3.2"/> <h3 class="head2">Configuration Options for ACLs</h3> <p><a href="ch08.html#samba2-CHP-8-TABLE-3">Table 8-3</a> <a name="INDEX-84"/><a name="INDEX-85"/>shows the Samba configuration options for working with Windows NT/2000/XP access control lists.</p> <a name="samba2-CHP-8-TABLE-3"/><h4 class="head4">Table 8-3. ACL configuration options</h4><table border="1"> <tr> <th> <p>Option</p> </th> <th> <p>Parameters</p> </th> <th> <p>Function</p> </th> <th> <p>Default</p> </th> <th> <p>Scope</p> </th> </tr> <tr> <td> <p><tt class="literal">nt acl support</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>If <tt class="literal">yes</tt>, allows users on Windows NT/2000/XP clients to modify ACL settings</p> </td> <td> <p><tt class="literal">yes</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">security mask</tt></p> </td> <td> <p>numeric</p> </td> <td> <p>Bitmask that allows or denies permission settings on files</p> </td> <td> <p><tt class="literal">0777</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">force security</tt> <tt class="literal">mode</tt></p> </td> <td> <p>numeric</p> </td> <td> <p>Bits that are always set when modifying file permissions</p> </td> <td> <p><tt class="literal">0000</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">directory</tt> <tt class="literal">security mask</tt></p> </td> <td> <p>numeric</p> </td> <td> <p>Bitmask that allows or denies permission settings on directories</p> </td> <td> <p><tt class="literal">0777</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">force directory</tt> <tt class="literal">security mode</tt></p> </td> <td> <p>numeric</p> </td> <td> <p>Bits that are always set when modifying directory permissions</p> </td> <td> <p><tt class="literal">0000</tt></p> </td> <td> <p>Share</p> </td> </tr> </table> <div class="sect3"><a name="samba2-CHP-8-SECT-3.2.1"/> <a name="INDEX-86"/><h3 class="head3">nt acl support</h3> <p>This parameter defaults to <tt class="literal">yes</tt>, which allows users on Windows NT/2000/XP clients to modify ACL settings for files on the Samba server. When set to <tt class="literal">no</tt>, files show up as owned by <tt class="literal">Everyone</tt>, with permissions appearing as "Full Control". However, <em class="emphasis">actual</em> ownership and permissions are enforced as whatever they are set to on the Samba server, and the user on the Windows client cannot view or modify them with the dialog boxes used for managing ACLs.</p> <p>When enabled, support for Windows NT/2000/XP ACLs is limited to whatever ownerships and permissions can map into valid users and permissions on the Samba server. If the server supports ACLs (either "out of the box" or with an additional patch to enhance the filesystem), Samba's ACL support more closely matches that of a Windows NT/2000/XP server.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-3.2.2"/> <h3 class="head3">security mask</h3> <p>Using the <tt class="literal">security</tt><a name="INDEX-87"/> <tt class="literal">mask</tt> option, it is possible to define which file permissions users can modify from Windows NT/2000/XP clients. This is for files only and not directories, which are handled with the <tt class="literal">directory</tt><a name="INDEX-88"/> <tt class="literal">security</tt> <tt class="literal">mask</tt> option. The parameter is assigned a numeric value that is a Unix-style permissions mask. For bits in the mask that are set, the client can modify the corresponding bits in the files' permissions. If the bit is zero, the client cannot modify that permission. For example, if <tt class="literal">security</tt> <tt class="literal">mask</tt> is set as:</p> <blockquote><pre class="code">[data] security mask = 0777</pre></blockquote> <p>the client can modify all the user/group/other permissions for the files in the share. This is the default. A value of <tt class="literal">0</tt> would deny clients from changing any of the permissions, and setting <tt class="literal">security</tt> <tt class="literal">mask</tt> as:</p> <blockquote><pre class="code">[data] security mask = 0666</pre></blockquote> <p>would allow client users to modify the read and write permissions, but not the execute permissions.</p> <p>Do not count on <tt class="literal">security</tt> <tt class="literal">mask</tt> for complete control because if the user can access the files on the Samba server through any other means (for example, by logging directly into the Unix host), he can modify the permissions using that method.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-3.2.3"/> <h3 class="head3">force security mode</h3> <p>The <tt class="literal">force</tt><a name="INDEX-89"/> <tt class="literal">security</tt> <tt class="literal">mode</tt> option can be used to define a set of permissions that are always set whenever the user on a Windows NT/2000/XP client modifies a file's permissions. (See the <tt class="literal">force</tt> <tt class="literal">directory</tt> <tt class="literal">security</tt> <tt class="literal">mode</tt> option for handling directories.)</p> <p>Be careful to understand this properly. The mask given as the parameter's value is not necessarily equal to the resulting permissions on the file. The permissions that the client user attempts to modify are logically OR'd with the <tt class="literal">force</tt> <tt class="literal">security</tt> <tt class="literal">mode</tt> <tt class="literal">mask</tt> option, and any bits that are turned on will cause the file's corresponding permissions to be set. As an example, suppose <tt class="literal">force</tt> <tt class="literal">security</tt> <tt class="literal">mode</tt> is set in a share thusly:</p> <blockquote><pre class="code">[data] force security mode = 0440</pre></blockquote> <p>(This sets the read bit for owner and group, but not other.) If a user on a Windows NT/2000/XP client modifies an ACL on a file in the <tt class="literal">[data]</tt> share and attempts to remove all read permissions, the read permission for other (<tt class="literal">Everyone</tt>) will be removed, but the read permission for the owner and group will remain. Note that this parameter cannot force a permission bit to be turned off.</p> <p>As with the <tt class="literal">security</tt> <tt class="literal">mask</tt> option, if a user can access the files in the share through any means other than Samba, she can easily work around Samba's enforcement of this parameter.</p> <p>The default value of <tt class="literal">force</tt> <tt class="literal">security</tt> <tt class="literal">mode</tt> is <tt class="literal">0000</tt>, which allows users to remove any permission from files.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-3.2.4"/> <a name="INDEX-90"/><h3 class="head3">directory security mask</h3> <p>This option works exactly the same as the <tt class="literal">security</tt> <tt class="literal">mask</tt> option, except that it operates on directories rather than files. As with <tt class="literal">security</tt> <tt class="literal">mask</tt>, it has a default value of <tt class="literal">0777</tt>, which allows Windows NT/2000/XP client users to modify all Unix permissions on directories in the share.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-3.2.5"/> <a name="INDEX-91"/><h3 class="head3">force directory security mode</h3> <p>This option works exactly the same as the <tt class="literal">force</tt> <tt class="literal">security</tt> <tt class="literal">mode</tt> option, except that it operates on directories rather than files. It also has a default value of <tt class="literal">0000</tt>, which allows Windows NT/2000/XP client users to remove any permissions from directories in the share. <a name="INDEX-92"/><a name="INDEX-93"/><a name="INDEX-94"/><a name="INDEX-95"/> <a name="INDEX-96"/><a name="INDEX-97"/></p> </div> </div> </div> <div class="sect1"><a name="samba2-CHP-8-SECT-4"/> <h2 class="head1">Name Mangling and Case</h2> <p><a name="INDEX-98"/><a name="INDEX-99"/><a name="INDEX-100"/><a name="INDEX-101"/>Back in the days of DOS and Windows 3.1, every filename was limited to eight uppercase characters, followed by a dot, and three more uppercase characters. This was known as the <em class="firstterm">8.3 format</em> and was a huge nuisance. Windows 95/98/Me, Windows NT/2000/XP, and Unix have since relaxed this problem by allowing longer, sometimes case-sensitive, filenames. <a href="ch08.html#samba2-CHP-8-TABLE-4">Table 8-4</a> shows the current naming state of several popular operating systems.</p> <a name="samba2-CHP-8-TABLE-4"/><h4 class="head4">Table 8-4. Operating system filename limitations</h4><table border="1"> <tr> <th> <p>Operating system</p> </th> <th> <p>File-naming rules</p> </th> </tr> <tr> <td> <p>DOS 6.22 or below</p> </td> <td> <p>Eight characters followed by a dot followed by a three-letter extension (8.3 format); case-insensitive</p> </td> </tr> <tr> <td> <p>Windows 3.1 for Workgroups</p> </td> <td> <p>Eight characters followed by a dot followed by a three-letter extension (8.3 format); case-insensitive</p> </td> </tr> <tr> <td> <p>Windows 95/98/Me</p> </td> <td> <p>255 characters; case-insensitive but case-preserving</p> </td> </tr> <tr> <td> <p>Windows NT/2000/XP</p> </td> <td> <p>255 characters; case-insensitive but case-preserving</p> </td> </tr> <tr> <td> <p>Unix</p> </td> <td> <p>255 characters; case-sensitive</p> </td> </tr> </table> <p>Samba still has to remain backward-compatible with network clients that store files in just the 8.3 format, such as Windows for Workgroups. If a user creates a file on a share called <em class="emphasis">antidisestablishmentarianism.txt</em>, a Windows for Workgroups client cannot tell it apart from another file in the same directory called <em class="emphasis">antidisease.txt</em>. Like Windows 95/98/Me and Windows NT/2000/XP, Samba has to employ a special method for translating a long filename to an 8.3 filename in such a way that similar filenames will not cause collisions. This is called <em class="firstterm">name mangling</em>, and Samba deals with this in a manner that is similar, but not identical to, Windows 95 and its successors.</p> <div class="sect2"><a name="samba2-CHP-8-SECT-4.1"/> <h3 class="head2">The Samba Mangling Operation</h3> <p><a name="INDEX-102"/>Here is how Samba mangles a long filename into an 8.3 filename:</p> <ul><li> <p>If the original filename does not begin with a dot, the first five characters before the dot (if there is one) are converted to uppercase. These characters are used as the first five characters of the 8.3 mangled filename.</p> </li><li> <p>If the original filename begins with a dot, the dot is removed and then the previous step is performed on what is left.</p> </li><li> <p>These characters are immediately followed by a special mangling character: by default, a tilde (~), although Samba allows you to change this character.</p> </li><li> <p>The base of the long filename before the last period is hashed into a two-character code; parts of the name after the last dot can be used if necessary. This two-character code is appended to the filename after the mangling character.</p> </li><li> <p>The first three characters after the last dot (if there is one) of the original filename are converted to uppercase and appended onto the mangled name as the extension. If the original filename began with a dot, three underscores ( <tt class="literal">_ _ _</tt> ) are used as the extension instead.</p> </li></ul> <p>Here are some examples:</p> <blockquote><pre class="code">virtuosity.dat VIRTU~F1.DAT .htaccess HTACC~U0._ _ _ hello.java HELLO~1F.JAV team.config.txt TEAMC~04.TXT antidisestablishmentarianism.txt ANTID~E3.TXT antidisease.txt ANTID~9K.TXT</pre></blockquote> <p>Using these rules will allow Windows for Workgroups to differentiate the two files on behalf of the poor individual who is forced to see the network through the eyes of that operating system. Note that the same long filename should always hash to the same mangled name with Samba; this doesn't always happen with Windows. The downside of this approach is that there can still be collisions; however, the chances are greatly reduced.</p> <p>You generally want to use the mangling configuration options with only the oldest clients. We recommend doing this without disrupting other clients by adding an <tt class="literal">include</tt> directive to the <em class="filename">smb.conf</em> file:</p> <blockquote><pre class="code">[global] include = /usr/local/samba/lib/smb.conf.%a</pre></blockquote> <p>This resolves to <em class="filename">smb.conf.WfWg</em> when a Windows for Workgroups client attaches. Now you can create a file <em class="filename">/usr/local/samba/lib/smb.conf.WfWg</em>, which might contain these options:</p> <blockquote><pre class="code">[global] case sensitive = no default case = upper preserve case = no short preserve case = no mangle case = yes mangled names= yes</pre></blockquote> <p>If you are not using Windows for Workgroups, you probably do not need to change any of these options from their defaults.</p> <div class="sect3"><a name="samba2-CHP-8-SECT-4.1.1"/> <h3 class="head3">Representing and resolving filenames with Samba</h3> <p><a name="INDEX-103"/>Another item that we should point out is that there is a difference between how an operating system <em class="emphasis">represents</em> a file and how it <em class="emphasis">resolves</em> it. For example, you have likely run across a file on a Windows system called <em class="filename">README.TXT</em>. The file can be represented by the operating system entirely in uppercase letters. However, if you open an MS-DOS command prompt and enter the command:</p> <blockquote><pre class="code">C:\> <tt class="userinput"><b>notepad readme.txt</b></tt></pre></blockquote> <p>the all-caps file is loaded into the editing program, even though you typed the name in lowercase letters.</p> <p>This is because the Windows 95/98/Me and Windows NT/2000/XP families of operating systems resolve filenames in a case-insensitive manner, even though the files are represented in a case-sensitive manner. Unix-based operating systems, on the other hand, always resolve files in a case-sensitive manner; if you try to edit <em class="filename">README.TXT</em> with the command:</p> <blockquote><pre class="code">$ <tt class="userinput"><b>vi readme.txt</b></tt></pre></blockquote> <p>you will likely be editing the empty buffer of a new file.</p> <p><a name="INDEX-104"/>Here is how Samba handles case: if the <tt class="literal">preserve</tt><a name="INDEX-105"/> <tt class="literal">case</tt> is set to <tt class="literal">yes</tt>, Samba will always use the case provided by the operating system for representing (not resolving) filenames. If it is set to <tt class="literal">no</tt>, it will use the case specified by the <tt class="literal">default</tt><a name="INDEX-106"/> <tt class="literal">case</tt> option. The same is true for <tt class="literal">short</tt><a name="INDEX-107"/> <tt class="literal">preserve</tt> <tt class="literal">case</tt>. If this option is set to <tt class="literal">yes</tt>, Samba will use the default case of the operating system for representing 8.3 filenames; otherwise, it will use the case specified by the <tt class="literal">default</tt> <tt class="literal">case</tt> option. Finally, Samba will always resolve filenames in its shares based on the value of the <tt class="literal">case</tt> <tt class="literal">sensitive</tt> option.</p> </div> </div> <div class="sect2"><a name="samba2-CHP-8-SECT-4.2"/> <h3 class="head2">Mangling Options</h3> <p><a name="INDEX-108"/><a name="INDEX-109"/>Samba allows more refined instructions on how it should perform name mangling, including those controlling the case sensitivity, the character inserted to form a mangled name, and the ability to map filenames manually from one format to another. These options are shown in <a href="ch08.html#samba2-CHP-8-TABLE-5">Table 8-5</a>.</p> <a name="samba2-CHP-8-TABLE-5"/><h4 class="head4">Table 8-5. Name-mangling options</h4><table border="1"> <tr> <th> <p>Option</p> </th> <th> <p>Parameters</p> </th> <th> <p>Function</p> </th> <th> <p>Default</p> </th> <th> <p>Scope</p> </th> </tr> <tr> <td> <p><tt class="literal">case sensitive</tt></p> <p><tt class="literal">(casesignames)</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>If <tt class="literal">yes</tt>, treats filenames as case-sensitive (Windows doesn't).</p> </td> <td> <p><tt class="literal">no</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">default case</tt></p> </td> <td> <p>string (<tt class="literal">upper</tt> or <tt class="literal">lower</tt>)</p> </td> <td> <p>Case to assume as default (used only when preserve case is <tt class="literal">no</tt>).</p> </td> <td> <p>Lower</p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">preserve case</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>If <tt class="literal">yes</tt>, keep the case the client supplied (i.e., do not convert to <tt class="literal">default</tt> <tt class="literal">case</tt>).</p> </td> <td> <p><tt class="literal">yes</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">short preserve case</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>If <tt class="literal">yes</tt>, preserve case of 8.3-format names that the client provides.</p> </td> <td> <p><tt class="literal">yes</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">mangled names</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>Mangles long names into 8.3 DOS format.</p> </td> <td> <p><tt class="literal">yes</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">mangle case</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>Mangle a name if it is mixed case.</p> </td> <td> <p><tt class="literal">no</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">mangling char</tt></p> </td> <td> <p>string (single character)</p> </td> <td> <p>Gives mangling character.</p> </td> <td> <p><tt class="literal">~</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">mangled stack</tt></p> </td> <td> <p>numeric</p> </td> <td> <p>Number of mangled names to keep on the local mangling stack.</p> </td> <td> <p><tt class="literal">50</tt></p> </td> <td> <p>Global</p> </td> </tr> <tr> <td> <p><tt class="literal">mangled map</tt></p> </td> <td> <p>string (list of patterns)</p> </td> <td> <p>Allows mapping of filenames from one format into another.</p> </td> <td> <p>None</p> </td> <td> <p>Share</p> </td> </tr> </table> <div class="sect3"><a name="samba2-CHP-8-SECT-4.2.1"/> <a name="INDEX-110"/><h3 class="head3">case sensitive</h3> <p>This share-level option, which has the obtuse synonym <tt class="literal">casesignames</tt>, specifies whether Samba should preserve case when resolving filenames in a specific share. The default value for this option is <tt class="literal">no</tt>, which is how Windows handles file resolution. If clients are using an operating system that takes advantage of case-sensitive filenames, you can set this configuration option to <tt class="literal">yes</tt> as shown here:</p> <blockquote><pre class="code">[accounting] case sensitive = yes</pre></blockquote> <p>Otherwise, we recommend that you leave this option set to its default.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-4.2.2"/> <h3 class="head3">default case</h3> <p>The <tt class="literal">default</tt><a name="INDEX-111"/> <tt class="literal">case</tt> option is used with <tt class="literal">preserve</tt> <tt class="literal">case</tt>. This specifies the default case (upper or lower) Samba uses to create a file on one of its shares on behalf of a client. The default case is <tt class="literal">lower</tt>, which means that newly created files will have lowercase names. If you need to, you can override this global option by specifying the following:</p> <blockquote><pre class="code">[global] default case = upper</pre></blockquote> <p>If you specify this value, the names of newly created files are translated into uppercase and cannot be overridden in a program. We recommend that you use the default value unless you are dealing with a Windows for Workgroups or other 8.3 client, in which case it should be <tt class="literal">upper</tt>.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-4.2.3"/> <a name="INDEX-112"/><h3 class="head3">preserve case</h3> <p>This option specifies whether a file created by Samba on behalf of the client is created with the case provided by the client operating system or the case specified by the earlier <tt class="literal">default</tt> <tt class="literal">case</tt> configuration option. The default value is <tt class="literal">yes</tt>, which uses the case provided by the client operating system. If it is set to <tt class="literal">no</tt>, the value of the <tt class="literal">default</tt> <tt class="literal">case</tt> option (upper or lower) is used.</p> <p>Note that this option does not handle 8.3 file requests sent from the client—see the upcoming <tt class="literal">short</tt> <tt class="literal">preserve</tt> <tt class="literal">case</tt> option. You might want to set this option to <tt class="literal">yes</tt>, for example, if applications that create files on the Samba server demand the file be all uppercase. If instead you want Samba to mimic the behavior of a Windows NT filesystem, you can leave this option set to its default, <tt class="literal">yes</tt>.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-4.2.4"/> <a name="INDEX-113"/><h3 class="head3">short preserve case</h3> <p>This option specifies whether an 8.3 filename created by Samba on behalf of the client is created with the default case of the client operating system or the case specified by the <tt class="literal">default</tt> <tt class="literal">case</tt> configuration option. The default value is <tt class="literal">yes</tt>, which uses the case provided by the client operating system. You can let Samba choose the case through the <tt class="literal">default</tt> <tt class="literal">case</tt> option by setting it as follows:</p> <blockquote><pre class="code">[global] short preserve case = no</pre></blockquote> <p>If you want to force Samba to mimic the behavior of a Windows NT filesystem, you can leave this option set to its default, <tt class="literal">yes</tt>.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-4.2.5"/> <a name="INDEX-114"/><h3 class="head3">mangled names</h3> <p>This share-level option specifies whether Samba will mangle filenames for 8.3 clients. If the option is set to <tt class="literal">no</tt>, Samba will not mangle the names, and (depending on the client) they will either be invisible or appear truncated to those using 8.3 operating systems. The default value is <tt class="literal">yes</tt>. You can override it per share as follows:</p> <blockquote><pre class="code">[data] mangled names = no</pre></blockquote> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-4.2.6"/> <a name="INDEX-115"/><h3 class="head3">mangle case</h3> <p>This option tells Samba whether it should mangle filenames that are not composed entirely of the case specified using the <tt class="literal">default</tt> <tt class="literal">case</tt> configuration option. The default for this option is <tt class="literal">no</tt>. If you set it to <tt class="literal">yes</tt>, you should be sure that all clients can handle the mangled filenames that result. You can override it per share as follows:</p> <blockquote><pre class="code">[data] mangle case = yes</pre></blockquote> <p>We recommend that you leave this option alone unless you have a well-justified need to change it.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-4.2.7"/> <a name="INDEX-116"/><h3 class="head3">mangling char</h3> <p>This share-level option specifies the mangling character used when Samba mangles filenames into the 8.3 format. The default character used is a tilde (~). You can reset it to whatever character you wish. For instance:</p> <blockquote><pre class="code">[data] mangling char = #</pre></blockquote> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-4.2.8"/> <a name="INDEX-117"/><h3 class="head3">mangled stack</h3> <p>Samba maintains a local stack of recently mangled 8.3 filenames; this stack can be used to reverse-map mangled filenames back to their original state. This is often needed by applications that create and save a file, close it, and need to modify it later. The default number of long filename/mangled filename pairs stored on this stack is 50. However, if you want to cut down on the amount of processor time used to mangle filenames, you can increase the size of the stack to whatever you wish, at the expense of memory and slightly slower file access:</p> <blockquote><pre class="code">[global] mangled stack = 100</pre></blockquote> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-4.2.9"/> <a name="INDEX-118"/><h3 class="head3">mangled map</h3> <p>If the default behavior of name mangling is not sufficient, you can give Samba further instructions on how to behave using the <tt class="literal">mangled</tt> <tt class="literal">map</tt> option. This option allows you to specify mapping patterns that can be used in place of name mangling performed by Samba. For example:</p> <blockquote><pre class="code">[data] mangled map =(*.database *.db) (*.class *.cls)</pre></blockquote> <p>Here, Samba is instructed to search each encountered file for characters that match the first pattern specified in the parenthesis and convert them to the modified second pattern in the parenthesis for display on an 8.3 client. This is useful in the event that name mangling converts the filename incorrectly or converts it to a format that the client cannot understand readily. Patterns are separated by whitespaces. <a name="INDEX-119"/><a name="INDEX-120"/> <a name="INDEX-121"/><a name="INDEX-122"/></p> </div> </div> </div> <div class="sect1"><a name="samba2-CHP-8-SECT-5"/> <h2 class="head1">Locks and Oplocks</h2> <p><a name="INDEX-123"/><a name="INDEX-124"/><a name="INDEX-125"/><a name="INDEX-126"/>Concurrent writes to a single file are not desirable in any operating system. To prevent this, most operating systems use <em class="firstterm">locks</em> to guarantee that only one process can write to a file at a time. Operating systems traditionally lock entire files, although newer ones allow a range of bytes within a file to be locked. If another process attempts to write to a file (or section of one) that is already locked, it receives an error from the operating system and will have to wait until the lock is released.</p> <p>Samba supports the standard DOS and NT filesystem (deny-mode) locking requests—which allow only one process to write to an entire file on a server at a given time—as well as byte-range locking. In addition, Samba supports a locking mechanism known in the Windows NT world as <em class="firstterm">opportunistic locking, </em><a name="INDEX-127"/>or<em class="firstterm"> </em><em class="emphasis">oplock</em> for short.</p> <div class="sect2"><a name="samba2-CHP-8-SECT-5.1"/> <h3 class="head2">Opportunistic Locking</h3> <p>Opportunistic locking allows a client to notify the Samba server that it will not only be the exclusive writer of a file, but will also cache its changes to that file locally to speed up access by reducing network activity. This can result in a large performance gain—typically 30%—while at the same time reserving network bandwidth for other purposes.</p> <p>Because exclusive access can be obtained using regular file locks, the value of opportunistic locks is not so much to lock the file as it is to cache it. In fact, a better name for opportunistic locking might be <em class="firstterm">opportunistic caching</em>.</p> <p>When Samba knows that a file in one of its shares has been oplocked by a client, it marks its version as having an opportunistic lock and waits for the client to complete work on the file, at which point it expects the client to send its changes back to the Samba server for synchronization with the copy on the server.</p> <p>If a second client requests access to that file before the first client has finished working on it, Samba sends an oplock break request to the first client. This tells the client to stop caching its changes and return the current state of the file to the server so that the interrupting client can use it as it sees fit. An opportunistic lock, however, is not a replacement for a standard deny-mode lock. It is not unheard of for the interrupting process to be granted an oplock break only to discover that the original process also has a deny-mode lock on a file as well. <a href="ch08.html#samba2-CHP-8-FIG-11">Figure 8-11</a> illustrates this <a name="INDEX-128"/>opportunistic locking process.</p> <div class="figure"><a name="samba2-CHP-8-FIG-11"/><img src="figs/sam2_0811.gif"/></div><h4 class="head4">Figure 8-11. Opportunistic locking</h4> <p>In most cases, the extra performance resulting from the use of oplocks is highly desirable. However, allowing the client to cache data can be a big risk if either the client or network hardware are unreliable. Suppose a client opens a file for writing, creating an oplock on it. When another client also tries to open the file, an oplock break request is sent to the first client. If this request goes unfulfilled for any reason and the second client starts writing to the file, the file can be easily corrupted as a result of the two processes writing to it concurrently. Unfortunately, this scenario is very real. Uncoordinated behavior such as this has been observed many times among Windows clients in SMB networks (with files served by Windows NT/2000 or Samba). Typically, the affected files are database files, which multiple clients open concurrently for writing.</p> <p>A more concrete example of <a name="INDEX-129"/>oplock failure occurs when database files are very large. If a client is allowed to oplock this kind of file, there can be a huge delay while the client copies the entire file from the server to cache it, even though it might need to update only one record. The situation goes from bad to worse when another client tries to open the oplocked file. The first client might need to write the entire file back to the server before the second client's file open request can succeed. This results in another huge delay (for both clients), which in practice often results in a failed open due to a timeout on the second client, perhaps along with a message warning of possible database corruption!</p> <p>If you are having problems of this variety, you can turn off oplocks for the affected files by using the <tt class="literal">veto</tt><a name="INDEX-130"/> <tt class="literal">oplock</tt> <tt class="literal">files</tt> parameter:</p> <blockquote><pre class="code">[dbdata] veto oplock files = /*.dbm/</pre></blockquote> <p>Use the value of the parameter (a list of filename-matching patterns separated by slash characters) to match all the files in the share that might be a source of trouble. The syntax of this parameter is similar to that of the <tt class="literal">veto</tt> <tt class="literal">files</tt> parameter.</p> <p>If you want to be really careful and can live with reduced performance, you can turn off oplocks altogether, preventing the oplock break problem from ever occurring:</p> <blockquote><pre class="code">[global] oplocks = no</pre></blockquote> <p>This disables oplocks for all files in all shares served by the Samba server. If you wish to disable oplocks in just a specific share, you can specify the <tt class="literal">oplocks</tt> <tt class="literal">=</tt> <tt class="literal">no</tt> parameter in just that share:</p> <blockquote><pre class="code">[database] oplocks = no</pre></blockquote> <p>This example allows other shares, which might have less sensitive data, to attain better performance, while trading performance for better data integrity for files in the <tt class="literal">[database]</tt> share.</p> </div> <div class="sect2"><a name="samba2-CHP-8-SECT-5.2"/> <h3 class="head2">Unix and Oplocks</h3> <p><a name="INDEX-131"/>Most of the time, oplocks help Windows client systems cooperate to avoid overwriting each other's changes. Unix systems also have file-locking mechanisms to allow Unix processes to cooperate with each other. But if a file stored on a Samba system is accessed by both a Windows network client and a local Unix process—without an additional coordination between the two systems—the Unix process could easily ride roughshod over an oplock.</p> <p>Some Unix systems have enhanced kernels that understand the Windows oplocks maintained by Samba. Currently the support exists only in SGI Irix and Linux.</p> <p>If you leave oplocks enabled and your Unix system does not support kernel oplocks, you could end up with corrupted data when somebody runs a Unix process that reads or writes a file that Windows users also access. This is another case where the <tt class="literal">veto</tt><a name="INDEX-132"/> <tt class="literal">oplock</tt> <tt class="literal">files</tt> parameter can be used, assuming you can anticipate which Samba files are used by both Windows users and Unix users. For example, suppose the <tt class="literal">[usrfiles]</tt> share contains some ASCII text files with the <em class="filename">.txt</em> filename extension and OpenOffice word processor documents with the <em class="filename">.doc</em> filename extension, which Unix and Windows users both modify. We can use <tt class="literal">veto</tt> <tt class="literal">oplock</tt> <tt class="literal">files</tt> like this:</p> <blockquote><pre class="code">[usrfiles] veto oplock files = /*.txt/*.doc/</pre></blockquote> <p>This will suppress the use of oplocks on <em class="filename">.txt</em> and <em class="filename">.doc</em> files, which will suppress client caching, while allowing the Windows and Unix programs to use regular file locking to prevent concurrent writes to the same file.</p> </div> <div class="sect2"><a name="samba2-CHP-8-SECT-5.3"/> <h3 class="head2">Locks and Oplocks Configuration Options</h3> <p><a name="INDEX-133"/><a name="INDEX-134"/>Samba's options for locks and oplocks are given in <a href="ch08.html#samba2-CHP-8-TABLE-6">Table 8-6</a>.</p> <a name="samba2-CHP-8-TABLE-6"/><h4 class="head4">Table 8-6. Locks and oplocks configuration options</h4><table border="1"> <tr> <th> <p>Option</p> </th> <th> <p>Parameters</p> </th> <th> <p>Function</p> </th> <th> <p>Default</p> </th> <th> <p>Scope</p> </th> </tr> <tr> <td> <p><tt class="literal">locking</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>If <tt class="literal">yes</tt>, turns on byte-range locks.</p> </td> <td> <p><tt class="literal">yes</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">strict</tt> <tt class="literal">locking</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>If <tt class="literal">yes</tt>, denies access to an entire file if a byte-range lock exists in it.</p> </td> <td> <p><tt class="literal">no</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">posix locking</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>If <tt class="literal">yes</tt>, maps oplocks to POSIX locks on the local system.</p> </td> <td> <p><tt class="literal">yes</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">oplocks</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>If <tt class="literal">yes</tt>, turns on local caching of files on the client for this share.</p> </td> <td> <p><tt class="literal">yes</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">kernel</tt> <tt class="literal">oplocks</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>If <tt class="literal">yes</tt>, indicates that the kernel supports oplocks.</p> </td> <td> <p><tt class="literal">yes</tt></p> </td> <td> <p>Global</p> </td> </tr> <tr> <td> <p><tt class="literal">level2 oplocks</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>If <tt class="literal">yes</tt>, allows oplocks to downgrade to read-only.</p> </td> <td> <p><tt class="literal">yes</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">fake oplocks</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>If <tt class="literal">yes</tt>, tells client the lock was obtained, but doesn't actually lock it.</p> </td> <td> <p><tt class="literal">no</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">blocking</tt> <tt class="literal">locks</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>Allows lock requestor to wait for the lock to be granted.</p> </td> <td> <p><tt class="literal">yes</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">veto oplock</tt> <tt class="literal">files</tt></p> </td> <td> <p>string (list of filenames)</p> </td> <td> <p>Does not oplock specified files.</p> </td> <td> <p>None</p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">lock</tt> <tt class="literal">directory</tt></p> </td> <td> <p>string (fully qualified pathname)</p> </td> <td> <p>Sets the location where various Samba files, including locks, are stored.</p> </td> <td> <p>As specified in Samba makefile</p> </td> <td> <p>Global</p> </td> </tr> </table> <div class="sect3"><a name="samba2-CHP-8-SECT-5.3.1"/> <h3 class="head3">locking</h3> <p>The <tt class="literal">locking</tt><a name="INDEX-135"/> option can be used to tell Samba to engage or disengage server-side byte-range locks on behalf of the client. Samba implements byte-range locks on the server side with normal Unix advisory locks and consequently prevents other properly behaved Unix processes from overwriting a locked byte range.</p> <p>This option can be specified per share as follows:</p> <blockquote><pre class="code">[accounting] locking = yes</pre></blockquote> <p>If the <tt class="literal">locking</tt> option is set to <tt class="literal">yes</tt>, the requestor is delayed until the holder of either type of lock releases it (or crashes). If, however, the option is set to <tt class="literal">no</tt>, no byte-range locks are kept for the files, although requests to lock and unlock files will appear to succeed. The option is set to <tt class="literal">yes</tt> by default; however, you can turn this option off if you have read-only media.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-5.3.2"/> <a name="INDEX-136"/><h3 class="head3">strict locking</h3> <p>This option checks every file access for a byte-range lock on the range of bytes being accessed. This is typically not needed if a client adheres to all the locking mechanisms in place. This option is set to <tt class="literal">no</tt> by default; however, you can reset it per share as follows:</p> <blockquote><pre class="code">[accounting] strict locking = yes</pre></blockquote> <p>If this option is set to <tt class="literal">yes</tt>, mandatory locks are enforced on any file with byte-range locks.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-5.3.3"/> <a name="INDEX-137"/><h3 class="head3">posix locking</h3> <p>On systems that support POSIX locking, Samba automatically maps oplocks to POSIX locks. This behavior can be disabled by setting <tt class="literal">posix</tt> <tt class="literal">locking</tt> <tt class="literal">=</tt> <tt class="literal">no</tt>. You should never need to change the default behavior, which is <tt class="literal">posix</tt> <tt class="literal">locking</tt> <tt class="literal">=</tt> <tt class="literal">yes</tt>.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-5.3.4"/> <a name="INDEX-138"/><h3 class="head3">oplocks</h3> <p>This option enables or disables support for oplocks on the client. The option is enabled by default. However, you can disable it with the following command:</p> <blockquote><pre class="code">[data] oplocks = no</pre></blockquote> <p>If you are in an extremely unstable network environment or have many clients that cannot take advantage of opportunistic locking, it might be better to shut this Samba feature off. If the host operating system does not support kernel oplocks, oplocks should be disabled if users are accessing the same files from both Unix applications (such as <em class="emphasis">vi</em>) and SMB clients.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-5.3.5"/> <a name="INDEX-139"/><h3 class="head3">kernel oplocks</h3> <p>If a Unix application on the Samba host system (that is not part of the Samba suite) tries to open a file for writing that Samba has oplocked to a Windows client, it is likely to succeed (depending on the operating system), and both Samba and the client are never aware of it.</p> <p>Some versions of Unix have support for oplocks in the kernel that can work along with Samba's oplocks. In this case, the Unix process trying to open the file is suspended while Samba directs the client to write its copy back. After that has happened, the operating system allows the open to complete. At the time of this writing, this feature is supported only by SGI Irix and Linux.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-5.3.6"/> <a name="INDEX-140"/><h3 class="head3">level2 oplocks</h3> <p>Windows NT/2000/XP clients can downgrade their read-write oplocks to read-only oplocks when another client opens the same file. This can result in significant improvements in performance on files that are written infrequently or not at all—especially executables—because all clients can then maintain a read-ahead cache for the file. By default, <tt class="literal">level2</tt> <tt class="literal">oplocks</tt> is set to <tt class="literal">yes</tt>, and you probably won't need to change it.</p> <p>Currently, Samba cannot support level 2 oplocks along with kernel oplocks and automatically disables level 2 oplocks when kernel oplocks are in use. (This might change in future releases as improved support for oplocks is added by the Samba developers.) If you are running Samba on a host system that supports kernel oplocks, you must set <tt class="literal">kernel</tt> <tt class="literal">oplocks</tt> <tt class="literal">=</tt> <tt class="literal">no</tt> to enable support for level 2 oplocks.</p> <p>Disabling oplocks with <tt class="literal">oplocks</tt> <tt class="literal">=</tt> <tt class="literal">no</tt> also disables level 2 oplocks.</p> <p>Samba can automatically detect its Unix host's support of kernel oplocks and will set the value of <tt class="literal">kernel</tt> <tt class="literal">oplocks</tt> automatically. You should never need to set this option in your Samba configuration file.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-5.3.7"/> <a name="INDEX-141"/><h3 class="head3">fake oplocks</h3> <p>When this option is set to <tt class="literal">yes</tt>, Samba pretends to allow oplocks rather than actually supporting them. If this option is enabled on a read-only share (such as a shared CD-ROM drive), all clients are told that the files are available for opportunistic locking and never warned of simultaneous access. As a result, Windows clients cache more of the file's data and obtain much better performance.</p> <p>This option was added to Samba before opportunistic-locking support was available, and it is now generally considered better to use real oplocks. Do not ever enable <tt class="literal">fake</tt> <tt class="literal">oplocks</tt> on a read/write share.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-5.3.8"/> <h3 class="head3">blocking locks</h3> <p>Samba also supports <em class="firstterm">blocking locks</em>, a minor variant of range locks. Here, if the range of bytes is not available, the client specifies an amount of time that it's willing to wait. The server then caches the lock request, periodically checking to see if the file is available. If it is, it notifies the client; however, if time expires, Samba will tell the client that the request has failed. This strategy prevents the client from continually polling to see if the lock is available.</p> <p>You can disable this option per share as follows:</p> <blockquote><pre class="code">[accounting] blocking locks = no</pre></blockquote> <p>When set to <tt class="literal">yes</tt>, blocking locks are enforced on the file. If this option is set to <tt class="literal">no</tt>, Samba behaves as if normal locking mechanisms are in place on the file. The default is <tt class="literal">yes</tt>.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-5.3.9"/> <a name="INDEX-142"/><h3 class="head3">veto oplock files</h3> <p>You can provide a list of filenames that are never granted opportunistic locks with the <tt class="literal">veto</tt> <tt class="literal">oplock</tt> <tt class="literal">files</tt> option. This option can be set either globally or on a per-share basis. For example:</p> <blockquote><pre class="code">veto oplock files = /*.bat/*.htm/</pre></blockquote> <p>The value of this option is a series of patterns. Each pattern entry must begin, end, or be separated from another with a slash ( / ) character, even if only one pattern is listed. Asterisks can be used as a wildcard to represent zero or more characters. Questions marks can be used to represent exactly one character.</p> <p>We recommend that you disable oplocks on any files that are meant to be updated by Unix or are intended for simultaneous sharing by several processes.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-5.3.10"/> <a name="INDEX-143"/><h3 class="head3">lock directory</h3> <p>This option (sometimes called <tt class="literal">lock</tt> <tt class="literal">dir</tt>) specifies the location of a directory where Samba will store SMB deny-mode lock files. Samba stores other files in this directory as well, such as browse lists and its shared memory file. If WINS is enabled, the WINS database is written to this directory as well. The default for this option is specified in the Samba makefile; it is typically <em class="filename">/usr/local/samba/var/locks</em>. You can override this location as follows:</p> <blockquote><pre class="code">[global] lock directory = /usr/local/samba/locks</pre></blockquote> <p>You typically would not need to override this option, unless you want to move the lock files to a more standard location, such as <em class="filename">/var/spool/locks</em>. <a name="INDEX-144"/> <a name="INDEX-145"/><a name="INDEX-146"/></p> </div> </div> </div> <div class="sect1"><a name="samba2-CHP-8-SECT-6"/> <h2 class="head1">Connection Scripts</h2> <p><a name="INDEX-147"/><a name="INDEX-148"/><a name="INDEX-149"/>Samba supports a mechanism called <em class="firstterm">connection scripts</em>, by which commands can be executed on the server as clients connect to a share or later disconnect from it. By using configuration file variables along with some custom programming, you can create connection scripts that perform a wide range of functions. As a simple example, here is a "quick and dirty" way to monitor connections to shares on the Samba server in real time. First, the value of the <tt class="literal">preexec</tt><a name="INDEX-150"/> parameter is set as follows:</p> <blockquote><pre class="code">[global] preexec = /bin/echo %u at %m connected to //%L/%S on %T >>/tmp/smblog</pre></blockquote> <p>This causes information about the user and the connection to be written to the file <em class="filename">/tmp/smblog</em> whenever any client connects to any share. To watch clients connect, run the following command:</p> <blockquote><pre class="code">$ <tt class="userinput"><b>tail -f /tmp/smblog</b></tt> jay at maya connected to //toltec/data on 2002/11/21 21:21:15 david at apache connected to //toltec/techs on 2002/11/21 21:21:57 sally at seminole connected to //toltec/payroll on 2002/11/21 21:22:16 martha at dine connected to //toltec/profiles on 2002/11/21 21:23:38 martha at dine connected to //toltec/netlogon on 2002/11/21 21:23:39 martha at dine connected to //toltec/martha on 2002/11/21 21:23:40 aaron at huastec connected to //toltec/netlogon on 2002/11/21 21:24:19 aaron at huastec connected to //toltec/aaron on 2002/11/21 21:24:20</pre></blockquote> <p>With the <em class="emphasis">-f</em> option, the <em class="emphasis">tail</em> command monitors <em class="filename">/tmp/smblog</em> and prints additional output as new data is appended to the file. Every time a new connection is made, an additional line is printed, showing the output of the <tt class="literal">preexec</tt> command. Notice the lines resulting from connections by user <tt class="literal">martha</tt> and <tt class="literal">aaron</tt>. User <tt class="literal">martha</tt> logged on to the domain from a Windows NT client, which accessed the <tt class="literal">[profiles]</tt> share to download her profile, then the <tt class="literal">[netlogon]</tt> share to read the logon script, and then her home directory (because her logon script contains a <tt class="literal">net</tt> <tt class="literal">use</tt> <tt class="literal">H</tt>: <tt class="literal">/home</tt> command) to connect her home directory to drive letter H. The connections from <tt class="literal">aaron</tt> are similar, except that he connected from a Windows 98 system, which does not use the <tt class="literal">[profiles]</tt> share. (See <a href="ch04.html">Chapter 4</a> for more information about domain logons.)</p> <p>A more advanced use of <a name="INDEX-151"/><a name="INDEX-152"/>connection scripts is to monitor the contents of users' home directories and/or other shared directories and perform checks ensuring that local administrative policies are followed. Checked items might include the following:</p> <ul><li> <p>Disk usage, on a per-share, per-directory, or per-file basis</p> </li><li> <p>Types of files stored on the server</p> </li><li> <p>Whether filenames follow naming guidelines</p> </li><li> <p>Whether viruses have copied themselves to the Samba server</p> </li></ul> <p>To handle this kind of task, a shell script or other program would be written to perform the checks and take appropriate actions, such as removing offending files. The <tt class="literal">root</tt> <tt class="literal">preexec</tt> parameter would be used to run the command as the root user, using configuration file variables to pass arguments. For example:</p> <blockquote><pre class="code">[homes] root preexec = admin_checks %S root preexec close = yes</pre></blockquote> <p>In this example, a specially written administrative checking program (<em class="emphasis">admin_checks</em>) is used to monitor users' home directories on the Samba server. The <tt class="literal">%S</tt> variable is used to pass the name of the home directory to the script. The <tt class="literal">root</tt><a name="INDEX-153"/> <tt class="literal">preexec</tt> <tt class="literal">close</tt> parameter has been set to <tt class="literal">yes</tt> so that if <em class="emphasis">admin_checks</em> detects a serious violation of local policy, it can exit with a nonzero status, and the client is prevented from connecting.</p> <div class="sect2"><a name="samba2-CHP-8-SECT-6.1"/> <h3 class="head2">Connection Script Options</h3> <p><a href="ch08.html#samba2-CHP-8-TABLE-7">Table 8-7</a> introduces some of the configuration options provided for setting up users.</p> <a name="samba2-CHP-8-TABLE-7"/><h4 class="head4">Table 8-7. Connection script options</h4><table border="1"> <tr> <th> <p>Option</p> </th> <th> <p>Parameters</p> </th> <th> <p>Function</p> </th> <th> <p>Default</p> </th> <th> <p>Scope</p> </th> </tr> <tr> <td> <p><tt class="literal">root preexec</tt></p> </td> <td> <p>string (Unix command)</p> </td> <td> <p>Sets a Unix command to run as <tt class="literal">root</tt>, before connecting to the share.</p> </td> <td> <p>None</p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">root preexec close</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>If set to <tt class="literal">yes</tt>, nonzero exit status of <tt class="literal">root preexec</tt> command will disconnect.</p> </td> <td> <p><tt class="literal">no</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">preexec</tt> <tt class="literal">(exec)</tt></p> </td> <td> <p>string (Unix command)</p> </td> <td> <p>Sets a Unix command to run as the user before connecting to the share.</p> </td> <td> <p>None</p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">preexec close</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>If set to <tt class="literal">yes</tt>, nonzero exit status of <tt class="literal">preexec</tt> command will disconnect.</p> </td> <td> <p><tt class="literal">no</tt></p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">postexec</tt></p> </td> <td> <p>string (Unix command)</p> </td> <td> <p>Sets a Unix command to run as the user after disconnecting from the share.</p> </td> <td> <p>None</p> </td> <td> <p>Share</p> </td> </tr> <tr> <td> <p><tt class="literal">root</tt> <tt class="literal">postexec</tt></p> </td> <td> <p>string (Unix command)</p> </td> <td> <p>Sets a Unix command to run as <tt class="literal">root</tt> after disconnecting from the share.</p> </td> <td> <p>None</p> </td> <td> <p>Share</p> </td> </tr> </table> <div class="sect3"><a name="samba2-CHP-8-SECT-6.1.1"/> <a name="INDEX-156"/><h3 class="head3">root preexec</h3> <p>This option specifies as its value a Unix command to be run <em class="emphasis">as the root user</em> before any connection to a share is completed. You should use this option specifically for performing actions that require root privilege.</p> <p>To ensure security, users should never be able to modify the target of the <tt class="literal">root</tt> <tt class="literal">preexec</tt> command. In addition, unless you explicitly redirect it, any information the command sends to standard output will be discarded. If you intend to use any <tt class="literal">preexec</tt> or <tt class="literal">postexec</tt> script, you should ensure that it will run correctly before having Samba invoke it.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-6.1.2"/> <a name="INDEX-157"/><h3 class="head3">root preexec close</h3> <p>Sometimes you might want the share to disconnect if the <tt class="literal">root</tt> <tt class="literal">preexec</tt> script fails, giving the client an error rather than allowing it to connect. For example, if you are using <tt class="literal">root</tt> <tt class="literal">preexec</tt> to mount a CD-ROM or filesystem, it would make no sense to connect the client to it in the event that the mount fails. If you specify <tt class="literal">root</tt> <tt class="literal">preexec</tt> <tt class="literal">close</tt> <tt class="literal">=</tt> <tt class="literal">yes</tt>, the share will fail to connect if the <tt class="literal">root</tt> <tt class="literal">preexec</tt> script returns a nonzero exit status.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-6.1.3"/> <a name="INDEX-158"/><h3 class="head3">preexec</h3> <p>Sometimes just called <tt class="literal">exec</tt>, this option defines an ordinary unprivileged command run by Samba as the user specified by the variable <tt class="literal">%u</tt>. For example, a common use of this option is to perform logging, such as the following:</p> <blockquote><pre class="code">[homes] preexec = echo "%u connected from %m (%I)\" >>/tmp/.log</pre></blockquote> <p>You must redirect the standard output of the command if you want to use it. Otherwise, it is discarded. This warning also applies to the command's standard error output. If you intend to use a <tt class="literal">preexec</tt> script, you should ensure that it will run correctly before having Samba invoke it.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-6.1.4"/> <a name="INDEX-159"/><h3 class="head3">preexec close</h3> <p>This is similar to <tt class="literal">root</tt> <tt class="literal">preexec</tt> <tt class="literal">close</tt>, except that it goes with the <tt class="literal">preexec</tt> option. By setting <tt class="literal">preexec</tt> <tt class="literal">close</tt> <tt class="literal">=</tt> <tt class="literal">yes</tt>, a <tt class="literal">preexec</tt> script that returns nonzero will cause the share to disconnect immediately.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-6.1.5"/> <a name="INDEX-160"/><h3 class="head3">postexec</h3> <p>Once the user disconnects from the share, the command specified with <tt class="literal">postexec</tt> is run as the user on the Samba server to do any necessary cleanup. This option is essentially the same as the <tt class="literal">preexec</tt> option. Again, remember that the command is run as the user represented by <tt class="literal">%u</tt>, and any information sent to standard output will be ignored.</p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-6.1.6"/> <a name="INDEX-161"/><h3 class="head3">root postexec</h3> <p>Following the <tt class="literal">postexec</tt> option, the <tt class="literal">root</tt> <tt class="literal">postexec</tt> command is run, if one has been specified. Again, this option specifies as its value a Unix command to be run <em class="emphasis">as the root user</em> before disconnecting from a share. You should use this option specifically for performing actions that require root privilege. <a name="INDEX-162"/> <a name="INDEX-163"/><a name="INDEX-164"/></p> </div> </div> </div> <div class="sect1"><a name="samba2-CHP-8-SECT-7"/> <h2 class="head1">Microsoft Distributed Filesystems</h2> <p><a name="INDEX-165"/>In a large network where many shared folders are spread out over a large number of servers, it can be difficult for users to locate the resources they are trying to find. Browsing through Network Neighborhood or My Network Places can become an ordeal rather than a time-saving convenience. To mitigate this problem, Microsoft added an extension to file sharing called <em class="firstterm">Distributed filesystem</em><a name="INDEX-166"/><a name="INDEX-167"/> (Dfs). Using Dfs, it is possible to organize file shares on the network so that they appear to users as organized in a single directory tree on a single server, regardless of which servers on the network actually contain the resources. Instead of having to browse the entire network, users can go to the Dfs share and locate their data much more easily.</p> <p>Dfs can also help administrators because it provides a level of indirection between the name of a shared folder and its actual location. The Dfs share contains references to resources on the network, and when a resource is accessed, the Dfs server hands the client off to the actual server of the resource. When moving resources to another computer, the reference to the resource in the Dfs share can be redirected to the new location in one step, with the change being entirely seamless for users.</p> <p>To a limited extent, Dfs also can help improve performance for read-only shares because it provides <a name="INDEX-168"/>load balancing. It is possible to set up a Dfs reference to point to identical shares on two or more servers. The Dfs server then divides requests between the servers, dividing the client load among them. However, this works well only for static, read-only data because no provision is included in Dfs for synchronization among the servers when changes are made on any of them.</p> <div class="sect2"><a name="samba2-CHP-8-SECT-7.1"/> <h3 class="head2">Windows Dfs Clients</h3> <p><a name="INDEX-169"/>Modern versions of Windows come with client-side support for Dfs, and no extra configuration is required. Support is more limited for older versions, however. Windows for Workgroups cannot function as a Dfs client at all. Windows NT 4.0 must be upgraded to at least Service Pack 3 to act as a Dfs client, and the Dfs Client must be installed. Later service packs (such as Service Pack 6) include the Dfs Client. Windows 95 must also have the Dfs Client software installed to act as a Dfs client. Without the Dfs Client software, double-clicking a remote folder in a Dfs share will show an empty folder, and no error message will appear.</p> <a name="samba2-CHP-8-NOTE-140"/><blockquote class="note"><h4 class="objtitle">TIP</h4> <p>To use the Dfs Client for Windows 95 or Windows NT, you must first download and install it. See the web page <a href="http://microsoft.com/ntserver/nts/downloads/winfeatures/NTSDistrFile/default.asp">http://microsoft.com/ntserver/nts/downloads/winfeatures/NTSDistrFile/default.asp</a> for a link to download the installation program and instructions on how to install the Dfs Client.</p> </blockquote> </div> <div class="sect2"><a name="samba2-CHP-8-SECT-7.2"/> <h3 class="head2">Configuring Samba for Dfs</h3> <p><a name="INDEX-170"/>To act as a Dfs server, Samba 2.2 must be compiled with the <tt class="literal">--with-msdfs</tt> configure option. (See <a href="ch02.html">Chapter 2</a> for instructions on configuring and compiling Samba.) Samba 3.0 includes Dfs support by default and does not need to be compiled with the <tt class="literal">--with-msdfs</tt> configure option.</p> <p>Once a Dfs-enabled Samba server is running, there are just two steps to serving a Dfs share. First we will set up a Dfs root directory on the server, and then we will modify the <em class="filename">smb.conf</em> configuration file to enable the share.</p> <div class="sect3"><a name="samba2-CHP-8-SECT-7.2.1"/> <h3 class="head3">Setting up the Dfs root</h3> <p>First we need to create a directory to act as the Dfs root:</p> <blockquote><pre class="code"># <tt class="userinput"><b>mkdir /usr/local/samba/dfs</b></tt></pre></blockquote> <p>This can be any directory, but it is important that it be owned by root and given the proper permissions:</p> <blockquote><pre class="code"># <tt class="userinput"><b>chown root:root /usr/local/samba/dfs</b></tt> # <tt class="userinput"><b>chmod 755 /usr/local/samba/dfs</b></tt></pre></blockquote> <p>The Dfs directory tree can have subdirectories and files, just like any other shared directory. These will function just as they would in any other share, allowing clients to access the directories and files on the Samba server. The whole idea of Dfs, though, is to gather together shares on other servers by making references to them in the Dfs tree. The way this is implemented with Samba involves a clever use of symbolic links, which can be in the Dfs root directory or any subdirectory in the Dfs tree.</p> <p>You are probably familiar with using symbolic links to create references to files that exist on the same system, and perhaps crossing a local filesystem boundary (which ordinary Unix links cannot do). But maybe you didn't know that symbolic links have a more general functionality. Although we can't display its contents directly, as we could with a text or binary file, a symbolic link "contains" an ASCII text string naming what the link points to. For example, take a look at the listing for these symbolic links:</p> <blockquote><pre class="code">$ <tt class="userinput"><b>ls -l wrdlnk alnk</b></tt> lrwxrwxrwx 1 jay jay 15 Mar 14 06:50 wrdlnk -> /usr/dict/words lrwxrwxrwx 1 jay jay 9 Mar 14 06:53 alnk -> dreamtime</pre></blockquote> <p>As you can infer from the size of the <em class="filename">wrdlnk</em> link (15 bytes), the string <tt class="literal">/usr/dict/words</tt> is encoded into it. The size of <em class="filename">alnk</em> (9 bytes) is smaller, corresponding to the shorter name of <em class="filename">dreamtime</em>.</p> <p>Now let's create a link in our Dfs root for an SMB share:</p> <blockquote><pre class="code"># <tt class="userinput"><b>cd /usr/local/samba/dfs</b></tt> # <tt class="userinput"><b>ln -s 'msdfs:maya\e' maya-e</b></tt> # <tt class="userinput"><b>ls -l maya-e</b></tt> lrwxrwxrwx 1 root root 12 Mar 13 17:34 maya-e -> msdfs:maya\e</pre></blockquote> <p>This link might appear as a "broken" link in a directory listing because it points to something that isn't a file on the local system. For example, the <em class="emphasis">file</em> command will report:</p> <blockquote><pre class="code">$ <tt class="userinput"><b>file maya-e</b></tt> maya-e: broken symbolic link to msdfs:maya\e</pre></blockquote> <p>However, <em class="filename">maya-e</em> is a valid reference to the <em class="filename">\\maya\e</em> share when used with Samba's Dfs support. When Samba encounters this file, it sees the leading <tt class="literal">msdfs</tt>: and interprets the rest as the name of a remote share. The client is then redirected to the remote share.</p> <p>When creating links in the Dfs root directory, simply follow the same format, which in general is <tt class="literal">msdfs</tt>:<em class="replaceable">server</em>\<em class="replaceable">share</em>. Note that this is similar to a UNC appended onto the <tt class="literal">msdfs</tt>: string, except that in this case, the two backslashes preceding the server's name are omitted.</p> <a name="samba2-CHP-8-NOTE-141"/><blockquote class="note"><h4 class="objtitle">TIP</h4> <p>The names for the symbolic links in Dfs shares must be in all lowercase.</p> </blockquote> <p>In addition to regular network shares, you can use symbolic links of this type to reference Dfs shares on other Dfs servers. However, referencing printer shares does not work. Dfs is for sharing files only. <a name="INDEX-171"/></p> </div> <div class="sect3"><a name="samba2-CHP-8-SECT-7.2.2"/> <h3 class="head3">Load balancing</h3> <p><a name="INDEX-172"/>To set up a load-balancing Dfs share, create the symbolic link like this:</p> <blockquote><pre class="code"># <tt class="userinput"><b>ln -s 'msdfs:toltec\data,msdfs:mixtec\data' lb-data</b></tt></pre></blockquote> <p>That is, simply use a list of shares separated by commas as the reference. Remember, it is up to you to make sure the shared folders remain identical. Set up permissions on the servers to make the shares read-only to users.</p> <p>The last thing we need to do is to modify the <em class="filename">smb.conf</em> file to define the Dfs root share and add Dfs support. The Dfs root is added as a share definition:</p> <a name="INDEX-173"/><blockquote><pre class="code">[dfs] path = /usr/local/samba/dfs msdfs root = yes</pre></blockquote> <p>You can use any name you like for the share. The path is set to the Dfs root directory we just set up, and the parameter <tt class="literal">msdfs</tt> <tt class="literal">root</tt> <tt class="literal">=</tt> <tt class="literal">yes</tt> tells Samba that this share is a Dfs root.</p> <p>To enable support for Dfs in the server, we need to add one line to the <tt class="literal">[global]</tt> section:</p> <a name="INDEX-174"/><blockquote><pre class="code">[global] host msdfs = yes</pre></blockquote> <p>Restart the Samba daemons—or just wait a minute for them to reread the configuration file—and you will see the new share from Windows clients. If you have trouble accessing any of the remote shares in the Dfs share, recheck your symbolic links to make sure they were created correctly. <a name="INDEX-175"/></p> <a name="samba2-CHP-8-NOTE-142"/><blockquote class="note"><h4 class="objtitle">TIP</h4> <p>If you previously had a share by the same name as your Dfs share, you might need to reboot Windows clients before they can access the share as a Dfs share.</p> </blockquote> </div> </div> </div> <div class="sect1"><a name="samba2-CHP-8-SECT-8"/> <h2 class="head1">Working with NIS</h2> <p>In networks where NIS and NFS are in use, it is common for users' home directories to be mounted over the network by NFS. If a Samba server being used to authenticate user logons is running on a system with NFS-mounted home directories shared with a <tt class="literal">[homes]</tt> share, the additional overhead can result in poor performance—about 30% of normal Samba speed.</p> <p>Samba has the ability to work with <a name="INDEX-176"/>NIS and NIS+ to find the server on which the home directories actually reside so that they can be shared directly from that server. For this to work, the server that holds the home directories must also have Samba running, with a <tt class="literal">[homes]</tt> share of its own.</p> <div class="sect2"><a name="samba2-CHP-8-SECT-8.1"/> <h3 class="head2">NIS Configuration Options</h3> <p><a href="ch08.html#samba2-CHP-8-TABLE-8">Table 8-8</a> introduces the <a name="INDEX-177"/><a name="INDEX-178"/>NIS configuration options specifically for setting up users.</p> <a name="samba2-CHP-8-TABLE-8"/><h4 class="head4">Table 8-8. NIS options</h4><table border="1"> <tr> <th> <p>Option</p> </th> <th> <p>Parameters</p> </th> <th> <p>Function</p> </th> <th> <p>Default</p> </th> <th> <p>Scope</p> </th> </tr> <tr> <td> <p><tt class="literal">nis homedir</tt></p> </td> <td> <p>Boolean</p> </td> <td> <p>If <tt class="literal">yes</tt>, uses NIS instead of <em class="filename">/etc/passwd</em> to look up the path of a user's home directory.</p> </td> <td> <p><tt class="literal">no</tt></p> </td> <td> <p>Global</p> </td> </tr> <tr> <td> <p><tt class="literal">homedir map</tt></p> </td> <td> <p>string (NIS map name)</p> </td> <td> <p>Sets the NIS map to use to look up a user's home directory.</p> </td> <td> <p>None</p> </td> <td> <p>Global</p> </td> </tr> </table> <div class="sect3"><a name="samba2-CHP-8-SECT-8.1.1"/> <h3 class="head3">nis homedir, homedir map</h3> <p>The <tt class="literal">nis</tt><a name="INDEX-179"/> <tt class="literal">homedir</tt> and <tt class="literal">homedir</tt><a name="INDEX-180"/> <tt class="literal">map</tt> options are for Samba servers on network sites where Unix home directories are provided using NFS, the automounter, and NIS.</p> <p>The <tt class="literal">nis</tt> <tt class="literal">homedir</tt> option indicates that the home-directory server for the user needs to be looked up in NIS. The <tt class="literal">homedir</tt> <tt class="literal">map</tt> option tells Samba in which NIS map to look for the server that has the user's home directory. The server needs to be a Samba server so that the client can do an SMB connect to it, and the other Samba servers need to have NIS installed so that they can do the lookup.</p> <p>For example, if user <tt class="literal">joe</tt> asks for a share called <tt class="literal">[joe]</tt>, and the <tt class="literal">nis</tt> <tt class="literal">homedir</tt> option is set to <tt class="literal">yes</tt>, Samba will look in the file specified by <tt class="literal">homedir</tt> <tt class="literal">map</tt> for a home directory for <tt class="literal">joe</tt>. If it finds one, Samba will return the associated system name to the client. The client will then try to connect to that machine and get the share from there. Enabling NIS lookups looks like the following:</p> <blockquote><pre class="code">[globals] nis homedir = yes homedir map = amd.map</pre></blockquote> </div> </div> </div> <hr/><h4 class="head4">Footnotes</h4><blockquote><a name="FOOTNOTE-1"/> <p><a href="#FNPTR-1">[1]</a> The system checkbox will probably be grayed for your file. Don't worry about that—you should still be able to see when the box is checked and when it isn't.</p> </blockquote><hr/><h4 class="head4"><a href="toc.html">TOC</a></h4></body></html>