source: branches/samba-3.3.x/docs/htmldocs/using_samba/ch08.html

Last change on this file was 218, checked in by Herwig Bauernfeind, 16 years ago

Import Samba 3.3 branch at 3.3.0 level docs htmldocs (psmedley's port)
File size: 124.1 KB
Line 
1<html>
2<body bgcolor="#ffffff">
3
4<img src="samba2_xs.gif" border="0" alt=" " height="100" width="76"
5hspace="10" align="left" />
6
7<h1 class="head0">Chapter 8. Advanced Disk Shares</h1>
8
9
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
11regarding the integration of Unix and Windows filesystems, including
12hidden files, Unix links, file permissions, name mangling, case
13sensitivity of filenames, file locking, opportunistic locking
14(oplocks), connection scripts, supporting Microsoft Dfs (Distributed
15filesystem) shares, and using NIS home directories.</p>
16
17
18<div class="sect1"><a name="samba2-CHP-8-SECT-1"/>
19
20<h2 class="head1">Filesystem Differences</h2>
21
22<p>One of the biggest issues for which Samba has to correct is the
23difference between Unix and Microsoft filesystems. This includes
24items such as handling symbolic links, hidden files, and dot files.
25In addition, file permissions can also be a headache if not properly
26accounted for.</p>
27
28
29<div class="sect2"><a name="samba2-CHP-8-SECT-1.1"/>
30
31<h3 class="head2">Hiding and Vetoing Files</h3>
32
33<p><a name="INDEX-1"/><a name="INDEX-2"/>Sometimes you need to ensure that a user
34cannot see or access a file at all. Other times, you
35don't want to keep users from accessing a
36file&mdash;you just want to hide it when they view the contents of
37the directory. On Windows systems, an attribute of files allows them
38to be hidden from a folder listing. With Unix, the traditional way of
39hiding files in a directory is to use a <a name="INDEX-3"/><a name="INDEX-4"/>dot (.) as the first character in the
40filename. This prevents items such as configuration files from being
41seen when performing an ordinary <em class="emphasis">ls</em> command.
42Keeping a user from accessing a file at all, however, involves
43working with permissions on files and directories.</p>
44
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>,
48Samba reports files beginning with a period (.) as having their
49hidden attribute set. If the user has chosen to show all hidden files
50while browsing (e.g., using the Folder Options menu item under the
51View menu in Windows 98), he will still be able to see the files,
52although his icons will appear
53&quot;ghosted,&quot; or slightly grayed-out.
54If the client is configured not to show hidden files, the files will
55not appear at all.</p>
56
57<p>Instead of simply hiding files beginning with a dot, you can also
58specify 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>
60option. For example, let's assume you specified the
61following in our example <tt class="literal">[data]</tt> share:</p>
62
63<blockquote><pre class="code">[data]
64 hide files = /*.java/*README*/</pre></blockquote>
65
66<p>Each entry for this option must begin, end, or be separated from
67another with a slash ( / ) character, even if only one pattern is
68listed. This convention allows spaces to appear in filenames. The
69slashes have nothing to do with Unix directories; they are instead
70acting as delimiters for the <tt class="literal">hide</tt>
71<tt class="literal">files</tt> values.</p>
72
73<p>If you want to prevent users from seeing files completely, you can
74instead use the <tt class="literal">veto</tt><a name="INDEX-8"/> <tt class="literal">files</tt>
75option. This option, which takes the same syntax as the
76<tt class="literal">hide</tt> <tt class="literal">files</tt> option, specifies a
77list of files that should never be seen by the user. For example,
78let's change the <tt class="literal">[data]</tt> share to
79the following:</p>
80
81<blockquote><pre class="code">[data]
82 veto files = /*.java/*README*/</pre></blockquote>
83
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,
86end, or be separated from another with a slash (<tt class="literal">/</tt>)
87character, even if only one pattern is listed. If you do so, files
88that match the pattern, such as <em class="filename">hello.java</em> and
89<em class="filename">README.txt,</em> will simply disappear from the
90directory, and the user cannot access them through SMB.</p>
91
92<p><a name="INDEX-9"/>We need to address
93one other question. What happens if the user tries to delete a
94directory 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
97set to <tt class="literal">yes</tt>, the user can delete both the regular
98files and the vetoed files in the directory, and the directory itself
99is removed. If the option is set to <tt class="literal">no</tt>, the user
100cannot delete the vetoed files, and consequently the directory is not
101deleted either. From the user's perspective, the
102directory appears empty, but cannot be removed.</p>
103
104<p>The <tt class="literal">dont</tt><a name="INDEX-11"/> <tt class="literal">descend</tt>
105directive specifies a list of directories whose contents Samba should
106not make visible. Note that we say <em class="emphasis">contents</em>, not
107the directory itself. Users can enter a directory marked as such, but
108they are prohibited from descending the directory tree any
109farther&mdash;they always see an empty folder. For example,
110let's use this option with a more basic form of the
111share that we defined earlier in the chapter:</p>
112
113<blockquote><pre class="code">[data]
114 dont descend = config defaults</pre></blockquote>
115
116<p>In addition, let's assume that the
117<em class="filename">/home/samba/data</em> directory has the following
118contents:</p>
119
120<blockquote><pre class="code">drwxr-xr-x 6 tom users 1024 Jun 13 09:24 .
121drwxr-xr-x 8 root root 1024 Jun 10 17:53 ..
122-rw-r--r-- 2 tom users 1024 Jun 9 11:43 README
123drwxr-xr-x 3 tom users 1024 Jun 13 09:28 config
124drwxr-xr-x 3 tom users 1024 Jun 13 09:28 defaults
125drwxr-xr-x 3 tom users 1024 Jun 13 09:28 market</pre></blockquote>
126
127<p>If the user then connects to the share, she would see the directories
128in the share. However, the contents of the
129<em class="filename">/config</em> and <em class="filename">/defaults</em>
130directories would appear empty to her, even if other folders or files
131existed in them. In addition, users cannot write any data to the
132folder (which prevents them from creating a file or folder with the
133same name as one that is already there but invisible). If a user
134attempts to do so, she will receive an &quot;Access
135Denied&quot; message. The <tt class="literal">dont</tt>
136<tt class="literal">descend</tt> option is an administrative
137option&mdash;not a security option&mdash;and is not a substitute for
138good file permissions. <a name="INDEX-12"/><a name="INDEX-13"/></p>
139
140
141</div>
142
143
144<div class="sect2"><a name="samba2-CHP-8-SECT-1.2"/>
145
146<h3 class="head2">Links</h3>
147
148<p><a name="INDEX-14"/>When a client
149tries to open a symbolic link on a Samba server share, Samba attempts
150to follow the link to find the real file and let the client open it,
151as if the user were on a Unix machine. If you don't
152want to allow this, set the <tt class="literal">follow</tt>
153<tt class="literal">symlinks</tt> option like this:</p>
154
155<blockquote><pre class="code">[data]
156 follow symlinks = no</pre></blockquote>
157
158<p>You can test this by setting up and trying to access a symbolic link.
159Create a directory on the Unix server inside the share, acting as the
160user under which you will log in to Samba. Enter the following
161commands:</p>
162
163<blockquote><pre class="code">$ <tt class="userinput"><b>echo &quot;This is a test&quot; &gt;hello.txt</b></tt>
164$ <tt class="userinput"><b>ln -s hello.txt hello-link.txt</b></tt></pre></blockquote>
165
166<p>This results in the text file <em class="filename">hello.txt</em> and a
167symbolic link to it called <em class="filename">hello-link.txt</em>.
168Normally, if you double-click either one, you will receive a file
169that has the text &quot;This is a test&quot;
170inside 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
173double-click <em class="filename">hello-link.txt</em>.</p>
174
175<p>The <tt class="literal">wide</tt><a name="INDEX-16"/> <tt class="literal">links</tt>
176option, if set to <tt class="literal">no</tt>, prevents the client user
177from following symbolic links that point outside the shared directory
178tree. For example, let's assume that we modified the
179<tt class="literal">[data]</tt> share as follows:</p>
180
181<blockquote><pre class="code">[data]
182 follow symlinks = yes
183 wide links = no</pre></blockquote>
184
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
187follow any symbolic links outside the current share tree. If we
188create a file outside the share (for example, in
189someone's home directory) and then create a link to
190it in the share as follows:</p>
191
192<blockquote><pre class="code">ln -s ~tom/datafile ./datafile</pre></blockquote>
193
194<p>the client cannot open the file in Tom's home
195directory.</p>
196
197
198</div>
199
200
201<div class="sect2"><a name="samba2-CHP-8-SECT-1.3"/>
202
203<h3 class="head2">Filesystem Options</h3>
204
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
206discussed earlier. We recommend the defaults for most, except those
207listed in the following descriptions.</p>
208
209<a name="samba2-CHP-8-TABLE-1"/><h4 class="head4">Table 8-1. Filesystem configuration options</h4><table border="1">
210
211
212
213
214
215
216<tr>
217<th>
218<p>Option</p>
219</th>
220<th>
221<p>Parameters</p>
222</th>
223<th>
224<p>Function</p>
225</th>
226<th>
227<p>Default</p>
228</th>
229<th>
230<p>Scope</p>
231</th>
232</tr>
233
234
235<tr>
236<td>
237<p><tt class="literal">dont descend</tt></p>
238</td>
239<td>
240<p>string (list of directories)</p>
241</td>
242<td>
243<p>Indicates a list of directories whose contents Samba should make
244invisible to clients.</p>
245</td>
246<td>
247<p>None</p>
248</td>
249<td>
250<p>Share</p>
251</td>
252</tr>
253<tr>
254<td>
255<p><tt class="literal">follow</tt> <tt class="literal">symlinks</tt></p>
256</td>
257<td>
258<p>Boolean</p>
259</td>
260<td>
261<p>If set to <tt class="literal">no</tt>, will not honor symbolic links.</p>
262</td>
263<td>
264<p><tt class="literal">yes</tt></p>
265</td>
266<td>
267<p>Share</p>
268</td>
269</tr>
270<tr>
271<td>
272<p><tt class="literal">getwd cache</tt></p>
273</td>
274<td>
275<p>Boolean</p>
276</td>
277<td>
278<p>If set to <tt class="literal">yes</tt>, will use a cache for
279<tt class="literal">getwd( )</tt> calls.</p>
280</td>
281<td>
282<p><tt class="literal">yes</tt></p>
283</td>
284<td>
285<p>Global</p>
286</td>
287</tr>
288<tr>
289<td>
290<p><tt class="literal">wide links</tt></p>
291</td>
292<td>
293<p>Boolean</p>
294</td>
295<td>
296<p>If set to <tt class="literal">yes</tt>, will follow symbolic links outside
297the share.</p>
298</td>
299<td>
300<p><tt class="literal">yes</tt></p>
301</td>
302<td>
303<p>Share</p>
304</td>
305</tr>
306<tr>
307<td>
308<p><tt class="literal">hide dot files</tt></p>
309</td>
310<td>
311<p>Boolean</p>
312</td>
313<td>
314<p>If set to <tt class="literal">yes</tt>, treats Unix hidden files as hidden
315files in Windows.</p>
316</td>
317<td>
318<p><tt class="literal">yes</tt></p>
319</td>
320<td>
321<p>Share</p>
322</td>
323</tr>
324<tr>
325<td>
326<p><tt class="literal">hide files</tt></p>
327</td>
328<td>
329<p>string (list of files)</p>
330</td>
331<td>
332<p>List of file patterns to treat as hidden.</p>
333</td>
334<td>
335<p>None</p>
336</td>
337<td>
338<p>Share</p>
339</td>
340</tr>
341<tr>
342<td>
343<p><tt class="literal">veto files</tt></p>
344</td>
345<td>
346<p>string (list of files)</p>
347</td>
348<td>
349<p>List of file patterns to never show.</p>
350</td>
351<td>
352<p>None</p>
353</td>
354<td>
355<p>Share</p>
356</td>
357</tr>
358<tr>
359<td>
360<p><tt class="literal">delete veto</tt> <tt class="literal">files</tt></p>
361</td>
362<td>
363<p>Boolean</p>
364</td>
365<td>
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
368deleted.</p>
369</td>
370<td>
371<p><tt class="literal">no</tt></p>
372</td>
373<td>
374<p>Share</p>
375</td>
376</tr>
377
378</table>
379
380
381<div class="sect3"><a name="samba2-CHP-8-SECT-1.3.1"/>
382
383<h3 class="head3">dont descend</h3>
384
385<p>The <tt class="literal">dont</tt><a name="INDEX-20"/> <tt class="literal">descend</tt>
386option can be used to specify various directories that should appear
387empty to the client. Note that the directory itself will still
388appear. However, Samba will not show any of the contents of the
389directory to the client user. This is not a good option to use as a
390security feature; it is really meant only as a convenience to keep
391users from casually browsing into directories that might have
392sensitive files. See our example earlier in this section.</p>
393
394
395</div>
396
397
398
399<div class="sect3"><a name="samba2-CHP-8-SECT-1.3.2"/>
400
401<a name="INDEX-21"/><h3 class="head3">follow symlinks</h3>
402
403<p>This option controls whether Samba will follow a symbolic link in the
404Unix operating system to the target or if it should return an error
405to the client user. If the option is set to <tt class="literal">yes</tt>,
406the 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
408link is accessed.</p>
409
410
411</div>
412
413
414
415<div class="sect3"><a name="samba2-CHP-8-SECT-1.3.3"/>
416
417<a name="INDEX-22"/><h3 class="head3">getwd cache</h3>
418
419<p>This global option specifies whether Samba should use a local cache
420for the Unix <em class="emphasis">getwd( )</em> ( get current working
421directory) system call. You can override the default value of
422<tt class="literal">yes</tt> as follows:</p>
423
424<blockquote><pre class="code">[global]
425 getwd cache = no</pre></blockquote>
426
427<p>Setting this option to <tt class="literal">no</tt> can significantly
428increase the time it takes to resolve the working directory,
429especially if the <tt class="literal">wide</tt> <tt class="literal">links</tt>
430option is set to <tt class="literal">no</tt>. You should normally not need
431to alter this option.</p>
432
433
434</div>
435
436
437
438<div class="sect3"><a name="samba2-CHP-8-SECT-1.3.4"/>
439
440<a name="INDEX-23"/><h3 class="head3">wide links</h3>
441
442<p>This option specifies whether the client user can follow symbolic
443links that point outside the shared directory tree. This includes any
444files or directories at the other end of the link, as long as the
445permissions are correct for the user. The default value for this
446option is <tt class="literal">yes</tt>. Note that this option will not be
447honored if the <tt class="literal">follow</tt> <tt class="literal">symlinks</tt>
448options 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
450because it will have to check each link it encounters.</p>
451
452
453</div>
454
455
456
457<div class="sect3"><a name="samba2-CHP-8-SECT-1.3.5"/>
458
459<h3 class="head3">hide dot files</h3>
460
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
463begin with a dot (.) character to mimic the functionality behind
464several shell commands that are present on Unix systems. Like
465<tt class="literal">hide</tt> <tt class="literal">files</tt>, those files that
466begin with a dot have the DOS hidden attribute set, which
467doesn't guarantee that a client cannot view them.
468The default value for this option is <tt class="literal">yes</tt>.</p>
469
470
471</div>
472
473
474
475<div class="sect3"><a name="samba2-CHP-8-SECT-1.3.6"/>
476
477<h3 class="head3">hide files</h3>
478
479<p>The <tt class="literal">hide</tt><a name="INDEX-26"/> <tt class="literal">files</tt> option
480provides one or more directory or filename patterns to Samba. Any
481file matching this pattern will be treated as a hidden file from the
482perspective of the client. Note that this simply means that the DOS
483hidden attribute is set, which might or might not mean that the user
484can actually see it while browsing.</p>
485
486<p>Each entry in the list must begin, end, or be separated from another
487entry with a slash (<tt class="literal">/</tt>) character, even if only one
488pattern is listed. This allows spaces to appear in the list.
489Asterisks can be used as a wildcard to represent zero or more
490characters. Questions marks can be used to represent exactly one
491character. For example:</p>
492
493<blockquote><pre class="code">hide files = /.jav*/README.???/</pre></blockquote>
494
495
496</div>
497
498
499
500<div class="sect3"><a name="samba2-CHP-8-SECT-1.3.7"/>
501
502<a name="INDEX-27"/><h3 class="head3">veto files</h3>
503
504<p>More stringent than the hidden files state is the state provided by
505the <tt class="literal">veto</tt> <tt class="literal">files</tt> configuration
506option. Samba won't even admit these files exist.
507You cannot list or open them from the client. This should not be used
508as a means of implementing security. It is actually a mechanism to
509keep PC programs from deleting special files, such as ones used to
510store the resource fork of a Macintosh file on a Unix filesystem. If
511both Windows and Macs are sharing the same files, this can prevent
512ill-advised power users from removing files the Mac users need.</p>
513
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
516option: each entry must begin, end, or be separated from another with
517a slash ( / ) character, even if only one pattern is listed.
518Asterisks can be used as a wildcard to represent zero or more
519characters. Question marks can be used to represent exactly one
520character. For example:</p>
521
522<blockquote><pre class="code">veto files = /*config/*default?/</pre></blockquote>
523
524<p>This option is primarily administrative and is not a substitute for
525good file permissions.</p>
526
527
528</div>
529
530
531
532<div class="sect3"><a name="samba2-CHP-8-SECT-1.3.8"/>
533
534<a name="INDEX-28"/><h3 class="head3">delete veto files</h3>
535
536<p>This option tells Samba to delete vetoed files when a user attempts
537to 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
539directory that contains a vetoed file, the file (and the directory)
540will not be deleted. Instead, the directory remains and appears empty
541from the perspective of the user. If set to <tt class="literal">yes</tt>,
542the directory and the vetoed files will be deleted. <a name="INDEX-29"/><a name="INDEX-30"/></p>
543
544
545</div>
546
547
548</div>
549
550
551</div>
552
553
554
555<div class="sect1"><a name="samba2-CHP-8-SECT-2"/>
556
557<h2 class="head1">File Permissions and Attributes on MS-DOS and Unix</h2>
558
559<p><a name="INDEX-31"/><a name="INDEX-32"/><a name="INDEX-33"/>Originally, DOS was not intended to be a
560multiuser, networked operating system. Unix, on the other hand, was
561designed for multiple users from the start. Consequently, Samba must
562not only be aware of, but also provide special solutions for,
563inconsistencies and gaps in coverage between the two filesystems. One
564of the biggest gaps is how Unix and DOS handle permissions on files.</p>
565
566<p>Let's take a look at how Unix assigns permissions.
567All Unix files have read, write, and execute bits for three
568classifications of users: owner, group, and world. These permissions
569can 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>
571
572<blockquote><pre class="code">-rwxr--r-- 1 tom users 2014 Apr 13 14:11 access.conf</pre></blockquote>
573
574<p>Windows, on the other hand, has four principal bits that it uses with
575any file: read-only, system, hidden, and archive. You can view these
576bits by right-clicking the file and choosing the Properties menu
577item. 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>
578
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>
580
581<p>The definition of each bit follows:</p>
582
583<dl>
584<dt><b>Read-only</b></dt>
585<dd>
586<p>The file's contents can be read by a user but cannot
587be written to.</p>
588</dd>
589
590
591
592<dt><b>System</b></dt>
593<dd>
594<p>This file has a specific purpose required by the operating system.</p>
595</dd>
596
597
598
599<dt><b>Hidden</b></dt>
600<dd>
601<p>This file has been marked to be invisible to the user, unless the
602operating system is explicitly set to show it.</p>
603</dd>
604
605
606
607<dt><b>Archive</b></dt>
608<dd>
609<p>This file has been touched since the last DOS backup was performed on
610it.</p>
611</dd>
612
613</dl>
614
615<p>Note that there is no bit to specify that a file is executable. DOS
616and Windows NT filesystems identify executable files by giving them
617the extensions <em class="filename">.exe</em>, <em class="filename">.com</em>,
618<em class="filename">.cmd</em>, or <em class="filename">.bat</em>.</p>
619
620<p>Consequently, there is no use for any of the three Unix executable
621bits that are present on a file in a Samba disk share. DOS files,
622however, have their own attributes that need to be preserved when
623they are stored in a Unix environment: the archive, system, and
624hidden bits. Samba can preserve these bits by reusing the executable
625permission bits of the file on the Unix side&mdash;if it is
626instructed to do so. Mapping these bits, however, has an unfortunate
627side effect: if a Windows user stores a file in a Samba share, and
628you view it on Unix with the <em class="emphasis">ls -al</em> command,
629some of the executable bits won't mean what
630you'd expect them to.</p>
631
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
636map the archive, system, and hidden attributes to the owner, group,
637and world execute bits of the file, respectively. You can add these
638options to the <tt class="literal">[data]</tt> share, setting each of their
639values as follows:</p>
640
641<blockquote><pre class="code">[data]
642 map archive = yes
643 map system = yes
644 map hidden = yes</pre></blockquote>
645
646<p>After that, try creating a file in the share under Unix&mdash;such as
647<em class="emphasis">hello.java</em>&mdash;and change the permissions of
648the file to 755. With these Samba options set, you should be able to
649check the permissions on the Windows side and see that each of the
650three values has been checked in the Properties dialog box. What
651about the read-only attribute? By default, Samba sets this whenever a
652file does not have the Unix owner write permission bit set. In other
653words, you can set this bit by changing the permissions of the file
654to 555.</p>
655
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
658the other two options have a default value of <tt class="literal">no</tt>.
659This is because many programs do not work properly if the archive bit
660is not stored correctly for DOS and Windows files. The system and
661hidden attributes, however, are not critical for a
662program's operation and are left to the discretion
663of the administrator.</p>
664
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
666illustrates how Samba maps those bits to DOS attributes. Note that
667the group read/write and world read/write bits do not directly
668translate to a DOS attribute, but they still retain their original
669Unix definitions on the Samba server.</p>
670
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>
672
673
674<div class="sect2"><a name="samba2-CHP-8-SECT-2.1"/>
675
676<h3 class="head2">Creation Masks</h3>
677
678<p><a name="INDEX-39"/>File and directory creation masks are
679similar to <a name="INDEX-40"/>umasks you
680have probably encountered while working with Unix systems. They are
681used to help define the permissions that will be assigned to a file
682or directory at the time it is created. Samba's
683masks work differently in that the bits that can be set are set in
684the creation mask, while in Unix umasks, the bits
685<em class="emphasis">cannot</em> be set are set in the umask. We think you
686will find Samba's method to be much more intuitive.
687Once in a while you might need to convert between a Unix umask and
688the equivalent Samba mask. It is simple: one is just the bitwise
689complement of the other. For example, an octal umask of 0022 has the
690same effect as a Samba mask of 0755.</p>
691
692<p>Unix umasks are set on a user-by-user basis, usually while executing
693the GUI's or command-line shell's
694startup scripts. When users connect to a Samba share from a network
695client, these scripts are not executed, so Samba supplies the ability
696to set the creation masks for files and directories. By default, this
697is 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
700user-by-user basis, thus matching conventional Unix behavior.</p>
701
702<p>To show how Samba's create masks work, suppose we
703have a Windows Me user connecting to his Unix home directory through
704Samba, 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>
706in 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
708bits that are set on new files. If the user creates a file with
709Wordpad, it will appear in the Unix filesystem like this:</p>
710
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>
713
714<p>Wordpad created the file with read/write permissions (i.e., the
715MS-DOS read-only attribute was not set), so Samba mapped the MS-DOS
716attributes to Unix read/write permissions for user, group, and other.
717The <a name="INDEX-41"/><a name="INDEX-42"/>execute bit is set for the owner
718because 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
724you see fit, and unless you do backups from MS-DOS or Windows
725systems, 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>
727to avoid Windows files from appearing as executables on the Unix
728system.</p>
729
730<p>Now suppose we set
731<tt class="literal">create</tt><a name="INDEX-43"/> <tt class="literal">mask</tt> to have
732an effect. For example:</p>
733
734<blockquote><pre class="code">[homes]
735 create mask = 664</pre></blockquote>
736
737<p>This is equivalent to a Unix umask of 113. If the user creates the
738Wordpad document as before, it will show up as:</p>
739
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>
742
743<p>Comparing this to the previous example, notice that not only has the
744write permission for other disappeared as we expected, but so has the
745execute permission for owner. This happened because the value of
746<tt class="literal">create</tt> <tt class="literal">mask</tt> logically ANDs the
747owner's permissions with a 6, which has masked off
748the 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
752not to mask off the corresponding execute bit with your
753<tt class="literal">create</tt> <tt class="literal">mask</tt>.</p>
754
755<p>The <tt class="literal">directory</tt><a name="INDEX-44"/> <tt class="literal">mask</tt>
756option works similarly, masking permissions for newly created
757directories. The following example will allow the permissions of a
758newly created directory to be, at most, 755:</p>
759
760<blockquote><pre class="code">[data]
761 directory mask = 755</pre></blockquote>
762
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
767OR against the file and directory creation masks, ensuring that those
768bits that are specified will always be set. You would typically set
769these options globally to ensure that group and world read/write
770permissions have been set appropriately for new files or directories
771in each share.</p>
772
773<p>In the same spirit, if you wish to set explicitly the Unix user and
774group attributes of a file created on the Windows side, you can use
775the <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>
777options. For example:</p>
778
779<blockquote><pre class="code">[data]
780 create mask = 744
781 directory mask = 755
782 force user = joe
783 force group = accounting</pre></blockquote>
784
785<p>These options assign the same Unix username and group to every client
786that connects to the share. However, this occurs
787<em class="emphasis">after</em> the client authenticates; it does not
788allow free access to a share. These options are frequently used for
789their side effects of assigning a specific user and group to each new
790file or directory that is created in a share. Use these options with
791discretion.</p>
792
793<p>Finally, one of the capabilities of Unix that DOS lacks is the
794ability to delete a read-only file from a writable directory. In
795Unix, if a directory is writable, a read-only file in that directory
796can still be removed. This could permit you to delete files in any of
797your directories, even if the file was left by someone else.</p>
798
799<p>DOS filesystems are not designed for multiple users, and so its
800designers decided that read-only means &quot;protected
801against accidental change, including deletion,&quot;
802rather than &quot;protected against some other user on a
803single-user machine.&quot; So the designers of DOS
804prohibited removal of a read-only file. Even today, Windows
805filesystems exhibit the same behavior.</p>
806
807<p>Normally, this is harmless. Windows programs don't
808try to remove read-only files because they know it's
809a bad idea. However, a number of source-code control
810programs&mdash;which were first written for Unix&mdash;run on Windows
811and require the ability to delete read-only files. Samba permits this
812behavior with the <tt class="literal">delete</tt><a name="INDEX-47"/>
813<tt class="literal">readonly</tt> option. To enable this functionality, set
814the option to <tt class="literal">yes</tt>:</p>
815
816<a name="INDEX-48"/><blockquote><pre class="code">[data]
817 delete readonly = yes</pre></blockquote>
818
819
820</div>
821
822
823<div class="sect2"><a name="samba2-CHP-8-SECT-2.2"/>
824
825<h3 class="head2">File and Directory Permission Options</h3>
826
827<p><a name="INDEX-49"/><a name="INDEX-50"/><a name="INDEX-51"/>The
828options 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>
829
830<a name="samba2-CHP-8-TABLE-2"/><h4 class="head4">Table 8-2. File and directory permission options</h4><table border="1">
831
832
833
834
835
836
837<tr>
838<th>
839<p>Option</p>
840</th>
841<th>
842<p>Parameters</p>
843</th>
844<th>
845<p>Function</p>
846</th>
847<th>
848<p>Default</p>
849</th>
850<th>
851<p>Scope</p>
852</th>
853</tr>
854
855
856<tr>
857<td>
858<p><tt class="literal">create mask</tt> <tt class="literal">(create mode)</tt></p>
859</td>
860<td>
861<p>numeric</p>
862</td>
863<td>
864<p>Maximum permissions for files created by Samba.</p>
865</td>
866<td>
867<p><tt class="literal">0744</tt></p>
868</td>
869<td>
870<p>Share</p>
871</td>
872</tr>
873<tr>
874<td>
875<p><tt class="literal">directory mask</tt> <tt class="literal">(directory mode)</tt></p>
876</td>
877<td>
878<p>numeric</p>
879</td>
880<td>
881<p>Maximum permissions for directories created by Samba.</p>
882</td>
883<td>
884<p><tt class="literal">0744</tt></p>
885</td>
886<td>
887<p>Share</p>
888</td>
889</tr>
890<tr>
891<td>
892<p><tt class="literal">force create mode</tt></p>
893</td>
894<td>
895<p>numeric</p>
896</td>
897<td>
898<p>Forces the specified permissions (bitwise <tt class="literal">or</tt>) for
899directories created by Samba.</p>
900</td>
901<td>
902<p><tt class="literal">0000</tt></p>
903</td>
904<td>
905<p>Share</p>
906</td>
907</tr>
908<tr>
909<td>
910<p><tt class="literal">force directory</tt> <tt class="literal">mode</tt></p>
911</td>
912<td>
913<p>numeric</p>
914</td>
915<td>
916<p>Forces the specified permissions (bitwise <tt class="literal">or</tt>) for
917directories created by Samba.</p>
918</td>
919<td>
920<p><tt class="literal">0000</tt></p>
921</td>
922<td>
923<p>Share</p>
924</td>
925</tr>
926<tr>
927<td>
928<p><tt class="literal">force group</tt> <tt class="literal">(group)</tt></p>
929</td>
930<td>
931<p>string ( group name)</p>
932</td>
933<td>
934<p>Effective group for a user accessing this share.</p>
935</td>
936<td>
937<p>None</p>
938</td>
939<td>
940<p>Share</p>
941</td>
942</tr>
943<tr>
944<td>
945<p><tt class="literal">force user</tt></p>
946</td>
947<td>
948<p>string (username)</p>
949</td>
950<td>
951<p>Effective username for a user accessing this share.</p>
952</td>
953<td>
954<p>None</p>
955</td>
956<td>
957<p>Share</p>
958</td>
959</tr>
960<tr>
961<td>
962<p><tt class="literal">delete readonly</tt></p>
963</td>
964<td>
965<p>Boolean</p>
966</td>
967<td>
968<p>Allows a user to delete a read-only file from a writable directory.</p>
969</td>
970<td>
971<p><tt class="literal">no</tt></p>
972</td>
973<td>
974<p>Share</p>
975</td>
976</tr>
977<tr>
978<td>
979<p><tt class="literal">map archive</tt></p>
980</td>
981<td>
982<p>Boolean</p>
983</td>
984<td>
985<p>Preserve DOS archive attribute in user execute bit (0100).</p>
986</td>
987<td>
988<p><tt class="literal">yes</tt></p>
989</td>
990<td>
991<p>Share</p>
992</td>
993</tr>
994<tr>
995<td>
996<p><tt class="literal">map system</tt></p>
997</td>
998<td>
999<p>Boolean</p>
1000</td>
1001<td>
1002<p>Preserve DOS system attribute in group execute bit (0010).</p>
1003</td>
1004<td>
1005<p><tt class="literal">no</tt></p>
1006</td>
1007<td>
1008<p>Share</p>
1009</td>
1010</tr>
1011<tr>
1012<td>
1013<p><tt class="literal">map hidden</tt></p>
1014</td>
1015<td>
1016<p>Boolean</p>
1017</td>
1018<td>
1019<p>Preserve DOS hidden attribute in world execute bit (0001).</p>
1020</td>
1021<td>
1022<p><tt class="literal">no</tt></p>
1023</td>
1024<td>
1025<p>Share</p>
1026</td>
1027</tr>
1028<tr>
1029<td>
1030<p><tt class="literal">inherit permissions</tt></p>
1031</td>
1032<td>
1033<p>Boolean</p>
1034</td>
1035<td>
1036<p>If <tt class="literal">yes</tt>, permissions on new files and directories
1037are inherited from parent directory.</p>
1038</td>
1039<td>
1040<p>no</p>
1041</td>
1042<td>
1043<p>Share</p>
1044</td>
1045</tr>
1046
1047</table>
1048
1049
1050<div class="sect3"><a name="samba2-CHP-8-SECT-2.2.1"/>
1051
1052<a name="INDEX-52"/><h3 class="head3">create mask</h3>
1053
1054<p>The argument for this option is an octal number indicating which
1055permission flags can be set at file creation by a client in a share.
1056The default is 0744, which means that the Unix owner can at most
1057read, write, and optionally execute her own files, while members of
1058the user's group and others can only read or execute
1059them. If you need to change it for nonexecutable files, we recommend
10600644, or <tt class="literal">rw-r--r--</tt>. Keep in mind that the execute
1061bits can be used by the server to map certain DOS file attributes, as
1062described earlier. If you're altering the create
1063mask, those bits have to be part of the create mask as well.</p>
1064
1065
1066</div>
1067
1068
1069
1070<div class="sect3"><a name="samba2-CHP-8-SECT-2.2.2"/>
1071
1072<a name="INDEX-53"/><h3 class="head3">directory mask</h3>
1073
1074<p>The argument for this option is an octal number indicating which
1075permission flags can be set at directory creation by a client in a
1076share. The default is 0744, which allows everyone on the Unix side
1077to, at most, read and traverse the directories, but allows only you
1078to modify them. We recommend the mask 0750, removing access by
1079&quot;the world.&quot;</p>
1080
1081
1082</div>
1083
1084
1085
1086<div class="sect3"><a name="samba2-CHP-8-SECT-2.2.3"/>
1087
1088<a name="INDEX-54"/><h3 class="head3">force create mode</h3>
1089
1090<p>This option sets the permission bits that Samba will set when a file
1091permission change is made. It's often used to force
1092group permissions, as mentioned previously. It can also be used to
1093preset any of the DOS attributes we mentioned: archive (0100), system
1094(0010), or hidden (0001).</p>
1095
1096<a name="samba2-CHP-8-NOTE-139"/><blockquote class="note"><h4 class="objtitle">TIP</h4>
1097<p><a name="INDEX-55"/>When saving
1098documents, many Windows applications rename their datafiles with a
1099<em class="filename">.bak</em> extension and create new ones. When the
1100files are in a Samba share, this changes their ownership and
1101permissions so that members of the same Unix group
1102can't edit them. Setting <tt class="literal">force</tt>
1103<tt class="literal">create mode = 0660</tt> will keep the new file editable
1104by members of the group.</p>
1105</blockquote>
1106
1107
1108</div>
1109
1110
1111
1112<div class="sect3"><a name="samba2-CHP-8-SECT-2.2.4"/>
1113
1114<a name="INDEX-56"/><h3 class="head3">force directory mode</h3>
1115
1116<p>This option sets the permission bits that Samba will set when a
1117directory permission change is made or a directory is created.
1118It's often used to force group permissions, as
1119mentioned previously. This option defaults to 0000 and can be used
1120just 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>
1122
1123
1124</div>
1125
1126
1127
1128<div class="sect3"><a name="samba2-CHP-8-SECT-2.2.5"/>
1129
1130<a name="INDEX-57"/><h3 class="head3">force group</h3>
1131
1132<p>This option, sometimes called <tt class="literal">group</tt>, assigns a
1133static group ID that will be used on all connections to a share after
1134the client has successfully authenticated. This assigns a specific
1135group to each new file or directory created from an SMB client.</p>
1136
1137
1138</div>
1139
1140
1141
1142<div class="sect3"><a name="samba2-CHP-8-SECT-2.2.6"/>
1143
1144<h3 class="head3">force user</h3>
1145
1146<p>The <tt class="literal">force</tt><a name="INDEX-58"/> <tt class="literal">user</tt> option
1147assigns a static user ID that will be used on all connections to a
1148share after the client has successfully authenticated. This assigns a
1149specific user to each new file or directory created from an SMB
1150client.</p>
1151
1152
1153</div>
1154
1155
1156
1157<div class="sect3"><a name="samba2-CHP-8-SECT-2.2.7"/>
1158
1159<a name="INDEX-59"/><h3 class="head3">delete readonly</h3>
1160
1161<p>This option allows a user to delete a directory containing a
1162read-only file. By default, DOS and Windows will not allow such an
1163operation. You probably will want to leave this option turned off
1164unless a program (for example, an RCS program) needs this capability;
1165many Windows users would be appalled to find that
1166they'd accidentally deleted a file that they had set
1167as read-only.</p>
1168
1169
1170</div>
1171
1172
1173
1174<div class="sect3"><a name="samba2-CHP-8-SECT-2.2.8"/>
1175
1176<a name="INDEX-60"/><h3 class="head3">map archive</h3>
1177
1178<p>The DOS archive bit is used to flag a file that has been changed
1179since it was last archived (e.g., backed up with the DOS archive
1180program). 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
1183execute-by-owner (0100) bit. It's best to leave this
1184option on if your Windows users are doing their own backups or are
1185using programs that require the archive bit. Unix lacks the notion of
1186an archive bit entirely. Backup programs typically keep a file that
1187lists what files were backed up on what date, so comparing
1188file-modification dates serves the same purpose.</p>
1189
1190<p>Setting this option to <tt class="literal">yes</tt> causes an occasional
1191surprise on Unix when a user notices that a datafile is marked as
1192executable, but rarely causes harm. If a user tries to run it, he
1193will normally get a string of error messages as the shell tries to
1194execute the first few lines as commands. The reverse is also
1195possible; an executable Unix program looks like it
1196hasn't been backed up recently on Windows. But
1197again, this is rare and usually harmless.</p>
1198
1199<p>For map archive to work properly, the execute bit for owner must not
1200be masked off with the <tt class="literal">create</tt>
1201<tt class="literal">mask</tt> parameter.</p>
1202
1203
1204</div>
1205
1206
1207
1208<div class="sect3"><a name="samba2-CHP-8-SECT-2.2.9"/>
1209
1210<a name="INDEX-61"/><h3 class="head3">map system</h3>
1211
1212<p>The DOS system attribute indicates files that are required by the
1213operating system and should not be deleted, renamed, or moved without
1214special effort. Set this option only if you need to store Windows
1215system files on the Unix fileserver. Executable Unix programs will
1216appear to be nonremovable, special Windows files when viewed from
1217Windows clients. This might prove mildly inconvenient if you want to
1218move or remove one. For most sites, however, this is fairly harmless.</p>
1219
1220<p>For map archive to work properly, the execute bit for group must not
1221be masked off with the <tt class="literal">create</tt>
1222<tt class="literal">mask</tt> parameter.</p>
1223
1224
1225</div>
1226
1227
1228
1229<div class="sect3"><a name="samba2-CHP-8-SECT-2.2.10"/>
1230
1231<a name="INDEX-62"/><h3 class="head3">map hidden</h3>
1232
1233<p>DOS uses the hidden attribute to indicate that a file should not
1234ordinarily be visible in directory listings. Unix
1235doesn't have such a facility; it's
1236up to individual programs (notably, the shell) to decide what to
1237display and what not to display. Normally, you won't
1238have any DOS files that need to be hidden, so the best thing to do is
1239to leave this option turned off.</p>
1240
1241<p>Setting this option to <tt class="literal">yes</tt> causes the server to
1242map the hidden flag onto the executable-by-others bit (0001). This
1243feature can produce a rather startling effect. Any Unix program that
1244is executable by world seems to vanish when you look for it from a
1245Windows client. If this option is not set, however, and a Windows
1246user attempts to mark a file hidden on a Samba share, it will not
1247work&mdash;Samba has no place to store the hidden attribute!</p>
1248
1249<p>For map archive to work properly, the execute bit for other must not
1250be masked off with the <tt class="literal">create</tt>
1251<tt class="literal">mask</tt> parameter.</p>
1252
1253
1254</div>
1255
1256
1257
1258<div class="sect3"><a name="samba2-CHP-8-SECT-2.2.11"/>
1259
1260<h3 class="head3">inherit permissions</h3>
1261
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
1270the permissions on newly created files is overridden such that the
1271new files and directories take on permissions from their parent
1272directory. New directories will have exactly the same permissions as
1273the parent, and new files will inherit the read and write bits from
1274the parent directory, while the execute bits are determined as usual
1275by 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>
1279
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>
1281
1282
1283</div>
1284
1285
1286</div>
1287
1288
1289</div>
1290
1291
1292
1293<div class="sect1"><a name="samba2-CHP-8-SECT-3"/>
1294
1295<h2 class="head1">Windows NT/2000/XP ACLs</h2>
1296
1297<p><a name="INDEX-70"/><a name="INDEX-71"/><a name="INDEX-72"/><a name="INDEX-73"/>Unix and Windows
1298have different <a name="INDEX-74"/>security models, and Windows NT/2000/XP
1299has a security model that is different from Windows 95/98/Me. One
1300area in which this is readily apparent is file protections. On Unix
1301systems, the method used has traditionally been the 9-bit
1302&quot;user, group, other&quot; system, in
1303which read, write, and execute bits can be set separately for the
1304owner of the file, the groups to which the owner belongs, and
1305everyone else, respectively.</p>
1306
1307<p><a name="INDEX-75"/>Windows 95/98/Me has a file-protection
1308system that is essentially no protection at all. This family of
1309operating systems was developed from MS-DOS, which was implemented as
1310a non-networked, single-user system. Multiuser security simply was
1311never added. One apparent exception to this is user-level security
1312for shared files, which we will discuss in <a href="ch09.html">Chapter 9</a>. Here, separate access permissions can be
1313assigned to individual network client users or groups. However,
1314user-level security on Windows 95/98/Me systems requires a Windows
1315NT/2000 or Samba server to perform the actual authentication.</p>
1316
1317<p>On <a name="INDEX-76"/><a name="INDEX-77"/><a name="INDEX-78"/>Windows NT/2000/XP,
1318user-level security is an extension of the native file security
1319model, which involves access control lists (ACLs). This system is
1320somewhat more extensive than the Unix security model, allowing the
1321access rights on individual files to be set separately for any number
1322of 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>,
1324and <a href="ch08.html#samba2-CHP-8-FIG-5">Figure 8-5</a> show the dialog boxes on a Windows
13252000 system in which the ACL is set for a file. By right-clicking a
1326file's icon and selecting Properties, then selecting
1327the 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
1328file, which are similar to Unix permissions, although not identical.</p>
1329
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>
1331
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.
1335In this dialog, ACEs can be added to or deleted from the ACL, or an
1336existing ACE can be viewed and modified. Each ACE either allows or
1337denies a set of permissions for a specific user or group.</p>
1338
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>
1340
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>
1342
1343<p><a href="ch08.html#samba2-CHP-8-FIG-5">Figure 8-5</a> shows the dialog box for adding an ACE.
1344As you can see, there are more options for permissions in an ACL than
1345with the permission bits on typical Unix systems. You can learn more
1346about these settings in <em class="citetitle">Essential Windows NT System
1347Administration</em>, published by O'Reilly.</p>
1348
1349<p>In a networked environment where a Samba server is serving files to
1350Windows NT/2000/XP clients, Samba has to map Unix permissions for
1351files and directories to Windows NT/2000/XP access control lists.
1352When a Windows NT/2000/XP client accesses a shared file or directory
1353on a Samba server, Samba translates the object's
1354ownership, group, and permissions into an ACL and returns them to the
1355client.</p>
1356
1357<p><a href="ch08.html#samba2-CHP-8-FIG-6">Figure 8-6</a> shows the Properties dialog box for the
1358file <em class="filename">shopping_list.doc</em> that resides on the Samba
1359server.</p>
1360
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>
1362
1363<p>From Unix, this file appears as:</p>
1364
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>
1367
1368<p>Notice that because the file has read permissions for the owner, the
1369Read-only checkbox will show as cleared, even though the user on the
1370Windows client (who is not <tt class="literal">adilia</tt> in this example)
1371does not have read access permissions. The checkboxes here show only
1372DOS attributes. By clicking the Security tab, we can start to examine
1373the ACLs, as shown in <a href="ch08.html#samba2-CHP-8-FIG-7">Figure 8-7</a>.</p>
1374
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>
1376
1377<p>The owner of the file (<tt class="literal">adilia</tt>) is shown as one
1378entry, while the group (<tt class="literal">users</tt>) and other
1379permissions are presented as the groups called
1380<tt class="literal">users</tt> and <tt class="literal">Everyone</tt>. Clicking
1381one of the items in the upper windows causes the simplified view of
1382the permissions in that item to appear in the bottom window. Here,
1383the read/write permissions for <tt class="literal">adilia</tt> appear in a
1384manner that makes the security model of Unix and Windows seem
1385similar. However, clicking the Advanced . . . button brings up the
1386additional dialog box shown in <a href="ch08.html#samba2-CHP-8-FIG-8">Figure 8-8</a>.</p>
1387
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>
1389
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
1392with Take Ownership in the Permission column. This is a trick used by
1393Samba for ACLs that have no permissions on the Unix side. On Windows,
1394an ACL with nothing set results in no ACL at all, so Samba sets the
1395Take Ownership permission to make sure that all the ACLs
1396corresponding to the Unix &quot;user, group,
1397other&quot; permissions will show up on Windows. The Take
1398Ownership permission has no corresponding Unix attribute, so the
1399setting on Windows does not affect the actual file on the Unix system
1400in any way. Although Windows client users might be misled into
1401thinking they can take ownership of the file (that is, change the
1402ownership of the file to themselves), an actual attempt to do so will
1403fail.</p>
1404
1405<p>The Permissions column for the <tt class="literal">adilia</tt> ACL is
1406listed as Special because Samba reports permissions for the file that
1407do not correspond to settings for which Windows has a more
1408descriptive 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
1410can be viewed and perhaps modified.</p>
1411
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>
1413
1414<p>We say &quot;perhaps&quot; here because
1415checking or unchecking boxes in this dialog box might not result in
1416settings that Samba is able to map back into the Unix security model.
1417When a user attempts to modify a setting (either permissions or
1418ownership) that she does not have authority to change, or does not
1419correspond to a valid setting on the Unix system, Samba will respond
1420with an error dialog or by quietly ignoring the unmappable settings.</p>
1421
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
1423button.</p>
1424
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>
1426
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
1429the directory itself, and the other specifies permissions for the
1430directory's contents. When changing settings in the
1431View/Edit... dialog, there is an extra drop-down menu to apply the
1432settings either to just the directory or to some combination of the
1433directory and the files and directories it contains. If settings are
1434applied to more than just the directory, Samba will match the
1435behavior of a Windows server and change the permissions on the
1436contents of the directory, as specified in the dialog.</p>
1437
1438
1439<div class="sect2"><a name="samba2-CHP-8-SECT-3.1"/>
1440
1441<h3 class="head2">Unix ACLs</h3>
1442
1443<p><a name="INDEX-80"/><a name="INDEX-81"/>In
1444most cases, users of Windows clients will find the Unix security
1445model to be sufficient. However, in some cases, people might want the
1446Samba server to support the full Windows ACL security model. Even if
1447they don't need the fine-grained control over file
1448and directory permissions, they might find Samba's
1449translation between ACLs and Unix permissions to be a source of
1450confusion or frustration.</p>
1451
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
1454support of Windows NT/2000/XP ACLs. Versions of Unix that offer the
1455necessary support include the following:</p>
1456
1457<ul><li>
1458<p>Solaris 2.6 and later</p>
1459</li><li>
1460<p>SGI Irix</p>
1461</li><li>
1462<p>Linux, with Andreas Gr&uuml;nbacher's kernel
1463patch from <a href="http://acl.bestbits.at">http://acl.bestbits.at</a>
1464that adds ACL support to the Linux ext2 and ext3 filesystems</p>
1465</li><li>
1466<p>Linux, with the XFS filesystem</p>
1467</li><li>
1468<p>AIX</p>
1469</li><li>
1470<p>FreeBSD 5.0 and later</p>
1471</li><li>
1472<p>HP/UX 11.0 and later, with the JFS 3.3 filesystem layout Version 4</p>
1473</li></ul>
1474<p>If you are fortunate enough to have a Unix host operating system with
1475ACL support already provided, all you need to do is recompile Samba
1476using the <tt class="literal">--with-acl-support</tt> configure option, as
1477we described in <a href="ch02.html">Chapter 2</a>. If you are running
1478Linux and need to patch your kernel, things are much more
1479complicated. We suggest you refer to the documentation that comes
1480with the patch for details on using it.</p>
1481
1482
1483</div>
1484
1485
1486<div class="sect2"><a name="samba2-CHP-8-SECT-3.2"/>
1487
1488<h3 class="head2">Configuration Options for ACLs</h3>
1489
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
1491for working with Windows NT/2000/XP access control lists.</p>
1492
1493<a name="samba2-CHP-8-TABLE-3"/><h4 class="head4">Table 8-3. ACL configuration options</h4><table border="1">
1494
1495
1496
1497
1498
1499
1500<tr>
1501<th>
1502<p>Option</p>
1503</th>
1504<th>
1505<p>Parameters</p>
1506</th>
1507<th>
1508<p>Function</p>
1509</th>
1510<th>
1511<p>Default</p>
1512</th>
1513<th>
1514<p>Scope</p>
1515</th>
1516</tr>
1517
1518
1519<tr>
1520<td>
1521<p><tt class="literal">nt acl support</tt></p>
1522</td>
1523<td>
1524<p>Boolean</p>
1525</td>
1526<td>
1527<p>If <tt class="literal">yes</tt>, allows users on Windows NT/2000/XP clients
1528to modify ACL settings</p>
1529</td>
1530<td>
1531<p><tt class="literal">yes</tt></p>
1532</td>
1533<td>
1534<p>Share</p>
1535</td>
1536</tr>
1537<tr>
1538<td>
1539<p><tt class="literal">security mask</tt></p>
1540</td>
1541<td>
1542<p>numeric</p>
1543</td>
1544<td>
1545<p>Bitmask that allows or denies permission settings on files</p>
1546</td>
1547<td>
1548<p><tt class="literal">0777</tt></p>
1549</td>
1550<td>
1551<p>Share</p>
1552</td>
1553</tr>
1554<tr>
1555<td>
1556<p><tt class="literal">force security</tt> <tt class="literal">mode</tt></p>
1557</td>
1558<td>
1559<p>numeric</p>
1560</td>
1561<td>
1562<p>Bits that are always set when modifying file permissions</p>
1563</td>
1564<td>
1565<p><tt class="literal">0000</tt></p>
1566</td>
1567<td>
1568<p>Share</p>
1569</td>
1570</tr>
1571<tr>
1572<td>
1573<p><tt class="literal">directory</tt> <tt class="literal">security mask</tt></p>
1574</td>
1575<td>
1576<p>numeric</p>
1577</td>
1578<td>
1579<p>Bitmask that allows or denies permission settings on directories</p>
1580</td>
1581<td>
1582<p><tt class="literal">0777</tt></p>
1583</td>
1584<td>
1585<p>Share</p>
1586</td>
1587</tr>
1588<tr>
1589<td>
1590<p><tt class="literal">force directory</tt> <tt class="literal">security mode</tt></p>
1591</td>
1592<td>
1593<p>numeric</p>
1594</td>
1595<td>
1596<p>Bits that are always set when modifying directory permissions</p>
1597</td>
1598<td>
1599<p><tt class="literal">0000</tt></p>
1600</td>
1601<td>
1602<p>Share</p>
1603</td>
1604</tr>
1605
1606</table>
1607
1608
1609<div class="sect3"><a name="samba2-CHP-8-SECT-3.2.1"/>
1610
1611<a name="INDEX-86"/><h3 class="head3">nt acl support</h3>
1612
1613<p>This parameter defaults to <tt class="literal">yes</tt>, which allows users
1614on Windows NT/2000/XP clients to modify ACL settings for files on the
1615Samba server. When set to <tt class="literal">no</tt>, files show up as
1616owned by <tt class="literal">Everyone</tt>, with permissions appearing as
1617&quot;Full Control&quot;. However,
1618<em class="emphasis">actual</em> ownership and permissions are enforced as
1619whatever they are set to on the Samba server, and the user on the
1620Windows client cannot view or modify them with the dialog boxes used
1621for managing ACLs.</p>
1622
1623<p>When enabled, support for Windows NT/2000/XP ACLs is limited to
1624whatever ownerships and permissions can map into valid users and
1625permissions on the Samba server. If the server supports ACLs (either
1626&quot;out of the box&quot; or with an
1627additional patch to enhance the filesystem), Samba's
1628ACL support more closely matches that of a Windows NT/2000/XP server.</p>
1629
1630
1631</div>
1632
1633
1634
1635<div class="sect3"><a name="samba2-CHP-8-SECT-3.2.2"/>
1636
1637<h3 class="head3">security mask</h3>
1638
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
1641permissions users can modify from Windows NT/2000/XP clients. This is
1642for 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
1645parameter is assigned a numeric value that is a Unix-style
1646permissions mask. For bits in the mask that are set, the client can
1647modify the corresponding bits in the files'
1648permissions. If the bit is zero, the client cannot modify that
1649permission. For example, if <tt class="literal">security</tt>
1650<tt class="literal">mask</tt> is set as:</p>
1651
1652<blockquote><pre class="code">[data]
1653 security mask = 0777</pre></blockquote>
1654
1655<p>the client can modify all the user/group/other permissions for the
1656files in the share. This is the default. A value of
1657<tt class="literal">0</tt> would deny clients from changing any of the
1658permissions, and setting <tt class="literal">security</tt>
1659<tt class="literal">mask</tt> as:</p>
1660
1661<blockquote><pre class="code">[data]
1662 security mask = 0666</pre></blockquote>
1663
1664<p>would allow client users to modify the read and write permissions,
1665but not the execute permissions.</p>
1666
1667<p>Do not count on <tt class="literal">security</tt> <tt class="literal">mask</tt>
1668for complete control because if the user can access the files on the
1669Samba server through any other means (for example, by logging
1670directly into the Unix host), he can modify the permissions using
1671that method.</p>
1672
1673
1674</div>
1675
1676
1677
1678<div class="sect3"><a name="samba2-CHP-8-SECT-3.2.3"/>
1679
1680<h3 class="head3">force security mode</h3>
1681
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
1684used to define a set of permissions that are always set whenever the
1685user on a Windows NT/2000/XP client modifies a
1686file'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
1689handling directories.)</p>
1690
1691<p>Be careful to understand this properly. The mask given as the
1692parameter's value is not necessarily equal to the
1693resulting permissions on the file. The permissions that the client
1694user 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
1697that are turned on will cause the file's
1698corresponding 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>
1701
1702<blockquote><pre class="code">[data]
1703 force security mode = 0440</pre></blockquote>
1704
1705<p>(This sets the read bit for owner and group, but not other.) If a
1706user 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
1708permissions, the read permission for other
1709(<tt class="literal">Everyone</tt>) will be removed, but the read
1710permission for the owner and group will remain. Note that this
1711parameter cannot force a permission bit to be turned off.</p>
1712
1713<p>As with the <tt class="literal">security</tt> <tt class="literal">mask</tt>
1714option, if a user can access the files in the share through any means
1715other than Samba, she can easily work around Samba's
1716enforcement of this parameter.</p>
1717
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
1721from files.</p>
1722
1723
1724</div>
1725
1726
1727
1728<div class="sect3"><a name="samba2-CHP-8-SECT-3.2.4"/>
1729
1730<a name="INDEX-90"/><h3 class="head3">directory security mask</h3>
1731
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
1734directories 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
1737to modify all Unix permissions on directories in the share.</p>
1738
1739
1740</div>
1741
1742
1743
1744<div class="sect3"><a name="samba2-CHP-8-SECT-3.2.5"/>
1745
1746<a name="INDEX-91"/><h3 class="head3">force directory security mode</h3>
1747
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
1750that it operates on directories rather than files. It also has a
1751default value of <tt class="literal">0000</tt>, which allows Windows
1752NT/2000/XP client users to remove any permissions from directories in
1753the 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>
1754
1755
1756</div>
1757
1758
1759</div>
1760
1761
1762</div>
1763
1764
1765
1766<div class="sect1"><a name="samba2-CHP-8-SECT-4"/>
1767
1768<h2 class="head1">Name Mangling and Case</h2>
1769
1770<p><a name="INDEX-98"/><a name="INDEX-99"/><a name="INDEX-100"/><a name="INDEX-101"/>Back
1771in the days of DOS and Windows 3.1, every filename was limited to
1772eight uppercase characters, followed by a dot, and three more
1773uppercase characters. This was known as the <em class="firstterm">8.3
1774format</em> and was a huge nuisance. Windows 95/98/Me, Windows
1775NT/2000/XP, and Unix have since relaxed this problem by allowing
1776longer, sometimes case-sensitive, filenames. <a href="ch08.html#samba2-CHP-8-TABLE-4">Table 8-4</a> shows the current naming state of several
1777popular operating systems.</p>
1778
1779<a name="samba2-CHP-8-TABLE-4"/><h4 class="head4">Table 8-4. Operating system filename limitations</h4><table border="1">
1780
1781
1782
1783<tr>
1784<th>
1785<p>Operating system</p>
1786</th>
1787<th>
1788<p>File-naming rules</p>
1789</th>
1790</tr>
1791
1792
1793<tr>
1794<td>
1795<p>DOS 6.22 or below</p>
1796</td>
1797<td>
1798<p>Eight characters followed by a dot followed by a three-letter
1799extension (8.3 format); case-insensitive</p>
1800</td>
1801</tr>
1802<tr>
1803<td>
1804<p>Windows 3.1 for Workgroups</p>
1805</td>
1806<td>
1807<p>Eight characters followed by a dot followed by a three-letter
1808extension (8.3 format); case-insensitive</p>
1809</td>
1810</tr>
1811<tr>
1812<td>
1813<p>Windows 95/98/Me</p>
1814</td>
1815<td>
1816<p>255 characters; case-insensitive but case-preserving</p>
1817</td>
1818</tr>
1819<tr>
1820<td>
1821<p>Windows NT/2000/XP</p>
1822</td>
1823<td>
1824<p>255 characters; case-insensitive but case-preserving</p>
1825</td>
1826</tr>
1827<tr>
1828<td>
1829<p>Unix</p>
1830</td>
1831<td>
1832<p>255 characters; case-sensitive</p>
1833</td>
1834</tr>
1835
1836</table>
1837
1838<p>Samba still has to remain backward-compatible with network clients
1839that store files in just the 8.3 format, such as Windows for
1840Workgroups. If a user creates a file on a share called
1841<em class="emphasis">antidisestablishmentarianism.txt</em>, a Windows for
1842Workgroups client cannot tell it apart from another file in the same
1843directory called <em class="emphasis">antidisease.txt</em>. Like Windows
184495/98/Me and Windows NT/2000/XP, Samba has to employ a special method
1845for translating a long filename to an 8.3 filename in such a way that
1846similar filenames will not cause collisions. This is called
1847<em class="firstterm">name mangling</em>, and Samba deals with this in a
1848manner that is similar, but not identical to, Windows 95 and its
1849successors.</p>
1850
1851
1852<div class="sect2"><a name="samba2-CHP-8-SECT-4.1"/>
1853
1854<h3 class="head2">The Samba Mangling Operation</h3>
1855
1856<p><a name="INDEX-102"/>Here is how Samba mangles a long
1857filename into an 8.3 filename:</p>
1858
1859<ul><li>
1860<p>If the original filename does not begin with a dot, the first five
1861characters before the dot (if there is one) are converted to
1862uppercase. These characters are used as the first five characters of
1863the 8.3 mangled filename.</p>
1864</li><li>
1865<p>If the original filename begins with a dot, the dot is removed and
1866then the previous step is performed on what is left.</p>
1867</li><li>
1868<p>These characters are immediately followed by a special mangling
1869character: by default, a tilde (~), although Samba allows you to
1870change this character.</p>
1871</li><li>
1872<p>The base of the long filename before the last period is hashed into a
1873two-character code; parts of the name after the last dot can be used
1874if necessary. This two-character code is appended to the filename
1875after the mangling character.</p>
1876</li><li>
1877<p>The first three characters after the last dot (if there is one) of
1878the original filename are converted to uppercase and appended onto
1879the mangled name as the extension. If the original filename began
1880with a dot, three underscores ( <tt class="literal">_ _ _</tt> ) are used
1881as the extension instead.</p>
1882</li></ul>
1883<p>Here are some examples:</p>
1884
1885<blockquote><pre class="code">virtuosity.dat VIRTU~F1.DAT
1886.htaccess HTACC~U0._ _ _
1887hello.java HELLO~1F.JAV
1888team.config.txt TEAMC~04.TXT
1889antidisestablishmentarianism.txt ANTID~E3.TXT
1890antidisease.txt ANTID~9K.TXT</pre></blockquote>
1891
1892<p>Using these rules will allow Windows for Workgroups to differentiate
1893the two files on behalf of the poor individual who is forced to see
1894the network through the eyes of that operating system. Note that the
1895same long filename should always hash to the same mangled name with
1896Samba; this doesn't always happen with Windows. The
1897downside of this approach is that there can still be collisions;
1898however, the chances are greatly reduced.</p>
1899
1900<p>You generally want to use the mangling configuration options with
1901only the oldest clients. We recommend doing this without disrupting
1902other clients by adding an <tt class="literal">include</tt> directive to
1903the <em class="filename">smb.conf</em> file:</p>
1904
1905<blockquote><pre class="code">[global]
1906 include = /usr/local/samba/lib/smb.conf.%a</pre></blockquote>
1907
1908<p>This resolves to <em class="filename">smb.conf.WfWg</em> when a Windows
1909for Workgroups client attaches. Now you can create a file
1910<em class="filename">/usr/local/samba/lib/smb.conf.WfWg</em>, which might
1911contain these options:</p>
1912
1913<blockquote><pre class="code">[global]
1914 case sensitive = no
1915 default case = upper
1916 preserve case = no
1917 short preserve case = no
1918 mangle case = yes
1919 mangled names= yes</pre></blockquote>
1920
1921<p>If you are not using Windows for Workgroups, you probably do not need
1922to change any of these options from their defaults.</p>
1923
1924
1925<div class="sect3"><a name="samba2-CHP-8-SECT-4.1.1"/>
1926
1927<h3 class="head3">Representing and resolving filenames with Samba</h3>
1928
1929<p><a name="INDEX-103"/>Another item that we should
1930point out is that there is a difference between how an operating
1931system <em class="emphasis">represents</em> a file and how it
1932<em class="emphasis">resolves</em> it. For example, you have likely run
1933across a file on a Windows system called
1934<em class="filename">README.TXT</em>. The file can be represented by the
1935operating system entirely in uppercase letters. However, if you open
1936an MS-DOS command prompt and enter the command:</p>
1937
1938<blockquote><pre class="code">C:\&gt; <tt class="userinput"><b>notepad readme.txt</b></tt></pre></blockquote>
1939
1940<p>the all-caps file is loaded into the editing program, even though you
1941typed the name in lowercase letters.</p>
1942
1943<p>This is because the Windows 95/98/Me and Windows NT/2000/XP families
1944of operating systems resolve filenames in a case-insensitive manner,
1945even though the files are represented in a case-sensitive manner.
1946Unix-based operating systems, on the other hand, always resolve files
1947in a case-sensitive manner; if you try to edit
1948<em class="filename">README.TXT</em> with the command:</p>
1949
1950<blockquote><pre class="code">$ <tt class="userinput"><b>vi readme.txt</b></tt></pre></blockquote>
1951
1952<p>you will likely be editing the empty buffer of a new file.</p>
1953
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
1956to <tt class="literal">yes</tt>, Samba will always use the case provided by
1957the operating system for representing (not resolving) filenames. If
1958it is set to <tt class="literal">no</tt>, it will use the case specified by
1959the <tt class="literal">default</tt><a name="INDEX-106"/> <tt class="literal">case</tt> option.
1960The 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
1963is set to <tt class="literal">yes</tt>, Samba will use the default case of
1964the operating system for representing 8.3 filenames; otherwise, it
1965will use the case specified by the <tt class="literal">default</tt>
1966<tt class="literal">case</tt> option. Finally, Samba will always resolve
1967filenames in its shares based on the value of the
1968<tt class="literal">case</tt> <tt class="literal">sensitive</tt> option.</p>
1969
1970
1971</div>
1972
1973
1974</div>
1975
1976
1977<div class="sect2"><a name="samba2-CHP-8-SECT-4.2"/>
1978
1979<h3 class="head2">Mangling Options</h3>
1980
1981<p><a name="INDEX-108"/><a name="INDEX-109"/>Samba
1982allows more refined instructions on how it should perform name
1983mangling, including those controlling the case sensitivity, the
1984character inserted to form a mangled name, and the ability to map
1985filenames manually from one format to another. These options are
1986shown in <a href="ch08.html#samba2-CHP-8-TABLE-5">Table 8-5</a>.</p>
1987
1988<a name="samba2-CHP-8-TABLE-5"/><h4 class="head4">Table 8-5. Name-mangling options</h4><table border="1">
1989
1990
1991
1992
1993
1994
1995<tr>
1996<th>
1997<p>Option</p>
1998</th>
1999<th>
2000<p>Parameters</p>
2001</th>
2002<th>
2003<p>Function</p>
2004</th>
2005<th>
2006<p>Default</p>
2007</th>
2008<th>
2009<p>Scope</p>
2010</th>
2011</tr>
2012
2013
2014<tr>
2015<td>
2016<p><tt class="literal">case sensitive</tt></p>
2017
2018<p><tt class="literal">(casesignames)</tt></p>
2019</td>
2020<td>
2021<p>Boolean</p>
2022</td>
2023<td>
2024<p>If <tt class="literal">yes</tt>, treats filenames as case-sensitive
2025(Windows doesn't).</p>
2026</td>
2027<td>
2028<p><tt class="literal">no</tt></p>
2029</td>
2030<td>
2031<p>Share</p>
2032</td>
2033</tr>
2034<tr>
2035<td>
2036<p><tt class="literal">default case</tt></p>
2037</td>
2038<td>
2039<p>string (<tt class="literal">upper</tt> or <tt class="literal">lower</tt>)</p>
2040</td>
2041<td>
2042<p>Case to assume as default (used only when preserve case is
2043<tt class="literal">no</tt>).</p>
2044</td>
2045<td>
2046<p>Lower</p>
2047</td>
2048<td>
2049<p>Share</p>
2050</td>
2051</tr>
2052<tr>
2053<td>
2054<p><tt class="literal">preserve case</tt></p>
2055</td>
2056<td>
2057<p>Boolean</p>
2058</td>
2059<td>
2060<p>If <tt class="literal">yes</tt>, keep the case the client supplied (i.e.,
2061do not convert to <tt class="literal">default</tt>
2062<tt class="literal">case</tt>).</p>
2063</td>
2064<td>
2065<p><tt class="literal">yes</tt></p>
2066</td>
2067<td>
2068<p>Share</p>
2069</td>
2070</tr>
2071<tr>
2072<td>
2073<p><tt class="literal">short preserve case</tt></p>
2074</td>
2075<td>
2076<p>Boolean</p>
2077</td>
2078<td>
2079<p>If <tt class="literal">yes</tt>, preserve case of 8.3-format names that the
2080client provides.</p>
2081</td>
2082<td>
2083<p><tt class="literal">yes</tt></p>
2084</td>
2085<td>
2086<p>Share</p>
2087</td>
2088</tr>
2089<tr>
2090<td>
2091<p><tt class="literal">mangled names</tt></p>
2092</td>
2093<td>
2094<p>Boolean</p>
2095</td>
2096<td>
2097<p>Mangles long names into 8.3 DOS format.</p>
2098</td>
2099<td>
2100<p><tt class="literal">yes</tt></p>
2101</td>
2102<td>
2103<p>Share</p>
2104</td>
2105</tr>
2106<tr>
2107<td>
2108<p><tt class="literal">mangle case</tt></p>
2109</td>
2110<td>
2111<p>Boolean</p>
2112</td>
2113<td>
2114<p>Mangle a name if it is mixed case.</p>
2115</td>
2116<td>
2117<p><tt class="literal">no</tt></p>
2118</td>
2119<td>
2120<p>Share</p>
2121</td>
2122</tr>
2123<tr>
2124<td>
2125<p><tt class="literal">mangling char</tt></p>
2126</td>
2127<td>
2128<p>string (single character)</p>
2129</td>
2130<td>
2131<p>Gives mangling character.</p>
2132</td>
2133<td>
2134<p><tt class="literal">~</tt></p>
2135</td>
2136<td>
2137<p>Share</p>
2138</td>
2139</tr>
2140<tr>
2141<td>
2142<p><tt class="literal">mangled stack</tt></p>
2143</td>
2144<td>
2145<p>numeric</p>
2146</td>
2147<td>
2148<p>Number of mangled names to keep on the local mangling stack.</p>
2149</td>
2150<td>
2151<p><tt class="literal">50</tt></p>
2152</td>
2153<td>
2154<p>Global</p>
2155</td>
2156</tr>
2157<tr>
2158<td>
2159<p><tt class="literal">mangled map</tt></p>
2160</td>
2161<td>
2162<p>string (list of patterns)</p>
2163</td>
2164<td>
2165<p>Allows mapping of filenames from one format into another.</p>
2166</td>
2167<td>
2168<p>None</p>
2169</td>
2170<td>
2171<p>Share</p>
2172</td>
2173</tr>
2174
2175</table>
2176
2177
2178<div class="sect3"><a name="samba2-CHP-8-SECT-4.2.1"/>
2179
2180<a name="INDEX-110"/><h3 class="head3">case sensitive</h3>
2181
2182<p>This share-level option, which has the obtuse synonym
2183<tt class="literal">casesignames</tt>, specifies whether Samba should
2184preserve case when resolving filenames in a specific share. The
2185default value for this option is <tt class="literal">no</tt>, which is how
2186Windows handles file resolution. If clients are using an operating
2187system that takes advantage of case-sensitive filenames, you can set
2188this configuration option to <tt class="literal">yes</tt> as shown here:</p>
2189
2190<blockquote><pre class="code">[accounting]
2191 case sensitive = yes</pre></blockquote>
2192
2193<p>Otherwise, we recommend that you leave this option set to its default.</p>
2194
2195
2196</div>
2197
2198
2199
2200<div class="sect3"><a name="samba2-CHP-8-SECT-4.2.2"/>
2201
2202<h3 class="head3">default case</h3>
2203
2204<p>The <tt class="literal">default</tt><a name="INDEX-111"/> <tt class="literal">case</tt> option
2205is used with <tt class="literal">preserve</tt> <tt class="literal">case</tt>.
2206This specifies the default case (upper or lower) Samba uses to create
2207a file on one of its shares on behalf of a client. The default case
2208is <tt class="literal">lower</tt>, which means that newly created files
2209will have lowercase names. If you need to, you can override this
2210global option by specifying the following:</p>
2211
2212<blockquote><pre class="code">[global]
2213 default case = upper</pre></blockquote>
2214
2215<p>If you specify this value, the names of newly created files are
2216translated into uppercase and cannot be overridden in a program. We
2217recommend that you use the default value unless you are dealing with
2218a Windows for Workgroups or other 8.3 client, in which case it should
2219be <tt class="literal">upper</tt>.</p>
2220
2221
2222</div>
2223
2224
2225
2226<div class="sect3"><a name="samba2-CHP-8-SECT-4.2.3"/>
2227
2228<a name="INDEX-112"/><h3 class="head3">preserve case</h3>
2229
2230<p>This option specifies whether a file created by Samba on behalf of
2231the client is created with the case provided by the client operating
2232system or the case specified by the earlier
2233<tt class="literal">default</tt> <tt class="literal">case</tt> configuration
2234option. The default value is <tt class="literal">yes</tt>, which uses the
2235case 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>
2238
2239<p>Note that this option does not handle 8.3 file requests sent from the
2240client&mdash;see the upcoming <tt class="literal">short</tt>
2241<tt class="literal">preserve</tt> <tt class="literal">case</tt> option. You might
2242want to set this option to <tt class="literal">yes</tt>, for example, if
2243applications that create files on the Samba server demand the file be
2244all uppercase. If instead you want Samba to mimic the behavior of a
2245Windows NT filesystem, you can leave this option set to its default,
2246<tt class="literal">yes</tt>.</p>
2247
2248
2249</div>
2250
2251
2252
2253<div class="sect3"><a name="samba2-CHP-8-SECT-4.2.4"/>
2254
2255<a name="INDEX-113"/><h3 class="head3">short preserve case</h3>
2256
2257<p>This option specifies whether an 8.3 filename created by Samba on
2258behalf of the client is created with the default case of the client
2259operating system or the case specified by the
2260<tt class="literal">default</tt> <tt class="literal">case</tt> configuration
2261option. The default value is <tt class="literal">yes</tt>, which uses the
2262case provided by the client operating system. You can let Samba
2263choose the case through the <tt class="literal">default</tt>
2264<tt class="literal">case</tt> option by setting it as follows:</p>
2265
2266<blockquote><pre class="code">[global]
2267 short preserve case = no</pre></blockquote>
2268
2269<p>If you want to force Samba to mimic the behavior of a Windows NT
2270filesystem, you can leave this option set to its default,
2271<tt class="literal">yes</tt>.</p>
2272
2273
2274</div>
2275
2276
2277
2278<div class="sect3"><a name="samba2-CHP-8-SECT-4.2.5"/>
2279
2280<a name="INDEX-114"/><h3 class="head3">mangled names</h3>
2281
2282<p>This share-level option specifies whether Samba will mangle filenames
2283for 8.3 clients. If the option is set to <tt class="literal">no</tt>, Samba
2284will not mangle the names, and (depending on the client) they will
2285either be invisible or appear truncated to those using 8.3 operating
2286systems. The default value is <tt class="literal">yes</tt>. You can
2287override it per share as follows:</p>
2288
2289<blockquote><pre class="code">[data]
2290 mangled names = no</pre></blockquote>
2291
2292
2293</div>
2294
2295
2296
2297<div class="sect3"><a name="samba2-CHP-8-SECT-4.2.6"/>
2298
2299<a name="INDEX-115"/><h3 class="head3">mangle case</h3>
2300
2301<p>This option tells Samba whether it should mangle filenames that are
2302not composed entirely of the case specified using the
2303<tt class="literal">default</tt> <tt class="literal">case</tt> configuration
2304option. The default for this option is <tt class="literal">no</tt>. If you
2305set it to <tt class="literal">yes</tt>, you should be sure that all clients
2306can handle the mangled filenames that result. You can override it per
2307share as follows:</p>
2308
2309<blockquote><pre class="code">[data]
2310 mangle case = yes</pre></blockquote>
2311
2312<p>We recommend that you leave this option alone unless you have a
2313well-justified need to change it.</p>
2314
2315
2316</div>
2317
2318
2319
2320<div class="sect3"><a name="samba2-CHP-8-SECT-4.2.7"/>
2321
2322<a name="INDEX-116"/><h3 class="head3">mangling char</h3>
2323
2324<p>This share-level option specifies the mangling character used when
2325Samba mangles filenames into the 8.3 format. The default character
2326used is a tilde (~). You can reset it to whatever character you wish.
2327For instance:</p>
2328
2329<blockquote><pre class="code">[data]
2330 mangling char = #</pre></blockquote>
2331
2332
2333</div>
2334
2335
2336
2337<div class="sect3"><a name="samba2-CHP-8-SECT-4.2.8"/>
2338
2339<a name="INDEX-117"/><h3 class="head3">mangled stack</h3>
2340
2341<p>Samba maintains a local stack of recently mangled 8.3 filenames; this
2342stack can be used to reverse-map mangled filenames back to their
2343original state. This is often needed by applications that create and
2344save a file, close it, and need to modify it later. The default
2345number of long filename/mangled filename pairs stored on this stack
2346is 50. However, if you want to cut down on the amount of processor
2347time used to mangle filenames, you can increase the size of the stack
2348to whatever you wish, at the expense of memory and slightly slower
2349file access:</p>
2350
2351<blockquote><pre class="code">[global]
2352 mangled stack = 100</pre></blockquote>
2353
2354
2355</div>
2356
2357
2358
2359<div class="sect3"><a name="samba2-CHP-8-SECT-4.2.9"/>
2360
2361<a name="INDEX-118"/><h3 class="head3">mangled map</h3>
2362
2363<p>If the default behavior of name mangling is not sufficient, you can
2364give Samba further instructions on how to behave using the
2365<tt class="literal">mangled</tt> <tt class="literal">map</tt> option. This option
2366allows you to specify mapping patterns that can be used in place of
2367name mangling performed by Samba. For example:</p>
2368
2369<blockquote><pre class="code">[data]
2370 mangled map =(*.database *.db) (*.class *.cls)</pre></blockquote>
2371
2372<p>Here, Samba is instructed to search each encountered file for
2373characters that match the first pattern specified in the parenthesis
2374and convert them to the modified second pattern in the parenthesis
2375for display on an 8.3 client. This is useful in the event that name
2376mangling converts the filename incorrectly or converts it to a format
2377that the client cannot understand readily. Patterns are separated by
2378whitespaces. <a name="INDEX-119"/><a name="INDEX-120"/> <a name="INDEX-121"/><a name="INDEX-122"/></p>
2379
2380
2381</div>
2382
2383
2384</div>
2385
2386
2387</div>
2388
2389
2390
2391<div class="sect1"><a name="samba2-CHP-8-SECT-5"/>
2392
2393<h2 class="head1">Locks and Oplocks</h2>
2394
2395<p><a name="INDEX-123"/><a name="INDEX-124"/><a name="INDEX-125"/><a name="INDEX-126"/>Concurrent
2396writes to a single file are not desirable in any operating system. To
2397prevent this, most operating systems use <em class="firstterm">locks</em>
2398to guarantee that only one process can write to a file at a time.
2399Operating systems traditionally lock entire files, although newer
2400ones allow a range of bytes within a file to be locked. If another
2401process attempts to write to a file (or section of one) that is
2402already locked, it receives an error from the operating system and
2403will have to wait until the lock is released.</p>
2404
2405<p>Samba supports the standard DOS and NT filesystem (deny-mode) locking
2406requests&mdash;which allow only one process to write to an entire
2407file on a server at a given time&mdash;as well as byte-range locking.
2408In addition, Samba supports a locking mechanism known in the Windows
2409NT 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>
2412
2413
2414<div class="sect2"><a name="samba2-CHP-8-SECT-5.1"/>
2415
2416<h3 class="head2">Opportunistic Locking</h3>
2417
2418<p>Opportunistic locking allows a client to notify the Samba server that
2419it will not only be the exclusive writer of a file, but will also
2420cache its changes to that file locally to speed up access by reducing
2421network activity. This can result in a large performance
2422gain&mdash;typically 30%&mdash;while at the same time reserving
2423network bandwidth for other purposes.</p>
2424
2425<p>Because exclusive access can be obtained using regular file locks,
2426the value of opportunistic locks is not so much to lock the file as
2427it is to cache it. In fact, a better name for opportunistic locking
2428might be <em class="firstterm">opportunistic caching</em>.</p>
2429
2430<p>When Samba knows that a file in one of its shares has been oplocked
2431by a client, it marks its version as having an opportunistic lock and
2432waits for the client to complete work on the file, at which point it
2433expects the client to send its changes back to the Samba server for
2434synchronization with the copy on the server.</p>
2435
2436<p>If a second client requests access to that file before the first
2437client has finished working on it, Samba sends an oplock break
2438request to the first client. This tells the client to stop caching
2439its changes and return the current state of the file to the server so
2440that the interrupting client can use it as it sees fit. An
2441opportunistic lock, however, is not a replacement for a standard
2442deny-mode lock. It is not unheard of for the interrupting process to
2443be granted an oplock break only to discover that the original process
2444also 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>
2445
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>
2447
2448<p>In most cases, the extra performance resulting from the use of
2449oplocks is highly desirable. However, allowing the client to cache
2450data can be a big risk if either the client or network hardware are
2451unreliable. Suppose a client opens a file for writing, creating an
2452oplock on it. When another client also tries to open the file, an
2453oplock break request is sent to the first client. If this request
2454goes unfulfilled for any reason and the second client starts writing
2455to the file, the file can be easily corrupted as a result of the two
2456processes writing to it concurrently. Unfortunately, this scenario is
2457very real. Uncoordinated behavior such as this has been observed many
2458times among Windows clients in SMB networks (with files served by
2459Windows NT/2000 or Samba). Typically, the affected files are database
2460files, which multiple clients open concurrently for writing.</p>
2461
2462<p>A more concrete example of <a name="INDEX-129"/>oplock failure occurs when database
2463files are very large. If a client is allowed to oplock this kind of
2464file, there can be a huge delay while the client copies the entire
2465file from the server to cache it, even though it might need to update
2466only one record. The situation goes from bad to worse when another
2467client tries to open the oplocked file. The first client might need
2468to write the entire file back to the server before the second
2469client's file open request can succeed. This results
2470in another huge delay (for both clients), which in practice often
2471results in a failed open due to a timeout on the second client,
2472perhaps along with a message warning of possible database corruption!</p>
2473
2474<p>If you are having problems of this variety, you can turn off oplocks
2475for 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>
2478
2479<blockquote><pre class="code">[dbdata]
2480 veto oplock files = /*.dbm/</pre></blockquote>
2481
2482<p>Use the value of the parameter (a list of filename-matching patterns
2483separated by slash characters) to match all the files in the share
2484that might be a source of trouble. The syntax of this parameter is
2485similar to that of the <tt class="literal">veto</tt>
2486<tt class="literal">files</tt> parameter.</p>
2487
2488<p>If you want to be really careful and can live with reduced
2489performance, you can turn off oplocks altogether, preventing the
2490oplock break problem from ever occurring:</p>
2491
2492<blockquote><pre class="code">[global]
2493 oplocks = no</pre></blockquote>
2494
2495<p>This disables oplocks for all files in all shares served by the Samba
2496server. If you wish to disable oplocks in just a specific share, you
2497can specify the <tt class="literal">oplocks</tt> <tt class="literal">=</tt>
2498<tt class="literal">no</tt> parameter in just that share:</p>
2499
2500<blockquote><pre class="code">[database]
2501 oplocks = no</pre></blockquote>
2502
2503<p>This example allows other shares, which might have less sensitive
2504data, to attain better performance, while trading performance for
2505better data integrity for files in the <tt class="literal">[database]</tt>
2506share.</p>
2507
2508
2509</div>
2510
2511
2512<div class="sect2"><a name="samba2-CHP-8-SECT-5.2"/>
2513
2514<h3 class="head2">Unix and Oplocks</h3>
2515
2516<p><a name="INDEX-131"/>Most of the time, oplocks help Windows
2517client systems cooperate to avoid overwriting each
2518other's changes. Unix systems also have file-locking
2519mechanisms to allow Unix processes to cooperate with each other. But
2520if a file stored on a Samba system is accessed by both a Windows
2521network client and a local Unix process&mdash;without an additional
2522coordination between the two systems&mdash;the Unix process could
2523easily ride roughshod over an oplock.</p>
2524
2525<p>Some Unix systems have enhanced kernels that understand the Windows
2526oplocks maintained by Samba. Currently the support exists only in SGI
2527Irix and Linux.</p>
2528
2529<p>If you leave oplocks enabled and your Unix system does not support
2530kernel oplocks, you could end up with corrupted data when somebody
2531runs a Unix process that reads or writes a file that Windows users
2532also 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
2535anticipate which Samba files are used by both Windows users and Unix
2536users. For example, suppose the <tt class="literal">[usrfiles]</tt> share
2537contains some ASCII text files with the <em class="filename">.txt</em>
2538filename extension and OpenOffice word processor documents with the
2539<em class="filename">.doc</em> filename extension, which Unix and Windows
2540users both modify. We can use <tt class="literal">veto</tt>
2541<tt class="literal">oplock</tt> <tt class="literal">files</tt> like this:</p>
2542
2543<blockquote><pre class="code">[usrfiles]
2544 veto oplock files = /*.txt/*.doc/</pre></blockquote>
2545
2546<p>This will suppress the use of oplocks on <em class="filename">.txt</em>
2547and <em class="filename">.doc</em> files, which will suppress client
2548caching, while allowing the Windows and Unix programs to use regular
2549file locking to prevent concurrent writes to the same file.</p>
2550
2551
2552</div>
2553
2554
2555<div class="sect2"><a name="samba2-CHP-8-SECT-5.3"/>
2556
2557<h3 class="head2">Locks and Oplocks Configuration Options</h3>
2558
2559<p><a name="INDEX-133"/><a name="INDEX-134"/>Samba's options for
2560locks and oplocks are given in <a href="ch08.html#samba2-CHP-8-TABLE-6">Table 8-6</a>.</p>
2561
2562<a name="samba2-CHP-8-TABLE-6"/><h4 class="head4">Table 8-6. Locks and oplocks configuration options</h4><table border="1">
2563
2564
2565
2566
2567
2568
2569<tr>
2570<th>
2571<p>Option</p>
2572</th>
2573<th>
2574<p>Parameters</p>
2575</th>
2576<th>
2577<p>Function</p>
2578</th>
2579<th>
2580<p>Default</p>
2581</th>
2582<th>
2583<p>Scope</p>
2584</th>
2585</tr>
2586
2587
2588<tr>
2589<td>
2590<p><tt class="literal">locking</tt></p>
2591</td>
2592<td>
2593<p>Boolean</p>
2594</td>
2595<td>
2596<p>If <tt class="literal">yes</tt>, turns on byte-range locks.</p>
2597</td>
2598<td>
2599<p><tt class="literal">yes</tt></p>
2600</td>
2601<td>
2602<p>Share</p>
2603</td>
2604</tr>
2605<tr>
2606<td>
2607<p><tt class="literal">strict</tt> <tt class="literal">locking</tt></p>
2608</td>
2609<td>
2610<p>Boolean</p>
2611</td>
2612<td>
2613<p>If <tt class="literal">yes</tt>, denies access to an entire file if a
2614byte-range lock exists in it.</p>
2615</td>
2616<td>
2617<p><tt class="literal">no</tt></p>
2618</td>
2619<td>
2620<p>Share</p>
2621</td>
2622</tr>
2623<tr>
2624<td>
2625<p><tt class="literal">posix locking</tt></p>
2626</td>
2627<td>
2628<p>Boolean</p>
2629</td>
2630<td>
2631<p>If <tt class="literal">yes</tt>, maps oplocks to POSIX locks on the local
2632system.</p>
2633</td>
2634<td>
2635<p><tt class="literal">yes</tt></p>
2636</td>
2637<td>
2638<p>Share</p>
2639</td>
2640</tr>
2641<tr>
2642<td>
2643<p><tt class="literal">oplocks</tt></p>
2644</td>
2645<td>
2646<p>Boolean</p>
2647</td>
2648<td>
2649<p>If <tt class="literal">yes</tt>, turns on local caching of files on the
2650client for this share.</p>
2651</td>
2652<td>
2653<p><tt class="literal">yes</tt></p>
2654</td>
2655<td>
2656<p>Share</p>
2657</td>
2658</tr>
2659<tr>
2660<td>
2661<p><tt class="literal">kernel</tt> <tt class="literal">oplocks</tt></p>
2662</td>
2663<td>
2664<p>Boolean</p>
2665</td>
2666<td>
2667<p>If <tt class="literal">yes</tt>, indicates that the kernel supports oplocks.</p>
2668</td>
2669<td>
2670<p><tt class="literal">yes</tt></p>
2671</td>
2672<td>
2673<p>Global</p>
2674</td>
2675</tr>
2676<tr>
2677<td>
2678<p><tt class="literal">level2 oplocks</tt></p>
2679</td>
2680<td>
2681<p>Boolean</p>
2682</td>
2683<td>
2684<p>If <tt class="literal">yes</tt>, allows oplocks to downgrade to read-only.</p>
2685</td>
2686<td>
2687<p><tt class="literal">yes</tt></p>
2688</td>
2689<td>
2690<p>Share</p>
2691</td>
2692</tr>
2693<tr>
2694<td>
2695<p><tt class="literal">fake oplocks</tt></p>
2696</td>
2697<td>
2698<p>Boolean</p>
2699</td>
2700<td>
2701<p>If <tt class="literal">yes</tt>, tells client the lock was obtained, but
2702doesn't actually lock it.</p>
2703</td>
2704<td>
2705<p><tt class="literal">no</tt></p>
2706</td>
2707<td>
2708<p>Share</p>
2709</td>
2710</tr>
2711<tr>
2712<td>
2713<p><tt class="literal">blocking</tt> <tt class="literal">locks</tt></p>
2714</td>
2715<td>
2716<p>Boolean</p>
2717</td>
2718<td>
2719<p>Allows lock requestor to wait for the lock to be granted.</p>
2720</td>
2721<td>
2722<p><tt class="literal">yes</tt></p>
2723</td>
2724<td>
2725<p>Share</p>
2726</td>
2727</tr>
2728<tr>
2729<td>
2730<p><tt class="literal">veto oplock</tt> <tt class="literal">files</tt></p>
2731</td>
2732<td>
2733<p>string (list of filenames)</p>
2734</td>
2735<td>
2736<p>Does not oplock specified files.</p>
2737</td>
2738<td>
2739<p>None</p>
2740</td>
2741<td>
2742<p>Share</p>
2743</td>
2744</tr>
2745<tr>
2746<td>
2747<p><tt class="literal">lock</tt> <tt class="literal">directory</tt></p>
2748</td>
2749<td>
2750<p>string (fully qualified pathname)</p>
2751</td>
2752<td>
2753<p>Sets the location where various Samba files, including locks, are
2754stored.</p>
2755</td>
2756<td>
2757<p>As specified in Samba makefile</p>
2758</td>
2759<td>
2760<p>Global</p>
2761</td>
2762</tr>
2763
2764</table>
2765
2766
2767<div class="sect3"><a name="samba2-CHP-8-SECT-5.3.1"/>
2768
2769<h3 class="head3">locking</h3>
2770
2771<p>The <tt class="literal">locking</tt><a name="INDEX-135"/> option can be used to tell
2772Samba to engage or disengage server-side byte-range locks on behalf
2773of the client. Samba implements byte-range locks on the server side
2774with normal Unix advisory locks and consequently prevents other
2775properly behaved Unix processes from overwriting a locked byte range.</p>
2776
2777<p>This option can be specified per share as follows:</p>
2778
2779<blockquote><pre class="code">[accounting]
2780 locking = yes</pre></blockquote>
2781
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
2784either type of lock releases it (or crashes). If, however, the option
2785is set to <tt class="literal">no</tt>, no byte-range locks are kept for the
2786files, although requests to lock and unlock files will appear to
2787succeed. The option is set to <tt class="literal">yes</tt> by default;
2788however, you can turn this option off if you have read-only media.</p>
2789
2790
2791</div>
2792
2793
2794
2795<div class="sect3"><a name="samba2-CHP-8-SECT-5.3.2"/>
2796
2797<a name="INDEX-136"/><h3 class="head3">strict locking</h3>
2798
2799<p>This option checks every file access for a byte-range lock on the
2800range of bytes being accessed. This is typically not needed if a
2801client adheres to all the locking mechanisms in place. This option is
2802set to <tt class="literal">no</tt> by default; however, you can reset it
2803per share as follows:</p>
2804
2805<blockquote><pre class="code">[accounting]
2806 strict locking = yes</pre></blockquote>
2807
2808<p>If this option is set to <tt class="literal">yes</tt>, mandatory locks are
2809enforced on any file with byte-range locks.</p>
2810
2811
2812</div>
2813
2814
2815
2816<div class="sect3"><a name="samba2-CHP-8-SECT-5.3.3"/>
2817
2818<a name="INDEX-137"/><h3 class="head3">posix locking</h3>
2819
2820<p>On systems that support POSIX locking, Samba automatically maps
2821oplocks 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
2824change 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>
2827
2828
2829</div>
2830
2831
2832
2833<div class="sect3"><a name="samba2-CHP-8-SECT-5.3.4"/>
2834
2835<a name="INDEX-138"/><h3 class="head3">oplocks</h3>
2836
2837<p>This option enables or disables support for oplocks on the client.
2838The option is enabled by default. However, you can disable it with
2839the following command:</p>
2840
2841<blockquote><pre class="code">[data]
2842 oplocks = no</pre></blockquote>
2843
2844<p>If you are in an extremely unstable network environment or have many
2845clients that cannot take advantage of opportunistic locking, it might
2846be better to shut this Samba feature off. If the host operating
2847system does not support kernel oplocks, oplocks should be disabled if
2848users are accessing the same files from both Unix applications (such
2849as <em class="emphasis">vi</em>) and SMB clients.</p>
2850
2851
2852</div>
2853
2854
2855
2856<div class="sect3"><a name="samba2-CHP-8-SECT-5.3.5"/>
2857
2858<a name="INDEX-139"/><h3 class="head3">kernel oplocks</h3>
2859
2860<p>If a Unix application on the Samba host system (that is not part of
2861the Samba suite) tries to open a file for writing that Samba has
2862oplocked to a Windows client, it is likely to succeed (depending on
2863the operating system), and both Samba and the client are never aware
2864of it.</p>
2865
2866<p>Some versions of Unix have support for oplocks in the kernel that can
2867work along with Samba's oplocks. In this case, the
2868Unix process trying to open the file is suspended while Samba directs
2869the client to write its copy back. After that has happened, the
2870operating system allows the open to complete. At the time of this
2871writing, this feature is supported only by SGI Irix and Linux.</p>
2872
2873
2874</div>
2875
2876
2877
2878<div class="sect3"><a name="samba2-CHP-8-SECT-5.3.6"/>
2879
2880<a name="INDEX-140"/><h3 class="head3">level2 oplocks</h3>
2881
2882<p>Windows NT/2000/XP clients can downgrade their read-write oplocks to
2883read-only oplocks when another client opens the same file. This can
2884result in significant improvements in performance on files that are
2885written infrequently or not at all&mdash;especially
2886executables&mdash;because all clients can then maintain a read-ahead
2887cache 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
2889probably won't need to change it.</p>
2890
2891<p>Currently, Samba cannot support level 2 oplocks along with kernel
2892oplocks and automatically disables level 2 oplocks when kernel
2893oplocks are in use. (This might change in future releases as improved
2894support for oplocks is added by the Samba developers.) If you are
2895running Samba on a host system that supports kernel oplocks, you must
2896set <tt class="literal">kernel</tt> <tt class="literal">oplocks</tt>
2897<tt class="literal">=</tt> <tt class="literal">no</tt> to enable support for
2898level 2 oplocks.</p>
2899
2900<p>Disabling oplocks with <tt class="literal">oplocks</tt>
2901<tt class="literal">=</tt> <tt class="literal">no</tt> also disables level 2
2902oplocks.</p>
2903
2904<p>Samba can automatically detect its Unix host's
2905support of kernel oplocks and will set the value of
2906<tt class="literal">kernel</tt> <tt class="literal">oplocks</tt> automatically.
2907You should never need to set this option in your Samba configuration
2908file.</p>
2909
2910
2911</div>
2912
2913
2914
2915<div class="sect3"><a name="samba2-CHP-8-SECT-5.3.7"/>
2916
2917<a name="INDEX-141"/><h3 class="head3">fake oplocks</h3>
2918
2919<p>When this option is set to <tt class="literal">yes</tt>, Samba pretends to
2920allow oplocks rather than actually supporting them. If this option is
2921enabled on a read-only share (such as a shared CD-ROM drive), all
2922clients are told that the files are available for opportunistic
2923locking and never warned of simultaneous access. As a result, Windows
2924clients cache more of the file's data and obtain
2925much better performance.</p>
2926
2927<p>This option was added to Samba before opportunistic-locking support
2928was available, and it is now generally considered better to use real
2929oplocks. Do not ever enable <tt class="literal">fake</tt>
2930<tt class="literal">oplocks</tt> on a read/write share.</p>
2931
2932
2933</div>
2934
2935
2936
2937<div class="sect3"><a name="samba2-CHP-8-SECT-5.3.8"/>
2938
2939<h3 class="head3">blocking locks</h3>
2940
2941<p>Samba also supports <em class="firstterm">blocking locks</em>, a minor
2942variant of range locks. Here, if the range of bytes is not available,
2943the client specifies an amount of time that it's
2944willing to wait. The server then caches the lock request,
2945periodically checking to see if the file is available. If it is, it
2946notifies the client; however, if time expires, Samba will tell the
2947client that the request has failed. This strategy prevents the client
2948from continually polling to see if the lock is available.</p>
2949
2950<p>You can disable this option per share as follows:</p>
2951
2952<blockquote><pre class="code">[accounting]
2953 blocking locks = no</pre></blockquote>
2954
2955<p>When set to <tt class="literal">yes</tt>, blocking locks are enforced on
2956the file. If this option is set to <tt class="literal">no</tt>, Samba
2957behaves as if normal locking mechanisms are in place on the file. The
2958default is <tt class="literal">yes</tt>.</p>
2959
2960
2961</div>
2962
2963
2964
2965<div class="sect3"><a name="samba2-CHP-8-SECT-5.3.9"/>
2966
2967<a name="INDEX-142"/><h3 class="head3">veto oplock files</h3>
2968
2969<p>You can provide a list of filenames that are never granted
2970opportunistic locks with the <tt class="literal">veto</tt>
2971<tt class="literal">oplock</tt> <tt class="literal">files</tt> option. This
2972option can be set either globally or on a per-share basis. For
2973example:</p>
2974
2975<blockquote><pre class="code">veto oplock files = /*.bat/*.htm/</pre></blockquote>
2976
2977<p>The value of this option is a series of patterns. Each pattern entry
2978must begin, end, or be separated from another with a slash ( / )
2979character, even if only one pattern is listed. Asterisks can be used
2980as a wildcard to represent zero or more characters. Questions marks
2981can be used to represent exactly one character.</p>
2982
2983<p>We recommend that you disable oplocks on any files that are meant to
2984be updated by Unix or are intended for simultaneous sharing by
2985several processes.</p>
2986
2987
2988</div>
2989
2990
2991
2992<div class="sect3"><a name="samba2-CHP-8-SECT-5.3.10"/>
2993
2994<a name="INDEX-143"/><h3 class="head3">lock directory</h3>
2995
2996<p>This option (sometimes called <tt class="literal">lock</tt>
2997<tt class="literal">dir</tt>) specifies the location of a directory where
2998Samba will store SMB deny-mode lock files. Samba stores other files
2999in this directory as well, such as browse lists and its shared memory
3000file. If WINS is enabled, the WINS database is written to this
3001directory as well. The default for this option is specified in the
3002Samba makefile; it is typically
3003<em class="filename">/usr/local/samba/var/locks</em>. You can override
3004this location as follows:</p>
3005
3006<blockquote><pre class="code">[global]
3007 lock directory = /usr/local/samba/locks</pre></blockquote>
3008
3009<p>You typically would not need to override this option, unless you want
3010to 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>
3012
3013
3014</div>
3015
3016
3017</div>
3018
3019
3020</div>
3021
3022
3023
3024<div class="sect1"><a name="samba2-CHP-8-SECT-6"/>
3025
3026<h2 class="head1">Connection Scripts</h2>
3027
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
3030executed on the server as clients connect to a share or later
3031disconnect from it. By using configuration file variables along with
3032some custom programming, you can create connection scripts that
3033perform a wide range of functions. As a simple example, here is a
3034&quot;quick and dirty&quot; way to monitor
3035connections to shares on the Samba server in real time. First, the
3036value of the <tt class="literal">preexec</tt><a name="INDEX-150"/> parameter is set as
3037follows:</p>
3038
3039<blockquote><pre class="code">[global]
3040 preexec = /bin/echo %u at %m connected to //%L/%S on %T &gt;&gt;/tmp/smblog</pre></blockquote>
3041
3042<p>This causes information about the user and the connection to be
3043written to the file <em class="filename">/tmp/smblog</em> whenever any
3044client connects to any share. To watch clients connect, run the
3045following command:</p>
3046
3047<blockquote><pre class="code">$ <tt class="userinput"><b>tail -f /tmp/smblog</b></tt>
3048jay at maya connected to //toltec/data on 2002/11/21 21:21:15
3049david at apache connected to //toltec/techs on 2002/11/21 21:21:57
3050sally at seminole connected to //toltec/payroll on 2002/11/21 21:22:16
3051martha at dine connected to //toltec/profiles on 2002/11/21 21:23:38
3052martha at dine connected to //toltec/netlogon on 2002/11/21 21:23:39
3053martha at dine connected to //toltec/martha on 2002/11/21 21:23:40
3054aaron at huastec connected to //toltec/netlogon on 2002/11/21 21:24:19
3055aaron at huastec connected to //toltec/aaron on 2002/11/21 21:24:20</pre></blockquote>
3056
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
3060data is appended to the file. Every time a new connection is made, an
3061additional line is printed, showing the output of the
3062<tt class="literal">preexec</tt> command. Notice the lines resulting from
3063connections by user <tt class="literal">martha</tt> and
3064<tt class="literal">aaron</tt>. User <tt class="literal">martha</tt> logged on to
3065the 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
3068then 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
3071drive letter H. The connections from <tt class="literal">aaron</tt> are
3072similar, except that he connected from a Windows 98 system, which
3073does not use the <tt class="literal">[profiles]</tt> share. (See <a href="ch04.html">Chapter 4</a> for more information about domain logons.)</p>
3074
3075<p>A more advanced use of
3076<a name="INDEX-151"/><a name="INDEX-152"/>connection scripts is to monitor the
3077contents of users' home directories and/or other
3078shared directories and perform checks ensuring that local
3079administrative policies are followed. Checked items might include the
3080following:</p>
3081
3082<ul><li>
3083<p>Disk usage, on a per-share, per-directory, or per-file basis</p>
3084</li><li>
3085<p>Types of files stored on the server</p>
3086</li><li>
3087<p>Whether filenames follow naming guidelines</p>
3088</li><li>
3089<p>Whether viruses have copied themselves to the Samba server</p>
3090</li></ul>
3091<p>To handle this kind of task, a shell script or other program would be
3092written to perform the checks and take appropriate actions, such as
3093removing offending files. The <tt class="literal">root</tt>
3094<tt class="literal">preexec</tt> parameter would be used to run the command
3095as the root user, using configuration file variables to pass
3096arguments. For example:</p>
3097
3098<blockquote><pre class="code">[homes]
3099 root preexec = admin_checks %S
3100 root preexec close = yes</pre></blockquote>
3101
3102<p>In this example, a specially written administrative checking program
3103(<em class="emphasis">admin_checks</em>) is used to monitor
3104users' home directories on the Samba server. The
3105<tt class="literal">%S</tt> variable is used to pass the name of the home
3106directory 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>
3110detects a serious violation of local policy, it can exit with a
3111nonzero status, and the client is prevented from connecting.</p>
3112
3113
3114<div class="sect2"><a name="samba2-CHP-8-SECT-6.1"/>
3115
3116<h3 class="head2">Connection Script Options</h3>
3117
3118<p><a href="ch08.html#samba2-CHP-8-TABLE-7">Table 8-7</a> introduces some of the configuration
3119options provided for setting up users.</p>
3120
3121<a name="samba2-CHP-8-TABLE-7"/><h4 class="head4">Table 8-7. Connection script options</h4><table border="1">
3122
3123
3124
3125
3126
3127
3128<tr>
3129<th>
3130<p>Option</p>
3131</th>
3132<th>
3133<p>Parameters</p>
3134</th>
3135<th>
3136<p>Function</p>
3137</th>
3138<th>
3139<p>Default</p>
3140</th>
3141<th>
3142<p>Scope</p>
3143</th>
3144</tr>
3145
3146
3147<tr>
3148<td>
3149<p><tt class="literal">root preexec</tt></p>
3150</td>
3151<td>
3152<p>string (Unix command)</p>
3153</td>
3154<td>
3155<p>Sets a Unix command to run as <tt class="literal">root</tt>, before
3156connecting to the share.</p>
3157</td>
3158<td>
3159<p>None</p>
3160</td>
3161<td>
3162<p>Share</p>
3163</td>
3164</tr>
3165<tr>
3166<td>
3167<p><tt class="literal">root preexec close</tt></p>
3168</td>
3169<td>
3170<p>Boolean</p>
3171</td>
3172<td>
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>
3175</td>
3176<td>
3177<p><tt class="literal">no</tt></p>
3178</td>
3179<td>
3180<p>Share</p>
3181</td>
3182</tr>
3183<tr>
3184<td>
3185<p><tt class="literal">preexec</tt> <tt class="literal">(exec)</tt></p>
3186</td>
3187<td>
3188<p>string (Unix command)</p>
3189</td>
3190<td>
3191<p>Sets a Unix command to run as the user before connecting to the share.</p>
3192</td>
3193<td>
3194<p>None</p>
3195</td>
3196<td>
3197<p>Share</p>
3198</td>
3199</tr>
3200<tr>
3201<td>
3202<p><tt class="literal">preexec close</tt></p>
3203</td>
3204<td>
3205<p>Boolean</p>
3206</td>
3207<td>
3208<p>If set to <tt class="literal">yes</tt>, nonzero exit status of
3209<tt class="literal">preexec</tt> command will disconnect.</p>
3210</td>
3211<td>
3212<p><tt class="literal">no</tt></p>
3213</td>
3214<td>
3215<p>Share</p>
3216</td>
3217</tr>
3218<tr>
3219<td>
3220<p><tt class="literal">postexec</tt></p>
3221</td>
3222<td>
3223<p>string (Unix command)</p>
3224</td>
3225<td>
3226<p>Sets a Unix command to run as the user after disconnecting from the
3227share.</p>
3228</td>
3229<td>
3230<p>None</p>
3231</td>
3232<td>
3233<p>Share</p>
3234</td>
3235</tr>
3236<tr>
3237<td>
3238<p><tt class="literal">root</tt> <tt class="literal">postexec</tt></p>
3239</td>
3240<td>
3241<p>string (Unix command)</p>
3242</td>
3243<td>
3244<p>Sets a Unix command to run as <tt class="literal">root</tt> after
3245disconnecting from the share.</p>
3246</td>
3247<td>
3248<p>None</p>
3249</td>
3250<td>
3251<p>Share</p>
3252</td>
3253</tr>
3254
3255</table>
3256
3257
3258<div class="sect3"><a name="samba2-CHP-8-SECT-6.1.1"/>
3259
3260<a name="INDEX-156"/><h3 class="head3">root preexec</h3>
3261
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
3264share is completed. You should use this option specifically for
3265performing actions that require root privilege.</p>
3266
3267<p>To ensure security, users should never be able to modify the target
3268of the <tt class="literal">root</tt> <tt class="literal">preexec</tt> command. In
3269addition, unless you explicitly redirect it, any information the
3270command sends to standard output will be discarded. If you intend to
3271use any <tt class="literal">preexec</tt> or <tt class="literal">postexec</tt>
3272script, you should ensure that it will run correctly before having
3273Samba invoke it.</p>
3274
3275
3276</div>
3277
3278
3279
3280<div class="sect3"><a name="samba2-CHP-8-SECT-6.1.2"/>
3281
3282<a name="INDEX-157"/><h3 class="head3">root preexec close</h3>
3283
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,
3286giving the client an error rather than allowing it to connect. For
3287example, if you are using <tt class="literal">root</tt>
3288<tt class="literal">preexec</tt> to mount a CD-ROM or filesystem, it would
3289make no sense to connect the client to it in the event that the mount
3290fails. 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
3293connect if the <tt class="literal">root</tt> <tt class="literal">preexec</tt>
3294script returns a nonzero exit status.</p>
3295
3296
3297</div>
3298
3299
3300
3301<div class="sect3"><a name="samba2-CHP-8-SECT-6.1.3"/>
3302
3303<a name="INDEX-158"/><h3 class="head3">preexec</h3>
3304
3305<p>Sometimes just called <tt class="literal">exec</tt>, this option defines an
3306ordinary unprivileged command run by Samba as the user specified by
3307the variable <tt class="literal">%u</tt>. For example, a common use of this
3308option is to perform logging, such as the following:</p>
3309
3310<blockquote><pre class="code">[homes]
3311 preexec = echo &quot;%u connected from %m (%I)\&quot; &gt;&gt;/tmp/.log</pre></blockquote>
3312
3313<p>You must redirect the standard output of the command if you want to
3314use it. Otherwise, it is discarded. This warning also applies to the
3315command's standard error output. If you intend to
3316use a <tt class="literal">preexec</tt> script, you should ensure that it
3317will run correctly before having Samba invoke it.</p>
3318
3319
3320</div>
3321
3322
3323
3324<div class="sect3"><a name="samba2-CHP-8-SECT-6.1.4"/>
3325
3326<a name="INDEX-159"/><h3 class="head3">preexec close</h3>
3327
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
3334share to disconnect immediately.</p>
3335
3336
3337</div>
3338
3339
3340
3341<div class="sect3"><a name="samba2-CHP-8-SECT-6.1.5"/>
3342
3343<a name="INDEX-160"/><h3 class="head3">postexec</h3>
3344
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
3347do any necessary cleanup. This option is essentially the same as the
3348<tt class="literal">preexec</tt> option. Again, remember that the command
3349is run as the user represented by <tt class="literal">%u</tt>, and any
3350information sent to standard output will be ignored.</p>
3351
3352
3353</div>
3354
3355
3356
3357<div class="sect3"><a name="samba2-CHP-8-SECT-6.1.6"/>
3358
3359<a name="INDEX-161"/><h3 class="head3">root postexec</h3>
3360
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,
3363if one has been specified. Again, this option specifies as its value
3364a Unix command to be run <em class="emphasis">as the root user</em> before
3365disconnecting from a share. You should use this option specifically
3366for performing actions that require root privilege. <a name="INDEX-162"/> <a name="INDEX-163"/><a name="INDEX-164"/></p>
3367
3368
3369</div>
3370
3371
3372</div>
3373
3374
3375</div>
3376
3377
3378
3379<div class="sect1"><a name="samba2-CHP-8-SECT-7"/>
3380
3381<h2 class="head1">Microsoft Distributed Filesystems</h2>
3382
3383<p><a name="INDEX-165"/>In a
3384large network where many shared folders are spread out over a large
3385number of servers, it can be difficult for users to locate the
3386resources they are trying to find. Browsing through Network
3387Neighborhood or My Network Places can become an ordeal rather than a
3388time-saving convenience. To mitigate this problem, Microsoft added an
3389extension to file sharing called <em class="firstterm">Distributed
3390filesystem</em><a name="INDEX-166"/><a name="INDEX-167"/> (Dfs). Using Dfs, it
3391is possible to organize file shares on the network so that they
3392appear to users as organized in a single directory tree on a single
3393server, regardless of which servers on the network actually contain
3394the resources. Instead of having to browse the entire network, users
3395can go to the Dfs share and locate their data much more easily.</p>
3396
3397<p>Dfs can also help administrators because it provides a level of
3398indirection between the name of a shared folder and its actual
3399location. The Dfs share contains references to resources on the
3400network, and when a resource is accessed, the Dfs server hands the
3401client off to the actual server of the resource. When moving
3402resources to another computer, the reference to the resource in the
3403Dfs share can be redirected to the new location in one step, with the
3404change being entirely seamless for users.</p>
3405
3406<p>To a limited extent, Dfs also can help improve performance for
3407read-only shares because it provides <a name="INDEX-168"/>load balancing. It is possible
3408to set up a Dfs reference to point to identical shares on two or more
3409servers. The Dfs server then divides requests between the servers,
3410dividing the client load among them. However, this works well only
3411for static, read-only data because no provision is included in Dfs
3412for synchronization among the servers when changes are made on any of
3413them.</p>
3414
3415
3416<div class="sect2"><a name="samba2-CHP-8-SECT-7.1"/>
3417
3418<h3 class="head2">Windows Dfs Clients</h3>
3419
3420<p><a name="INDEX-169"/>Modern versions of Windows come with
3421client-side support for Dfs, and no extra configuration is required.
3422Support is more limited for older versions, however. Windows for
3423Workgroups cannot function as a Dfs client at all. Windows NT 4.0
3424must be upgraded to at least Service Pack 3 to act as a Dfs client,
3425and the Dfs Client must be installed. Later service packs (such as
3426Service Pack 6) include the Dfs Client. Windows 95 must also have the
3427Dfs Client software installed to act as a Dfs client. Without the Dfs
3428Client software, double-clicking a remote folder in a Dfs share will
3429show an empty folder, and no error message will appear.</p>
3430
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
3433download 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>
3434for a link to download the installation program and instructions on
3435how to install the Dfs Client.</p>
3436</blockquote>
3437
3438
3439</div>
3440
3441
3442<div class="sect2"><a name="samba2-CHP-8-SECT-7.2"/>
3443
3444<h3 class="head2">Configuring Samba for Dfs</h3>
3445
3446<p><a name="INDEX-170"/>To act as a Dfs server, Samba 2.2 must
3447be compiled with the <tt class="literal">--with-msdfs</tt> configure
3448option. (See <a href="ch02.html">Chapter 2</a> for instructions on
3449configuring and compiling Samba.) Samba 3.0 includes Dfs support by
3450default and does not need to be compiled with the
3451<tt class="literal">--with-msdfs</tt> configure option.</p>
3452
3453<p>Once a Dfs-enabled Samba server is running, there are just two steps
3454to serving a Dfs share. First we will set up a Dfs root directory on
3455the server, and then we will modify the <em class="filename">smb.conf</em>
3456configuration file to enable the share.</p>
3457
3458
3459<div class="sect3"><a name="samba2-CHP-8-SECT-7.2.1"/>
3460
3461<h3 class="head3">Setting up the Dfs root</h3>
3462
3463<p>First we need to create a directory to act as the Dfs root:</p>
3464
3465<blockquote><pre class="code"># <tt class="userinput"><b>mkdir /usr/local/samba/dfs</b></tt></pre></blockquote>
3466
3467<p>This can be any directory, but it is important that it be owned by
3468root and given the proper permissions:</p>
3469
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>
3472
3473<p>The Dfs directory tree can have subdirectories and files, just like
3474any other shared directory. These will function just as they would in
3475any other share, allowing clients to access the directories and files
3476on the Samba server. The whole idea of Dfs, though, is to gather
3477together shares on other servers by making references to them in the
3478Dfs tree. The way this is implemented with Samba involves a clever
3479use of symbolic links, which can be in the Dfs root directory or any
3480subdirectory in the Dfs tree.</p>
3481
3482<p>You are probably familiar with using symbolic links to create
3483references to files that exist on the same system, and perhaps
3484crossing a local filesystem boundary (which ordinary Unix links
3485cannot do). But maybe you didn't know that symbolic
3486links have a more general functionality. Although we
3487can't display its contents directly, as we could
3488with a text or binary file, a symbolic link
3489&quot;contains&quot; an ASCII text string
3490naming what the link points to. For example, take a look at the
3491listing for these symbolic links:</p>
3492
3493<blockquote><pre class="code">$ <tt class="userinput"><b>ls -l wrdlnk alnk</b></tt>
3494lrwxrwxrwx 1 jay jay 15 Mar 14 06:50 wrdlnk -&gt; /usr/dict/words
3495lrwxrwxrwx 1 jay jay 9 Mar 14 06:53 alnk -&gt; dreamtime</pre></blockquote>
3496
3497<p>As you can infer from the size of the <em class="filename">wrdlnk</em>
3498link (15 bytes), the string <tt class="literal">/usr/dict/words</tt> is
3499encoded into it. The size of <em class="filename">alnk</em> (9 bytes) is
3500smaller, corresponding to the shorter name of
3501<em class="filename">dreamtime</em>.</p>
3502
3503<p>Now let's create a link in our Dfs root for an SMB
3504share:</p>
3505
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>
3509lrwxrwxrwx 1 root root 12 Mar 13 17:34 maya-e -&gt; msdfs:maya\e</pre></blockquote>
3510
3511<p>This link might appear as a
3512&quot;broken&quot; link in a directory
3513listing because it points to something that isn't a
3514file on the local system. For example, the <em class="emphasis">file</em>
3515command will report:</p>
3516
3517<blockquote><pre class="code">$ <tt class="userinput"><b>file maya-e</b></tt>
3518maya-e: broken symbolic link to msdfs:maya\e</pre></blockquote>
3519
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
3522Samba's Dfs support. When Samba encounters this
3523file, it sees the leading <tt class="literal">msdfs</tt>: and interprets
3524the rest as the name of a remote share. The client is then redirected
3525to the remote share.</p>
3526
3527<p>When creating links in the Dfs root directory, simply follow the same
3528format, which in general is
3529<tt class="literal">msdfs</tt>:<em class="replaceable">server</em>\<em class="replaceable">share</em>.
3530Note that this is similar to a UNC appended onto the
3531<tt class="literal">msdfs</tt>: string, except that in this case, the two
3532backslashes preceding the server's name are omitted.</p>
3533
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
3536lowercase.</p>
3537</blockquote>
3538
3539<p>In addition to regular network shares, you can use symbolic links of
3540this type to reference Dfs shares on other Dfs servers. However,
3541referencing printer shares does not work. Dfs is for sharing files
3542only. <a name="INDEX-171"/></p>
3543
3544
3545</div>
3546
3547
3548
3549<div class="sect3"><a name="samba2-CHP-8-SECT-7.2.2"/>
3550
3551<h3 class="head3">Load balancing</h3>
3552
3553<p><a name="INDEX-172"/>To
3554set up a load-balancing Dfs share, create the symbolic link like
3555this:</p>
3556
3557<blockquote><pre class="code"># <tt class="userinput"><b>ln -s 'msdfs:toltec\data,msdfs:mixtec\data' lb-data</b></tt></pre></blockquote>
3558
3559<p>That is, simply use a list of shares separated by commas as the
3560reference. Remember, it is up to you to make sure the shared folders
3561remain identical. Set up permissions on the servers to make the
3562shares read-only to users.</p>
3563
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
3566add Dfs support. The Dfs root is added as a share definition:</p>
3567
3568<a name="INDEX-173"/><blockquote><pre class="code">[dfs]
3569 path = /usr/local/samba/dfs
3570 msdfs root = yes</pre></blockquote>
3571
3572<p>You can use any name you like for the share. The path is set to the
3573Dfs 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>
3576
3577<p>To enable support for Dfs in the server, we need to add one line to
3578the <tt class="literal">[global]</tt> section:</p>
3579
3580<a name="INDEX-174"/><blockquote><pre class="code">[global]
3581 host msdfs = yes</pre></blockquote>
3582
3583<p>Restart the Samba daemons&mdash;or just wait a minute for them to
3584reread the configuration file&mdash;and you will see the new share
3585from Windows clients. If you have trouble accessing any of the remote
3586shares in the Dfs share, recheck your symbolic links to make sure
3587they were created correctly. <a name="INDEX-175"/></p>
3588
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
3591might need to reboot Windows clients before they can access the share
3592as a Dfs share.</p>
3593</blockquote>
3594
3595
3596</div>
3597
3598
3599</div>
3600
3601
3602</div>
3603
3604
3605
3606<div class="sect1"><a name="samba2-CHP-8-SECT-8"/>
3607
3608<h2 class="head1">Working with NIS</h2>
3609
3610<p>In networks where NIS and NFS are in use, it is common for
3611users' home directories to be mounted over the
3612network by NFS. If a Samba server being used to authenticate user
3613logons is running on a system with NFS-mounted home directories
3614shared with a <tt class="literal">[homes]</tt> share, the additional
3615overhead can result in poor performance&mdash;about 30% of normal
3616Samba speed.</p>
3617
3618<p>Samba has the ability to work with <a name="INDEX-176"/>NIS and NIS+ to find the
3619server on which the home directories actually reside so that they can
3620be shared directly from that server. For this to work, the server
3621that holds the home directories must also have Samba running, with a
3622<tt class="literal">[homes]</tt> share of its own.</p>
3623
3624
3625<div class="sect2"><a name="samba2-CHP-8-SECT-8.1"/>
3626
3627<h3 class="head2">NIS Configuration Options</h3>
3628
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
3631for setting up users.</p>
3632
3633<a name="samba2-CHP-8-TABLE-8"/><h4 class="head4">Table 8-8. NIS options</h4><table border="1">
3634
3635
3636
3637
3638
3639
3640<tr>
3641<th>
3642<p>Option</p>
3643</th>
3644<th>
3645<p>Parameters</p>
3646</th>
3647<th>
3648<p>Function</p>
3649</th>
3650<th>
3651<p>Default</p>
3652</th>
3653<th>
3654<p>Scope</p>
3655</th>
3656</tr>
3657
3658
3659<tr>
3660<td>
3661<p><tt class="literal">nis homedir</tt></p>
3662</td>
3663<td>
3664<p>Boolean</p>
3665</td>
3666<td>
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
3669user's home directory.</p>
3670</td>
3671<td>
3672<p><tt class="literal">no</tt></p>
3673</td>
3674<td>
3675<p>Global</p>
3676</td>
3677</tr>
3678<tr>
3679<td>
3680<p><tt class="literal">homedir map</tt></p>
3681</td>
3682<td>
3683<p>string (NIS map name)</p>
3684</td>
3685<td>
3686<p>Sets the NIS map to use to look up a user's home
3687directory.</p>
3688</td>
3689<td>
3690<p>None</p>
3691</td>
3692<td>
3693<p>Global</p>
3694</td>
3695</tr>
3696
3697</table>
3698
3699
3700<div class="sect3"><a name="samba2-CHP-8-SECT-8.1.1"/>
3701
3702<h3 class="head3">nis homedir, homedir map</h3>
3703
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
3706are for Samba servers on network sites where Unix home directories
3707are provided using NFS, the automounter, and NIS.</p>
3708
3709<p>The <tt class="literal">nis</tt> <tt class="literal">homedir</tt> option
3710indicates that the home-directory server for the user needs to be
3711looked up in NIS. The <tt class="literal">homedir</tt>
3712<tt class="literal">map</tt> option tells Samba in which NIS map to look
3713for the server that has the user's home directory.
3714The server needs to be a Samba server so that the client can do an
3715SMB connect to it, and the other Samba servers need to have NIS
3716installed so that they can do the lookup.</p>
3717
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>,
3721Samba 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
3724associated system name to the client. The client will then try to
3725connect to that machine and get the share from there. Enabling NIS
3726lookups looks like the following:</p>
3727
3728<blockquote><pre class="code">[globals]
3729 nis homedir = yes
3730 homedir map = amd.map</pre></blockquote>
3731
3732
3733</div>
3734
3735
3736</div>
3737
3738
3739</div>
3740
3741<hr/><h4 class="head4">Footnotes</h4><blockquote><a name="FOOTNOTE-1"/> <p><a href="#FNPTR-1">[1]</a> The system checkbox will
3742probably be grayed for your file. Don't worry about
3743that&mdash;you should still be able to see when the box is checked
3744and when it isn't.</p> </blockquote><hr/><h4 class="head4"><a href="toc.html">TOC</a></h4></body></html>
Note: See TracBrowser for help on using the repository browser.