vcs.maemo.org Git - samba/blob - docs/htmldocs/using_samba/ch08.html

   1 <html>
   2 <body bgcolor="#ffffff">
   3
   4 <img src="samba2_xs.gif" border="0" alt=" " height="100" width="76"
   5 hspace="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
  11 regarding the integration of Unix and Windows filesystems, including
  12 hidden files, Unix links, file permissions, name mangling, case
  13 sensitivity of filenames, file locking, opportunistic locking
  14 (oplocks), connection scripts, supporting Microsoft Dfs (Distributed
  15 filesystem) shares, and using NIS home directories.</p>
  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
  23 difference between Unix and Microsoft filesystems. This includes
  24 items such as handling symbolic links, hidden files, and dot files.
  25 In addition, file permissions can also be a headache if not properly
  26 accounted 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
  34 cannot see or access a file at all. Other times, you
  35 don't want to keep users from accessing a
  36 file&mdash;you just want to hide it when they view the contents of
  37 the directory. On Windows systems, an attribute of files allows them
  38 to be hidden from a folder listing. With Unix, the traditional way of
  39 hiding files in a directory is to use a <a name="INDEX-3"/><a name="INDEX-4"/>dot (.) as the first character in the
  40 filename. This prevents items such as configuration files from being
  41 seen when performing an ordinary <em class="emphasis">ls</em> command.
  42 Keeping a user from accessing a file at all, however, involves
  43 working with permissions on files and directories.</p>
  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>,
  48 Samba reports files beginning with a period (.) as having their
  49 hidden attribute set. If the user has chosen to show all hidden files
  50 while browsing (e.g., using the Folder Options menu item under the
  51 View menu in Windows 98), he will still be able to see the files,
  52 although his icons will appear
  53 &quot;ghosted,&quot; or slightly grayed-out.
  54 If the client is configured not to show hidden files, the files will
  55 not appear at all.</p>
  56
  57 <p>Instead of simply hiding files beginning with a dot, you can also
  58 specify a string pattern to Samba for files to hide, using the
  59 <tt class="literal">hide</tt><a name="INDEX-7"/> <tt class="literal">files</tt>
  60 option. For example, let's assume you specified the
  61 following in our example <tt class="literal">[data]</tt> share:</p>
  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
  67 another with a slash ( / ) character, even if only one pattern is
  68 listed. This convention allows spaces to appear in filenames. The
  69 slashes have nothing to do with Unix directories; they are instead
  70 acting as delimiters for the <tt class="literal">hide</tt>
  71 <tt class="literal">files</tt> values.</p>
  72
  73 <p>If you want to prevent users from seeing files completely, you can
  74 instead use the <tt class="literal">veto</tt><a name="INDEX-8"/> <tt class="literal">files</tt>
  75 option. This option, which takes the same syntax as the
  76 <tt class="literal">hide</tt> <tt class="literal">files</tt> option, specifies a
  77 list of files that should never be seen by the user. For example,
  78 let's change the <tt class="literal">[data]</tt> share to
  79 the 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,
  86 end, or be separated from another with a slash (<tt class="literal">/</tt>)
  87 character, even if only one pattern is listed. If you do so, files
  88 that match the pattern, such as <em class="filename">hello.java</em> and
  89 <em class="filename">README.txt,</em> will simply disappear from the
  90 directory, and the user cannot access them through SMB.</p>
  91
  92 <p><a name="INDEX-9"/>We need to address
  93 one other question. What happens if the user tries to delete a
  94 directory that contains vetoed files? This is where the
  95 <tt class="literal">delete</tt><a name="INDEX-10"/> <tt class="literal">veto</tt>
  96 <tt class="literal">files</tt> option comes in. If this Boolean option is
  97 set to <tt class="literal">yes</tt>, the user can delete both the regular
  98 files and the vetoed files in the directory, and the directory itself
  99 is removed. If the option is set to <tt class="literal">no</tt>, the user
 100 cannot delete the vetoed files, and consequently the directory is not
 101 deleted either. From the user's perspective, the
 102 directory appears empty, but cannot be removed.</p>
 103
 104 <p>The <tt class="literal">dont</tt><a name="INDEX-11"/> <tt class="literal">descend</tt>
 105 directive specifies a list of directories whose contents Samba should
 106 not make visible. Note that we say <em class="emphasis">contents</em>, not
 107 the directory itself. Users can enter a directory marked as such, but
 108 they are prohibited from descending the directory tree any
 109 farther&mdash;they always see an empty folder. For example,
 110 let's use this option with a more basic form of the
 111 share that we defined earlier in the chapter:</p>
 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
 118 contents:</p>
 119
 120 <blockquote><pre class="code">drwxr-xr-x   6 tom      users     1024 Jun 13 09:24 .
 121 drwxr-xr-x   8 root     root      1024 Jun 10 17:53 ..
 122 -rw-r--r--   2 tom      users     1024 Jun  9 11:43 README
 123 drwxr-xr-x   3 tom      users     1024 Jun 13 09:28 config
 124 drwxr-xr-x   3 tom      users     1024 Jun 13 09:28 defaults
 125 drwxr-xr-x   3 tom      users     1024 Jun 13 09:28 market</pre></blockquote>
 126
 127 <p>If the user then connects to the share, she would see the directories
 128 in the share. However, the contents of the
 129 <em class="filename">/config</em> and <em class="filename">/defaults</em>
 130 directories would appear empty to her, even if other folders or files
 131 existed in them. In addition, users cannot write any data to the
 132 folder (which prevents them from creating a file or folder with the
 133 same name as one that is already there but invisible). If a user
 134 attempts to do so, she will receive an &quot;Access
 135 Denied&quot; message. The <tt class="literal">dont</tt>
 136 <tt class="literal">descend</tt> option is an administrative
 137 option&mdash;not a security option&mdash;and is not a substitute for
 138 good 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
 149 tries to open a symbolic link on a Samba server share, Samba attempts
 150 to follow the link to find the real file and let the client open it,
 151 as if the user were on a Unix machine. If you don't
 152 want to allow this, set the <tt class="literal">follow</tt>
 153 <tt class="literal">symlinks</tt> option like this:</p>
 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.
 159 Create a directory on the Unix server inside the share, acting as the
 160 user under which you will log in to Samba. Enter the following
 161 commands:</p>
 162
 163 <blockquote><pre class="code">$ <tt class="userinput"><b>echo &quot;This is a test&quot; &gt;hello.txt</b></tt>
 164 $ <tt class="userinput"><b>ln -s hello.txt hello-link.txt</b></tt></pre></blockquote>
 165
 166 <p>This results in the text file <em class="filename">hello.txt</em> and a
 167 symbolic link to it called <em class="filename">hello-link.txt</em>.
 168 Normally, if you double-click either one, you will receive a file
 169 that has the text &quot;This is a test&quot;
 170 inside of it. However, with the <tt class="literal">follow</tt>
 171 <tt class="literal">symlinks</tt><a name="INDEX-15"/> option set to
 172 <tt class="literal">no</tt>, you will receive an error dialog if you
 173 double-click <em class="filename">hello-link.txt</em>.</p>
 174
 175 <p>The <tt class="literal">wide</tt><a name="INDEX-16"/> <tt class="literal">links</tt>
 176 option, if set to <tt class="literal">no</tt>, prevents the client user
 177 from following symbolic links that point outside the shared directory
 178 tree. For example, let's assume that we modified the
 179 <tt class="literal">[data]</tt> share as follows:</p>
 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
 187 follow any symbolic links outside the current share tree. If we
 188 create a file outside the share (for example, in
 189 someone's home directory) and then create a link to
 190 it in the share as follows:</p>
 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
 195 directory.</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
 206 discussed earlier. We recommend the defaults for most, except those
 207 listed 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
 244 invisible 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
 297 the 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
 315 files 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
 368 deleted.</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>
 386 option can be used to specify various directories that should appear
 387 empty to the client. Note that the directory itself will still
 388 appear. However, Samba will not show any of the contents of the
 389 directory to the client user. This is not a good option to use as a
 390 security feature; it is really meant only as a convenience to keep
 391 users from casually browsing into directories that might have
 392 sensitive files. See our example earlier in this section.</p>
 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
 404 Unix operating system to the target or if it should return an error
 405 to the client user. If the option is set to <tt class="literal">yes</tt>,
 406 the target of the link will be interpreted as the file. If set to
 407 <tt class="literal">no</tt>, an error will be generated if the symbolic
 408 link is accessed.</p>
 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
 420 for the Unix <em class="emphasis">getwd( )</em> ( get current working
 421 directory) system call. You can override the default value of
 422 <tt class="literal">yes</tt> as follows:</p>
 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
 428 increase the time it takes to resolve the working directory,
 429 especially if the <tt class="literal">wide</tt> <tt class="literal">links</tt>
 430 option is set to <tt class="literal">no</tt>. You should normally not need
 431 to alter this option.</p>
 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
 443 links that point outside the shared directory tree. This includes any
 444 files or directories at the other end of the link, as long as the
 445 permissions are correct for the user. The default value for this
 446 option is <tt class="literal">yes</tt>. Note that this option will not be
 447 honored if the <tt class="literal">follow</tt> <tt class="literal">symlinks</tt>
 448 options is set to <tt class="literal">no</tt>. Setting this option to
 449 <tt class="literal">no</tt> slows <em class="emphasis">smbd</em> considerably
 450 because it will have to check each link it encounters.</p>
 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
 463 begin with a dot (.) character to mimic the functionality behind
 464 several shell commands that are present on Unix systems. Like
 465 <tt class="literal">hide</tt> <tt class="literal">files</tt>, those files that
 466 begin with a dot have the DOS hidden attribute set, which
 467 doesn't guarantee that a client cannot view them.
 468 The default value for this option is <tt class="literal">yes</tt>.</p>
 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
 480 provides one or more directory or filename patterns to Samba. Any
 481 file matching this pattern will be treated as a hidden file from the
 482 perspective of the client. Note that this simply means that the DOS
 483 hidden attribute is set, which might or might not mean that the user
 484 can actually see it while browsing.</p>
 485
 486 <p>Each entry in the list must begin, end, or be separated from another
 487 entry with a slash (<tt class="literal">/</tt>) character, even if only one
 488 pattern is listed. This allows spaces to appear in the list.
 489 Asterisks can be used as a wildcard to represent zero or more
 490 characters. Questions marks can be used to represent exactly one
 491 character. For example:</p>
 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
 505 the <tt class="literal">veto</tt> <tt class="literal">files</tt> configuration
 506 option. Samba won't even admit these files exist.
 507 You cannot list or open them from the client. This should not be used
 508 as a means of implementing security. It is actually a mechanism to
 509 keep PC programs from deleting special files, such as ones used to
 510 store the resource fork of a Macintosh file on a Unix filesystem. If
 511 both Windows and Macs are sharing the same files, this can prevent
 512 ill-advised power users from removing files the Mac users need.</p>
 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
 516 option: each entry must begin, end, or be separated from another with
 517 a slash ( / ) character, even if only one pattern is listed.
 518 Asterisks can be used as a wildcard to represent zero or more
 519 characters. Question marks can be used to represent exactly one
 520 character. For example:</p>
 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
 525 good 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
 537 to delete the directory in which they reside. The default value is
 538 <tt class="literal">no</tt>. This means that if a user tries to delete a
 539 directory that contains a vetoed file, the file (and the directory)
 540 will not be deleted. Instead, the directory remains and appears empty
 541 from the perspective of the user. If set to <tt class="literal">yes</tt>,
 542 the directory and the vetoed files will be deleted. <a name="INDEX-29"/><a name="INDEX-30"/></p>
 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
 560 multiuser, networked operating system. Unix, on the other hand, was
 561 designed for multiple users from the start. Consequently, Samba must
 562 not only be aware of, but also provide special solutions for,
 563 inconsistencies and gaps in coverage between the two filesystems. One
 564 of the biggest gaps is how Unix and DOS handle permissions on files.</p>
 565
 566 <p>Let's take a look at how Unix assigns permissions.
 567 All Unix files have read, write, and execute bits for three
 568 classifications of users: owner, group, and world. These permissions
 569 can be seen at the extreme lefthand side when an <em class="emphasis">ls
 570 -al</em> command is issued in a Unix directory. For example:</p>
 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
 575 any file: read-only, system, hidden, and archive. You can view these
 576 bits by right-clicking the file and choosing the Properties menu
 577 item. You should see a dialog similar to <a href="ch08.html#samba2-CHP-8-FIG-1">Figure 8-1</a>.<a name="FNPTR-1"/><a href="#FOOTNOTE-1">[1]</a></p>
 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
 587 be 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
 602 operating 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
 610 it.</p>
 611 </dd>
 612
 613 </dl>
 614
 615 <p>Note that there is no bit to specify that a file is executable. DOS
 616 and Windows NT filesystems identify executable files by giving them
 617 the extensions <em class="filename">.exe</em>, <em class="filename">.com</em>,
 618 <em class="filename">.cmd</em>, or <em class="filename">.bat</em>.</p>
 619
 620 <p>Consequently, there is no use for any of the three Unix executable
 621 bits that are present on a file in a Samba disk share. DOS files,
 622 however, have their own attributes that need to be preserved when
 623 they are stored in a Unix environment: the archive, system, and
 624 hidden bits. Samba can preserve these bits by reusing the executable
 625 permission bits of the file on the Unix side&mdash;if it is
 626 instructed to do so. Mapping these bits, however, has an unfortunate
 627 side effect: if a Windows user stores a file in a Samba share, and
 628 you view it on Unix with the <em class="emphasis">ls -al</em> command,
 629 some of the executable bits won't mean what
 630 you'd expect them to.</p>
 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
 636 map the archive, system, and hidden attributes to the owner, group,
 637 and world execute bits of the file, respectively. You can add these
 638 options to the <tt class="literal">[data]</tt> share, setting each of their
 639 values as follows:</p>
 640
 641 <blockquote><pre class="code">[data]
 642     map archive = yes
 643     map system = yes
 644     map hidden = yes</pre></blockquote>
 645
 646 <p>After that, try creating a file in the share under Unix&mdash;such as
 647 <em class="emphasis">hello.java</em>&mdash;and change the permissions of
 648 the file to 755. With these Samba options set, you should be able to
 649 check the permissions on the Windows side and see that each of the
 650 three values has been checked in the Properties dialog box. What
 651 about the read-only attribute? By default, Samba sets this whenever a
 652 file does not have the Unix owner write permission bit set. In other
 653 words, you can set this bit by changing the permissions of the file
 654 to 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
 658 the other two options have a default value of <tt class="literal">no</tt>.
 659 This is because many programs do not work properly if the archive bit
 660 is not stored correctly for DOS and Windows files. The system and
 661 hidden attributes, however, are not critical for a
 662 program's operation and are left to the discretion
 663 of the administrator.</p>
 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
 666 illustrates how Samba maps those bits to DOS attributes. Note that
 667 the group read/write and world read/write bits do not directly
 668 translate to a DOS attribute, but they still retain their original
 669 Unix definitions on the Samba server.</p>
 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
 679 similar to <a name="INDEX-40"/>umasks you
 680 have probably encountered while working with Unix systems. They are
 681 used to help define the permissions that will be assigned to a file
 682 or directory at the time it is created. Samba's
 683 masks work differently in that the bits that can be set are set in
 684 the creation mask, while in Unix umasks, the bits
 685 <em class="emphasis">cannot</em> be set are set in the umask. We think you
 686 will find Samba's method to be much more intuitive.
 687 Once in a while you might need to convert between a Unix umask and
 688 the equivalent Samba mask. It is simple: one is just the bitwise
 689 complement of the other. For example, an octal umask of 0022 has the
 690 same effect as a Samba mask of 0755.</p>
 691
 692 <p>Unix umasks are set on a user-by-user basis, usually while executing
 693 the GUI's or command-line shell's
 694 startup scripts. When users connect to a Samba share from a network
 695 client, these scripts are not executed, so Samba supplies the ability
 696 to set the creation masks for files and directories. By default, this
 697 is done on a share-by-share basis, although you can use the
 698 <tt class="literal">include</tt> parameter in the Samba configuration file
 699 (as explained in <a href="ch06.html">Chapter 6</a>) to assign masks on a
 700 user-by-user basis, thus matching conventional Unix behavior.</p>
 701
 702 <p>To show how Samba's create masks work, suppose we
 703 have a Windows Me user connecting to his Unix home directory through
 704 Samba, and Samba is configured with <tt class="literal">create</tt>
 705 <tt class="literal">mask</tt> <tt class="literal">=</tt> <tt class="literal">777</tt>
 706 in the <tt class="literal">[homes]</tt> share. With this value,
 707 <tt class="literal">create</tt> <tt class="literal">mask</tt> will not affect the
 708 bits that are set on new files. If the user creates a file with
 709 Wordpad, it will appear in the Unix filesystem like this:</p>
 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
 715 MS-DOS read-only attribute was not set), so Samba mapped the MS-DOS
 716 attributes to Unix read/write permissions for user, group, and other.
 717 The <a name="INDEX-41"/><a name="INDEX-42"/>execute bit is set for the owner
 718 because by default, the <tt class="literal">map</tt>
 719 <tt class="literal">archive</tt> parameter is set to
 720 <tt class="literal">yes</tt>. The other execute bits are not set because
 721 <tt class="literal">map</tt> <tt class="literal">system</tt> and
 722 <tt class="literal">map</tt> <tt class="literal">hidden</tt> are set to
 723 <tt class="literal">no</tt> by default. You can customize this behavior as
 724 you see fit, and unless you do backups from MS-DOS or Windows
 725 systems, you might want to specify <tt class="literal">map</tt>
 726 <tt class="literal">archive</tt> <tt class="literal">=</tt> <tt class="literal">no</tt>
 727 to avoid Windows files from appearing as executables on the Unix
 728 system.</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
 732 an 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
 738 Wordpad 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
 744 write permission for other disappeared as we expected, but so has the
 745 execute permission for owner. This happened because the value of
 746 <tt class="literal">create</tt> <tt class="literal">mask</tt> logically ANDs the
 747 owner's permissions with a 6, which has masked off
 748 the execute bit. The lesson here is that if you want to enable any of
 749 <tt class="literal">map</tt> <tt class="literal">archive</tt>,
 750 <tt class="literal">map</tt> <tt class="literal">system</tt>, or
 751 <tt class="literal">map</tt> <tt class="literal">hidden</tt>, you must be careful
 752 not to mask off the corresponding execute bit with your
 753 <tt class="literal">create</tt> <tt class="literal">mask</tt>.</p>
 754
 755 <p>The <tt class="literal">directory</tt><a name="INDEX-44"/> <tt class="literal">mask</tt>
 756 option works similarly, masking permissions for newly created
 757 directories. The following example will allow the permissions of a
 758 newly created directory to be, at most, 755:</p>
 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
 767 OR against the file and directory creation masks, ensuring that those
 768 bits that are specified will always be set. You would typically set
 769 these options globally to ensure that group and world read/write
 770 permissions have been set appropriately for new files or directories
 771 in each share.</p>
 772
 773 <p>In the same spirit, if you wish to set explicitly the Unix user and
 774 group attributes of a file created on the Windows side, you can use
 775 the <tt class="literal">force</tt><a name="INDEX-45"/> <tt class="literal">user</tt> and
 776 <tt class="literal">force</tt><a name="INDEX-46"/> <tt class="literal">group</tt>
 777 options. For example:</p>
 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
 786 that connects to the share. However, this occurs
 787 <em class="emphasis">after</em> the client authenticates; it does not
 788 allow free access to a share. These options are frequently used for
 789 their side effects of assigning a specific user and group to each new
 790 file or directory that is created in a share. Use these options with
 791 discretion.</p>
 792
 793 <p>Finally, one of the capabilities of Unix that DOS lacks is the
 794 ability to delete a read-only file from a writable directory. In
 795 Unix, if a directory is writable, a read-only file in that directory
 796 can still be removed. This could permit you to delete files in any of
 797 your directories, even if the file was left by someone else.</p>
 798
 799 <p>DOS filesystems are not designed for multiple users, and so its
 800 designers decided that read-only means &quot;protected
 801 against accidental change, including deletion,&quot;
 802 rather than &quot;protected against some other user on a
 803 single-user machine.&quot; So the designers of DOS
 804 prohibited removal of a read-only file. Even today, Windows
 805 filesystems exhibit the same behavior.</p>
 806
 807 <p>Normally, this is harmless. Windows programs don't
 808 try to remove read-only files because they know it's
 809 a bad idea. However, a number of source-code control
 810 programs&mdash;which were first written for Unix&mdash;run on Windows
 811 and require the ability to delete read-only files. Samba permits this
 812 behavior with the <tt class="literal">delete</tt><a name="INDEX-47"/>
 813 <tt class="literal">readonly</tt> option. To enable this functionality, set
 814 the option to <tt class="literal">yes</tt>:</p>
 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
 828 options for file and directory permissions are summarized in <a href="ch08.html#samba2-CHP-8-TABLE-2">Table 8-2</a>; each option is then described in detail.</p>
 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
 899 directories 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
 917 directories 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
1037 are 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
1055 permission flags can be set at file creation by a client in a share.
1056 The default is 0744, which means that the Unix owner can at most
1057 read, write, and optionally execute her own files, while members of
1058 the user's group and others can only read or execute
1059 them. If you need to change it for nonexecutable files, we recommend
1060 0644, or <tt class="literal">rw-r--r--</tt>. Keep in mind that the execute
1061 bits can be used by the server to map certain DOS file attributes, as
1062 described earlier. If you're altering the create
1063 mask, those bits have to be part of the create mask as well.</p>
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
1075 permission flags can be set at directory creation by a client in a
1076 share. The default is 0744, which allows everyone on the Unix side
1077 to, at most, read and traverse the directories, but allows only you
1078 to modify them. We recommend the mask 0750, removing access by
1079 &quot;the world.&quot;</p>
1080
1081
1082 </div>
1083
1084
1085
1086 <div class="sect3"><a name="samba2-CHP-8-SECT-2.2.3"/>
1087
1088 <a name="INDEX-54"/><h3 class="head3">force create mode</h3>
1089
1090 <p>This option sets the permission bits that Samba will set when a file
1091 permission change is made. It's often used to force
1092 group permissions, as mentioned previously. It can also be used to
1093 preset any of the DOS attributes we mentioned: archive (0100), system
1094 (0010), or hidden (0001).</p>
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
1098 documents, many Windows applications rename their datafiles with a
1099 <em class="filename">.bak</em> extension and create new ones. When the
1100 files are in a Samba share, this changes their ownership and
1101 permissions so that members of the same Unix group
1102 can't edit them. Setting <tt class="literal">force</tt>
1103 <tt class="literal">create mode = 0660</tt> will keep the new file editable
1104 by members of the group.</p>
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
1117 directory permission change is made or a directory is created.
1118 It's often used to force group permissions, as
1119 mentioned previously. This option defaults to 0000 and can be used
1120 just like the <tt class="literal">force</tt> <tt class="literal">create</tt>
1121 <tt class="literal">mode</tt> to add group or other permissions if needed.</p>
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
1133 static group ID that will be used on all connections to a share after
1134 the client has successfully authenticated. This assigns a specific
1135 group to each new file or directory created from an SMB client.</p>
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
1147 assigns a static user ID that will be used on all connections to a
1148 share after the client has successfully authenticated. This assigns a
1149 specific user to each new file or directory created from an SMB
1150 client.</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
1162 read-only file. By default, DOS and Windows will not allow such an
1163 operation. You probably will want to leave this option turned off
1164 unless a program (for example, an RCS program) needs this capability;
1165 many Windows users would be appalled to find that
1166 they'd accidentally deleted a file that they had set
1167 as 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
1179 since it was last archived (e.g., backed up with the DOS archive
1180 program). Setting the Samba option <tt class="literal">map</tt>
1181 <tt class="literal">archive</tt> <tt class="literal">=</tt>
1182 <tt class="literal">yes</tt> maps the DOS archive flag to the Unix
1183 execute-by-owner (0100) bit. It's best to leave this
1184 option on if your Windows users are doing their own backups or are
1185 using programs that require the archive bit. Unix lacks the notion of
1186 an archive bit entirely. Backup programs typically keep a file that
1187 lists what files were backed up on what date, so comparing
1188 file-modification dates serves the same purpose.</p>
1189
1190 <p>Setting this option to <tt class="literal">yes</tt> causes an occasional
1191 surprise on Unix when a user notices that a datafile is marked as
1192 executable, but rarely causes harm. If a user tries to run it, he
1193 will normally get a string of error messages as the shell tries to
1194 execute the first few lines as commands. The reverse is also
1195 possible; an executable Unix program looks like it
1196 hasn't been backed up recently on Windows. But
1197 again, this is rare and usually harmless.</p>
1198
1199 <p>For map archive to work properly, the execute bit for owner must not
1200 be masked off with the <tt class="literal">create</tt>
1201 <tt class="literal">mask</tt> parameter.</p>
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
1213 operating system and should not be deleted, renamed, or moved without
1214 special effort. Set this option only if you need to store Windows
1215 system files on the Unix fileserver. Executable Unix programs will
1216 appear to be nonremovable, special Windows files when viewed from
1217 Windows clients. This might prove mildly inconvenient if you want to
1218 move or remove one. For most sites, however, this is fairly harmless.</p>
1219
1220 <p>For map archive to work properly, the execute bit for group must not
1221 be masked off with the <tt class="literal">create</tt>
1222 <tt class="literal">mask</tt> parameter.</p>
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
1234 ordinarily be visible in directory listings. Unix
1235 doesn't have such a facility; it's
1236 up to individual programs (notably, the shell) to decide what to
1237 display and what not to display. Normally, you won't
1238 have any DOS files that need to be hidden, so the best thing to do is
1239 to leave this option turned off.</p>
1240
1241 <p>Setting this option to <tt class="literal">yes</tt> causes the server to
1242 map the hidden flag onto the executable-by-others bit (0001). This
1243 feature can produce a rather startling effect. Any Unix program that
1244 is executable by world seems to vanish when you look for it from a
1245 Windows client. If this option is not set, however, and a Windows
1246 user attempts to mark a file hidden on a Samba share, it will not
1247 work&mdash;Samba has no place to store the hidden attribute!</p>
1248
1249 <p>For map archive to work properly, the execute bit for other must not
1250 be 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
1270 the permissions on newly created files is overridden such that the
1271 new files and directories take on permissions from their parent
1272 directory. New directories will have exactly the same permissions as
1273 the parent, and new files will inherit the read and write bits from
1274 the parent directory, while the execute bits are determined as usual
1275 by the values of the <tt class="literal">map</tt>
1276 <tt class="literal">archive</tt>, <tt class="literal">map</tt>
1277 <tt class="literal">hidden</tt>, and <tt class="literal">map</tt>
1278 <tt class="literal">system</tt> parameters.</p>
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
1298 have different <a name="INDEX-74"/>security models, and Windows NT/2000/XP
1299 has a security model that is different from Windows 95/98/Me. One
1300 area in which this is readily apparent is file protections. On Unix
1301 systems, the method used has traditionally been the 9-bit
1302 &quot;user, group, other&quot; system, in
1303 which read, write, and execute bits can be set separately for the
1304 owner of the file, the groups to which the owner belongs, and
1305 everyone else, respectively.</p>
1306
1307 <p><a name="INDEX-75"/>Windows 95/98/Me has a file-protection
1308 system that is essentially no protection at all. This family of
1309 operating systems was developed from MS-DOS, which was implemented as
1310 a non-networked, single-user system. Multiuser security simply was
1311 never added. One apparent exception to this is user-level security
1312 for shared files, which we will discuss in <a href="ch09.html">Chapter 9</a>. Here, separate access permissions can be
1313 assigned to individual network client users or groups. However,
1314 user-level security on Windows 95/98/Me systems requires a Windows
1315 NT/2000 or Samba server to perform the actual authentication.</p>
1316
1317 <p>On <a name="INDEX-76"/><a name="INDEX-77"/><a name="INDEX-78"/>Windows NT/2000/XP,
1318 user-level security is an extension of the native file security
1319 model, which involves access control lists (ACLs). This system is
1320 somewhat more extensive than the Unix security model, allowing the
1321 access rights on individual files to be set separately for any number
1322 of individual users and/or any number of arbitrary groups of users.
1323 <a href="ch08.html#samba2-CHP-8-FIG-3">Figure 8-3</a>, <a href="ch08.html#samba2-CHP-8-FIG-4">Figure 8-4</a>,
1324 and <a href="ch08.html#samba2-CHP-8-FIG-5">Figure 8-5</a> show the dialog boxes on a Windows
1325 2000 system in which the ACL is set for a file. By right-clicking a
1326 file's icon and selecting Properties, then selecting
1327 the Security tab, we get to the dialog box shown in <a href="ch08.html#samba2-CHP-8-FIG-3">Figure 8-3</a>. Here, we can set the basic permissions for a
1328 file, which are similar to Unix permissions, although not identical.</p>
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.
1335 In this dialog, ACEs can be added to or deleted from the ACL, or an
1336 existing ACE can be viewed and modified. Each ACE either allows or
1337 denies a set of permissions for a specific user or group.</p>
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.
1344 As you can see, there are more options for permissions in an ACL than
1345 with the permission bits on typical Unix systems. You can learn more
1346 about these settings in <em class="citetitle">Essential Windows NT System
1347 Administration</em>, published by O'Reilly.</p>
1348
1349 <p>In a networked environment where a Samba server is serving files to
1350 Windows NT/2000/XP clients, Samba has to map Unix permissions for
1351 files and directories to Windows NT/2000/XP access control lists.
1352 When a Windows NT/2000/XP client accesses a shared file or directory
1353 on a Samba server, Samba translates the object's
1354 ownership, group, and permissions into an ACL and returns them to the
1355 client.</p>
1356
1357 <p><a href="ch08.html#samba2-CHP-8-FIG-6">Figure 8-6</a> shows the Properties dialog box for the
1358 file <em class="filename">shopping_list.doc</em> that resides on the Samba
1359 server.</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
1369 Read-only checkbox will show as cleared, even though the user on the
1370 Windows client (who is not <tt class="literal">adilia</tt> in this example)
1371 does not have read access permissions. The checkboxes here show only
1372 DOS attributes. By clicking the Security tab, we can start to examine
1373 the ACLs, as shown in <a href="ch08.html#samba2-CHP-8-FIG-7">Figure 8-7</a>.</p>
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
1378 entry, while the group (<tt class="literal">users</tt>) and other
1379 permissions are presented as the groups called
1380 <tt class="literal">users</tt> and <tt class="literal">Everyone</tt>. Clicking
1381 one of the items in the upper windows causes the simplified view of
1382 the permissions in that item to appear in the bottom window. Here,
1383 the read/write permissions for <tt class="literal">adilia</tt> appear in a
1384 manner that makes the security model of Unix and Windows seem
1385 similar. However, clicking the Advanced . . . button brings up the
1386 additional dialog box shown in <a href="ch08.html#samba2-CHP-8-FIG-8">Figure 8-8</a>.</p>
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
1392 with Take Ownership in the Permission column. This is a trick used by
1393 Samba for ACLs that have no permissions on the Unix side. On Windows,
1394 an ACL with nothing set results in no ACL at all, so Samba sets the
1395 Take Ownership permission to make sure that all the ACLs
1396 corresponding to the Unix &quot;user, group,
1397 other&quot; permissions will show up on Windows. The Take
1398 Ownership permission has no corresponding Unix attribute, so the
1399 setting on Windows does not affect the actual file on the Unix system
1400 in any way. Although Windows client users might be misled into
1401 thinking they can take ownership of the file (that is, change the
1402 ownership of the file to themselves), an actual attempt to do so will
1403 fail.</p>
1404
1405 <p>The Permissions column for the <tt class="literal">adilia</tt> ACL is
1406 listed as Special because Samba reports permissions for the file that
1407 do not correspond to settings for which Windows has a more
1408 descriptive name. Clicking the entry and then clicking the View/Edit
1409 . . . button brings up the dialog box shown in <a href="ch08.html#samba2-CHP-8-FIG-9">Figure 8-9</a>, in which the details of the ACL permissions
1410 can be viewed and perhaps modified.</p>
1411
1412 <div class="figure"><a name="samba2-CHP-8-FIG-9"/><img src="figs/sam2_0809.gif"/></div><h4 class="head4">Figure 8-9. Permission Entry dialog for a file served by Samba</h4>
1413
1414 <p>We say &quot;perhaps&quot; here because
1415 checking or unchecking boxes in this dialog box might not result in
1416 settings that Samba is able to map back into the Unix security model.
1417 When a user attempts to modify a setting (either permissions or
1418 ownership) that she does not have authority to change, or does not
1419 correspond to a valid setting on the Unix system, Samba will respond
1420 with an error dialog or by quietly ignoring the unmappable settings.</p>
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
1423 button.</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
1429 the directory itself, and the other specifies permissions for the
1430 directory's contents. When changing settings in the
1431 View/Edit... dialog, there is an extra drop-down menu to apply the
1432 settings either to just the directory or to some combination of the
1433 directory and the files and directories it contains. If settings are
1434 applied to more than just the directory, Samba will match the
1435 behavior of a Windows server and change the permissions on the
1436 contents of the directory, as specified in the dialog.</p>
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
1444 most cases, users of Windows clients will find the Unix security
1445 model to be sufficient. However, in some cases, people might want the
1446 Samba server to support the full Windows ACL security model. Even if
1447 they don't need the fine-grained control over file
1448 and directory permissions, they might find Samba's
1449 translation between ACLs and Unix permissions to be a source of
1450 confusion or frustration.</p>
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
1454 support of Windows NT/2000/XP ACLs. Versions of Unix that offer the
1455 necessary support include the following:</p>
1456
1457 <ul><li>
1458 <p>Solaris 2.6 and later</p>
1459 </li><li>
1460 <p>SGI Irix</p>
1461 </li><li>
1462 <p>Linux, with Andreas Gr&uuml;nbacher's kernel
1463 patch from <a href="http://acl.bestbits.at">http://acl.bestbits.at</a>
1464 that adds ACL support to the Linux ext2 and ext3 filesystems</p>
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
1475 ACL support already provided, all you need to do is recompile Samba
1476 using the <tt class="literal">--with-acl-support</tt> configure option, as
1477 we described in <a href="ch02.html">Chapter 2</a>. If you are running
1478 Linux and need to patch your kernel, things are much more
1479 complicated. We suggest you refer to the documentation that comes
1480 with the patch for details on using it.</p>
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
1491 for 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
1528 to 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
1614 on Windows NT/2000/XP clients to modify ACL settings for files on the
1615 Samba server. When set to <tt class="literal">no</tt>, files show up as
1616 owned by <tt class="literal">Everyone</tt>, with permissions appearing as
1617 &quot;Full Control&quot;. However,
1618 <em class="emphasis">actual</em> ownership and permissions are enforced as
1619 whatever they are set to on the Samba server, and the user on the
1620 Windows client cannot view or modify them with the dialog boxes used
1621 for managing ACLs.</p>
1622
1623 <p>When enabled, support for Windows NT/2000/XP ACLs is limited to
1624 whatever ownerships and permissions can map into valid users and
1625 permissions on the Samba server. If the server supports ACLs (either
1626 &quot;out of the box&quot; or with an
1627 additional patch to enhance the filesystem), Samba's
1628 ACL support more closely matches that of a Windows NT/2000/XP server.</p>
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
1641 permissions users can modify from Windows NT/2000/XP clients. This is
1642 for files only and not directories, which are handled with the
1643 <tt class="literal">directory</tt><a name="INDEX-88"/>
1644 <tt class="literal">security</tt> <tt class="literal">mask</tt> option. The
1645 parameter is assigned a numeric value that is a Unix-style
1646 permissions mask. For bits in the mask that are set, the client can
1647 modify the corresponding bits in the files'
1648 permissions. If the bit is zero, the client cannot modify that
1649 permission. For example, if <tt class="literal">security</tt>
1650 <tt class="literal">mask</tt> is set as:</p>
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
1656 files in the share. This is the default. A value of
1657 <tt class="literal">0</tt> would deny clients from changing any of the
1658 permissions, and setting <tt class="literal">security</tt>
1659 <tt class="literal">mask</tt> as:</p>
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,
1665 but not the execute permissions.</p>
1666
1667 <p>Do not count on <tt class="literal">security</tt> <tt class="literal">mask</tt>
1668 for complete control because if the user can access the files on the
1669 Samba server through any other means (for example, by logging
1670 directly into the Unix host), he can modify the permissions using
1671 that 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
1684 used to define a set of permissions that are always set whenever the
1685 user on a Windows NT/2000/XP client modifies a
1686 file's permissions. (See the
1687 <tt class="literal">force</tt> <tt class="literal">directory</tt>
1688 <tt class="literal">security</tt> <tt class="literal">mode</tt> option for
1689 handling directories.)</p>
1690
1691 <p>Be careful to understand this properly. The mask given as the
1692 parameter's value is not necessarily equal to the
1693 resulting permissions on the file. The permissions that the client
1694 user attempts to modify are logically OR'd with the
1695 <tt class="literal">force</tt> <tt class="literal">security</tt>
1696 <tt class="literal">mode</tt> <tt class="literal">mask</tt> option, and any bits
1697 that are turned on will cause the file's
1698 corresponding permissions to be set. As an example, suppose
1699 <tt class="literal">force</tt> <tt class="literal">security</tt>
1700 <tt class="literal">mode</tt> is set in a share thusly:</p>
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
1706 user on a Windows NT/2000/XP client modifies an ACL on a file in the
1707 <tt class="literal">[data]</tt> share and attempts to remove all read
1708 permissions, the read permission for other
1709 (<tt class="literal">Everyone</tt>) will be removed, but the read
1710 permission for the owner and group will remain. Note that this
1711 parameter cannot force a permission bit to be turned off.</p>
1712
1713 <p>As with the <tt class="literal">security</tt> <tt class="literal">mask</tt>
1714 option, if a user can access the files in the share through any means
1715 other than Samba, she can easily work around Samba's
1716 enforcement of this parameter.</p>
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
1721 from 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
1734 directories rather than files. As with <tt class="literal">security</tt>
1735 <tt class="literal">mask</tt>, it has a default value of
1736 <tt class="literal">0777</tt>, which allows Windows NT/2000/XP client users
1737 to modify all Unix permissions on directories in the share.</p>
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
1750 that it operates on directories rather than files. It also has a
1751 default value of <tt class="literal">0000</tt>, which allows Windows
1752 NT/2000/XP client users to remove any permissions from directories in
1753 the share. <a name="INDEX-92"/><a name="INDEX-93"/><a name="INDEX-94"/><a name="INDEX-95"/> <a name="INDEX-96"/><a name="INDEX-97"/></p>
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
1771 in the days of DOS and Windows 3.1, every filename was limited to
1772 eight uppercase characters, followed by a dot, and three more
1773 uppercase characters. This was known as the <em class="firstterm">8.3
1774 format</em> and was a huge nuisance. Windows 95/98/Me, Windows
1775 NT/2000/XP, and Unix have since relaxed this problem by allowing
1776 longer, sometimes case-sensitive, filenames. <a href="ch08.html#samba2-CHP-8-TABLE-4">Table 8-4</a> shows the current naming state of several
1777 popular operating systems.</p>
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
1799 extension (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
1808 extension (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
1839 that store files in just the 8.3 format, such as Windows for
1840 Workgroups. If a user creates a file on a share called
1841 <em class="emphasis">antidisestablishmentarianism.txt</em>, a Windows for
1842 Workgroups client cannot tell it apart from another file in the same
1843 directory called <em class="emphasis">antidisease.txt</em>. Like Windows
1844 95/98/Me and Windows NT/2000/XP, Samba has to employ a special method
1845 for translating a long filename to an 8.3 filename in such a way that
1846 similar filenames will not cause collisions. This is called
1847 <em class="firstterm">name mangling</em>, and Samba deals with this in a
1848 manner that is similar, but not identical to, Windows 95 and its
1849 successors.</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
1857 filename 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
1861 characters before the dot (if there is one) are converted to
1862 uppercase. These characters are used as the first five characters of
1863 the 8.3 mangled filename.</p>
1864 </li><li>
1865 <p>If the original filename begins with a dot, the dot is removed and
1866 then the previous step is performed on what is left.</p>
1867 </li><li>
1868 <p>These characters are immediately followed by a special mangling
1869 character: by default, a tilde (~), although Samba allows you to
1870 change this character.</p>
1871 </li><li>
1872 <p>The base of the long filename before the last period is hashed into a
1873 two-character code; parts of the name after the last dot can be used
1874 if necessary. This two-character code is appended to the filename
1875 after the mangling character.</p>
1876 </li><li>
1877 <p>The first three characters after the last dot (if there is one) of
1878 the original filename are converted to uppercase and appended onto
1879 the mangled name as the extension. If the original filename began
1880 with a dot, three underscores ( <tt class="literal">_ _ _</tt> ) are used
1881 as the extension instead.</p>
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._ _ _
1887 hello.java                           HELLO~1F.JAV
1888 team.config.txt                      TEAMC~04.TXT
1889 antidisestablishmentarianism.txt     ANTID~E3.TXT
1890 antidisease.txt                      ANTID~9K.TXT</pre></blockquote>
1891
1892 <p>Using these rules will allow Windows for Workgroups to differentiate
1893 the two files on behalf of the poor individual who is forced to see
1894 the network through the eyes of that operating system. Note that the
1895 same long filename should always hash to the same mangled name with
1896 Samba; this doesn't always happen with Windows. The
1897 downside of this approach is that there can still be collisions;
1898 however, the chances are greatly reduced.</p>
1899
1900 <p>You generally want to use the mangling configuration options with
1901 only the oldest clients. We recommend doing this without disrupting
1902 other clients by adding an <tt class="literal">include</tt> directive to
1903 the <em class="filename">smb.conf</em> file:</p>
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
1909 for Workgroups client attaches. Now you can create a file
1910 <em class="filename">/usr/local/samba/lib/smb.conf.WfWg</em>, which might
1911 contain these options:</p>
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
1922 to 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
1930 point out is that there is a difference between how an operating
1931 system <em class="emphasis">represents</em> a file and how it
1932 <em class="emphasis">resolves</em> it. For example, you have likely run
1933 across a file on a Windows system called
1934 <em class="filename">README.TXT</em>. The file can be represented by the
1935 operating system entirely in uppercase letters. However, if you open
1936 an MS-DOS command prompt and enter the command:</p>
1937
1938 <blockquote><pre class="code">C:\&gt; <tt class="userinput"><b>notepad readme.txt</b></tt></pre></blockquote>
1939
1940 <p>the all-caps file is loaded into the editing program, even though you
1941 typed the name in lowercase letters.</p>
1942
1943 <p>This is because the Windows 95/98/Me and Windows NT/2000/XP families
1944 of operating systems resolve filenames in a case-insensitive manner,
1945 even though the files are represented in a case-sensitive manner.
1946 Unix-based operating systems, on the other hand, always resolve files
1947 in a case-sensitive manner; if you try to edit
1948 <em class="filename">README.TXT</em> with the command:</p>
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
1956 to <tt class="literal">yes</tt>, Samba will always use the case provided by
1957 the operating system for representing (not resolving) filenames. If
1958 it is set to <tt class="literal">no</tt>, it will use the case specified by
1959 the <tt class="literal">default</tt><a name="INDEX-106"/> <tt class="literal">case</tt> option.
1960 The same is true for
1961 <tt class="literal">short</tt><a name="INDEX-107"/>
1962 <tt class="literal">preserve</tt> <tt class="literal">case</tt>. If this option
1963 is set to <tt class="literal">yes</tt>, Samba will use the default case of
1964 the operating system for representing 8.3 filenames; otherwise, it
1965 will use the case specified by the <tt class="literal">default</tt>
1966 <tt class="literal">case</tt> option. Finally, Samba will always resolve
1967 filenames in its shares based on the value of the
1968 <tt class="literal">case</tt> <tt class="literal">sensitive</tt> option.</p>
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
1982 allows more refined instructions on how it should perform name
1983 mangling, including those controlling the case sensitivity, the
1984 character inserted to form a mangled name, and the ability to map
1985 filenames manually from one format to another. These options are
1986 shown in <a href="ch08.html#samba2-CHP-8-TABLE-5">Table 8-5</a>.</p>
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.,
2061 do 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
2080 client 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
2184 preserve case when resolving filenames in a specific share. The
2185 default value for this option is <tt class="literal">no</tt>, which is how
2186 Windows handles file resolution. If clients are using an operating
2187 system that takes advantage of case-sensitive filenames, you can set
2188 this configuration option to <tt class="literal">yes</tt> as shown here:</p>
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
2205 is used with <tt class="literal">preserve</tt> <tt class="literal">case</tt>.
2206 This specifies the default case (upper or lower) Samba uses to create
2207 a file on one of its shares on behalf of a client. The default case
2208 is <tt class="literal">lower</tt>, which means that newly created files
2209 will have lowercase names. If you need to, you can override this
2210 global option by specifying the following:</p>
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
2216 translated into uppercase and cannot be overridden in a program. We
2217 recommend that you use the default value unless you are dealing with
2218 a Windows for Workgroups or other 8.3 client, in which case it should
2219 be <tt class="literal">upper</tt>.</p>
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
2231 the client is created with the case provided by the client operating
2232 system or the case specified by the earlier
2233 <tt class="literal">default</tt> <tt class="literal">case</tt> configuration
2234 option. The default value is <tt class="literal">yes</tt>, which uses the
2235 case provided by the client operating system. If it is set to
2236 <tt class="literal">no</tt>, the value of the <tt class="literal">default</tt>
2237 <tt class="literal">case</tt> option (upper or lower) is used.</p>
2238
2239 <p>Note that this option does not handle 8.3 file requests sent from the
2240 client&mdash;see the upcoming <tt class="literal">short</tt>
2241 <tt class="literal">preserve</tt> <tt class="literal">case</tt> option. You might
2242 want to set this option to <tt class="literal">yes</tt>, for example, if
2243 applications that create files on the Samba server demand the file be
2244 all uppercase. If instead you want Samba to mimic the behavior of a
2245 Windows NT filesystem, you can leave this option set to its default,
2246 <tt class="literal">yes</tt>.</p>
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
2258 behalf of the client is created with the default case of the client
2259 operating system or the case specified by the
2260 <tt class="literal">default</tt> <tt class="literal">case</tt> configuration
2261 option. The default value is <tt class="literal">yes</tt>, which uses the
2262 case provided by the client operating system. You can let Samba
2263 choose the case through the <tt class="literal">default</tt>
2264 <tt class="literal">case</tt> option by setting it as follows:</p>
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
2270 filesystem, 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
2283 for 8.3 clients. If the option is set to <tt class="literal">no</tt>, Samba
2284 will not mangle the names, and (depending on the client) they will
2285 either be invisible or appear truncated to those using 8.3 operating
2286 systems. The default value is <tt class="literal">yes</tt>. You can
2287 override it per share as follows:</p>
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
2302 not composed entirely of the case specified using the
2303 <tt class="literal">default</tt> <tt class="literal">case</tt> configuration
2304 option. The default for this option is <tt class="literal">no</tt>. If you
2305 set it to <tt class="literal">yes</tt>, you should be sure that all clients
2306 can handle the mangled filenames that result. You can override it per
2307 share as follows:</p>
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
2313 well-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
2325 Samba mangles filenames into the 8.3 format. The default character
2326 used is a tilde (~). You can reset it to whatever character you wish.
2327 For 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
2342 stack can be used to reverse-map mangled filenames back to their
2343 original state. This is often needed by applications that create and
2344 save a file, close it, and need to modify it later. The default
2345 number of long filename/mangled filename pairs stored on this stack
2346 is 50. However, if you want to cut down on the amount of processor
2347 time used to mangle filenames, you can increase the size of the stack
2348 to whatever you wish, at the expense of memory and slightly slower
2349 file 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
2364 give Samba further instructions on how to behave using the
2365 <tt class="literal">mangled</tt> <tt class="literal">map</tt> option. This option
2366 allows you to specify mapping patterns that can be used in place of
2367 name mangling performed by Samba. For example:</p>
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
2373 characters that match the first pattern specified in the parenthesis
2374 and convert them to the modified second pattern in the parenthesis
2375 for display on an 8.3 client. This is useful in the event that name
2376 mangling converts the filename incorrectly or converts it to a format
2377 that the client cannot understand readily. Patterns are separated by
2378 whitespaces. <a name="INDEX-119"/><a name="INDEX-120"/> <a name="INDEX-121"/><a name="INDEX-122"/></p>
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
2396 writes to a single file are not desirable in any operating system. To
2397 prevent this, most operating systems use <em class="firstterm">locks</em>
2398 to guarantee that only one process can write to a file at a time.
2399 Operating systems traditionally lock entire files, although newer
2400 ones allow a range of bytes within a file to be locked. If another
2401 process attempts to write to a file (or section of one) that is
2402 already locked, it receives an error from the operating system and
2403 will have to wait until the lock is released.</p>
2404
2405 <p>Samba supports the standard DOS and NT filesystem (deny-mode) locking
2406 requests&mdash;which allow only one process to write to an entire
2407 file on a server at a given time&mdash;as well as byte-range locking.
2408 In addition, Samba supports a locking mechanism known in the Windows
2409 NT world as <em class="firstterm">opportunistic locking,
2410 </em><a name="INDEX-127"/>or<em class="firstterm">
2411 </em><em class="emphasis">oplock</em> for short.</p>
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
2419 it will not only be the exclusive writer of a file, but will also
2420 cache its changes to that file locally to speed up access by reducing
2421 network activity. This can result in a large performance
2422 gain&mdash;typically 30%&mdash;while at the same time reserving
2423 network bandwidth for other purposes.</p>
2424
2425 <p>Because exclusive access can be obtained using regular file locks,
2426 the value of opportunistic locks is not so much to lock the file as
2427 it is to cache it. In fact, a better name for opportunistic locking
2428 might be <em class="firstterm">opportunistic caching</em>.</p>
2429
2430 <p>When Samba knows that a file in one of its shares has been oplocked
2431 by a client, it marks its version as having an opportunistic lock and
2432 waits for the client to complete work on the file, at which point it
2433 expects the client to send its changes back to the Samba server for
2434 synchronization with the copy on the server.</p>
2435
2436 <p>If a second client requests access to that file before the first
2437 client has finished working on it, Samba sends an oplock break
2438 request to the first client. This tells the client to stop caching
2439 its changes and return the current state of the file to the server so
2440 that the interrupting client can use it as it sees fit. An
2441 opportunistic lock, however, is not a replacement for a standard
2442 deny-mode lock. It is not unheard of for the interrupting process to
2443 be granted an oplock break only to discover that the original process
2444 also has a deny-mode lock on a file as well. <a href="ch08.html#samba2-CHP-8-FIG-11">Figure 8-11</a> illustrates this <a name="INDEX-128"/>opportunistic locking process.</p>
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
2449 oplocks is highly desirable. However, allowing the client to cache
2450 data can be a big risk if either the client or network hardware are
2451 unreliable. Suppose a client opens a file for writing, creating an
2452 oplock on it. When another client also tries to open the file, an
2453 oplock break request is sent to the first client. If this request
2454 goes unfulfilled for any reason and the second client starts writing
2455 to the file, the file can be easily corrupted as a result of the two
2456 processes writing to it concurrently. Unfortunately, this scenario is
2457 very real. Uncoordinated behavior such as this has been observed many
2458 times among Windows clients in SMB networks (with files served by
2459 Windows NT/2000 or Samba). Typically, the affected files are database
2460 files, which multiple clients open concurrently for writing.</p>
2461
2462 <p>A more concrete example of <a name="INDEX-129"/>oplock failure occurs when database
2463 files are very large. If a client is allowed to oplock this kind of
2464 file, there can be a huge delay while the client copies the entire
2465 file from the server to cache it, even though it might need to update
2466 only one record. The situation goes from bad to worse when another
2467 client tries to open the oplocked file. The first client might need
2468 to write the entire file back to the server before the second
2469 client's file open request can succeed. This results
2470 in another huge delay (for both clients), which in practice often
2471 results in a failed open due to a timeout on the second client,
2472 perhaps along with a message warning of possible database corruption!</p>
2473
2474 <p>If you are having problems of this variety, you can turn off oplocks
2475 for the affected files by using the
2476 <tt class="literal">veto</tt><a name="INDEX-130"/> <tt class="literal">oplock</tt>
2477 <tt class="literal">files</tt> parameter:</p>
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
2483 separated by slash characters) to match all the files in the share
2484 that might be a source of trouble. The syntax of this parameter is
2485 similar to that of the <tt class="literal">veto</tt>
2486 <tt class="literal">files</tt> parameter.</p>
2487
2488 <p>If you want to be really careful and can live with reduced
2489 performance, you can turn off oplocks altogether, preventing the
2490 oplock break problem from ever occurring:</p>
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
2496 server. If you wish to disable oplocks in just a specific share, you
2497 can specify the <tt class="literal">oplocks</tt> <tt class="literal">=</tt>
2498 <tt class="literal">no</tt> parameter in just that share:</p>
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
2504 data, to attain better performance, while trading performance for
2505 better data integrity for files in the <tt class="literal">[database]</tt>
2506 share.</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
2517 client systems cooperate to avoid overwriting each
2518 other's changes. Unix systems also have file-locking
2519 mechanisms to allow Unix processes to cooperate with each other. But
2520 if a file stored on a Samba system is accessed by both a Windows
2521 network client and a local Unix process&mdash;without an additional
2522 coordination between the two systems&mdash;the Unix process could
2523 easily ride roughshod over an oplock.</p>
2524
2525 <p>Some Unix systems have enhanced kernels that understand the Windows
2526 oplocks maintained by Samba. Currently the support exists only in SGI
2527 Irix and Linux.</p>
2528
2529 <p>If you leave oplocks enabled and your Unix system does not support
2530 kernel oplocks, you could end up with corrupted data when somebody
2531 runs a Unix process that reads or writes a file that Windows users
2532 also access. This is another case where the
2533 <tt class="literal">veto</tt><a name="INDEX-132"/> <tt class="literal">oplock</tt>
2534 <tt class="literal">files</tt> parameter can be used, assuming you can
2535 anticipate which Samba files are used by both Windows users and Unix
2536 users. For example, suppose the <tt class="literal">[usrfiles]</tt> share
2537 contains some ASCII text files with the <em class="filename">.txt</em>
2538 filename extension and OpenOffice word processor documents with the
2539 <em class="filename">.doc</em> filename extension, which Unix and Windows
2540 users both modify. We can use <tt class="literal">veto</tt>
2541 <tt class="literal">oplock</tt> <tt class="literal">files</tt> like this:</p>
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>
2547 and <em class="filename">.doc</em> files, which will suppress client
2548 caching, while allowing the Windows and Unix programs to use regular
2549 file locking to prevent concurrent writes to the same file.</p>
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
2560 locks 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
2614 byte-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
2632 system.</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
2650 client 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
2702 doesn'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
2754 stored.</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
2772 Samba to engage or disengage server-side byte-range locks on behalf
2773 of the client. Samba implements byte-range locks on the server side
2774 with normal Unix advisory locks and consequently prevents other
2775 properly behaved Unix processes from overwriting a locked byte range.</p>
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
2784 either type of lock releases it (or crashes). If, however, the option
2785 is set to <tt class="literal">no</tt>, no byte-range locks are kept for the
2786 files, although requests to lock and unlock files will appear to
2787 succeed. The option is set to <tt class="literal">yes</tt> by default;
2788 however, you can turn this option off if you have read-only media.</p>
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
2800 range of bytes being accessed. This is typically not needed if a
2801 client adheres to all the locking mechanisms in place. This option is
2802 set to <tt class="literal">no</tt> by default; however, you can reset it
2803 per share as follows:</p>
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
2809 enforced 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
2821 oplocks to POSIX locks. This behavior can be disabled by setting
2822 <tt class="literal">posix</tt> <tt class="literal">locking</tt>
2823 <tt class="literal">=</tt> <tt class="literal">no</tt>. You should never need to
2824 change the default behavior, which is <tt class="literal">posix</tt>
2825 <tt class="literal">locking</tt> <tt class="literal">=</tt>
2826 <tt class="literal">yes</tt>.</p>
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.
2838 The option is enabled by default. However, you can disable it with
2839 the 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
2845 clients that cannot take advantage of opportunistic locking, it might
2846 be better to shut this Samba feature off. If the host operating
2847 system does not support kernel oplocks, oplocks should be disabled if
2848 users are accessing the same files from both Unix applications (such
2849 as <em class="emphasis">vi</em>) and SMB clients.</p>
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
2861 the Samba suite) tries to open a file for writing that Samba has
2862 oplocked to a Windows client, it is likely to succeed (depending on
2863 the operating system), and both Samba and the client are never aware
2864 of it.</p>
2865
2866 <p>Some versions of Unix have support for oplocks in the kernel that can
2867 work along with Samba's oplocks. In this case, the
2868 Unix process trying to open the file is suspended while Samba directs
2869 the client to write its copy back. After that has happened, the
2870 operating system allows the open to complete. At the time of this
2871 writing, this feature is supported only by SGI Irix and Linux.</p>
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
2883 read-only oplocks when another client opens the same file. This can
2884 result in significant improvements in performance on files that are
2885 written infrequently or not at all&mdash;especially
2886 executables&mdash;because all clients can then maintain a read-ahead
2887 cache for the file. By default, <tt class="literal">level2</tt>
2888 <tt class="literal">oplocks</tt> is set to <tt class="literal">yes</tt>, and you
2889 probably won't need to change it.</p>
2890
2891 <p>Currently, Samba cannot support level 2 oplocks along with kernel
2892 oplocks and automatically disables level 2 oplocks when kernel
2893 oplocks are in use. (This might change in future releases as improved
2894 support for oplocks is added by the Samba developers.) If you are
2895 running Samba on a host system that supports kernel oplocks, you must
2896 set <tt class="literal">kernel</tt> <tt class="literal">oplocks</tt>
2897 <tt class="literal">=</tt> <tt class="literal">no</tt> to enable support for
2898 level 2 oplocks.</p>
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
2902 oplocks.</p>
2903
2904 <p>Samba can automatically detect its Unix host's
2905 support of kernel oplocks and will set the value of
2906 <tt class="literal">kernel</tt> <tt class="literal">oplocks</tt> automatically.
2907 You should never need to set this option in your Samba configuration
2908 file.</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
2920 allow oplocks rather than actually supporting them. If this option is
2921 enabled on a read-only share (such as a shared CD-ROM drive), all
2922 clients are told that the files are available for opportunistic
2923 locking and never warned of simultaneous access. As a result, Windows
2924 clients cache more of the file's data and obtain
2925 much better performance.</p>
2926
2927 <p>This option was added to Samba before opportunistic-locking support
2928 was available, and it is now generally considered better to use real
2929 oplocks. Do not ever enable <tt class="literal">fake</tt>
2930 <tt class="literal">oplocks</tt> on a read/write share.</p>
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
2942 variant of range locks. Here, if the range of bytes is not available,
2943 the client specifies an amount of time that it's
2944 willing to wait. The server then caches the lock request,
2945 periodically checking to see if the file is available. If it is, it
2946 notifies the client; however, if time expires, Samba will tell the
2947 client that the request has failed. This strategy prevents the client
2948 from continually polling to see if the lock is available.</p>
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
2956 the file. If this option is set to <tt class="literal">no</tt>, Samba
2957 behaves as if normal locking mechanisms are in place on the file. The
2958 default is <tt class="literal">yes</tt>.</p>
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
2970 opportunistic locks with the <tt class="literal">veto</tt>
2971 <tt class="literal">oplock</tt> <tt class="literal">files</tt> option. This
2972 option can be set either globally or on a per-share basis. For
2973 example:</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
2978 must begin, end, or be separated from another with a slash ( / )
2979 character, even if only one pattern is listed. Asterisks can be used
2980 as a wildcard to represent zero or more characters. Questions marks
2981 can be used to represent exactly one character.</p>
2982
2983 <p>We recommend that you disable oplocks on any files that are meant to
2984 be updated by Unix or are intended for simultaneous sharing by
2985 several processes.</p>
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
2998 Samba will store SMB deny-mode lock files. Samba stores other files
2999 in this directory as well, such as browse lists and its shared memory
3000 file. If WINS is enabled, the WINS database is written to this
3001 directory as well. The default for this option is specified in the
3002 Samba makefile; it is typically
3003 <em class="filename">/usr/local/samba/var/locks</em>. You can override
3004 this location as follows:</p>
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
3010 to move the lock files to a more standard location, such as
3011 <em class="filename">/var/spool/locks</em>. <a name="INDEX-144"/> <a name="INDEX-145"/><a name="INDEX-146"/></p>
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
3030 executed on the server as clients connect to a share or later
3031 disconnect from it. By using configuration file variables along with
3032 some custom programming, you can create connection scripts that
3033 perform a wide range of functions. As a simple example, here is a
3034 &quot;quick and dirty&quot; way to monitor
3035 connections to shares on the Samba server in real time. First, the
3036 value of the <tt class="literal">preexec</tt><a name="INDEX-150"/> parameter is set as
3037 follows:</p>
3038
3039 <blockquote><pre class="code">[global]
3040     preexec = /bin/echo %u at %m connected to //%L/%S on %T &gt;&gt;/tmp/smblog</pre></blockquote>
3041
3042 <p>This causes information about the user and the connection to be
3043 written to the file <em class="filename">/tmp/smblog</em> whenever any
3044 client connects to any share. To watch clients connect, run the
3045 following command:</p>
3046
3047 <blockquote><pre class="code">$ <tt class="userinput"><b>tail -f /tmp/smblog</b></tt>
3048 jay at maya connected to //toltec/data on 2002/11/21 21:21:15
3049 david at apache connected to //toltec/techs on 2002/11/21 21:21:57
3050 sally at seminole connected to //toltec/payroll on 2002/11/21 21:22:16
3051 martha at dine connected to //toltec/profiles on 2002/11/21 21:23:38
3052 martha at dine connected to //toltec/netlogon on 2002/11/21 21:23:39
3053 martha at dine connected to //toltec/martha on 2002/11/21 21:23:40
3054 aaron at huastec connected to //toltec/netlogon on 2002/11/21 21:24:19
3055 aaron at huastec connected to //toltec/aaron on 2002/11/21 21:24:20</pre></blockquote>
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
3060 data is appended to the file. Every time a new connection is made, an
3061 additional line is printed, showing the output of the
3062 <tt class="literal">preexec</tt> command. Notice the lines resulting from
3063 connections by user <tt class="literal">martha</tt> and
3064 <tt class="literal">aaron</tt>. User <tt class="literal">martha</tt> logged on to
3065 the domain from a Windows NT client, which accessed the
3066 <tt class="literal">[profiles]</tt> share to download her profile, then the
3067 <tt class="literal">[netlogon]</tt> share to read the logon script, and
3068 then her home directory (because her logon script contains a
3069 <tt class="literal">net</tt> <tt class="literal">use</tt> <tt class="literal">H</tt>:
3070 <tt class="literal">/home</tt> command) to connect her home directory to
3071 drive letter H. The connections from <tt class="literal">aaron</tt> are
3072 similar, except that he connected from a Windows 98 system, which
3073 does not use the <tt class="literal">[profiles]</tt> share. (See <a href="ch04.html">Chapter 4</a> for more information about domain logons.)</p>
3074
3075 <p>A more advanced use of
3076 <a name="INDEX-151"/><a name="INDEX-152"/>connection scripts is to monitor the
3077 contents of users' home directories and/or other
3078 shared directories and perform checks ensuring that local
3079 administrative policies are followed. Checked items might include the
3080 following:</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
3092 written to perform the checks and take appropriate actions, such as
3093 removing offending files. The <tt class="literal">root</tt>
3094 <tt class="literal">preexec</tt> parameter would be used to run the command
3095 as the root user, using configuration file variables to pass
3096 arguments. For example:</p>
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
3104 users' home directories on the Samba server. The
3105 <tt class="literal">%S</tt> variable is used to pass the name of the home
3106 directory to the script. The
3107 <tt class="literal">root</tt><a name="INDEX-153"/> <tt class="literal">preexec</tt>
3108 <tt class="literal">close</tt> parameter has been set to
3109 <tt class="literal">yes</tt> so that if <em class="emphasis">admin_checks</em>
3110 detects a serious violation of local policy, it can exit with a
3111 nonzero status, and the client is prevented from connecting.</p>
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
3119 options 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
3156 connecting 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
3227 share.</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
3245 disconnecting 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
3264 share is completed. You should use this option specifically for
3265 performing actions that require root privilege.</p>
3266
3267 <p>To ensure security, users should never be able to modify the target
3268 of the <tt class="literal">root</tt> <tt class="literal">preexec</tt> command. In
3269 addition, unless you explicitly redirect it, any information the
3270 command sends to standard output will be discarded. If you intend to
3271 use any <tt class="literal">preexec</tt> or <tt class="literal">postexec</tt>
3272 script, you should ensure that it will run correctly before having
3273 Samba invoke it.</p>
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,
3286 giving the client an error rather than allowing it to connect. For
3287 example, if you are using <tt class="literal">root</tt>
3288 <tt class="literal">preexec</tt> to mount a CD-ROM or filesystem, it would
3289 make no sense to connect the client to it in the event that the mount
3290 fails. If you specify <tt class="literal">root</tt>
3291 <tt class="literal">preexec</tt> <tt class="literal">close</tt>
3292 <tt class="literal">=</tt> <tt class="literal">yes</tt>, the share will fail to
3293 connect if the <tt class="literal">root</tt> <tt class="literal">preexec</tt>
3294 script returns a nonzero exit status.</p>
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
3306 ordinary unprivileged command run by Samba as the user specified by
3307 the variable <tt class="literal">%u</tt>. For example, a common use of this
3308 option is to perform logging, such as the following:</p>
3309
3310 <blockquote><pre class="code">[homes]
3311     preexec = echo &quot;%u connected from %m (%I)\&quot; &gt;&gt;/tmp/.log</pre></blockquote>
3312
3313 <p>You must redirect the standard output of the command if you want to
3314 use it. Otherwise, it is discarded. This warning also applies to the
3315 command's standard error output. If you intend to
3316 use a <tt class="literal">preexec</tt> script, you should ensure that it
3317 will run correctly before having Samba invoke it.</p>
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
3334 share 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
3347 do any necessary cleanup. This option is essentially the same as the
3348 <tt class="literal">preexec</tt> option. Again, remember that the command
3349 is run as the user represented by <tt class="literal">%u</tt>, and any
3350 information sent to standard output will be ignored.</p>
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,
3363 if one has been specified. Again, this option specifies as its value
3364 a Unix command to be run <em class="emphasis">as the root user</em> before
3365 disconnecting from a share. You should use this option specifically
3366 for performing actions that require root privilege. <a name="INDEX-162"/> <a name="INDEX-163"/><a name="INDEX-164"/></p>
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
3384 large network where many shared folders are spread out over a large
3385 number of servers, it can be difficult for users to locate the
3386 resources they are trying to find. Browsing through Network
3387 Neighborhood or My Network Places can become an ordeal rather than a
3388 time-saving convenience. To mitigate this problem, Microsoft added an
3389 extension to file sharing called <em class="firstterm">Distributed
3390 filesystem</em><a name="INDEX-166"/><a name="INDEX-167"/> (Dfs). Using Dfs, it
3391 is possible to organize file shares on the network so that they
3392 appear to users as organized in a single directory tree on a single
3393 server, regardless of which servers on the network actually contain
3394 the resources. Instead of having to browse the entire network, users
3395 can go to the Dfs share and locate their data much more easily.</p>
3396
3397 <p>Dfs can also help administrators because it provides a level of
3398 indirection between the name of a shared folder and its actual
3399 location. The Dfs share contains references to resources on the
3400 network, and when a resource is accessed, the Dfs server hands the
3401 client off to the actual server of the resource. When moving
3402 resources to another computer, the reference to the resource in the
3403 Dfs share can be redirected to the new location in one step, with the
3404 change being entirely seamless for users.</p>
3405
3406 <p>To a limited extent, Dfs also can help improve performance for
3407 read-only shares because it provides <a name="INDEX-168"/>load balancing. It is possible
3408 to set up a Dfs reference to point to identical shares on two or more
3409 servers. The Dfs server then divides requests between the servers,
3410 dividing the client load among them. However, this works well only
3411 for static, read-only data because no provision is included in Dfs
3412 for synchronization among the servers when changes are made on any of
3413 them.</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
3421 client-side support for Dfs, and no extra configuration is required.
3422 Support is more limited for older versions, however. Windows for
3423 Workgroups cannot function as a Dfs client at all. Windows NT 4.0
3424 must be upgraded to at least Service Pack 3 to act as a Dfs client,
3425 and the Dfs Client must be installed. Later service packs (such as
3426 Service Pack 6) include the Dfs Client. Windows 95 must also have the
3427 Dfs Client software installed to act as a Dfs client. Without the Dfs
3428 Client software, double-clicking a remote folder in a Dfs share will
3429 show an empty folder, and no error message will appear.</p>
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
3433 download and install it. See the web page <a href="http://microsoft.com/ntserver/nts/downloads/winfeatures/NTSDistrFile/default.asp">http://microsoft.com/ntserver/nts/downloads/winfeatures/NTSDistrFile/default.asp</a>
3434 for a link to download the installation program and instructions on
3435 how to install the Dfs Client.</p>
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
3447 be compiled with the <tt class="literal">--with-msdfs</tt> configure
3448 option. (See <a href="ch02.html">Chapter 2</a> for instructions on
3449 configuring and compiling Samba.) Samba 3.0 includes Dfs support by
3450 default and does not need to be compiled with the
3451 <tt class="literal">--with-msdfs</tt> configure option.</p>
3452
3453 <p>Once a Dfs-enabled Samba server is running, there are just two steps
3454 to serving a Dfs share. First we will set up a Dfs root directory on
3455 the server, and then we will modify the <em class="filename">smb.conf</em>
3456 configuration file to enable the share.</p>
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
3468 root 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
3474 any other shared directory. These will function just as they would in
3475 any other share, allowing clients to access the directories and files
3476 on the Samba server. The whole idea of Dfs, though, is to gather
3477 together shares on other servers by making references to them in the
3478 Dfs tree. The way this is implemented with Samba involves a clever
3479 use of symbolic links, which can be in the Dfs root directory or any
3480 subdirectory in the Dfs tree.</p>
3481
3482 <p>You are probably familiar with using symbolic links to create
3483 references to files that exist on the same system, and perhaps
3484 crossing a local filesystem boundary (which ordinary Unix links
3485 cannot do). But maybe you didn't know that symbolic
3486 links have a more general functionality. Although we
3487 can't display its contents directly, as we could
3488 with a text or binary file, a symbolic link
3489 &quot;contains&quot; an ASCII text string
3490 naming what the link points to. For example, take a look at the
3491 listing for these symbolic links:</p>
3492
3493 <blockquote><pre class="code">$ <tt class="userinput"><b>ls -l wrdlnk alnk</b></tt>
3494 lrwxrwxrwx    1 jay      jay            15 Mar 14 06:50 wrdlnk -&gt; /usr/dict/words
3495 lrwxrwxrwx    1 jay      jay             9 Mar 14 06:53 alnk -&gt; dreamtime</pre></blockquote>
3496
3497 <p>As you can infer from the size of the <em class="filename">wrdlnk</em>
3498 link (15 bytes), the string <tt class="literal">/usr/dict/words</tt> is
3499 encoded into it. The size of <em class="filename">alnk</em> (9 bytes) is
3500 smaller, corresponding to the shorter name of
3501 <em class="filename">dreamtime</em>.</p>
3502
3503 <p>Now let's create a link in our Dfs root for an SMB
3504 share:</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>
3509 lrwxrwxrwx    1 root     root           12 Mar 13 17:34 maya-e -&gt; msdfs:maya\e</pre></blockquote>
3510
3511 <p>This link might appear as a
3512 &quot;broken&quot; link in a directory
3513 listing because it points to something that isn't a
3514 file on the local system. For example, the <em class="emphasis">file</em>
3515 command will report:</p>
3516
3517 <blockquote><pre class="code">$ <tt class="userinput"><b>file maya-e</b></tt>
3518 maya-e: broken symbolic link to msdfs:maya\e</pre></blockquote>
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
3522 Samba's Dfs support. When Samba encounters this
3523 file, it sees the leading <tt class="literal">msdfs</tt>: and interprets
3524 the rest as the name of a remote share. The client is then redirected
3525 to the remote share.</p>
3526
3527 <p>When creating links in the Dfs root directory, simply follow the same
3528 format, which in general is
3529 <tt class="literal">msdfs</tt>:<em class="replaceable">server</em>\<em class="replaceable">share</em>.
3530 Note that this is similar to a UNC appended onto the
3531 <tt class="literal">msdfs</tt>: string, except that in this case, the two
3532 backslashes preceding the server's name are omitted.</p>
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
3536 lowercase.</p>
3537 </blockquote>
3538
3539 <p>In addition to regular network shares, you can use symbolic links of
3540 this type to reference Dfs shares on other Dfs servers. However,
3541 referencing printer shares does not work. Dfs is for sharing files
3542 only. <a name="INDEX-171"/></p>
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
3554 set up a load-balancing Dfs share, create the symbolic link like
3555 this:</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
3560 reference. Remember, it is up to you to make sure the shared folders
3561 remain identical. Set up permissions on the servers to make the
3562 shares read-only to users.</p>
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
3566 add 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
3573 Dfs root directory we just set up, and the parameter
3574 <tt class="literal">msdfs</tt> <tt class="literal">root</tt> <tt class="literal">=</tt>
3575 <tt class="literal">yes</tt> tells Samba that this share is a Dfs root.</p>
3576
3577 <p>To enable support for Dfs in the server, we need to add one line to
3578 the <tt class="literal">[global]</tt> section:</p>
3579
3580 <a name="INDEX-174"/><blockquote><pre class="code">[global]
3581     host msdfs = yes</pre></blockquote>
3582
3583 <p>Restart the Samba daemons&mdash;or just wait a minute for them to
3584 reread the configuration file&mdash;and you will see the new share
3585 from Windows clients. If you have trouble accessing any of the remote
3586 shares in the Dfs share, recheck your symbolic links to make sure
3587 they were created correctly. <a name="INDEX-175"/></p>
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
3591 might need to reboot Windows clients before they can access the share
3592 as 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
3611 users' home directories to be mounted over the
3612 network by NFS. If a Samba server being used to authenticate user
3613 logons is running on a system with NFS-mounted home directories
3614 shared with a <tt class="literal">[homes]</tt> share, the additional
3615 overhead can result in poor performance&mdash;about 30% of normal
3616 Samba speed.</p>
3617
3618 <p>Samba has the ability to work with <a name="INDEX-176"/>NIS and NIS+ to find the
3619 server on which the home directories actually reside so that they can
3620 be shared directly from that server. For this to work, the server
3621 that holds the home directories must also have Samba running, with a
3622 <tt class="literal">[homes]</tt> share of its own.</p>
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
3631 for 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
3669 user'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
3687 directory.</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
3706 are for Samba servers on network sites where Unix home directories
3707 are provided using NFS, the automounter, and NIS.</p>
3708
3709 <p>The <tt class="literal">nis</tt> <tt class="literal">homedir</tt> option
3710 indicates that the home-directory server for the user needs to be
3711 looked up in NIS. The <tt class="literal">homedir</tt>
3712 <tt class="literal">map</tt> option tells Samba in which NIS map to look
3713 for the server that has the user's home directory.
3714 The server needs to be a Samba server so that the client can do an
3715 SMB connect to it, and the other Samba servers need to have NIS
3716 installed so that they can do the lookup.</p>
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>,
3721 Samba will look in the file specified by <tt class="literal">homedir</tt>
3722 <tt class="literal">map</tt> for a home directory for
3723 <tt class="literal">joe</tt>. If it finds one, Samba will return the
3724 associated system name to the client. The client will then try to
3725 connect to that machine and get the share from there. Enabling NIS
3726 lookups looks like the following:</p>
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
3742 probably be grayed for your file. Don't worry about
3743 that&mdash;you should still be able to see when the box is checked
3744 and when it isn't.</p> </blockquote><hr/><h4 class="head4"><a href="toc.html">TOC</a></h4></body></html>