--- /dev/null
+<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>
projects / samba / blobdiff