diff options
Diffstat (limited to 'docs/htmldocs/using_samba/ch06.html')
| -rw-r--r-- | docs/htmldocs/using_samba/ch06.html | 2727 |
1 files changed, 2727 insertions, 0 deletions
diff --git a/docs/htmldocs/using_samba/ch06.html b/docs/htmldocs/using_samba/ch06.html new file mode 100644 index 0000000000..a507b7c9d9 --- /dev/null +++ b/docs/htmldocs/using_samba/ch06.html @@ -0,0 +1,2727 @@ +<html> +<body bgcolor="#ffffff"> + +<img src="samba2_xs.gif" border="0" alt=" " height="100" width="76" +hspace="10" align="left" /> + +<h1 class="head0">Chapter 6. The Samba Configuration File</h1> + + +<p><a name="INDEX-1"/>In +previous 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.</p> + +<p>Samba's daemons, <em class="emphasis">smbd</em> and +<em class="emphasis">nmbd</em>, are controlled through a single ASCII +file, <em class="filename">smb.conf</em>, that can contain over 300 unique +options (also called parameters). Some of these options you will use +and change frequently; others you might never use, depending on how +much functionality you want Samba to offer its clients.</p> + +<p>This chapter introduces the structure of the Samba configuration file +and shows you how to use options to create and modify disk shares. +Subsequent chapters will discuss browsing, how to configure users, +security, printing, and other topics related to implementing Samba on +your network.</p> + + + +<div class="sect1"><a name="samba2-CHP-6-SECT-1"/> + +<h2 class="head1">The Samba Configuration File</h2> + +<p>The Samba configuration file, called <em class="filename">smb.conf</em> by +default, uses the same format as Windows +<em class="filename">.ini</em><a name="INDEX-2"/><a name="INDEX-3"/> files. If you have ever worked with a +<em class="filename">.ini</em> file, you will find +<em class="filename">smb.conf</em> easy to create and modify. Even if you +haven't, you will find the format to be simple and +easy to learn. Here is an example of a Samba +<a name="INDEX-4"/>configuration +file:</p> + +<blockquote><pre class="code">[global] + workgroup = METRAN + encrypt passwords = yes + wins support = yes + log level = 1 + max log size = 1000 + read only = no +[homes] + browsable = no + map archive = yes +[printers] + path = /var/tmp + printable = yes + min print space = 2000 +[test] + browsable = yes + read only = yes + path = /usr/local/samba/tmp</pre></blockquote> + +<p>This configuration file is based on the one we created in <a href="ch02.html">Chapter 2</a> and sets up a workgroup in which Samba +authenticates users using encrypted passwords and the default +user-level security method. Samba is providing WINS name server +support. We've configured very basic event logging +to use a log file not to exceed 1MB in size. The +<tt class="literal">[homes]</tt> share has been added to allow Samba to +create a disk share for the home directory of each user who has a +standard Unix account on the server. In addition, each printer +registered on the server will be publicly available, as will a single +read-only share that maps to the +<em class="filename">/usr/local/samba/tmp</em> directory.</p> + + +<div class="sect2"><a name="samba2-CHP-6-SECT-1.1"/> + +<h3 class="head2">Configuration File Structure</h3> + +<p><a name="INDEX-5"/>Let's take another +look at this configuration file, this time from a higher level:</p> + +<blockquote><pre class="code">[global] + ... +[homes] + ... +[printers] + ... +[test] + ...</pre></blockquote> + +<p><a name="INDEX-6"/><a name="INDEX-7"/>The +names inside the square brackets delineate unique +<em class="firstterm">sections</em> of the <em class="filename">smb.conf</em> +file; each section names the share (or service) to which the section +refers. For example, the <tt class="literal">[test]</tt> and +<tt class="literal">[homes]</tt> sections are unique disk shares; they +contain options that map to specific directories on the Samba server. +The <tt class="literal">[printers]</tt> share contains options that map to +various printers on the server. All the sections defined in the +<em class="filename">smb.conf</em> file, with the exception of the +<tt class="literal">[global]</tt> section, will be available as a disk or +printer share to clients connecting to the Samba server.</p> + +<p>The remaining lines are individual configuration options for that +share. These options will continue until a new section is encountered +or until the end of the file is reached. Each configuration option +follows a simple format:</p> + +<blockquote><pre class="code"><em class="replaceable">option</em> = <em class="replaceable">value</em></pre></blockquote> + +<p><a name="INDEX-8"/>Options in +the <em class="filename">smb.conf</em> file are set by assigning a value +to them. We should warn you up front that some of the option names in +Samba are poorly chosen. For example, <tt class="literal">read</tt> +<tt class="literal">only</tt> is self-explanatory and is typical of many +recent Samba options. The <tt class="literal">public</tt> option is an +older option and is vague. It now has a less-confusing synonym +<tt class="literal">guest</tt> <tt class="literal">ok</tt> (meaning it can be +accessed by guests). <em class="emphasis">Appendix B</em> contains an +alphabetical index of all the configuration options and their +meanings.</p> + + +<div class="sect3"><a name="samba2-CHP-6-SECT-1.1.1"/> + +<h3 class="head3">Whitespace, quotes, and commas</h3> + +<p>An important item to remember about configuration options is that all +whitespace within the <em class="replaceable">value</em> is +significant. For example, consider the following option:</p> + +<blockquote><pre class="code">volume = The Big Bad Hard Drive Number 3543</pre></blockquote> + +<p>Samba strips away the spaces up to the first <tt class="literal">T</tt> in +<tt class="literal">The</tt>. 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 <tt class="literal">read</tt> +<tt class="literal">only</tt>), but we recommend you follow convention and +keep spaces between the words of options.</p> + +<p>If you feel safer including quotation marks at the beginning and end +of a configuration option's value, you can do so. +Samba will ignore these quotation marks when it encounters them. +Never use quotation marks around an option name; Samba will treat +this as an error.</p> + +<p>Usually, you can use whitespaces or commas to separate a series of +values in a list. These two options are equivalent:</p> + +<blockquote><pre class="code">netbios aliases = sales, accounting, payroll +netbios aliases = sales accounting payroll</pre></blockquote> + +<p>In some cases, you must use one form of separation—sometimes +spaces are required, and sometimes commas.</p> + + +</div> + + + +<div class="sect3"><a name="samba2-CHP-6-SECT-1.1.2"/> + +<h3 class="head3">Capitalization</h3> + +<p><a name="INDEX-9"/>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 <em class="filename">/export/samba/simple +</em>:</p> + +<blockquote><pre class="code">PATH = /EXPORT/SAMBA/SIMPLE</pre></blockquote> + +<p>Samba would have no problem with the <tt class="literal">path</tt> +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 <em class="emphasis">is</em> +case-sensitive. Consequently, the path listed would not be found, and +clients could not connect to the share.</p> + + +</div> + + + +<div class="sect3"><a name="samba2-CHP-6-SECT-1.1.3"/> + +<h3 class="head3">Line continuation</h3> + +<p><a name="INDEX-10"/>You can continue a line in the +Samba configuration file using the backslash, like this:</p> + +<blockquote><pre class="code">comment = The first share that has the primary copies \ + of the new Teamworks software product.</pre></blockquote> + +<p>Because of the backslash, these two lines will be treated as one line +by Samba. The second line begins at the first nonwhitespace character +that Samba encounters; in this case, the <tt class="literal">o</tt> in +<tt class="literal">of</tt>.</p> + + +</div> + + + +<div class="sect3"><a name="samba2-CHP-6-SECT-1.1.4"/> + +<h3 class="head3">Comments</h3> + +<p><a name="INDEX-11"/>You can +insert comments in the <em class="filename">smb.conf</em> configuration +file by starting a line with either a hash (<tt class="literal">#</tt>) or +a semicolon ( <tt class="literal">;</tt> ). For this purpose, both +characters are equivalent. For example, the first three lines in the +following example would be considered comments:</p> + +<blockquote><pre class="code"># This is the printers section. We have given a minimum print +; space of 2000 to prevent some errors that we've seen when +; the spooler runs out of space. + +[printers] + public = yes + min print space = 2000</pre></blockquote> + +<p>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 continuation +character (<tt class="literal">\</tt>) will <em class="emphasis">not</em> be +honored on a commented line. Like the rest of the line, it is +ignored.</p> +<a name="samba2-CHP-6-NOTE-128"/><blockquote class="note"><h4 class="objtitle">WARNING</h4> +<p>Samba does not allow mixing of comment lines and parameters. Be +careful not to put comments on the same line as anything else, such +as:</p> + + +<blockquote><pre class="code">path = /d # server's data partition</pre></blockquote> + + +<p>Errors such as this, where the parameter value is defined with a +string, can be tricky to notice. The <em class="emphasis">testparm</em> +program won't complain, and the only clues +you'll receive are that +<em class="emphasis">testparm</em> reports the <tt class="literal">path</tt> +parameter set to <tt class="literal">/d # server's data partition</tt>, and +the failures that result when clients attempt to access the share.</p> +</blockquote> + + +</div> + + + +<div class="sect3"><a name="samba2-CHP-6-SECT-1.1.5"/> + +<h3 class="head3">Changes at runtime</h3> + +<p><a name="INDEX-12"/>You can modify the +<em class="filename">smb.conf</em> 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. If it finds any +changes, they are immediately put into effect.</p> + +<a name="samba2-CHP-6-NOTE-129"/><blockquote class="note"><h4 class="objtitle">TIP</h4> +<p>Having Samba check the configuration file automatically can be +convenient, but it also means that if you edit +<em class="filename">smb.conf</em> directly, you might be immediately +changing your network's <a name="INDEX-13"/>configuration every time you save the +file. If you're making anything more than a minor +change, it may be wiser to copy <em class="filename">smb.conf</em> to a +temporary file, edit that, run <tt class="literal">testparm</tt> +<em class="replaceable">filename</em> to check it, and then copy the +temporary file back to <em class="filename">smb.conf</em>. That way, you +can be sure to put all your changes into effect at once, and only +after you are confident that you have created the exact configuration +you wish to implement.</p> +</blockquote> + +<p>If you don't want to wait for the configuration file +to be reloaded automatically, you can force a reload either by +sending a hangup signal to the <em class="emphasis">smbd</em> and +<em class="emphasis">nmbd</em> processes or simply by restarting the +daemons. Actually, it can be a good idea to restart the daemons +because it forces the clients to disconnect and reconnect, ensuring +that the new configuration is applied to all clients. We showed you +how to restart the daemons in <a href="ch02.html">Chapter 2</a>, and +sending them a hangup (HUP) signal is very similar. On Linux, it can +be done with the command:</p> + +<blockquote><pre class="code"># <tt class="userinput"><b>killall -HUP smbd nmbd</b></tt></pre></blockquote> + +<p>In this case, 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 go into effect +immediately either. (This behavior was implemented intentionally +because it keeps active clients from being suddenly disconnected or +encountering unexpected access problems while a session is open.) +<a name="INDEX-14"/></p> + + +</div> + + +</div> + + +<div class="sect2"><a name="samba2-CHP-6-SECT-1.2"/> + +<h3 class="head2">Variables</h3> + +<p><a name="INDEX-15"/>Because a +new copy of the<em class="filename"> </em><em class="emphasis">smbd</em> daemon +is created for each connecting client, it is possible for each client +to have its own customized configuration file. Samba allows a +limited, yet useful, form of variable substitution in the +configuration file to allow information about the Samba server and +the client to be included in the configuration at the time the client +connects. Inside the configuration file, a variable begins with a +percent sign (<tt class="literal">%</tt>), followed by a single upper- or +lowercase letter, and can be used only on the right side of a +configuration option (i.e., after the equal sign). An example is:</p> + +<blockquote><pre class="code">[pub] + path = /home/ftp/pub/%a</pre></blockquote> + +<p>The <tt class="literal">%a</tt><a name="INDEX-16"/> stands for the client +system's architecture and will be replaced as shown +in <a href="ch06.html#samba2-CHP-6-TABLE-1">Table 6-1</a>.</p> + +<a name="samba2-CHP-6-TABLE-1"/><h4 class="head4">Table 6-1. %a substitution</h4><table border="1"> + + + +<tr> +<th> +<p>Client operating system +("architecture")</p> +</th> +<th> +<p>Replacement string</p> +</th> +</tr> + + +<tr> +<td> +<p>Windows for Workgroups</p> +</td> +<td> +<p><tt class="literal">WfWg</tt></p> +</td> +</tr> +<tr> +<td> +<p>Windows 95 and Windows 98</p> +</td> +<td> +<p><tt class="literal">Win95</tt></p> +</td> +</tr> +<tr> +<td> +<p>Windows NT</p> +</td> +<td> +<p><tt class="literal">WinNT</tt></p> +</td> +</tr> +<tr> +<td> +<p>Windows 2000 and Windows XP</p> +</td> +<td> +<p><tt class="literal">Win2K</tt></p> +</td> +</tr> +<tr> +<td> +<p>Samba</p> +</td> +<td> +<p><tt class="literal">Samba</tt></p> +</td> +</tr> +<tr> +<td> +<p>Any OS not listed earlier</p> +</td> +<td> +<p><tt class="literal">UNKNOWN</tt></p> +</td> +</tr> + +</table> + +<p>In this example, Samba will assign a unique path for the +<tt class="literal">[pub]</tt> share to client systems based on what +operating system they are running. The paths that each client would +see as its share differ according to the client's +architecture:</p> + +<blockquote><pre class="code">/home/ftp/pub/WfwG +/home/ftp/pub/Win95 +/home/ftp/pub/WinNT +/home/ftp/pub/Win2K +/home/ftp/pub/Samba +/home/ftp/pub/UNKNOWN</pre></blockquote> + +<p>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. +<a name="INDEX-17"/><a name="INDEX-18"/>Samba +has 20 variables, as shown in <a href="ch06.html#samba2-CHP-6-TABLE-2">Table 6-2</a>.</p> + +<a name="samba2-CHP-6-TABLE-2"/><h4 class="head4">Table 6-2. Samba variables</h4><table border="1"> + + + +<tr> +<th> +<p>Variable</p> +</th> +<th> +<p>Definition</p> +</th> +</tr> + + +<tr> +<td> +<p><b class="emphasis-bold">Client variables</b></p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">%a</tt><a name="INDEX-19"/></p> +</td> +<td> +<p>Client's architecture (see <a href="ch06.html#samba2-CHP-6-TABLE-1">Table 6-1</a>)</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">%I</tt><a name="INDEX-20"/></p> +</td> +<td> +<p>Client's IP address (e.g., 172.16.1.2)</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">%m</tt><a name="INDEX-21"/></p> +</td> +<td> +<p>Client's NetBIOS name</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">%M</tt><a name="INDEX-22"/></p> +</td> +<td> +<p>Client's DNS name</p> +</td> +</tr> +<tr> +<td> +<p><b class="emphasis-bold">User variables</b></p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">%u</tt><a name="INDEX-23"/></p> +</td> +<td> +<p>Current Unix username</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">%U</tt><a name="INDEX-24"/></p> +</td> +<td> +<p>Requested client username (not always used by Samba)</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">%H</tt><a name="INDEX-25"/></p> +</td> +<td> +<p>Home directory of <tt class="literal">%u</tt></p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">%g</tt><a name="INDEX-26"/></p> +</td> +<td> +<p>Primary group of <tt class="literal">%u</tt></p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">%G</tt><a name="INDEX-27"/></p> +</td> +<td> +<p>Primary group of <tt class="literal">%U</tt></p> +</td> +</tr> +<tr> +<td> +<p><b class="emphasis-bold">Share variables</b></p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">%S</tt><a name="INDEX-28"/></p> +</td> +<td> +<p>Current share's name</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">%P</tt><a name="INDEX-29"/></p> +</td> +<td> +<p>Current share's root directory</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">%p</tt><a name="INDEX-30"/></p> +</td> +<td> +<p>Automounter's path to the share's +root directory, if different from <tt class="literal">%P</tt></p> +</td> +</tr> +<tr> +<td> +<p><b class="emphasis-bold">Server variables</b></p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">%d</tt><a name="INDEX-31"/></p> +</td> +<td> +<p>Current server process ID</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">%h</tt><a name="INDEX-32"/></p> +</td> +<td> +<p>Samba server's DNS hostname</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">%L</tt><a name="INDEX-33"/></p> +</td> +<td> +<p>Samba server's NetBIOS name</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">%N</tt><a name="INDEX-34"/></p> +</td> +<td> +<p>Home directory server, from the automount map</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">%v</tt><a name="INDEX-35"/></p> +</td> +<td> +<p>Samba version</p> +</td> +</tr> +<tr> +<td> +<p><b class="emphasis-bold">Miscellaneous variables</b></p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">%R</tt><a name="INDEX-36"/></p> +</td> +<td> +<p>The SMB protocol level that was negotiated</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">%T</tt><a name="INDEX-37"/></p> +</td> +<td> +<p>The current date and time</p> +</td> +</tr> +<tr> +<td> +<p><a name="INDEX-38"/>%$<em class="replaceable">var</em></p> +</td> +<td> +<p>The value of environment variable <tt class="literal">var</tt></p> +</td> +</tr> + +</table> + +<p>Here's another example of using +<a name="INDEX-39"/><a name="INDEX-40"/><a name="INDEX-41"/>variables: let's say there +are five clients on your network, but one client, +<tt class="literal">maya</tt>, requires a slightly different +<tt class="literal">[homes]</tt> configuration. With Samba, +it's simple to handle this:</p> + +<blockquote><pre class="code">[homes] + ... + include = /usr/local/samba/lib/smb.conf.%m + ...</pre></blockquote> + +<p>The <tt class="literal">include</tt> option here causes a separate +configuration file for each particular NetBIOS machine +(<tt class="literal">%m</tt>) to be read in addition to the current file. +If the hostname of the client system is <tt class="literal">maya</tt>, and +if a <em class="filename">smb.conf.maya</em> file exists in the +<em class="filename">/usr/local/samba/lib</em> directory, Samba will +insert that configuration file into the default one. If any +configuration options are restated in +<em class="filename">smb.conf.maya</em>, 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 +<tt class="literal">include</tt> option, Samba will honor those restated +values for the share in which they are defined.</p> + +<p>If the file specified by the <tt class="literal">include</tt> parameter +does not exist, 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 <tt class="literal">maya</tt> when +using this strategy, instead of one for each client that is on the +network.</p> + +<p>Client-specific configuration files can be used to customize +particular clients. They also can be used to make debugging Samba +easier. For example, 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.</p> + +<p>You can use the variables in <a href="ch06.html#samba2-CHP-6-TABLE-2">Table 6-2</a> 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. +<a name="INDEX-42"/></p> + + +</div> + + +</div> + + + +<div class="sect1"><a name="samba2-CHP-6-SECT-2"/> + +<h2 class="head1">Special Sections</h2> + +<p>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 every configuration option listed here; +we'll go over each of them in the upcoming chapters.</p> + + +<div class="sect2"><a name="samba2-CHP-6-SECT-2.1"/> + +<h3 class="head2">The [ global] Section</h3> + +<p>The <tt class="literal">[global]</tt><a name="INDEX-43"/><a name="INDEX-44"/> section appears in virtually +every Samba configuration file, even though it is not mandatory. +There are two purposes for the <tt class="literal">[global]</tt> section. +Server-wide settings are defined here, and any options that apply to +shares will be used as a default in all share definitions, unless +overridden within the share definition.</p> + +<p>To illustrate this, let's again look at the example +at the beginning of the chapter:</p> + +<blockquote><pre class="code">[global] + workgroup = METRAN + encrypt passwords = yes + wins support = yes + log level = 1 + max log size = 1000 + read only = no +[homes] + browsable = no + map archive = yes +[printers] + path = /var/tmp + printable = yes + min print space = 2000 +[test] + browsable = yes + read only = yes + path = /usr/local/samba/tmp</pre></blockquote> + +<p>When a client connects to the <tt class="literal">[test]</tt> share, Samba +first reads the <tt class="literal">[global]</tt> section and sets the +option <tt class="literal">read</tt> <tt class="literal">only</tt> +<tt class="literal">=</tt> <tt class="literal">no</tt> as the global default for +each share it encounters throughout the configuration file. This +includes the <tt class="literal">[homes]</tt> and <tt class="literal">[test]</tt> +shares. When it reads the definition of the <tt class="literal">[test]</tt> +share, it then finds the configuration option <tt class="literal">read</tt> +<tt class="literal">only</tt> <tt class="literal">=</tt> <tt class="literal">yes</tt> +and overrides the default from the <tt class="literal">[global]</tt> +section with the value <tt class="literal">yes</tt>.</p> + +<p>Any option that appears before the first marked section is assumed to +be a global option. This means that the <tt class="literal">[global]</tt> +section heading is not absolutely required; however, we suggest you +always include it for clarity and to ensure future compatibility.</p> + + +</div> + + +<div class="sect2"><a name="samba2-CHP-6-SECT-2.2"/> + +<h3 class="head2">The [ homes] Section</h3> + +<p>If a client attempts to connect to a share that +doesn't appear in the <em class="filename">smb.conf</em> +file, Samba will search for a +<tt class="literal">[homes]</tt><a name="INDEX-45"/><a name="INDEX-46"/> share in the +configuration file. If a <tt class="literal">[homes]</tt> share exists, the +unresolved share name is assumed to be a Unix username. If that +username appears in the password database on the Samba server, Samba +assumes the client is a Unix user trying to connect to her home +directory on the server.</p> + +<p>For example, assume a client system is connecting to the Samba server +<tt class="literal">toltec</tt> for the first time and tries to connect to +a share named <tt class="literal">[alice]</tt>. There is no +<tt class="literal">[alice]</tt> share defined in the +<em class="filename">smb.conf</em> file, but there is a +<tt class="literal">[homes]</tt>, so Samba searches the password database +file and finds an <tt class="literal">alice</tt> user account is present on +the system. Samba then checks the password provided by the client +against user <tt class="literal">alice</tt>'s Unix +password—either with the password database file if +it's using nonencrypted passwords or with +Samba's <em class="filename">smbpasswd</em> file if +encrypted passwords are in use. If the passwords match, Samba knows +it has guessed right: the user <tt class="literal">alice</tt> is trying to +connect to her home directory. Samba will then create a share called +<tt class="literal">[alice]</tt> for her, with the share's +path set to <tt class="literal">alice</tt>'s home +directory.</p> + +<p>The process of using the <tt class="literal">[homes]</tt> section to create +users (and dealing with their passwords) is discussed in more detail +in <a href="ch09.html">Chapter 9</a>.</p> + + +</div> + + +<div class="sect2"><a name="samba2-CHP-6-SECT-2.3"/> + +<h3 class="head2">The [printers] Section</h3> + +<p>The third special section is called +<tt class="literal">[printers]</tt><a name="INDEX-47"/><a name="INDEX-48"/> and is similar to +<tt class="literal">[homes]</tt>. If a client attempts to connect to a +share that isn't in the +<em class="filename">smb.conf</em> 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 +printer capabilities file (usually +<em class="filename">/etc/printcap</em>) to see if the share name appears +there.<a name="FNPTR-1"/><a href="#FOOTNOTE-1">[1]</a> If it does, Samba creates a share named after the +printer.</p> + +<p>This means that as with <tt class="literal">[homes]</tt>, you +don't have to maintain a share for each system +printer in the <em class="filename">smb.conf</em> file. Instead, Samba +honors the Unix printer registry if you ask it to, and it provides +the registered printers to the client systems. However, there is a +potential difficulty: if you have an account named +<tt class="literal">fred</tt> and a printer named <tt class="literal">fred</tt>, +Samba will always find the user account first, even if the client +really needed to connect to the printer.</p> + +<p>The process of setting up the <tt class="literal">[printers]</tt> share is +discussed in more detail in <a href="ch10.html">Chapter 10</a>.</p> + + +</div> + + +</div> + + + +<div class="sect1"><a name="samba2-CHP-6-SECT-3"/> + +<h2 class="head1">Configuration Options</h2> + +<p><a name="INDEX-49"/>Options in +the Samba configuration files fall into one of two categories: +<em class="firstterm">global</em> options or <em class="firstterm">share</em> +options. Each category dictates where an option can appear in the +configuration file.</p> + +<dl> +<dt><b>Global options</b></dt> +<dd> +<p>Global options must appear in the <tt class="literal">[global]</tt> 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.</p> +</dd> + + + +<dt><b>Share options</b></dt> +<dd> +<p>Share options can appear in share definitions, the +<tt class="literal">[global]</tt> section, or both. If they appear in the +<tt class="literal">[global]</tt> section, they will define a default +behavior for all shares unless a share overrides the option with a +value of its own.</p> +</dd> + +</dl> + +<p>In addition, configuration options can take three kinds of values. +They are as follows:</p> + +<dl> +<dt><b>Boolean</b></dt> +<dd> +<p>These are simply yes or no values, but can be represented by any of +the following: <tt class="literal">yes</tt>, <tt class="literal">no</tt>, +<tt class="literal">true</tt>, <tt class="literal">false</tt>, +<tt class="literal">1</tt>, or <tt class="literal">0</tt>. The values are +case-insensitive: <tt class="literal">YES</tt> is the same as +<tt class="literal">yes</tt>.</p> +</dd> + + + +<dt><b>Numeric</b></dt> +<dd> +<p>This is a decimal, hexadecimal, or octal number. The standard +<tt class="literal">0x</tt><em class="emphasis">nn</em> syntax is used for +hexadecimal and <tt class="literal">0</tt><em class="emphasis">nnn</em> for +octal.</p> +</dd> + + + +<dt><b>String</b></dt> +<dd> +<p>This is a string of case-sensitive characters, such as a filename or +a username.</p> +</dd> + +</dl> + + +<div class="sect2"><a name="samba2-CHP-6-SECT-3.1"/> + +<h3 class="head2">Configuration File Options</h3> + +<p>You can instruct Samba to include or replace configuration options as +it is processing them. The options to do this are summarized in <a href="ch06.html#samba2-CHP-6-TABLE-3">Table 6-3</a>.</p> + +<a name="samba2-CHP-6-TABLE-3"/><h4 class="head4">Table 6-3. Configuration file options</h4><table border="1"> + + + + + + +<tr> +<th> +<p>Option</p> +</th> +<th> +<p>Parameters</p> +</th> +<th> +<p>Function</p> +</th> +<th> +<p>Default</p> +</th> +<th> +<p>Scope</p> +</th> +</tr> + + +<tr> +<td> +<p><tt class="literal">config</tt> <tt class="literal">file</tt></p> +</td> +<td> +<p>string (name of file)</p> +</td> +<td> +<p>Sets the location of a configuration file to use instead of the +current one</p> +</td> +<td> +<p>None</p> +</td> +<td> +<p>Global</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">include</tt></p> +</td> +<td> +<p>string (name of file)</p> +</td> +<td> +<p>Specifies an additional set of configuration options to be included +in the configuration file</p> +</td> +<td> +<p>None</p> +</td> +<td> +<p>Global</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">copy</tt></p> +</td> +<td> +<p>string (name of share)</p> +</td> +<td> +<p>Allows you to clone the configuration options of another share in the +current share</p> +</td> +<td> +<p>None</p> +</td> +<td> +<p>Share</p> +</td> +</tr> + +</table> + + +<div class="sect3"><a name="samba2-CHP-6-SECT-3.1.1"/> + +<h3 class="head3">config file</h3> + +<p>The global <tt class="literal">config</tt><a name="INDEX-50"/> <tt class="literal">file</tt> +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 +encountered so far, will be discarded, and Samba will configure +itself entirely with the options in the new file. Variables can be +used with the <tt class="literal">config</tt> <tt class="literal">file</tt> +option, which is useful in the event that you want to use a special +configuration file based on the NetBIOS machine name or user of the +client that is connecting.</p> + +<p>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:</p> + +<blockquote><pre class="code">[global] + config file = /usr/local/samba/lib/smb.conf.%m</pre></blockquote> + +<p>If the configuration file specified does not exist, the option is +ignored, and Samba will continue to configure itself based on the +current file. This allows a default configuration file to serve most +clients, while providing for exceptions with customized configuration +files.</p> + + +</div> + + + +<div class="sect3"><a name="samba2-CHP-6-SECT-3.1.2"/> + +<h3 class="head3">include</h3> + +<p>This <a name="INDEX-51"/>option, discussed in greater detail +earlier, copies the target file into the current configuration file +at the point specified, as shown in <a href="ch06.html#samba2-CHP-6-FIG-1">Figure 6-1</a>. +This option also can be used with variables. You can use this option +as follows:</p> + +<blockquote><pre class="code">[global] + include = /usr/local/samba/lib/smb.conf.%m</pre></blockquote> + +<p>If the configuration file specified does not exist, the option is +ignored. Options in the include file override any option specified +previously, but not options that are specified later. In <a href="ch06.html#samba2-CHP-6-FIG-1">Figure 6-1</a>, all three options will override their +previous values.</p> + +<div class="figure"><a name="samba2-CHP-6-FIG-1"/><img src="figs/sam2_0601.gif"/></div><h4 class="head4">Figure 6-1. The include option in a Samba configuration file</h4> + +<p>The <tt class="literal">include</tt> option does not work with the +variables <tt class="literal">%u</tt> (user), <tt class="literal">%P</tt> +(current share's root directory), or +<tt class="literal">%S</tt> (current share's name) because +they are not set at the time the <tt class="literal">include</tt> parameter +is processed.</p> + + +</div> + + + +<div class="sect3"><a name="samba2-CHP-6-SECT-3.1.3"/> + +<h3 class="head3">copy</h3> + +<p>The <tt class="literal">copy</tt><a name="INDEX-52"/> 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:</p> + +<blockquote><pre class="code">[template] + writable = yes + browsable = yes + valid users = andy, dave, jay + +[data] + path = /usr/local/samba + copy = template</pre></blockquote> + +<p>Note that any options in the share that invoked the +<tt class="literal">copy</tt> directive will override those in the cloned +share; it does not matter whether they appear before or after the +<tt class="literal">copy</tt> directive. <a name="INDEX-53"/></p> + + +</div> + + +</div> + + +</div> + + + +<div class="sect1"><a name="samba2-CHP-6-SECT-4"/> + +<h2 class="head1">Server Configuration</h2> + +<p><a name="INDEX-54"/>We will now start from +scratch and build a configuration file for our Samba server. First we +will introduce three basic configuration options that can appear in +the <tt class="literal">[global]</tt> section of the +<em class="filename">smb.conf</em> file:</p> + +<blockquote><pre class="code">[global] + # Server configuration parameters + netbios name = toltec + server string = Samba %v on %L + workgroup = METRAN + encrypt passwords = yes</pre></blockquote> + +<p>This configuration file is pretty simple; it advertises the Samba +server under the NetBIOS name <tt class="literal">toltec</tt>. In addition, +it places the system in the METRAN workgroup and displays a +description to clients that includes the Samba version number, as +well as the NetBIOS name of the Samba server.</p> + +<a name="samba2-CHP-6-NOTE-130"/><blockquote class="note"><h4 class="objtitle">TIP</h4> +<p>If you used the line <tt class="literal">encrypt passwords = yes</tt> in +your earlier configuration file, you should do so here as well.</p> +</blockquote> + +<p>If you like, you can go ahead and try this configuration file. Create +a file named <em class="filename">smb.conf</em> under the +<em class="filename">/usr/local/samba/lib</em> directory with the text +listed earlier. Then restart the Samba server and use a Windows +client to verify the results. Be sure that your Windows clients are +in the METRAN workgroup as well. After double-clicking the Network +Neighborhood on a Windows client, you should see a window similar to +<a href="ch06.html#samba2-CHP-6-FIG-2">Figure 6-2</a>. (In this figure, +<tt class="literal">Mixtec</tt> is another Samba server, +<tt class="literal">a</tt>nd <tt class="literal">Zapotec</tt> is a Windows +client.)</p> + +<div class="figure"><a name="samba2-CHP-6-FIG-2"/><img src="figs/sam2_0602.gif"/></div><h4 class="head4">Figure 6-2. Network Neighborhood showing Toltec, the Samba server</h4> + +<p>You can verify the <tt class="literal">server</tt> +<tt class="literal">string</tt> by listing the details of the Network +Neighborhood window (select Details in the View menu). You should see +a window similar to <a href="ch06.html#samba2-CHP-6-FIG-3">Figure 6-3</a>.</p> + +<div class="figure"><a name="samba2-CHP-6-FIG-3"/><img src="figs/sam2_0603.gif"/></div><h4 class="head4">Figure 6-3. Network Neighborhood details listing</h4> + +<p>If you were to click the <em class="filename">toltec</em> 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.</p> + + +<div class="sect2"><a name="samba2-CHP-6-SECT-4.1"/> + +<h3 class="head2">Server Configuration Options</h3> + +<p><a href="ch06.html#samba2-CHP-6-TABLE-4">Table 6-4</a> summarizes the server configuration +options introduced previously. All three of these options are global +in scope, so they must appear in the <tt class="literal">[global]</tt> +section of the configuration file.<a name="INDEX-55"/></p> + +<a name="samba2-CHP-6-TABLE-4"/><h4 class="head4">Table 6-4. Server configuration options</h4><table border="1"> + + + + + + +<tr> +<th> +<p>Option</p> +</th> +<th> +<p>Parameters</p> +</th> +<th> +<p>Function</p> +</th> +<th> +<p>Default</p> +</th> +<th> +<p>Scope</p> +</th> +</tr> + + +<tr> +<td> +<p><tt class="literal">netbios</tt> <tt class="literal">name</tt></p> +</td> +<td> +<p>string</p> +</td> +<td> +<p>NetBIOS name of the Samba server</p> +</td> +<td> +<p>Server's unqualified DNS hostname</p> +</td> +<td> +<p>Global</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">workgroup</tt></p> +</td> +<td> +<p>string</p> +</td> +<td> +<p>NetBIOS group to which the server belongs</p> +</td> +<td> +<p>Defined at compile time</p> +</td> +<td> +<p>Global</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">server</tt> <tt class="literal">string</tt></p> +</td> +<td> +<p>string</p> +</td> +<td> +<p>Descriptive string for the Samba server</p> +</td> +<td> +<p><tt class="literal">Samba %v</tt></p> +</td> +<td> +<p>Global</p> +</td> +</tr> + +</table> + + +<div class="sect3"><a name="samba2-CHP-6-SECT-4.1.1"/> + +<h3 class="head3">netbios name</h3> + +<p>The <tt class="literal">netbios</tt><a name="INDEX-56"/> <tt class="literal">name</tt> option +allows you to set the NetBIOS name of the server. For example:</p> + +<blockquote><pre class="code">netbios name = YORKVM1</pre></blockquote> + +<p>The default value for this configuration option is the +server's hostname—that is, the first part of +its fully qualified domain name. For example, a system with the DNS +name <tt class="literal">ruby.ora.com</tt> would be given the NetBIOS name +<tt class="literal">RUBY</tt> by default. While you can use this option to +restate the system'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 outlined in <a href="ch01.html">Chapter 1</a>.</p> + +<p>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 +system is not unique because the LAN is divided over two or more DNS +domains. For example, YORKVM1 is a good NetBIOS candidate for +<tt class="literal">vm1.york.example.com</tt> to differentiate it from +<tt class="literal">vm1.falkirk.example.com</tt>, which has the same +hostname but resides in a different DNS domain.</p> + +<p>Another use of this option is for relocating SMB services from a dead +or retired system. For example, if <tt class="literal">SALES</tt> is the +SMB server for the department and it suddenly dies, you could +immediately reset <tt class="literal">netbios</tt> <tt class="literal">name</tt> +<tt class="literal">=</tt> <tt class="literal">SALES</tt> on a backup Samba +server that's taking over for it. Users +won't have to change their drive mappings to a +different server; new connections to <tt class="literal">SALES</tt> will +simply go to the new server.</p> + + +</div> + + + +<div class="sect3"><a name="samba2-CHP-6-SECT-4.1.2"/> + +<h3 class="head3">workgroup</h3> + +<p>The <tt class="literal">workgroup</tt><a name="INDEX-57"/> parameter sets the +current workgroup (or domain) in which the Samba server will +advertise itself. Clients that wish to access shares on the Samba +server should be in the same NetBIOS group. Remember that workgroups +are really just NetBIOS group names and must follow the standard +NetBIOS naming conventions outlined in <a href="ch01.html">Chapter 1</a>.</p> + +<p>The default option for this parameter is set at compile time to +<tt class="literal">WORKGROUP</tt>. Because this is the default workgroup +name of every unconfigured Windows and Samba system, we recommend +that you always set your workgroup name in the Samba configuration +file. When choosing your workgroup name, try to avoid making it the +same name as a server or user. This will avoid possible problems with +WINS name resolution.</p> + + +</div> + + + +<div class="sect3"><a name="samba2-CHP-6-SECT-4.1.3"/> + +<h3 class="head3">server string</h3> + +<p>The <tt class="literal">server</tt><a name="INDEX-58"/> <tt class="literal">string</tt> +parameter defines a comment string that will appear next to the +server name in both the Network Neighborhood (when shown with the +Details view) and the comment entry of the Microsoft Windows printer +manager.<a name="FNPTR-2"/><a href="#FOOTNOTE-2">[2]</a> </p> + +<p>You can use variables to provide +information in the description. For example, our entry earlier was:</p> + +<blockquote><pre class="code">[global] + server string = Samba %v on (%h)</pre></blockquote> + +<p>The default for this option simply presents the current version of +Samba and is equivalent to:</p> + +<a name="INDEX-59"/><blockquote><pre class="code">server string = Samba %v</pre></blockquote> + + +</div> + + +</div> + + +</div> + + + +<div class="sect1"><a name="samba2-CHP-6-SECT-5"/> + +<h2 class="head1">Disk Share Configuration</h2> + +<p><a name="INDEX-60"/><a name="INDEX-61"/>We mentioned in the previous section that +there were no disk shares on the <tt class="literal">toltec</tt> server. +Let's continue building the configuration file and +create an empty disk share called <tt class="literal">[data]</tt>. Here are +the additions that will do it:</p> + +<blockquote><pre class="code">[data] + path = /export/samba/data + comment = Data Drive + volume = Sample-Data-Drive + writable = yes</pre></blockquote> + +<p>The <tt class="literal">[data]</tt> share is typical for a Samba disk +share. The share maps to the directory <em class="filename">/export/samba/data +</em>on the Samba server. We've also provided +a comment that describes the share as a <tt class="literal">Data</tt> +<tt class="literal">Drive</tt>, as well as a volume name for the share +itself.</p> + +<p>Samba's default is to create a read-only share. As a +result, the <tt class="literal">writable</tt> option needs to be explicitly +set for each disk share you wish to make writable.</p> + +<p>We will also need to create the +<em class="filename">/export/samba/data</em> directory on the Samba server +with the following commands:</p> + +<blockquote><pre class="code"># <tt class="userinput"><b>mkdir /export/samba/data</b></tt> +# <tt class="userinput"><b>chmod 777 /export/samba/data</b></tt></pre></blockquote> + +<p>Now, if we connect to the <tt class="literal">toltec</tt> server again by +double-clicking its icon in the Windows Network Neighborhood, we will +see a single share entitled <tt class="literal">data</tt>, as shown in +<a href="ch06.html#samba2-CHP-6-FIG-4">Figure 6-4</a>. This share has read/write access, so +files can be copied to or from it.</p> + +<div class="figure"><a name="samba2-CHP-6-FIG-4"/><img src="figs/sam2_0604.gif"/></div><h4 class="head4">Figure 6-4. The initial data share on the Samba server</h4> + + +<div class="sect2"><a name="samba2-CHP-6-SECT-5.1"/> + +<h3 class="head2">Disk Share Configuration Options</h3> + +<p>The basic Samba configuration options for disk shares previously +introduced are listed in <a href="ch06.html#samba2-CHP-6-TABLE-5">Table 6-5</a>.</p> + +<a name="samba2-CHP-6-TABLE-5"/><h4 class="head4">Table 6-5. Basic share configuration options</h4><table border="1"> + + + + + + +<tr> +<th> +<p>Option</p> +</th> +<th> +<p>Parameters</p> +</th> +<th> +<p>Function</p> +</th> +<th> +<p>Default</p> +</th> +<th> +<p>Scope</p> +</th> +</tr> + + +<tr> +<td> +<p><tt class="literal">path</tt> <tt class="literal">(directory)</tt></p> +</td> +<td> +<p>string (directory name)</p> +</td> +<td> +<p>Sets the Unix directory that will be provided for a disk share or +used for spooling by a printer share.</p> +</td> +<td> +<p><tt class="literal">/tmp</tt></p> +</td> +<td> +<p>Share</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">comment</tt></p> +</td> +<td> +<p>string</p> +</td> +<td> +<p>Sets the comment that appears with the share.</p> +</td> +<td> +<p>None</p> +</td> +<td> +<p>Share</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">volume</tt></p> +</td> +<td> +<p>string</p> +</td> +<td> +<p>Sets the MS-DOS volume name for the share.</p> +</td> +<td> +<p>Share name</p> +</td> +<td> +<p>Share</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">read only</tt></p> +</td> +<td> +<p>boolean</p> +</td> +<td> +<p>If <tt class="literal">yes</tt>, allows read-only access to a share.</p> +</td> +<td> +<p><tt class="literal">yes</tt></p> +</td> +<td> +<p>Share</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">writable</tt> <tt class="literal">(write ok or writeable)</tt></p> +</td> +<td> +<p>boolean</p> +</td> +<td> +<p>If <tt class="literal">no</tt>, allows read-only access to a share. If +<tt class="literal">yes</tt>, both reading and writing are allowed.</p> +</td> +<td> +<p><tt class="literal">no</tt></p> +</td> +<td> +<p>Share</p> +</td> +</tr> + +</table> + + +<div class="sect3"><a name="samba2-CHP-6-SECT-5.1.1"/> + +<h3 class="head3">path</h3> + +<p>This <a name="INDEX-63"/>option, which has the synonym +<tt class="literal">directory</tt>, indicates the pathname for the root of +the shared directory or printer. You can choose any directory 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 ( <em class="filename"> /tmp</em> and +<em class="filename">/var/spool</em> are popular choices). If this path is +for a disk share, the contents of the folder representing the share +name on the client will match the contents of the directory on the +Samba server.</p> + +<p>The directory specified as the value for <tt class="literal">path</tt> can +be given as a relative path, in which case it will be relative to the +directory specified by the <tt class="literal">root</tt> +<tt class="literal">directory</tt> parameter. Because +<tt class="literal">root</tt> <tt class="literal">directory</tt> defaults to root +(<em class="filename">/</em> ), it is generally a good idea to use +absolute paths for the <tt class="literal">path</tt> parameter, unless +<tt class="literal">root</tt> <tt class="literal">directory</tt> has been set to +something other than the default.</p> + + +</div> + + + +<div class="sect3"><a name="samba2-CHP-6-SECT-5.1.2"/> + +<h3 class="head3">comment</h3> + +<p>The <tt class="literal">comment</tt><a name="INDEX-64"/> 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 using the Details view on +the share folder or with the <em class="emphasis">net view</em> command at +an MS-DOS prompt. For example, here is how you might insert a comment +for a share:</p> + +<blockquote><pre class="code">[network] + comment = Network Drive + path = /export/samba/network</pre></blockquote> + +<p>Be sure not to confuse the <tt class="literal">comment</tt> option, which +documents a Samba server's shares, with the +<tt class="literal">server</tt> <tt class="literal">string</tt> option, which +documents the server itself.</p> + + +</div> + + + +<div class="sect3"><a name="samba2-CHP-6-SECT-5.1.3"/> + +<h3 class="head3">volume</h3> + +<p>This <a name="INDEX-65"/>option allows you to specify the volume +name of the share, which would otherwise default to the name of the +share given in the <em class="filename">smb.conf</em> file.</p> + +<p>Some software installation programs check the volume name of the +distribution CD-ROM to make sure the correct CD-ROM is in the drive +before attempting to install from 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 make sure the installation program sees the +correct volume name:</p> + +<blockquote><pre class="code">[network] + comment = Network Drive + volume = ASVP-102-RTYUIKA + path = /home/samba/network</pre></blockquote> + + +</div> + + + +<div class="sect3"><a name="samba2-CHP-6-SECT-5.1.4"/> + +<h3 class="head3">read only, writable</h3> + +<p>The options <tt class="literal">read</tt><a name="INDEX-66"/> <tt class="literal">only</tt> +and <tt class="literal">writable</tt><a name="INDEX-67"/> (also called +<tt class="literal">writeable</tt><a name="INDEX-68"/> or +<tt class="literal">write</tt><a name="INDEX-69"/> <tt class="literal">ok</tt> ) are really two +ways of saying the same thing, but they are approached from opposite +ends. For example, you can set either of the following options in the +<tt class="literal">[global]</tt> section or in an individual share:</p> + +<blockquote><pre class="code">read only = yes +writable = no</pre></blockquote> + +<p>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 <em class="emphasis">default</em> 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:</p> + +<blockquote><pre class="code">read only = no +writable = yes</pre></blockquote> + +<p>If you specify more than one occurrence of either option, Samba will +adhere to the last value it encounters for the share. <a name="INDEX-70"/><a name="INDEX-71"/></p> + + +</div> + + +</div> + + +</div> + + + +<div class="sect1"><a name="samba2-CHP-6-SECT-6"/> + +<h2 class="head1">Networking Options with Samba</h2> + +<p><a name="INDEX-72"/><a name="INDEX-73"/>If +you're running <a name="INDEX-74"/><a name="INDEX-75"/>Samba on a multihomed +system (on multiple subnets), you will need to configure Samba to use +all the network interfaces. Another use for the options presented in +this section is to implement better security by allowing or +disallowing connections on the specified interfaces.</p> + +<p>Let's assume that our Samba server can access both +the subnets 192.168.220.* and 134.213.233.*. Here are our additions +to the configuration file to add the networking configuration +options:</p> + +<blockquote><pre class="code">[global] + # Networking configuration options + hosts allow = 192.168.220. 134.213.233. + hosts deny = 192.168.220.102 + interfaces = 192.168.220.100/255.255.255.0 \ + 134.213.233.110/255.255.255.0 + bind interfaces only = yes</pre></blockquote> + +<p>Take a look at the <tt class="literal">hosts</tt><a name="INDEX-76"/> <tt class="literal">allow</tt> +and <tt class="literal">hosts</tt><a name="INDEX-77"/> <tt class="literal">deny</tt> options. If these +options sound familiar, you're probably thinking of +the <em class="filename">hosts.allow</em> and +<em class="filename">hosts.deny</em> files that are found in the +<em class="filename">/etc</em> 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. We could use the +<em class="filename">hosts.allow</em> and <em class="filename">hosts.deny</em> +files, but we are using this method instead because there might be +services on the server that we want others to access without also +giving them access to Samba's disk or printer +shares.</p> + +<p>With the <tt class="literal">hosts</tt> <tt class="literal">allow</tt> option, +we've specified a 192.168.220 IP address, which is +equivalent to saying: "All hosts on the 192.168.220 +subnet." However, we've explicitly +specified in a <tt class="literal">hosts</tt> <tt class="literal">deny</tt> line +that 192.168.220.102 is not to be allowed access.</p> + +<p>You might be wondering why 192.168.220.102 will be denied even though +it is still in the subnet matched by the <tt class="literal">hosts</tt> +<tt class="literal">allow</tt> option. It is important to understand how +Samba sorts out the rules specified by <tt class="literal">hosts</tt> +<tt class="literal">allow</tt> and <tt class="literal">hosts</tt> <tt class="literal">deny</tt> +:</p> + +<ol><li> +<p>If no <tt class="literal">allow</tt> or <tt class="literal">deny</tt> options are +defined anywhere in <em class="filename">smb.conf</em>, Samba will allow +connections from any system.</p> +</li><li> +<p>If <tt class="literal">hosts</tt> <tt class="literal">allow</tt> or +<tt class="literal">hosts</tt> <tt class="literal">deny</tt> options are defined +in the <tt class="literal">[global]</tt> section of +<em class="filename">smb.conf</em>, they will apply to all shares, even if +either option is defined in one or more of the shares.</p> +</li><li> +<p>If only a <tt class="literal">hosts</tt> <tt class="literal">allow</tt> option is +defined for a share, only the hosts listed will be allowed to use the +share. All others will be denied.</p> +</li><li> +<p>If only a <tt class="literal">hosts</tt> <tt class="literal">deny</tt> option is +defined for a share, any client which is not on the list will be able +to use the share.</p> +</li><li> +<p>If both a <tt class="literal">hosts</tt> <tt class="literal">allow</tt> and +<tt class="literal">hosts</tt> <tt class="literal">deny</tt> option are defined, +a host must appear in the allow list and not appear in the deny list +(in any form) to access the share. Otherwise, the host will not be +allowed.</p> +</li></ol><a name="samba2-CHP-6-NOTE-131"/><blockquote class="note"><h4 class="objtitle">WARNING</h4> +<p>Take care that you don't explicitly allow a host to +access a share, but then deny access to the entire subnet of which +the host is part.</p> +</blockquote> + +<p>Let's look at another example of that final item. +Consider the following options:</p> + +<blockquote><pre class="code">hosts allow = 111.222. +hosts deny = 111.222.333.</pre></blockquote> + +<p>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 +<tt class="literal">hosts</tt> <tt class="literal">allow</tt>. The client must +appear on the <tt class="literal">hosts</tt> <tt class="literal">allow</tt> list +and <em class="emphasis">must not</em> appear on the +<tt class="literal">hosts</tt> <tt class="literal">deny</tt> list to gain access +to a Samba share.</p> + +<p>The other two options that we've specified are +<tt class="literal">interfaces</tt> and <tt class="literal">bind</tt> +<tt class="literal">interface</tt> <tt class="literal">only</tt>. +Let's look at the <tt class="literal">interfaces</tt> +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 +interface, we need to specify the complete list with the +<tt class="literal">interfaces</tt> option. In the previous example, +we've bound Samba to interface with both subnets +(192.168.220 and 134.213.233) on which the system 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.</p> + +<p>Finally, the <tt class="literal">bind</tt> <tt class="literal">interfaces</tt> +<tt class="literal">only</tt> option instructs the +<em class="filename">nmbd</em> process not to accept any broadcast +messages other than on the subnets specified with the +<tt class="literal">interfaces</tt> option. This is different from the +<tt class="literal">hosts</tt> <tt class="literal">allow</tt> and +<tt class="literal">hosts</tt> <tt class="literal">deny</tt> options, which +prevent clients from making connections to services, but not from +receiving broadcast messages. Using the <tt class="literal">bind</tt> +<tt class="literal">interfaces</tt> <tt class="literal">only</tt> option is a way +to shut out all datagrams from foreign subnets. In addition, it +instructs the <em class="emphasis">smbd</em> process to bind to only the +interface list given by the <em class="emphasis">interfaces</em> option. +This restricts the networks that Samba will serve.</p> + + +<div class="sect2"><a name="samba2-CHP-6-SECT-6.1"/> + +<h3 class="head2">Networking Options</h3> + +<p>The networking options we introduced earlier are summarized in <a href="ch06.html#samba2-CHP-6-TABLE-6">Table 6-6</a>.</p> + +<a name="samba2-CHP-6-TABLE-6"/><h4 class="head4">Table 6-6. Networking configuration options</h4><table border="1"> + + + + + + +<tr> +<th> +<p>Option</p> +</th> +<th> +<p>Parameters</p> +</th> +<th> +<p>Function</p> +</th> +<th> +<p>Default</p> +</th> +<th> +<p>Scope</p> +</th> +</tr> + + +<tr> +<td> +<p><tt class="literal">hosts allow (allow</tt> <tt class="literal">hosts)</tt></p> +</td> +<td> +<p>string (list of hostnames)</p> +</td> +<td> +<p>Client systems that can connect to Samba.</p> +</td> +<td> +<p>None</p> +</td> +<td> +<p>Share</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">hosts deny (deny</tt> <tt class="literal">hosts)</tt></p> +</td> +<td> +<p>string (list of hostnames)</p> +</td> +<td> +<p>Client systems that cannot connect to Samba.</p> +</td> +<td> +<p>None</p> +</td> +<td> +<p>Share</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">interfaces</tt></p> +</td> +<td> +<p>string (list of IP/netmask combinations)</p> +</td> +<td> +<p>Network interfaces Samba will respond to. Allows correcting defaults.</p> +</td> +<td> +<p>System-dependent</p> +</td> +<td> +<p>Global</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">bind</tt></p> + +<p><tt class="literal">interfaces only</tt></p> +</td> +<td> +<p>boolean</p> +</td> +<td> +<p>If set to <tt class="literal">yes</tt>, Samba will bind only to those +interfaces specified by the <tt class="literal">interfaces</tt> option.</p> +</td> +<td> +<p><tt class="literal">no</tt></p> +</td> +<td> +<p>Global</p> +</td> +</tr> + +</table> + + +<div class="sect3"><a name="samba2-CHP-6-SECT-6.1.1"/> + +<h3 class="head3">hosts allow</h3> + +<p>The <tt class="literal">hosts</tt> <tt class="literal">allow</tt> option +(sometimes written as <tt class="literal">allow</tt> +<tt class="literal">hosts</tt>) specifies the clients that have permission +to access shares on the Samba server, written as a comma- or +space-separated list of hostnames of systems or their IP addresses. +You can gain quite a bit of security by simply placing your +LAN's subnet address in this option.</p> + +<p>You can specify any of the following formats for this option:</p> + +<ul><li> +<p>Hostnames, such as <tt class="literal">ftp.example.com</tt> .</p> +</li><li> +<p>IP addresses, such as <tt class="literal">130.63.9.252</tt>.</p> +</li><li> +<p>Domain names, which can be differentiated from individual hostnames +because they start with a dot. For example, +<tt class="literal">.ora.com</tt> represents all systems within the +<em class="emphasis">ora.com</em> domain.</p> +</li><li> +<p>Netgroups, which start with an at sign (<tt class="literal">@</tt>), such +as <tt class="literal">@printerhosts</tt>. Netgroups are usually available +only on systems running NIS or NIS+. If netgroups are supported on +your system, there should be a <tt class="literal">netgroups</tt> manual +page that describes them in more detail.</p> +</li><li> +<p>Subnets, which end with a dot. For example, +<tt class="literal">130.63.9</tt>. means all the systems whose IP addresses +begin with 130.63.9.</p> +</li><li> +<p>The keyword <tt class="literal">ALL</tt>, which allows any client access.</p> +</li><li> +<p>The keyword <tt class="literal">EXCEPT</tt> followed by 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 <tt class="literal">hosts</tt> +<tt class="literal">allow</tt> <tt class="literal">=</tt> <tt class="literal">ALL</tt> +<tt class="literal">EXCEPT</tt> <tt class="literal">192.168.110</tt>. (remember +to include the trailing dot).</p> +</li></ul> +<p>Using the <tt class="literal">ALL</tt> keyword by itself is almost always a +bad idea because it means that crackers on any network can access +your Samba server.</p> + +<p>The hostname <tt class="literal">localhost</tt>, for the loopback address +127.0.0.1, is included in the <tt class="literal">hosts</tt> +<tt class="literal">allow</tt> list by default and does not need to be +listed explicitly unless you have specified the +<tt class="literal">bind</tt> <tt class="literal">interfaces</tt> +<tt class="literal">only</tt> parameter. This address is required for Samba +to work properly.</p> + +<p>Other than that, there is no default value for the +<tt class="literal">hosts</tt> <tt class="literal">allow</tt> configuration +option. The default course of action in the event that neither the +<tt class="literal">hosts</tt> <tt class="literal">allow</tt> or +<tt class="literal">hosts</tt> <tt class="literal">deny</tt> option is specified +in <em class="filename">smb.conf</em> is to allow access from all sources.</p> + +<a name="samba2-CHP-6-NOTE-132"/><blockquote class="note"><h4 class="objtitle">TIP</h4> +<p>If you specify <tt class="literal">hosts allow</tt> in the +<tt class="literal">[global]</tt> section, that definition will override +any <tt class="literal">hosts allow</tt> lines in the share definitions. +This is the opposite of the usual behavior, which is for parameters +set in share definitions to override default values set in the +<tt class="literal">[global]</tt> section.<a name="INDEX-78"/></p> +</blockquote> + + +</div> + + + +<div class="sect3"><a name="samba2-CHP-6-SECT-6.1.2"/> + +<h3 class="head3">hosts deny</h3> + +<p>The <tt class="literal">hosts</tt> <tt class="literal">deny</tt> option +(synonymous with <tt class="literal">deny</tt> <tt class="literal">hosts</tt>) +specifies client systems that do not have permission to access a +share, written as a comma- or space-separated list of hostnames or +their IP addresses. Use the same format for specifying clients as the +<tt class="literal">hosts</tt> <tt class="literal">allow</tt> option earlier. For +example, to restrict access to the server from everywhere but +<tt class="literal">example.com</tt>, you could write:</p> + +<blockquote><pre class="code">hosts deny = ALL EXCEPT .example.com</pre></blockquote> + +<p>There is no default value for the <tt class="literal">hosts</tt> +<tt class="literal">deny</tt> 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 <tt class="literal">[global]</tt> section of the configuration file, it +will override any <tt class="literal">hosts</tt> <tt class="literal">deny</tt> +options defined in shares. If you wish to deny access to specific +shares, omit both the <tt class="literal">hosts</tt> +<tt class="literal">allow</tt> and <tt class="literal">hosts</tt> +<tt class="literal">deny</tt> options from the <tt class="literal">[global]</tt> +section of the configuration file.</p> + +<a name="samba2-CHP-6-NOTE-133"/><blockquote class="note"><h4 class="objtitle">NOTE</h4> +<p>Never include the loopback address (<tt class="literal">localhost</tt> at +IP address 127.0.0.1) in the <tt class="literal">hosts deny</tt> list. The +<em class="filename">smbpasswd</em> program needs to connect through the +loopback address to the Samba server as a client to change a +user's encrypted password. If the loopback address +is disabled, the locally generated packets requesting the change of +the encrypted password will be discarded by Samba.</p> + + +<p>In addition, both local browsing propagation and some functions of +SWAT require access to the Samba server through the loopback address +and will not work correctly if this address is disabled. +<a name="INDEX-79"/></p> +</blockquote> + + +</div> + + + +<div class="sect3"><a name="samba2-CHP-6-SECT-6.1.3"/> + +<h3 class="head3">interfaces</h3> + +<p>The <tt class="literal">interfaces</tt><a name="INDEX-80"/> option specifies the +networks that you want the Samba server to recognize and respond to. +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.</p> + +<p>The value of this option is one or more sets of IP address/netmask +pairs, as in the following:</p> + +<blockquote><pre class="code">interfaces = 192.168.220.100/255.255.255.0 192.168.210.30/255.255.255.0</pre></blockquote> + +<p>You can optionally specify a +<a name="INDEX-81"/><a name="INDEX-82"/>CIDR format bitmask, like this:</p> + +<blockquote><pre class="code">interfaces = 192.168.220.100/24 192.168.210.30/24</pre></blockquote> + +<p>The number after the slash specifies the number of bits that will be +set in the netmask. For example, the number 24 means that the first +24 (of 32) bits will be set in the bitmask, which is the same as +specifying 255.255.255.0 as the netmask. Likewise, 16 would be +equivalent to a netmask of 255.255.0.0, and 8 would be the same as a +netmask of 255.0.0.0.</p> +<a name="samba2-CHP-6-NOTE-135"/><blockquote class="note"><h4 class="objtitle">WARNING</h4> +<p>This option might not work correctly if you are using DHCP.</p> +</blockquote> + + +</div> + + + +<div class="sect3"><a name="samba2-CHP-6-SECT-6.1.4"/> + +<h3 class="head3">bind interfaces only</h3> + +<p>The <tt class="literal">bind</tt><a name="INDEX-83"/> +<tt class="literal">interfaces</tt> <tt class="literal">only</tt> option can be +used to force the <em class="emphasis">smbd</em> and +<em class="emphasis">nmbd</em> processes to respond only to those +addresses specified by the <tt class="literal">interfaces</tt> option. The +<em class="emphasis">nmbd</em> 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:</p> + +<blockquote><pre class="code">bind interfaces only = yes</pre></blockquote> + +<p>This will cause Samba to ignore any packets (including broadcast +packets) whose source address does not correspond to any of the +network interfaces specified by the <tt class="literal">interfaces</tt> +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 be used only by experts.</p> + +<a name="samba2-CHP-6-NOTE-136"/><blockquote class="note"><h4 class="objtitle">TIP</h4> +<p>If you set <tt class="literal">bind interfaces only</tt> to <tt class="literal">yes</tt> +, add the <a name="INDEX-84"/><a name="INDEX-85"/><a name="INDEX-86"/>local host +address (127.0.01) to the +"interfaces" list. Otherwise, +<em class="emphasis">smbpasswd</em> will be unable to connect to the +server using its default mode in order to change a password, local +browse list propagation will fail, and some functions of swat will +not work properly. <a name="INDEX-87"/><a name="INDEX-88"/></p> +</blockquote> + + +</div> + + +</div> + + +</div> + + + +<div class="sect1"><a name="samba2-CHP-6-SECT-7"/> + +<h2 class="head1">Virtual Servers</h2> + +<p><a name="INDEX-89"/>Virtual +servers can be used to create the illusion of having multiple servers +on the network, when in reality there is only one. The technique is +simple to implement: a system simply registers more than one NetBIOS +name in association with its IP address. There are tangible benefits +to doing this.</p> + +<p>For example, the accounting department might have an +<tt class="literal">accounting</tt> server, and clients of it would see +just the accounting disks and printers. The marketing department +could have its own server, <tt class="literal">marketing</tt>, with its own +reports, and so on. However, all the services would be provided by +one medium-size Unix server (and one relaxed administrator) instead +of having one small server per department.</p> + + +<div class="sect2"><a name="samba2-CHP-6-SECT-7.1"/> + +<h3 class="head2">Virtual Server Configuration Options</h3> + +<p><a name="INDEX-90"/><a name="INDEX-91"/>Samba will allow a server to use more +than one NetBIOS name with the <tt class="literal">netbios</tt> +<tt class="literal">aliases</tt> option. See <a href="ch06.html#samba2-CHP-6-TABLE-7">Table 6-7</a>.</p> + +<a name="samba2-CHP-6-TABLE-7"/><h4 class="head4">Table 6-7. Virtual server configuration options</h4><table border="1"> + + + + + + +<tr> +<th> +<p>Option</p> +</th> +<th> +<p>Parameters</p> +</th> +<th> +<p>Function</p> +</th> +<th> +<p>Default</p> +</th> +<th> +<p>Scope</p> +</th> +</tr> + + +<tr> +<td> +<p><tt class="literal">netbios</tt> <tt class="literal">aliases</tt></p> +</td> +<td> +<p>string (list of NetBIOS names)</p> +</td> +<td> +<p>Additional NetBIOS names to respond to, for use with multiple +"virtual" Samba servers</p> +</td> +<td> +<p>None</p> +</td> +<td> +<p>Global</p> +</td> +</tr> + +</table> + + +<div class="sect3"><a name="samba2-CHP-6-SECT-7.1.1"/> + +<h3 class="head3">netbios aliases</h3> + +<p>The <tt class="literal">netbios</tt><a name="INDEX-92"/> +<tt class="literal">aliases</tt> option can be used to give the Samba +server more than one NetBIOS name. Each NetBIOS name listed as a +value will be displayed in the Network Neighborhood of Windows +clients. When a connection is requested to any of the servers, it +will connect to the same Samba server.</p> + +<p>This might come in handy, for example, if you're +transferring three departments' data to a single +Unix server with larger and faster disks and are retiring or +reallocating the old Windows NT/2000 servers. If the three servers +are called <tt class="literal">sales</tt>, <tt class="literal">accounting</tt>, +and <tt class="literal">admin</tt>, you can have Samba represent all three +servers with the following options:</p> + +<blockquote><pre class="code">[global] + netbios aliases = sales accounting admin + include = /usr/local/samba/lib/smb.conf.%L</pre></blockquote> + +<p>See <a href="ch06.html#samba2-CHP-6-FIG-5">Figure 6-5</a> 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 to which +it's trying to connect, which is made available in +the configuration file through the <tt class="literal">%L</tt> variable. If +the requested server is <tt class="literal">sales</tt>, Samba will include +the file <em class="filename">/usr/local/samba/lib/smb.conf.sales</em>. +This file might contain global and share declarations exclusively for +the sales team, such as the following:</p> + +<blockquote><pre class="code">[global] + workgroup = SALES + hosts allow = 192.168.10.255 + +[sales2003] + path = /usr/local/samba/sales/sales2003/ +...</pre></blockquote> + +<p>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.</p> + +<div class="figure"><a name="samba2-CHP-6-FIG-5"/><img src="figs/sam2_0605.gif"/></div><h4 class="head4">Figure 6-5. Using NetBIOS aliases for a Samba server</h4> + + +</div> + + +</div> + + +</div> + + + +<div class="sect1"><a name="samba2-CHP-6-SECT-8"/> + +<h2 class="head1">Logging Configuration Options</h2> + +<p><a name="INDEX-93"/><a name="INDEX-94"/>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.</p> + +<p>Samba <a name="INDEX-95"/>log files +can be as brief or verbose as you like. Here is an example of what a +Samba log file looks like:</p> + +<blockquote><pre class="code">[2002/07/21 13:23:25, 3] smbd/service.c:close_cnum(514) + maya (172.16.1.6) closed connection to service IPC$ +[2002/07/21 13:23:25, 3] smbd/connection.c:yield_connection(40) + Yielding connection to IPC$ +[2002/07/21 13:23:25, 3] smbd/process.c:process_smb(615) + Transaction 923 of length 49 +[2002/07/21 13:23:25, 3] smbd/process.c:switch_message(448) + switch message SMBread (pid 467) +[2002/07/21 13:23:25, 3] lib/doscalls.c:dos_ChDir(336) + dos_ChDir to /home/samba +[2002/07/21 13:23:25, 3] smbd/reply.c:reply_read(2199) + read fnum=4207 num=2820 nread=2820 +[2002/07/21 13:23:25, 3] smbd/process.c:process_smb(615) + Transaction 924 of length 55 +[2002/07/21 13:23:25, 3] smbd/process.c:switch_message(448) + switch message SMBreadbraw (pid 467) +[2002/07/21 13:23:25, 3] smbd/reply.c:reply_readbraw(2053) + readbraw fnum=4207 start=130820 max=1276 min=0 nread=1276 +[2002/07/21 13:23:25, 3] smbd/process.c:process_smb(615) + Transaction 925 of length 55 +[2002/07/21 13:23:25, 3] smbd/process.c:switch_message(448) + switch message SMBreadbraw (pid 467)</pre></blockquote> + +<p>Much of this information is of use only to Samba programmers. +However, we will go over the meaning of some of these entries in more +detail in <a href="ch12.html">Chapter 12</a>.</p> + +<p>Samba contains six options that allow users to describe how and where +logging information should be written. Each of these are global +options and cannot appear inside a share definition. Here is an +example of some logging options that we are adding to our +configuration file:</p> + +<blockquote><pre class="code">[global] + log level = 2 + log file = /var/log/samba.log.%m + max log size = 50 + debug timestamp = yes</pre></blockquote> + +<p>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. Levels 2 or 3 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 working on the Samba source code.</p> + +<p>The logging file is located in the <em class="filename">/var/log</em> +directory thanks to the <tt class="literal">log</tt> +<tt class="literal">file</tt> configuration option. However, we can use +variable substitution to create log files specifically for individual +users or clients, such as with the <tt class="literal">%m</tt> variable in +the following line:</p> + +<blockquote><pre class="code">log file = /usr/local/logs/samba.log.%m</pre></blockquote> + +<p>Isolating the log messages can be invaluable in tracking down a +network error if you know the problem is coming from a specific +client system or user.</p> + +<p>We've added a precaution to the log files: no one +log file can exceed 50 KB in size, as specified by the +<tt class="literal">max</tt> <tt class="literal">log</tt> <tt class="literal">size</tt> +option. If a log file exceeds this size, the contents are moved to a +file with the same name but with the suffix <em class="emphasis">.old</em> +appended. If the <em class="emphasis">.old</em> 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 +the Samba daemons.</p> + +<p>We have decided to write the timestamps of the messages in the logs +with the <tt class="literal">debug</tt> <tt class="literal">timestamp</tt> +option, which is the default behavior. This will place a timestamp in +each message written to the logging file. If we were not interested +in this information, we could specify <tt class="literal">no</tt> for this +option instead.</p> + + +<div class="sect2"><a name="samba2-CHP-6-SECT-8.1"/> + +<h3 class="head2">Using syslog</h3> + +<p>If you wish to use the system logger +(<a name="INDEX-96"/>syslog<em class="filename"> +</em>) in addition to or in place of the standard Samba logging +file, Samba provides options for this as well. However, to use +syslog, the first thing you will have to do is make sure that Samba +was built with the <tt class="literal">configure</tt> +<tt class="literal">--with-syslog</tt> option. See <a href="ch02.html">Chapter 2</a> for more information on configuring and +compiling Samba. See <a href="appe.html">Appendix E</a> for more +information about the <tt class="literal">--with-syslog</tt> option.</p> + +<p>Once that is done, you will need to configure your +<em class="filename">/etc/syslog.conf</em><a name="INDEX-97"/> to accept logging information from Samba. +If there is not already a <tt class="literal">daemon.*</tt> entry in the +<em class="filename">/etc/syslog.conf</em> file, add the following:</p> + +<blockquote><pre class="code">daemon.* /var/log/daemon.log</pre></blockquote> + +<p>This specifies that any logging information from system daemons will +be stored in the <em class="filename">/var/log/daemon.log</em> file. This +is where the Samba information will be stored as well. From there, +you can set a value for the <tt class="literal">syslog</tt> parameter in +your Samba configuration file to specify which logging messages are +to be sent to syslog. Only messages that have debug levels lower than +the value of the <tt class="literal">syslog</tt> parameter will be sent to +syslog. For example, setting the following:</p> + +<blockquote><pre class="code">syslog = 3</pre></blockquote> + +<p>specifies that any logging messages with a level of 2 or below will +be sent to both syslog and the Samba logging files. (The mappings to +<em class="filename">syslog</em> priorities are described in the upcoming +section "syslog.") To continue the +example, let's assume that we have set the +<tt class="literal">log</tt> <tt class="literal">level</tt> option to 4. Logging +messages with levels of 2 and 1 will be sent to both syslog and the +Samba logging files, and messages with a level of 3 or 4 will be sent +to the Samba logging files, but not to syslog. If the +<tt class="literal">syslog</tt> value exceeds the <tt class="literal">log</tt> +<tt class="literal">level</tt> value, nothing will be sent to syslog.</p> + +<p>If you want to specify that messages be sent only to syslog—and +not to the standard Samba logging files—you can place this +option in the configuration file:</p> + +<blockquote><pre class="code">syslog only = yes</pre></blockquote> + +<p>If this is the case, any logging information above the number +specified in the <tt class="literal">syslog</tt> option will be discarded, +as with the <tt class="literal">log</tt> <tt class="literal">level</tt> option.</p> + + +</div> + + +<div class="sect2"><a name="samba2-CHP-6-SECT-8.2"/> + +<h3 class="head2">Logging Configuration Options</h3> + +<p><a href="ch06.html#samba2-CHP-6-TABLE-8">Table 6-8</a> lists each logging configuration option +that Samba can use.</p> + +<a name="samba2-CHP-6-TABLE-8"/><h4 class="head4">Table 6-8. Logging configuration options</h4><table border="1"> + + + + + + +<tr> +<th> +<p>Option</p> +</th> +<th> +<p>Parameters</p> +</th> +<th> +<p>Function</p> +</th> +<th> +<p>Default</p> +</th> +<th> +<p>Scope</p> +</th> +</tr> + + +<tr> +<td> +<p><tt class="literal">log file</tt></p> +</td> +<td> +<p>string (name of file)</p> +</td> +<td> +<p>Name of the log file that Samba is to use. Works with all variables.</p> +</td> +<td> +<p>Specified in Samba makefile</p> +</td> +<td> +<p>Global</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">log level</tt></p> + +<p><tt class="literal">(debug level)</tt></p> +</td> +<td> +<p>numeric (0-10)</p> +</td> +<td> +<p>Amount of log/debug messages that are sent to the log file. 0 is +none; 3 is considerable.</p> +</td> +<td> +<p><tt class="literal">1</tt></p> +</td> +<td> +<p>Global</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">max log size</tt></p> +</td> +<td> +<p>numeric (size in KB)</p> +</td> +<td> +<p>Maximum size of log file.</p> +</td> +<td> +<p><tt class="literal">5000</tt></p> +</td> +<td> +<p>Global</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">debug timestamp</tt> <tt class="literal">(timestamp logs)</tt></p> +</td> +<td> +<p>boolean</p> +</td> +<td> +<p>If <tt class="literal">no</tt>, doesn't timestamp logs, +making them easier to read during heavy debugging.</p> +</td> +<td> +<p><tt class="literal">yes</tt></p> +</td> +<td> +<p>Global</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">syslog</tt></p> +</td> +<td> +<p>numeric (0-10)</p> +</td> +<td> +<p>Level of messages sent to <em class="emphasis">syslog</em>. Those levels +below <tt class="literal">syslog</tt> <tt class="literal">level</tt> will be sent +to the system logger.</p> +</td> +<td> +<p><tt class="literal">1</tt></p> +</td> +<td> +<p>Global</p> +</td> +</tr> +<tr> +<td> +<p><tt class="literal">syslog only</tt></p> +</td> +<td> +<p>boolean</p> +</td> +<td> +<p>If <tt class="literal">yes</tt>, uses <em class="emphasis">syslog</em> entirely +and sends no output to the Samba log files.</p> +</td> +<td> +<p><tt class="literal">no</tt></p> +</td> +<td> +<p>Global</p> +</td> +</tr> + +</table> + + +<div class="sect3"><a name="samba2-CHP-6-SECT-8.2.1"/> + +<h3 class="head3">log file</h3> + +<p>By default, Samba writes log information to text files in the +<em class="filename">/usr/local/samba/var</em> directory. The +<tt class="literal">log</tt><a name="INDEX-98"/> <tt class="literal">file</tt> option can be +used to set the name of the log file to another location. For +example, to put the Samba log information in +<em class="filename">/usr/local/logs/samba.log</em>, you could use the +following:</p> + +<blockquote><pre class="code">[global] + log file = /usr/local/logs/samba.log</pre></blockquote> + +<p>You can use variable substitution to create log files specifically +for individual users or clients.</p> + +<p>You can override the default log file location using the +<em class="emphasis">-l</em> command-line switch when either daemon is +started. However, this does not override the <tt class="literal">log</tt> +<tt class="literal">file</tt> option. If you do specify this parameter, +initial logging information will be sent to the file specified after +<em class="emphasis">-l</em> (or the default specified in the Samba +makefile) until the daemons have processed the +<em class="filename">smb.conf</em> file and know to redirect it to a new +log file.</p> + + +</div> + + + +<div class="sect3"><a name="samba2-CHP-6-SECT-8.2.2"/> + +<h3 class="head3">log level</h3> + +<p>The <tt class="literal">log</tt><a name="INDEX-99"/> <tt class="literal">level</tt> option +sets the amount of data to be logged. Normally this is set to 0 or 1. +However, if you have a specific problem, you might 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 it slows down the server considerably. +Therefore, we recommend that for normal day-to-day operation, you +avoid setting this option to anything above 3.</p> + + +</div> + + + +<div class="sect3"><a name="samba2-CHP-6-SECT-8.2.3"/> + +<h3 class="head3">max log size</h3> + +<p>The <tt class="literal">max</tt><a name="INDEX-100"/> <tt class="literal">log</tt> +<tt class="literal">size</tt> 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 a +<em class="filename">.old</em> extension (erasing any previous file with +that name) and a new debugging log file is started with the original +name. For example:</p> + +<blockquote><pre class="code">[global] + log file = /usr/local/logs/samba.log.%m + max log size = 1000</pre></blockquote> + +<p>Here, if the size of any log file exceeds 1MB, Samba renames the log +file <em class="emphasis">samba.log</em>. +<em class="replaceable">machine-name</em><em class="emphasis">.old</em>, +and a new log file is generated. If there is already a file with the +<em class="emphasis">.old</em> extension, Samba deletes it. We highly +recommend setting this option in your configuration files because +debug logging (even at lower levels) can quietly eat away at your +available disk space. Using this option protects unwary +administrators from suddenly discovering that most of the space on a +disk or partition has been swallowed up by a single Samba log file.</p> + + +</div> + + + +<div class="sect3"><a name="samba2-CHP-6-SECT-8.2.4"/> + +<h3 class="head3">debug timestamp or timestamp logs</h3> + +<p>If you happen to be debugging a network problem and you find that the +timestamp information within the Samba log lines gets in the way, you +can turn it off by giving either the +<tt class="literal">timestamp</tt><a name="INDEX-101"/> <tt class="literal">logs</tt> or the +synonymous <tt class="literal">debug</tt><a name="INDEX-102"/> +<tt class="literal">timestamp</tt> option a value of <tt class="literal">no</tt>. +For example, a regular Samba log file presents its output in the +following form:</p> + +<blockquote><pre class="code">12/31/01 12:03:34 toltec (172.16.1.1) connect to server network as user jay</pre></blockquote> + +<p>With a <tt class="literal">no</tt> value for this option, the output would +appear without the timestamp:</p> + +<blockquote><pre class="code">toltec (172.16.1.1) connect to server network as user jay</pre></blockquote> + + +</div> + + + +<div class="sect3"><a name="samba2-CHP-6-SECT-8.2.5"/> + +<h3 class="head3">syslog</h3> + +<p>The <tt class="literal">syslog</tt><a name="INDEX-103"/> option causes Samba log +messages to be sent to the Unix system logger. The type of log +information to be sent is specified as a numeric value. Like the +<tt class="literal">log</tt> <tt class="literal">level</tt> 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. Debug logs +greater than or equal to the <tt class="literal">syslog</tt> level, but +less than log level, will still be sent to the standard Samba log +files. For example:</p> + +<blockquote><pre class="code">[global] + log level = 3 + syslog = 1</pre></blockquote> + +<p>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. All messages sent to the system +logger are mapped to a priority level that the syslogd daemon +understands, as shown in <a href="ch06.html#samba2-CHP-6-TABLE-9">Table 6-9</a>. The default +level is 1.</p> + +<a name="samba2-CHP-6-TABLE-9"/><h4 class="head4">Table 6-9. syslog priority conversion</h4><table border="1"> + + + +<tr> +<th> +<p>Log level</p> +</th> +<th> +<p>syslog priority</p> +</th> +</tr> + + +<tr> +<td> +<p>0</p> +</td> +<td> +<p><tt class="literal">LOG_ERR</tt></p> +</td> +</tr> +<tr> +<td> +<p>1</p> +</td> +<td> +<p><tt class="literal">LOG_WARNING</tt></p> +</td> +</tr> +<tr> +<td> +<p>2</p> +</td> +<td> +<p><tt class="literal">LOG_NOTICE</tt></p> +</td> +</tr> +<tr> +<td> +<p>3</p> +</td> +<td> +<p><tt class="literal">LOG_INFO</tt></p> +</td> +</tr> +<tr> +<td> +<p>4 and above</p> +</td> +<td> +<p><tt class="literal">LOG_DEBUG</tt></p> +</td> +</tr> + +</table> + +<p>If you wish to use <em class="emphasis">syslog</em>, you will have to run +<tt class="literal">configure</tt> <tt class="literal">--with-syslog</tt> when +compiling Samba, and you will need to configure your +<em class="filename">/etc/syslog.conf</em> to suit. (See <a href="ch06.html#samba2-CHP-6-SECT-8.1">Section 6.8.1</a>, earlier in this chapter.)</p> + + +</div> + + + +<div class="sect3"><a name="samba2-CHP-6-SECT-8.2.6"/> + +<h3 class="head3">syslog only</h3> + +<p>The <tt class="literal">syslog</tt><a name="INDEX-104"/> <tt class="literal">only</tt> option +tells Samba not to use its own logging files at all and to use only +the system logger. To enable this, specify the following option in +the global section of the Samba configuration file:</p> + +<a name="INDEX-105"/><a name="INDEX-106"/><a name="INDEX-107"/><blockquote><pre class="code">[global] + syslog only = yes</pre></blockquote> + + +</div> + + +</div> + + +</div> + +<hr/><h4 class="head4">Footnotes</h4><blockquote><a name="FOOTNOTE-1"/> <p><a href="#FNPTR-1">[1]</a> Depending on your system, this file might not +be <em class="emphasis">/etc/printcap</em>. You can use the +<em class="emphasis">testparm</em> command that comes with Samba to dump +the parameter definitions and determine the value of the +<tt class="literal">printcap</tt> <tt class="literal">name</tt> configuration +option. The value assigned to it is the default value chosen when +Samba was configured and compiled, which should be correct.</p> +<a name="FOOTNOTE-2"/> <p><a href="#FNPTR-2">[2]</a> We are referring here to the window that +opens when a printer icon in the Printers control panel is +double-clicked.</p> </blockquote><hr/><h4 class="head4"><a href="toc.html">TOC</a></h4></body></html> |