2 <body bgcolor="#ffffff">
4 <img src="samba2_xs.gif" border="0" alt=" " height="100" width="76"
5 hspace="10" align="left" />
7 <h1 class="head0">Chapter 8. Advanced Disk Shares</h1>
10 <p>This chapter continues our discussion of configuring Samba from <a href="ch06.html">Chapter 6</a>. We will cover some more advanced issues
11 regarding the integration of Unix and Windows filesystems, including
12 hidden files, Unix links, file permissions, name mangling, case
13 sensitivity of filenames, file locking, opportunistic locking
14 (oplocks), connection scripts, supporting Microsoft Dfs (Distributed
15 filesystem) shares, and using NIS home directories.</p>
18 <div class="sect1"><a name="samba2-CHP-8-SECT-1"/>
20 <h2 class="head1">Filesystem Differences</h2>
22 <p>One of the biggest issues for which Samba has to correct is the
23 difference between Unix and Microsoft filesystems. This includes
24 items such as handling symbolic links, hidden files, and dot files.
25 In addition, file permissions can also be a headache if not properly
29 <div class="sect2"><a name="samba2-CHP-8-SECT-1.1"/>
31 <h3 class="head2">Hiding and Vetoing Files</h3>
33 <p><a name="INDEX-1"/><a name="INDEX-2"/>Sometimes you need to ensure that a user
34 cannot see or access a file at all. Other times, you
35 don't want to keep users from accessing a
36 file—you just want to hide it when they view the contents of
37 the directory. On Windows systems, an attribute of files allows them
38 to be hidden from a folder listing. With Unix, the traditional way of
39 hiding files in a directory is to use a <a name="INDEX-3"/><a name="INDEX-4"/>dot (.) as the first character in the
40 filename. This prevents items such as configuration files from being
41 seen when performing an ordinary <em class="emphasis">ls</em> command.
42 Keeping a user from accessing a file at all, however, involves
43 working with permissions on files and directories.</p>
45 <p>The first option we should discuss is the Boolean
46 <tt class="literal">hide</tt><a name="INDEX-5"/><a name="INDEX-6"/> <tt class="literal">dot</tt>
47 <tt class="literal">files</tt>. When it is set to <tt class="literal">yes</tt>,
48 Samba reports files beginning with a period (.) as having their
49 hidden attribute set. If the user has chosen to show all hidden files
50 while browsing (e.g., using the Folder Options menu item under the
51 View menu in Windows 98), he will still be able to see the files,
52 although his icons will appear
53 "ghosted," or slightly grayed-out.
54 If the client is configured not to show hidden files, the files will
55 not appear at all.</p>
57 <p>Instead of simply hiding files beginning with a dot, you can also
58 specify a string pattern to Samba for files to hide, using the
59 <tt class="literal">hide</tt><a name="INDEX-7"/> <tt class="literal">files</tt>
60 option. For example, let's assume you specified the
61 following in our example <tt class="literal">[data]</tt> share:</p>
63 <blockquote><pre class="code">[data]
64 hide files = /*.java/*README*/</pre></blockquote>
66 <p>Each entry for this option must begin, end, or be separated from
67 another with a slash ( / ) character, even if only one pattern is
68 listed. This convention allows spaces to appear in filenames. The
69 slashes have nothing to do with Unix directories; they are instead
70 acting as delimiters for the <tt class="literal">hide</tt>
71 <tt class="literal">files</tt> values.</p>
73 <p>If you want to prevent users from seeing files completely, you can
74 instead use the <tt class="literal">veto</tt><a name="INDEX-8"/> <tt class="literal">files</tt>
75 option. This option, which takes the same syntax as the
76 <tt class="literal">hide</tt> <tt class="literal">files</tt> option, specifies a
77 list of files that should never be seen by the user. For example,
78 let's change the <tt class="literal">[data]</tt> share to
81 <blockquote><pre class="code">[data]
82 veto files = /*.java/*README*/</pre></blockquote>
84 <p>The syntax of this option is identical to the <tt class="literal">hide</tt>
85 <tt class="literal">files</tt> configuration option: each entry must begin,
86 end, or be separated from another with a slash (<tt class="literal">/</tt>)
87 character, even if only one pattern is listed. If you do so, files
88 that match the pattern, such as <em class="filename">hello.java</em> and
89 <em class="filename">README.txt,</em> will simply disappear from the
90 directory, and the user cannot access them through SMB.</p>
92 <p><a name="INDEX-9"/>We need to address
93 one other question. What happens if the user tries to delete a
94 directory that contains vetoed files? This is where the
95 <tt class="literal">delete</tt><a name="INDEX-10"/> <tt class="literal">veto</tt>
96 <tt class="literal">files</tt> option comes in. If this Boolean option is
97 set to <tt class="literal">yes</tt>, the user can delete both the regular
98 files and the vetoed files in the directory, and the directory itself
99 is removed. If the option is set to <tt class="literal">no</tt>, the user
100 cannot delete the vetoed files, and consequently the directory is not
101 deleted either. From the user's perspective, the
102 directory appears empty, but cannot be removed.</p>
104 <p>The <tt class="literal">dont</tt><a name="INDEX-11"/> <tt class="literal">descend</tt>
105 directive specifies a list of directories whose contents Samba should
106 not make visible. Note that we say <em class="emphasis">contents</em>, not
107 the directory itself. Users can enter a directory marked as such, but
108 they are prohibited from descending the directory tree any
109 farther—they always see an empty folder. For example,
110 let's use this option with a more basic form of the
111 share that we defined earlier in the chapter:</p>
113 <blockquote><pre class="code">[data]
114 dont descend = config defaults</pre></blockquote>
116 <p>In addition, let's assume that the
117 <em class="filename">/home/samba/data</em> directory has the following
120 <blockquote><pre class="code">drwxr-xr-x 6 tom users 1024 Jun 13 09:24 .
121 drwxr-xr-x 8 root root 1024 Jun 10 17:53 ..
122 -rw-r--r-- 2 tom users 1024 Jun 9 11:43 README
123 drwxr-xr-x 3 tom users 1024 Jun 13 09:28 config
124 drwxr-xr-x 3 tom users 1024 Jun 13 09:28 defaults
125 drwxr-xr-x 3 tom users 1024 Jun 13 09:28 market</pre></blockquote>
127 <p>If the user then connects to the share, she would see the directories
128 in the share. However, the contents of the
129 <em class="filename">/config</em> and <em class="filename">/defaults</em>
130 directories would appear empty to her, even if other folders or files
131 existed in them. In addition, users cannot write any data to the
132 folder (which prevents them from creating a file or folder with the
133 same name as one that is already there but invisible). If a user
134 attempts to do so, she will receive an "Access
135 Denied" message. The <tt class="literal">dont</tt>
136 <tt class="literal">descend</tt> option is an administrative
137 option—not a security option—and is not a substitute for
138 good file permissions. <a name="INDEX-12"/><a name="INDEX-13"/></p>
144 <div class="sect2"><a name="samba2-CHP-8-SECT-1.2"/>
146 <h3 class="head2">Links</h3>
148 <p><a name="INDEX-14"/>When a client
149 tries to open a symbolic link on a Samba server share, Samba attempts
150 to follow the link to find the real file and let the client open it,
151 as if the user were on a Unix machine. If you don't
152 want to allow this, set the <tt class="literal">follow</tt>
153 <tt class="literal">symlinks</tt> option like this:</p>
155 <blockquote><pre class="code">[data]
156 follow symlinks = no</pre></blockquote>
158 <p>You can test this by setting up and trying to access a symbolic link.
159 Create a directory on the Unix server inside the share, acting as the
160 user under which you will log in to Samba. Enter the following
163 <blockquote><pre class="code">$ <tt class="userinput"><b>echo "This is a test" >hello.txt</b></tt>
164 $ <tt class="userinput"><b>ln -s hello.txt hello-link.txt</b></tt></pre></blockquote>
166 <p>This results in the text file <em class="filename">hello.txt</em> and a
167 symbolic link to it called <em class="filename">hello-link.txt</em>.
168 Normally, if you double-click either one, you will receive a file
169 that has the text "This is a test"
170 inside of it. However, with the <tt class="literal">follow</tt>
171 <tt class="literal">symlinks</tt><a name="INDEX-15"/> option set to
172 <tt class="literal">no</tt>, you will receive an error dialog if you
173 double-click <em class="filename">hello-link.txt</em>.</p>
175 <p>The <tt class="literal">wide</tt><a name="INDEX-16"/> <tt class="literal">links</tt>
176 option, if set to <tt class="literal">no</tt>, prevents the client user
177 from following symbolic links that point outside the shared directory
178 tree. For example, let's assume that we modified the
179 <tt class="literal">[data]</tt> share as follows:</p>
181 <blockquote><pre class="code">[data]
182 follow symlinks = yes
183 wide links = no</pre></blockquote>
185 <p>As long as the <tt class="literal">follow</tt><a name="INDEX-17"/>
186 <tt class="literal">symlinks</tt> option is disabled, Samba will refuse to
187 follow any symbolic links outside the current share tree. If we
188 create a file outside the share (for example, in
189 someone's home directory) and then create a link to
190 it in the share as follows:</p>
192 <blockquote><pre class="code">ln -s ~tom/datafile ./datafile</pre></blockquote>
194 <p>the client cannot open the file in Tom's home
201 <div class="sect2"><a name="samba2-CHP-8-SECT-1.3"/>
203 <h3 class="head2">Filesystem Options</h3>
205 <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
206 discussed earlier. We recommend the defaults for most, except those
207 listed in the following descriptions.</p>
209 <a name="samba2-CHP-8-TABLE-1"/><h4 class="head4">Table 8-1. Filesystem configuration options</h4><table border="1">
237 <p><tt class="literal">dont descend</tt></p>
240 <p>string (list of directories)</p>
243 <p>Indicates a list of directories whose contents Samba should make
244 invisible to clients.</p>
255 <p><tt class="literal">follow</tt> <tt class="literal">symlinks</tt></p>
261 <p>If set to <tt class="literal">no</tt>, will not honor symbolic links.</p>
264 <p><tt class="literal">yes</tt></p>
272 <p><tt class="literal">getwd cache</tt></p>
278 <p>If set to <tt class="literal">yes</tt>, will use a cache for
279 <tt class="literal">getwd( )</tt> calls.</p>
282 <p><tt class="literal">yes</tt></p>
290 <p><tt class="literal">wide links</tt></p>
296 <p>If set to <tt class="literal">yes</tt>, will follow symbolic links outside
300 <p><tt class="literal">yes</tt></p>
308 <p><tt class="literal">hide dot files</tt></p>
314 <p>If set to <tt class="literal">yes</tt>, treats Unix hidden files as hidden
315 files in Windows.</p>
318 <p><tt class="literal">yes</tt></p>
326 <p><tt class="literal">hide files</tt></p>
329 <p>string (list of files)</p>
332 <p>List of file patterns to treat as hidden.</p>
343 <p><tt class="literal">veto files</tt></p>
346 <p>string (list of files)</p>
349 <p>List of file patterns to never show.</p>
360 <p><tt class="literal">delete veto</tt> <tt class="literal">files</tt></p>
366 <p>If set to <tt class="literal">yes</tt>, will delete files matched by
367 <tt class="literal">veto files</tt> when the directory they reside in is
371 <p><tt class="literal">no</tt></p>
381 <div class="sect3"><a name="samba2-CHP-8-SECT-1.3.1"/>
383 <h3 class="head3">dont descend</h3>
385 <p>The <tt class="literal">dont</tt><a name="INDEX-20"/> <tt class="literal">descend</tt>
386 option can be used to specify various directories that should appear
387 empty to the client. Note that the directory itself will still
388 appear. However, Samba will not show any of the contents of the
389 directory to the client user. This is not a good option to use as a
390 security feature; it is really meant only as a convenience to keep
391 users from casually browsing into directories that might have
392 sensitive files. See our example earlier in this section.</p>
399 <div class="sect3"><a name="samba2-CHP-8-SECT-1.3.2"/>
401 <a name="INDEX-21"/><h3 class="head3">follow symlinks</h3>
403 <p>This option controls whether Samba will follow a symbolic link in the
404 Unix operating system to the target or if it should return an error
405 to the client user. If the option is set to <tt class="literal">yes</tt>,
406 the target of the link will be interpreted as the file. If set to
407 <tt class="literal">no</tt>, an error will be generated if the symbolic
408 link is accessed.</p>
415 <div class="sect3"><a name="samba2-CHP-8-SECT-1.3.3"/>
417 <a name="INDEX-22"/><h3 class="head3">getwd cache</h3>
419 <p>This global option specifies whether Samba should use a local cache
420 for the Unix <em class="emphasis">getwd( )</em> ( get current working
421 directory) system call. You can override the default value of
422 <tt class="literal">yes</tt> as follows:</p>
424 <blockquote><pre class="code">[global]
425 getwd cache = no</pre></blockquote>
427 <p>Setting this option to <tt class="literal">no</tt> can significantly
428 increase the time it takes to resolve the working directory,
429 especially if the <tt class="literal">wide</tt> <tt class="literal">links</tt>
430 option is set to <tt class="literal">no</tt>. You should normally not need
431 to alter this option.</p>
438 <div class="sect3"><a name="samba2-CHP-8-SECT-1.3.4"/>
440 <a name="INDEX-23"/><h3 class="head3">wide links</h3>
442 <p>This option specifies whether the client user can follow symbolic
443 links that point outside the shared directory tree. This includes any
444 files or directories at the other end of the link, as long as the
445 permissions are correct for the user. The default value for this
446 option is <tt class="literal">yes</tt>. Note that this option will not be
447 honored if the <tt class="literal">follow</tt> <tt class="literal">symlinks</tt>
448 options is set to <tt class="literal">no</tt>. Setting this option to
449 <tt class="literal">no</tt> slows <em class="emphasis">smbd</em> considerably
450 because it will have to check each link it encounters.</p>
457 <div class="sect3"><a name="samba2-CHP-8-SECT-1.3.5"/>
459 <h3 class="head3">hide dot files</h3>
461 <p>The <tt class="literal">hide</tt><a name="INDEX-24"/><a name="INDEX-25"/> <tt class="literal">dot</tt>
462 <tt class="literal">files</tt> option hides any files on the server that
463 begin with a dot (.) character to mimic the functionality behind
464 several shell commands that are present on Unix systems. Like
465 <tt class="literal">hide</tt> <tt class="literal">files</tt>, those files that
466 begin with a dot have the DOS hidden attribute set, which
467 doesn't guarantee that a client cannot view them.
468 The default value for this option is <tt class="literal">yes</tt>.</p>
475 <div class="sect3"><a name="samba2-CHP-8-SECT-1.3.6"/>
477 <h3 class="head3">hide files</h3>
479 <p>The <tt class="literal">hide</tt><a name="INDEX-26"/> <tt class="literal">files</tt> option
480 provides one or more directory or filename patterns to Samba. Any
481 file matching this pattern will be treated as a hidden file from the
482 perspective of the client. Note that this simply means that the DOS
483 hidden attribute is set, which might or might not mean that the user
484 can actually see it while browsing.</p>
486 <p>Each entry in the list must begin, end, or be separated from another
487 entry with a slash (<tt class="literal">/</tt>) character, even if only one
488 pattern is listed. This allows spaces to appear in the list.
489 Asterisks can be used as a wildcard to represent zero or more
490 characters. Questions marks can be used to represent exactly one
491 character. For example:</p>
493 <blockquote><pre class="code">hide files = /.jav*/README.???/</pre></blockquote>
500 <div class="sect3"><a name="samba2-CHP-8-SECT-1.3.7"/>
502 <a name="INDEX-27"/><h3 class="head3">veto files</h3>
504 <p>More stringent than the hidden files state is the state provided by
505 the <tt class="literal">veto</tt> <tt class="literal">files</tt> configuration
506 option. Samba won't even admit these files exist.
507 You cannot list or open them from the client. This should not be used
508 as a means of implementing security. It is actually a mechanism to
509 keep PC programs from deleting special files, such as ones used to
510 store the resource fork of a Macintosh file on a Unix filesystem. If
511 both Windows and Macs are sharing the same files, this can prevent
512 ill-advised power users from removing files the Mac users need.</p>
514 <p>The syntax of this option is identical to that of the
515 <tt class="literal">hide</tt> <tt class="literal">files</tt> configuration
516 option: each entry must begin, end, or be separated from another with
517 a slash ( / ) character, even if only one pattern is listed.
518 Asterisks can be used as a wildcard to represent zero or more
519 characters. Question marks can be used to represent exactly one
520 character. For example:</p>
522 <blockquote><pre class="code">veto files = /*config/*default?/</pre></blockquote>
524 <p>This option is primarily administrative and is not a substitute for
525 good file permissions.</p>
532 <div class="sect3"><a name="samba2-CHP-8-SECT-1.3.8"/>
534 <a name="INDEX-28"/><h3 class="head3">delete veto files</h3>
536 <p>This option tells Samba to delete vetoed files when a user attempts
537 to delete the directory in which they reside. The default value is
538 <tt class="literal">no</tt>. This means that if a user tries to delete a
539 directory that contains a vetoed file, the file (and the directory)
540 will not be deleted. Instead, the directory remains and appears empty
541 from the perspective of the user. If set to <tt class="literal">yes</tt>,
542 the directory and the vetoed files will be deleted. <a name="INDEX-29"/><a name="INDEX-30"/></p>
555 <div class="sect1"><a name="samba2-CHP-8-SECT-2"/>
557 <h2 class="head1">File Permissions and Attributes on MS-DOS and Unix</h2>
559 <p><a name="INDEX-31"/><a name="INDEX-32"/><a name="INDEX-33"/>Originally, DOS was not intended to be a
560 multiuser, networked operating system. Unix, on the other hand, was
561 designed for multiple users from the start. Consequently, Samba must
562 not only be aware of, but also provide special solutions for,
563 inconsistencies and gaps in coverage between the two filesystems. One
564 of the biggest gaps is how Unix and DOS handle permissions on files.</p>
566 <p>Let's take a look at how Unix assigns permissions.
567 All Unix files have read, write, and execute bits for three
568 classifications of users: owner, group, and world. These permissions
569 can be seen at the extreme lefthand side when an <em class="emphasis">ls
570 -al</em> command is issued in a Unix directory. For example:</p>
572 <blockquote><pre class="code">-rwxr--r-- 1 tom users 2014 Apr 13 14:11 access.conf</pre></blockquote>
574 <p>Windows, on the other hand, has four principal bits that it uses with
575 any file: read-only, system, hidden, and archive. You can view these
576 bits by right-clicking the file and choosing the Properties menu
577 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>
579 <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>
581 <p>The definition of each bit follows:</p>
584 <dt><b>Read-only</b></dt>
586 <p>The file's contents can be read by a user but cannot
592 <dt><b>System</b></dt>
594 <p>This file has a specific purpose required by the operating system.</p>
599 <dt><b>Hidden</b></dt>
601 <p>This file has been marked to be invisible to the user, unless the
602 operating system is explicitly set to show it.</p>
607 <dt><b>Archive</b></dt>
609 <p>This file has been touched since the last DOS backup was performed on
615 <p>Note that there is no bit to specify that a file is executable. DOS
616 and Windows NT filesystems identify executable files by giving them
617 the extensions <em class="filename">.exe</em>, <em class="filename">.com</em>,
618 <em class="filename">.cmd</em>, or <em class="filename">.bat</em>.</p>
620 <p>Consequently, there is no use for any of the three Unix executable
621 bits that are present on a file in a Samba disk share. DOS files,
622 however, have their own attributes that need to be preserved when
623 they are stored in a Unix environment: the archive, system, and
624 hidden bits. Samba can preserve these bits by reusing the executable
625 permission bits of the file on the Unix side—if it is
626 instructed to do so. Mapping these bits, however, has an unfortunate
627 side effect: if a Windows user stores a file in a Samba share, and
628 you view it on Unix with the <em class="emphasis">ls -al</em> command,
629 some of the executable bits won't mean what
630 you'd expect them to.</p>
632 <p>Three Samba options decide whether the bits are mapped:
633 <tt class="literal">map</tt><a name="INDEX-34"/> <tt class="literal">archive</tt>,
634 <tt class="literal">map</tt><a name="INDEX-35"/> <tt class="literal">system</tt> , and
635 <tt class="literal">map</tt><a name="INDEX-36"/> <tt class="literal">hidden</tt>. These options
636 map the archive, system, and hidden attributes to the owner, group,
637 and world execute bits of the file, respectively. You can add these
638 options to the <tt class="literal">[data]</tt> share, setting each of their
639 values as follows:</p>
641 <blockquote><pre class="code">[data]
644 map hidden = yes</pre></blockquote>
646 <p>After that, try creating a file in the share under Unix—such as
647 <em class="emphasis">hello.java</em>—and change the permissions of
648 the file to 755. With these Samba options set, you should be able to
649 check the permissions on the Windows side and see that each of the
650 three values has been checked in the Properties dialog box. What
651 about the read-only attribute? By default, Samba sets this whenever a
652 file does not have the Unix owner write permission bit set. In other
653 words, you can set this bit by changing the permissions of the file
656 <p>The default value of the <tt class="literal">map</tt>
657 <tt class="literal">archive</tt> option is <tt class="literal">yes</tt>, while
658 the other two options have a default value of <tt class="literal">no</tt>.
659 This is because many programs do not work properly if the archive bit
660 is not stored correctly for DOS and Windows files. The system and
661 hidden attributes, however, are not critical for a
662 program's operation and are left to the discretion
663 of the administrator.</p>
665 <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
666 illustrates how Samba maps those bits to DOS attributes. Note that
667 the group read/write and world read/write bits do not directly
668 translate to a DOS attribute, but they still retain their original
669 Unix definitions on the Samba server.</p>
671 <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>
674 <div class="sect2"><a name="samba2-CHP-8-SECT-2.1"/>
676 <h3 class="head2">Creation Masks</h3>
678 <p><a name="INDEX-39"/>File and directory creation masks are
679 similar to <a name="INDEX-40"/>umasks you
680 have probably encountered while working with Unix systems. They are
681 used to help define the permissions that will be assigned to a file
682 or directory at the time it is created. Samba's
683 masks work differently in that the bits that can be set are set in
684 the creation mask, while in Unix umasks, the bits
685 <em class="emphasis">cannot</em> be set are set in the umask. We think you
686 will find Samba's method to be much more intuitive.
687 Once in a while you might need to convert between a Unix umask and
688 the equivalent Samba mask. It is simple: one is just the bitwise
689 complement of the other. For example, an octal umask of 0022 has the
690 same effect as a Samba mask of 0755.</p>
692 <p>Unix umasks are set on a user-by-user basis, usually while executing
693 the GUI's or command-line shell's
694 startup scripts. When users connect to a Samba share from a network
695 client, these scripts are not executed, so Samba supplies the ability
696 to set the creation masks for files and directories. By default, this
697 is done on a share-by-share basis, although you can use the
698 <tt class="literal">include</tt> parameter in the Samba configuration file
699 (as explained in <a href="ch06.html">Chapter 6</a>) to assign masks on a
700 user-by-user basis, thus matching conventional Unix behavior.</p>
702 <p>To show how Samba's create masks work, suppose we
703 have a Windows Me user connecting to his Unix home directory through
704 Samba, and Samba is configured with <tt class="literal">create</tt>
705 <tt class="literal">mask</tt> <tt class="literal">=</tt> <tt class="literal">777</tt>
706 in the <tt class="literal">[homes]</tt> share. With this value,
707 <tt class="literal">create</tt> <tt class="literal">mask</tt> will not affect the
708 bits that are set on new files. If the user creates a file with
709 Wordpad, it will appear in the Unix filesystem like this:</p>
711 <blockquote><pre class="code">$ <tt class="userinput"><b>ls -l file.doc</b></tt>
712 -rwxrw-rw- 1 jay jay 0 Sep 21 11:02 file.doc</pre></blockquote>
714 <p>Wordpad created the file with read/write permissions (i.e., the
715 MS-DOS read-only attribute was not set), so Samba mapped the MS-DOS
716 attributes to Unix read/write permissions for user, group, and other.
717 The <a name="INDEX-41"/><a name="INDEX-42"/>execute bit is set for the owner
718 because by default, the <tt class="literal">map</tt>
719 <tt class="literal">archive</tt> parameter is set to
720 <tt class="literal">yes</tt>. The other execute bits are not set because
721 <tt class="literal">map</tt> <tt class="literal">system</tt> and
722 <tt class="literal">map</tt> <tt class="literal">hidden</tt> are set to
723 <tt class="literal">no</tt> by default. You can customize this behavior as
724 you see fit, and unless you do backups from MS-DOS or Windows
725 systems, you might want to specify <tt class="literal">map</tt>
726 <tt class="literal">archive</tt> <tt class="literal">=</tt> <tt class="literal">no</tt>
727 to avoid Windows files from appearing as executables on the Unix
730 <p>Now suppose we set
731 <tt class="literal">create</tt><a name="INDEX-43"/> <tt class="literal">mask</tt> to have
732 an effect. For example:</p>
734 <blockquote><pre class="code">[homes]
735 create mask = 664</pre></blockquote>
737 <p>This is equivalent to a Unix umask of 113. If the user creates the
738 Wordpad document as before, it will show up as:</p>
740 <blockquote><pre class="code">$ <tt class="userinput"><b>ls -l file.doc</b></tt>
741 -rw-rw-r-- 1 jay jay 0 Sep 22 16:38 file.doc</pre></blockquote>
743 <p>Comparing this to the previous example, notice that not only has the
744 write permission for other disappeared as we expected, but so has the
745 execute permission for owner. This happened because the value of
746 <tt class="literal">create</tt> <tt class="literal">mask</tt> logically ANDs the
747 owner's permissions with a 6, which has masked off
748 the execute bit. The lesson here is that if you want to enable any of
749 <tt class="literal">map</tt> <tt class="literal">archive</tt>,
750 <tt class="literal">map</tt> <tt class="literal">system</tt>, or
751 <tt class="literal">map</tt> <tt class="literal">hidden</tt>, you must be careful
752 not to mask off the corresponding execute bit with your
753 <tt class="literal">create</tt> <tt class="literal">mask</tt>.</p>
755 <p>The <tt class="literal">directory</tt><a name="INDEX-44"/> <tt class="literal">mask</tt>
756 option works similarly, masking permissions for newly created
757 directories. The following example will allow the permissions of a
758 newly created directory to be, at most, 755:</p>
760 <blockquote><pre class="code">[data]
761 directory mask = 755</pre></blockquote>
763 <p>Also, you can force various bits with the <tt class="literal">force</tt>
764 <tt class="literal">create</tt> <tt class="literal">mode</tt> and
765 <tt class="literal">force</tt> <tt class="literal">directory</tt>
766 <tt class="literal">mode</tt> options. These options will perform a logical
767 OR against the file and directory creation masks, ensuring that those
768 bits that are specified will always be set. You would typically set
769 these options globally to ensure that group and world read/write
770 permissions have been set appropriately for new files or directories
773 <p>In the same spirit, if you wish to set explicitly the Unix user and
774 group attributes of a file created on the Windows side, you can use
775 the <tt class="literal">force</tt><a name="INDEX-45"/> <tt class="literal">user</tt> and
776 <tt class="literal">force</tt><a name="INDEX-46"/> <tt class="literal">group</tt>
777 options. For example:</p>
779 <blockquote><pre class="code">[data]
783 force group = accounting</pre></blockquote>
785 <p>These options assign the same Unix username and group to every client
786 that connects to the share. However, this occurs
787 <em class="emphasis">after</em> the client authenticates; it does not
788 allow free access to a share. These options are frequently used for
789 their side effects of assigning a specific user and group to each new
790 file or directory that is created in a share. Use these options with
793 <p>Finally, one of the capabilities of Unix that DOS lacks is the
794 ability to delete a read-only file from a writable directory. In
795 Unix, if a directory is writable, a read-only file in that directory
796 can still be removed. This could permit you to delete files in any of
797 your directories, even if the file was left by someone else.</p>
799 <p>DOS filesystems are not designed for multiple users, and so its
800 designers decided that read-only means "protected
801 against accidental change, including deletion,"
802 rather than "protected against some other user on a
803 single-user machine." So the designers of DOS
804 prohibited removal of a read-only file. Even today, Windows
805 filesystems exhibit the same behavior.</p>
807 <p>Normally, this is harmless. Windows programs don't
808 try to remove read-only files because they know it's
809 a bad idea. However, a number of source-code control
810 programs—which were first written for Unix—run on Windows
811 and require the ability to delete read-only files. Samba permits this
812 behavior with the <tt class="literal">delete</tt><a name="INDEX-47"/>
813 <tt class="literal">readonly</tt> option. To enable this functionality, set
814 the option to <tt class="literal">yes</tt>:</p>
816 <a name="INDEX-48"/><blockquote><pre class="code">[data]
817 delete readonly = yes</pre></blockquote>
823 <div class="sect2"><a name="samba2-CHP-8-SECT-2.2"/>
825 <h3 class="head2">File and Directory Permission Options</h3>
827 <p><a name="INDEX-49"/><a name="INDEX-50"/><a name="INDEX-51"/>The
828 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>
830 <a name="samba2-CHP-8-TABLE-2"/><h4 class="head4">Table 8-2. File and directory permission options</h4><table border="1">
858 <p><tt class="literal">create mask</tt> <tt class="literal">(create mode)</tt></p>
864 <p>Maximum permissions for files created by Samba.</p>
867 <p><tt class="literal">0744</tt></p>
875 <p><tt class="literal">directory mask</tt> <tt class="literal">(directory mode)</tt></p>
881 <p>Maximum permissions for directories created by Samba.</p>
884 <p><tt class="literal">0744</tt></p>
892 <p><tt class="literal">force create mode</tt></p>
898 <p>Forces the specified permissions (bitwise <tt class="literal">or</tt>) for
899 directories created by Samba.</p>
902 <p><tt class="literal">0000</tt></p>
910 <p><tt class="literal">force directory</tt> <tt class="literal">mode</tt></p>
916 <p>Forces the specified permissions (bitwise <tt class="literal">or</tt>) for
917 directories created by Samba.</p>
920 <p><tt class="literal">0000</tt></p>
928 <p><tt class="literal">force group</tt> <tt class="literal">(group)</tt></p>
931 <p>string ( group name)</p>
934 <p>Effective group for a user accessing this share.</p>
945 <p><tt class="literal">force user</tt></p>
948 <p>string (username)</p>
951 <p>Effective username for a user accessing this share.</p>
962 <p><tt class="literal">delete readonly</tt></p>
968 <p>Allows a user to delete a read-only file from a writable directory.</p>
971 <p><tt class="literal">no</tt></p>
979 <p><tt class="literal">map archive</tt></p>
985 <p>Preserve DOS archive attribute in user execute bit (0100).</p>
988 <p><tt class="literal">yes</tt></p>
996 <p><tt class="literal">map system</tt></p>
1002 <p>Preserve DOS system attribute in group execute bit (0010).</p>
1005 <p><tt class="literal">no</tt></p>
1013 <p><tt class="literal">map hidden</tt></p>
1019 <p>Preserve DOS hidden attribute in world execute bit (0001).</p>
1022 <p><tt class="literal">no</tt></p>
1030 <p><tt class="literal">inherit permissions</tt></p>
1036 <p>If <tt class="literal">yes</tt>, permissions on new files and directories
1037 are inherited from parent directory.</p>
1050 <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.1"/>
1052 <a name="INDEX-52"/><h3 class="head3">create mask</h3>
1054 <p>The argument for this option is an octal number indicating which
1055 permission flags can be set at file creation by a client in a share.
1056 The default is 0744, which means that the Unix owner can at most
1057 read, write, and optionally execute her own files, while members of
1058 the user's group and others can only read or execute
1059 them. If you need to change it for nonexecutable files, we recommend
1060 0644, or <tt class="literal">rw-r--r--</tt>. Keep in mind that the execute
1061 bits can be used by the server to map certain DOS file attributes, as
1062 described earlier. If you're altering the create
1063 mask, those bits have to be part of the create mask as well.</p>
1070 <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.2"/>
1072 <a name="INDEX-53"/><h3 class="head3">directory mask</h3>
1074 <p>The argument for this option is an octal number indicating which
1075 permission flags can be set at directory creation by a client in a
1076 share. The default is 0744, which allows everyone on the Unix side
1077 to, at most, read and traverse the directories, but allows only you
1078 to modify them. We recommend the mask 0750, removing access by
1079 "the world."</p>
1086 <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.3"/>
1088 <a name="INDEX-54"/><h3 class="head3">force create mode</h3>
1090 <p>This option sets the permission bits that Samba will set when a file
1091 permission change is made. It's often used to force
1092 group permissions, as mentioned previously. It can also be used to
1093 preset any of the DOS attributes we mentioned: archive (0100), system
1094 (0010), or hidden (0001).</p>
1096 <a name="samba2-CHP-8-NOTE-139"/><blockquote class="note"><h4 class="objtitle">TIP</h4>
1097 <p><a name="INDEX-55"/>When saving
1098 documents, many Windows applications rename their datafiles with a
1099 <em class="filename">.bak</em> extension and create new ones. When the
1100 files are in a Samba share, this changes their ownership and
1101 permissions so that members of the same Unix group
1102 can't edit them. Setting <tt class="literal">force</tt>
1103 <tt class="literal">create mode = 0660</tt> will keep the new file editable
1104 by members of the group.</p>
1112 <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.4"/>
1114 <a name="INDEX-56"/><h3 class="head3">force directory mode</h3>
1116 <p>This option sets the permission bits that Samba will set when a
1117 directory permission change is made or a directory is created.
1118 It's often used to force group permissions, as
1119 mentioned previously. This option defaults to 0000 and can be used
1120 just like the <tt class="literal">force</tt> <tt class="literal">create</tt>
1121 <tt class="literal">mode</tt> to add group or other permissions if needed.</p>
1128 <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.5"/>
1130 <a name="INDEX-57"/><h3 class="head3">force group</h3>
1132 <p>This option, sometimes called <tt class="literal">group</tt>, assigns a
1133 static group ID that will be used on all connections to a share after
1134 the client has successfully authenticated. This assigns a specific
1135 group to each new file or directory created from an SMB client.</p>
1142 <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.6"/>
1144 <h3 class="head3">force user</h3>
1146 <p>The <tt class="literal">force</tt><a name="INDEX-58"/> <tt class="literal">user</tt> option
1147 assigns a static user ID that will be used on all connections to a
1148 share after the client has successfully authenticated. This assigns a
1149 specific user to each new file or directory created from an SMB
1157 <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.7"/>
1159 <a name="INDEX-59"/><h3 class="head3">delete readonly</h3>
1161 <p>This option allows a user to delete a directory containing a
1162 read-only file. By default, DOS and Windows will not allow such an
1163 operation. You probably will want to leave this option turned off
1164 unless a program (for example, an RCS program) needs this capability;
1165 many Windows users would be appalled to find that
1166 they'd accidentally deleted a file that they had set
1174 <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.8"/>
1176 <a name="INDEX-60"/><h3 class="head3">map archive</h3>
1178 <p>The DOS archive bit is used to flag a file that has been changed
1179 since it was last archived (e.g., backed up with the DOS archive
1180 program). Setting the Samba option <tt class="literal">map</tt>
1181 <tt class="literal">archive</tt> <tt class="literal">=</tt>
1182 <tt class="literal">yes</tt> maps the DOS archive flag to the Unix
1183 execute-by-owner (0100) bit. It's best to leave this
1184 option on if your Windows users are doing their own backups or are
1185 using programs that require the archive bit. Unix lacks the notion of
1186 an archive bit entirely. Backup programs typically keep a file that
1187 lists what files were backed up on what date, so comparing
1188 file-modification dates serves the same purpose.</p>
1190 <p>Setting this option to <tt class="literal">yes</tt> causes an occasional
1191 surprise on Unix when a user notices that a datafile is marked as
1192 executable, but rarely causes harm. If a user tries to run it, he
1193 will normally get a string of error messages as the shell tries to
1194 execute the first few lines as commands. The reverse is also
1195 possible; an executable Unix program looks like it
1196 hasn't been backed up recently on Windows. But
1197 again, this is rare and usually harmless.</p>
1199 <p>For map archive to work properly, the execute bit for owner must not
1200 be masked off with the <tt class="literal">create</tt>
1201 <tt class="literal">mask</tt> parameter.</p>
1208 <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.9"/>
1210 <a name="INDEX-61"/><h3 class="head3">map system</h3>
1212 <p>The DOS system attribute indicates files that are required by the
1213 operating system and should not be deleted, renamed, or moved without
1214 special effort. Set this option only if you need to store Windows
1215 system files on the Unix fileserver. Executable Unix programs will
1216 appear to be nonremovable, special Windows files when viewed from
1217 Windows clients. This might prove mildly inconvenient if you want to
1218 move or remove one. For most sites, however, this is fairly harmless.</p>
1220 <p>For map archive to work properly, the execute bit for group must not
1221 be masked off with the <tt class="literal">create</tt>
1222 <tt class="literal">mask</tt> parameter.</p>
1229 <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.10"/>
1231 <a name="INDEX-62"/><h3 class="head3">map hidden</h3>
1233 <p>DOS uses the hidden attribute to indicate that a file should not
1234 ordinarily be visible in directory listings. Unix
1235 doesn't have such a facility; it's
1236 up to individual programs (notably, the shell) to decide what to
1237 display and what not to display. Normally, you won't
1238 have any DOS files that need to be hidden, so the best thing to do is
1239 to leave this option turned off.</p>
1241 <p>Setting this option to <tt class="literal">yes</tt> causes the server to
1242 map the hidden flag onto the executable-by-others bit (0001). This
1243 feature can produce a rather startling effect. Any Unix program that
1244 is executable by world seems to vanish when you look for it from a
1245 Windows client. If this option is not set, however, and a Windows
1246 user attempts to mark a file hidden on a Samba share, it will not
1247 work—Samba has no place to store the hidden attribute!</p>
1249 <p>For map archive to work properly, the execute bit for other must not
1250 be masked off with the <tt class="literal">create</tt>
1251 <tt class="literal">mask</tt> parameter.</p>
1258 <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.11"/>
1260 <h3 class="head3">inherit permissions</h3>
1262 <p>When the <tt class="literal">inherit</tt><a name="INDEX-63"/>
1263 <tt class="literal">permissions</tt> option is set to
1264 <tt class="literal">yes</tt>, the <tt class="literal">create</tt>
1265 <tt class="literal">mask</tt>, <tt class="literal">directory</tt>
1266 <tt class="literal">mask</tt>, <tt class="literal">force</tt>
1267 <tt class="literal">create</tt> <tt class="literal">mode</tt>, and
1268 <tt class="literal">force</tt> <tt class="literal">directory</tt>
1269 <tt class="literal">mode</tt> are ignored. The normal behavior of setting
1270 the permissions on newly created files is overridden such that the
1271 new files and directories take on permissions from their parent
1272 directory. New directories will have exactly the same permissions as
1273 the parent, and new files will inherit the read and write bits from
1274 the parent directory, while the execute bits are determined as usual
1275 by the values of the <tt class="literal">map</tt>
1276 <tt class="literal">archive</tt>, <tt class="literal">map</tt>
1277 <tt class="literal">hidden</tt>, and <tt class="literal">map</tt>
1278 <tt class="literal">system</tt> parameters.</p>
1280 <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>
1293 <div class="sect1"><a name="samba2-CHP-8-SECT-3"/>
1295 <h2 class="head1">Windows NT/2000/XP ACLs</h2>
1297 <p><a name="INDEX-70"/><a name="INDEX-71"/><a name="INDEX-72"/><a name="INDEX-73"/>Unix and Windows
1298 have different <a name="INDEX-74"/>security models, and Windows NT/2000/XP
1299 has a security model that is different from Windows 95/98/Me. One
1300 area in which this is readily apparent is file protections. On Unix
1301 systems, the method used has traditionally been the 9-bit
1302 "user, group, other" system, in
1303 which read, write, and execute bits can be set separately for the
1304 owner of the file, the groups to which the owner belongs, and
1305 everyone else, respectively.</p>
1307 <p><a name="INDEX-75"/>Windows 95/98/Me has a file-protection
1308 system that is essentially no protection at all. This family of
1309 operating systems was developed from MS-DOS, which was implemented as
1310 a non-networked, single-user system. Multiuser security simply was
1311 never added. One apparent exception to this is user-level security
1312 for shared files, which we will discuss in <a href="ch09.html">Chapter 9</a>. Here, separate access permissions can be
1313 assigned to individual network client users or groups. However,
1314 user-level security on Windows 95/98/Me systems requires a Windows
1315 NT/2000 or Samba server to perform the actual authentication.</p>
1317 <p>On <a name="INDEX-76"/><a name="INDEX-77"/><a name="INDEX-78"/>Windows NT/2000/XP,
1318 user-level security is an extension of the native file security
1319 model, which involves access control lists (ACLs). This system is
1320 somewhat more extensive than the Unix security model, allowing the
1321 access rights on individual files to be set separately for any number
1322 of individual users and/or any number of arbitrary groups of users.
1323 <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>,
1324 and <a href="ch08.html#samba2-CHP-8-FIG-5">Figure 8-5</a> show the dialog boxes on a Windows
1325 2000 system in which the ACL is set for a file. By right-clicking a
1326 file's icon and selecting Properties, then selecting
1327 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
1328 file, which are similar to Unix permissions, although not identical.</p>
1330 <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>
1332 <p>By clicking the Advanced tab, we can bring up the dialog box shown in
1333 <a href="ch08.html#samba2-CHP-8-FIG-4">Figure 8-4</a>, which shows the list of
1334 <a name="INDEX-79"/>access control entries (ACEs) in the ACL.
1335 In this dialog, ACEs can be added to or deleted from the ACL, or an
1336 existing ACE can be viewed and modified. Each ACE either allows or
1337 denies a set of permissions for a specific user or group.</p>
1339 <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>
1341 <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>
1343 <p><a href="ch08.html#samba2-CHP-8-FIG-5">Figure 8-5</a> shows the dialog box for adding an ACE.
1344 As you can see, there are more options for permissions in an ACL than
1345 with the permission bits on typical Unix systems. You can learn more
1346 about these settings in <em class="citetitle">Essential Windows NT System
1347 Administration</em>, published by O'Reilly.</p>
1349 <p>In a networked environment where a Samba server is serving files to
1350 Windows NT/2000/XP clients, Samba has to map Unix permissions for
1351 files and directories to Windows NT/2000/XP access control lists.
1352 When a Windows NT/2000/XP client accesses a shared file or directory
1353 on a Samba server, Samba translates the object's
1354 ownership, group, and permissions into an ACL and returns them to the
1357 <p><a href="ch08.html#samba2-CHP-8-FIG-6">Figure 8-6</a> shows the Properties dialog box for the
1358 file <em class="filename">shopping_list.doc</em> that resides on the Samba
1361 <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>
1363 <p>From Unix, this file appears as:</p>
1365 <blockquote><pre class="code">$ <tt class="userinput"><b>ls -l shopping_list.doc</b></tt>
1366 -rw------- 1 adilia users 49 Mar 29 11:58 shopping_list.doc</pre></blockquote>
1368 <p>Notice that because the file has read permissions for the owner, the
1369 Read-only checkbox will show as cleared, even though the user on the
1370 Windows client (who is not <tt class="literal">adilia</tt> in this example)
1371 does not have read access permissions. The checkboxes here show only
1372 DOS attributes. By clicking the Security tab, we can start to examine
1373 the ACLs, as shown in <a href="ch08.html#samba2-CHP-8-FIG-7">Figure 8-7</a>.</p>
1375 <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>
1377 <p>The owner of the file (<tt class="literal">adilia</tt>) is shown as one
1378 entry, while the group (<tt class="literal">users</tt>) and other
1379 permissions are presented as the groups called
1380 <tt class="literal">users</tt> and <tt class="literal">Everyone</tt>. Clicking
1381 one of the items in the upper windows causes the simplified view of
1382 the permissions in that item to appear in the bottom window. Here,
1383 the read/write permissions for <tt class="literal">adilia</tt> appear in a
1384 manner that makes the security model of Unix and Windows seem
1385 similar. However, clicking the Advanced . . . button brings up the
1386 additional dialog box shown in <a href="ch08.html#samba2-CHP-8-FIG-8">Figure 8-8</a>.</p>
1388 <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>
1390 <p>In this dialog box, we see the actual ACL of the file. The ACEs for
1391 <tt class="literal">users</tt> and <tt class="literal">Everyone</tt> are listed
1392 with Take Ownership in the Permission column. This is a trick used by
1393 Samba for ACLs that have no permissions on the Unix side. On Windows,
1394 an ACL with nothing set results in no ACL at all, so Samba sets the
1395 Take Ownership permission to make sure that all the ACLs
1396 corresponding to the Unix "user, group,
1397 other" permissions will show up on Windows. The Take
1398 Ownership permission has no corresponding Unix attribute, so the
1399 setting on Windows does not affect the actual file on the Unix system
1400 in any way. Although Windows client users might be misled into
1401 thinking they can take ownership of the file (that is, change the
1402 ownership of the file to themselves), an actual attempt to do so will
1405 <p>The Permissions column for the <tt class="literal">adilia</tt> ACL is
1406 listed as Special because Samba reports permissions for the file that
1407 do not correspond to settings for which Windows has a more
1408 descriptive name. Clicking the entry and then clicking the View/Edit
1409 . . . 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
1410 can be viewed and perhaps modified.</p>
1412 <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>
1414 <p>We say "perhaps" here because
1415 checking or unchecking boxes in this dialog box might not result in
1416 settings that Samba is able to map back into the Unix security model.
1417 When a user attempts to modify a setting (either permissions or
1418 ownership) that she does not have authority to change, or does not
1419 correspond to a valid setting on the Unix system, Samba will respond
1420 with an error dialog or by quietly ignoring the unmappable settings.</p>
1422 <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
1425 <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>
1427 <p>Here, there are two ACLs each for <tt class="literal">users</tt> and
1428 <tt class="literal">Everyone</tt>. One ACL specifies the permissions for
1429 the directory itself, and the other specifies permissions for the
1430 directory's contents. When changing settings in the
1431 View/Edit... dialog, there is an extra drop-down menu to apply the
1432 settings either to just the directory or to some combination of the
1433 directory and the files and directories it contains. If settings are
1434 applied to more than just the directory, Samba will match the
1435 behavior of a Windows server and change the permissions on the
1436 contents of the directory, as specified in the dialog.</p>
1439 <div class="sect2"><a name="samba2-CHP-8-SECT-3.1"/>
1441 <h3 class="head2">Unix ACLs</h3>
1443 <p><a name="INDEX-80"/><a name="INDEX-81"/>In
1444 most cases, users of Windows clients will find the Unix security
1445 model to be sufficient. However, in some cases, people might want the
1446 Samba server to support the full Windows ACL security model. Even if
1447 they don't need the fine-grained control over file
1448 and directory permissions, they might find Samba's
1449 translation between ACLs and Unix permissions to be a source of
1450 confusion or frustration.</p>
1452 <p>When the underlying Unix host operating system supports
1453 <a name="INDEX-82"/><a name="INDEX-83"/>POSIX.1e ACLs, Samba provides much better
1454 support of Windows NT/2000/XP ACLs. Versions of Unix that offer the
1455 necessary support include the following:</p>
1458 <p>Solaris 2.6 and later</p>
1462 <p>Linux, with Andreas Grünbacher's kernel
1463 patch from <a href="http://acl.bestbits.at">http://acl.bestbits.at</a>
1464 that adds ACL support to the Linux ext2 and ext3 filesystems</p>
1466 <p>Linux, with the XFS filesystem</p>
1470 <p>FreeBSD 5.0 and later</p>
1472 <p>HP/UX 11.0 and later, with the JFS 3.3 filesystem layout Version 4</p>
1474 <p>If you are fortunate enough to have a Unix host operating system with
1475 ACL support already provided, all you need to do is recompile Samba
1476 using the <tt class="literal">--with-acl-support</tt> configure option, as
1477 we described in <a href="ch02.html">Chapter 2</a>. If you are running
1478 Linux and need to patch your kernel, things are much more
1479 complicated. We suggest you refer to the documentation that comes
1480 with the patch for details on using it.</p>
1486 <div class="sect2"><a name="samba2-CHP-8-SECT-3.2"/>
1488 <h3 class="head2">Configuration Options for ACLs</h3>
1490 <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
1491 for working with Windows NT/2000/XP access control lists.</p>
1493 <a name="samba2-CHP-8-TABLE-3"/><h4 class="head4">Table 8-3. ACL configuration options</h4><table border="1">
1521 <p><tt class="literal">nt acl support</tt></p>
1527 <p>If <tt class="literal">yes</tt>, allows users on Windows NT/2000/XP clients
1528 to modify ACL settings</p>
1531 <p><tt class="literal">yes</tt></p>
1539 <p><tt class="literal">security mask</tt></p>
1545 <p>Bitmask that allows or denies permission settings on files</p>
1548 <p><tt class="literal">0777</tt></p>
1556 <p><tt class="literal">force security</tt> <tt class="literal">mode</tt></p>
1562 <p>Bits that are always set when modifying file permissions</p>
1565 <p><tt class="literal">0000</tt></p>
1573 <p><tt class="literal">directory</tt> <tt class="literal">security mask</tt></p>
1579 <p>Bitmask that allows or denies permission settings on directories</p>
1582 <p><tt class="literal">0777</tt></p>
1590 <p><tt class="literal">force directory</tt> <tt class="literal">security mode</tt></p>
1596 <p>Bits that are always set when modifying directory permissions</p>
1599 <p><tt class="literal">0000</tt></p>
1609 <div class="sect3"><a name="samba2-CHP-8-SECT-3.2.1"/>
1611 <a name="INDEX-86"/><h3 class="head3">nt acl support</h3>
1613 <p>This parameter defaults to <tt class="literal">yes</tt>, which allows users
1614 on Windows NT/2000/XP clients to modify ACL settings for files on the
1615 Samba server. When set to <tt class="literal">no</tt>, files show up as
1616 owned by <tt class="literal">Everyone</tt>, with permissions appearing as
1617 "Full Control". However,
1618 <em class="emphasis">actual</em> ownership and permissions are enforced as
1619 whatever they are set to on the Samba server, and the user on the
1620 Windows client cannot view or modify them with the dialog boxes used
1621 for managing ACLs.</p>
1623 <p>When enabled, support for Windows NT/2000/XP ACLs is limited to
1624 whatever ownerships and permissions can map into valid users and
1625 permissions on the Samba server. If the server supports ACLs (either
1626 "out of the box" or with an
1627 additional patch to enhance the filesystem), Samba's
1628 ACL support more closely matches that of a Windows NT/2000/XP server.</p>
1635 <div class="sect3"><a name="samba2-CHP-8-SECT-3.2.2"/>
1637 <h3 class="head3">security mask</h3>
1639 <p>Using the <tt class="literal">security</tt><a name="INDEX-87"/>
1640 <tt class="literal">mask</tt> option, it is possible to define which file
1641 permissions users can modify from Windows NT/2000/XP clients. This is
1642 for files only and not directories, which are handled with the
1643 <tt class="literal">directory</tt><a name="INDEX-88"/>
1644 <tt class="literal">security</tt> <tt class="literal">mask</tt> option. The
1645 parameter is assigned a numeric value that is a Unix-style
1646 permissions mask. For bits in the mask that are set, the client can
1647 modify the corresponding bits in the files'
1648 permissions. If the bit is zero, the client cannot modify that
1649 permission. For example, if <tt class="literal">security</tt>
1650 <tt class="literal">mask</tt> is set as:</p>
1652 <blockquote><pre class="code">[data]
1653 security mask = 0777</pre></blockquote>
1655 <p>the client can modify all the user/group/other permissions for the
1656 files in the share. This is the default. A value of
1657 <tt class="literal">0</tt> would deny clients from changing any of the
1658 permissions, and setting <tt class="literal">security</tt>
1659 <tt class="literal">mask</tt> as:</p>
1661 <blockquote><pre class="code">[data]
1662 security mask = 0666</pre></blockquote>
1664 <p>would allow client users to modify the read and write permissions,
1665 but not the execute permissions.</p>
1667 <p>Do not count on <tt class="literal">security</tt> <tt class="literal">mask</tt>
1668 for complete control because if the user can access the files on the
1669 Samba server through any other means (for example, by logging
1670 directly into the Unix host), he can modify the permissions using
1678 <div class="sect3"><a name="samba2-CHP-8-SECT-3.2.3"/>
1680 <h3 class="head3">force security mode</h3>
1682 <p>The <tt class="literal">force</tt><a name="INDEX-89"/>
1683 <tt class="literal">security</tt> <tt class="literal">mode</tt> option can be
1684 used to define a set of permissions that are always set whenever the
1685 user on a Windows NT/2000/XP client modifies a
1686 file's permissions. (See the
1687 <tt class="literal">force</tt> <tt class="literal">directory</tt>
1688 <tt class="literal">security</tt> <tt class="literal">mode</tt> option for
1689 handling directories.)</p>
1691 <p>Be careful to understand this properly. The mask given as the
1692 parameter's value is not necessarily equal to the
1693 resulting permissions on the file. The permissions that the client
1694 user attempts to modify are logically OR'd with the
1695 <tt class="literal">force</tt> <tt class="literal">security</tt>
1696 <tt class="literal">mode</tt> <tt class="literal">mask</tt> option, and any bits
1697 that are turned on will cause the file's
1698 corresponding permissions to be set. As an example, suppose
1699 <tt class="literal">force</tt> <tt class="literal">security</tt>
1700 <tt class="literal">mode</tt> is set in a share thusly:</p>
1702 <blockquote><pre class="code">[data]
1703 force security mode = 0440</pre></blockquote>
1705 <p>(This sets the read bit for owner and group, but not other.) If a
1706 user on a Windows NT/2000/XP client modifies an ACL on a file in the
1707 <tt class="literal">[data]</tt> share and attempts to remove all read
1708 permissions, the read permission for other
1709 (<tt class="literal">Everyone</tt>) will be removed, but the read
1710 permission for the owner and group will remain. Note that this
1711 parameter cannot force a permission bit to be turned off.</p>
1713 <p>As with the <tt class="literal">security</tt> <tt class="literal">mask</tt>
1714 option, if a user can access the files in the share through any means
1715 other than Samba, she can easily work around Samba's
1716 enforcement of this parameter.</p>
1718 <p>The default value of <tt class="literal">force</tt>
1719 <tt class="literal">security</tt> <tt class="literal">mode</tt> is
1720 <tt class="literal">0000</tt>, which allows users to remove any permission
1728 <div class="sect3"><a name="samba2-CHP-8-SECT-3.2.4"/>
1730 <a name="INDEX-90"/><h3 class="head3">directory security mask</h3>
1732 <p>This option works exactly the same as the <tt class="literal">security</tt>
1733 <tt class="literal">mask</tt> option, except that it operates on
1734 directories rather than files. As with <tt class="literal">security</tt>
1735 <tt class="literal">mask</tt>, it has a default value of
1736 <tt class="literal">0777</tt>, which allows Windows NT/2000/XP client users
1737 to modify all Unix permissions on directories in the share.</p>
1744 <div class="sect3"><a name="samba2-CHP-8-SECT-3.2.5"/>
1746 <a name="INDEX-91"/><h3 class="head3">force directory security mode</h3>
1748 <p>This option works exactly the same as the <tt class="literal">force</tt>
1749 <tt class="literal">security</tt> <tt class="literal">mode</tt> option, except
1750 that it operates on directories rather than files. It also has a
1751 default value of <tt class="literal">0000</tt>, which allows Windows
1752 NT/2000/XP client users to remove any permissions from directories in
1753 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>
1766 <div class="sect1"><a name="samba2-CHP-8-SECT-4"/>
1768 <h2 class="head1">Name Mangling and Case</h2>
1770 <p><a name="INDEX-98"/><a name="INDEX-99"/><a name="INDEX-100"/><a name="INDEX-101"/>Back
1771 in the days of DOS and Windows 3.1, every filename was limited to
1772 eight uppercase characters, followed by a dot, and three more
1773 uppercase characters. This was known as the <em class="firstterm">8.3
1774 format</em> and was a huge nuisance. Windows 95/98/Me, Windows
1775 NT/2000/XP, and Unix have since relaxed this problem by allowing
1776 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
1777 popular operating systems.</p>
1779 <a name="samba2-CHP-8-TABLE-4"/><h4 class="head4">Table 8-4. Operating system filename limitations</h4><table border="1">
1785 <p>Operating system</p>
1788 <p>File-naming rules</p>
1795 <p>DOS 6.22 or below</p>
1798 <p>Eight characters followed by a dot followed by a three-letter
1799 extension (8.3 format); case-insensitive</p>
1804 <p>Windows 3.1 for Workgroups</p>
1807 <p>Eight characters followed by a dot followed by a three-letter
1808 extension (8.3 format); case-insensitive</p>
1813 <p>Windows 95/98/Me</p>
1816 <p>255 characters; case-insensitive but case-preserving</p>
1821 <p>Windows NT/2000/XP</p>
1824 <p>255 characters; case-insensitive but case-preserving</p>
1832 <p>255 characters; case-sensitive</p>
1838 <p>Samba still has to remain backward-compatible with network clients
1839 that store files in just the 8.3 format, such as Windows for
1840 Workgroups. If a user creates a file on a share called
1841 <em class="emphasis">antidisestablishmentarianism.txt</em>, a Windows for
1842 Workgroups client cannot tell it apart from another file in the same
1843 directory called <em class="emphasis">antidisease.txt</em>. Like Windows
1844 95/98/Me and Windows NT/2000/XP, Samba has to employ a special method
1845 for translating a long filename to an 8.3 filename in such a way that
1846 similar filenames will not cause collisions. This is called
1847 <em class="firstterm">name mangling</em>, and Samba deals with this in a
1848 manner that is similar, but not identical to, Windows 95 and its
1852 <div class="sect2"><a name="samba2-CHP-8-SECT-4.1"/>
1854 <h3 class="head2">The Samba Mangling Operation</h3>
1856 <p><a name="INDEX-102"/>Here is how Samba mangles a long
1857 filename into an 8.3 filename:</p>
1860 <p>If the original filename does not begin with a dot, the first five
1861 characters before the dot (if there is one) are converted to
1862 uppercase. These characters are used as the first five characters of
1863 the 8.3 mangled filename.</p>
1865 <p>If the original filename begins with a dot, the dot is removed and
1866 then the previous step is performed on what is left.</p>
1868 <p>These characters are immediately followed by a special mangling
1869 character: by default, a tilde (~), although Samba allows you to
1870 change this character.</p>
1872 <p>The base of the long filename before the last period is hashed into a
1873 two-character code; parts of the name after the last dot can be used
1874 if necessary. This two-character code is appended to the filename
1875 after the mangling character.</p>
1877 <p>The first three characters after the last dot (if there is one) of
1878 the original filename are converted to uppercase and appended onto
1879 the mangled name as the extension. If the original filename began
1880 with a dot, three underscores ( <tt class="literal">_ _ _</tt> ) are used
1881 as the extension instead.</p>
1883 <p>Here are some examples:</p>
1885 <blockquote><pre class="code">virtuosity.dat VIRTU~F1.DAT
1886 .htaccess HTACC~U0._ _ _
1887 hello.java HELLO~1F.JAV
1888 team.config.txt TEAMC~04.TXT
1889 antidisestablishmentarianism.txt ANTID~E3.TXT
1890 antidisease.txt ANTID~9K.TXT</pre></blockquote>
1892 <p>Using these rules will allow Windows for Workgroups to differentiate
1893 the two files on behalf of the poor individual who is forced to see
1894 the network through the eyes of that operating system. Note that the
1895 same long filename should always hash to the same mangled name with
1896 Samba; this doesn't always happen with Windows. The
1897 downside of this approach is that there can still be collisions;
1898 however, the chances are greatly reduced.</p>
1900 <p>You generally want to use the mangling configuration options with
1901 only the oldest clients. We recommend doing this without disrupting
1902 other clients by adding an <tt class="literal">include</tt> directive to
1903 the <em class="filename">smb.conf</em> file:</p>
1905 <blockquote><pre class="code">[global]
1906 include = /usr/local/samba/lib/smb.conf.%a</pre></blockquote>
1908 <p>This resolves to <em class="filename">smb.conf.WfWg</em> when a Windows
1909 for Workgroups client attaches. Now you can create a file
1910 <em class="filename">/usr/local/samba/lib/smb.conf.WfWg</em>, which might
1911 contain these options:</p>
1913 <blockquote><pre class="code">[global]
1915 default case = upper
1917 short preserve case = no
1919 mangled names= yes</pre></blockquote>
1921 <p>If you are not using Windows for Workgroups, you probably do not need
1922 to change any of these options from their defaults.</p>
1925 <div class="sect3"><a name="samba2-CHP-8-SECT-4.1.1"/>
1927 <h3 class="head3">Representing and resolving filenames with Samba</h3>
1929 <p><a name="INDEX-103"/>Another item that we should
1930 point out is that there is a difference between how an operating
1931 system <em class="emphasis">represents</em> a file and how it
1932 <em class="emphasis">resolves</em> it. For example, you have likely run
1933 across a file on a Windows system called
1934 <em class="filename">README.TXT</em>. The file can be represented by the
1935 operating system entirely in uppercase letters. However, if you open
1936 an MS-DOS command prompt and enter the command:</p>
1938 <blockquote><pre class="code">C:\> <tt class="userinput"><b>notepad readme.txt</b></tt></pre></blockquote>
1940 <p>the all-caps file is loaded into the editing program, even though you
1941 typed the name in lowercase letters.</p>
1943 <p>This is because the Windows 95/98/Me and Windows NT/2000/XP families
1944 of operating systems resolve filenames in a case-insensitive manner,
1945 even though the files are represented in a case-sensitive manner.
1946 Unix-based operating systems, on the other hand, always resolve files
1947 in a case-sensitive manner; if you try to edit
1948 <em class="filename">README.TXT</em> with the command:</p>
1950 <blockquote><pre class="code">$ <tt class="userinput"><b>vi readme.txt</b></tt></pre></blockquote>
1952 <p>you will likely be editing the empty buffer of a new file.</p>
1954 <p><a name="INDEX-104"/>Here is how Samba handles case: if the
1955 <tt class="literal">preserve</tt><a name="INDEX-105"/> <tt class="literal">case</tt> is set
1956 to <tt class="literal">yes</tt>, Samba will always use the case provided by
1957 the operating system for representing (not resolving) filenames. If
1958 it is set to <tt class="literal">no</tt>, it will use the case specified by
1959 the <tt class="literal">default</tt><a name="INDEX-106"/> <tt class="literal">case</tt> option.
1960 The same is true for
1961 <tt class="literal">short</tt><a name="INDEX-107"/>
1962 <tt class="literal">preserve</tt> <tt class="literal">case</tt>. If this option
1963 is set to <tt class="literal">yes</tt>, Samba will use the default case of
1964 the operating system for representing 8.3 filenames; otherwise, it
1965 will use the case specified by the <tt class="literal">default</tt>
1966 <tt class="literal">case</tt> option. Finally, Samba will always resolve
1967 filenames in its shares based on the value of the
1968 <tt class="literal">case</tt> <tt class="literal">sensitive</tt> option.</p>
1977 <div class="sect2"><a name="samba2-CHP-8-SECT-4.2"/>
1979 <h3 class="head2">Mangling Options</h3>
1981 <p><a name="INDEX-108"/><a name="INDEX-109"/>Samba
1982 allows more refined instructions on how it should perform name
1983 mangling, including those controlling the case sensitivity, the
1984 character inserted to form a mangled name, and the ability to map
1985 filenames manually from one format to another. These options are
1986 shown in <a href="ch08.html#samba2-CHP-8-TABLE-5">Table 8-5</a>.</p>
1988 <a name="samba2-CHP-8-TABLE-5"/><h4 class="head4">Table 8-5. Name-mangling options</h4><table border="1">
2016 <p><tt class="literal">case sensitive</tt></p>
2018 <p><tt class="literal">(casesignames)</tt></p>
2024 <p>If <tt class="literal">yes</tt>, treats filenames as case-sensitive
2025 (Windows doesn't).</p>
2028 <p><tt class="literal">no</tt></p>
2036 <p><tt class="literal">default case</tt></p>
2039 <p>string (<tt class="literal">upper</tt> or <tt class="literal">lower</tt>)</p>
2042 <p>Case to assume as default (used only when preserve case is
2043 <tt class="literal">no</tt>).</p>
2054 <p><tt class="literal">preserve case</tt></p>
2060 <p>If <tt class="literal">yes</tt>, keep the case the client supplied (i.e.,
2061 do not convert to <tt class="literal">default</tt>
2062 <tt class="literal">case</tt>).</p>
2065 <p><tt class="literal">yes</tt></p>
2073 <p><tt class="literal">short preserve case</tt></p>
2079 <p>If <tt class="literal">yes</tt>, preserve case of 8.3-format names that the
2080 client provides.</p>
2083 <p><tt class="literal">yes</tt></p>
2091 <p><tt class="literal">mangled names</tt></p>
2097 <p>Mangles long names into 8.3 DOS format.</p>
2100 <p><tt class="literal">yes</tt></p>
2108 <p><tt class="literal">mangle case</tt></p>
2114 <p>Mangle a name if it is mixed case.</p>
2117 <p><tt class="literal">no</tt></p>
2125 <p><tt class="literal">mangling char</tt></p>
2128 <p>string (single character)</p>
2131 <p>Gives mangling character.</p>
2134 <p><tt class="literal">~</tt></p>
2142 <p><tt class="literal">mangled stack</tt></p>
2148 <p>Number of mangled names to keep on the local mangling stack.</p>
2151 <p><tt class="literal">50</tt></p>
2159 <p><tt class="literal">mangled map</tt></p>
2162 <p>string (list of patterns)</p>
2165 <p>Allows mapping of filenames from one format into another.</p>
2178 <div class="sect3"><a name="samba2-CHP-8-SECT-4.2.1"/>
2180 <a name="INDEX-110"/><h3 class="head3">case sensitive</h3>
2182 <p>This share-level option, which has the obtuse synonym
2183 <tt class="literal">casesignames</tt>, specifies whether Samba should
2184 preserve case when resolving filenames in a specific share. The
2185 default value for this option is <tt class="literal">no</tt>, which is how
2186 Windows handles file resolution. If clients are using an operating
2187 system that takes advantage of case-sensitive filenames, you can set
2188 this configuration option to <tt class="literal">yes</tt> as shown here:</p>
2190 <blockquote><pre class="code">[accounting]
2191 case sensitive = yes</pre></blockquote>
2193 <p>Otherwise, we recommend that you leave this option set to its default.</p>
2200 <div class="sect3"><a name="samba2-CHP-8-SECT-4.2.2"/>
2202 <h3 class="head3">default case</h3>
2204 <p>The <tt class="literal">default</tt><a name="INDEX-111"/> <tt class="literal">case</tt> option
2205 is used with <tt class="literal">preserve</tt> <tt class="literal">case</tt>.
2206 This specifies the default case (upper or lower) Samba uses to create
2207 a file on one of its shares on behalf of a client. The default case
2208 is <tt class="literal">lower</tt>, which means that newly created files
2209 will have lowercase names. If you need to, you can override this
2210 global option by specifying the following:</p>
2212 <blockquote><pre class="code">[global]
2213 default case = upper</pre></blockquote>
2215 <p>If you specify this value, the names of newly created files are
2216 translated into uppercase and cannot be overridden in a program. We
2217 recommend that you use the default value unless you are dealing with
2218 a Windows for Workgroups or other 8.3 client, in which case it should
2219 be <tt class="literal">upper</tt>.</p>
2226 <div class="sect3"><a name="samba2-CHP-8-SECT-4.2.3"/>
2228 <a name="INDEX-112"/><h3 class="head3">preserve case</h3>
2230 <p>This option specifies whether a file created by Samba on behalf of
2231 the client is created with the case provided by the client operating
2232 system or the case specified by the earlier
2233 <tt class="literal">default</tt> <tt class="literal">case</tt> configuration
2234 option. The default value is <tt class="literal">yes</tt>, which uses the
2235 case provided by the client operating system. If it is set to
2236 <tt class="literal">no</tt>, the value of the <tt class="literal">default</tt>
2237 <tt class="literal">case</tt> option (upper or lower) is used.</p>
2239 <p>Note that this option does not handle 8.3 file requests sent from the
2240 client—see the upcoming <tt class="literal">short</tt>
2241 <tt class="literal">preserve</tt> <tt class="literal">case</tt> option. You might
2242 want to set this option to <tt class="literal">yes</tt>, for example, if
2243 applications that create files on the Samba server demand the file be
2244 all uppercase. If instead you want Samba to mimic the behavior of a
2245 Windows NT filesystem, you can leave this option set to its default,
2246 <tt class="literal">yes</tt>.</p>
2253 <div class="sect3"><a name="samba2-CHP-8-SECT-4.2.4"/>
2255 <a name="INDEX-113"/><h3 class="head3">short preserve case</h3>
2257 <p>This option specifies whether an 8.3 filename created by Samba on
2258 behalf of the client is created with the default case of the client
2259 operating system or the case specified by the
2260 <tt class="literal">default</tt> <tt class="literal">case</tt> configuration
2261 option. The default value is <tt class="literal">yes</tt>, which uses the
2262 case provided by the client operating system. You can let Samba
2263 choose the case through the <tt class="literal">default</tt>
2264 <tt class="literal">case</tt> option by setting it as follows:</p>
2266 <blockquote><pre class="code">[global]
2267 short preserve case = no</pre></blockquote>
2269 <p>If you want to force Samba to mimic the behavior of a Windows NT
2270 filesystem, you can leave this option set to its default,
2271 <tt class="literal">yes</tt>.</p>
2278 <div class="sect3"><a name="samba2-CHP-8-SECT-4.2.5"/>
2280 <a name="INDEX-114"/><h3 class="head3">mangled names</h3>
2282 <p>This share-level option specifies whether Samba will mangle filenames
2283 for 8.3 clients. If the option is set to <tt class="literal">no</tt>, Samba
2284 will not mangle the names, and (depending on the client) they will
2285 either be invisible or appear truncated to those using 8.3 operating
2286 systems. The default value is <tt class="literal">yes</tt>. You can
2287 override it per share as follows:</p>
2289 <blockquote><pre class="code">[data]
2290 mangled names = no</pre></blockquote>
2297 <div class="sect3"><a name="samba2-CHP-8-SECT-4.2.6"/>
2299 <a name="INDEX-115"/><h3 class="head3">mangle case</h3>
2301 <p>This option tells Samba whether it should mangle filenames that are
2302 not composed entirely of the case specified using the
2303 <tt class="literal">default</tt> <tt class="literal">case</tt> configuration
2304 option. The default for this option is <tt class="literal">no</tt>. If you
2305 set it to <tt class="literal">yes</tt>, you should be sure that all clients
2306 can handle the mangled filenames that result. You can override it per
2307 share as follows:</p>
2309 <blockquote><pre class="code">[data]
2310 mangle case = yes</pre></blockquote>
2312 <p>We recommend that you leave this option alone unless you have a
2313 well-justified need to change it.</p>
2320 <div class="sect3"><a name="samba2-CHP-8-SECT-4.2.7"/>
2322 <a name="INDEX-116"/><h3 class="head3">mangling char</h3>
2324 <p>This share-level option specifies the mangling character used when
2325 Samba mangles filenames into the 8.3 format. The default character
2326 used is a tilde (~). You can reset it to whatever character you wish.
2329 <blockquote><pre class="code">[data]
2330 mangling char = #</pre></blockquote>
2337 <div class="sect3"><a name="samba2-CHP-8-SECT-4.2.8"/>
2339 <a name="INDEX-117"/><h3 class="head3">mangled stack</h3>
2341 <p>Samba maintains a local stack of recently mangled 8.3 filenames; this
2342 stack can be used to reverse-map mangled filenames back to their
2343 original state. This is often needed by applications that create and
2344 save a file, close it, and need to modify it later. The default
2345 number of long filename/mangled filename pairs stored on this stack
2346 is 50. However, if you want to cut down on the amount of processor
2347 time used to mangle filenames, you can increase the size of the stack
2348 to whatever you wish, at the expense of memory and slightly slower
2351 <blockquote><pre class="code">[global]
2352 mangled stack = 100</pre></blockquote>
2359 <div class="sect3"><a name="samba2-CHP-8-SECT-4.2.9"/>
2361 <a name="INDEX-118"/><h3 class="head3">mangled map</h3>
2363 <p>If the default behavior of name mangling is not sufficient, you can
2364 give Samba further instructions on how to behave using the
2365 <tt class="literal">mangled</tt> <tt class="literal">map</tt> option. This option
2366 allows you to specify mapping patterns that can be used in place of
2367 name mangling performed by Samba. For example:</p>
2369 <blockquote><pre class="code">[data]
2370 mangled map =(*.database *.db) (*.class *.cls)</pre></blockquote>
2372 <p>Here, Samba is instructed to search each encountered file for
2373 characters that match the first pattern specified in the parenthesis
2374 and convert them to the modified second pattern in the parenthesis
2375 for display on an 8.3 client. This is useful in the event that name
2376 mangling converts the filename incorrectly or converts it to a format
2377 that the client cannot understand readily. Patterns are separated by
2378 whitespaces. <a name="INDEX-119"/><a name="INDEX-120"/> <a name="INDEX-121"/><a name="INDEX-122"/></p>
2391 <div class="sect1"><a name="samba2-CHP-8-SECT-5"/>
2393 <h2 class="head1">Locks and Oplocks</h2>
2395 <p><a name="INDEX-123"/><a name="INDEX-124"/><a name="INDEX-125"/><a name="INDEX-126"/>Concurrent
2396 writes to a single file are not desirable in any operating system. To
2397 prevent this, most operating systems use <em class="firstterm">locks</em>
2398 to guarantee that only one process can write to a file at a time.
2399 Operating systems traditionally lock entire files, although newer
2400 ones allow a range of bytes within a file to be locked. If another
2401 process attempts to write to a file (or section of one) that is
2402 already locked, it receives an error from the operating system and
2403 will have to wait until the lock is released.</p>
2405 <p>Samba supports the standard DOS and NT filesystem (deny-mode) locking
2406 requests—which allow only one process to write to an entire
2407 file on a server at a given time—as well as byte-range locking.
2408 In addition, Samba supports a locking mechanism known in the Windows
2409 NT world as <em class="firstterm">opportunistic locking,
2410 </em><a name="INDEX-127"/>or<em class="firstterm">
2411 </em><em class="emphasis">oplock</em> for short.</p>
2414 <div class="sect2"><a name="samba2-CHP-8-SECT-5.1"/>
2416 <h3 class="head2">Opportunistic Locking</h3>
2418 <p>Opportunistic locking allows a client to notify the Samba server that
2419 it will not only be the exclusive writer of a file, but will also
2420 cache its changes to that file locally to speed up access by reducing
2421 network activity. This can result in a large performance
2422 gain—typically 30%—while at the same time reserving
2423 network bandwidth for other purposes.</p>
2425 <p>Because exclusive access can be obtained using regular file locks,
2426 the value of opportunistic locks is not so much to lock the file as
2427 it is to cache it. In fact, a better name for opportunistic locking
2428 might be <em class="firstterm">opportunistic caching</em>.</p>
2430 <p>When Samba knows that a file in one of its shares has been oplocked
2431 by a client, it marks its version as having an opportunistic lock and
2432 waits for the client to complete work on the file, at which point it
2433 expects the client to send its changes back to the Samba server for
2434 synchronization with the copy on the server.</p>
2436 <p>If a second client requests access to that file before the first
2437 client has finished working on it, Samba sends an oplock break
2438 request to the first client. This tells the client to stop caching
2439 its changes and return the current state of the file to the server so
2440 that the interrupting client can use it as it sees fit. An
2441 opportunistic lock, however, is not a replacement for a standard
2442 deny-mode lock. It is not unheard of for the interrupting process to
2443 be granted an oplock break only to discover that the original process
2444 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>
2446 <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>
2448 <p>In most cases, the extra performance resulting from the use of
2449 oplocks is highly desirable. However, allowing the client to cache
2450 data can be a big risk if either the client or network hardware are
2451 unreliable. Suppose a client opens a file for writing, creating an
2452 oplock on it. When another client also tries to open the file, an
2453 oplock break request is sent to the first client. If this request
2454 goes unfulfilled for any reason and the second client starts writing
2455 to the file, the file can be easily corrupted as a result of the two
2456 processes writing to it concurrently. Unfortunately, this scenario is
2457 very real. Uncoordinated behavior such as this has been observed many
2458 times among Windows clients in SMB networks (with files served by
2459 Windows NT/2000 or Samba). Typically, the affected files are database
2460 files, which multiple clients open concurrently for writing.</p>
2462 <p>A more concrete example of <a name="INDEX-129"/>oplock failure occurs when database
2463 files are very large. If a client is allowed to oplock this kind of
2464 file, there can be a huge delay while the client copies the entire
2465 file from the server to cache it, even though it might need to update
2466 only one record. The situation goes from bad to worse when another
2467 client tries to open the oplocked file. The first client might need
2468 to write the entire file back to the server before the second
2469 client's file open request can succeed. This results
2470 in another huge delay (for both clients), which in practice often
2471 results in a failed open due to a timeout on the second client,
2472 perhaps along with a message warning of possible database corruption!</p>
2474 <p>If you are having problems of this variety, you can turn off oplocks
2475 for the affected files by using the
2476 <tt class="literal">veto</tt><a name="INDEX-130"/> <tt class="literal">oplock</tt>
2477 <tt class="literal">files</tt> parameter:</p>
2479 <blockquote><pre class="code">[dbdata]
2480 veto oplock files = /*.dbm/</pre></blockquote>
2482 <p>Use the value of the parameter (a list of filename-matching patterns
2483 separated by slash characters) to match all the files in the share
2484 that might be a source of trouble. The syntax of this parameter is
2485 similar to that of the <tt class="literal">veto</tt>
2486 <tt class="literal">files</tt> parameter.</p>
2488 <p>If you want to be really careful and can live with reduced
2489 performance, you can turn off oplocks altogether, preventing the
2490 oplock break problem from ever occurring:</p>
2492 <blockquote><pre class="code">[global]
2493 oplocks = no</pre></blockquote>
2495 <p>This disables oplocks for all files in all shares served by the Samba
2496 server. If you wish to disable oplocks in just a specific share, you
2497 can specify the <tt class="literal">oplocks</tt> <tt class="literal">=</tt>
2498 <tt class="literal">no</tt> parameter in just that share:</p>
2500 <blockquote><pre class="code">[database]
2501 oplocks = no</pre></blockquote>
2503 <p>This example allows other shares, which might have less sensitive
2504 data, to attain better performance, while trading performance for
2505 better data integrity for files in the <tt class="literal">[database]</tt>
2512 <div class="sect2"><a name="samba2-CHP-8-SECT-5.2"/>
2514 <h3 class="head2">Unix and Oplocks</h3>
2516 <p><a name="INDEX-131"/>Most of the time, oplocks help Windows
2517 client systems cooperate to avoid overwriting each
2518 other's changes. Unix systems also have file-locking
2519 mechanisms to allow Unix processes to cooperate with each other. But
2520 if a file stored on a Samba system is accessed by both a Windows
2521 network client and a local Unix process—without an additional
2522 coordination between the two systems—the Unix process could
2523 easily ride roughshod over an oplock.</p>
2525 <p>Some Unix systems have enhanced kernels that understand the Windows
2526 oplocks maintained by Samba. Currently the support exists only in SGI
2529 <p>If you leave oplocks enabled and your Unix system does not support
2530 kernel oplocks, you could end up with corrupted data when somebody
2531 runs a Unix process that reads or writes a file that Windows users
2532 also access. This is another case where the
2533 <tt class="literal">veto</tt><a name="INDEX-132"/> <tt class="literal">oplock</tt>
2534 <tt class="literal">files</tt> parameter can be used, assuming you can
2535 anticipate which Samba files are used by both Windows users and Unix
2536 users. For example, suppose the <tt class="literal">[usrfiles]</tt> share
2537 contains some ASCII text files with the <em class="filename">.txt</em>
2538 filename extension and OpenOffice word processor documents with the
2539 <em class="filename">.doc</em> filename extension, which Unix and Windows
2540 users both modify. We can use <tt class="literal">veto</tt>
2541 <tt class="literal">oplock</tt> <tt class="literal">files</tt> like this:</p>
2543 <blockquote><pre class="code">[usrfiles]
2544 veto oplock files = /*.txt/*.doc/</pre></blockquote>
2546 <p>This will suppress the use of oplocks on <em class="filename">.txt</em>
2547 and <em class="filename">.doc</em> files, which will suppress client
2548 caching, while allowing the Windows and Unix programs to use regular
2549 file locking to prevent concurrent writes to the same file.</p>
2555 <div class="sect2"><a name="samba2-CHP-8-SECT-5.3"/>
2557 <h3 class="head2">Locks and Oplocks Configuration Options</h3>
2559 <p><a name="INDEX-133"/><a name="INDEX-134"/>Samba's options for
2560 locks and oplocks are given in <a href="ch08.html#samba2-CHP-8-TABLE-6">Table 8-6</a>.</p>
2562 <a name="samba2-CHP-8-TABLE-6"/><h4 class="head4">Table 8-6. Locks and oplocks configuration options</h4><table border="1">
2590 <p><tt class="literal">locking</tt></p>
2596 <p>If <tt class="literal">yes</tt>, turns on byte-range locks.</p>
2599 <p><tt class="literal">yes</tt></p>
2607 <p><tt class="literal">strict</tt> <tt class="literal">locking</tt></p>
2613 <p>If <tt class="literal">yes</tt>, denies access to an entire file if a
2614 byte-range lock exists in it.</p>
2617 <p><tt class="literal">no</tt></p>
2625 <p><tt class="literal">posix locking</tt></p>
2631 <p>If <tt class="literal">yes</tt>, maps oplocks to POSIX locks on the local
2635 <p><tt class="literal">yes</tt></p>
2643 <p><tt class="literal">oplocks</tt></p>
2649 <p>If <tt class="literal">yes</tt>, turns on local caching of files on the
2650 client for this share.</p>
2653 <p><tt class="literal">yes</tt></p>
2661 <p><tt class="literal">kernel</tt> <tt class="literal">oplocks</tt></p>
2667 <p>If <tt class="literal">yes</tt>, indicates that the kernel supports oplocks.</p>
2670 <p><tt class="literal">yes</tt></p>
2678 <p><tt class="literal">level2 oplocks</tt></p>
2684 <p>If <tt class="literal">yes</tt>, allows oplocks to downgrade to read-only.</p>
2687 <p><tt class="literal">yes</tt></p>
2695 <p><tt class="literal">fake oplocks</tt></p>
2701 <p>If <tt class="literal">yes</tt>, tells client the lock was obtained, but
2702 doesn't actually lock it.</p>
2705 <p><tt class="literal">no</tt></p>
2713 <p><tt class="literal">blocking</tt> <tt class="literal">locks</tt></p>
2719 <p>Allows lock requestor to wait for the lock to be granted.</p>
2722 <p><tt class="literal">yes</tt></p>
2730 <p><tt class="literal">veto oplock</tt> <tt class="literal">files</tt></p>
2733 <p>string (list of filenames)</p>
2736 <p>Does not oplock specified files.</p>
2747 <p><tt class="literal">lock</tt> <tt class="literal">directory</tt></p>
2750 <p>string (fully qualified pathname)</p>
2753 <p>Sets the location where various Samba files, including locks, are
2757 <p>As specified in Samba makefile</p>
2767 <div class="sect3"><a name="samba2-CHP-8-SECT-5.3.1"/>
2769 <h3 class="head3">locking</h3>
2771 <p>The <tt class="literal">locking</tt><a name="INDEX-135"/> option can be used to tell
2772 Samba to engage or disengage server-side byte-range locks on behalf
2773 of the client. Samba implements byte-range locks on the server side
2774 with normal Unix advisory locks and consequently prevents other
2775 properly behaved Unix processes from overwriting a locked byte range.</p>
2777 <p>This option can be specified per share as follows:</p>
2779 <blockquote><pre class="code">[accounting]
2780 locking = yes</pre></blockquote>
2782 <p>If the <tt class="literal">locking</tt> option is set to
2783 <tt class="literal">yes</tt>, the requestor is delayed until the holder of
2784 either type of lock releases it (or crashes). If, however, the option
2785 is set to <tt class="literal">no</tt>, no byte-range locks are kept for the
2786 files, although requests to lock and unlock files will appear to
2787 succeed. The option is set to <tt class="literal">yes</tt> by default;
2788 however, you can turn this option off if you have read-only media.</p>
2795 <div class="sect3"><a name="samba2-CHP-8-SECT-5.3.2"/>
2797 <a name="INDEX-136"/><h3 class="head3">strict locking</h3>
2799 <p>This option checks every file access for a byte-range lock on the
2800 range of bytes being accessed. This is typically not needed if a
2801 client adheres to all the locking mechanisms in place. This option is
2802 set to <tt class="literal">no</tt> by default; however, you can reset it
2803 per share as follows:</p>
2805 <blockquote><pre class="code">[accounting]
2806 strict locking = yes</pre></blockquote>
2808 <p>If this option is set to <tt class="literal">yes</tt>, mandatory locks are
2809 enforced on any file with byte-range locks.</p>
2816 <div class="sect3"><a name="samba2-CHP-8-SECT-5.3.3"/>
2818 <a name="INDEX-137"/><h3 class="head3">posix locking</h3>
2820 <p>On systems that support POSIX locking, Samba automatically maps
2821 oplocks to POSIX locks. This behavior can be disabled by setting
2822 <tt class="literal">posix</tt> <tt class="literal">locking</tt>
2823 <tt class="literal">=</tt> <tt class="literal">no</tt>. You should never need to
2824 change the default behavior, which is <tt class="literal">posix</tt>
2825 <tt class="literal">locking</tt> <tt class="literal">=</tt>
2826 <tt class="literal">yes</tt>.</p>
2833 <div class="sect3"><a name="samba2-CHP-8-SECT-5.3.4"/>
2835 <a name="INDEX-138"/><h3 class="head3">oplocks</h3>
2837 <p>This option enables or disables support for oplocks on the client.
2838 The option is enabled by default. However, you can disable it with
2839 the following command:</p>
2841 <blockquote><pre class="code">[data]
2842 oplocks = no</pre></blockquote>
2844 <p>If you are in an extremely unstable network environment or have many
2845 clients that cannot take advantage of opportunistic locking, it might
2846 be better to shut this Samba feature off. If the host operating
2847 system does not support kernel oplocks, oplocks should be disabled if
2848 users are accessing the same files from both Unix applications (such
2849 as <em class="emphasis">vi</em>) and SMB clients.</p>
2856 <div class="sect3"><a name="samba2-CHP-8-SECT-5.3.5"/>
2858 <a name="INDEX-139"/><h3 class="head3">kernel oplocks</h3>
2860 <p>If a Unix application on the Samba host system (that is not part of
2861 the Samba suite) tries to open a file for writing that Samba has
2862 oplocked to a Windows client, it is likely to succeed (depending on
2863 the operating system), and both Samba and the client are never aware
2866 <p>Some versions of Unix have support for oplocks in the kernel that can
2867 work along with Samba's oplocks. In this case, the
2868 Unix process trying to open the file is suspended while Samba directs
2869 the client to write its copy back. After that has happened, the
2870 operating system allows the open to complete. At the time of this
2871 writing, this feature is supported only by SGI Irix and Linux.</p>
2878 <div class="sect3"><a name="samba2-CHP-8-SECT-5.3.6"/>
2880 <a name="INDEX-140"/><h3 class="head3">level2 oplocks</h3>
2882 <p>Windows NT/2000/XP clients can downgrade their read-write oplocks to
2883 read-only oplocks when another client opens the same file. This can
2884 result in significant improvements in performance on files that are
2885 written infrequently or not at all—especially
2886 executables—because all clients can then maintain a read-ahead
2887 cache for the file. By default, <tt class="literal">level2</tt>
2888 <tt class="literal">oplocks</tt> is set to <tt class="literal">yes</tt>, and you
2889 probably won't need to change it.</p>
2891 <p>Currently, Samba cannot support level 2 oplocks along with kernel
2892 oplocks and automatically disables level 2 oplocks when kernel
2893 oplocks are in use. (This might change in future releases as improved
2894 support for oplocks is added by the Samba developers.) If you are
2895 running Samba on a host system that supports kernel oplocks, you must
2896 set <tt class="literal">kernel</tt> <tt class="literal">oplocks</tt>
2897 <tt class="literal">=</tt> <tt class="literal">no</tt> to enable support for
2898 level 2 oplocks.</p>
2900 <p>Disabling oplocks with <tt class="literal">oplocks</tt>
2901 <tt class="literal">=</tt> <tt class="literal">no</tt> also disables level 2
2904 <p>Samba can automatically detect its Unix host's
2905 support of kernel oplocks and will set the value of
2906 <tt class="literal">kernel</tt> <tt class="literal">oplocks</tt> automatically.
2907 You should never need to set this option in your Samba configuration
2915 <div class="sect3"><a name="samba2-CHP-8-SECT-5.3.7"/>
2917 <a name="INDEX-141"/><h3 class="head3">fake oplocks</h3>
2919 <p>When this option is set to <tt class="literal">yes</tt>, Samba pretends to
2920 allow oplocks rather than actually supporting them. If this option is
2921 enabled on a read-only share (such as a shared CD-ROM drive), all
2922 clients are told that the files are available for opportunistic
2923 locking and never warned of simultaneous access. As a result, Windows
2924 clients cache more of the file's data and obtain
2925 much better performance.</p>
2927 <p>This option was added to Samba before opportunistic-locking support
2928 was available, and it is now generally considered better to use real
2929 oplocks. Do not ever enable <tt class="literal">fake</tt>
2930 <tt class="literal">oplocks</tt> on a read/write share.</p>
2937 <div class="sect3"><a name="samba2-CHP-8-SECT-5.3.8"/>
2939 <h3 class="head3">blocking locks</h3>
2941 <p>Samba also supports <em class="firstterm">blocking locks</em>, a minor
2942 variant of range locks. Here, if the range of bytes is not available,
2943 the client specifies an amount of time that it's
2944 willing to wait. The server then caches the lock request,
2945 periodically checking to see if the file is available. If it is, it
2946 notifies the client; however, if time expires, Samba will tell the
2947 client that the request has failed. This strategy prevents the client
2948 from continually polling to see if the lock is available.</p>
2950 <p>You can disable this option per share as follows:</p>
2952 <blockquote><pre class="code">[accounting]
2953 blocking locks = no</pre></blockquote>
2955 <p>When set to <tt class="literal">yes</tt>, blocking locks are enforced on
2956 the file. If this option is set to <tt class="literal">no</tt>, Samba
2957 behaves as if normal locking mechanisms are in place on the file. The
2958 default is <tt class="literal">yes</tt>.</p>
2965 <div class="sect3"><a name="samba2-CHP-8-SECT-5.3.9"/>
2967 <a name="INDEX-142"/><h3 class="head3">veto oplock files</h3>
2969 <p>You can provide a list of filenames that are never granted
2970 opportunistic locks with the <tt class="literal">veto</tt>
2971 <tt class="literal">oplock</tt> <tt class="literal">files</tt> option. This
2972 option can be set either globally or on a per-share basis. For
2975 <blockquote><pre class="code">veto oplock files = /*.bat/*.htm/</pre></blockquote>
2977 <p>The value of this option is a series of patterns. Each pattern entry
2978 must begin, end, or be separated from another with a slash ( / )
2979 character, even if only one pattern is listed. Asterisks can be used
2980 as a wildcard to represent zero or more characters. Questions marks
2981 can be used to represent exactly one character.</p>
2983 <p>We recommend that you disable oplocks on any files that are meant to
2984 be updated by Unix or are intended for simultaneous sharing by
2985 several processes.</p>
2992 <div class="sect3"><a name="samba2-CHP-8-SECT-5.3.10"/>
2994 <a name="INDEX-143"/><h3 class="head3">lock directory</h3>
2996 <p>This option (sometimes called <tt class="literal">lock</tt>
2997 <tt class="literal">dir</tt>) specifies the location of a directory where
2998 Samba will store SMB deny-mode lock files. Samba stores other files
2999 in this directory as well, such as browse lists and its shared memory
3000 file. If WINS is enabled, the WINS database is written to this
3001 directory as well. The default for this option is specified in the
3002 Samba makefile; it is typically
3003 <em class="filename">/usr/local/samba/var/locks</em>. You can override
3004 this location as follows:</p>
3006 <blockquote><pre class="code">[global]
3007 lock directory = /usr/local/samba/locks</pre></blockquote>
3009 <p>You typically would not need to override this option, unless you want
3010 to move the lock files to a more standard location, such as
3011 <em class="filename">/var/spool/locks</em>. <a name="INDEX-144"/> <a name="INDEX-145"/><a name="INDEX-146"/></p>
3024 <div class="sect1"><a name="samba2-CHP-8-SECT-6"/>
3026 <h2 class="head1">Connection Scripts</h2>
3028 <p><a name="INDEX-147"/><a name="INDEX-148"/><a name="INDEX-149"/>Samba supports a mechanism called
3029 <em class="firstterm">connection scripts</em>, by which commands can be
3030 executed on the server as clients connect to a share or later
3031 disconnect from it. By using configuration file variables along with
3032 some custom programming, you can create connection scripts that
3033 perform a wide range of functions. As a simple example, here is a
3034 "quick and dirty" way to monitor
3035 connections to shares on the Samba server in real time. First, the
3036 value of the <tt class="literal">preexec</tt><a name="INDEX-150"/> parameter is set as
3039 <blockquote><pre class="code">[global]
3040 preexec = /bin/echo %u at %m connected to //%L/%S on %T >>/tmp/smblog</pre></blockquote>
3042 <p>This causes information about the user and the connection to be
3043 written to the file <em class="filename">/tmp/smblog</em> whenever any
3044 client connects to any share. To watch clients connect, run the
3045 following command:</p>
3047 <blockquote><pre class="code">$ <tt class="userinput"><b>tail -f /tmp/smblog</b></tt>
3048 jay at maya connected to //toltec/data on 2002/11/21 21:21:15
3049 david at apache connected to //toltec/techs on 2002/11/21 21:21:57
3050 sally at seminole connected to //toltec/payroll on 2002/11/21 21:22:16
3051 martha at dine connected to //toltec/profiles on 2002/11/21 21:23:38
3052 martha at dine connected to //toltec/netlogon on 2002/11/21 21:23:39
3053 martha at dine connected to //toltec/martha on 2002/11/21 21:23:40
3054 aaron at huastec connected to //toltec/netlogon on 2002/11/21 21:24:19
3055 aaron at huastec connected to //toltec/aaron on 2002/11/21 21:24:20</pre></blockquote>
3057 <p>With the <em class="emphasis">-f</em> option, the
3058 <em class="emphasis">tail</em> command monitors
3059 <em class="filename">/tmp/smblog</em> and prints additional output as new
3060 data is appended to the file. Every time a new connection is made, an
3061 additional line is printed, showing the output of the
3062 <tt class="literal">preexec</tt> command. Notice the lines resulting from
3063 connections by user <tt class="literal">martha</tt> and
3064 <tt class="literal">aaron</tt>. User <tt class="literal">martha</tt> logged on to
3065 the domain from a Windows NT client, which accessed the
3066 <tt class="literal">[profiles]</tt> share to download her profile, then the
3067 <tt class="literal">[netlogon]</tt> share to read the logon script, and
3068 then her home directory (because her logon script contains a
3069 <tt class="literal">net</tt> <tt class="literal">use</tt> <tt class="literal">H</tt>:
3070 <tt class="literal">/home</tt> command) to connect her home directory to
3071 drive letter H. The connections from <tt class="literal">aaron</tt> are
3072 similar, except that he connected from a Windows 98 system, which
3073 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>
3075 <p>A more advanced use of
3076 <a name="INDEX-151"/><a name="INDEX-152"/>connection scripts is to monitor the
3077 contents of users' home directories and/or other
3078 shared directories and perform checks ensuring that local
3079 administrative policies are followed. Checked items might include the
3083 <p>Disk usage, on a per-share, per-directory, or per-file basis</p>
3085 <p>Types of files stored on the server</p>
3087 <p>Whether filenames follow naming guidelines</p>
3089 <p>Whether viruses have copied themselves to the Samba server</p>
3091 <p>To handle this kind of task, a shell script or other program would be
3092 written to perform the checks and take appropriate actions, such as
3093 removing offending files. The <tt class="literal">root</tt>
3094 <tt class="literal">preexec</tt> parameter would be used to run the command
3095 as the root user, using configuration file variables to pass
3096 arguments. For example:</p>
3098 <blockquote><pre class="code">[homes]
3099 root preexec = admin_checks %S
3100 root preexec close = yes</pre></blockquote>
3102 <p>In this example, a specially written administrative checking program
3103 (<em class="emphasis">admin_checks</em>) is used to monitor
3104 users' home directories on the Samba server. The
3105 <tt class="literal">%S</tt> variable is used to pass the name of the home
3106 directory to the script. The
3107 <tt class="literal">root</tt><a name="INDEX-153"/> <tt class="literal">preexec</tt>
3108 <tt class="literal">close</tt> parameter has been set to
3109 <tt class="literal">yes</tt> so that if <em class="emphasis">admin_checks</em>
3110 detects a serious violation of local policy, it can exit with a
3111 nonzero status, and the client is prevented from connecting.</p>
3114 <div class="sect2"><a name="samba2-CHP-8-SECT-6.1"/>
3116 <h3 class="head2">Connection Script Options</h3>
3118 <p><a href="ch08.html#samba2-CHP-8-TABLE-7">Table 8-7</a> introduces some of the configuration
3119 options provided for setting up users.</p>
3121 <a name="samba2-CHP-8-TABLE-7"/><h4 class="head4">Table 8-7. Connection script options</h4><table border="1">
3149 <p><tt class="literal">root preexec</tt></p>
3152 <p>string (Unix command)</p>
3155 <p>Sets a Unix command to run as <tt class="literal">root</tt>, before
3156 connecting to the share.</p>
3167 <p><tt class="literal">root preexec close</tt></p>
3173 <p>If set to <tt class="literal">yes</tt>, nonzero exit status of
3174 <tt class="literal">root preexec</tt> command will disconnect.</p>
3177 <p><tt class="literal">no</tt></p>
3185 <p><tt class="literal">preexec</tt> <tt class="literal">(exec)</tt></p>
3188 <p>string (Unix command)</p>
3191 <p>Sets a Unix command to run as the user before connecting to the share.</p>
3202 <p><tt class="literal">preexec close</tt></p>
3208 <p>If set to <tt class="literal">yes</tt>, nonzero exit status of
3209 <tt class="literal">preexec</tt> command will disconnect.</p>
3212 <p><tt class="literal">no</tt></p>
3220 <p><tt class="literal">postexec</tt></p>
3223 <p>string (Unix command)</p>
3226 <p>Sets a Unix command to run as the user after disconnecting from the
3238 <p><tt class="literal">root</tt> <tt class="literal">postexec</tt></p>
3241 <p>string (Unix command)</p>
3244 <p>Sets a Unix command to run as <tt class="literal">root</tt> after
3245 disconnecting from the share.</p>
3258 <div class="sect3"><a name="samba2-CHP-8-SECT-6.1.1"/>
3260 <a name="INDEX-156"/><h3 class="head3">root preexec</h3>
3262 <p>This option specifies as its value a Unix command to be run
3263 <em class="emphasis">as the root user</em> before any connection to a
3264 share is completed. You should use this option specifically for
3265 performing actions that require root privilege.</p>
3267 <p>To ensure security, users should never be able to modify the target
3268 of the <tt class="literal">root</tt> <tt class="literal">preexec</tt> command. In
3269 addition, unless you explicitly redirect it, any information the
3270 command sends to standard output will be discarded. If you intend to
3271 use any <tt class="literal">preexec</tt> or <tt class="literal">postexec</tt>
3272 script, you should ensure that it will run correctly before having
3273 Samba invoke it.</p>
3280 <div class="sect3"><a name="samba2-CHP-8-SECT-6.1.2"/>
3282 <a name="INDEX-157"/><h3 class="head3">root preexec close</h3>
3284 <p>Sometimes you might want the share to disconnect if the
3285 <tt class="literal">root</tt> <tt class="literal">preexec</tt> script fails,
3286 giving the client an error rather than allowing it to connect. For
3287 example, if you are using <tt class="literal">root</tt>
3288 <tt class="literal">preexec</tt> to mount a CD-ROM or filesystem, it would
3289 make no sense to connect the client to it in the event that the mount
3290 fails. If you specify <tt class="literal">root</tt>
3291 <tt class="literal">preexec</tt> <tt class="literal">close</tt>
3292 <tt class="literal">=</tt> <tt class="literal">yes</tt>, the share will fail to
3293 connect if the <tt class="literal">root</tt> <tt class="literal">preexec</tt>
3294 script returns a nonzero exit status.</p>
3301 <div class="sect3"><a name="samba2-CHP-8-SECT-6.1.3"/>
3303 <a name="INDEX-158"/><h3 class="head3">preexec</h3>
3305 <p>Sometimes just called <tt class="literal">exec</tt>, this option defines an
3306 ordinary unprivileged command run by Samba as the user specified by
3307 the variable <tt class="literal">%u</tt>. For example, a common use of this
3308 option is to perform logging, such as the following:</p>
3310 <blockquote><pre class="code">[homes]
3311 preexec = echo "%u connected from %m (%I)\" >>/tmp/.log</pre></blockquote>
3313 <p>You must redirect the standard output of the command if you want to
3314 use it. Otherwise, it is discarded. This warning also applies to the
3315 command's standard error output. If you intend to
3316 use a <tt class="literal">preexec</tt> script, you should ensure that it
3317 will run correctly before having Samba invoke it.</p>
3324 <div class="sect3"><a name="samba2-CHP-8-SECT-6.1.4"/>
3326 <a name="INDEX-159"/><h3 class="head3">preexec close</h3>
3328 <p>This is similar to <tt class="literal">root</tt> <tt class="literal">preexec</tt>
3329 <tt class="literal">close</tt>, except that it goes with the
3330 <tt class="literal">preexec</tt> option. By setting
3331 <tt class="literal">preexec</tt> <tt class="literal">close</tt>
3332 <tt class="literal">=</tt> <tt class="literal">yes</tt>, a
3333 <tt class="literal">preexec</tt> script that returns nonzero will cause the
3334 share to disconnect immediately.</p>
3341 <div class="sect3"><a name="samba2-CHP-8-SECT-6.1.5"/>
3343 <a name="INDEX-160"/><h3 class="head3">postexec</h3>
3345 <p>Once the user disconnects from the share, the command specified with
3346 <tt class="literal">postexec</tt> is run as the user on the Samba server to
3347 do any necessary cleanup. This option is essentially the same as the
3348 <tt class="literal">preexec</tt> option. Again, remember that the command
3349 is run as the user represented by <tt class="literal">%u</tt>, and any
3350 information sent to standard output will be ignored.</p>
3357 <div class="sect3"><a name="samba2-CHP-8-SECT-6.1.6"/>
3359 <a name="INDEX-161"/><h3 class="head3">root postexec</h3>
3361 <p>Following the <tt class="literal">postexec</tt> option, the
3362 <tt class="literal">root</tt> <tt class="literal">postexec</tt> command is run,
3363 if one has been specified. Again, this option specifies as its value
3364 a Unix command to be run <em class="emphasis">as the root user</em> before
3365 disconnecting from a share. You should use this option specifically
3366 for performing actions that require root privilege. <a name="INDEX-162"/> <a name="INDEX-163"/><a name="INDEX-164"/></p>
3379 <div class="sect1"><a name="samba2-CHP-8-SECT-7"/>
3381 <h2 class="head1">Microsoft Distributed Filesystems</h2>
3383 <p><a name="INDEX-165"/>In a
3384 large network where many shared folders are spread out over a large
3385 number of servers, it can be difficult for users to locate the
3386 resources they are trying to find. Browsing through Network
3387 Neighborhood or My Network Places can become an ordeal rather than a
3388 time-saving convenience. To mitigate this problem, Microsoft added an
3389 extension to file sharing called <em class="firstterm">Distributed
3390 filesystem</em><a name="INDEX-166"/><a name="INDEX-167"/> (Dfs). Using Dfs, it
3391 is possible to organize file shares on the network so that they
3392 appear to users as organized in a single directory tree on a single
3393 server, regardless of which servers on the network actually contain
3394 the resources. Instead of having to browse the entire network, users
3395 can go to the Dfs share and locate their data much more easily.</p>
3397 <p>Dfs can also help administrators because it provides a level of
3398 indirection between the name of a shared folder and its actual
3399 location. The Dfs share contains references to resources on the
3400 network, and when a resource is accessed, the Dfs server hands the
3401 client off to the actual server of the resource. When moving
3402 resources to another computer, the reference to the resource in the
3403 Dfs share can be redirected to the new location in one step, with the
3404 change being entirely seamless for users.</p>
3406 <p>To a limited extent, Dfs also can help improve performance for
3407 read-only shares because it provides <a name="INDEX-168"/>load balancing. It is possible
3408 to set up a Dfs reference to point to identical shares on two or more
3409 servers. The Dfs server then divides requests between the servers,
3410 dividing the client load among them. However, this works well only
3411 for static, read-only data because no provision is included in Dfs
3412 for synchronization among the servers when changes are made on any of
3416 <div class="sect2"><a name="samba2-CHP-8-SECT-7.1"/>
3418 <h3 class="head2">Windows Dfs Clients</h3>
3420 <p><a name="INDEX-169"/>Modern versions of Windows come with
3421 client-side support for Dfs, and no extra configuration is required.
3422 Support is more limited for older versions, however. Windows for
3423 Workgroups cannot function as a Dfs client at all. Windows NT 4.0
3424 must be upgraded to at least Service Pack 3 to act as a Dfs client,
3425 and the Dfs Client must be installed. Later service packs (such as
3426 Service Pack 6) include the Dfs Client. Windows 95 must also have the
3427 Dfs Client software installed to act as a Dfs client. Without the Dfs
3428 Client software, double-clicking a remote folder in a Dfs share will
3429 show an empty folder, and no error message will appear.</p>
3431 <a name="samba2-CHP-8-NOTE-140"/><blockquote class="note"><h4 class="objtitle">TIP</h4>
3432 <p>To use the Dfs Client for Windows 95 or Windows NT, you must first
3433 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>
3434 for a link to download the installation program and instructions on
3435 how to install the Dfs Client.</p>
3442 <div class="sect2"><a name="samba2-CHP-8-SECT-7.2"/>
3444 <h3 class="head2">Configuring Samba for Dfs</h3>
3446 <p><a name="INDEX-170"/>To act as a Dfs server, Samba 2.2 must
3447 be compiled with the <tt class="literal">--with-msdfs</tt> configure
3448 option. (See <a href="ch02.html">Chapter 2</a> for instructions on
3449 configuring and compiling Samba.) Samba 3.0 includes Dfs support by
3450 default and does not need to be compiled with the
3451 <tt class="literal">--with-msdfs</tt> configure option.</p>
3453 <p>Once a Dfs-enabled Samba server is running, there are just two steps
3454 to serving a Dfs share. First we will set up a Dfs root directory on
3455 the server, and then we will modify the <em class="filename">smb.conf</em>
3456 configuration file to enable the share.</p>
3459 <div class="sect3"><a name="samba2-CHP-8-SECT-7.2.1"/>
3461 <h3 class="head3">Setting up the Dfs root</h3>
3463 <p>First we need to create a directory to act as the Dfs root:</p>
3465 <blockquote><pre class="code"># <tt class="userinput"><b>mkdir /usr/local/samba/dfs</b></tt></pre></blockquote>
3467 <p>This can be any directory, but it is important that it be owned by
3468 root and given the proper permissions:</p>
3470 <blockquote><pre class="code"># <tt class="userinput"><b>chown root:root /usr/local/samba/dfs</b></tt>
3471 # <tt class="userinput"><b>chmod 755 /usr/local/samba/dfs</b></tt></pre></blockquote>
3473 <p>The Dfs directory tree can have subdirectories and files, just like
3474 any other shared directory. These will function just as they would in
3475 any other share, allowing clients to access the directories and files
3476 on the Samba server. The whole idea of Dfs, though, is to gather
3477 together shares on other servers by making references to them in the
3478 Dfs tree. The way this is implemented with Samba involves a clever
3479 use of symbolic links, which can be in the Dfs root directory or any
3480 subdirectory in the Dfs tree.</p>
3482 <p>You are probably familiar with using symbolic links to create
3483 references to files that exist on the same system, and perhaps
3484 crossing a local filesystem boundary (which ordinary Unix links
3485 cannot do). But maybe you didn't know that symbolic
3486 links have a more general functionality. Although we
3487 can't display its contents directly, as we could
3488 with a text or binary file, a symbolic link
3489 "contains" an ASCII text string
3490 naming what the link points to. For example, take a look at the
3491 listing for these symbolic links:</p>
3493 <blockquote><pre class="code">$ <tt class="userinput"><b>ls -l wrdlnk alnk</b></tt>
3494 lrwxrwxrwx 1 jay jay 15 Mar 14 06:50 wrdlnk -> /usr/dict/words
3495 lrwxrwxrwx 1 jay jay 9 Mar 14 06:53 alnk -> dreamtime</pre></blockquote>
3497 <p>As you can infer from the size of the <em class="filename">wrdlnk</em>
3498 link (15 bytes), the string <tt class="literal">/usr/dict/words</tt> is
3499 encoded into it. The size of <em class="filename">alnk</em> (9 bytes) is
3500 smaller, corresponding to the shorter name of
3501 <em class="filename">dreamtime</em>.</p>
3503 <p>Now let's create a link in our Dfs root for an SMB
3506 <blockquote><pre class="code"># <tt class="userinput"><b>cd /usr/local/samba/dfs</b></tt>
3507 # <tt class="userinput"><b>ln -s 'msdfs:maya\e' maya-e</b></tt>
3508 # <tt class="userinput"><b>ls -l maya-e</b></tt>
3509 lrwxrwxrwx 1 root root 12 Mar 13 17:34 maya-e -> msdfs:maya\e</pre></blockquote>
3511 <p>This link might appear as a
3512 "broken" link in a directory
3513 listing because it points to something that isn't a
3514 file on the local system. For example, the <em class="emphasis">file</em>
3515 command will report:</p>
3517 <blockquote><pre class="code">$ <tt class="userinput"><b>file maya-e</b></tt>
3518 maya-e: broken symbolic link to msdfs:maya\e</pre></blockquote>
3520 <p>However, <em class="filename">maya-e</em> is a valid reference to the
3521 <em class="filename">\\maya\e</em> share when used with
3522 Samba's Dfs support. When Samba encounters this
3523 file, it sees the leading <tt class="literal">msdfs</tt>: and interprets
3524 the rest as the name of a remote share. The client is then redirected
3525 to the remote share.</p>
3527 <p>When creating links in the Dfs root directory, simply follow the same
3528 format, which in general is
3529 <tt class="literal">msdfs</tt>:<em class="replaceable">server</em>\<em class="replaceable">share</em>.
3530 Note that this is similar to a UNC appended onto the
3531 <tt class="literal">msdfs</tt>: string, except that in this case, the two
3532 backslashes preceding the server's name are omitted.</p>
3534 <a name="samba2-CHP-8-NOTE-141"/><blockquote class="note"><h4 class="objtitle">TIP</h4>
3535 <p>The names for the symbolic links in Dfs shares must be in all
3539 <p>In addition to regular network shares, you can use symbolic links of
3540 this type to reference Dfs shares on other Dfs servers. However,
3541 referencing printer shares does not work. Dfs is for sharing files
3542 only. <a name="INDEX-171"/></p>
3549 <div class="sect3"><a name="samba2-CHP-8-SECT-7.2.2"/>
3551 <h3 class="head3">Load balancing</h3>
3553 <p><a name="INDEX-172"/>To
3554 set up a load-balancing Dfs share, create the symbolic link like
3557 <blockquote><pre class="code"># <tt class="userinput"><b>ln -s 'msdfs:toltec\data,msdfs:mixtec\data' lb-data</b></tt></pre></blockquote>
3559 <p>That is, simply use a list of shares separated by commas as the
3560 reference. Remember, it is up to you to make sure the shared folders
3561 remain identical. Set up permissions on the servers to make the
3562 shares read-only to users.</p>
3564 <p>The last thing we need to do is to modify the
3565 <em class="filename">smb.conf</em> file to define the Dfs root share and
3566 add Dfs support. The Dfs root is added as a share definition:</p>
3568 <a name="INDEX-173"/><blockquote><pre class="code">[dfs]
3569 path = /usr/local/samba/dfs
3570 msdfs root = yes</pre></blockquote>
3572 <p>You can use any name you like for the share. The path is set to the
3573 Dfs root directory we just set up, and the parameter
3574 <tt class="literal">msdfs</tt> <tt class="literal">root</tt> <tt class="literal">=</tt>
3575 <tt class="literal">yes</tt> tells Samba that this share is a Dfs root.</p>
3577 <p>To enable support for Dfs in the server, we need to add one line to
3578 the <tt class="literal">[global]</tt> section:</p>
3580 <a name="INDEX-174"/><blockquote><pre class="code">[global]
3581 host msdfs = yes</pre></blockquote>
3583 <p>Restart the Samba daemons—or just wait a minute for them to
3584 reread the configuration file—and you will see the new share
3585 from Windows clients. If you have trouble accessing any of the remote
3586 shares in the Dfs share, recheck your symbolic links to make sure
3587 they were created correctly. <a name="INDEX-175"/></p>
3589 <a name="samba2-CHP-8-NOTE-142"/><blockquote class="note"><h4 class="objtitle">TIP</h4>
3590 <p>If you previously had a share by the same name as your Dfs share, you
3591 might need to reboot Windows clients before they can access the share
3606 <div class="sect1"><a name="samba2-CHP-8-SECT-8"/>
3608 <h2 class="head1">Working with NIS</h2>
3610 <p>In networks where NIS and NFS are in use, it is common for
3611 users' home directories to be mounted over the
3612 network by NFS. If a Samba server being used to authenticate user
3613 logons is running on a system with NFS-mounted home directories
3614 shared with a <tt class="literal">[homes]</tt> share, the additional
3615 overhead can result in poor performance—about 30% of normal
3618 <p>Samba has the ability to work with <a name="INDEX-176"/>NIS and NIS+ to find the
3619 server on which the home directories actually reside so that they can
3620 be shared directly from that server. For this to work, the server
3621 that holds the home directories must also have Samba running, with a
3622 <tt class="literal">[homes]</tt> share of its own.</p>
3625 <div class="sect2"><a name="samba2-CHP-8-SECT-8.1"/>
3627 <h3 class="head2">NIS Configuration Options</h3>
3629 <p><a href="ch08.html#samba2-CHP-8-TABLE-8">Table 8-8</a> introduces the
3630 <a name="INDEX-177"/><a name="INDEX-178"/>NIS configuration options specifically
3631 for setting up users.</p>
3633 <a name="samba2-CHP-8-TABLE-8"/><h4 class="head4">Table 8-8. NIS options</h4><table border="1">
3661 <p><tt class="literal">nis homedir</tt></p>
3667 <p>If <tt class="literal">yes</tt>, uses NIS instead of
3668 <em class="filename">/etc/passwd</em> to look up the path of a
3669 user's home directory.</p>
3672 <p><tt class="literal">no</tt></p>
3680 <p><tt class="literal">homedir map</tt></p>
3683 <p>string (NIS map name)</p>
3686 <p>Sets the NIS map to use to look up a user's home
3700 <div class="sect3"><a name="samba2-CHP-8-SECT-8.1.1"/>
3702 <h3 class="head3">nis homedir, homedir map</h3>
3704 <p>The <tt class="literal">nis</tt><a name="INDEX-179"/> <tt class="literal">homedir</tt> and
3705 <tt class="literal">homedir</tt><a name="INDEX-180"/> <tt class="literal">map</tt> options
3706 are for Samba servers on network sites where Unix home directories
3707 are provided using NFS, the automounter, and NIS.</p>
3709 <p>The <tt class="literal">nis</tt> <tt class="literal">homedir</tt> option
3710 indicates that the home-directory server for the user needs to be
3711 looked up in NIS. The <tt class="literal">homedir</tt>
3712 <tt class="literal">map</tt> option tells Samba in which NIS map to look
3713 for the server that has the user's home directory.
3714 The server needs to be a Samba server so that the client can do an
3715 SMB connect to it, and the other Samba servers need to have NIS
3716 installed so that they can do the lookup.</p>
3718 <p>For example, if user <tt class="literal">joe</tt> asks for a share called
3719 <tt class="literal">[joe]</tt>, and the <tt class="literal">nis</tt>
3720 <tt class="literal">homedir</tt> option is set to <tt class="literal">yes</tt>,
3721 Samba will look in the file specified by <tt class="literal">homedir</tt>
3722 <tt class="literal">map</tt> for a home directory for
3723 <tt class="literal">joe</tt>. If it finds one, Samba will return the
3724 associated system name to the client. The client will then try to
3725 connect to that machine and get the share from there. Enabling NIS
3726 lookups looks like the following:</p>
3728 <blockquote><pre class="code">[globals]
3730 homedir map = amd.map</pre></blockquote>
3741 <hr/><h4 class="head4">Footnotes</h4><blockquote><a name="FOOTNOTE-1"/> <p><a href="#FNPTR-1">[1]</a> The system checkbox will
3742 probably be grayed for your file. Don't worry about
3743 that—you should still be able to see when the box is checked
3744 and when it isn't.</p> </blockquote><hr/><h4 class="head4"><a href="toc.html">TOC</a></h4></body></html>