8bf541cd2f73b051cb074a71a8a015f8daf7fb52
[samba.git] / docs-xml / using_samba / ch05.xml
1 <chapter label="5" id="SAMBA-CH-5">
2 <title>Browsing and Advanced Disk Shares </title>
3
4
5
6
7 <para>
8 <indexterm id="ch05-idx-969559-0" class="startofrange"><primary>browsing</primary></indexterm>
9 <indexterm id="ch05-idx-969559-1" class="startofrange"><primary>disk shares</primary><secondary>advanced</secondary></indexterm>This chapter continues our discussion of disk shares from the previous chapter. Here, we will discuss various differences between the Windows and Unix filesystems&mdash;and how Samba works to bridge the gap. There are a surprising number of inconsistencies between a DOS filesystem and a Unix filesystem. In addition, we will talk briefly about name mangling, file locking, and a relatively new feature for Samba: opportunistic locking, or oplocks. However, before we move into that territory, we should first discuss the somewhat arcane topic of browsing with Samba.</para>
10
11
12
13
14
15
16
17
18
19
20
21 <sect1 role="" label="5.1" id="ch05-23763">
22 <title>Browsing</title>
23
24
25 <para>Browsing is the ability to examine the servers and <indexterm id="ch05-idx-969575-0"><primary>shares</primary><secondary>viewing</secondary><see>browsing</see></indexterm>shares that are currently available on your network. On a Windows NT 4.0 or 95/98 client, a user can browse network servers through the Network Neighborhood folder. By double-clicking  the icon representing the server, the user should be able to see the printer and disk share resources available on that machine as well. (If you have Windows NT 3.<emphasis>x</emphasis>, you can use the Disk-Connect Network Drive menu in the File Manager to display the available shares on a server.)</para>
26
27
28 <para>From the Windows command line, you can also use the <literal>net</literal> <literal>view</literal> option to see which servers are currently on the network. Here is an example of the <literal>net</literal> <literal>view</literal> command in action:</para>
29
30
31 <programlisting>C:\&gt;<userinput>net view</userinput>
32 Servers available in workgroup SIMPLE
33 Server name            Remark
34 ----------------------------------------------------------
35 \\CHIMAERA             Windows NT 4.0
36 \\HYDRA                Samba 2.0.4 on (hydra)
37 \\PHOENIX              Windows 98</programlisting>
38
39
40 <sect2 role="" label="5.1.1" id="ch05-SECT-1.1">
41 <title>Preventing Browsing</title>
42
43
44 <para>
45 <indexterm id="ch05-idx-969576-0"><primary>browsing</primary><secondary>preventing</secondary></indexterm>
46 <indexterm id="ch05-idx-969576-1"><primary>preventing browsing</primary></indexterm>
47 <indexterm id="ch05-idx-969576-2"><primary>browse lists</primary><secondary>restricting shares from</secondary></indexterm>
48 <indexterm id="ch05-idx-969576-3"><primary>shares</primary><secondary>contents, restricting view of</secondary></indexterm>You can restrict a share from being in a browse list by using the <literal>browseable</literal> option. This boolean option prevents a share from being seen in the Network Neighborhood at all. For example, to prevent the <literal>[data]</literal> share from the previous chapter from being visible, we could write:</para>
49
50
51 <programlisting>[data]
52         path = /home/samba/data
53         browseable = no
54         guest ok = yes
55         comment = Data Drive
56         volume = Sample-Data-Drive
57         writeable = yes</programlisting>
58
59
60 <para>Although you typically don't want to do this to an ordinary disk share, the browseable option is useful in the event that you need to create a share with contents that you do not want others to see, such as a <literal>[netlogin]</literal> share for storing logon scripts for Windows domain control (see <link linkend="SAMBA-CH-6">Chapter 6</link> for more information on logon scripts).</para>
61
62
63 <para>Another example is the <literal>[homes]</literal> share. This share is often marked non-browsable so that a share named <literal>[homes]</literal> won't appear when its machine's resources are browsed. However, if a user <literal>alice</literal> logs on and looks at the machine's shares, an <literal>[alice]</literal> share will appear under the machine. What if we wanted to make sure <literal>alice</literal>'s share appeared to everyone before she logs in? This could be done with the global <literal>auto</literal> <literal>services</literal> option. This option preloads shares into the browse list to ensure that they are always visible:</para>
64
65
66 <programlisting>[global]
67         ...
68         auto services = alice
69         ...</programlisting>
70 </sect2>
71
72
73
74
75
76 <sect2 role="" label="5.1.2" id="ch05-SECT-1.2">
77 <title>Default Services</title>
78
79
80 <para>In the event that a user cannot successfully connect to a share, you can specify a default <indexterm id="ch05-idx-969587-0"><primary>shares</primary><secondary>default</secondary></indexterm>
81 <indexterm id="ch05-idx-969587-1"><primary>default services</primary></indexterm>share to which they can connect. Since you do not know who will default to this share at any time, you will probably want to set the <literal>guest</literal> <literal>ok</literal> option to <literal>yes</literal> for this share. Specifying a <literal>default</literal> <literal>service</literal> can be useful when sending the utterly befuddled to a directory of help files. For example:</para>
82
83
84 <programlisting>[global]
85         ...
86         default service = helpshare
87         ...
88
89 [helpshare]
90         path = /home/samba/helpshare/%S
91         browseable = yes
92         guest ok = yes
93         comment = Default Share for Unsuccessful Connections
94         volume = Sample-Data-Drive
95         writeable = no</programlisting>
96
97
98 <para>Note that we used the <literal>%S</literal> variable in the <literal>path</literal> option. If you use the <literal>%S</literal> variable, it will refer to the requested nonexistent share (the original share requested by the user), not the name of the resulting default share. This allows us to create different paths with the names of each server, which can provide more customized help files for users. In addition, any <indexterm id="ch05-idx-969588-0"><primary>underscore ( _ ) in shares</primary></indexterm>
99 <indexterm id="ch05-idx-969588-1"><primary>_ underscore</primary></indexterm>underscores ( _ ) specified in the requested share will be converted to<indexterm id="ch05-idx-969589-0"><primary>slash (/)</primary><secondary>in shares</secondary></indexterm>
100 <indexterm id="ch05-idx-969589-1"><primary>/ (slash) in shares</primary></indexterm> slashes ( / ) when the <literal>%S</literal> variable is used.</para>
101 </sect2>
102
103
104
105
106
107 <sect2 role="" label="5.1.3" id="ch05-SECT-1.3">
108 <title>Browsing Elections</title>
109
110
111 <para>
112 <indexterm id="ch05-idx-969892-0" class="startofrange"><primary>browsing</primary><secondary>elections</secondary></indexterm>As mentioned in <link linkend="ch01-48078">Chapter 1</link>, one machine in each subnet always keeps a list of the currently active <indexterm id="ch05-idx-969897-0"><primary>servers</primary><secondary>active, list of</secondary></indexterm>machines. This list is called the <firstterm>browse list</firstterm>
113 <indexterm id="ch05-idx-969898-0"><primary>browse lists</primary></indexterm> and the server that maintains it is called the <indexterm id="ch05-idx-970543-0" class="startofrange"><primary>local master browser</primary></indexterm><firstterm>local master browser</firstterm>. As machines come on and off the network, the local master browser continually updates the information in the browse list and provides it to any machine that requests it.</para>
114
115
116 <para>A computer becomes a local master browser by holding a browsing election on the local subnet. Browsing elections can be called at any time. Samba can rig a browsing election for a variety of outcomes, including always becoming the local master browser of the subnet or never becoming it. For example, the following options, which we've added to the configuration file from <link linkend="ch04-21486">Chapter 4</link>, will ensure that Samba always wins the election for local master browser no matter which machines are also present:</para>
117
118
119 <programlisting>[global]
120         netbios name = HYDRA
121         server string = Samba %v on (%L)
122         workgroup = SIMPLE
123
124         #  Browsing election options
125         os level = 34
126         local master = yes
127
128         #  Networking configuration options
129         hosts allow = 192.168.220. 134.213.233. localhost
130         hosts deny = 192.168.220.102
131         interfaces = 192.168.220.100/255.255.255.0 \
132                          134.213.233.110/255.255.255.0
133
134         # Debug logging information
135         log level = 2
136         log file = /var/log/samba.log.%m
137         max log size = 50
138         debug timestamp = yes
139
140 [data]
141         path = /home/samba/data
142         browseable = yes
143         guest ok = yes
144         comment = Data Drive
145         volume = Sample-Data-Drive
146         writable = yes</programlisting>
147
148
149 <para>However, what if we didn't always want to win the election? What if we wanted to yield browsing to a Windows NT Server if present? In order to do that, we need to learn how browsing elections work. As you already know, each machine that takes place in the election must broadcast information about itself. This information includes the following:</para>
150
151
152 <itemizedlist>
153 <listitem><para>The version of the election protocol used</para></listitem>
154 <listitem><para>The operating system on the machine</para></listitem>
155 <listitem><para>The amount of time the client has been on the network</para></listitem>
156 <listitem><para>The hostname of the client</para></listitem>
157 </itemizedlist>
158
159 <para>Here is how the election is decided. Operating systems are assigned a binary value according to their version, as shown in <link linkend="ch05-51423">Table 5.1</link>.</para>
160
161
162 <table label="5.1" id="ch05-51423">
163 <title>Operating System Values in an Election </title>
164
165 <tgroup cols="2">
166 <colspec colnum="1" colname="col1"/>
167 <colspec colnum="2" colname="col2"/>
168 <thead>
169 <row>
170
171 <entry colname="col1"><para>Operating System</para></entry>
172
173 <entry colname="col2"><para>Value</para></entry>
174
175 </row>
176
177 </thead>
178
179 <tbody>
180 <row>
181
182 <entry colname="col1"><para>
183 <indexterm id="ch05-idx-969634-0"><primary>operating systems</primary><secondary>values in elections</secondary></indexterm>
184 <indexterm id="ch05-idx-969634-1"><primary>elections</primary><secondary>operating system values in</secondary></indexterm>Windows NT Server 4.0</para></entry>
185
186 <entry colname="col2"><para>33</para></entry>
187
188 </row>
189
190 <row>
191
192 <entry colname="col1"><para>Windows NT Server 3.51</para></entry>
193
194 <entry colname="col2"><para>32</para></entry>
195
196 </row>
197
198 <row>
199
200 <entry colname="col1"><para>Windows NT Workstation 4.0</para></entry>
201
202 <entry colname="col2"><para>17</para></entry>
203
204 </row>
205
206 <row>
207
208 <entry colname="col1"><para>Windows NT Workstation 3.51</para></entry>
209
210 <entry colname="col2"><para>16</para></entry>
211
212 </row>
213
214 <row>
215
216 <entry colname="col1"><para>Windows 98</para></entry>
217
218 <entry colname="col2"><para>2</para></entry>
219
220 </row>
221
222 <row>
223
224 <entry colname="col1"><para>Windows 95</para></entry>
225
226 <entry colname="col2"><para>1</para></entry>
227
228 </row>
229
230 <row>
231
232 <entry colname="col1"><para>Windows 3.1 for Workgroups</para></entry>
233
234 <entry colname="col2"><para>1</para></entry>
235
236 </row>
237
238 </tbody>
239 </tgroup>
240 </table>
241
242
243 <para>Following that, each computer on the network is assigned a separate value according to its role, as shown in <link linkend="SAMBA-CH-5-TBL-5.2">Table 5.2</link>.</para>
244
245
246 <table label="5.2" id="SAMBA-CH-5-TBL-5.2">
247 <title>Computer Role Settings in an Election </title>
248
249 <tgroup cols="2">
250 <colspec colnum="1" colname="col1"/>
251 <colspec colnum="2" colname="col2"/>
252 <thead>
253 <row>
254
255 <entry colname="col1"><para>Role</para></entry>
256
257 <entry colname="col2"><para>Value</para></entry>
258
259 </row>
260
261 </thead>
262
263 <tbody>
264 <row>
265
266 <entry colname="col1"><para>
267 <indexterm id="ch05-idx-969635-0"><primary>Windows clients</primary><secondary>role settings in elections</secondary></indexterm>
268 <indexterm id="ch05-idx-969635-1"><primary>elections</primary><secondary>role settings in</secondary></indexterm>
269 <indexterm id="ch05-idx-969635-2"><primary>role settings in elections</primary></indexterm>
270 <indexterm id="ch05-idx-969635-3"><primary>role settings in elections</primary></indexterm>Primary Domain Controller</para></entry>
271
272 <entry colname="col2"><para>128</para></entry>
273
274 </row>
275
276 <row>
277
278 <entry colname="col1"><para>WINS Client</para></entry>
279
280 <entry colname="col2"><para>32</para></entry>
281
282 </row>
283
284 <row>
285
286 <entry colname="col1"><para>Preferred Master Browser</para></entry>
287
288 <entry colname="col2"><para>8</para></entry>
289
290 </row>
291
292 <row>
293
294 <entry colname="col1"><para>Active Master Browser</para></entry>
295
296 <entry colname="col2"><para>4</para></entry>
297
298 </row>
299
300 <row>
301
302 <entry colname="col1"><para>Standby Browser</para></entry>
303
304 <entry colname="col2"><para>2</para></entry>
305
306 </row>
307
308 <row>
309
310 <entry colname="col1"><para>Active Backup Browser</para></entry>
311
312 <entry colname="col2"><para>1</para></entry>
313
314 </row>
315
316 </tbody>
317 </tgroup>
318 </table>
319
320
321 <para>
322 <indexterm id="ch05-idx-969637-0"><primary>elections</primary><secondary>order of decisions in</secondary></indexterm>Elections are decided in the following order:</para>
323
324
325 <orderedlist>
326 <listitem><para>The machine with the highest version of the election protocol will win. (So far, this is meaningless, as all Windows clients have version 1 of the election protocol.)</para></listitem>
327 <listitem><para>The machine with the highest operating system value wins the election.</para></listitem>
328 <listitem><para>If there is a tie, the machine with the setting of Preferred Master Browser (role 8) wins the election.</para></listitem>
329 <listitem><para>If there is still a tie, the client who has been online the longest wins the election.</para></listitem>
330 <listitem><para>And finally, if there is still a tie, the client name that comes first alphabetically wins.</para></listitem>
331 <listitem><para>The machine that is the "runner-up" can become a backup browser.</para></listitem>
332 </orderedlist>
333
334 <para>As a result, if you want Samba to take the role of a local master browser, but only if there isn't a Windows NT Server (4.0 or 3.51) on the network, you could change the <literal>os</literal> <literal>level</literal> parameter in the previous example to:</para>
335
336
337 <programlisting>os level = 31</programlisting>
338
339
340 <para>This will cause Samba to immediately lose the election to a Windows NT 4.0 or  Windows NT 3.5 Server, both of which have a higher operating systems level. On the other hand, if you wanted to decide the local master browser on the basis of the network role, such as which machine is the primary domain controller, you could set the <literal>os</literal> <literal>level</literal> to match the highest type of operating system on the network and let the election protocol fall down to the next level.</para>
341
342
343 <para>
344 <indexterm id="ch05-idx-969646-0"><primary>local master browser</primary><secondary>checking machines for</secondary></indexterm>How can you can tell if a machine is a local master browser? By using the <literal>nbtstat</literal> command. Place the NetBIOS name of the machine you wish to check after the <literal>-a</literal> option:</para>
345
346
347 <programlisting>C:\&gt;<userinput>nbtstat -a hydra</userinput>
348
349        NetBIOS Remote Machine Name Table
350
351  Name                            Type         Status
352 ----------------------------------------------------------
353  HYDRA                     &lt;00&gt;  UNIQUE       Registered
354  HYDRA                     &lt;03&gt;  UNIQUE       Registered
355  HYDRA                     &lt;20&gt;  UNIQUE       Registered
356  .._ _MSBROWSE_ _.         &lt;01&gt;  GROUP        Registered
357  SIMPLE                    &lt;00&gt;  GROUP        Registered
358  SIMPLE                    &lt;1D&gt;  UNIQUE       Registered
359  SIMPLE                    &lt;1E&gt;  GROUP        Registered
360
361  MAC Address = 00-00-00-00-00-00</programlisting>
362
363
364 <para>The resource entry that you're looking for is the <literal>.._   _MSBROWSE_   _.&lt;01&gt;</literal>. This indicates that the server is currently acting as the local master browser for the current subnet. In addition, if the machine is a Samba server, you can check the Samba <filename>nmbd</filename> log file for an entry such as:</para>
365
366
367 <programlisting>nmbd/nmbd_become_lmb.c:become_local_master_stage2(406)
368 *****
369 Samba name server HYDRA is now a local master browser for
370 workgroup SIMPLE on subnet 192.168.220.100
371 ****</programlisting>
372
373
374 <para>Finally, Windows NT servers serving as primary domain controllers contain a sneak that allows them to assume the role of the local master browser in certain conditions; this is called the <emphasis>preferred</emphasis>
375 <indexterm id="ch05-idx-969647-0"><primary>preferred master browser</primary></indexterm> <emphasis>master browser</emphasis> bit. Earlier, we mentioned that Samba could set this bit on itself as well. You can enable it with the <literal>preferred</literal> <literal>master</literal> option:</para>
376
377
378 <programlisting>#  Browsing election options
379 os level = 33
380 local master = yes
381 preferred master = yes</programlisting>
382
383
384 <para>If the preferred master bit is set, the machine will force a browsing election at startup. Of course, this is needed only if you set the <literal>os</literal> <literal>level</literal> option to match the Windows NT machine. We recommend that you don't use this option if another machine also has the role of preferred master, such as an NT server.<indexterm id="ch05-idx-969633-0" class="endofrange" startref="ch05-idx-969892-0"/></para>
385 </sect2>
386
387
388
389
390
391 <sect2 role="" label="5.1.4" id="ch05-SECT-1.4">
392 <title>Domain Master Browser</title>
393
394
395 <para>
396 <indexterm id="ch05-idx-969654-0" class="startofrange"><primary>DMB (domain master browser)</primary></indexterm>
397 <indexterm id="ch05-idx-969654-1"><primary>domain master browser</primary><see>DMB</see></indexterm>
398 <indexterm id="ch05-idx-969654-2"><primary>domains</primary><secondary>controllers</secondary><see>domain controllers</see></indexterm>In the opening chapter, we mentioned that in order for a Windows workgroup or domain to extend into multiple subnets, one machine would have to take the role of the <firstterm>domain master browser</firstterm>. The domain master browser propagates browse lists across each of the subnets in the workgroup. This works because each local master browser periodically synchronizes its browse list with the domain master browser. During this synchronization, the local master browser passes on any server that the domain master browser does not have in its browse list, and vice versa. In a perfect world, each local master browser would eventually have the browse list for the entire domain.</para>
399
400
401 <para>Unlike the local master browser, there is no election to determine which machine assumes the role of the domain master browser. Instead, the administrator has to set it manually. By Microsoft design, however, the domain master browser and the primary domain controller (PDC) both register a resource type of &lt;1B&gt;, so the roles&mdash;and the machines&mdash;are inseparable.</para>
402
403
404 <para>If you have a <indexterm id="ch05-idx-969663-0"><primary>Windows NT</primary><secondary>server, domain master browser and</secondary></indexterm>Windows NT server on the network acting as a PDC, we recommend that you do not use Samba to become the domain master browser. The reverse is true as well: if Samba is taking on the responsibilities of a <indexterm id="ch05-idx-969665-0"><primary>PDC (primary domain controller)</primary><secondary>domain master browser and</secondary></indexterm>PDC, we recommend making it the domain master browser as well. Although it is possible to split the roles with Samba, this is not a good idea. Using two different machines to serve as the PDC and the domain master browser can cause random errors to occur on a Windows workgroup.</para>
405
406
407 <para>Samba can assume the role of a domain master browser for all subnets in the workgroup with the following option:</para>
408
409
410 <programlisting>domain master = yes</programlisting>
411
412
413 <para>You can verify that a Samba machine is in fact the domain master browser by checking the <emphasis>nmbd</emphasis> log file:</para>
414
415
416 <programlisting>nmbd/nmbd_become_dmb.c:become_domain_master_stage2(118)
417 *****
418 Samba name server HYDRA is now a domain master browser for
419 workgroup SIMPLE on subnet 192.168.220.100
420 *****</programlisting>
421
422
423 <para>Or you can use the <literal>nmblookup</literal> command that comes with the Samba distribution to query for a unique &lt;1B&gt; resource type in the workgroup:</para>
424
425
426 <programlisting># <userinput>nmblookup SIMPLE#1B</userinput>
427 Sending queries to 192.168.220.255
428 192.168.220.100 SIMPLE&lt;1b&gt;</programlisting>
429
430
431 <sect3 role="" label="5.1.4.1" id="ch05-SECT-1.4.1">
432 <title>Multiple subnets</title>
433
434
435 <para>
436 <indexterm id="ch05-idx-969667-0"><primary>multiple subnets</primary></indexterm>There are three rules that you must remember when creating a workgroup/domain that spans more than one subnet:</para>
437
438
439 <itemizedlist>
440 <listitem><para>You must have either a Windows NT or Samba machine acting as a local master browser on each subnet in the workgroup/domain. (If you have a domain master browser in a subnet, a local master browser is not needed.)</para></listitem>
441 <listitem><para>You must have a Windows NT Server or a Samba machine acting as a domain master browser somewhere in the workgroup.</para></listitem>
442 <listitem><para>Each local master browser must be instructed to synchronize with the domain master browser.</para></listitem>
443 </itemizedlist>
444
445 <para>Samba has a few other features in this arena in the event that you don't have or want a domain master browser on your network. Consider the subnets shown in <link linkend="ch05-15706">Figure 5.1</link>.</para>
446
447
448 <figure label="5.1" id="ch05-15706">
449 <title>Multiple subnets with Samba servers</title>
450
451 <graphic width="502" depth="325" fileref="figs/sam.0501.gif"></graphic>
452 </figure>
453
454 <para>First, a Samba server that is a local master browser can use the <literal>remote</literal> <literal>announce</literal> configuration option to make sure that computers in different subnets are sent broadcast announcements about the server. This has the effect of ensuring that the Samba server appears in the browse lists of foreign subnets. To achieve this, however, the directed broadcasts must reach the local master browser on the other subnet. Be aware that many routers do not allow directed broadcasts by default; you may have to change this setting on the router for the directed broadcasts to get through to its subnet.</para>
455
456
457 <para>With the <literal>remote</literal> <literal>announce</literal> option, list the subnets and the workgroup that should receive the broadcast. For example, to ensure that machines in the 192.168.221 and 192.168.222 subnets and SIMPLE workgroup are sent broadcast information from our Samba server, we could specify the following:</para>
458
459
460 <programlisting>#  Browsing election options
461 os level = 34
462 local master = yes
463 remote announce = 192.168.221.255/SIMPLE \
464         192.168.222.255/SIMPLE</programlisting>
465
466
467 <para>In addition, you are allowed to specify the exact address to send broadcasts to if the local master browser on the foreign subnet is guaranteed to always have a fixed IP address.</para>
468
469
470 <para>A Samba local master browser can synchronize its browse list directly with another Samba server acting as a local master browser on a different subnet. For example, let's assume that Samba is configured as a local master browser, and Samba local master browsers exist at 192.168.221.130 and 192.168.222.120. We can use the <literal>remote</literal> <literal>browse</literal> <literal>sync</literal> option to sync directly with the Samba servers, as follows:</para>
471
472
473 <programlisting>#  Browsing election options
474 os level = 34
475 local master = yes
476 remote browse sync = 192.168.221.130 192.168.222.120</programlisting>
477
478
479 <para>In order for this to work, the other Samba machines must also be local master browsers. You can also use directed broadcasts with this option if you do not know specific IP addresses of local master browsers.<indexterm id="ch05-idx-969939-0" class="endofrange" startref="ch05-idx-969654-0"/>
480 <indexterm id="ch05-idx-969940-0" class="endofrange" startref="ch05-idx-970543-0"/></para>
481 </sect3>
482 </sect2>
483
484
485
486
487
488 <sect2 role="" label="5.1.5" id="ch05-SECT-1.5">
489 <title>Browsing Options</title>
490
491
492 <para>
493 <indexterm id="ch05-idx-969668-0" class="startofrange"><primary>browsing</primary><secondary>configuration options for</secondary></indexterm>
494 <indexterm id="ch05-idx-969668-1" class="startofrange"><primary>configuration options</primary><secondary>browsing</secondary></indexterm><link linkend="ch05-81028">Table 5.3</link> shows 14 options that define how Samba handles browsing tasks. We recommend the defaults for a site that prefers to be easy on its users with respect to locating shares and printers.</para>
495
496
497 <table label="5.3" id="ch05-81028">
498 <title>Browsing Configuration Options </title>
499
500 <tgroup cols="5">
501 <colspec colnum="1" colname="col1"/>
502 <colspec colnum="2" colname="col2"/>
503 <colspec colnum="3" colname="col3"/>
504 <colspec colnum="4" colname="col4"/>
505 <colspec colnum="5" colname="col5"/>
506 <thead>
507 <row>
508
509 <entry colname="col1"><para>Option</para></entry>
510
511 <entry colname="col2"><para>Parameters</para></entry>
512
513 <entry colname="col3"><para>Function</para></entry>
514
515 <entry colname="col4"><para>Default</para></entry>
516
517 <entry colname="col5"><para>Scope</para></entry>
518
519 </row>
520
521 </thead>
522
523 <tbody>
524 <row>
525
526 <entry colname="col1"><para><literal>announce as</literal></para></entry>
527
528 <entry colname="col2"><para><literal>NT</literal>
529 <indexterm id="ch05-idx-969670-0"><primary>browsing</primary><secondary>options for, list of</secondary></indexterm> or <literal>Win95</literal> or <literal>Wf W</literal></para></entry>
530
531 <entry colname="col3"><para>Sets the operating system that Samba will announce itself as.</para></entry>
532
533 <entry colname="col4"><para><literal>N T</literal></para></entry>
534
535 <entry colname="col5"><para>Global</para></entry>
536
537 </row>
538
539 <row>
540
541 <entry colname="col1"><para><literal>announce version</literal></para></entry>
542
543 <entry colname="col2"><para>numerical</para></entry>
544
545 <entry colname="col3"><para>Sets the version of the operating system that Samba will announce itself as.</para></entry>
546
547 <entry colname="col4"><para><literal>4.2</literal></para></entry>
548
549 <entry colname="col5"><para>Global</para></entry>
550
551 </row>
552
553 <row>
554
555 <entry colname="col1"><para><literal>browseable (browsable)</literal></para></entry>
556
557 <entry colname="col2"><para>boolean</para></entry>
558
559 <entry colname="col3"><para>Allows share to be displayed in list of machine resources.</para></entry>
560
561 <entry colname="col4"><para><literal>yes</literal></para></entry>
562
563 <entry colname="col5"><para>Share</para></entry>
564
565 </row>
566
567 <row>
568
569 <entry colname="col1"><para><literal>browse list</literal></para></entry>
570
571 <entry colname="col2"><para>boolean</para></entry>
572
573 <entry colname="col3"><para>If <literal>yes</literal>, Samba will provide a browse list on this server.</para></entry>
574
575 <entry colname="col4"><para><literal>yes</literal></para></entry>
576
577 <entry colname="col5"><para>Global</para></entry>
578
579 </row>
580
581 <row>
582
583 <entry colname="col1"><para><literal>auto services (preload)</literal></para></entry>
584
585 <entry colname="col2"><para>string (share list)</para></entry>
586
587 <entry colname="col3"><para>Sets a list of shares that will always appear in the browse list.</para></entry>
588
589 <entry colname="col4"><para>None</para></entry>
590
591 <entry colname="col5"><para>Global</para></entry>
592
593 </row>
594
595 <row>
596
597 <entry colname="col1"><para><literal>default service (default)</literal></para></entry>
598
599 <entry colname="col2"><para>string (share name)</para></entry>
600
601 <entry colname="col3"><para>Names a share (service) that will be provided if the client requests a share not listed in <emphasis>smb.conf.</emphasis></para></entry>
602
603 <entry colname="col4"><para>None</para></entry>
604
605 <entry colname="col5"><para>Global</para></entry>
606
607 </row>
608
609 <row>
610
611 <entry colname="col1"><para><literal>local master</literal></para></entry>
612
613 <entry colname="col2"><para>boolean</para></entry>
614
615 <entry colname="col3"><para>If <literal>yes</literal>, Samba will try to become a master browser on the local subnet.</para></entry>
616
617 <entry colname="col4"><para><literal>yes</literal></para></entry>
618
619 <entry colname="col5"><para>Global</para></entry>
620
621 </row>
622
623 <row>
624
625 <entry colname="col1"><para><literal>lm announce</literal></para></entry>
626
627 <entry colname="col2"><para><literal>yes</literal> or <literal>no</literal> or <literal>auto</literal></para></entry>
628
629 <entry colname="col3"><para>Enables or disables LAN Manager style host announcements.</para></entry>
630
631 <entry colname="col4"><para><literal>auto</literal></para></entry>
632
633 <entry colname="col5"><para>Global</para></entry>
634
635 </row>
636
637 <row>
638
639 <entry colname="col1"><para><literal>lm interval</literal></para></entry>
640
641 <entry colname="col2"><para>numerical</para></entry>
642
643 <entry colname="col3"><para>Specifies the frequency in seconds that LAN Manager announcements will be made if activated.</para></entry>
644
645 <entry colname="col4"><para><literal>60</literal></para></entry>
646
647 <entry colname="col5"><para>Global</para></entry>
648
649 </row>
650
651 <row>
652
653 <entry colname="col1"><para><literal>preferred master (prefered master)</literal></para></entry>
654
655 <entry colname="col2"><para>boolean</para></entry>
656
657 <entry colname="col3"><para>If <literal>yes</literal>, Samba will use the preferred master browser bit to attempt to become the local master browser.</para></entry>
658
659 <entry colname="col4"><para><literal>no</literal></para></entry>
660
661 <entry colname="col5"><para>Global</para></entry>
662
663 </row>
664
665 <row>
666
667 <entry colname="col1"><para><literal>domain master</literal></para></entry>
668
669 <entry colname="col2"><para>boolean</para></entry>
670
671 <entry colname="col3"><para>If <literal>yes</literal>, Samba will try to become the main browser master for the workgroup.</para></entry>
672
673 <entry colname="col4"><para><literal>no</literal></para></entry>
674
675 <entry colname="col5"><para>Global</para></entry>
676
677 </row>
678
679 <row>
680
681 <entry colname="col1"><para><literal>os level</literal></para></entry>
682
683 <entry colname="col2"><para>numerical</para></entry>
684
685 <entry colname="col3"><para>Sets the operating system level of Samba in an election for local master browser.</para></entry>
686
687 <entry colname="col4"><para><literal>0</literal></para></entry>
688
689 <entry colname="col5"><para>Global</para></entry>
690
691 </row>
692
693 <row>
694
695 <entry colname="col1"><para><literal>remote browse sync</literal></para></entry>
696
697 <entry colname="col2"><para>string (list of IP addresses)</para></entry>
698
699 <entry colname="col3"><para>Lists Samba servers to synchronize browse lists with.</para></entry>
700
701 <entry colname="col4"><para>None</para></entry>
702
703 <entry colname="col5"><para>Global</para></entry>
704
705 </row>
706
707 <row>
708
709 <entry colname="col1"><para><literal>remote announce</literal></para></entry>
710
711 <entry colname="col2"><para>string (IP address/ workgroup pairs)</para></entry>
712
713 <entry colname="col3"><para>Lists subnets and workgroups to send directed broadcast packets to, allowing Samba to appear to browse lists.</para></entry>
714
715 <entry colname="col4"><para>None</para></entry>
716
717 <entry colname="col5"><para>Global</para></entry>
718
719 </row>
720
721 </tbody>
722 </tgroup>
723 </table>
724
725
726 <sect3 role="" label="5.1.5.1" id="ch05-SECT-1.5.1">
727 <indexterm id="ch05-idx-970552-0"><primary>announce as option</primary></indexterm>
728 <title>
729 announce as</title>
730
731
732 <para>This global configuration option specifies the type of operating system that Samba will announce to other machines on the network. The default value for this option is <literal>N T</literal>, which represents a Windows NT operating system. Other possible values are <literal>Win95</literal>, which represents a Windows 95 operating system, and <literal>W f W</literal> for a Windows for Workgroup operating system. You can override the default value with the following:</para>
733
734
735 <programlisting>[global]
736         announce as = Win95</programlisting>
737
738
739 <para>We recommend against changing the default value of this configuration option.</para>
740 </sect3>
741
742
743
744 <sect3 role="" label="5.1.5.2" id="ch05-SECT-1.5.2">
745 <indexterm id="ch05-idx-970555-0"><primary>announce version option</primary></indexterm>
746 <title>
747 announce version</title>
748
749
750 <para>This global option is frequently used with the <literal>announce</literal> <literal>as</literal> configuration option; it specifies the version of the operating system that Samba will announce to other machines on the network. The default value of this options is 4.2, which places itself above the current Windows NT version of 4.0. You can specify a new value with a global entry such as the following:</para>
751
752
753 <programlisting>[global]
754         announce version = 4.3</programlisting>
755
756
757 <para>We recommend against changing the default value of this configuration option.</para>
758 </sect3>
759
760
761
762 <sect3 role="" label="5.1.5.3" id="ch05-38345">
763 <title>browseable</title>
764
765
766 <para>The <literal>browseable</literal> option (also spelled <literal>browsable</literal>) indicates whether the share referenced should appear in the list of available resources of the machine on which it resides. This option is always set to <literal>yes</literal> by default. If you wish to prevent the share from being seen in a client's browser, you can reset this option to <literal>no</literal>.</para>
767
768
769 <para>Note that this does not prevent someone from accessing the share using other means, such as specifying a UNC location (<literal>//server/accounting)</literal> in Windows Explorer. It only prevents the share from being listed under the machine's resources when being browsed.</para>
770 </sect3>
771
772
773
774 <sect3 role="" label="5.1.5.4" id="ch05-SECT-1.5.4">
775 <title>browse list</title>
776
777
778 <para>
779 <indexterm id="ch05-idx-969674-0"><primary>browse lists</primary><secondary>options for</secondary></indexterm>You should never need to change this parameter from its default value of <literal>yes</literal>. If your Samba server is acting as a local master browser (i.e., it has won the browsing election), you can use the global <literal>browse</literal> <literal>list</literal> option to instruct Samba to provide or withhold its browse list to all clients. By default, Samba always provides a browse list. You can withhold this information by specifying the following:</para>
780
781
782 <programlisting>[global]
783         browse list = no</programlisting>
784
785
786 <para>If you disable the browse list, clients cannot browse the names of other machines, their services, and other domains currently available on the network. Note that this won't make any particular machine inaccessible; if someone knows a valid machine name/address and a share on that machine, they can still connect to it explicitly using NET USE or by mapping a drive letter to it using Windows Explorer. It simply prevents information in the browse list from being retrieved by any client that requests it.</para>
787 </sect3>
788
789
790
791 <sect3 role="" label="5.1.5.5" id="ch05-SECT-1.5.5">
792 <title>auto services</title>
793
794
795 <para>The global <literal>auto</literal>
796 <indexterm id="ch05-idx-970563-0"><primary>auto services option</primary></indexterm> <literal>services</literal> option, which is also called <literal>preload </literal>, ensures that the specified shares are always visible in the browse list. One common use for this option is to advertise specific user or printer shares that are created by the <literal>[homes]</literal> or <literal>[printers]</literal> shares, but are not otherwise browsable.</para>
797
798
799 <para>This option works best with disk shares. If you wish to force each of your system printers (i.e., those listed in the printer capabilities file) into the browse list using this option, we recommend using the <literal>load</literal> <literal>printers</literal> option instead. Any shares listed with the <literal>auto</literal> <literal>services</literal> option will not be displayed if the <literal>browse</literal> <literal>list</literal> option is set to <literal>no</literal>.</para>
800 </sect3>
801
802
803
804 <sect3 role="" label="5.1.5.6" id="ch05-SECT-1.5.6">
805 <title>default service</title>
806
807
808 <para>The global <literal>default</literal>
809 <indexterm id="ch05-idx-970564-0"><primary>default services</primary><secondary>option for</secondary></indexterm> <literal>service</literal> option (sometimes called <literal>default</literal>) names a "last-ditch" share. If set to an existing share name, and a client requests a nonexistent disk or printer share, Samba will attempt to connect the user to the share specified by this option instead. The option is specified as follows:</para>
810
811
812 <programlisting>default service = helpshare</programlisting>
813
814
815 <para>Note that there are no braces surrounding the share name <literal>helpshare</literal>, even though the definition of the share later in the Samba configuration file will have braces. Also, if you use the <literal>%S</literal> variable in the share specified by this option, it will represent the requested, nonexistent share, not the default service. Any underscores (  <literal>_ </literal> ) specified in the request share will be converted to slashes (<literal>/</literal>) when the variable is used.</para>
816 </sect3>
817
818
819
820 <sect3 role="" label="5.1.5.7" id="ch05-SECT-1.5.7">
821 <indexterm id="ch05-idx-970565-0"><primary>local master option</primary></indexterm>
822 <title>
823 local master</title>
824
825
826 <para>
827 <indexterm id="ch05-idx-969675-0"><primary>local master browser</primary><secondary>option for</secondary></indexterm>This global option specifies whether Samba will attempt to become the local master browser for the subnet when it starts up. If this option is set to <literal>yes</literal>, Samba will take place in elections. However, setting this option by itself does not guarantee victory. (Other parameters, such as <literal>preferred</literal> <literal>master</literal> and <literal>os</literal> <literal>level</literal> help Samba win browsing elections.) If this option is set to <literal>no</literal>, Samba will lose all browsing elections, no matter which values are specified by the other configuration options. The default value is <literal>yes</literal>.</para>
828 </sect3>
829
830
831
832 <sect3 role="" label="5.1.5.8" id="ch05-SECT-1.5.8">
833 <title>lm announce</title>
834
835
836 <para>The global <literal>lm</literal>
837 <indexterm id="ch05-idx-970566-0"><primary>lm announce option</primary></indexterm> <literal>announce</literal> option tells Samba's <emphasis>nmbd</emphasis>
838 <indexterm id="ch05-idx-969678-0"><primary>nmbd daemon</primary><secondary>browsing options for</secondary></indexterm> whether or not to send LAN Manager host announcements on behalf of the server. These host announcements may be required by older clients, such as IBM's OS/2 operating system. This announcement allows the server to be added to the browse lists of the client. If activated, Samba will announce itself repetitively at the number of seconds specified by the <literal>lm</literal> <literal>interval</literal> option.</para>
839
840
841 <para>This configuration option takes the standard boolean values, <literal>yes</literal> and <literal>no</literal>, which engage or disengage LAN Manager announcements, respectively. In addition, there is a third option, <literal>auto</literal>, which causes <emphasis>nmbd</emphasis> to passively listen for LAN Manager announcements, but not send any of its own initially. If LAN Manager announcements are detected for another machine on the network, <emphasis>nmbd</emphasis> will start sending its own LAN Manager announcements to ensure that it is visible. You can specify the option as follows:</para>
842
843
844 <programlisting>[global]
845         lm announce = yes</programlisting>
846
847
848 <para>The default value is <literal>auto</literal>. You probably won't need to change this value from its default.</para>
849 </sect3>
850
851
852
853 <sect3 role="" label="5.1.5.9" id="ch05-SECT-1.5.9">
854 <indexterm id="ch05-idx-970567-0"><primary>lm interval option</primary></indexterm>
855 <title>
856 lm interval</title>
857
858
859 <para>This option, which is used in conjunction with <literal>lm</literal> <literal>announce</literal>, indicates the number of seconds <emphasis>nmbd</emphasis> will wait before repeatedly broadcasting LAN Manager-style announcements. Remember that LAN Manager announcements must be activated in order for this option to be used. The default value is 60 seconds. If you set this value to 0, Samba will not send any LAN Manager host announcements, no matter what the value of the <literal>lm</literal> <literal>announce</literal> option. You can reset the value of this option as follows:</para>
860
861
862 <programlisting>[global]
863         lm interval = 90</programlisting>
864 </sect3>
865
866
867
868 <sect3 role="" label="5.1.5.10" id="ch05-SECT-1.5.10">
869 <title>preferred master</title>
870
871
872 <para>The <literal>preferred</literal>
873 <indexterm id="ch05-idx-970568-0"><primary>preferred master option</primary></indexterm> <literal>master</literal> option requests that Samba set the preferred master bit when participating in an election. This gives the server a higher preferred status in the workgroup than other machines at the same operating system level. If you are configuring your Samba machine to become the local master browser, it is wise to set the following value:</para>
874
875
876 <programlisting>[global]
877         preferred master = yes</programlisting>
878
879
880 <para>Otherwise, you should leave it set to its default, <literal>no</literal>. If Samba is configured as a preferred master browser, it will force an election when it first comes online.</para>
881 </sect3>
882
883
884
885 <sect3 role="" label="5.1.5.11" id="ch05-SECT-1.5.11">
886 <title>os level</title>
887
888
889 <para>The global <literal>os</literal>
890 <indexterm id="ch05-idx-970569-0"><primary>os level option</primary></indexterm> <literal>level</literal> option dictates the operating system level at which Samba will masquerade during a browser election. If you wish to have Samba win an election and become the master browser, you can set the level above that of the operating system on your network with the highest current value. The values are shown in <link linkend="ch05-51423">Table 5.1</link> . The default level is 0, which means that Samba will lose all elections. If you wish Samba to win all elections, you can reset its value as follows:</para>
891
892
893 <programlisting>os level = 34</programlisting>
894
895
896 <para>This means that the server will vote for itself 34 times each time an election is called, which ensures a victory.</para>
897 </sect3>
898
899
900
901 <sect3 role="" label="5.1.5.12" id="ch05-SECT-1.5.12">
902 <indexterm id="ch05-idx-970570-0"><primary>domain master option</primary></indexterm>
903 <title>
904 domain master</title>
905
906
907 <para>If Samba is the primary domain controller for your workgroup or NT domain, it should also be the <indexterm id="ch05-idx-969682-0"><primary>DMB (domain master browser)</primary><secondary>option for</secondary></indexterm> domain master browser. The domain master browser is a special machine that has the NetBIOS resource type &lt;1B&gt; and is used to propagate browse lists to and from each of the local master browsers in individual subnets across the domain. To force Samba to become the domain master browser, set the following in the <literal>[global]</literal> section of the <filename>smb.conf</filename>:</para>
908
909
910 <programlisting>[global]
911         domain master = yes</programlisting>
912
913
914 <para>If you have a Windows NT server on the network acting as a primary domain controller (PDC), we recommend that you do not use Samba to become the domain master browser. The reverse is true as well: if Samba is taking on the responsibilities of a PDC, we recommend making it the domain master browser. Splitting the PDC and the domain master browser will cause unpredictable errors to occur on the network.</para>
915 </sect3>
916
917
918
919 <sect3 role="" label="5.1.5.13" id="ch05-SECT-1.5.13">
920 <title>remote browse sync</title>
921
922
923 <para>The global <literal>remote</literal>
924 <indexterm id="ch05-idx-970571-0"><primary>remote browse sync option</primary></indexterm> <literal>browse</literal> <literal>sync</literal> option specifies that Samba should synchronize its <indexterm id="ch05-idx-969683-0"><primary>browse lists</primary><secondary>options for</secondary></indexterm>browse lists with local master browsers in other subnets. However, the synchronization can occur only with other Samba servers, and not with Windows computers. For example, if your Samba server was a master browser on the subnet 192.168.235, and Samba local master browsers existed on other subnets at 192.168.234.92 and 192.168.236.2, you could specify the following:</para>
925
926
927 <programlisting>remote browse sync = 192.168.234.92 192.168.236.2</programlisting>
928
929
930 <para>The Samba server would then directly contact the other machines on the address list and synchronize browse lists. You can also say:</para>
931
932
933 <programlisting>remote browse sync = 192.168.234.255 192.168.236.255</programlisting>
934
935
936 <para>This forces Samba to broadcast queries to determine the IP addresses of the local master browser on each subnet, with which it will then synchronize browse lists. This only works, however, if your router doesn't block directed broadcast requests ending in 255.</para>
937 </sect3>
938
939
940
941 <sect3 role="" label="5.1.5.14" id="ch05-SECT-1.5.14">
942 <title>remote announce</title>
943
944
945 <para>Samba servers are capable of providing browse lists to foreign subnets with the <literal>remote</literal>
946 <indexterm id="ch05-idx-970572-0"><primary>remote announce option</primary></indexterm> <literal>announce</literal> option. This is typically sent to the local master browser of the foreign subnet in question. However, if you do not know the address of the local master browser, you can do the following:</para>
947
948
949 <programlisting>[global]
950     remote announce = 192.168.234.255/ACCOUNTING \
951                           192.168.236.255/ACCOUNTING</programlisting>
952
953
954 <para>With this, Samba will broadcast host announcements to all machines on subnets 192.168.234 and 192.168.236, which will hopefully reach the local master browser of the<indexterm id="ch05-idx-969669-0" class="endofrange" startref="ch05-idx-969668-0"/>
955 <indexterm id="ch05-idx-969669-1" class="endofrange" startref="ch05-idx-969668-1"/> subnet.<indexterm id="ch05-idx-969569-0" class="endofrange" startref="ch05-idx-969559-0"/> You can also specify exact IP addresses, if they are known.</para>
956 </sect3>
957 </sect2>
958 </sect1>
959
960
961
962
963
964
965
966
967
968 <sect1 role="" label="5.2" id="ch05-34221">
969 <title>Filesystem Differences</title>
970
971
972 <para>
973 <indexterm id="ch05-idx-969684-0" class="startofrange"><primary>filesystems</primary><secondary>differences between</secondary></indexterm>One <indexterm id="ch05-idx-969692-0"><primary>filesystems</primary><seealso>files</seealso></indexterm>of the biggest issues for which Samba has to correct is the difference between Unix and non-Unix filesystems. This includes items such as handling symbolic links, hidden files, and dot files. In addition, file permissions can also be a headache if not accounted for properly. This section describes how to use Samba to make up for some of those annoying differences, and even how to add some new functionality of its own.</para>
974
975
976 <sect2 role="" label="5.2.1" id="ch05-SECT-2.1">
977 <title>Hiding and Vetoing Files</title>
978
979
980 <para>
981 <indexterm id="ch05-idx-969693-0"><primary>files</primary><secondary>hidden</secondary></indexterm>
982 <indexterm id="ch05-idx-969693-1"><primary>hidden files</primary></indexterm>There are some cases when we need to ensure that a user cannot see or access a file at all. Other times, we don't want to keep a user from accessing a file&mdash;we just want to hide it when they view the contents of the directory. On Windows systems, an attribute of files allows them to be hidden from a folder listing. With Unix, the traditional way of hiding files in a directory is to precede them with a <indexterm id="ch05-idx-969701-0"><primary>dot (.) in hidden files</primary></indexterm>
983 <indexterm id="ch05-idx-969701-1"><primary>. (dot)</primary></indexterm>dot (.). This prevents items such as configuration files or defaults from being seen when performing an ordinary <literal>ls</literal> command. Keeping a user from accessing a file at all, however, involves working with permissions on files and or directories.</para>
984
985
986 <para>The first option we should discuss is the boolean <literal>hide</literal> <literal>dot</literal> <literal>files</literal>. This option does exactly what it says. When set to <literal>yes</literal>, the option treats files beginning with a <indexterm id="ch05-idx-969702-0"><primary>period (.)</primary></indexterm>
987 <indexterm id="ch05-idx-969702-1"><primary>. (period)</primary></indexterm>period (.) as hidden. If set to <literal>no</literal>, those files are always shown. The important thing to remember is that the files are only hidden. If the user has chosen to show all hidden files while browsing (e.g., using the Folder Options menu item under the View menu in Windows 98), they will still be able to see the files, as shown in <link linkend="ch05-77260">Figure 5.2</link>.</para>
988
989
990 <figure label="5.2" id="ch05-77260">
991 <title>Hidden files in the [data] share</title>
992
993 <graphic width="502" depth="210" fileref="figs/sam.0502.gif"></graphic>
994 </figure>
995
996 <para>Instead of simply hiding files beginning with a dot, you can also specify a string pattern to Samba for files to hide, using the <literal>hide</literal> <literal>files</literal> option. For example, let's assume that we specified the following in our example <literal>[data]</literal> share:</para>
997
998
999 <programlisting>[data]
1000         path = /home/samba/data
1001         browseable = yes
1002         guest ok = yes
1003         writeable = yes
1004         case sensitive = no
1005         hide files = /*.java/*README*/</programlisting>
1006
1007
1008 <para>Each entry for this option must begin, end, or be separated from another with a <indexterm id="ch05-idx-969703-0"><primary>slash (/)</primary><secondary>character</secondary></indexterm>
1009 <indexterm id="ch05-idx-969703-1"><primary>/ (slash character)</primary></indexterm>slash ( / ) character, even if there is only one pattern listed. This convention allows spaces to appear in filenames. In this example, the share directory would appear as shown in <link linkend="ch05-19743">Figure 5.3</link>. Again, note that we have set the Windows 98 option to view hidden files for the window.</para>
1010
1011
1012 <figure label="5.3" id="ch05-19743">
1013 <title>Hiding files based on filename patterns</title>
1014
1015 <graphic width="502" depth="210" fileref="figs/sam.0503.gif"></graphic>
1016 </figure>
1017
1018 <para>
1019 <indexterm id="ch05-idx-969704-0" class="startofrange"><primary>veto files</primary></indexterm>
1020 <indexterm id="ch05-idx-969704-1" class="startofrange"><primary>files</primary><secondary>veto</secondary></indexterm>If we want to prevent users from seeing files at all, we can instead use the <literal>veto</literal> <literal>files</literal> option. This option, which takes the same syntax as the <literal>hide</literal> <literal>files</literal> option, specifies a list of files that should never be seen by the user. For example, let's change the <literal>[data]</literal> share to the following:</para>
1021
1022
1023 <programlisting>[data]
1024         path = /home/samba/data
1025         browseable = yes
1026         guest ok = yes
1027         writeable = yes
1028         case sensitive = no
1029         veto files = /*.java/*README*/</programlisting>
1030
1031
1032 <para>The syntax of this option is identical to the <literal>hide</literal> <literal>files</literal> configuration option: each entry must begin, end, or be separated from another with a slash (<literal>/</literal>) character, even if there is only one pattern listed. By doing so, the files <literal>hello.java</literal> and <literal>README</literal> will simply disappear from the directory, and the user will not be able to access them through SMB.</para>
1033
1034
1035 <para>There is one other question that we need to address. What happens if the user tries to delete a directory that contains vetoed files? This is where the <literal>delete</literal>
1036 <indexterm id="ch05-idx-969711-0"><primary>files</primary><secondary>deleting, option for</secondary></indexterm> <literal>veto</literal> <literal>files</literal> option comes in. If this boolean option is set to <literal>yes</literal>, the user is allowed to delete both the regular files and the vetoed files in the directory, and the directory itself will be removed. If the option is set to <literal>no</literal>, the user will not be able to delete the vetoed files, and consequently the directory will not be deleted either. From the user's perspective, the directory will appear to be empty, but cannot be removed.</para>
1037
1038
1039 <para>The <literal>dont</literal> <literal>descend</literal> directive specifies a list of <indexterm id="ch05-idx-969715-0"><primary>directories</primary><secondary>barring users from viewing contents</secondary></indexterm>directories whose contents Samba should not allow to be visible. Note that we say <emphasis>contents</emphasis>, not the directory itself. Users will be able to enter a directory marked as such, but they are prohibited from descending the directory tree any farther&mdash;they will always see an empty folder. For example, let's use this option with a more basic form of the share that we defined earlier in the chapter:</para>
1040
1041
1042 <programlisting>[data]
1043         path = /home/samba/data
1044         browseable = yes
1045         guest ok = yes
1046         writeable = yes
1047         case sensitive = no
1048         dont descend = config defaults</programlisting>
1049
1050
1051 <para>In addition, let's assume that the <filename>/home/samba/data</filename> directory has the following contents:</para>
1052
1053
1054 <programlisting>drwxr-xr-x   6 tom      users     1024 Jun 13 09:24 .
1055 drwxr-xr-x   8 root     root      1024 Jun 10 17:53 ..
1056 -rw-r--r--   2 tom      users     1024 Jun  9 11:43 README
1057 drwxr-xr-x   3 tom      users     1024 Jun 13 09:28 config
1058 drwxr-xr-x   3 tom      users     1024 Jun 13 09:28 defaults
1059 drwxr-xr-x   3 tom      users     1024 Jun 13 09:28 market</programlisting>
1060
1061
1062 <para>If the user then connects to the share, he or she would see the directories shown in <link linkend="ch05-62659">Figure 5.4</link>. However, the contents of the <filename>/config</filename> and <filename>/defaults</filename> directories would appear empty to the user, even if other folders or files existed in them. In addition, users cannot write any data to the folder (which prevents them from creating a file or folder with the same name as one that is already there but invisible). If a user attempts to do so, he or she will receive an "Access Denied" message. <literal>dont</literal> <literal>descend</literal> is an administrative option, not a security option, and is not a substitute for good file permissions.</para>
1063
1064
1065 <figure label="5.4" id="ch05-62659">
1066 <indexterm id="ch05-idx-969696-0" class="endofrange" startref="ch05-idx-969684-0"/><indexterm id="ch05-idx-969696-1" class="endofrange" startref="ch05-idx-969704-0"/><indexterm id="ch05-idx-969696-2" class="endofrange" startref="ch05-idx-969704-1"/><title>Contents of the [data] share with dont descend
1067
1068  </title>
1069
1070 <graphic width="502" depth="210" fileref="figs/sam.0504.gif"></graphic>
1071 </figure>
1072 </sect2>
1073
1074
1075
1076
1077
1078 <sect2 role="" label="5.2.2" id="ch05-SECT-2.2">
1079 <title>Links</title>
1080
1081
1082 <para>
1083 <indexterm id="ch05-idx-969716-0"><primary>links</primary></indexterm>
1084 <indexterm id="ch05-idx-969716-1"><primary>filesystems</primary><secondary>links and</secondary></indexterm>DOS and NT filesystems don't have symbolic links; Windows 95/98/NT systems approximate this with "shortcuts" instead. Therefore, when a client tries to open a symbolic link on a Samba server share, Samba attempts to follow the link to find the real file and let the client open it, as if he or she were on a Unix machine. If you don't want to allow this, set the <literal>follow</literal> <literal>symlinks</literal> option:</para>
1085
1086
1087 <programlisting>[data]
1088         path = /home/samba/data
1089         browseable = yes
1090         guest ok = yes
1091         writeable = yes
1092         case sensitive = no
1093         follow symlinks = no</programlisting>
1094
1095
1096 <para>You can test this by creating a directory on the Unix server inside the share as the user that you are logging in with. Enter the following commands:</para>
1097
1098
1099 <programlisting>% <userinput>mkdir hello; cd hello</userinput>
1100 % <userinput>cat "This is a test" &gt;hello.txt</userinput>
1101 % <userinput>ln -s hello.txt "Link to hello"</userinput></programlisting>
1102
1103
1104 <para>This results in the two files shown in the window in <link linkend="ch05-36377">Figure 5.5</link>. Normally, if you click on either one, you will receive a file which has the text "This is a test" inside of it. However, with the <literal>follow</literal> <literal>symlinks</literal> option set to <literal>no</literal>, you should receive an error similar to the dialog in <link linkend="ch05-36377">Figure 5.5</link> if you click on "Link to hello."</para>
1105
1106
1107 <figure label="5.5" id="ch05-36377">
1108 <title>An error dialog trying to follow symbolic links when forbidden by Samba</title>
1109
1110 <graphic width="502" depth="149" fileref="figs/sam.0505.gif"></graphic>
1111 </figure>
1112
1113 <para>Finally, let's discuss the <literal>wide</literal> <literal>links</literal> option. This option, if set to <literal>yes</literal>, allows the client user to follow symbolic links that point outside the shared directory tree, including files or directories at the other end of the link. For example, let's assume that we modified the <literal>[data]</literal> share as follows:</para>
1114
1115
1116 <programlisting>[data]
1117         path = /home/samba/data
1118         browseable = yes
1119         guest ok = yes
1120         writeable = yes
1121         case sensitive = no
1122         follow symlinks = yes
1123         wide links = yes</programlisting>
1124
1125
1126 <para>As long as the <literal>follow</literal> <literal>symlinks</literal> option is enabled, this will cause Samba to follow all symbolic links outside the current share tree. If we create a file outside the share (for example, in someone's home directory) and then create a link to it in the share as follows:</para>
1127
1128
1129 <programlisting>ln -s ~tom/datafile ./datafile</programlisting>
1130
1131
1132 <para>then you will be able to open the file in Tom's directory as per the target file's permissions.</para>
1133 </sect2>
1134
1135
1136
1137
1138
1139 <sect2 role="" label="5.2.3" id="ch05-SECT-2.3">
1140 <title>Filesystem Options</title>
1141
1142
1143 <para>
1144 <indexterm id="ch05-idx-969717-0" class="startofrange"><primary>filesystems</primary><secondary>options for</secondary></indexterm><link linkend="ch05-48353">Table 5.4</link> shows a breakdown of the options we discussed earlier. We recommend the defaults for most, except those listed in the following descriptions.</para>
1145
1146
1147 <table label="5.4" id="ch05-48353">
1148 <title>Filesystem Configuration Options </title>
1149
1150 <tgroup cols="5">
1151 <colspec colnum="1" colname="col1"/>
1152 <colspec colnum="2" colname="col2"/>
1153 <colspec colnum="3" colname="col3"/>
1154 <colspec colnum="4" colname="col4"/>
1155 <colspec colnum="5" colname="col5"/>
1156 <thead>
1157 <row>
1158
1159 <entry colname="col1"><para>Option</para></entry>
1160
1161 <entry colname="col2"><para>Parameters</para></entry>
1162
1163 <entry colname="col3"><para>Function</para></entry>
1164
1165 <entry colname="col4"><para>Default</para></entry>
1166
1167 <entry colname="col5"><para>Scope</para></entry>
1168
1169 </row>
1170
1171 </thead>
1172
1173 <tbody>
1174 <row>
1175
1176 <entry colname="col1"><para><literal>unix realname</literal></para></entry>
1177
1178 <entry colname="col2"><para>boolean</para></entry>
1179
1180 <entry colname="col3"><para>Provides Unix user's full name to client.</para></entry>
1181
1182 <entry colname="col4"><para><literal>no</literal></para></entry>
1183
1184 <entry colname="col5"><para>Global</para></entry>
1185
1186 </row>
1187
1188 <row>
1189
1190 <entry colname="col1"><para><literal>dont descend</literal></para></entry>
1191
1192 <entry colname="col2"><para>string (list of directories)</para></entry>
1193
1194 <entry colname="col3"><para>Indicates a list of directories whose contents Samba should make invisible to clients.</para></entry>
1195
1196 <entry colname="col4"><para>None</para></entry>
1197
1198 <entry colname="col5"><para>Share</para></entry>
1199
1200 </row>
1201
1202 <row>
1203
1204 <entry colname="col1"><para><literal>follow symlinks</literal></para></entry>
1205
1206 <entry colname="col2"><para>boolean</para></entry>
1207
1208 <entry colname="col3"><para>If set to <literal>no</literal>, Samba will not honor symbolic links.</para></entry>
1209
1210 <entry colname="col4"><para><literal>yes</literal></para></entry>
1211
1212 <entry colname="col5"><para>Share</para></entry>
1213
1214 </row>
1215
1216 <row>
1217
1218 <entry colname="col1"><para><literal>getwd cache</literal></para></entry>
1219
1220 <entry colname="col2"><para>boolean</para></entry>
1221
1222 <entry colname="col3"><para>If set to <literal>yes</literal>, Samba will use a cache for <literal>getwd( )</literal> calls.</para></entry>
1223
1224 <entry colname="col4"><para><literal>yes</literal></para></entry>
1225
1226 <entry colname="col5"><para>Global</para></entry>
1227
1228 </row>
1229
1230 <row>
1231
1232 <entry colname="col1"><para><literal>wide links</literal></para></entry>
1233
1234 <entry colname="col2"><para>boolean</para></entry>
1235
1236 <entry colname="col3"><para>If set to <literal>yes</literal>, Samba will follow symbolic links outside the share.</para></entry>
1237
1238 <entry colname="col4"><para><literal>yes</literal></para></entry>
1239
1240 <entry colname="col5"><para>Share</para></entry>
1241
1242 </row>
1243
1244 <row>
1245
1246 <entry colname="col1"><para><literal>hide dot files</literal></para></entry>
1247
1248 <entry colname="col2"><para>boolean</para></entry>
1249
1250 <entry colname="col3"><para>If set to <literal>yes</literal>, treats Unix hidden files as hidden files in Windows.</para></entry>
1251
1252 <entry colname="col4"><para><literal>yes</literal></para></entry>
1253
1254 <entry colname="col5"><para>Share</para></entry>
1255
1256 </row>
1257
1258 <row>
1259
1260 <entry colname="col1"><para><literal>hide files</literal></para></entry>
1261
1262 <entry colname="col2"><para>string (list of files)</para></entry>
1263
1264 <entry colname="col3"><para>List of file patterns to treat as hidden.</para></entry>
1265
1266 <entry colname="col4"><para>None</para></entry>
1267
1268 <entry colname="col5"><para>Share</para></entry>
1269
1270 </row>
1271
1272 <row>
1273
1274 <entry colname="col1"><para><literal>veto files</literal></para></entry>
1275
1276 <entry colname="col2"><para>string (list of files)</para></entry>
1277
1278 <entry colname="col3"><para>List of file patterns to never show.</para></entry>
1279
1280 <entry colname="col4"><para>None</para></entry>
1281
1282 <entry colname="col5"><para>Share</para></entry>
1283
1284 </row>
1285
1286 <row>
1287
1288 <entry colname="col1"><para><literal>delete veto files</literal></para></entry>
1289
1290 <entry colname="col2"><para>boolean</para></entry>
1291
1292 <entry colname="col3"><para>If set to <literal>yes</literal>, will delete files matched by <literal>veto files</literal> when the directory they reside in is deleted.</para></entry>
1293
1294 <entry colname="col4"><para><literal>no</literal></para></entry>
1295
1296 <entry colname="col5"><para>Share</para></entry>
1297
1298 </row>
1299
1300 </tbody>
1301 </tgroup>
1302 </table>
1303
1304
1305 <sect3 role="" label="5.2.3.1" id="ch05-SECT-2.3.1">
1306 <indexterm id="ch05-idx-970574-0"><primary>unix realname option</primary></indexterm>
1307 <title>
1308 unix realname</title>
1309
1310
1311 <para>Some programs require a full username in order to operate. For example, a Windows email program often needs to associate a username with a given real name. If your system password file contains the real names of users in the GCOS field, the <literal>unix</literal> <literal>realname</literal> option instructs Samba to provide this information to clients. Without it, the name of the user will simply be his or her login ID. For example, if your Unix password file contains the following line:</para>
1312
1313
1314 <programlisting>rcollins:/KaBfco47Rer5:500:500:Robert Collins:
1315 /home/rcollins:/bin/ksh</programlisting>
1316
1317
1318 <para>And the option in the configuration file is:</para>
1319
1320
1321 <programlisting>[global]
1322         unix realname = yes</programlisting>
1323
1324
1325 <para>then the name Robert Collins will be provided to any client that requests the real name of user <literal>rcollins</literal>. You typically don't need to bother with this option.</para>
1326 </sect3>
1327
1328
1329
1330 <sect3 role="" label="5.2.3.2" id="ch05-SECT-2.3.2">
1331 <title>dont descend</title>
1332
1333
1334 <para>The <literal>dont</literal>
1335 <indexterm id="ch05-idx-970575-0"><primary>dont descend option</primary></indexterm> <literal>descend</literal> option can be used to specify various <indexterm id="ch05-idx-969728-0"><primary>directories</primary><secondary>barring users from viewing contents</secondary></indexterm>directories that should appear empty to the client. Note that the directory itself will still appear. However, Samba will not show any of the contents of the directory to the client user. This is not a good option to use as a security feature (a user could probably find a way around it); it really is meant only as a convenience to keep client users from browsing into directories that might have sensitive files. See our example earlier in this section.</para>
1336 </sect3>
1337
1338
1339
1340 <sect3 role="" label="5.2.3.3" id="ch05-SECT-2.3.3">
1341 <indexterm id="ch05-idx-970576-0"><primary>follow symlinks option</primary></indexterm>
1342 <title>
1343 follow symlinks</title>
1344
1345
1346 <para>
1347 <indexterm id="ch05-idx-969732-0"><primary>links</primary><secondary>option for</secondary></indexterm>This option, which is discussed in greater detail earlier, controls whether Samba will follow a symbolic link in the Unix operating system to the target, or if it should return an error to the client user. If the option is set to <literal>yes</literal>, the target of the link will be interpreted as the file.</para>
1348 </sect3>
1349
1350
1351
1352 <sect3 role="" label="5.2.3.4" id="ch05-SECT-2.3.4">
1353 <indexterm id="ch05-idx-970577-0"><primary>getwd cache option</primary></indexterm>
1354 <title>
1355 getwd cache</title>
1356
1357
1358 <para>This global option specifies whether Samba should use a local cache for the Unix <literal>getwd()</literal> ( get current working directory) system call. You can override the default value of <literal>yes</literal> as follows:</para>
1359
1360
1361 <programlisting>[global]
1362         getwd cache = no</programlisting>
1363
1364
1365 <para>Setting this option to <literal>yes</literal> can significantly increase the time it takes to resolve the <indexterm id="ch05-idx-969733-0"><primary>working directory, option for</primary></indexterm>
1366 <indexterm id="ch05-idx-969733-1"><primary>directories</primary><secondary>working, option for</secondary></indexterm>working directory, especially if the <literal>wide</literal> <literal>links</literal> option is set to <literal>no</literal>. You should normally not need to alter this option.</para>
1367 </sect3>
1368
1369
1370
1371 <sect3 role="" label="5.2.3.5" id="ch05-SECT-2.3.5">
1372 <indexterm id="ch05-idx-970578-0"><primary>wide links option</primary></indexterm>
1373 <title>
1374 wide links</title>
1375
1376
1377 <para>This option specifies whether the client user can follow symbolic links that point outside the shared directory tree. This includes any files or directories at the other end of the link, as long as the permissions are correct for the user. The default value for this option is <literal>yes</literal>. Note that this option will not be honored if the <literal>follow</literal> <literal>symlinks</literal> options is set to <literal>no</literal>. Setting this option to <literal>no</literal> slows <emphasis>smbd</emphasis> considerably.</para>
1378 </sect3>
1379
1380
1381
1382 <sect3 role="" label="5.2.3.6" id="ch05-SECT-2.3.6">
1383 <title>hide files</title>
1384
1385
1386 <para>
1387 <indexterm id="ch05-idx-969738-0"><primary>files</primary><secondary>hidden</secondary><tertiary>options for</tertiary></indexterm>
1388 <indexterm id="ch05-idx-969738-1"><primary>hidden files</primary><secondary>options for</secondary></indexterm>The <literal>hide</literal> <literal>files</literal> option provides one or more directory or filename patterns to Samba. Any file matching this pattern will be treated as a hidden file from the perspective of the client. Note that this simply means that the DOS hidden attribute is set, which may or may not mean that the user can actually see it while browsing.</para>
1389
1390
1391 <para>Each entry in the list must begin, end, or be separated from another entry with a <indexterm id="ch05-idx-969734-0"><primary>slash (/)</primary><secondary>character</secondary></indexterm>
1392 <indexterm id="ch05-idx-969734-1"><primary>/ (slash character)</primary></indexterm>slash (<literal>/</literal>) character, even if there is only one pattern listed. This allows spaces to appear in the list. Asterisks can be used as a wildcard to represent zero or more characters. Questions marks can be used to represent exactly one character. For example:</para>
1393
1394
1395 <programlisting>hide files = /.jav*/README.???/</programlisting>
1396 </sect3>
1397
1398
1399
1400 <sect3 role="" label="5.2.3.7" id="ch05-SECT-2.3.7">
1401 <title>hide dot files</title>
1402
1403
1404 <para>The <literal>hide</literal> <literal>dot</literal> <literal>files</literal> option hides any files on the server that begin with a <indexterm id="ch05-idx-969735-0"><primary>dot (.) in hidden files</primary></indexterm>
1405 <indexterm id="ch05-idx-969735-1"><primary>. (dot)</primary></indexterm>dot (.) character, in order to mimic the functionality behind several shell commands that are present on Unix systems. Like <literal>hide</literal> <literal>files</literal>, those files that begin with a dot have the DOS hidden attribute set, which doesn't necessarily guarantee that a client cannot view them. The default value for this option is <literal>yes</literal>.</para>
1406 </sect3>
1407
1408
1409
1410 <sect3 role="" label="5.2.3.8" id="ch05-SECT-2.3.8">
1411 <indexterm id="ch05-idx-970581-0"><primary>veto files option</primary></indexterm>
1412 <title>
1413 veto files</title>
1414
1415
1416 <para>More stringent than the hidden files state is the state provided by the <literal>veto</literal> <literal>files</literal> configuration option. Samba won't even admit these files exist. You cannot list or open them from the client. In reality, this isn't a trustworthy security option. It is actually a mechanism to keep PC programs from deleting special files, such as ones used to store the resource fork of a Macintosh file on a Unix filesystem. If both Windows and Macs are sharing the same files, this can prevent ill-advised power users from removing files the Mac users need.</para>
1417
1418
1419 <para>The syntax of this option is identical to that of the <literal>hide</literal> <literal>files</literal> configuration option: each entry must begin, end, or be separated from another with a <indexterm id="ch05-idx-969758-0"><primary>slash (/)</primary><secondary>character</secondary></indexterm>
1420 <indexterm id="ch05-idx-969758-1"><primary>/ (slash character)</primary></indexterm>slash ( / ) character, even if only one pattern is listed. Asterisks can be used as a wildcard to represent zero or more characters. <indexterm id="ch05-idx-969762-0"><primary>question mark (?)</primary></indexterm>
1421 <indexterm id="ch05-idx-969762-1"><primary>? (question mark)</primary></indexterm>Questions marks can be used to represent exactly one character. For example:</para>
1422
1423
1424 <programlisting>veto files = /*config/*default?/</programlisting>
1425
1426
1427 <para>This option is primarily administrative&mdash;not a substitute for good file permissions.</para>
1428 </sect3>
1429
1430
1431
1432 <sect3 role="" label="5.2.3.9" id="ch05-SECT-2.3.9">
1433 <indexterm id="ch05-idx-970582-0"><primary>delete veto files option</primary></indexterm>
1434 <title>
1435 delete veto files</title>
1436
1437
1438 <para>
1439 <indexterm id="ch05-idx-969768-0"><primary>veto files</primary><secondary>option for deleting</secondary></indexterm>
1440 <indexterm id="ch05-idx-969768-1"><primary>files</primary><secondary>veto</secondary><tertiary>option for deleting</tertiary></indexterm>This option tells Samba to delete vetoed files when a user attempts to delete the directory in which they reside. The default value is <literal>no</literal>. This means if a user tries to delete a directory that contains a vetoed file, the file (and the directory) will not be deleted. Instead, the directory will remain and appear to be empty from the perspective of the user. If set to <literal>yes</literal>, the directory and the vetoed files will be<indexterm id="ch05-idx-969721-0" class="endofrange" startref="ch05-idx-969717-0"/> deleted.</para>
1441 </sect3>
1442 </sect2>
1443 </sect1>
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453 <sect1 role="" label="5.3" id="ch05-34062">
1454 <title>File Permissions and Attributes on MS-DOS and Unix</title>
1455
1456
1457 <para>
1458 <indexterm id="ch05-idx-969769-0" class="startofrange"><primary>files</primary><secondary>permissions</secondary></indexterm>
1459 <indexterm id="ch05-idx-969769-1" class="startofrange"><primary>files</primary><secondary>attributes</secondary></indexterm>
1460 <indexterm id="ch05-idx-969769-2" class="startofrange"><primary>DOS file permissions and attributes</primary></indexterm>
1461 <indexterm id="ch05-idx-969769-3" class="startofrange"><primary>Unix</primary><secondary>file permissions and attributes</secondary></indexterm>DOS was never intended to be a multiuser, networked operating system. Unix, on the other hand, was designed that way from the start. Consequently, there are inconsistencies and gaps in coverage between the two filesystems that Samba must not only be aware of, but also provide solutions for. One of the biggest gaps is how Unix and DOS handle permissions with files.</para>
1462
1463
1464 <para>Let's take a look at how Unix assigns permissions. All Unix files have read, write, and execute bits for three classifications of users: <indexterm id="ch05-idx-969803-0"><primary>Unix</primary><secondary>user classifications</secondary></indexterm>owner, group, and world. These permissions can be seen at the extreme left-hand side when a <literal>ls</literal> <literal>-al</literal> command is issued in a Unix directory. For example:</para>
1465
1466
1467 <programlisting>-rwxr--r--   1 tom     users   2014 Apr 13 14:11 access.conf</programlisting>
1468
1469
1470 <para>Windows, on the other hand, has four principal bits that it uses with any file: read-only, system, hidden, and archive. You can view these bits by right-clicking on the file and choosing the Properties menu item. You should see a dialog similar to <link linkend="ch05-76568">Figure 5.6</link>.<footnote label="1" id="ch05-pgfId-964268">
1471
1472
1473 <para>The system checkbox will probably be greyed for your file. Don't worry about that&mdash;you should still be able to see when the box is checked and when it isn't.</para>
1474
1475
1476 </footnote></para>
1477
1478
1479 <figure label="5.6" id="ch05-76568">
1480 <title>DOS and Windows file properties</title>
1481
1482 <graphic width="502" depth="435" fileref="figs/sam.0506.gif"></graphic>
1483 </figure>
1484
1485 <para>The definition of each of those bits follows:</para>
1486
1487
1488 <variablelist>
1489 <varlistentry><term>
1490 <indexterm id="ch05-idx-969799-0"><primary>read-only files</primary></indexterm>
1491 <indexterm id="ch05-idx-969799-1"><primary>files</primary><secondary>read-only</secondary></indexterm>Read-only</term>
1492 <listitem><para>The file's contents can be read by a user but cannot be written to.</para></listitem>
1493 </varlistentry>
1494
1495
1496 <varlistentry><term>
1497 <indexterm id="ch05-idx-969800-0"><primary>system files</primary></indexterm>
1498 <indexterm id="ch05-idx-969800-1"><primary>files</primary><secondary>system</secondary></indexterm>System</term>
1499 <listitem><para>This file has a specific purpose required by the operating system.</para></listitem>
1500 </varlistentry>
1501
1502
1503 <varlistentry><term>
1504 <indexterm id="ch05-idx-969801-0"><primary>hidden files</primary></indexterm>
1505 <indexterm id="ch05-idx-969801-1"><primary>files</primary><secondary>hidden</secondary></indexterm>Hidden</term>
1506 <listitem><para>This file has been marked to be invisible to the user, unless the operating systems is explicitly set to show it.</para></listitem>
1507 </varlistentry>
1508
1509
1510 <varlistentry><term>
1511 <indexterm id="ch05-idx-969802-0"><primary>archive files</primary></indexterm>
1512 <indexterm id="ch05-idx-969802-1"><primary>files</primary><secondary>archive</secondary></indexterm>Archive</term>
1513 <listitem><para>This file has been touched since the last DOS backup was performed on it.</para></listitem>
1514 </varlistentry>
1515 </variablelist>
1516
1517
1518 <para>Note that there is no bit to specify that a file is executable. DOS and Windows NT filesystems identify executable files by giving them the extensions .EXE, .COM, .CMD, or .BAT.</para>
1519
1520
1521 <para>Consequently, there is no use for any of the three Unix executable bits that are present on a file in a Samba disk share. DOS files, however, have their own attributes that need to be preserved when they are stored in a Unix environment: the archive, system, and hidden bits. Samba can preserve these bits by reusing the executable permission bits of the file on the Unix side&mdash;if it is instructed to do so. Mapping these bits, however, has an unfortunate side-effect: if a Windows user stores a file in a Samba share, and you view it on Unix with the <literal>ls</literal> <literal>-al</literal> command, some of the executable bits won't mean what you'd expect them to.</para>
1522
1523
1524 <para>Three Samba options decide whether the bits are mapped: <literal>map</literal> <literal>archive</literal>, <literal>map</literal> <literal>system </literal>, and <literal>map</literal> <literal>hidden</literal>. These options map the archive, system, and hidden attributes to the owner, group, and world execute bits of the file, respectively. You can add these options to the <literal>[data]</literal> share, setting each of their values as follows:</para>
1525
1526
1527 <programlisting>[data]
1528         path = /home/samba/data
1529         browseable = yes
1530         guest ok = yes
1531         writeable = yes
1532         map archive = yes
1533         map system = yes
1534         map hidden = yes</programlisting>
1535
1536
1537 <para>After that, try creating a file in the share under Unix&mdash;such as <literal>hello.java</literal>&mdash;and change the permissions of the file to 755. With these Samba options set, you should be able to check the permissions on the Windows side and see that each of the three values has been checked in the Properties dialog box. What about the read-only attribute? By default, Samba 2.0 sets this whenever a file does not have the Unix owner write permission bit set. In other words, you can set this bit by changing the permissions of the file to 555.</para>
1538
1539
1540 <para>We should warn you that the default value of the <literal>map</literal> <literal>archive</literal> option is <literal>yes</literal>, while the other two options have a default value of <literal>no</literal>. This is because many programs do not work properly if the archive bit is not stored correctly for DOS and Windows files. The system and hidden attributes, however, are not critical for a program's operation and are left to the discretion of the administrator.</para>
1541
1542
1543 <para><link linkend="ch05-56404">Figure 5.7</link> summarizes the Unix permission bits and illustrates how Samba maps those bits to DOS attributes. Note that the group read/write and world read/write bits do not directly translate to a DOS attribute, but they still retain their original Unix definitions on the Samba server.</para>
1544
1545
1546 <figure label="5.7" id="ch05-56404">
1547 <title>How Samba and Unix view the permissions of a file</title>
1548
1549 <graphic width="502" depth="211" fileref="figs/sam.0507.gif"></graphic>
1550 </figure>
1551
1552 <sect2 role="" label="5.3.1" id="ch05-SECT-3.0.1">
1553 <title>Creation masks</title>
1554
1555
1556 <para>Samba has several options to help with file <indexterm id="ch05-idx-969796-0"><primary>creation masks</primary></indexterm>
1557 <indexterm id="ch05-idx-969796-1"><primary>file creation masks</primary></indexterm>
1558 <indexterm id="ch05-idx-969796-2"><primary>masks</primary><secondary>creation</secondary></indexterm>
1559 <indexterm id="ch05-idx-969796-3"><primary>masks</primary><secondary>umasks</secondary></indexterm>creation masks. File creation masks (or <firstterm>umasks</firstterm>
1560 <indexterm id="ch05-idx-969797-0"><primary>umasks</primary></indexterm>) help to define the permissions a file or directory will receive at the time it is created. In Unix, this means that you can control what permissions a file or directory does not have when it is created. For files accessed from Windows, this means you can disable the read-only, archive, system, and hidden attributes of a file as well.</para>
1561
1562
1563 <para>For example, the <literal>create</literal> <literal>mask</literal> option will force the permissions of a file created by a Windows client to be at most 744:</para>
1564
1565
1566 <programlisting>[data]
1567         path = /home/samba/data
1568         browseable = yes
1569         guest ok = yes
1570         writeable = yes
1571         create mask = 744</programlisting>
1572
1573
1574 <para>while the <literal>directory</literal>
1575 <indexterm id="ch05-idx-970586-0"><primary>directory mask option</primary></indexterm> <literal>mask</literal> option shown here will force the permissions of a newly created directory to be at most 755:</para>
1576
1577
1578 <programlisting>[data]
1579         path = /home/samba/data
1580         browseable = yes
1581         guest ok = yes
1582         writeable = yes
1583         directory mask = 755</programlisting>
1584
1585
1586 <para>Alternatively, you can also force various bits with the <literal>force</literal> <literal>create</literal> <literal>mode</literal> and <literal>force</literal> <literal>directory</literal> <literal>mode</literal> options. These options will perform a logical OR against the file and directory creation masks, ensuring that those bits that are specified will always be set. You would typically set these options globally in order to ensure that group and world read/write permissions have been set appropriately for new files or directories in each share.</para>
1587
1588
1589 <para>In the same spirit, if you wish to explicitly set the Unix user and group attributes of a file that is created on the Windows side, you can use the <literal>force</literal>
1590 <indexterm id="ch05-idx-970587-0"><primary>force user option</primary></indexterm>
1591 <indexterm id="ch05-idx-970587-1"><primary>force group option</primary></indexterm> <literal>user</literal> and <literal>force</literal> <literal>group</literal> options. For example:</para>
1592
1593
1594 <programlisting>[data]
1595         path = /home/samba/data
1596         browseable = yes
1597         guest ok = yes
1598         writeable = yes
1599
1600         create mask = 744
1601         directory mask = 755
1602         force user = joe
1603         force group = accounting</programlisting>
1604
1605
1606 <para>These options actually assign a static Unix user and group to each connection that is made to a share. However, this occurs <emphasis>after</emphasis> the client authenticates; it does not allow free access to a share. These options are frequently used for their side effects of assigning a specific user and group to each new file or directory that is created in a share. Use these options with discretion.</para>
1607
1608
1609 <para>Finally, one of the capabilities of Unix that DOS lacks is the ability to delete a read-only file from a writable directory. In Unix, if a directory is writable, a read-only file in that directory can still be removed. This could permit you to delete files in any of your directories, even if the file was left by someone else.</para>
1610
1611
1612 <para>DOS filesystems are not designed for multiple users, and so its designers decided that <indexterm id="ch05-idx-969808-0"><primary>read-only files</primary><secondary>deleting</secondary></indexterm>
1613 <indexterm id="ch05-idx-969808-1"><primary>files</primary><secondary>read-only</secondary><tertiary>deleting</tertiary></indexterm>read-only means "protected against accidental change, including deletion," rather than "protected against some other user on a single-user machine." So the designers of DOS prohibited removal of a read-only file. Even today, Windows file systems exhibit the same behavior.</para>
1614
1615
1616 <para>Normally, this is harmless. Windows programs don't try to remove read-only files because they know it's a bad idea. However, a number of source-code control programs&mdash;which were first written for Unix&mdash;run on Windows and require the ability to delete read-only files. Samba permits this behavior with the <literal>delete</literal>
1617 <indexterm id="ch05-idx-970588-0"><primary>delete readonly option</primary></indexterm> <literal>readonly</literal> option. In order to enable this functionality, set the option to <literal>yes</literal>:</para>
1618
1619
1620 <programlisting>[data]
1621         path = /home/samba/data
1622         browseable = yes
1623         guest ok = yes
1624         writeable = yes
1625
1626         create mask = 744
1627         directory mask = 755
1628         force user = joe
1629         force group = accounting
1630         delete readonly = yes</programlisting>
1631 </sect2>
1632
1633
1634
1635
1636 <sect2 role="" label="5.3.2" id="ch05-SECT-3.1">
1637 <title>File and Directory Permission Options</title>
1638
1639
1640 <para>
1641 <indexterm id="ch05-idx-969813-0" class="startofrange"><primary>files</primary><secondary>permissions</secondary><tertiary>options for</tertiary></indexterm>
1642 <indexterm id="ch05-idx-969813-1" class="startofrange"><primary>directories</primary><secondary>permissions, options for</secondary></indexterm>
1643 <indexterm id="ch05-idx-969813-2" class="startofrange"><primary>permissions</primary><secondary>options for</secondary></indexterm>The options for file and directory permissions are summarized in <link linkend="ch05-96508">Table 5.5</link>; each option is then described in detail.</para>
1644
1645
1646 <table label="5.5" id="ch05-96508">
1647 <title>File and Directory Permission Options </title>
1648
1649 <tgroup cols="5">
1650 <colspec colnum="1" colname="col1"/>
1651 <colspec colnum="2" colname="col2"/>
1652 <colspec colnum="3" colname="col3"/>
1653 <colspec colnum="4" colname="col4"/>
1654 <colspec colnum="5" colname="col5"/>
1655 <thead>
1656 <row>
1657
1658 <entry colname="col1"><para>Option</para></entry>
1659
1660 <entry colname="col2"><para>Parameters</para></entry>
1661
1662 <entry colname="col3"><para>Function</para></entry>
1663
1664 <entry colname="col4"><para>Default</para></entry>
1665
1666 <entry colname="col5"><para>Scope</para></entry>
1667
1668 </row>
1669
1670 </thead>
1671
1672 <tbody>
1673 <row>
1674
1675 <entry colname="col1"><para><literal>map archive</literal></para></entry>
1676
1677 <entry colname="col2"><para>boolean</para></entry>
1678
1679 <entry colname="col3"><para>Preserve DOS archive attribute in user execute bit (0100).</para></entry>
1680
1681 <entry colname="col4"><para><literal>yes</literal></para></entry>
1682
1683 <entry colname="col5"><para>Share</para></entry>
1684
1685 </row>
1686
1687 <row>
1688
1689 <entry colname="col1"><para><literal>map system</literal></para></entry>
1690
1691 <entry colname="col2"><para>boolean</para></entry>
1692
1693 <entry colname="col3"><para>Preserve DOS system attribute in group execute bit (0010).</para></entry>
1694
1695 <entry colname="col4"><para><literal>no</literal></para></entry>
1696
1697 <entry colname="col5"><para>Share</para></entry>
1698
1699 </row>
1700
1701 <row>
1702
1703 <entry colname="col1"><para><literal>map hidden</literal></para></entry>
1704
1705 <entry colname="col2"><para>boolean</para></entry>
1706
1707 <entry colname="col3"><para>Preserve DOS hidden attribute in world execute bit (0001).</para></entry>
1708
1709 <entry colname="col4"><para><literal>no</literal></para></entry>
1710
1711 <entry colname="col5"><para>Share</para></entry>
1712
1713 </row>
1714
1715 <row>
1716
1717 <entry colname="col1"><para><literal>create mask (create mode)</literal></para></entry>
1718
1719 <entry colname="col2"><para>numeric</para></entry>
1720
1721 <entry colname="col3"><para>Sets the maximum permissions for files created by Samba.</para></entry>
1722
1723 <entry colname="col4"><para><literal>0744</literal></para></entry>
1724
1725 <entry colname="col5"><para>Share</para></entry>
1726
1727 </row>
1728
1729 <row>
1730
1731 <entry colname="col1"><para><literal>directory mask (directory mode)</literal></para></entry>
1732
1733 <entry colname="col2"><para>numeric</para></entry>
1734
1735 <entry colname="col3"><para>Sets the maximum permissions for directories created by Samba.</para></entry>
1736
1737 <entry colname="col4"><para><literal>0755</literal></para></entry>
1738
1739 <entry colname="col5"><para>Share</para></entry>
1740
1741 </row>
1742
1743 <row>
1744
1745 <entry colname="col1"><para><literal>force create mode</literal></para></entry>
1746
1747 <entry colname="col2"><para>numeric</para></entry>
1748
1749 <entry colname="col3"><para>Forces the specified permissions (bitwise or) for directories created by Samba.</para></entry>
1750
1751 <entry colname="col4"><para><literal>0000</literal></para></entry>
1752
1753 <entry colname="col5"><para>Share</para></entry>
1754
1755 </row>
1756
1757 <row>
1758
1759 <entry colname="col1"><para><literal>force directory mode</literal></para></entry>
1760
1761 <entry colname="col2"><para>numeric</para></entry>
1762
1763 <entry colname="col3"><para>Forces the specified permissions (bitwise or) for directories created by Samba.</para></entry>
1764
1765 <entry colname="col4"><para><literal>0000</literal></para></entry>
1766
1767 <entry colname="col5"><para>Share</para></entry>
1768
1769 </row>
1770
1771 <row>
1772
1773 <entry colname="col1"><para><literal>force group (group)</literal></para></entry>
1774
1775 <entry colname="col2"><para>string ( group name)</para></entry>
1776
1777 <entry colname="col3"><para>Sets the effective group for a user accessing this share.</para></entry>
1778
1779 <entry colname="col4"><para>None</para></entry>
1780
1781 <entry colname="col5"><para>Share</para></entry>
1782
1783 </row>
1784
1785 <row>
1786
1787 <entry colname="col1"><para><literal>force user</literal></para></entry>
1788
1789 <entry colname="col2"><para>string (username)</para></entry>
1790
1791 <entry colname="col3"><para>Sets the effective username for a user accessing this share.</para></entry>
1792
1793 <entry colname="col4"><para>None</para></entry>
1794
1795 <entry colname="col5"><para>Share</para></entry>
1796
1797 </row>
1798
1799 <row>
1800
1801 <entry colname="col1"><para><literal>delete readonly</literal></para></entry>
1802
1803 <entry colname="col2"><para>boolean</para></entry>
1804
1805 <entry colname="col3"><para>Allows a user to delete a read-only file from a writable directory.</para></entry>
1806
1807 <entry colname="col4"><para><literal>no</literal></para></entry>
1808
1809 <entry colname="col5"><para>Share</para></entry>
1810
1811 </row>
1812
1813 </tbody>
1814 </tgroup>
1815 </table>
1816
1817
1818 <sect3 role="" label="5.3.2.1" id="ch05-SECT-3.1.1">
1819 <title>create mask</title>
1820
1821
1822 <para>The argument for this option is an octal number indicating which permission flags may be set at file creation by a client in a share. The default is 0755, which means the Unix owner can at most read, write, and optionally execute his or her own files, while members of the user's group and others can only read or execute them. If you need to change it for non-executable files, we recommend 0644, or <literal>rw-r--r--</literal>. Keep in mind that the execute bits may be used by the server to map certain DOS file attributes, as described earlier. If you're altering the <indexterm id="ch05-idx-969816-0"><primary>creation masks</primary><secondary>option for</secondary></indexterm>create mask, those bits have to be part of the create mask as well.</para>
1823 </sect3>
1824
1825
1826
1827 <sect3 role="" label="5.3.2.2" id="ch05-SECT-3.1.2">
1828 <indexterm id="ch05-idx-970593-0"><primary>directory mask option</primary></indexterm>
1829 <title>
1830 directory mask</title>
1831
1832
1833 <para>The argument for this option is an octal number indicating which permission flags may be set at directory creation by a client in a share. The default is 0755, which allows everyone on the Unix side to at most read and traverse the directories, but allows only you to modify them. We recommend the mask 0750, removing access by world users.</para>
1834 </sect3>
1835
1836
1837
1838 <sect3 role="" label="5.3.2.3" id="ch05-SECT-3.1.3">
1839 <indexterm id="ch05-idx-970594-0"><primary>force create mode option</primary></indexterm>
1840 <title>
1841 force create mode</title>
1842
1843
1844 <para>This option sets the permission bits that Samba will force to be set when a file permission change is made. It's often used to force group permissions, mentioned previously. It can also be used to preset any of the DOS attributes we mentioned: archive (0100), system (0010), or hidden (0001). This option always takes effect after the <literal>map</literal> <literal>archive</literal>, <literal>map</literal> <literal>system </literal>, <literal>map</literal> <literal>hidden</literal>, and <literal>create</literal> <literal>mask</literal> options.</para>
1845
1846
1847 <tip role="ora">
1848 <para>Many Windows applications rename their data files to <emphasis>datafile.bak</emphasis> and create new ones, thus changing their ownership and permissions so that members of the same Unix group can't edit them. Setting <literal>force create mask = 0660</literal> will keep the new file editable by members of the group.</para>
1849
1850 </tip>
1851 </sect3>
1852
1853
1854
1855 <sect3 role="" label="5.3.2.4" id="ch05-SECT-3.1.4">
1856 <indexterm id="ch05-idx-970595-0"><primary>force directory mode option</primary></indexterm>
1857 <title>
1858 force directory mode</title>
1859
1860
1861 <para>This option sets the permission bits which Samba will force when a directory permission change is made or a directory is created. It's often used to force group permissions, as mentioned previously. This option defaults to 0000, and can be used just like the <literal>force</literal> <literal>create</literal> <literal>mode</literal> to add group or other permissions if needed. This option always takes effect after the <literal>map</literal> <literal>archive</literal>, <literal>map</literal> <literal>system</literal>, <literal>map</literal> <literal>hidden</literal>, and <literal>directory</literal> <literal>mask</literal> options.</para>
1862 </sect3>
1863
1864
1865
1866 <sect3 role="" label="5.3.2.5" id="ch05-SECT-3.1.5">
1867 <indexterm id="ch05-idx-970596-0"><primary>force group option</primary></indexterm>
1868 <title>
1869 force group</title>
1870
1871
1872 <para>This option, sometimes called <literal>group</literal>, assigns a static group ID that will be used on all connections to a service after the client has successfully authenticated. This assigns a specific group to each new file or directory created from an SMB client.</para>
1873 </sect3>
1874
1875
1876
1877 <sect3 role="" label="5.3.2.6" id="ch05-SECT-3.1.6">
1878 <indexterm id="ch05-idx-970597-0"><primary>force user option</primary></indexterm>
1879 <title>
1880 force user</title>
1881
1882
1883 <para>The <literal>force</literal> <literal>user</literal> option assigns a static user ID that will be used on all connections to a service after the client has successfully authenticated. This assigns a specific user to each new file or directory created from an SMB client.</para>
1884 </sect3>
1885
1886
1887
1888 <sect3 role="" label="5.3.2.7" id="ch05-SECT-3.1.7">
1889 <indexterm id="ch05-idx-970598-0"><primary>delete readonly option</primary></indexterm>
1890 <title>
1891 delete readonly</title>
1892
1893
1894 <para>
1895 <indexterm id="ch05-idx-969827-0"><primary>files</primary><secondary>read-only</secondary><tertiary>deleting</tertiary></indexterm>
1896 <indexterm id="ch05-idx-969827-1"><primary>read-only files</primary><secondary>deleting</secondary></indexterm>This option allows a user to delete a directory containing a read-only file. By default, DOS and Windows will not allow such an operation. You probably will want to leave this option turned off unless a program needs this capability; many Windows users would be appalled to find that they'd accidentally deleted a file which they had set read-only. In fact, even the Unix <literal>rm</literal> command will ask users if they really want to override the protection and delete read-only files. It's a good idea to have Samba be at least as cautious.</para>
1897 </sect3>
1898
1899
1900
1901 <sect3 role="" label="5.3.2.8" id="ch05-SECT-3.1.8">
1902 <indexterm id="ch05-idx-970600-0"><primary>map archive option</primary></indexterm>
1903 <title>
1904 map archive</title>
1905
1906
1907 <para>The DOS archive bit is used to flag a file that has been changed since it was last archived (e.g., backed up with the DOS archive program.) Setting the Samba option <literal>map</literal> <literal>archive</literal> <literal>=</literal> <literal>yes</literal> causes the DOS archive flag to be mapped to the Unix execute-by-owner (0100) bit. It's best to leave this option on if your Windows users are doing their own backups, or are using programs that require the archive bit. Unix lacks the notion of an archive bit entirely. Backup programs typically keep a file that lists what files were backed up on what date, so comparing file modification dates serves the same purpose.</para>
1908
1909
1910 <para>Setting this option to <literal>yes</literal> causes an occasional surprise on Unix when a user notices that a data file is marked as executable, but rarely causes harm. If a user tries to run it, he or she will normally get a string of error messages as the shell tries to execute the first few lines as commands. The reverse is also possible; an executable Unix program looks like it hasn't been backed up recently on Windows. But again, this is rare, and is usually harmless.</para>
1911 </sect3>
1912
1913
1914
1915 <sect3 role="" label="5.3.2.9" id="ch05-SECT-3.1.9">
1916 <indexterm id="ch05-idx-970601-0"><primary>map system option</primary></indexterm>
1917 <title>
1918 map system</title>
1919
1920
1921 <para>The DOS system attribute is used to indicate files that are required by the operating system, and should not be deleted, renamed, or moved without special effort. Set this option only if you need to store Windows system files on the Unix file server. Executable Unix programs will appear to be non-removable special Windows files when viewed from Windows clients. This may prove mildly inconvenient if you want to move or remove one. For most sites, however, this is fairly harmless.</para>
1922 </sect3>
1923
1924
1925
1926 <sect3 role="" label="5.3.2.10" id="ch05-SECT-3.1.10">
1927 <indexterm id="ch05-idx-970602-0"><primary>map hidden option</primary></indexterm>
1928 <title>
1929 map hidden</title>
1930
1931
1932 <para>
1933 <indexterm id="ch05-idx-969828-0"><primary>hidden files</primary><secondary>options for</secondary></indexterm>DOS uses the hidden attribute to indicate that a file should not ordinarily be visible in directory listings. Unix doesn't have such a facility; it's up to individual programs (notably the shell) to decide what to display and what not to display. Normally, you won't have any DOS files that need to be hidden, so the best thing to do is to leave this option turned off.</para>
1934
1935
1936 <para>Setting this option to <literal>yes</literal> causes the server to map the hidden flag onto the executable-by-others bit (0001). This feature can produce a rather startling effect. Any Unix program that is executable by world seems to vanish when you look for it from a Windows client. If this option is not set, however, and a Windows user attempts to mark a file hidden on a Samba share, it will not work&mdash;Samba has no place to store the hidden attribute!<indexterm id="ch05-idx-969791-0" class="endofrange" startref="ch05-idx-969769-0"/>
1937 <indexterm id="ch05-idx-969791-1" class="endofrange" startref="ch05-idx-969769-1"/>
1938 <indexterm id="ch05-idx-969791-2" class="endofrange" startref="ch05-idx-969769-2"/>
1939 <indexterm id="ch05-idx-969791-3" class="endofrange" startref="ch05-idx-969769-3"/>
1940 <indexterm id="ch05-idx-969791-4" class="endofrange" startref="ch05-idx-969813-2"/></para>
1941 </sect3>
1942 </sect2>
1943 </sect1>
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953 <sect1 role="" label="5.4" id="ch05-30534">
1954 <title>Name Mangling and Case</title>
1955
1956
1957 <para>
1958 <indexterm id="ch05-idx-969835-0" class="startofrange"><primary>name mangling</primary></indexterm>Back in the days of DOS and Windows 3.1, every filename was limited to eight upper-case characters, followed by a dot, and three more uppercase characters. This was known as the <firstterm>8.3 format</firstterm>
1959 <indexterm id="ch05-idx-969833-0"><primary>8.3 format</primary></indexterm>
1960 <indexterm id="ch05-idx-969833-1"><primary>filenames</primary><secondary>8.3 format</secondary></indexterm>, and was a huge nuisance. Windows 95/98, Windows NT, and Unix have since relaxed this problem by allowing many more case-sensitive characters to make up a filename. <link linkend="ch05-24354">Table 5.6</link> shows the current naming state of several popular operating systems.</para>
1961
1962
1963 <table label="5.6" id="ch05-24354">
1964 <title>Operating System Filename Limitations </title>
1965
1966 <tgroup cols="2">
1967 <colspec colnum="1" colname="col1"/>
1968 <colspec colnum="2" colname="col2"/>
1969 <thead>
1970 <row>
1971
1972 <entry colname="col1"><para>Operating System</para></entry>
1973
1974 <entry colname="col2"><para>File Naming Rules</para></entry>
1975
1976 </row>
1977
1978 </thead>
1979
1980 <tbody>
1981 <row>
1982
1983 <entry colname="col1"><para>DOS 6.22 or below</para></entry>
1984
1985 <entry colname="col2"><para>
1986 <indexterm id="ch05-idx-969834-0"><primary>filenames</primary><secondary>limitations on</secondary></indexterm>Eight characters followed by a dot followed by a three-letter extension (8.3 format); case insensitive</para></entry>
1987
1988 </row>
1989
1990 <row>
1991
1992 <entry colname="col1"><para>Windows 3.1 for Workgroups</para></entry>
1993
1994 <entry colname="col2"><para>Eight characters followed by a dot followed by a three-letter extension (8.3 format); case insensitive</para></entry>
1995
1996 </row>
1997
1998 <row>
1999
2000 <entry colname="col1"><para>Windows 95/98</para></entry>
2001
2002 <entry colname="col2"><para>127 characters; case sensitive</para></entry>
2003
2004 </row>
2005
2006 <row>
2007
2008 <entry colname="col1"><para>Windows NT</para></entry>
2009
2010 <entry colname="col2"><para>127 characters; case sensitive</para></entry>
2011
2012 </row>
2013
2014 <row>
2015
2016 <entry colname="col1"><para>Unix</para></entry>
2017
2018 <entry colname="col2"><para>255 characters; case sensitive</para></entry>
2019
2020 </row>
2021
2022 </tbody>
2023 </tgroup>
2024 </table>
2025
2026
2027 <para>
2028 <indexterm id="ch05-idx-969837-0"><primary>backwards compatibility</primary><secondary sortas="filenames">for filenames</secondary></indexterm>Samba still has to remain backwards compatible with network clients who store files only in the 8.3 format, such as Windows for Workgroups. If a user creates a file on a share called <emphasis>antidisestablishmentarianism.txt</emphasis>, a Windows for Workgroups client couldn't tell it apart from another file in the same directory called <emphasis>antidisease.txt</emphasis>. Like Windows 95/98 and Windows NT, Samba has to employ a special methodology of translating a long filename to an 8.3 filename in such a way that similar filenames will not cause collisions. This is called <firstterm>name mangling</firstterm>, and Samba deals with this in a manner that is similar, but not identical to, Windows 95 and its successors.</para>
2029
2030
2031 <sect2 role="" label="5.4.1" id="ch05-SECT-4.1">
2032 <title>The Samba Mangling Operation</title>
2033
2034
2035 <para>
2036 <indexterm id="ch05-idx-969840-0"><primary>name mangling</primary><secondary>steps in</secondary></indexterm>Here is how Samba mangles a long filename into an 8.3 filename:</para>
2037
2038
2039 <itemizedlist>
2040 <listitem><para>If the original filename does not begin with a dot, up to the first five alphanumeric characters that occur before the last dot (if there is one) are converted to uppercase. These characters are used as the first five characters of the 8.3 mangled filename.</para></listitem>
2041 <listitem><para>If the original filename begins with a dot, the dot is removed and up to the first five alphanumeric characters that occur before the last dot (if there is one) are converted to uppercase. These characters are used as the first five characters of the 8.3 mangled filename.</para></listitem>
2042 <listitem><para>These characters are immediately followed a special mangling character: by default, a tilde (~), although Samba allows you to change this character.</para></listitem>
2043 <listitem><para>The base of the long filename before the last period is hashed into a two-character code; parts of the name after the last dot may be used if necessary. This two character code is appended to the 8.3 filename after the mangling character.</para></listitem>
2044 <listitem><para>The first three characters after the last dot (if there is one) of the original filename are converted to uppercase and appended onto the mangled name as the extension. If the original filename began with a dot, three underscores (  <literal>_   _   _  </literal>) are used as the extension instead.</para></listitem>
2045 </itemizedlist>
2046
2047 <para>Here are some examples:</para>
2048
2049
2050 <programlisting>virtuosity.dat                       VIRTU~F1.DAT
2051 .htaccess                            HTACC~U0._ _ _
2052 hello.java                           HELLO~1F.JAV
2053 team.config.txt                      TEAMC~04.TXT
2054 antidisestablishmentarianism.txt     ANTID~E3.TXT
2055 antidiseast.txt                      ANTID~9K.TXT</programlisting>
2056
2057
2058 <para>Using these rules will allow Windows for Workgroups to differentiate the two files on behalf of the poor individual who is forced to see the network through the eyes of that operating system. Note that the same long filename should always hash to the same mangled name with Samba; this doesn't always happen with Windows. The downside of this approach is that there can still be collisions; however, the chances are greatly reduced.</para>
2059
2060
2061 <para>You generally want to use the mangling configuration options with only the oldest clients. We recommend doing this without disrupting other clients by adding an <literal>include</literal> directive to the <filename>smb.conf</filename> file:</para>
2062
2063
2064 <programlisting>[global]
2065         include = /ucsr/local/samba/lib/smb.conf.%m</programlisting>
2066
2067
2068 <para>This resolves to <filename>smb.conf.WfWg</filename> when a Window for Workgroups client attaches.  Now you can create a file <filename>/usr/local/samba/lib/smb.conf.WfWg</filename> which might contain these options:</para>
2069
2070
2071 <programlisting>[global]
2072         case sensitive = no
2073         default case = upper
2074         preserve case = no
2075         short preserve case = no
2076         mangle case = yes
2077         mangled names= yes</programlisting>
2078
2079
2080 <para>If you are not using Windows for Workgroups 3.1, then you probably do not need to change any of these options from their defaults.</para>
2081
2082
2083 <sect3 role="" label="5.4.1.1" id="ch05-SECT-4.1.1">
2084 <title>Representing and resolving filenames with Samba</title>
2085
2086
2087 <para>
2088 <indexterm id="ch05-idx-969841-0"><primary>representing/resolving filenames</primary></indexterm>
2089 <indexterm id="ch05-idx-969841-1"><primary>filenames</primary><secondary>representing/resolving</secondary></indexterm>Another item that we should point out is that there is a difference between how an operating system <emphasis>represents</emphasis> a file and how it <emphasis>resolves</emphasis> it. For example, if you've used Windows 95/98/NT, you have likely run across a file called <filename>README.TXT</filename>. The file can be represented by the operating system entirely in uppercase letters. However, if you open an MS-DOS prompt and enter the command <literal>edit</literal> <literal>readme.txt</literal>, the all-caps file is loaded into the editing program, even though you typed the name in lowercase letters!</para>
2090
2091
2092 <para>This is because the Windows 95/98/NT family of operating systems resolves files in a case-insensitive manner, even though the files are represented it in a case-sensitive manner. Unix-based operating systems, on the other hand, always resolve files in a case-sensitive manner; if you try to edit <filename>README.TXT</filename> with the command <literal>vi</literal> <literal>readme.txt</literal>, you will likely be editing the empty buffer of a new file.</para>
2093
2094
2095 <para>Here is how Samba handles case: if the <literal>preserve</literal> <literal>case</literal> is set to <literal>yes</literal>, Samba will always use the case provided by the operating system for representing (not resolving) filenames. If it is set to <literal>no</literal>, it will use the case specified by the <literal>default</literal> <literal>case</literal> option. The same is true for <literal>short</literal> <literal>preserve</literal> <literal>case</literal>. If this option is set to <literal>yes</literal>, Samba will use the default case of the operating system for representing 8.3 filenames; otherwise it will use the case specified by the <literal>default</literal> <literal>case</literal> option. Finally, Samba will always resolve filenames in its shares based on the value of the <literal>case</literal> <literal>sensitive</literal> option.</para>
2096 </sect3>
2097 </sect2>
2098
2099
2100
2101
2102
2103 <sect2 role="" label="5.4.2" id="ch05-SECT-4.2">
2104 <title>Mangling Options</title>
2105
2106
2107 <para>
2108 <indexterm id="ch05-idx-969842-0" class="startofrange"><primary>name mangling</primary><secondary>options for</secondary></indexterm>Samba allows you to give it more refined instructions on how it should perform name mangling, including those controlling the case sensitivity, the character inserted to form a mangled name, and the ability to manually map filenames from one format to another. These options are shown in <link linkend="ch05-47431">Table 5.7</link>.</para>
2109
2110
2111 <table label="5.7" id="ch05-47431">
2112 <title>Name Mangling Options </title>
2113
2114 <tgroup cols="5">
2115 <colspec colnum="1" colname="col1"/>
2116 <colspec colnum="2" colname="col2"/>
2117 <colspec colnum="3" colname="col3"/>
2118 <colspec colnum="4" colname="col4"/>
2119 <colspec colnum="5" colname="col5"/>
2120 <thead>
2121 <row>
2122
2123 <entry colname="col1"><para>Option</para></entry>
2124
2125 <entry colname="col2"><para>Parameters</para></entry>
2126
2127 <entry colname="col3"><para>Function</para></entry>
2128
2129 <entry colname="col4"><para>Default</para></entry>
2130
2131 <entry colname="col5"><para>Scope</para></entry>
2132
2133 </row>
2134
2135 </thead>
2136
2137 <tbody>
2138 <row>
2139
2140 <entry colname="col1"><para><literal>case sensitive</literal></para>
2141
2142 <para><literal>(casesignames)</literal></para></entry>
2143
2144 <entry colname="col2"><para>boolean</para></entry>
2145
2146 <entry colname="col3"><para>If <literal>yes</literal>, Samba will treat filenames as case-sensitive (Windows doesn't).</para></entry>
2147
2148 <entry colname="col4"><para><literal>no</literal></para></entry>
2149
2150 <entry colname="col5"><para>Share</para></entry>
2151
2152 </row>
2153
2154 <row>
2155
2156 <entry colname="col1"><para><literal>default case</literal></para></entry>
2157
2158 <entry colname="col2"><para>(<literal>upper</literal> or <literal>lower</literal>)</para></entry>
2159
2160 <entry colname="col3"><para>Case to assume as default (only used when preserve case is <literal>no</literal>).</para></entry>
2161
2162 <entry colname="col4"><para>Lower</para></entry>
2163
2164 <entry colname="col5"><para>Share</para></entry>
2165
2166 </row>
2167
2168 <row>
2169
2170 <entry colname="col1"><para><literal>preserve case</literal></para></entry>
2171
2172 <entry colname="col2"><para>boolean</para></entry>
2173
2174 <entry colname="col3"><para>If <literal>yes</literal>, keep the case the client supplied (i.e., do not convert to <literal>default case</literal>).</para></entry>
2175
2176 <entry colname="col4"><para><literal>yes</literal></para></entry>
2177
2178 <entry colname="col5"><para>Share</para></entry>
2179
2180 </row>
2181
2182 <row>
2183
2184 <entry colname="col1"><para><literal>short preserve case</literal></para></entry>
2185
2186 <entry colname="col2"><para>boolean</para></entry>
2187
2188 <entry colname="col3"><para>If <literal>yes</literal>, preserve case of 8.3-format names that the client provides.</para></entry>
2189
2190 <entry colname="col4"><para><literal>yes</literal></para></entry>
2191
2192 <entry colname="col5"><para>Share</para></entry>
2193
2194 </row>
2195
2196 <row>
2197
2198 <entry colname="col1"><para><literal>mangle case</literal></para></entry>
2199
2200 <entry colname="col2"><para>boolean</para></entry>
2201
2202 <entry colname="col3"><para>Mangle a name if it is mixed case.</para></entry>
2203
2204 <entry colname="col4"><para><literal>no</literal></para></entry>
2205
2206 <entry colname="col5"><para>Share</para></entry>
2207
2208 </row>
2209
2210 <row>
2211
2212 <entry colname="col1"><para><literal>mangled names</literal></para></entry>
2213
2214 <entry colname="col2"><para>boolean</para></entry>
2215
2216 <entry colname="col3"><para>8.3 DOS format.</para></entry>
2217
2218 <entry colname="col4"><para><literal>yes</literal></para></entry>
2219
2220 <entry colname="col5"><para>Share</para></entry>
2221
2222 </row>
2223
2224 <row>
2225
2226 <entry colname="col1"><para><literal>mangling char</literal></para></entry>
2227
2228 <entry colname="col2"><para>string (single character)</para></entry>
2229
2230 <entry colname="col3"><para>Gives mangling character.</para></entry>
2231
2232 <entry colname="col4"><para><literal>~</literal></para></entry>
2233
2234 <entry colname="col5"><para>Share</para></entry>
2235
2236 </row>
2237
2238 <row>
2239
2240 <entry colname="col1"><para><literal>mangled stack</literal></para></entry>
2241
2242 <entry colname="col2"><para>numerical</para></entry>
2243
2244 <entry colname="col3"><para>Number of mangled names to keep on the local mangling stack.</para></entry>
2245
2246 <entry colname="col4"><para><literal>50</literal></para></entry>
2247
2248 <entry colname="col5"><para>Global</para></entry>
2249
2250 </row>
2251
2252 <row>
2253
2254 <entry colname="col1"><para><literal>mangled map</literal></para></entry>
2255
2256 <entry colname="col2"><para>string (list of patterns)</para></entry>
2257
2258 <entry colname="col3"><para>Allows mapping of filenames from one format into another.</para></entry>
2259
2260 <entry colname="col4"><para>None</para></entry>
2261
2262 <entry colname="col5"><para>Share</para></entry>
2263
2264 </row>
2265
2266 </tbody>
2267 </tgroup>
2268 </table>
2269
2270
2271 <sect3 role="" label="5.4.2.1" id="ch05-SECT-4.2.1">
2272 <title>case sensitive</title>
2273
2274
2275 <para>
2276 <indexterm id="ch05-idx-969856-0"><primary>case sensitivity</primary><secondary>options for</secondary></indexterm>This share-level option, which has the obtuse synonym <literal>casesignames</literal>, specifies whether Samba should preserve case when resolving filenames in a specific share. The default value for this option is <literal>no</literal>, which is how Windows handles file resolution. If clients are using an operating system that takes advantage of case-sensitive filenames, you can set this configuration option to <literal>yes</literal> as shown here:</para>
2277
2278
2279 <programlisting>[accounting]
2280         case sensitive = yes</programlisting>
2281
2282
2283 <para>Otherwise, we recommend that you leave this option set to its default.</para>
2284 </sect3>
2285
2286
2287
2288 <sect3 role="" label="5.4.2.2" id="ch05-SECT-4.2.2">
2289 <title>default case</title>
2290
2291
2292 <para>The <literal>default</literal>
2293 <indexterm id="ch05-idx-970606-0"><primary>default case option</primary></indexterm> <literal>case</literal> option is used with <literal>preserve</literal> <literal>case</literal>. This specifies the default case (upper or lower) that Samba will use when it creates a file on one of its shares on behalf of a client. The default case is <literal>lower</literal>, which means that newly created files will use the mixed-case names given to them by the client. If you need to, you can override this global option by specifying the following:</para>
2294
2295
2296 <programlisting>[global]
2297         default case = upper</programlisting>
2298
2299
2300 <para>If you specify this value, the names of newly created files will be translated into uppercase, and cannot be overridden in a program. We recommend that you use the default value unless you are dealing with a Windows for Workgroups or other 8.3 client, in which case it should be <literal>upper</literal>.</para>
2301 </sect3>
2302
2303
2304
2305 <sect3 role="" label="5.4.2.3" id="ch05-SECT-4.2.3">
2306 <indexterm id="ch05-idx-970607-0"><primary>preserve case option</primary></indexterm>
2307 <title>
2308 preserve case</title>
2309
2310
2311 <para>This option specifies whether a file created by Samba on behalf of the client is created with the case provided by the client operating system, or the case specified by the <literal>default</literal> <literal>case</literal> configuration option above. The default value is <literal>yes</literal>, which uses the case provided by the client operating system. If it is set to <literal>no</literal>, the value of the <literal>default</literal> <literal>case</literal> option is used.</para>
2312
2313
2314 <para>Note that this option does not handle 8.3 file requests sent from the client&mdash;see the <literal>short</literal> <literal>preserve</literal> <literal>case</literal> option below. You may want to set this option to <literal>yes</literal> if applications that create files on the Samba server are sensitive to the case used when creating the file. If you want to force Samba, for example, to mimic the behavior of a Windows NT filesystem, you can leave this option to its default, <literal>yes</literal>.</para>
2315 </sect3>
2316
2317
2318
2319 <sect3 role="" label="5.4.2.4" id="ch05-SECT-4.2.4">
2320 <indexterm id="ch05-idx-970608-0"><primary>hort preserve case option</primary></indexterm>
2321 <title>short preserve case</title>
2322
2323
2324 <para>This option specifies whether an 8.3 filename created by Samba on behalf of the client is created with the default case of the client operating system, or the case specified by the <literal>default</literal> <literal>case</literal> configuration option. The default value is <literal>yes</literal>, which uses the case provided by the client operating system. You can let Samba choose the case through the <literal>default</literal> <literal>case</literal> option by setting it as follows:</para>
2325
2326
2327 <programlisting>[global]
2328         short preserve case = no</programlisting>
2329
2330
2331 <para>If you want to force Samba to mimic the behavior of a Windows NT filesystem, you can leave this option set to its default, <literal>yes</literal>.</para>
2332 </sect3>
2333
2334
2335
2336 <sect3 role="" label="5.4.2.5" id="ch05-SECT-4.2.5">
2337 <indexterm id="ch05-idx-970609-0"><primary>mangled names option</primary></indexterm>
2338 <title>
2339 mangled names</title>
2340
2341
2342 <para>This share-level option specifies whether Samba will mangle filenames for 8.3 clients in that share. If the option is set to <literal>no</literal>, Samba will not mangle the names and (depending on the client), they will either be invisible or appear truncated to those using 8.3 operating systems. The default value is <literal>yes</literal>. You can override it per share as follows:</para>
2343
2344
2345 <programlisting>[data]
2346         mangled names = no</programlisting>
2347 </sect3>
2348
2349
2350
2351 <sect3 role="" label="5.4.2.6" id="ch05-SECT-4.2.6">
2352 <indexterm id="ch05-idx-970610-0"><primary>mangle case option</primary></indexterm>
2353 <title>
2354 mangle case</title>
2355
2356
2357 <para>This option tells Samba whether it should mangle filenames that are not composed entirely of the case specified using the <literal>default</literal> <literal>case</literal> configuration option. The default for this option is <literal>no</literal>. If you set it to <literal>yes</literal>, you should be sure that all clients will be able to handle the mangled filenames that result. You can override it per share as follows:</para>
2358
2359
2360 <programlisting>[data]
2361         mangle case = yes</programlisting>
2362
2363
2364 <para>We recommend that you leave this option alone unless you have a well-justified need to change it.</para>
2365 </sect3>
2366
2367
2368
2369 <sect3 role="" label="5.4.2.7" id="ch05-SECT-4.2.7">
2370 <indexterm id="ch05-idx-970611-0"><primary>mangling char option</primary></indexterm>
2371 <title>
2372 mangling char</title>
2373
2374
2375 <para>This share-level option specifies the mangling character used when Samba mangles filenames into the 8.3 format. The default character used is a tilde (~). You can reset it to whatever character you wish, for instance:</para>
2376
2377
2378 <programlisting>[data]
2379         mangling char = #</programlisting>
2380 </sect3>
2381
2382
2383
2384 <sect3 role="" label="5.4.2.8" id="ch05-SECT-4.2.8">
2385 <indexterm id="ch05-idx-970612-0"><primary>mangled stack option</primary></indexterm>
2386 <title>
2387 mangled stack</title>
2388
2389
2390 <para>Samba maintains a local stack of recently mangled 8.3 filenames; this stack can be used to reverse map mangled filenames back to their original state. This is often needed by applications that create and save a file, close it, and need to modify it later. The default number of long filename/mangled filename pairs stored on this stack is 50. However, if you want to cut down on the amount of processor time used to mangle filenames, you can increase the size of the stack to whatever you wish, at the expense of memory and slightly slower file access.</para>
2391
2392
2393 <programlisting>[global]
2394         mangled stack = 100</programlisting>
2395 </sect3>
2396
2397
2398
2399 <sect3 role="" label="5.4.2.9" id="ch05-SECT-4.2.9">
2400 <indexterm id="ch05-idx-970613-0"><primary>mangled map option</primary></indexterm>
2401 <title>
2402 mangled map</title>
2403
2404
2405 <para>If the default behavior of name mangling is not sufficient, you can give Samba further instructions on how to behave using the <literal>mangled</literal> <literal>map</literal> option. This option allows you to specify mapping patterns that can be used before or even in place of name mangling performed by Samba. For example:</para>
2406
2407
2408 <programlisting>[data]
2409         mangled map =(*.database *.db) (*.class *.cls)</programlisting>
2410
2411
2412 <para>Here, Samba is instructed to search each file it encounters for characters that match the first pattern specified in the parenthesis and convert them to the modified second pattern in the parenthesis for display on an 8.3 client. This is useful in the event that name mangling converts the filename incorrectly or to a format that the client cannot understand<indexterm id="ch05-idx-969851-0" class="endofrange" startref="ch05-idx-969842-0"/> readily. Patterns are separated by whitespaces.<indexterm id="ch05-idx-969845-0" class="endofrange" startref="ch05-idx-969835-0"/></para>
2413 </sect3>
2414 </sect2>
2415 </sect1>
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425 <sect1 role="" label="5.5" id="ch05-75933">
2426 <title>Locks and Oplocks</title>
2427
2428
2429 <para>
2430 <indexterm id="ch05-idx-969857-0" class="startofrange"><primary>locks/locking files</primary></indexterm>
2431 <indexterm id="ch05-idx-969857-1" class="startofrange"><primary>oplocks</primary></indexterm>Concurrent writes to a single file are not desirable in any operating system. To prevent this, most operating systems use <firstterm>locks</firstterm> to guarantee that only one process can write to a file at a time. Operating systems traditionally lock entire files, although newer ones allow a range of bytes within a file to be locked. If another process attempts to write to a file (or section of one) that is already locked, it will receive an error from the operating system and will wait until the lock is released.</para>
2432
2433
2434 <para>Samba supports the standard DOS and NT filesystem (deny-mode) locking requests, which allow only one process to write to an entire file on a server at a give time, as well as byte-range locking. In addition, Samba supports a new locking mechanism known in the Windows NT world as <firstterm>opportunistic locking&mdash;</firstterm><emphasis>oplock</emphasis> for short.</para>
2435
2436
2437 <sect2 role="" label="5.5.1" id="ch05-SECT-5.1">
2438 <title>Opportunistic Locking</title>
2439
2440
2441 <para>Opportunistic locking allows a client to notify the Samba server that it will not only be the exclusive writer of a file, but will also cache its changes to that file on its own machine (and not on the Samba server) in order to speed up file access for that client. When Samba knows that a file has been opportunistically locked by a client, it marks its version as having an opportunistic lock and waits for the client to complete work on the file, at which point it expects the client to send the final changes back to the Samba server for synchronization.</para>
2442
2443
2444 <para>If a second client requests access to that file before the first client has finished working on it, Samba can send an <firstterm>oplock break</firstterm>
2445 <indexterm id="ch05-idx-969865-0"><primary>oplocks</primary><secondary>break requests</secondary></indexterm> request to the first client. This tells the client to stop caching its changes and return the current state of the file to the server so that the interrupting client can use it as it sees fit. An opportunistic lock, however, is not a replacement for a standard deny-mode lock. It is not unheard of for the interrupting process to be granted an oplock break only to discover that the original process also has a deny-mode lock on a file as well. <link linkend="ch05-74304">Figure 5.8</link> illustrates this opportunistic locking process.</para>
2446
2447
2448 <figure label="5.8" id="ch05-74304">
2449 <title>Opportunistic locking</title>
2450
2451 <graphic width="502" depth="314" fileref="figs/sam.0508.gif"></graphic>
2452 </figure>
2453
2454 <para>In terms of locks, we highly recommend using the defaults provided by Samba: standard DOS/Windows deny-mode locks for compatibility and oplocks for the extra performance that local caching allows. If your operating system can take advantage of oplocks, it should provide significant performance improvements. Unless you have a specific reason for changing any of these options, it's best to leave them as they are.</para>
2455 </sect2>
2456
2457
2458
2459
2460
2461 <sect2 role="" label="5.5.2" id="ch05-SECT-5.2">
2462 <title>Unix and Locking</title>
2463
2464
2465 <para>
2466 <indexterm id="ch05-idx-969866-0"><primary>locks/locking files</primary><secondary>Unix and</secondary></indexterm>
2467 <indexterm id="ch05-idx-969866-1"><primary>Unix</primary><secondary>locks and</secondary></indexterm>Windows systems cooperate well to avoid overwriting each other's changes. But if a file stored on a Samba system is accessed by a Unix process, this process won't know a thing about Windows oplocks and could easily ride roughshod over a lock. Some Unix systems have been enhanced to understand the Windows oplocks maintained by Samba. Currently the support exists only in SGI Irix 6.5.2f and later; Linux and FreeBSD should soon follow.</para>
2468
2469
2470 <para>If you have a system that understands oplocks, set <literal>kernel</literal> <literal>oplocks</literal> <literal>=</literal> <literal>yes</literal> in the Samba configuration file. That should eliminate conflicts between Unix processes and Windows users.</para>
2471
2472
2473 <para>If your system does not support kernel oplocks, you could end up with corrupted data when somebody runs a Unix process that reads or writes a file that Windows users also access. However, Samba provides a rough protection mechanism in the absence of kernel oplocks: the <literal>veto</literal> <literal>oplock</literal> <literal>files</literal> option. If you can anticipate which Samba files are used by both Windows users and Unix users, set their names in a <literal>veto</literal> <literal>oplock</literal> <literal>files</literal> option. This will suppress the use of oplocks on matching filenames, which will supress client caching, and let the Windows and Unix programs use system locking or update times to detect competition for the same file. A sample option is:</para>
2474
2475
2476 <programlisting>veto oplock files = /*.dbm/</programlisting>
2477
2478
2479 <para>This option allows both Unix processes and Windows users to edit files ending in the suffix <emphasis>.dbm</emphasis>. Note that the syntax of this option is similar to <literal>veto</literal> <literal>files</literal>.</para>
2480
2481
2482 <para>Samba's options for locks and oplocks are given in <link linkend="ch05-53407">Table 5.8</link>.</para>
2483
2484
2485 <table label="5.8" id="ch05-53407">
2486 <title>Locks and Oplocks Configuration Options </title>
2487
2488 <tgroup cols="5">
2489 <colspec colnum="1" colname="col1"/>
2490 <colspec colnum="2" colname="col2"/>
2491 <colspec colnum="3" colname="col3"/>
2492 <colspec colnum="4" colname="col4"/>
2493 <colspec colnum="5" colname="col5"/>
2494 <thead>
2495 <row>
2496
2497 <entry colname="col1"><para>Option</para></entry>
2498
2499 <entry colname="col2"><para>Parameters</para></entry>
2500
2501 <entry colname="col3"><para>Function</para></entry>
2502
2503 <entry colname="col4"><para>Default</para></entry>
2504
2505 <entry colname="col5"><para>Scope</para></entry>
2506
2507 </row>
2508
2509 </thead>
2510
2511 <tbody>
2512 <row>
2513
2514 <entry colname="col1"><para><literal>share modes</literal></para></entry>
2515
2516 <entry colname="col2"><para>
2517 <indexterm id="ch05-idx-969867-0" class="startofrange"><primary>locks/locking files</primary><secondary>options for</secondary></indexterm>
2518 <indexterm id="ch05-idx-969867-1" class="startofrange"><primary>oplocks</primary><secondary>options for</secondary></indexterm>boolean</para></entry>
2519
2520 <entry colname="col3"><para>If set to <literal>yes</literal>, turns on support for DOS-style whole-file locks.</para></entry>
2521
2522 <entry colname="col4"><para><literal>yes</literal></para></entry>
2523
2524 <entry colname="col5"><para>Share</para></entry>
2525
2526 </row>
2527
2528 <row>
2529
2530 <entry colname="col1"><para><literal>locking</literal></para></entry>
2531
2532 <entry colname="col2"><para>boolean</para></entry>
2533
2534 <entry colname="col3"><para>If <literal>yes</literal>, turns on byte-range locks.</para></entry>
2535
2536 <entry colname="col4"><para><literal>yes</literal></para></entry>
2537
2538 <entry colname="col5"><para>Share</para></entry>
2539
2540 </row>
2541
2542 <row>
2543
2544 <entry colname="col1"><para><literal>strict locking</literal></para></entry>
2545
2546 <entry colname="col2"><para>boolean</para></entry>
2547
2548 <entry colname="col3"><para>If <literal>yes</literal>, denies access to an entire file if a byte-range lock exists in it.</para></entry>
2549
2550 <entry colname="col4"><para><literal>no</literal></para></entry>
2551
2552 <entry colname="col5"><para>Share</para></entry>
2553
2554 </row>
2555
2556 <row>
2557
2558 <entry colname="col1"><para><literal>oplocks</literal></para></entry>
2559
2560 <entry colname="col2"><para>boolean</para></entry>
2561
2562 <entry colname="col3"><para>If <literal>yes</literal>, turn on local caching of files on the client for this share.</para></entry>
2563
2564 <entry colname="col4"><para><literal>yes</literal></para></entry>
2565
2566 <entry colname="col5"><para>Share</para></entry>
2567
2568 </row>
2569
2570 <row>
2571
2572 <entry colname="col1"><para><literal>kernel oplocks</literal></para></entry>
2573
2574 <entry colname="col2"><para>boolean</para></entry>
2575
2576 <entry colname="col3"><para>If <literal>yes</literal>, indicates that the kernel supports oplocks.</para></entry>
2577
2578 <entry colname="col4"><para><literal>yes</literal></para></entry>
2579
2580 <entry colname="col5"><para>Global</para></entry>
2581
2582 </row>
2583
2584 <row>
2585
2586 <entry colname="col1"><para><literal>fake oplocks</literal></para></entry>
2587
2588 <entry colname="col2"><para>boolean</para></entry>
2589
2590 <entry colname="col3"><para>If <literal>yes</literal>, tells client the lock was obtained, but doesn't actually lock it.</para></entry>
2591
2592 <entry colname="col4"><para><literal>no</literal></para></entry>
2593
2594 <entry colname="col5"><para>Share</para></entry>
2595
2596 </row>
2597
2598 <row>
2599
2600 <entry colname="col1"><para><literal>blocking locks </literal></para></entry>
2601
2602 <entry colname="col2"><para>boolean</para></entry>
2603
2604 <entry colname="col3"><para>Allows lock requestor to wait for the lock to be granted.</para></entry>
2605
2606 <entry colname="col4"><para><literal>yes</literal></para></entry>
2607
2608 <entry colname="col5"><para>Share</para></entry>
2609
2610 </row>
2611
2612 <row>
2613
2614 <entry colname="col1"><para><literal>veto oplock files</literal></para></entry>
2615
2616 <entry colname="col2"><para>string (list of filenames)</para></entry>
2617
2618 <entry colname="col3"><para>Does not oplock specified files.</para></entry>
2619
2620 <entry colname="col4"><para>None</para></entry>
2621
2622 <entry colname="col5"><para>Share</para></entry>
2623
2624 </row>
2625
2626 <row>
2627
2628 <entry colname="col1"><para><literal>lock directory</literal></para></entry>
2629
2630 <entry colname="col2"><para>string (fully-qualified pathname)</para></entry>
2631
2632 <entry colname="col3"><para>Sets the location where various Samba files, including locks, are stored.</para></entry>
2633
2634 <entry colname="col4"><para>As specified in Samba makefile</para></entry>
2635
2636 <entry colname="col5"><para>Global</para></entry>
2637
2638 </row>
2639
2640 </tbody>
2641 </tgroup>
2642 </table>
2643
2644
2645 <sect3 role="" label="5.5.2.1" id="ch05-SECT-5.2.1">
2646 <title>share modes</title>
2647
2648
2649 <para>The most primitive locks available to Samba are deny-mode locks, known as <firstterm>share modes</firstterm>
2650 <indexterm id="ch05-idx-969868-0"><primary>share modes</primary></indexterm>
2651 <indexterm id="ch05-idx-969868-1"><primary>SMB (Server Message Block)</primary><secondary>deny-mode locks</secondary></indexterm>, which are employed by programs such as text editors to avoid accidental overwriting of files. For reference, the deny-mode locks are listed in <link linkend="ch05-55885">Table 5.9</link>.</para>
2652
2653
2654 <table label="5.9" id="ch05-55885">
2655 <title>SMB Deny-Mode Locks </title>
2656
2657 <tgroup cols="2">
2658 <colspec colnum="1" colname="col1"/>
2659 <colspec colnum="2" colname="col2"/>
2660 <thead>
2661 <row>
2662
2663 <entry colname="col1"><para>Lock</para></entry>
2664
2665 <entry colname="col2"><para>Description</para></entry>
2666
2667 </row>
2668
2669 </thead>
2670
2671 <tbody>
2672 <row>
2673
2674 <entry colname="col1"><para><literal>DENY_NONE</literal></para></entry>
2675
2676 <entry colname="col2"><para>Do not deny any other file requests.</para></entry>
2677
2678 </row>
2679
2680 <row>
2681
2682 <entry colname="col1"><para><literal>DENY_ALL</literal></para></entry>
2683
2684 <entry colname="col2"><para>Deny all open requests on the current file.</para></entry>
2685
2686 </row>
2687
2688 <row>
2689
2690 <entry colname="col1"><para><literal>DENY_READ</literal></para></entry>
2691
2692 <entry colname="col2"><para>Deny any read-only open requests on the current file.</para></entry>
2693
2694 </row>
2695
2696 <row>
2697
2698 <entry colname="col1"><para><literal>DENY_WRITE</literal></para></entry>
2699
2700 <entry colname="col2"><para>Deny any write-only open requests on the current file.</para></entry>
2701
2702 </row>
2703
2704 <row>
2705
2706 <entry colname="col1"><para><literal>DENY_DOS</literal></para></entry>
2707
2708 <entry colname="col2"><para>If opened for reading, others can read but cannot write to the file. If opened for writing, others cannot open the file at all.</para></entry>
2709
2710 </row>
2711
2712 <row>
2713
2714 <entry colname="col1"><para><literal>DENY_FCB</literal></para></entry>
2715
2716 <entry colname="col2"><para>Obsolete.</para></entry>
2717
2718 </row>
2719
2720 </tbody>
2721 </tgroup>
2722 </table>
2723
2724
2725 <para>The <literal>share</literal> <literal>modes</literal> parameter, which enforces the use of these locks, is enabled by default. To disable it, use the following command:</para>
2726
2727
2728 <programlisting>[accounting]
2729         share modes = no</programlisting>
2730
2731
2732 <para>We highly recommend against disabling the default locking mechanism unless you have a justifiable reason for doing so. Most Windows and DOS applications rely on these locking mechanisms in order to work correctly, and will complain bitterly if this functionality is taken away.</para>
2733 </sect3>
2734
2735
2736
2737 <sect3 role="" label="5.5.2.2" id="ch05-SECT-5.2.2">
2738 <title>locking</title>
2739
2740
2741 <para>The<indexterm id="ch05-idx-970616-0"><primary>locking option</primary></indexterm> <literal>locking</literal> option can be used to tell Samba to engage or disengage server-side byte-range locks on behalf of the client. Samba implements byte-range locks on the server side with normal Unix advisory locks and will consequently prevent other properly-behaved Unix processes from overwriting a locked byte range.</para>
2742
2743
2744 <para>This option can be specified per share as follows:</para>
2745
2746
2747 <programlisting>[accounting]
2748         locking = yes</programlisting>
2749
2750
2751 <para>If the <literal>locking</literal> option is set to <literal>yes</literal>, the requestor will be delayed until the holder of either type of lock releases it (or crashes). If, however, the option is set to <literal>no</literal>, no byte-range locks will be kept for the files, although requests to lock and unlock files will appear to succeed. The option is set to <literal>yes</literal> by default; however, you can turn this option off if you have read-only media.</para>
2752 </sect3>
2753
2754
2755
2756 <sect3 role="" label="5.5.2.3" id="ch05-SECT-5.2.3">
2757 <indexterm id="ch05-idx-970617-0"><primary>strict locking option</primary></indexterm>
2758 <title>
2759 strict locking</title>
2760
2761
2762 <para>This option checks every file access for a byte-range lock on the range of bytes being accessed. This is typically not needed if a client adheres to all the locking mechanisms in place. This option is set to <literal>no</literal> by default; however, you can reset it per share as follows:</para>
2763
2764
2765 <programlisting>[accounting]
2766         strict locking = yes</programlisting>
2767
2768
2769 <para>If this option is set to <literal>yes</literal>, mandatory locks are enforced on any file with byte-range locks.</para>
2770 </sect3>
2771
2772
2773
2774 <sect3 role="" label="5.5.2.4" id="ch05-SECT-5.2.4">
2775 <indexterm id="ch05-idx-970618-0"><primary>blocking locks option</primary></indexterm>
2776 <title>
2777 blocking locks</title>
2778
2779
2780 <para>Samba also supports <firstterm>blocking locks</firstterm>, a minor variant of range locks. Here, if the range of bytes is not available, the client specifies an amount of time that it's willing to wait. The server then caches the lock request, periodically checking to see if the file is available. If it is, it notifies the client; however, if time expires, Samba will tell the client that the request has failed. This strategy prevents the client from continually polling to see if the lock is available.</para>
2781
2782
2783 <para>You can disable this option per share as follows:</para>
2784
2785
2786 <programlisting>[accounting]
2787         blocking locks = no</programlisting>
2788
2789
2790 <para>When set to <literal>yes</literal>, blocking locks will be enforced on the file. If this option is set to <literal>no</literal>, Samba behaves as if normal locking mechanisms are in place on the file. The default is <literal>yes</literal>.</para>
2791 </sect3>
2792
2793
2794
2795 <sect3 role="" label="5.5.2.5" id="ch05-SECT-5.2.5">
2796 <indexterm id="ch05-idx-970619-0"><primary>oplocks option</primary></indexterm>
2797 <title>
2798 oplocks</title>
2799
2800
2801 <para>This option enables or disables support for oplocks on the client. The option is enabled by default. However, you can disable it with the following command:</para>
2802
2803
2804 <programlisting>[data]
2805         oplocks = no</programlisting>
2806
2807
2808 <para>If you are in an extremely unstable network environment or have many clients that cannot take advantage of opportunistic locking, it may be better to shut this Samba feature off. Oplocks should be disabled if you are accessing the same files from both Unix applications (such as <emphasis>vi</emphasis>  ) and SMB clients (unless you are lucky enough to have an operating system that supports kernel oplocks as discussed earlier).</para>
2809 </sect3>
2810
2811
2812
2813 <sect3 role="" label="5.5.2.6" id="ch05-SECT-5.2.6">
2814 <indexterm id="ch05-idx-970620-0"><primary>fake oplocks option</primary></indexterm>
2815 <title>
2816 fake oplocks</title>
2817
2818
2819 <para>Before opportunistic locking was available on Samba, the Samba daemons pretended to allow oplocks via the <literal>fake</literal> <literal>oplocks</literal> option. If this option was enabled, all clients were told that the file is available for opportunistic locking, and never warned of simultaneous access. This option is deprecated now that real oplocks are available on Samba.</para>
2820 </sect3>
2821
2822
2823
2824 <sect3 role="" label="5.5.2.7" id="ch05-SECT-5.2.7">
2825 <indexterm id="ch05-idx-970621-0"><primary>kernel oplocks option</primary></indexterm>
2826 <title>
2827 kernel oplocks</title>
2828
2829
2830 <para>If a Unix application separate from Samba tries to update a file that Samba has oplocked to a Windows client, it will likely succeed (depending on the operating system) and both Samba and the client will never be aware of it. However, if the local Unix operating system supports it, Samba can warn it of oplocked files, which can suspend the Unix process, notify the client via Samba to write its copy back, and only then allow the open to complete. Essentially, this means that the operating system kernel on the Samba system has the ability to handle oplocks as well as Samba.</para>
2831
2832
2833 <para>You can enable this behavior with the <literal>kernel</literal> <literal>oplocks</literal> option, as follows:</para>
2834
2835
2836 <programlisting>[global]
2837         kernel oplocks = yes</programlisting>
2838
2839
2840 <para>Samba can automatically detect kernel oplocks and use them if present. At the time of this writing, this feature is supported only by SGI Irix 6.5.2f and later. However, Linux and FreeBSD support are expected in the near future. A system without kernel oplocks will allow the Unix process to update the file, but the client programs will notice the change only at a later time, if at all.</para>
2841 </sect3>
2842
2843
2844
2845 <sect3 role="" label="5.5.2.8" id="ch05-SECT-5.2.8">
2846 <indexterm id="ch05-idx-970622-0"><primary>veto oplock files option</primary></indexterm>
2847 <title>
2848 veto oplock files</title>
2849
2850
2851 <para>You can provide a list of filenames that are never granted opportunistic locks with the <literal>veto</literal> <literal>oplock</literal> <literal>files</literal> option. This option can be set either globally or on a per-share basis. For example:</para>
2852
2853
2854 <programlisting>veto oplock files = /*.bat/*.htm/</programlisting>
2855
2856
2857 <para>The value of this option is a series of patterns. Each pattern entry must begin, end, or be separated from another with a slash ( / ) character, even if there is only one pattern listed. Asterisks can be used as a wildcard to represent zero or more characters. Questions marks can be used to represent exactly one character.</para>
2858
2859
2860 <para>We recommend that you disable oplocks on any files that are meant to be updated by Unix or are intended to be shared by several processes simultaneously.</para>
2861 </sect3>
2862
2863
2864
2865 <sect3 role="" label="5.5.2.9" id="ch05-SECT-5.2.9">
2866 <indexterm id="ch05-idx-970623-0"><primary>lock directory option</primary></indexterm>
2867 <title>
2868 lock directory</title>
2869
2870
2871 <para>This option (sometimes called <literal>lock</literal> <literal>dir</literal>) specifies the location of a directory where Samba will store SMB deny-mode lock files. Samba stores other files in this directory as well, such as browse lists and its shared memory file. If WINS is enabled, the WINS database is written to this directory as well. The default for this option is specified in the Samba makefile; it is typically <filename>/usr/local/samba/var/locks</filename>. You can override this location as follows:</para>
2872
2873
2874 <programlisting>[global]
2875         lock directory = /usr/local/samba/locks</programlisting>
2876
2877
2878 <para>You typically would not need to override this option, unless you want to move the lock files to a more standardized location, such<indexterm id="ch05-idx-969871-0" class="endofrange" startref="ch05-idx-969867-0"/>
2879 <indexterm id="ch05-idx-969871-1" class="endofrange" startref="ch05-idx-969867-1"/> as<indexterm id="ch05-idx-969860-0" class="endofrange" startref="ch05-idx-969857-0"/>
2880 <indexterm id="ch05-idx-969860-1" class="endofrange" startref="ch05-idx-969857-1"/>
2881 <indexterm id="ch05-idx-969860-2"><primary>opportunistic locking</primary><seealso>oplocks</seealso></indexterm> <filename>/var/spool/locks</filename>.<indexterm id="ch05-idx-969562-0" class="endofrange" startref="ch05-idx-969559-1"/></para>
2882 </sect3>
2883 </sect2>
2884 </sect1>
2885 </chapter>