Correct "hexidecimal" typos.
[sfrench/samba-autobuild/.git] / docs-xml / using_samba / ch04.xml
1 <chapter label="4" id="ch04-21486">
2 <title>Disk Shares </title>
3
4
5
6
7 <para>
8 <indexterm id="ch04-idx-967030-0" class="startofrange"><primary>disk shares</primary></indexterm>In the previous three chapters, we showed you how to install Samba on a Unix server and set up Windows clients to use a simple disk share. This chapter will show you how Samba can assume more productive roles on your network.</para>
9
10
11 <para>Samba's <indexterm id="ch04-idx-967124-0"><primary>daemons</primary></indexterm>daemons, <emphasis>smbd</emphasis>
12 <indexterm id="ch04-idx-967122-0"><primary>smbd daemon</primary></indexterm> and <emphasis>nmbd</emphasis>
13 <indexterm id="ch04-idx-967123-0"><primary>nmbd daemon</primary></indexterm>, are controlled through a single ASCII file, <filename>smb.conf</filename>, that can contain over 200 unique options. These options define how Samba reacts to the network around it, including everything from simple permissions to encrypted connections and NT domains. The next five chapters are designed to help you get familiar with this file and its options. Some of these options you will use and change frequently; others you may never use&mdash;it all depends on how much functionality you want Samba to offer its clients.</para>
14
15
16 <para>This chapter introduces the structure of the Samba configuration file and shows you how to use these options to create and modify disk shares. Subsequent chapters will discuss browsing, how to configure users, security, domains, and printers, and a host of other myriad topics that you can implement with Samba on your network.</para>
17
18
19
20
21
22
23
24
25
26
27
28 <sect1 role="" label="4.1" id="ch04-76968">
29 <title>Learning the Samba Configuration File</title>
30
31
32 <para><filename></filename>
33 <indexterm id="ch04-idx-968372-0" class="startofrange"><primary>smb.conf (Samba configuration) file</primary></indexterm>Here is an <filename></filename>
34 <indexterm id="ch04-idx-968374-0"><primary>smb.conf (Samba configuration) file</primary><secondary>example of</secondary></indexterm>example of a Samba configuration file. If you have worked with a Windows .INI file, the structure of the <filename>smb.conf </filename> file should look very familiar:</para>
35
36
37 <programlisting>[global]
38         log level = 1
39         max log size = 1000
40         socket options = TCP_NODELAY IPTOS_LOWDELAY
41         guest ok = no
42 [homes]
43         browseable = no
44         map archive = yes
45 [printers]
46         path = /usr/tmp
47         guest ok = yes
48         printable = yes
49 [test]
50         browseable = yes
51         read only = yes
52         guest ok = yes
53         path = /export/samba/test</programlisting>
54
55
56 <para>Although you may not understand the contents yet, this is a good configuration file to grab if you're in a hurry. (If you're not, we'll create a new one from scratch shortly.) In a nutshell, this configuration file sets up basic debug logging in a default log file not to exceed 1MB, optimizes TCP/IP socket connections between the Samba server and any SMB clients, and allows Samba to create a disk share for each user that has a standard Unix account on the server. In addition, each of the printers registered on the server will be publicly available, as will a single read-only share that maps to the <filename>/export/samba/test</filename> directory. The last part of this file is similar to the disk share you used to test Samba in <link linkend="SAMBA-CH-2">Chapter 2</link>.</para>
57
58
59 <sect2 role="" label="4.1.1" id="ch04-52415">
60 <title>Configuration File Structure</title>
61
62
63 <para><filename></filename>
64 <indexterm id="ch04-idx-967054-0" class="startofrange"><primary>smb.conf (Samba configuration) file</primary><secondary>structure of</secondary></indexterm>Let's take another look at this configuration file, this time from a higher level:</para>
65
66
67 <programlisting>[global]
68         ...
69 [homes]
70         ...
71 [printers]
72         ...
73 [test]
74         ...</programlisting>
75
76
77 <para>The names inside the <indexterm id="ch04-idx-967103-0"><primary>square brackets</primary></indexterm>square brackets delineate unique sections of the <filename>smb.conf</filename> file; each <indexterm id="ch04-idx-967104-0"><primary>sections of smb.conf (Samba configuration) file</primary></indexterm>section names the <firstterm>share</firstterm>
78 <indexterm id="ch04-idx-967105-0"><primary>shares</primary></indexterm> (or <indexterm id="ch04-idx-967106-0"><primary>services</primary></indexterm>service) that the section refers to. For example, the <literal>[test]</literal> and <literal>[homes]</literal> sections are each unique disk shares; they contain options that map to specific directories on the Samba server. The <literal>[printers]</literal> share contains options that map to various printers on the server. All the sections defined in the <filename>smb.conf</filename> file, with the exception of the <literal>[global]</literal> section, will be available as a disk or printer share to clients connecting to the Samba server.</para>
79
80
81 <para>The remaining lines are individual configuration options unique to that share. These options will continue until a new bracketed section is encountered, or until the end of the file is reached. Each <indexterm id="ch04-idx-967107-0"><primary>configuration options</primary><secondary>format of</secondary></indexterm>
82 <indexterm id="ch04-idx-967107-1"><primary>smb.conf (Samba configuration) file</primary><secondary>options for</secondary><tertiary>format of</tertiary></indexterm>configuration option follows a simple format:</para>
83
84
85 <programlisting><replaceable>option</replaceable> = <replaceable>value</replaceable></programlisting>
86
87
88 <para>Options in the <filename>smb.conf</filename> file are set by assigning a value to them. We should warn you up front that some of the <indexterm id="ch04-idx-967109-0"><primary>option names</primary></indexterm>option names in Samba are poorly chosen. For example, <literal>read</literal> <literal>only</literal> is self-explanatory, and is typical of many recent Samba options. <literal>public</literal> is an older option, and is vague; it now has a less-confusing synonym <literal>guest</literal> <literal>ok</literal> (may be accessed by guests). We describe some of the more common historical names in this chapter in sections that highlight each major task. In addition,  <link linkend="SAMBA-AP-C">Appendix C</link>, contains an alphabetical index of all the configuration options and their meanings.</para>
89
90
91 <sect3 role="" label="4.1.1.1" id="ch04-SECT-1.1.1">
92 <title>Whitespaces, quotes, and commas</title>
93
94
95 <para>An important item to remember about configuration options is that all <indexterm id="ch04-idx-967110-0"><primary>whitespaces in values</primary></indexterm>whitespaces in the <replaceable>value</replaceable> are significant. For example, consider the following option:</para>
96
97
98 <programlisting>volume = The Big Bad Hard Drive Number 3543</programlisting>
99
100
101 <para>Samba strips away the spaces between the final <literal>e</literal> in <literal>volume</literal> and the first <literal>T</literal> in <literal>The</literal>. These whitespaces are insignificant. The rest of the whitespaces are significant and will be recognized and preserved by Samba when reading in the file. Space is not significant in option names (such as <literal>guest</literal> <literal>ok</literal>), but we recommend you follow convention and keep spaces between the words of options.</para>
102
103
104 <para>If you feel safer including <indexterm id="ch04-idx-967111-0"><primary>quotation marks in values</primary></indexterm>quotation marks at the beginning and ending of a configuration option's value, you may do so. Samba will ignore these quotation marks when it encounters them. Never use quotation marks around an option itself; Samba will treat this as an error.</para>
105
106
107 <para>Finally, you can use whitespaces to separate a series of values in a list, or you can use commas. These two options are equivalent:</para>
108
109
110 <programlisting>netbios aliases = sales, accounting, payroll
111 netbios aliases = sales accounting payroll</programlisting>
112
113
114 <para>In some values, however, you must use one form of separation&mdash;<indexterm id="ch04-idx-967367-0"><primary>spaces in values</primary></indexterm>spaces in some cases, <indexterm id="ch04-idx-967112-0"><primary>commas in values</primary></indexterm>commas in others.</para>
115 </sect3>
116
117
118
119 <sect3 role="" label="4.1.1.2" id="ch04-SECT-1.1.2">
120 <title>Capitalization</title>
121
122
123 <para>
124 <indexterm id="ch04-idx-967113-0"><primary>capitalization</primary></indexterm>Capitalization is not important in the Samba configuration file except in locations where it would confuse the underlying operating system. For example, let's assume that you included the following option in a share that pointed to <filename>/export/samba/simple </filename>:</para>
125
126
127 <programlisting>PATH = /EXPORT/SAMBA/SIMPLE</programlisting>
128
129
130 <para>Samba would have no problem with the <literal>path</literal> configuration option appearing entirely in capital letters. However, when it tries to connect to the given directory, it would be unsuccessful because the Unix filesystem in the underlying operating system <emphasis>is</emphasis> case sensitive. Consequently, the path listed would not be found and clients would be unable to connect to the share.</para>
131 </sect3>
132
133
134
135 <sect3 role="" label="4.1.1.3" id="ch04-SECT-1.1.3">
136 <title>Line continuation</title>
137
138
139 <para>You can continue a <indexterm id="ch04-idx-967114-0"><primary>line contiinuation</primary></indexterm>line in the Samba configuration file using the <indexterm id="ch04-idx-967115-0"><primary>\ (backslash) in smb.conf file</primary></indexterm>
140 <indexterm id="ch04-idx-967115-1"><primary>backslash (\) in smb.conf file</primary></indexterm>backslash, as follows:</para>
141
142
143 <programlisting>comment = The first share that has the primary copies \
144           of the new Teamworks software product.</programlisting>
145
146
147 <para>Because of the backslash, these two lines will be treated as one line by Samba. The second line begins at the first non-whitespace character that Samba encounters; in this case, the <literal>o</literal> in <literal>of</literal>.</para>
148 </sect3>
149
150
151
152 <sect3 role="" label="4.1.1.4" id="ch04-SECT-1.1.4">
153 <title>Comments</title>
154
155
156 <para>You can insert <indexterm id="ch04-idx-967118-0"><primary>comments in smb.conf (Samba configuration) file</primary></indexterm>comments in the <filename>smb.conf</filename> configuration file by preceding a line with either a<indexterm id="ch04-idx-967119-0"><primary>hash mark (#) in comments</primary></indexterm>
157 <indexterm id="ch04-idx-967119-1"><primary># (hash mark)</primary></indexterm> hash mark (#) or a<indexterm id="ch04-idx-967120-0"><primary>semicolon (;) in configuration file comments</primary></indexterm>
158 <indexterm id="ch04-idx-967120-1"><primary>; (semicolon)</primary></indexterm> semicolon ( ; ). Both characters are equivalent. For example, the first three lines in the following example would be considered comments:</para>
159
160
161 <programlisting>#  This is the printers section. We have given a minimum print
162 ;  space of 2000 to prevent some errors that we've seen when
163 ;  the spooler runs out of space.
164
165 [printers]
166         public = yes
167         min print space = 2000</programlisting>
168
169
170 <para>Samba will ignore all comment lines in its configuration file; there are no limitations to what can be placed on a comment line after the initial hash mark or semicolon. Note that the line <indexterm id="ch04-idx-967121-0"><primary>continuation character (\) in comments</primary></indexterm>
171 <indexterm id="ch04-idx-967121-1"><primary>\ (continuation character)</primary></indexterm>continuation character (<literal>\</literal>) will <emphasis>not</emphasis> be honored on a commented line. Like the rest of the line, it is ignored.</para>
172 </sect3>
173
174
175
176 <sect3 role="" label="4.1.1.5" id="ch04-SECT-1.1.5">
177 <title>Changes at runtime</title>
178
179
180 <para>
181 <indexterm id="ch04-idx-967126-0"><primary>changes at runtime</primary></indexterm>You can modify the <filename>smb.conf</filename> configuration file and any of its options at any time while the Samba daemons are running. By default, Samba checks the configuration file every 60 seconds for changes. If it finds any, the changes are immediately put into effect. If you don't wish to wait that long, you can force a reload by either sending a <indexterm id="ch04-idx-967127-0"><primary>SIGHUP signal</primary></indexterm>SIGHUP signal to the <emphasis>smbd</emphasis> and <emphasis>nmbd</emphasis> processes, or simply restarting the daemons.</para>
182
183
184 <para>For example, if the <emphasis>smbd</emphasis> <indexterm id="ch04-idx-967128-0"><primary>processes</primary><see>daemons</see></indexterm>
185 <indexterm id="ch04-idx-967128-1"><primary>daemons</primary><seealso>smbd daemon; nmbd daemon</seealso></indexterm>
186 <indexterm id="ch04-idx-967128-2"><primary>nmbd daemon</primary></indexterm>process was 893, you could force it to reread the configuration file with the following command:</para>
187
188
189 <programlisting># <emphasis role="bold">kill -SIGHUP 893</emphasis></programlisting>
190
191
192 <para>Not all changes will be immediately recognized by clients. For example, changes to a share that is currently in use will not be registered until the client disconnects and reconnects to that share. In addition, server-specific parameters such as the workgroup or NetBIOS name of the server will not register immediately either. This keeps active clients from being suddenly disconnected or encountering unexpected access problems while a session is open.<filename></filename>
193 <indexterm id="ch04-idx-967061-0" class="endofrange" startref="ch04-idx-967054-0"/></para>
194 </sect3>
195 </sect2>
196
197
198
199
200
201 <sect2 role="" label="4.1.2" id="ch04-87365">
202 <title>Variables</title>
203
204
205 <para><filename></filename>
206 <indexterm id="ch04-idx-967393-0" class="startofrange"><primary>smb.conf (Samba configuration) file</primary><secondary>variables for</secondary></indexterm>
207 <indexterm id="ch04-idx-967393-1" class="startofrange"><primary>variables</primary></indexterm>Samba includes a complete set of variables for determining characteristics of the Samba server and the clients to which it connects. Each of these variables begins with a <indexterm id="ch04-idx-967129-0"><primary>percent sign (%) in variables</primary></indexterm>
208 <indexterm id="ch04-idx-967129-1"><primary>% (percent sign)</primary></indexterm>percent sign, followed by a single uppercase or lowercase letter, and can be used only on the right side of a configuration option (e.g., after the equal sign):</para>
209
210
211 <programlisting>[pub]
212     path = /home/ftp/pub/%a</programlisting>
213
214
215 <para>The <literal>%a</literal> stands for the client machine's architecture (e.g., <literal>WinNT</literal> for Windows NT, <literal>Win95</literal> for Windows 95 or 98, or <literal>WfWg</literal> for Windows for Workgroups). Because of this, Samba will assign a unique <indexterm id="ch04-idx-967130-0"><primary>paths, architecture-specific</primary></indexterm>path for the <literal>[pub]</literal> share to client machines running Windows NT, a different path for client machines running Windows 95, and another path for Windows for Workgroups. In other words, the paths that each client would see as its share differ according to the client's architecture, as follows:</para>
216
217
218 <programlisting>/home/ftp/pub/WinNT
219 /home/ftp/pub/Win95
220 /home/ftp/pub/WfWg</programlisting>
221
222
223 <para>Using variables in this manner comes in handy if you wish to have different users run custom configurations based on their own unique characteristics or conditions. Samba has 19 variables, as shown in <link linkend="ch04-10883">Table 4.1</link>.</para>
224
225
226 <table label="4.1" id="ch04-10883">
227 <title>Samba Variables </title>
228
229 <tgroup cols="2">
230 <colspec colnum="1" colname="col1"/>
231 <colspec colnum="2" colname="col2"/>
232 <thead>
233 <row>
234
235 <entry colname="col1"><para>Variable</para></entry>
236
237 <entry colname="col2"><para>Definition</para></entry>
238
239 </row>
240
241 </thead>
242
243 <tbody>
244 <row>
245
246 <entry namest="col1" nameend="col2"><para><emphasis role="bold">
247 <indexterm id="ch04-idx-968086-0"><primary>client variables</primary></indexterm>Client variables</emphasis></para></entry>
248
249 </row>
250
251 <row>
252
253 <entry colname="col1"><para><literal>%a</literal></para></entry>
254
255 <entry colname="col2"><para><filename></filename>
256 <indexterm id="ch04-idx-968093-0"><primary>smb.conf (Samba configuration) file</primary><secondary>variables for</secondary><tertiary>list of</tertiary></indexterm>Client's architecture (e.g., Samba, WfWg, WinNT, Win95, or UNKNOWN)</para></entry>
257
258 </row>
259
260 <row>
261
262 <entry colname="col1"><para><literal>%I</literal></para></entry>
263
264 <entry colname="col2"><para>Client's IP address (e.g., 192.168.220.100)</para></entry>
265
266 </row>
267
268 <row>
269
270 <entry colname="col1"><para><literal>%m</literal></para></entry>
271
272 <entry colname="col2"><para>Client's NetBIOS name</para></entry>
273
274 </row>
275
276 <row>
277
278 <entry colname="col1"><para><literal>%M</literal></para></entry>
279
280 <entry colname="col2"><para>Client's DNS name</para></entry>
281
282 </row>
283
284 <row>
285
286 <entry namest="col1" nameend="col2"><para><emphasis role="bold">
287 <indexterm id="ch04-idx-968108-0"><primary>user variables</primary></indexterm>User variables</emphasis></para></entry>
288
289 </row>
290
291 <row>
292
293 <entry colname="col1"><para><literal>%g</literal></para></entry>
294
295 <entry colname="col2"><para>Primary group of <literal>%u</literal></para></entry>
296
297 </row>
298
299 <row>
300
301 <entry colname="col1"><para><literal>%G</literal></para></entry>
302
303 <entry colname="col2"><para>Primary group of <literal>%U</literal></para></entry>
304
305 </row>
306
307 <row>
308
309 <entry colname="col1"><para><literal>%H</literal></para></entry>
310
311 <entry colname="col2"><para>Home directory of <literal>%u</literal></para></entry>
312
313 </row>
314
315 <row>
316
317 <entry colname="col1"><para><literal>%u</literal></para></entry>
318
319 <entry colname="col2"><para>Current Unix username</para></entry>
320
321 </row>
322
323 <row>
324
325 <entry colname="col1"><para><literal>%U</literal></para></entry>
326
327 <entry colname="col2"><para>Requested client username (not always used by Samba)</para></entry>
328
329 </row>
330
331 <row>
332
333 <entry namest="col1" nameend="col2"><para><emphasis role="bold">Share variables</emphasis></para></entry>
334
335 </row>
336
337 <row>
338
339 <entry colname="col1"><para><literal>%p</literal></para></entry>
340
341 <entry colname="col2"><para>Automounter's path to the share's root directory, if different from <literal>%P</literal></para></entry>
342
343 </row>
344
345 <row>
346
347 <entry colname="col1"><para><literal>%P</literal></para></entry>
348
349 <entry colname="col2"><para>Current share's root directory</para></entry>
350
351 </row>
352
353 <row>
354
355 <entry colname="col1"><para><literal>%S</literal></para></entry>
356
357 <entry colname="col2"><para>Current share's name</para></entry>
358
359 </row>
360
361 <row>
362
363 <entry namest="col1" nameend="col2"><para><emphasis role="bold">Server variables</emphasis></para></entry>
364
365 </row>
366
367 <row>
368
369 <entry colname="col1"><para><literal>%d</literal></para></entry>
370
371 <entry colname="col2"><para>Current server process ID</para></entry>
372
373 </row>
374
375 <row>
376
377 <entry colname="col1"><para><literal>%h</literal></para></entry>
378
379 <entry colname="col2"><para>Samba server's DNS hostname</para></entry>
380
381 </row>
382
383 <row>
384
385 <entry colname="col1"><para><literal>%L</literal></para></entry>
386
387 <entry colname="col2"><para>Samba server's NetBIOS name</para></entry>
388
389 </row>
390
391 <row>
392
393 <entry colname="col1"><para><literal>%N</literal></para></entry>
394
395 <entry colname="col2"><para>Home directory server, from the automount map</para></entry>
396
397 </row>
398
399 <row>
400
401 <entry colname="col1"><para><literal>%v</literal></para></entry>
402
403 <entry colname="col2"><para>Samba version</para></entry>
404
405 </row>
406
407 <row>
408
409 <entry namest="col1" nameend="col2"><para><emphasis role="bold">Miscellaneous variables</emphasis></para></entry>
410
411 </row>
412
413 <row>
414
415 <entry colname="col1"><para><literal>%R</literal></para></entry>
416
417 <entry colname="col2"><para>The SMB protocol level that was negotiated</para></entry>
418
419 </row>
420
421 <row>
422
423 <entry colname="col1"><para><literal>%T</literal></para></entry>
424
425 <entry colname="col2"><para>The current date and time</para></entry>
426
427 </row>
428
429 </tbody>
430 </tgroup>
431 </table>
432
433
434 <para>
435 <indexterm id="ch04-idx-967143-0"><primary>configuration files</primary><secondary>machine-specific</secondary></indexterm>Here's another example of using variables: let's say that there are five clients on your network, but one client, <literal>fred</literal>, requires a slightly different <literal>[homes]</literal> configuration loaded when it connects to the Samba server. With Samba, it's simple to attack such a problem:</para>
436
437
438 <programlisting>[homes]
439         ...
440         include = /usr/local/samba/lib/smb.conf.%m
441         ...</programlisting>
442
443
444 <para>The <literal>include</literal> option here causes a separate configuration file for each particular NetBIOS machine (<literal>%m</literal>) to be read in addition to the current file. If the hostname of the client machine is <literal>fred</literal>, and if a <filename>smb.conf.fred</filename> file exists in the <replaceable>samba_dir</replaceable><filename>/lib/</filename> directory (or whatever directory you've specified for your configuration files), Samba will insert that configuration file into the default one. If any configuration options are restated in <filename>smb.conf.fred</filename>, those values will override any options previously encountered in that share. Note that we say "previously." If any options are restated in the main configuration file after the <literal>include</literal> option, Samba will honor those restated values for the share in which they are defined.</para>
445
446
447 <para>Here's the important part: if there is no such file, Samba will not generate an error. In fact, it won't do anything at all. This allows you to create only one extra configuration file for <literal>fred</literal> when using this strategy, instead of one for each NetBIOS machine that is on the network.</para>
448
449
450 <para>Machine-specific configuration files can be used both to customize particular clients and to make debugging Samba easier. Consider the latter; if we have one client with a problem, we can use this approach to give it a private log file with a more verbose logging level. This allows us to see what Samba is doing without slowing down all the other clients or overflowing the disk with useless logs. Remember, with large networks you may not always have the option to restart the Samba server to perform debugging!</para>
451
452
453 <para>You can use each of the variables in <link linkend="ch04-10883">Table 4.1</link> to give custom values to a variety of Samba options. We will highlight several of these options as we move through the next few chapters.<filename></filename>
454 <indexterm id="ch04-idx-967084-0" class="endofrange" startref="ch04-idx-967393-0"/>
455 <indexterm id="ch04-idx-967084-1" class="endofrange" startref="ch04-idx-967393-1"/></para>
456 </sect2>
457 </sect1>
458
459
460
461
462
463
464
465
466
467 <sect1 role="" label="4.2" id="ch04-81402">
468 <title>Special Sections</title>
469
470
471 <para><filename></filename>
472 <indexterm id="ch04-idx-967091-0" class="startofrange"><primary>smb.conf (Samba configuration) file</primary><secondary>special sections of</secondary></indexterm>
473 <indexterm id="ch04-idx-967091-1" class="startofrange"><primary>special sections, smb.conf (Samba configuration) file</primary></indexterm>Now that we've gotten our feet wet with variables, there are a few special sections of the Samba configuration file that we should talk about. Again, don't worry if you do not understand each and every configuration options listed below; we'll go over each of them over the course of the upcoming chapters.</para>
474
475
476 <sect2 role="" label="4.2.1" id="ch04-SECT-2.1">
477 <title>The [globals] Section</title>
478
479
480 <para>The <literal>[globals]</literal>
481 <indexterm id="ch04-idx-967171-0"><primary sortas="globals section">[globals] section</primary></indexterm>
482 <indexterm id="ch04-idx-967171-1"><primary>shares</primary><secondary sortas="globals section">[globals] section</secondary></indexterm> section appears in virtually every Samba configuration file, even though it is not mandatory to define one. Any option set in this section of the file will apply to all the other shares, as if the contents of the section were copied into the share itself. There is one catch: other sections can list the same option in their section with a new value; this has the effect of overriding the value specified in the <literal>[globals]</literal> section.</para>
483
484
485 <para>To illustrate this, let's again look at the opening example of the chapter:</para>
486
487
488 <programlisting>[global]
489         log level = 1
490         max log size = 1000
491         socket options = TCP_NODELAY IPTOS_LOWDELAY
492         guest ok = no
493 [homes]
494         browseable = no
495         map archive = yes
496 [printers]
497         path = /usr/tmp
498         guest ok = yes
499         printable = yes
500         min print space = 2000
501 [test]
502         browseable = yes
503         read only = yes
504         guest ok = yes
505         path = /export/samba/test</programlisting>
506
507
508 <para>In the previous example, if we were going to connect a client to the <literal>[test]</literal> share, Samba would first read in the <literal>[globals]</literal> section. At that point, it would set the option <literal>guest</literal> <literal>ok</literal> <literal>=</literal> <literal>no</literal> as the global default for each share it encounters throughout the configuration file. This includes the <literal>[homes]</literal> and <literal>[printers]</literal> shares. When it reads in the <literal>[test]</literal> share, however, it would then find the configuration option <literal>guest</literal> <literal>ok</literal> <literal>=</literal> <literal>yes</literal>, and override the default from the <literal>[globals]</literal> section with the value <literal>yes</literal> in the context of the <literal>[pub]</literal> share.</para>
509
510
511 <para>Any option that appears outside of a section (before the first marked section) is also assumed to be a global option.</para>
512 </sect2>
513
514
515
516
517
518 <sect2 role="" label="4.2.2" id="ch04-SECT-2.2">
519 <title>The [ homes] Section</title>
520
521
522 <para>If a client attempts to connect to a share that doesn't appear in the <filename>smb.conf</filename> file, Samba will search for a <literal>[homes]</literal>
523 <indexterm id="ch04-idx-967172-0"><primary sortas="homes share">[homes] share</primary></indexterm> share in the configuration file. If one exists, the unidentified share name is assumed to be a Unix username, which is queried in the password database of the Samba server. If that username appears, Samba assumes the client is a Unix user trying to connect to his or her home directory on the server.</para>
524
525
526 <para>For example, assume a client machine is connecting to the Samba server <literal>hydra</literal> for the first time, and tries to connect to a share named [<literal>alice]</literal>. There is no <literal>[alice]</literal> share defined in the <filename>smb.conf</filename> file, but there is a <literal>[homes]</literal>, so Samba searches the password database file and finds an <literal>alice</literal> user account is present on the system. Samba then checks the password provided by the client against user <literal>alice</literal>'s Unix password&mdash;either with the password database file if it's using non-encrypted passwords, or Samba's <filename>smbpasswd</filename> file if encrypted passwords are in use. If the passwords match, then Samba knows it has guessed right: the user <literal>alice</literal> is trying to connect to her home directory. Samba will then create a share called <literal>[alice]</literal> for her.</para>
527
528
529 <para>The process of using the <literal>[homes]</literal> section to create <indexterm id="ch04-idx-967175-0"><primary>users</primary><secondary>creating</secondary></indexterm>users (and dealing with their passwords) is discussed in more detail in the <link linkend="SAMBA-CH-6">Chapter 6</link>.</para>
530 </sect2>
531
532
533
534
535
536 <sect2 role="" label="4.2.3" id="ch04-SECT-2.3">
537 <title>The [printers] Section</title>
538
539
540 <para>The third special section is called <literal>[printers]</literal>
541 <indexterm id="ch04-idx-967173-0"><primary>print shares</primary></indexterm> and is similar to <literal>[homes]</literal>. If a client attempts to connect to a share that isn't in the <filename>smb.conf</filename>  file, and its name can't be found in the password file, Samba will check to see if it is a printer share. Samba does this by reading the <indexterm id="ch04-idx-967182-0"><primary>printer capabilities file</primary></indexterm>printer capabilities file (usually <filename>/etc/printcap</filename>) to see if the share name appears there.<footnote label="1" id="ch04-pgfId-960558">
542
543
544 <para>Depending on your system, this file may not be <emphasis>/etc/printcap</emphasis>. You can use the <emphasis>testparm</emphasis> command that comes with Samba to determine the value of the <literal>printcap</literal> <literal>name</literal> configuration option; this was the default value chosen when Samba was compiled.</para>
545
546
547 </footnote> If it does, Samba creates a share named after the printer.</para>
548
549
550 <para>Like <literal>[homes]</literal>, this means you don't have to maintain a share for each of your system printers in the <filename>smb.conf</filename>  file. Instead, Samba honors the Unix printer registry if you request it to, and provides the registered printers to the client machines. There is, however, an obvious limitation: if you have an account named <literal>fred</literal> and a printer named <literal>fred</literal>, Samba will always find the user account first, even if the client really needed to connect to the printer.</para>
551
552
553 <para>The process of setting up the <literal>[printers]</literal>
554 <indexterm id="ch04-idx-968220-0"><primary>print shares</primary></indexterm> share is discussed in more detail in <link linkend="SAMBA-CH-7">Chapter 7</link>.<filename></filename>
555 <indexterm id="ch04-idx-968225-0"><primary>configuration files</primary><secondary>smb.conf (Samba configuration) file</secondary><see>smb.conf file</see></indexterm></para>
556 </sect2>
557
558
559
560
561
562 <sect2 role="" label="4.2.4" id="ch04-SECT-2.4">
563 <title>Configuration Options</title>
564
565
566 <para><filename></filename>
567 <indexterm id="ch04-idx-967407-0" class="startofrange"><primary>smb.conf (Samba configuration) file</primary><secondary>options for</secondary></indexterm>Options in the Samba configuration files fall into one of two categories: <firstterm>global</firstterm> or <firstterm>share</firstterm>. Each category dictates where an option can appear in the configuration file.</para>
568
569
570 <variablelist>
571 <varlistentry><term>Global</term>
572 <listitem><para>
573 <indexterm id="ch04-idx-967207-0"><primary>global options</primary></indexterm>Global options <emphasis>must</emphasis> appear in the <literal>[global]</literal> section and nowhere else. These are options that typically apply to the behavior of the Samba server itself, and not to any of its shares.</para></listitem>
574 </varlistentry>
575
576
577 <varlistentry><term>Share</term>
578 <listitem><para>
579 <indexterm id="ch04-idx-967209-0"><primary>share options</primary></indexterm>Share options can appear in specific shares, or they can appear in the <literal>[global]</literal> section. If they appear in the <literal>[global]</literal> section, they will define a default behavior for all shares, unless a share overrides the option with a value of its own.</para></listitem>
580 </varlistentry>
581 </variablelist>
582
583
584 <para>In addition, the values that a configuration option can take can be divided into four categories. They are as follows:</para>
585
586
587 <variablelist>
588 <varlistentry><term>Boolean</term>
589 <listitem><para>
590 <indexterm id="ch04-idx-967210-0"><primary>boolean type</primary></indexterm>These are simply yes or no values, but can be represented by any of the following: <literal>yes</literal>, <literal>no</literal>, <literal>true</literal>, <literal>false</literal>, <literal>0</literal>, <literal>1</literal>. The values are case insensitive: <literal>YES</literal> is the same as <literal>yes</literal>.</para></listitem>
591 </varlistentry>
592
593
594 <varlistentry><term>Numerical</term>
595 <listitem><para>
596 <indexterm id="ch04-idx-967220-0"><primary>numerical type</primary></indexterm>An integer, hexadecimal, or octal number. The standard <literal>0x</literal><emphasis>nn</emphasis> syntax is used for hexadecimal and <literal>0</literal><emphasis>nnn</emphasis> for octal.</para></listitem>
597 </varlistentry>
598
599
600 <varlistentry><term>String</term>
601 <listitem><para>A <indexterm id="ch04-idx-967222-0"><primary>string types</primary></indexterm>string of case-sensitive characters, such as a filename or a username.</para></listitem>
602 </varlistentry>
603
604
605 <varlistentry><term>Enumerated list</term>
606 <listitem><para>A finite list of known values. In effect, a boolean is an <indexterm id="ch04-idx-967223-0"><primary>enumerated lists</primary></indexterm>enumerated list with only two values.<filename></filename>
607 <indexterm id="ch04-idx-967166-0" class="endofrange" startref="ch04-idx-967091-0"/>
608 <indexterm id="ch04-idx-967166-1" class="endofrange" startref="ch04-idx-967091-1"/></para></listitem>
609 </varlistentry>
610 </variablelist>
611 </sect2>
612 </sect1>
613
614
615
616
617
618
619
620
621
622 <sect1 role="" label="4.3" id="ch04-46076">
623 <title>Configuration File Options</title>
624
625
626 <para>Samba has well over 200 configuration options at its disposal. So let's start off easy by introducing some of the options you can use to modify the configuration file itself.</para>
627
628
629 <para>As we hinted earlier in the chapter, configuration files are by no means static. You can instruct Samba to include or even replace configuration options as it is processing them. The options to do this are summarized in <link linkend="ch04-94939">Table 4.2</link>.</para>
630
631
632 <table label="4.2" id="ch04-94939">
633 <title>Configuration File Options </title>
634
635 <tgroup cols="5">
636 <colspec colnum="1" colname="col1"/>
637 <colspec colnum="2" colname="col2"/>
638 <colspec colnum="3" colname="col3"/>
639 <colspec colnum="4" colname="col4"/>
640 <colspec colnum="5" colname="col5"/>
641 <thead>
642 <row>
643
644 <entry colname="col1"><para>Option</para></entry>
645
646 <entry colname="col2"><para>Parameters</para></entry>
647
648 <entry colname="col3"><para>Function</para></entry>
649
650 <entry colname="col4"><para>Default</para></entry>
651
652 <entry colname="col5"><para>Scope</para></entry>
653
654 </row>
655
656 </thead>
657
658 <tbody>
659 <row>
660
661 <entry colname="col1"><para><literal>config file</literal></para></entry>
662
663 <entry colname="col2"><para>string (fully-qualified name)</para></entry>
664
665 <entry colname="col3"><para>Sets the location of a configuration file to use instead of the current one.</para></entry>
666
667 <entry colname="col4"><para>None</para></entry>
668
669 <entry colname="col5"><para>Global</para></entry>
670
671 </row>
672
673 <row>
674
675 <entry colname="col1"><para><literal>include</literal></para></entry>
676
677 <entry colname="col2"><para>string (fully-qualified name)</para></entry>
678
679 <entry colname="col3"><para>Specifies an additional segment of configuration options to be included at this point in the configuration file.</para></entry>
680
681 <entry colname="col4"><para>None</para></entry>
682
683 <entry colname="col5"><para>Global</para></entry>
684
685 </row>
686
687 <row>
688
689 <entry colname="col1"><para><literal>copy</literal></para></entry>
690
691 <entry colname="col2"><para>string (name of share)</para></entry>
692
693 <entry colname="col3"><para>Allows you to clone the configuration options of another share in the current share.</para></entry>
694
695 <entry colname="col4"><para>None</para></entry>
696
697 <entry colname="col5"><para>Share</para></entry>
698
699 </row>
700
701 </tbody>
702 </tgroup>
703 </table>
704
705
706 <sect2 role="" label="4.3.1" id="ch04-SECT-3.0.1">
707 <indexterm id="ch04-idx-968272-0"><primary>config file option</primary></indexterm>
708 <title>
709 config file</title>
710
711
712 <para>The global <literal>config</literal> <literal>file</literal> option specifies a replacement configuration file that will be loaded when the option is encountered. If the target file exists, the remainder of the current configuration file, as well as the options encounter so far, will be discarded; Samba will configure itself entirely with the options in the new file. The <literal>config</literal> <literal>file</literal> option takes advantage of the variables above, which is useful in the event that you want load a special configuration file based on the machine name or user of the client that it connecting.</para>
713
714
715 <para>For example, the following line instructs Samba to use a configuration file specified by the NetBIOS name of the client connecting, if such a file exists. If it does, options specified in the original configuration file are ignored. The following example attempts to lead a new configuration file based on the client's NetBIOS name:</para>
716
717
718 <programlisting>[global]
719         config file = /usr/local/samba/lib/smb.conf.%m</programlisting>
720
721
722 <para>If the configuration file specified does not exist, the option is ignored and Samba will continue to configure itself based on the current file.</para>
723 </sect2>
724
725
726
727
728
729 <sect2 role="" label="4.3.2" id="ch04-SECT-3.0.2">
730 <indexterm id="ch04-idx-968282-0"><primary>include option</primary></indexterm>
731 <title>
732 include</title>
733
734
735 <para>This option, discussed in greater detail earlier, copies the target file into the current configuration file at the point specified, as shown in <link linkend="ch04-97340">Figure 4.1</link>. This option also takes advantage of the variables specified earlier in the chapter, which is useful in the event that you want load configuration options based on the machine name or user of the client that it connecting. You can use this option as follows:</para>
736
737
738 <programlisting>[global]
739         include = /usr/local/samba/lib/smb.conf.%m</programlisting>
740
741
742 <para>If the configuration file specified does not exist, the option is ignored. Remember that any option specified previously is overridden. In <link linkend="ch04-97340">Figure 4.1</link>, all three options will override their previous values.</para>
743
744
745 <figure label="4.1" id="ch04-97340">
746 <title>The include option in a Samba configuration file</title>
747
748 <graphic width="502" depth="232" fileref="figs/sam.0401.gif"></graphic>
749 </figure>
750
751 <para>The <literal>include</literal> option cannot understand the variables <literal>%u</literal> (user), <literal>%p</literal> (current share's rout directory), or <literal>%s</literal> (current share) because they are not set at the time the file is read.</para>
752 </sect2>
753
754
755
756
757
758 <sect2 role="" label="4.3.3" id="ch04-SECT-3.0.3">
759 <indexterm id="ch04-idx-968285-0"><primary>copy option</primary></indexterm>
760 <title>
761 copy</title>
762
763
764 <para>The <literal>copy</literal> configuration option allows you to clone the configuration options of the share name that you specify in the current share. The target share must appear earlier in the configuration file than the share that is performing the copy. For example:</para>
765
766
767 <programlisting>[template]
768         writable = yes
769         browsable = yes
770         valid users = andy, dave, peter
771
772 [data]
773         path = /usr/local/samba
774         copy = template</programlisting>
775
776
777 <para>Note that any options in the share that invoked the <literal>copy</literal> directive will override those in the cloned share; it does not matter whether they appear before or after the <literal>copy</literal><filename></filename>
778 <indexterm id="ch04-idx-968230-0" class="endofrange" startref="ch04-idx-967407-0"/> directive.<filename></filename>
779 <indexterm id="ch04-idx-967416-0" class="endofrange" startref="ch04-idx-968372-0"/></para>
780 </sect2>
781 </sect1>
782
783
784
785
786
787
788
789
790
791 <sect1 role="" label="4.4" id="ch04-71382">
792 <title>Server Configuration</title>
793
794
795 <para>
796 <indexterm id="ch04-idx-967242-0" class="startofrange"><primary>configuring Samba</primary><secondary>server</secondary></indexterm>Now it's time to begin configuring your Samba server. Let's introduce three basic configuration options that can appear in the <literal>[global]</literal> section of your <filename>smb.conf</filename> file:</para>
797
798
799 <programlisting>[global]
800         #  Server configuration parameters
801         netbios name = HYDRA
802         server string = Samba %v on (%L)
803         workgroup = SIMPLE</programlisting>
804
805
806 <para>This configuration file is pretty simple; it advertises the Samba server on a NBT network under the NetBIOS name <literal>hydra</literal>. In addition, the machine belongs to the workgroup SIMPLE and displays a description to clients that includes the Samba version number as well as the NetBIOS name of the Samba server.</para>
807
808
809 <tip role="ora">
810 <para>If you had to enter <literal>encrypt passwords=yes</literal> in your earlier configuration file, you should do so here as well.</para>
811
812 </tip>
813
814 <para>Go ahead and try this configuration file. Create a file named <filename>smb.conf</filename>
815 <indexterm id="ch04-idx-967246-0"><primary>smb.conf (Samba configuration) file</primary><secondary>creating</secondary></indexterm> under the <filename>/usr/local/samba/lib</filename> directory with the text listed above. Then reset the Samba server and use a Windows client to verify the results. Be sure that your Windows clients are in the SIMPLE workgroup as well. After clicking on the <indexterm id="ch04-idx-967247-0"><primary>Network Neighborhood icon</primary></indexterm>Network Neighborhood on a Windows client, you should see a window similar to <link linkend="ch04-38915">Figure 4.2</link>. (In this figure, <literal>phoenix</literal> and <literal>chimaera</literal> are our Windows clients.)</para>
816
817
818 <figure label="4.2" id="ch04-38915">
819 <title>Network Neighborhood showing the Samba server</title>
820
821 <graphic width="502" depth="206" fileref="figs/sam.0402.gif"></graphic>
822 </figure>
823
824 <para>You can verify the <literal>server</literal> <literal>string</literal> by listing the details of the Network Neighborhood window (select the Details menu item under the View menu), at which point you should see a window similar to <link linkend="ch04-50900">Figure 4.3</link>.</para>
825
826
827 <figure label="4.3" id="ch04-50900">
828 <title>Network Neighborhood details listing</title>
829
830 <graphic width="502" depth="220" fileref="figs/sam.0403.gif"></graphic>
831 </figure>
832
833 <para>If you were to click on the Hydra icon, a window should appear that shows the services that it provides. In this case, the window would be completely empty because there are no shares on the server yet.</para>
834
835
836 <sect2 role="" label="4.4.1" id="ch04-SECT-4.1">
837 <title>Server Configuration Options</title>
838
839
840 <para>
841 <indexterm id="ch04-idx-967248-0" class="startofrange"><primary>configuration options</primary><secondary>server</secondary></indexterm>
842 <indexterm id="ch04-idx-967248-1" class="startofrange"><primary>server configuration options</primary></indexterm><link linkend="ch04-61150">Table 4.3</link> summarizes the server configuration options introduced previously. Note that all three of these options are global in scope; in other words, they must appear in the <literal>[global]</literal> section of the configuration file.</para>
843
844
845 <table label="4.3" id="ch04-61150">
846 <title>Server Configuration Options </title>
847
848 <tgroup cols="5">
849 <colspec colnum="1" colname="col1"/>
850 <colspec colnum="2" colname="col2"/>
851 <colspec colnum="3" colname="col3"/>
852 <colspec colnum="4" colname="col4"/>
853 <colspec colnum="5" colname="col5"/>
854 <thead>
855 <row>
856
857 <entry colname="col1"><para>Option</para></entry>
858
859 <entry colname="col2"><para>Parameters</para></entry>
860
861 <entry colname="col3"><para>Function</para></entry>
862
863 <entry colname="col4"><para>Default</para></entry>
864
865 <entry colname="col5"><para>Scope</para></entry>
866
867 </row>
868
869 </thead>
870
871 <tbody>
872 <row>
873
874 <entry colname="col1"><para><literal>netbios name</literal></para></entry>
875
876 <entry colname="col2"><para>string</para></entry>
877
878 <entry colname="col3"><para>Sets the primary NetBIOS name of the Samba server.</para></entry>
879
880 <entry colname="col4"><para>Server DNS hostname</para></entry>
881
882 <entry colname="col5"><para>Global</para></entry>
883
884 </row>
885
886 <row>
887
888 <entry colname="col1"><para><literal>server string</literal></para></entry>
889
890 <entry colname="col2"><para>string</para></entry>
891
892 <entry colname="col3"><para>Sets a descriptive string for the Samba server.</para></entry>
893
894 <entry colname="col4"><para><literal>Samba %v</literal></para></entry>
895
896 <entry colname="col5"><para>Global</para></entry>
897
898 </row>
899
900 <row>
901
902 <entry colname="col1"><para><literal>workgroup</literal></para></entry>
903
904 <entry colname="col2"><para>string</para></entry>
905
906 <entry colname="col3"><para>Sets the NetBIOS group of machines that the server belongs to.</para></entry>
907
908 <entry colname="col4"><para>Defined at compile time</para></entry>
909
910 <entry colname="col5"><para>Global</para></entry>
911
912 </row>
913
914 </tbody>
915 </tgroup>
916 </table>
917
918
919 <sect3 role="" label="4.4.1.1" id="ch04-SECT-4.1.1">
920 <indexterm id="ch04-idx-968288-0"><primary>netbios name option</primary></indexterm>
921 <title>
922 netbios name</title>
923
924
925 <para>The <literal>netbios</literal> <literal>name</literal> option allows you to set the NetBIOS name of the server. For example:</para>
926
927
928 <programlisting>netbios name = YORKVM1</programlisting>
929
930
931 <para>The default value for this configuration option is the server's hostname; that is, the first part of its complete DNS machine name. For example, a machine with the DNS name <literal>ruby.ora.com</literal> would be given the NetBIOS name <literal>RUBY</literal> by default. While you can use this option to restate the machine's NetBIOS name in the configuration file (as we did previously), it is more commonly used to assign the Samba server a NetBIOS name other than its current DNS name. Remember that the name given must follow the rules for valid NetBIOS machine names as outlines in <link linkend="ch01-48078">Chapter 1</link>.</para>
932
933
934 <para>Changing the NetBIOS name of the server is not recommended unless you have a good reason. One such reason might be if the hostname of the machine is not unique because the LAN is divided over two or more DNS domains. For example, YORKVM1 is a good NetBIOS candidate for <emphasis>vm1.york.example.com</emphasis> to differentiate it from <emphasis>vm1.falkirk.example.com</emphasis>, which has the same hostname but resides in a different DNS domain.</para>
935
936
937 <para>Another use of this option is for relocating SMB services from a dead or retired machine. For example, if <literal>SALES</literal> is the SMB server for the department, and it suddenly dies, you could immediately reset <literal>netbios</literal> <literal>name</literal> <literal>=</literal> <literal>SALES</literal> on a backup Samba machine that's taking over for it. Users won't have to change their drive mappings to a different machine; new connections to <literal>SALES</literal> will simply go to the new machine.</para>
938 </sect3>
939
940
941
942 <sect3 role="" label="4.4.1.2" id="ch04-SECT-4.1.2">
943 <indexterm id="ch04-idx-968291-0"><primary>server string parameter</primary></indexterm>
944 <title>
945 server string</title>
946
947
948 <para>The <literal>server</literal> <literal>string</literal> parameter defines a comment string that will appear next to the server name in both the Network Neighborhood (when shown with the Details menu) and the comment entry of the Microsoft Windows print manager. You can use the standard variables to provide information in the description. For example, our entry earlier was:</para>
949
950
951 <programlisting>[global]
952         server string = Samba %v on (%h)</programlisting>
953
954
955 <para>The default for this option simply presents the current version of Samba and is equivalent to:</para>
956
957
958 <programlisting>server string = Samba %v</programlisting>
959 </sect3>
960
961
962
963 <sect3 role="" label="4.4.1.3" id="ch04-SECT-4.1.3">
964 <indexterm id="ch04-idx-968294-0"><primary>workgroup parameter</primary></indexterm>
965 <title>
966 workgroup</title>
967
968
969 <para>The <literal>workgroup</literal> parameter sets the current workgroup where the Samba server will advertise itself. Clients that wish to access shares on the Samba server should be on the same NetBIOS workgroup. Remember that workgroups are really just NetBIOS group names, and must follow the standard NetBIOS naming conventions outlined in <link linkend="ch01-48078">Chapter 1</link>. For example:</para>
970
971
972 <programlisting>[global]
973         workgroup = SIMPLE</programlisting>
974
975
976 <para>The default option for this parameter is set at compile time. If the entry is not changed in the makefile, it will be <literal>WORKGROUP</literal>. Because this tends to be the workgroup name of every unconfigured NetBIOS network, we recommend that you always set your workgroup name in the Samba configuration<indexterm id="ch04-idx-967252-0" class="endofrange" startref="ch04-idx-967248-0"/>
977 <indexterm id="ch04-idx-967252-1" class="endofrange" startref="ch04-idx-967248-1"/> file.<footnote label="2" id="ch04-pgfId-962322">
978
979
980 <para>We should also mention that it is an inherently bad idea to have a workgroup that shares the same name as a server.</para>
981
982
983 </footnote>
984 <indexterm id="ch04-idx-967243-0" class="endofrange" startref="ch04-idx-967242-0"/></para>
985 </sect3>
986 </sect2>
987 </sect1>
988
989
990
991
992
993
994
995
996
997 <sect1 role="" label="4.5" id="ch04-14274">
998 <title>Disk Share Configuration</title>
999
1000
1001 <para>
1002 <indexterm id="ch04-idx-967244-0" class="startofrange"><primary>configuring disk shares</primary></indexterm>
1003 <indexterm id="ch04-idx-967244-1" class="startofrange"><primary>disk shares</primary><secondary>configuring</secondary></indexterm>We mentioned in the previous section that there were no disk shares on the <literal>hydra</literal> server. Let's continue with the configuration file and create an empty <indexterm id="ch04-idx-967268-0"><primary>disk shares</primary><secondary>creating</secondary></indexterm>disk share called [<literal>data</literal>]. Here are the additions that will do it:</para>
1004
1005
1006 <programlisting>[global]
1007         netbios name = HYDRA
1008         server string = Samba %v on (%L)
1009         workgroup = SIMPLE
1010
1011 [data]
1012         path = /export/samba/data
1013         comment = Data Drive
1014         volume = Sample-Data-Drive
1015         writeable = yes
1016         guest ok = yes</programlisting>
1017
1018
1019 <para>The <literal>[data]</literal> share is typical for a Samba disk share. The share maps to a directory on the Samba server: <filename>/export/samba/data</filename>. We've also provided a comment that describes the share as a <literal>Data</literal> <literal>Drive</literal>, as well as a volume name for the share itself.</para>
1020
1021
1022 <para>The share is set to writeable so that users can write data to it; the default with Samba is to create a read-only share. As a result, this option needs to be explicitly set for each disk share you wish to make writeable.</para>
1023
1024
1025 <para>You may have noticed that we set the <literal>guest</literal> <literal>ok</literal> parameter to <literal>yes</literal>. While this isn't very security-conscious, there are some password issues that we need to understand before setting up individual users and authentication. For the moment, this will sidestep those issues and let anyone connect to the share.</para>
1026
1027
1028 <para>Go ahead and make these additions to your configuration file. In addition, create the <filename>/export/samba/data</filename> directory as root on your Samba machine with the following commands:</para>
1029
1030
1031 <programlisting># <emphasis role="bold">mkdir /export/samba/data</emphasis>
1032 # <emphasis role="bold">chmod 777 /export/samba/data</emphasis></programlisting>
1033
1034
1035 <para>Now, if you connect to the <literal>hydra</literal> server again (you can do this by clicking on its icon in the Windows Network Neighborhood), you should see a single share listed entitled <literal>data</literal>, as shown in <link linkend="ch04-13866">Figure 4.4</link>. This share should also have read/write access to it. Try creating or copying a file into the share. Or, if you're really feeling adventurous, you can even try mapping a network drive to it!</para>
1036
1037
1038 <figure label="4.4" id="ch04-13866">
1039 <title>The initial data share on the Samba server</title>
1040
1041 <graphic width="502" depth="175" fileref="figs/sam.0404.gif"></graphic>
1042 </figure>
1043
1044 <sect2 role="" label="4.5.1" id="ch04-SECT-5.1">
1045 <title>Disk Share Configuration Options</title>
1046
1047
1048 <para>
1049 <indexterm id="ch04-idx-967272-0" class="startofrange"><primary>configuration options</primary><secondary>disk share</secondary></indexterm>The basic Samba configuration options for disk shares previously introduced are listed in <link linkend="ch04-82964">Table 4.4</link>.</para>
1050
1051
1052 <table label="4.4" id="ch04-82964">
1053 <title>Basic Share Configuration Options </title>
1054
1055 <tgroup cols="5">
1056 <colspec colnum="1" colname="col1"/>
1057 <colspec colnum="2" colname="col2"/>
1058 <colspec colnum="3" colname="col3"/>
1059 <colspec colnum="4" colname="col4"/>
1060 <colspec colnum="5" colname="col5"/>
1061 <thead>
1062 <row>
1063
1064 <entry colname="col1"><para>Option</para></entry>
1065
1066 <entry colname="col2"><para>Parameters</para></entry>
1067
1068 <entry colname="col3"><para>Function</para></entry>
1069
1070 <entry colname="col4"><para>Default</para></entry>
1071
1072 <entry colname="col5"><para>Scope</para></entry>
1073
1074 </row>
1075
1076 </thead>
1077
1078 <tbody>
1079 <row>
1080
1081 <entry colname="col1"><para><literal>path (directory)</literal></para></entry>
1082
1083 <entry colname="col2"><para>string (fully-qualified pathname)</para></entry>
1084
1085 <entry colname="col3"><para>Sets the Unix directory that will be provided for a disk share or used for spooling by a printer share</para></entry>
1086
1087 <entry colname="col4"><para><literal>/tmp</literal></para></entry>
1088
1089 <entry colname="col5"><para>Share</para></entry>
1090
1091 </row>
1092
1093 <row>
1094
1095 <entry colname="col1"><para><literal>guest ok (public)</literal></para></entry>
1096
1097 <entry colname="col2"><para>boolean</para></entry>
1098
1099 <entry colname="col3"><para>If set to <literal>yes</literal>, authentication is not needed to access this share</para></entry>
1100
1101 <entry colname="col4"><para><literal>no</literal></para></entry>
1102
1103 <entry colname="col5"><para>Share</para></entry>
1104
1105 </row>
1106
1107 <row>
1108
1109 <entry colname="col1"><para><literal>comment</literal></para></entry>
1110
1111 <entry colname="col2"><para>string</para></entry>
1112
1113 <entry colname="col3"><para>Sets the comment that appears with the share</para></entry>
1114
1115 <entry colname="col4"><para>None</para></entry>
1116
1117 <entry colname="col5"><para>Share</para></entry>
1118
1119 </row>
1120
1121 <row>
1122
1123 <entry colname="col1"><para><literal>volume</literal></para></entry>
1124
1125 <entry colname="col2"><para>string</para></entry>
1126
1127 <entry colname="col3"><para>Sets the volume name: the DOS name of the physical drive</para></entry>
1128
1129 <entry colname="col4"><para>Share name</para></entry>
1130
1131 <entry colname="col5"><para>Share</para></entry>
1132
1133 </row>
1134
1135 <row>
1136
1137 <entry colname="col1"><para><literal>read only</literal></para></entry>
1138
1139 <entry colname="col2"><para>boolean</para></entry>
1140
1141 <entry colname="col3"><para>If <literal>yes</literal>, allows read only access to a share.</para></entry>
1142
1143 <entry colname="col4"><para><literal>yes</literal></para></entry>
1144
1145 <entry colname="col5"><para>Share</para></entry>
1146
1147 </row>
1148
1149 <row>
1150
1151 <entry colname="col1"><para><literal>writeable (write ok)</literal></para></entry>
1152
1153 <entry colname="col2"><para>boolean</para></entry>
1154
1155 <entry colname="col3"><para>If <literal>no</literal>, allows read only access to a share.</para></entry>
1156
1157 <entry colname="col4"><para><literal>no</literal></para></entry>
1158
1159 <entry colname="col5"><para>Share</para></entry>
1160
1161 </row>
1162
1163 </tbody>
1164 </tgroup>
1165 </table>
1166
1167
1168 <sect3 role="" label="4.5.1.1" id="ch04-SECT-5.1.1">
1169 <title>path</title>
1170
1171
1172 <para>
1173 <indexterm id="ch04-idx-967257-0"><primary>pathnames</primary><secondary>option for</secondary></indexterm>
1174 <indexterm id="ch04-idx-967257-1"><primary>shares</primary><secondary>file, path option for</secondary></indexterm>
1175 <indexterm id="ch04-idx-967257-2"><primary>print shares</primary><secondary>path option</secondary></indexterm>This option, which has the synonym <literal>directory</literal>, indicates the pathname at the root of the file or printing share. You can choose any path on the Samba server, so long as the owner of the Samba process that is connecting has read and write access to that directory. If the path is for a printing share, it should point to a temporary directory where files can be written on the server before being spooled to the target printer ( <filename> /tmp</filename> and <filename>/var/spool</filename> are popular choices). If this path is for a <indexterm id="ch04-idx-967258-0"><primary>disk shares</primary><secondary>path option</secondary></indexterm>disk share, the contents of the folder representing the share name on the client will match the content of the directory on the Samba server. For example, if we have the following disk share listed in our configuration file:</para>
1176
1177
1178 <programlisting>[network]
1179         path = /export/samba/network
1180         writable = yes
1181         guest ok = yes</programlisting>
1182
1183
1184 <para>And the contents of the directory <filename>/usr/local/network</filename> on the Unix side are:</para>
1185
1186
1187 <programlisting>$ <emphasis role="bold">ls -al /export/samba/network</emphasis>
1188 drwxrwxrwx  9  root   nobody  1024  Feb 16 17:17  .
1189 drwxr-xr-x  9  nobody nobody  1024  Feb 16 17:17  ..
1190 drwxr-xr-x  9  nobody nobody  1024  Feb 16 17:17  quicken
1191 drwxr-xr-x  9  nobody nobody  1024  Feb 16 17:17  tax98
1192 drwxr-xr-x  9  nobody nobody  1024  Feb 16 17:17  taxdocuments</programlisting>
1193
1194
1195 <para>Then we should see the equivalent of <link linkend="ch04-88746">Figure 4.5</link> on the client side.</para>
1196
1197
1198 <figure label="4.5" id="ch04-88746">
1199 <title>Windows client view of a network filesystem specified by path</title>
1200
1201 <graphic width="502" depth="155" fileref="figs/sam.0405.gif"></graphic>
1202 </figure>
1203 </sect3>
1204
1205
1206
1207 <sect3 role="" label="4.5.1.2" id="ch04-SECT-5.1.2">
1208 <indexterm id="ch04-idx-968300-0"><primary>guest ok option</primary></indexterm>
1209 <title>
1210 guest ok</title>
1211
1212
1213 <para>This option (which has an older synonym <literal>public</literal>) allows or prohibits guest access to a share. The default value is <literal>no</literal>. If set to <literal>yes</literal>, it means that no username or password will be needed to connect to the share. When a user connects, the access rights will be equivalent to the designated guest user. The default account to which Samba offers the share is <literal>nobody</literal>. However, this can be reset with the <literal>guest</literal> <literal>account</literal> configuration option. For example, the following lines allow guest user access to the <literal>[accounting]</literal> share with the permissions of the <emphasis>ftp</emphasis> account:</para>
1214
1215
1216 <programlisting>[global]
1217         guest account = ftp
1218 [accounting]
1219         path = /usr/local/account
1220         guest ok = yes</programlisting>
1221
1222
1223 <para>Note that users can still connect to the share using a valid username/password combination. If successful, they will hold the access rights granted by their own account and not the guest account. If a user attempts to log in and fails, however, he or she will default to the access rights of the guest account. You can mandate that every user who attaches to the share will be using the guest account (and will have the permissions of the guest) by setting the option <literal>guest</literal> <literal>only</literal> <literal>=</literal> <literal>yes</literal>.</para>
1224 </sect3>
1225
1226
1227
1228 <sect3 role="" label="4.5.1.3" id="ch04-SECT-5.1.3">
1229 <indexterm id="ch04-idx-968303-0"><primary>comment option</primary></indexterm>
1230 <title>
1231 comment</title>
1232
1233
1234 <para>The <literal>comment</literal> option allows you to enter a comment that will be sent to the client when it attempts to browse the share. The user can see the comment by listing Details on the share folder under the appropriate computer in the Windows Network Neighborhood, or type the command <literal>NET</literal> <literal>VIEW</literal> at an MS-DOS prompt. For example, here is how you might insert a comment for a <literal>[network]</literal> share:</para>
1235
1236
1237 <programlisting>[network]
1238         comment = Network Drive
1239         path = /export/samba/network</programlisting>
1240
1241
1242 <para>This yields a folder similar to <link linkend="ch04-34850">Figure 4.6</link> on the client side. Note that with the current configuration of Windows, this comment will not be shown once a share is mapped to a Windows network drive.</para>
1243
1244
1245 <figure label="4.6" id="ch04-34850">
1246 <title>Windows client view of a share comment</title>
1247
1248 <graphic width="502" depth="135" fileref="figs/sam.0406.gif"></graphic>
1249 </figure>
1250
1251 <para>Be sure not to confuse the <literal>comment</literal> option, which documents a Samba server's shares, with the <literal>server</literal> <literal>string</literal> option, which documents the server itself.</para>
1252 </sect3>
1253
1254
1255
1256 <sect3 role="" label="4.5.1.4" id="ch04-SECT-5.1.4">
1257 <indexterm id="ch04-idx-968306-0"><primary>volume option</primary></indexterm>
1258 <title>
1259 volume</title>
1260
1261
1262 <para>This option allows you to specify the volume name of the share as reported by SMB. This normally resolves to the name of the share given in the <filename>smb.conf</filename>  file. However, if you wish to name it something else (for whatever reason) you can do so with this option.</para>
1263
1264
1265 <para>For example, an installer program may check the volume name of a CD-ROM to make sure the right CD-ROM is in the drive before attempting to install it. If you copy the contents of the CD-ROM into a network share, and wish to install from there, you can use this option to get around the issue:</para>
1266
1267
1268 <programlisting>[network]
1269         comment = Network Drive
1270         volume = ASVP-102-RTYUIKA
1271         path = /home/samba/network</programlisting>
1272 </sect3>
1273
1274
1275
1276 <sect3 role="" label="4.5.1.5" id="ch04-SECT-5.1.5">
1277 <indexterm id="ch04-idx-968309-0"><primary>read only option</primary></indexterm>
1278 <indexterm id="ch04-idx-968309-1"><primary>writeable/write ok option</primary></indexterm>
1279 <title>
1280
1281 read only and writeable</title>
1282
1283
1284 <para>The options <literal>read</literal> <literal>only</literal> and <literal>writeable</literal> (or <literal>write</literal> <literal>ok </literal>) are really two ways of saying the same thing, but approached from opposite ends. For example, you can set either of the following options in the <literal>[global]</literal> section or in an individual share:</para>
1285
1286
1287 <programlisting>read only = yes
1288 writeable = no</programlisting>
1289
1290
1291 <para>If either option is set as shown, data can be read from a share, but cannot be written to it. You might think you would need this option only if you were creating a read-only share. However, note that this read-only behavior is the <emphasis>default</emphasis> action for shares; if you want to be able to write data to a share, you must explicitly specify one of the following options in the configuration file for each share:</para>
1292
1293
1294 <programlisting>read only = no
1295 writeable = yes</programlisting>
1296
1297
1298 <para>Note that if you specify more than one occurrence of either option, Samba will adhere to the last value it encounters for the<indexterm id="ch04-idx-967387-0" class="endofrange" startref="ch04-idx-967272-0"/> share.<indexterm id="ch04-idx-967245-0" class="endofrange" startref="ch04-idx-967244-0"/>
1299 <indexterm id="ch04-idx-967245-1" class="endofrange" startref="ch04-idx-967244-1"/></para>
1300 </sect3>
1301 </sect2>
1302 </sect1>
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312 <sect1 role="" label="4.6" id="ch04-86705">
1313 <title>Networking Options with Samba</title>
1314
1315
1316 <para>
1317 <indexterm id="ch04-idx-967291-0" class="startofrange"><primary>networking</primary><secondary>options</secondary></indexterm>If you're running Samba on a multi-homed machine (that is, one on multiple subnets), or even if you want to implement a security policy on your own subnet, you should take a close look at the networking configuration options:</para>
1318
1319
1320 <para>For the purposes of this exercise, let's assume that our Samba server is connected to a network with more than one subnet. Specifically, the machine can access both the 192.168.220.* and 134.213.233.* subnets. Here are our additions to the ongoing configuration file for the networking configuration options:</para>
1321
1322
1323 <programlisting>[global]
1324         netbios name = HYDRA
1325         server string = Samba %v on (%L)
1326         workgroup = SIMPLE
1327
1328         #  Networking configuration options
1329         hosts allow = 192.168.220. 134.213.233. localhost
1330         hosts deny = 192.168.220.102
1331         interfaces = 192.168.220.100/255.255.255.0 \
1332                          134.213.233.110/255.255.255.0
1333         bind interfaces only = yes
1334
1335 [data]
1336         path = /home/samba/data
1337         guest ok = yes
1338         comment = Data Drive
1339         volume = Sample-Data-Drive
1340         writeable = yes</programlisting>
1341
1342
1343 <para>
1344 <indexterm id="ch04-idx-967305-0"><primary>hosts</primary><secondary>networking option for connections</secondary></indexterm>Let's first talk about the <literal>hosts</literal> <literal>allow</literal> and <literal>hosts</literal> <literal>deny</literal> options. If these options sound familiar, you're probably thinking of the <filename>hosts.allow</filename> and <filename>hosts.deny</filename> files that are found in the <filename>/etc</filename> directories of many Unix systems. The purpose of these options is identical to those files; they provide a means of security by allowing or denying the connections of other hosts based on their IP addresses. Why not just use the <filename>hosts.allow</filename> and <filename>hosts.deny</filename> files themselves? Because there may be services on the server that you want others to access without giving them access Samba's disk or printer shares</para>
1345
1346
1347 <para>With the <literal>hosts</literal> <literal>allow</literal> option above, we've specified a cropped IP address: 192.168.220. (Note that there is still a third period; it's just missing the fourth number.) This is equivalent to saying: "All hosts on the 192.168.220 subnet." However, we've explicitly specified in a hosts deny line that 192.168.220.102 is not to be allowed access.</para>
1348
1349
1350 <para>You might be wondering: why will 192.168.220.102 be denied even though it is still in the subnet matched by the <literal>hosts</literal> <literal>allow</literal> option? Here is how Samba sorts out the rules specified by <literal>hosts</literal> <literal>allow</literal> and <literal>hosts</literal> <literal>deny </literal>:</para>
1351
1352
1353 <orderedlist>
1354 <listitem><para>If there are no <literal>allow</literal> or <literal>deny</literal> options defined anywhere in <filename>smb.conf</filename>, Samba will allow connections from any machine allowed by the system itself.</para></listitem>
1355 <listitem><para>If there are <literal>hosts</literal> <literal>allow</literal> or <literal>hosts</literal> <literal>deny</literal> options defined in the <literal>[global]</literal> section of <filename>smb.conf</filename>, they will apply to all shares, even if the shares have an overriding option defined.</para></listitem>
1356 <listitem><para>If there is only a <literal>hosts</literal> <literal>allow</literal> option defined for a share, only the hosts listed will be allowed to use the share. All others will be denied.</para></listitem>
1357 <listitem><para>If there is only a <literal>hosts</literal> <literal>deny</literal> option defined for a share, any machine which is not on the list will be able to use the share.</para></listitem>
1358 <listitem><para>If both a <literal>hosts</literal> <literal>allow</literal> and <literal>hosts</literal> <literal>deny</literal> option are defined, a host must appear in the allow list and not appear in the deny list (in any form) in order to access the share. Otherwise, the host will not be allowed.</para></listitem>
1359 </orderedlist>
1360
1361 <warning role="ora"> <para>
1362 <indexterm id="ch04-idx-967307-0"><primary>hosts</primary><secondary>subnets and,
1363 caution with</secondary></indexterm>
1364 <indexterm id="ch04-idx-967307-1"><primary>subnets</primary><secondary>hosts and,
1365 caution with</secondary></indexterm>Take care that you don't explicitly
1366 allow a host to access a share, but then deny access to the entire
1367 subnet of which the host is part.</para>
1368
1369 </warning>
1370
1371 <para>Let's look at another example of that final item. Consider the following options:</para>
1372
1373
1374 <programlisting>hosts allow = 111.222.
1375 hosts deny = 111.222.333.</programlisting>
1376
1377
1378 <para>In this case, only the hosts that belong to the subnet 111.222.*.* will be allowed access to the Samba shares. However, if a client belongs to the 111.222.333.* subnet, it will be denied access, even though it still matches the qualifications outlined by <literal>hosts</literal> <literal>allow</literal>. The client must appear on the <literal>hosts</literal> <literal>allow</literal> list and <emphasis>must not</emphasis> appear on the <literal>hosts</literal> <literal>deny</literal> list in order to gain access to a Samba share. If a computer attempts to access a share to which it is not allowed access, it will receive an error message.</para>
1379
1380
1381 <para>The other two options that we've specified are the <literal>interfaces</literal> and the <literal>bind</literal> <literal>interface</literal> <literal>only</literal> address. Let's look at the <literal>interfaces</literal> option first. Samba, by default, sends data only from the primary network interface, which in our example is the 192.168.220.100 subnet. If we would like it to send data to more than that one <indexterm id="ch04-idx-967310-0"><primary>interfaces, networking options for</primary></indexterm>interface, we need to specify the complete list with the <literal>interfaces</literal> option. In the previous example, we've bound Samba to interface with both subnets (192.168.220 and 134.213.233) on which the machine is operating by specifying the other network interface address: 134.213.233.100. If you have more than one interface on your computer, you should always set this option as there is no guarantee that the primary interface that Samba chooses will be the right one.</para>
1382
1383
1384 <para>Finally, the <literal>bind</literal> <literal>interfaces</literal> <literal>only</literal> option instructs the <filename>nmbd</filename> process not to accept any broadcast messages other than those subnets specified with the <literal>interfaces</literal> option. Note that this is different from the <literal>hosts</literal> <literal>allow</literal> and <literal>hosts</literal> <literal>deny</literal> options, which prevent machines from making connections to services, but not from receiving broadcast messages. Using the <literal>bind</literal> <literal>interfaces</literal> <literal>only</literal> option is a way to shut out even datagrams from foreign subnets from being received by the Samba server. In addition, it instructs the <emphasis>smbd</emphasis> process to bind to only the interface list given by the <emphasis>interfaces</emphasis> option. This restricts the networks that Samba will serve.</para>
1385
1386
1387 <sect2 role="" label="4.6.1" id="ch04-SECT-6.1">
1388 <title>Networking Options</title>
1389
1390
1391 <para>
1392 <indexterm id="ch04-idx-967302-0"><primary>networking</primary><secondary>options</secondary><tertiary>list of</tertiary></indexterm>The networking options we introduced above are summarized in <link linkend="ch04-32963">Table 4.5</link>.</para>
1393
1394
1395 <table label="4.5" id="ch04-32963">
1396 <title>Networking Configuration Options </title>
1397
1398 <tgroup cols="5">
1399 <colspec colnum="1" colname="col1"/>
1400 <colspec colnum="2" colname="col2"/>
1401 <colspec colnum="3" colname="col3"/>
1402 <colspec colnum="4" colname="col4"/>
1403 <colspec colnum="5" colname="col5"/>
1404 <thead>
1405 <row>
1406
1407 <entry colname="col1"><para>Option</para></entry>
1408
1409 <entry colname="col2"><para>Parameters</para></entry>
1410
1411 <entry colname="col3"><para>Function</para></entry>
1412
1413 <entry colname="col4"><para>Default</para></entry>
1414
1415 <entry colname="col5"><para>Scope</para></entry>
1416
1417 </row>
1418
1419 </thead>
1420
1421 <tbody>
1422 <row>
1423
1424 <entry colname="col1"><para><literal>hosts allow (allow hosts)</literal></para></entry>
1425
1426 <entry colname="col2"><para>string (list of hostnames)</para></entry>
1427
1428 <entry colname="col3"><para>Specifies the machines that can connect to Samba.</para></entry>
1429
1430 <entry colname="col4"><para>none</para></entry>
1431
1432 <entry colname="col5"><para>Share</para></entry>
1433
1434 </row>
1435
1436 <row>
1437
1438 <entry colname="col1"><para><literal>hosts deny (deny hosts)</literal></para></entry>
1439
1440 <entry colname="col2"><para>string (list of hostnames)</para></entry>
1441
1442 <entry colname="col3"><para>Specifies the machines that cannot connect to Samba.</para></entry>
1443
1444 <entry colname="col4"><para>none</para></entry>
1445
1446 <entry colname="col5"><para>Share</para></entry>
1447
1448 </row>
1449
1450 <row>
1451
1452 <entry colname="col1"><para><literal>interfaces</literal></para></entry>
1453
1454 <entry colname="col2"><para>string (list of IP/netmask combinations)</para></entry>
1455
1456 <entry colname="col3"><para>Sets the network interfaces Samba will respond to. Allows correcting defaults.</para></entry>
1457
1458 <entry colname="col4"><para>system-dependent</para></entry>
1459
1460 <entry colname="col5"><para>Global</para></entry>
1461
1462 </row>
1463
1464 <row>
1465
1466 <entry colname="col1"><para><literal>bind</literal></para>
1467
1468 <para><literal>interfaces only</literal></para></entry>
1469
1470 <entry colname="col2"><para>boolean</para></entry>
1471
1472 <entry colname="col3"><para>If set to <literal>yes</literal>, Samba will bind only to those interfaces specified by the <literal>interfaces</literal> option.</para></entry>
1473
1474 <entry colname="col4"><para><literal>no</literal></para></entry>
1475
1476 <entry colname="col5"><para>Global</para></entry>
1477
1478 </row>
1479
1480 <row>
1481
1482 <entry colname="col1"><para><literal>socket</literal></para>
1483
1484 <para><literal>address</literal></para></entry>
1485
1486 <entry colname="col2"><para>string (IP address)</para></entry>
1487
1488 <entry colname="col3"><para>Sets IP address to listen on, for use with multiple virtual interfaces on a server.</para></entry>
1489
1490 <entry colname="col4"><para>none</para></entry>
1491
1492 <entry colname="col5"><para>Global</para></entry>
1493
1494 </row>
1495
1496 </tbody>
1497 </tgroup>
1498 </table>
1499
1500
1501 <sect3 role="" label="4.6.1.1" id="ch04-SECT-6.1.1">
1502 <indexterm id="ch04-idx-968312-0"><primary>hosts allow option</primary></indexterm>
1503 <title>
1504 hosts allow</title>
1505
1506
1507 <para>
1508 <indexterm id="ch04-idx-967314-0"><primary>hosts</primary><secondary>networking option for connections</secondary></indexterm>The <literal>hosts</literal> <literal>allow</literal> option (sometimes written as <literal>allow</literal> <literal>hosts</literal>) specifies the machines that have permission to access shares on the Samba server, written as a comma- or space-separated list of names of machines or their IP addresses. You can gain quite a bit of security by simply placing your LAN's subnet address in this option. For example, we specified the following in our example:</para>
1509
1510
1511 <programlisting>hosts allow = 192.168.220. localhost</programlisting>
1512
1513
1514 <para>Note that we placed <literal>localhost</literal> after the subnet address. One of the most common mistakes when attempting to use the <literal>hosts</literal> <literal>allow</literal> option is to accidentally disallow the Samba server from communicating with itself. The <filename>smbpasswd</filename> program will occasionally need to connect to the Samba server as a client in order to change a user's encrypted password. In addition, local browsing propagation requires local host access. If this option is enabled and the localhost address is not specified, the locally-generated packets requesting the change of the encrypted password will be discarded by Samba, and browsing propagation will not work properly. To avoid this, explicitly allow the loopback address (either <literal>localhost</literal> or <literal>127.0.0.1</literal>) to be used.<footnote label="3" id="ch04-pgfId-965714">
1515
1516
1517 <para>Starting with Samba 2.0.5, <literal>localhost</literal> will automatically be allowed unless it is explicitly denied.</para>
1518
1519
1520 </footnote></para>
1521
1522
1523 <para>You can specify any of the following formats for this option:</para>
1524
1525
1526 <itemizedlist>
1527 <listitem><para>Hostnames, such as <literal>ftp.example.com </literal>.</para></listitem>
1528 <listitem><para>IP addresses, like <literal>130.63.9.252</literal>.</para></listitem>
1529 <listitem><para>Domain names, which can be differentiated from individual hostnames because they start with a dot. For example, <literal>.ora.com</literal> represents all machines within the <emphasis>ora.com</emphasis> domain.</para></listitem>
1530 <listitem><para>Netgroups, which start with an at-sign, such as <literal>@printerhosts</literal>. Netgroups are available on systems running yellow pages/NIS or NIS+, but rarely otherwise. If netgroups are supported on your system, there should be a <literal>netgroups</literal> manual page that describes them in more detail.</para></listitem>
1531 <listitem><para>Subnets, which end with a dot. For example, <literal>130.63.9.</literal> means all the machines whose IP addresses begin with 130.63.9.</para></listitem>
1532 <listitem><para>The keyword <literal>ALL</literal>, which allows any client access.</para></listitem>
1533 <listitem><para>The keyword <literal>EXCEPT</literal> followed by more one or more names, IP addresses, domain names, netgroups, or subnets. For example, you could specify that Samba allow all hosts except those on the 192.168.110 subnet with <literal>hosts</literal> <literal>allow</literal> <literal>=</literal> <literal>ALL</literal> <literal>EXCEPT</literal> <literal>192.168.110.</literal> (remember the trailing dot).</para></listitem>
1534 </itemizedlist>
1535
1536 <para>Using the <literal>ALL</literal> keyword is almost always a bad idea, since it means that anyone on any network can browse your files if they guess the name of your server.</para>
1537
1538
1539 <para>Note that there is no default value for the <literal>hosts</literal> <literal>allow</literal> configuration option, although the default course of action in the event that neither option is specified is to allow access from all sources. In addition, if you specify this option in the <literal>[global]</literal> section of the configuration file, it will override any <literal>hosts</literal> <literal>allow</literal> options defined shares.</para>
1540 </sect3>
1541
1542
1543
1544 <sect3 role="" label="4.6.1.2" id="ch04-SECT-6.1.2">
1545 <indexterm id="ch04-idx-968319-0"><primary>hosts deny option</primary></indexterm>
1546 <title>
1547 hosts deny</title>
1548
1549
1550 <para>The <literal>hosts</literal> <literal>deny</literal> option (also <literal>deny</literal> <literal>hosts</literal>) specifies machines that do not have permission to access a share, written as a comma- or space-separated list of machine names or their IP addresses. Use the same format as specifying clients as the <literal>hosts</literal> <literal>allow</literal> option above. For example, to restrict access to the server from everywhere but <filename>example.com</filename>, you could write:</para>
1551
1552
1553 <programlisting>hosts deny = ALL EXCEPT .example.com</programlisting>
1554
1555
1556 <para>Like <literal>hosts</literal> <literal>allow</literal>, there is no default value for the <literal>hosts</literal> <literal>deny</literal> configuration option, although the default course of action in the event that neither option is specified is to allow access from all sources. Also, if you specify this option in the <literal>[global]</literal> section of the configuration file, it will override any <literal>hosts</literal> <literal>deny</literal> options defined in shares. If you wish to deny <emphasis>hosts</emphasis> access to specific shares, omit both the <literal>hosts</literal> <literal>allow</literal> and <literal>hosts</literal> <literal>deny</literal> options in the <literal>[global]</literal> section of the configuration file.</para>
1557 </sect3>
1558
1559
1560
1561 <sect3 role="" label="4.6.1.3" id="ch04-SECT-6.1.3">
1562 <indexterm id="ch04-idx-968322-0"><primary>interfaces option</primary></indexterm>
1563 <title>
1564 interfaces</title>
1565
1566
1567 <para>
1568 <indexterm id="ch04-idx-967320-0"><primary>hosts</primary><secondary>networking option for connections</secondary></indexterm>The <literal>interfaces</literal> option outlines the network addresses to which you want the Samba server to recognize and respond. This option is handy if you have a computer that resides on more than one network subnet. If this option is not set, Samba searches for the primary network interface of the server (typically the first Ethernet card) upon startup and configures itself to operate on only that subnet. If the server is configured for more than one subnet and you do not specify this option, Samba will only work on the first subnet it encounters. You must use this option to force Samba to serve the other subnets on your network.</para>
1569
1570
1571 <para>The value of this option is one or more sets of IP address/netmask pairs, such as the following:</para>
1572
1573
1574 <programlisting>interfaces = 192.168.220.100/255.255.255.0 192.168.210.30/255.255.255.0</programlisting>
1575
1576
1577 <para>You can optionally specify a CIDR format bitmask, as follows:</para>
1578
1579
1580 <programlisting>interfaces = 192.168.220.100/24 192.168.210.30/24</programlisting>
1581
1582
1583 <para>The bitmask number specifies the first number of bits that will be turned on in the netmask. For example, the number 24 means that the first 24 (of 32) bits will be activated in the bit mask, which is the same as saying 255.255.255.0. Likewise, 16 would be equal to 255.255.0.0, and 8 would be equal to 255.0.0.0.</para>
1584
1585
1586 <tip role="ora">
1587 <para>This option may not work correctly if you are using DHCP.</para>
1588
1589 </tip>
1590 </sect3>
1591
1592
1593
1594 <sect3 role="" label="4.6.1.4" id="ch04-SECT-6.1.4">
1595 <indexterm id="ch04-idx-968325-0"><primary>bind interfaces only option</primary></indexterm>
1596 <title>
1597 bind interfaces only</title>
1598
1599
1600 <para>The <literal>bind</literal> <literal>interfaces</literal> <literal>only</literal> option can be used to force the <emphasis>smbd</emphasis> and <emphasis>nmbd</emphasis> processes to serve SMB requests to only those addresses specified by the <literal>interfaces</literal> option. The <emphasis>nmbd</emphasis> process normally binds to the all addresses interface (0.0.0.0.) on ports 137 and 138, allowing it to receive broadcasts from anywhere. However, you can override this behavior with the following:</para>
1601
1602
1603 <programlisting>bind interfaces only = yes</programlisting>
1604
1605
1606 <para>This will cause both Samba processes to ignore any packets whose origination address does not match the broadcast address(es) specified by the <literal>interfaces</literal> option, including broadcast packets. With <emphasis>smbd</emphasis>, this option will cause Samba to not serve file requests to subnets other than those listed in the <literal>interfaces</literal> option. You should avoid using this option if you want to allow temporary network connections, such as those created through SLIP or PPP. It's very rare that this option is needed, and it should only be used by experts.</para>
1607
1608
1609 <tip role="ora">
1610 <para>If you set <literal>bind interfaces only</literal> to <literal>yes </literal>, you should add the localhost address (127.0.01) to the "interfaces" list. Otherwise, <emphasis>smbpasswd</emphasis> will be unable to connect to the server using its default mode in order to change a password.</para>
1611
1612 </tip>
1613 </sect3>
1614
1615
1616
1617 <sect3 role="" label="4.6.1.5" id="ch04-SECT-6.1.5">
1618 <indexterm id="ch04-idx-968328-0"><primary>socket address option</primary></indexterm>
1619 <title>
1620 socket address</title>
1621
1622
1623 <para>
1624 <indexterm id="ch04-idx-967324-0"><primary>addresses, networking option for</primary></indexterm>The <literal>socket</literal> <literal>address</literal> option dictates which of the addresses specified with the <literal>interfaces</literal> parameter Samba should listen on for connections. Samba accepts connections on all addresses specified by default. When used in an <filename>smb.conf</filename>  file, this option will force Samba to listen on only one IP address. For example:</para>
1625
1626
1627 <programlisting>interfaces = 192.168.220.100/24 192.168.210.30/24
1628 socket address = 192.168.210.30</programlisting>
1629
1630
1631 <para>This option is a programmer's tool and we recommend that you do not use it.<indexterm id="ch04-idx-967297-0" class="endofrange" startref="ch04-idx-967291-0"/></para>
1632 </sect3>
1633 </sect2>
1634 </sect1>
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644 <sect1 role="" label="4.7" id="ch04-16899">
1645 <title>Virtual Servers</title>
1646
1647
1648 <para>
1649 <indexterm id="ch04-idx-967325-0" class="startofrange"><primary>servers</primary><secondary>virtual</secondary></indexterm>
1650 <indexterm id="ch04-idx-967325-1" class="startofrange"><primary>virtual servers</primary></indexterm>Virtual servers are a technique for creating the illusion of multiple <indexterm id="ch04-idx-967337-0"><primary>NetBIOS (Network Basic Input/Output System)</primary><secondary>multiple servers</secondary><see>virtual servers</see></indexterm>NetBIOS servers on the network, when in reality there is only one. The technique is simple to implement: a machine simply registers more than one NetBIOS name in association with its IP address. There are tangible benefits to doing this.</para>
1651
1652
1653 <para>The accounting department, for example, might have an <literal>accounting</literal> server, and clients of it would see just the accounting disks and printers. The marketing department could have their own server, <literal>marketing</literal>, with their own reports, and so on. However, all the services would be provided by one medium-sized Unix workstation (and one relaxed administrator), instead of having one small server and one administrator per department.</para>
1654
1655
1656 <para>Samba will allow a Unix server to use more than one NetBIOS name with the <literal>netbios</literal> <literal>aliases</literal> option. See <link linkend="ch04-92259">Table 4.6</link>.</para>
1657
1658
1659 <table label="4.6" id="ch04-92259">
1660 <title>Virtual Server Configuration Options </title>
1661
1662 <tgroup cols="5">
1663 <colspec colnum="1" colname="col1"/>
1664 <colspec colnum="2" colname="col2"/>
1665 <colspec colnum="3" colname="col3"/>
1666 <colspec colnum="4" colname="col4"/>
1667 <colspec colnum="5" colname="col5"/>
1668 <thead>
1669 <row>
1670
1671 <entry colname="col1"><para>Option</para></entry>
1672
1673 <entry colname="col2"><para>Parameters</para></entry>
1674
1675 <entry colname="col3"><para>Function</para></entry>
1676
1677 <entry colname="col4"><para>Default</para></entry>
1678
1679 <entry colname="col5"><para>Scope</para></entry>
1680
1681 </row>
1682
1683 </thead>
1684
1685 <tbody>
1686 <row>
1687
1688 <entry colname="col1"><para><literal>netbios aliases</literal></para></entry>
1689
1690 <entry colname="col2"><para>
1691 <indexterm id="ch04-idx-967338-0"><primary>virtual servers</primary><secondary>options for</secondary></indexterm>
1692 <indexterm id="ch04-idx-967338-1"><primary>servers</primary><secondary>virtual</secondary><tertiary>options for</tertiary></indexterm>List of NetBIOS names</para></entry>
1693
1694 <entry colname="col3"><para>Additional NetBIOS names to respond to, for use with multiple "virtual" Samba servers.</para></entry>
1695
1696 <entry colname="col4"><para>None</para></entry>
1697
1698 <entry colname="col5"><para>Global</para></entry>
1699
1700 </row>
1701
1702 </tbody>
1703 </tgroup>
1704 </table>
1705
1706
1707 <sect2 role="" label="4.7.1" id="ch04-SECT-7.0.1">
1708 <indexterm id="ch04-idx-968331-0"><primary>netbios aliases option</primary></indexterm>
1709 <title>
1710 netbios aliases</title>
1711
1712
1713 <para>The <literal>netbios</literal> <literal>aliases</literal> option can be used to give the Samba server more than one <indexterm id="ch04-idx-967339-0"><primary>NetBIOS name</primary><secondary>option for aliases</secondary></indexterm>
1714 <indexterm id="ch04-idx-967339-1"><primary>aliases</primary><secondary sortas="NetBIOS names">for NetBIOS names</secondary></indexterm>NetBIOS name. Each NetBIOS name listed as a value will be displayed in the Network Neighborhood of a browsing machine. When a connection is requested to any machine, however, it will connect to the same Samba server.</para>
1715
1716
1717 <para>This might come in handy, for example, if you're transferring three departments' data to a single Unix server with modern large disks, and are retiring or reallocating the old NT servers. If the three servers are called <literal>sales</literal>, <literal>accounting</literal>, and <literal>admin</literal>, you can have Samba represent all three servers with the following options:</para>
1718
1719
1720 <programlisting>[global]
1721         netbios aliases = sales accounting admin
1722         include = /usr/local/samba/lib/smb.conf.%L</programlisting>
1723
1724
1725 <para>See <link linkend="ch04-28393">Figure 4.7</link> for what the Network Neighborhood would display from a client.When a client attempts to connect to Samba, it will specify the name of the server that it's trying to connect to, which you can access through the <literal>%L</literal> variable. If the requested server is <literal>sales</literal>, Samba will include the <filename>/usr/local/samba/lib/smb.conf.sales</filename> file. This file might contain global and share declarations exclusively for the sales team, such as the following:</para>
1726
1727
1728 <programlisting>[global]
1729         workgroup = SALES
1730         hosts allow = 192.168.10.255
1731
1732 [sales1998]
1733         path = /usr/local/samba/sales/sales1998/
1734 ...</programlisting>
1735
1736
1737 <para>This particular example would set the workgroup to SALES as well, and set the IP address to allow connections only from the SALES subnet (192.168.10). In addition, it would offer shares specific to the sales department.</para>
1738
1739
1740 <figure label="4.7" id="ch04-28393">
1741 <indexterm id="ch04-idx-967332-0" class="endofrange" startref="ch04-idx-967325-0"/><indexterm id="ch04-idx-967332-1" class="endofrange" startref="ch04-idx-967325-1"/><title>Using NetBIOS aliases for a Samba server
1742  </title>
1743
1744 <graphic width="502" depth="196" fileref="figs/sam.0407.gif"></graphic>
1745 </figure>
1746 </sect2>
1747 </sect1>
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757 <sect1 role="" label="4.8" id="ch04-29331">
1758 <title>Logging Configuration Options</title>
1759
1760
1761 <para>
1762 <indexterm id="ch04-idx-967340-0" class="startofrange"><primary>log files/logging</primary><secondary>configuration options</secondary></indexterm>
1763 <indexterm id="ch04-idx-967340-1" class="startofrange"><primary>log files/logging</primary><secondary>checking</secondary></indexterm>Occasionally, we need to find out what Samba is up to. This is especially true when Samba is performing an unexpected action or is not performing at all. To find out this information, we need to check Samba's log files to see exactly why it did what it did.</para>
1764
1765
1766 <para>Samba log files can be as brief or verbose as you like. Here is an example of what a Samba log file looks like:</para>
1767
1768
1769 <programlisting>[1999/07/21 13:23:25, 3] smbd/service.c:close_cnum(514)
1770   phoenix (192.168.220.101) closed connection to service IPC$
1771 [1999/07/21 13:23:25, 3] smbd/connection.c:yield_connection(40)
1772   Yielding connection to IPC$
1773 [1999/07/21 13:23:25, 3] smbd/process.c:process_smb(615)
1774   Transaction 923 of length 49
1775 [1999/07/21 13:23:25, 3] smbd/process.c:switch_message(448)
1776   switch message SMBread (pid 467)
1777 [1999/07/21 13:23:25, 3] lib/doscalls.c:dos_ChDir(336)
1778   dos_ChDir to /home/samba
1779 [1999/07/21 13:23:25, 3] smbd/reply.c:reply_read(2199)
1780   read fnum=4207 num=2820 nread=2820
1781 [1999/07/21 13:23:25, 3] smbd/process.c:process_smb(615)
1782   Transaction 924 of length 55
1783 [1999/07/21 13:23:25, 3] smbd/process.c:switch_message(448)
1784   switch message SMBreadbraw (pid 467)
1785 [1999/07/21 13:23:25, 3] smbd/reply.c:reply_readbraw(2053)
1786   readbraw fnum=4207 start=130820 max=1276 min=0 nread=1276
1787 [1999/07/21 13:23:25, 3] smbd/process.c:process_smb(615)
1788   Transaction 925 of length 55
1789 [1999/07/21 13:23:25, 3] smbd/process.c:switch_message(448)
1790   switch message SMBreadbraw (pid 467)</programlisting>
1791
1792
1793 <para>Many of these options are of use only to Samba programmers. However, we will go over the meaning of some of these entries in more detail in <link linkend="SAMBA-CH-9">Chapter 9</link>.</para>
1794
1795
1796 <para>Samba contains six options that allow users to describe how and where logging information should be written. Each of these options are global options and cannot appear inside a share definition. Here is an up-to-date configuration file that covers each of the share and logging options that we've seen so far:</para>
1797
1798
1799 <programlisting>[global]
1800         netbios name = HYDRA
1801         server string = Samba %v on (%I)
1802         workgroup = SIMPLE
1803
1804         #  Networking configuration options
1805         hosts allow = 192.168.220. 134.213.233. localhost
1806         hosts deny = 192.168.220.102
1807         interfaces = 192.168.220.100/255.255.255.0 \
1808                          134.213.233.110/255.255.255.0
1809         bind interfaces only = yes
1810
1811         # Debug logging information
1812         log level = 2
1813         log file = /var/log/samba.log.%m
1814         max log size = 50
1815         debug timestamp = yes
1816
1817 [data]
1818         path = /home/samba/data
1819         browseable = yes
1820         guest ok = yes
1821         comment = Data Drive
1822         volume = Sample-Data-Drive
1823         writeable = yes</programlisting>
1824
1825
1826 <para>  Here, we've added a custom log file that reports information up to debug level 2. This is a relatively light debugging level. The logging level ranges from 1 to 10, where level 1 provides only a small amount of information and level 10 provides a plethora of low-level information. Level 2 will provide us with useful debugging information without wasting disk space on our server. In practice, you should avoid using log levels greater than 3 unless you are programming Samba.</para>
1827
1828
1829 <para>This file is located in the <filename>/var/log</filename> directory thanks to the <literal>log</literal> <literal>file</literal> configuration option. However, we can use variable substitution to create log files specifically for individual users or clients, such as with the <literal>%m</literal> variable in the following line:</para>
1830
1831
1832 <programlisting>log file = /usr/local/logs/samba.log.%m</programlisting>
1833
1834
1835 <para>Isolating the log messages can be invaluable in tracking down a network error if you know the problem is coming from a specific machine or user.</para>
1836
1837
1838 <para>We've added another precaution to the log files: no one log file can exceed 50 kilobytes in size, as specified by the <literal>max</literal> <literal>log</literal> <literal>size</literal> option. If a log file exceeds this size, the contents are moved to a file with the same name but with the suffix <emphasis>.old</emphasis> appended. If the <emphasis>.old</emphasis> file already exists, it is overwritten and its contents are lost. The original file is cleared, waiting to receive new logging information. This prevents the hard drive from being overwhelmed with Samba log files during the life of our daemons.</para>
1839
1840
1841 <para>For convenience, we have decided to leave the debug timestamp in the logs with the <literal>debug</literal> <literal>timestamp</literal> option, which is the default behavior. This will place a timestamp next to each message in the logging file. If we were not interested in this information, we could specify <literal>no</literal> for this option instead.</para>
1842
1843
1844 <sect2 role="" label="4.8.1" id="ch04-97929">
1845 <title>Using syslog</title>
1846
1847
1848 <para>If you wish to use the system logger (<filename>syslog </filename>
1849 <indexterm id="ch04-idx-967351-0"><primary>SYSLOG utility</primary></indexterm>) in addition to or in place of the standard Samba logging file, Samba provides options for this as well. However, to use <filename>syslog</filename>, the first thing you will have to do is make sure that Samba was built with the <literal>configure</literal> <literal>--with-syslog</literal> option. See <link linkend="SAMBA-CH-2">Chapter 2</link> for more information on configuring and compiling Samba.</para>
1850
1851
1852 <para>Once that is done, you will need to configure your <filename>/etc/syslog.conf</filename> to accept logging information from Samba. If there is not already a <literal>daemon.*</literal> entry in the <replaceable>/etc/syslog.conf</replaceable> file, add the following:</para>
1853
1854
1855 <programlisting>daemon.*        /var/log/daemon.log</programlisting>
1856
1857
1858 <para>This specifies that any logging information from system daemons will be stored in the <filename>/var/log/daemon.log</filename> file. This is where the Samba information will be stored as well. From there, you can specify the following global option in your configuration file:</para>
1859
1860
1861 <programlisting>syslog = 2</programlisting>
1862
1863
1864 <para>This specifies that any logging messages with a level of 1 will be sent to both the <filename>syslog</filename> and the Samba logging files. (The mappings to <filename>syslog</filename> priorities are described in the upcoming <link linkend="ch04-78696">Section 4.8.2.5</link>.) Let's assume that we set the regular <literal>log</literal> <literal>level</literal> option above to 4. Any logging messages with a level of 2, 3, or 4 will be sent to the Samba logging files, but not to the <filename>syslog</filename>. Only level 1 logging messages will be sent to both. If the <literal>syslog</literal> value exceeds the <literal>log</literal> <literal>level</literal> value, nothing will be written to the <filename>syslog</filename>.</para>
1865
1866
1867 <para>If you want to specify that messages be sent only to <filename>syslog</filename>&mdash;and not to the standard Samba logging files&mdash;you can place this option in the configuration file:</para>
1868
1869
1870 <programlisting>syslog only = yes</programlisting>
1871
1872
1873 <para>If this is the case, any logging information above the number specified in the <literal>syslog</literal> option will be discarded, just like the <literal>log</literal> <literal>level</literal> option.</para>
1874 </sect2>
1875
1876
1877
1878
1879 <sect2 role="" label="4.8.2" id="ch04-SECT-8.1">
1880 <title>Logging Configuration Options</title>
1881
1882
1883 <para><link linkend="ch04-92838">Table 4.7</link> lists each of the<indexterm id="ch04-idx-967341-0"><primary>log files/logging</primary><secondary>configuration options</secondary><tertiary>list of</tertiary></indexterm> logging configuration options that Samba can use.</para>
1884
1885
1886 <table label="4.7" id="ch04-92838">
1887 <title>Global Configuration Options </title>
1888
1889 <tgroup cols="5">
1890 <colspec colnum="1" colname="col1"/>
1891 <colspec colnum="2" colname="col2"/>
1892 <colspec colnum="3" colname="col3"/>
1893 <colspec colnum="4" colname="col4"/>
1894 <colspec colnum="5" colname="col5"/>
1895 <thead>
1896 <row>
1897
1898 <entry colname="col1"><para>Option</para></entry>
1899
1900 <entry colname="col2"><para>Parameters</para></entry>
1901
1902 <entry colname="col3"><para>Function</para></entry>
1903
1904 <entry colname="col4"><para>Default</para></entry>
1905
1906 <entry colname="col5"><para>Scope</para></entry>
1907
1908 </row>
1909
1910 </thead>
1911
1912 <tbody>
1913 <row>
1914
1915 <entry colname="col1"><para><literal>log file</literal></para></entry>
1916
1917 <entry colname="col2"><para>string (fully-qualified filename)</para></entry>
1918
1919 <entry colname="col3"><para>Sets the name and location of the log file that Samba is to use. Uses standard variables.</para></entry>
1920
1921 <entry colname="col4"><para>Specified in Samba makefile</para></entry>
1922
1923 <entry colname="col5"><para>Global</para></entry>
1924
1925 </row>
1926
1927 <row>
1928
1929 <entry colname="col1"><para><literal>log level</literal></para>
1930
1931 <para><literal>(debug level)</literal></para></entry>
1932
1933 <entry colname="col2"><para>numerical (0-10)</para></entry>
1934
1935 <entry colname="col3"><para>Sets the amount of log/debug messages that are sent to the log file. 0 is none, 3 is considerable.</para></entry>
1936
1937 <entry colname="col4"><para><literal>1</literal></para></entry>
1938
1939 <entry colname="col5"><para>Global</para></entry>
1940
1941 </row>
1942
1943 <row>
1944
1945 <entry colname="col1"><para><literal>max log size</literal></para></entry>
1946
1947 <entry colname="col2"><para>numerical (size in KB)</para></entry>
1948
1949 <entry colname="col3"><para>Sets the maximum size of log file. After the log exceeds this size, the file will be renamed to <emphasis>.bak</emphasis> and a new log file started.</para></entry>
1950
1951 <entry colname="col4"><para><literal>5000</literal></para></entry>
1952
1953 <entry colname="col5"><para>Global</para></entry>
1954
1955 </row>
1956
1957 <row>
1958
1959 <entry colname="col1"><para><literal>debug</literal></para>
1960
1961 <para><literal>timestamp (timestamp logs)</literal></para></entry>
1962
1963 <entry colname="col2"><para>boolean</para></entry>
1964
1965 <entry colname="col3"><para>If no, doesn't timestamp logs, making them easier to read during heavy debugging.</para></entry>
1966
1967 <entry colname="col4"><para><literal>yes</literal></para></entry>
1968
1969 <entry colname="col5"><para>Global</para></entry>
1970
1971 </row>
1972
1973 <row>
1974
1975 <entry colname="col1"><para><literal>syslog</literal></para></entry>
1976
1977 <entry colname="col2"><para>numerical (0-10)</para></entry>
1978
1979 <entry colname="col3"><para>Sets level of messages sent to <emphasis>syslog</emphasis>. Those levels below <literal>syslog level</literal> will be sent to the system logger.</para></entry>
1980
1981 <entry colname="col4"><para><literal>1</literal></para></entry>
1982
1983 <entry colname="col5"><para>Global</para></entry>
1984
1985 </row>
1986
1987 <row>
1988
1989 <entry colname="col1"><para><literal>syslog only</literal></para></entry>
1990
1991 <entry colname="col2"><para>boolean</para></entry>
1992
1993 <entry colname="col3"><para>If yes, uses <emphasis>syslog</emphasis> entirely and sends no output to the standard Samba log files.</para></entry>
1994
1995 <entry colname="col4"><para><literal>no</literal></para></entry>
1996
1997 <entry colname="col5"><para>Global</para></entry>
1998
1999 </row>
2000
2001 </tbody>
2002 </tgroup>
2003 </table>
2004
2005
2006 <sect3 role="" label="4.8.2.1" id="ch04-log-file-option">
2007 <title>log file</title>
2008
2009
2010 <para>On our server, Samba outputs log information to text files in the <filename>var</filename> subdirectory of the Samba home directory, as set by the makefile during the build. The <literal>log</literal> <literal>file</literal> option can be used to reset the name of the log file to another location. For example, to reset the name and location of the Samba log file to <filename>/usr/local/logs/samba.log</filename>, you could use the following:</para>
2011
2012
2013 <programlisting>[global]
2014         log file = /usr/local/logs/samba.log</programlisting>
2015
2016
2017 <para>You may use variable substitution to create log files specifically for individual users or clients.</para>
2018
2019
2020 <para>You can override the default log file location using the <literal>-l</literal> command-line switch when either daemon is started. However, this does not override the <literal>log</literal> <literal>file</literal> option. If you do specify this parameter, initial logging information will be sent to the file specified after <literal>-l</literal> (or the default specified in the Samba makefile) until the daemons have processed the <filename>smb.conf</filename> file and know to redirect it to a new log file.</para>
2021 </sect3>
2022
2023
2024
2025 <sect3 role="" label="4.8.2.2" id="ch04-SECT-8.1.2">
2026 <indexterm id="ch04-idx-968338-0"><primary>log level option</primary></indexterm>
2027 <title>
2028 log level</title>
2029
2030
2031 <para>The <literal>log</literal> <literal>level</literal> option sets the amount of data to be logged. Normally this is left at 0 or 1. However, if you have a specific problem you may want to set it at 3, which provides the most useful debugging information you would need to track down a problem. Levels above 3 provide information that's primarily for the developers to use for chasing internal bugs, and slows down the server considerably. Therefore, we recommend that you avoid setting this option to anything above 3.</para>
2032
2033
2034 <programlisting>[global]
2035 log file = /usr/local/logs/samba.log.%m
2036 log level = 3</programlisting>
2037 </sect3>
2038
2039
2040
2041 <sect3 role="" label="4.8.2.3" id="ch04-SECT-8.1.3">
2042 <indexterm id="ch04-idx-968341-0"><primary>max log size option</primary></indexterm>
2043 <title>
2044 max log size</title>
2045
2046
2047 <para>The <literal>max</literal> <literal>log</literal> <literal>size</literal> option sets the maximum size, in kilobytes, of the debugging log file that Samba keeps. When the log file exceeds this size, the current log file is renamed to add an <emphasis>.old</emphasis> extension (erasing any previous file with that name) and a new debugging log file is started with the original name. For example:</para>
2048
2049
2050 <programlisting>[global]
2051 log file = /usr/local/logs/samba.log.%m
2052 max log size = 1000</programlisting>
2053
2054
2055 <para>Here, if the size of any log file exceeds one megabyte in size, Samba renames the log file <emphasis>samba.log.</emphasis> <replaceable>machine-name</replaceable><emphasis>.old</emphasis> and a new log file is generated. If there was a file there previously with the <emphasis>.old</emphasis> extension, Samba deletes it. We highly recommend setting this option in your configuration files because debug logging (even at lower levels) can covertly eat away at your available disk space. Using this option protects unwary administrators from suddenly discovering that most of their disk space has been swallowed up by a single Samba log file.</para>
2056 </sect3>
2057
2058
2059
2060 <sect3 role="" label="4.8.2.4" id="ch04-SECT-8.1.4">
2061 <indexterm id="ch04-idx-968344-0"><primary>debug timestamp option</primary></indexterm>
2062 <indexterm id="ch04-idx-968344-1"><primary>timestamp logs option</primary></indexterm>
2063 <title>
2064
2065 ;debug timestamp or timestamp logs</title>
2066
2067
2068 <para>If you happen to be debugging a network problem and you find that the date-stamp and timestamp information within the Samba log lines gets in the way, you can turn it off by giving either the <literal>timestamp</literal> <literal>logs</literal> or the <literal>debug</literal> <literal>timestamp</literal> option (they're synonymous) a value of <literal>no</literal>. For example, a regular Samba log file presents its output in the following form:</para>
2069
2070
2071 <programlisting>12/31/98 12:03:34 hydra (192.168.220.101) connect to server network as user davecb</programlisting>
2072
2073
2074 <para>With a <literal>no</literal> value for this option, the output would appear without the datestamp or  the timestamp:</para>
2075
2076
2077 <programlisting>hydra (192.168.220.101) connect to server network as user davecb</programlisting>
2078 </sect3>
2079
2080
2081
2082 <sect3 role="" label="4.8.2.5" id="ch04-78696">
2083 <title>syslog</title>
2084
2085
2086 <para>
2087 <indexterm id="ch04-idx-967365-0"><primary>Unix</primary><secondary>options</secondary><tertiary sortas="system logger">for system logger</tertiary></indexterm>The <literal>syslog</literal>
2088 <indexterm id="ch04-idx-968349-0"><primary>syslog option</primary></indexterm> option causes Samba log messages to be sent to the Unix system logger. The type of log information to be sent is specified as the parameter for this argument. Like the <literal>log</literal> <literal>level</literal> option, it can be a number from 0 to 10. Logging information with a level less than the number specified will be sent to the system logger. However, debug logs equal to or above the <literal>syslog</literal> level, but less than log level, will still be sent to the standard Samba log files. To get around this, use the <literal>syslog</literal> <literal>only</literal> option. For example:</para>
2089
2090
2091 <programlisting>[global]
2092         log level = 3
2093         syslog = 1</programlisting>
2094
2095
2096 <para>With this, all logging information with a level of 0 would be sent to the standard Samba logs and the system logger, while information with levels 1, 2, and 3 would be sent only to the standard Samba logs. Levels above 3 are not logged at all. Note that all messages sent to the system logger are mapped to a priority level that the <emphasis>syslog</emphasis> process understands, as shown in <link linkend="ch04-80576">Table 4.8</link>. The default level is 1.</para>
2097
2098
2099 <table label="4.8" id="ch04-80576">
2100 <title>Syslog Priority Conversion </title>
2101
2102 <tgroup cols="2">
2103 <colspec colnum="1" colname="col1"/>
2104 <colspec colnum="2" colname="col2"/>
2105 <thead>
2106 <row>
2107
2108 <entry colname="col1"><para>Log Level</para></entry>
2109
2110 <entry colname="col2"><para>Syslog Priority</para></entry>
2111
2112 </row>
2113
2114 </thead>
2115
2116 <tbody>
2117 <row>
2118
2119 <entry colname="col1"><para>0</para></entry>
2120
2121 <entry colname="col2"><para><literal>LOG_ERR</literal></para></entry>
2122
2123 </row>
2124
2125 <row>
2126
2127 <entry colname="col1"><para>1</para></entry>
2128
2129 <entry colname="col2"><para><literal>LOG_WARNING</literal></para></entry>
2130
2131 </row>
2132
2133 <row>
2134
2135 <entry colname="col1"><para>2</para></entry>
2136
2137 <entry colname="col2"><para><literal>LOG_NOTICE</literal></para></entry>
2138
2139 </row>
2140
2141 <row>
2142
2143 <entry colname="col1"><para>3</para></entry>
2144
2145 <entry colname="col2"><para><literal>LOG_INFO</literal></para></entry>
2146
2147 </row>
2148
2149 <row>
2150
2151 <entry colname="col1"><para>4 and above</para></entry>
2152
2153 <entry colname="col2"><para><literal>LOG_DEBUG</literal></para></entry>
2154
2155 </row>
2156
2157 </tbody>
2158 </tgroup>
2159 </table>
2160
2161
2162 <para>If you wish to use <emphasis>syslog</emphasis>, you will have to run <literal>configure</literal> <literal>--with-syslog</literal> when compiling Samba, and you will need to configure your <filename>/etc/syslog.conf</filename> to suit. (See <link linkend="ch04-97929">Section 4.8.1</link> earlier in this chapter.)</para>
2163 </sect3>
2164
2165
2166
2167 <sect3 role="" label="4.8.2.6" id="ch04-SECT-8.1.6">
2168 <indexterm id="ch04-idx-968350-0"><primary>syslog only option</primary></indexterm>
2169 <title>
2170 syslog only</title>
2171
2172
2173 <para>The <literal>syslog</literal> <literal>only</literal> option tells Samba not to use the regular logging files&mdash;the system logger only. To enable this, specify the following option in the global ection of the Samba configuration file:</para>
2174
2175
2176 <programlisting>[global]
2177         syslog only = <indexterm id="ch04-idx-967342-0" class="endofrange" startref="ch04-idx-967340-0"/>
2178 <indexterm id="ch04-idx-967342-1" class="endofrange" startref="ch04-idx-967340-1"/>yes<indexterm id="ch04-idx-967031-0" class="endofrange" startref="ch04-idx-967030-0"/></programlisting>
2179 </sect3>
2180 </sect2>
2181 </sect1>
2182 </chapter>