diff options
Diffstat (limited to 'docs/htmldocs/using_samba/ch08.html')
| -rw-r--r-- | docs/htmldocs/using_samba/ch08.html | 3744 |
1 files changed, 3744 insertions, 0 deletions
diff --git a/docs/htmldocs/using_samba/ch08.html b/docs/htmldocs/using_samba/ch08.html new file mode 100644 index 0000000000..001a86a4a3 --- /dev/null +++ b/docs/htmldocs/using_samba/ch08.html @@ -0,0 +1,3744 @@ +<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> |