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—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"ghosted," 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—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 "Access 135Denied" message. The <tt class="literal">dont</tt> 136<tt class="literal">descend</tt> option is an administrative 137option—not a security option—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 "This is a test" >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 "This is a test" 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—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—such as 647<em class="emphasis">hello.java</em>—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 "protected 801against accidental change, including deletion," 802rather than "protected against some other user on a 803single-user machine." 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—which were first written for Unix—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"the world."</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—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"user, group, other" 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 "user, group, 1397other" 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 "perhaps" 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ü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"Full Control". 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"out of the box" 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:\> <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—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—which allow only one process to write to an entire 2407file on a server at a given time—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—typically 30%—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—without an additional 2522coordination between the two systems—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—especially 2886executables—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"quick and dirty" 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 >>/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 "%u connected from %m (%I)\" >>/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"contains" 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 -> /usr/dict/words 3495lrwxrwxrwx 1 jay jay 9 Mar 14 06:53 alnk -> 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 -> msdfs:maya\e</pre></blockquote> 3510 3511<p>This link might appear as a 3512"broken" 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—or just wait a minute for them to 3584reread the configuration file—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—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—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> 3745
