s3: Lift the server_messaging_context from notify_job_status

[Samba/gbeck.git] / docs-xml / using_samba / ch04.xml

<chapter label="4" id="ch04-21486">
<title>Disk Shares </title>




<para>
<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>


<para>Samba's <indexterm id="ch04-idx-967124-0"><primary>daemons</primary></indexterm>daemons, <emphasis>smbd</emphasis>
<indexterm id="ch04-idx-967122-0"><primary>smbd daemon</primary></indexterm> and <emphasis>nmbd</emphasis>
<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>


<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>











<sect1 role="" label="4.1" id="ch04-76968">
<title>Learning the Samba Configuration File</title>


<para><filename></filename>
<indexterm id="ch04-idx-968372-0" class="startofrange"><primary>smb.conf (Samba configuration) file</primary></indexterm>Here is an <filename></filename>
<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>


<programlisting>[global]
        log level = 1
        max log size = 1000
        socket options = TCP_NODELAY IPTOS_LOWDELAY
        guest ok = no
[homes]
        browseable = no
        map archive = yes
[printers]
        path = /usr/tmp
        guest ok = yes
        printable = yes
[test]
        browseable = yes
        read only = yes
        guest ok = yes
        path = /export/samba/test</programlisting>


<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>


<sect2 role="" label="4.1.1" id="ch04-52415">
<title>Configuration File Structure</title>


<para><filename></filename>
<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>


<programlisting>[global]
        ...
[homes]
        ...
[printers]
        ...
[test]
        ...</programlisting>


<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>
<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>


<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>
<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>


<programlisting><replaceable>option</replaceable> = <replaceable>value</replaceable></programlisting>


<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>


<sect3 role="" label="4.1.1.1" id="ch04-SECT-1.1.1">
<title>Whitespaces, quotes, and commas</title>


<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>


<programlisting>volume = The Big Bad Hard Drive Number 3543</programlisting>


<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>


<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>


<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>


<programlisting>netbios aliases = sales, accounting, payroll
netbios aliases = sales accounting payroll</programlisting>


<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>
</sect3>



<sect3 role="" label="4.1.1.2" id="ch04-SECT-1.1.2">
<title>Capitalization</title>


<para>
<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>


<programlisting>PATH = /EXPORT/SAMBA/SIMPLE</programlisting>


<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>
</sect3>



<sect3 role="" label="4.1.1.3" id="ch04-SECT-1.1.3">
<title>Line continuation</title>


<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>
<indexterm id="ch04-idx-967115-1"><primary>backslash (\) in smb.conf file</primary></indexterm>backslash, as follows:</para>


<programlisting>comment = The first share that has the primary copies \
          of the new Teamworks software product.</programlisting>


<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>
</sect3>



<sect3 role="" label="4.1.1.4" id="ch04-SECT-1.1.4">
<title>Comments</title>


<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>
<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>
<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>


<programlisting>#  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</programlisting>


<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>
<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>
</sect3>



<sect3 role="" label="4.1.1.5" id="ch04-SECT-1.1.5">
<title>Changes at runtime</title>


<para>
<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>


<para>For example, if the <emphasis>smbd</emphasis> <indexterm id="ch04-idx-967128-0"><primary>processes</primary><see>daemons</see></indexterm>
<indexterm id="ch04-idx-967128-1"><primary>daemons</primary><seealso>smbd daemon; nmbd daemon</seealso></indexterm>
<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>


<programlisting># <emphasis role="bold">kill -SIGHUP 893</emphasis></programlisting>


<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>
<indexterm id="ch04-idx-967061-0" class="endofrange" startref="ch04-idx-967054-0"/></para>
</sect3>
</sect2>





<sect2 role="" label="4.1.2" id="ch04-87365">
<title>Variables</title>


<para><filename></filename>
<indexterm id="ch04-idx-967393-0" class="startofrange"><primary>smb.conf (Samba configuration) file</primary><secondary>variables for</secondary></indexterm>
<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>
<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>


<programlisting>[pub]
    path = /home/ftp/pub/%a</programlisting>


<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>


<programlisting>/home/ftp/pub/WinNT
/home/ftp/pub/Win95
/home/ftp/pub/WfWg</programlisting>


<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>


<table label="4.1" id="ch04-10883">
<title>Samba Variables </title>

<tgroup cols="2">
<colspec colnum="1" colname="col1"/>
<colspec colnum="2" colname="col2"/>
<thead>
<row>

<entry colname="col1"><para>Variable</para></entry>

<entry colname="col2"><para>Definition</para></entry>

</row>

</thead>

<tbody>
<row>

<entry namest="col1" nameend="col2"><para><emphasis role="bold">
<indexterm id="ch04-idx-968086-0"><primary>client variables</primary></indexterm>Client variables</emphasis></para></entry>

</row>

<row>

<entry colname="col1"><para><literal>%a</literal></para></entry>

<entry colname="col2"><para><filename></filename>
<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>

</row>

<row>

<entry colname="col1"><para><literal>%I</literal></para></entry>

<entry colname="col2"><para>Client's IP address (e.g., 192.168.220.100)</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>%m</literal></para></entry>

<entry colname="col2"><para>Client's NetBIOS name</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>%M</literal></para></entry>

<entry colname="col2"><para>Client's DNS name</para></entry>

</row>

<row>

<entry namest="col1" nameend="col2"><para><emphasis role="bold">
<indexterm id="ch04-idx-968108-0"><primary>user variables</primary></indexterm>User variables</emphasis></para></entry>

</row>

<row>

<entry colname="col1"><para><literal>%g</literal></para></entry>

<entry colname="col2"><para>Primary group of <literal>%u</literal></para></entry>

</row>

<row>

<entry colname="col1"><para><literal>%G</literal></para></entry>

<entry colname="col2"><para>Primary group of <literal>%U</literal></para></entry>

</row>

<row>

<entry colname="col1"><para><literal>%H</literal></para></entry>

<entry colname="col2"><para>Home directory of <literal>%u</literal></para></entry>

</row>

<row>

<entry colname="col1"><para><literal>%u</literal></para></entry>

<entry colname="col2"><para>Current Unix username</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>%U</literal></para></entry>

<entry colname="col2"><para>Requested client username (not always used by Samba)</para></entry>

</row>

<row>

<entry namest="col1" nameend="col2"><para><emphasis role="bold">Share variables</emphasis></para></entry>

</row>

<row>

<entry colname="col1"><para><literal>%p</literal></para></entry>

<entry colname="col2"><para>Automounter's path to the share's root directory, if different from <literal>%P</literal></para></entry>

</row>

<row>

<entry colname="col1"><para><literal>%P</literal></para></entry>

<entry colname="col2"><para>Current share's root directory</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>%S</literal></para></entry>

<entry colname="col2"><para>Current share's name</para></entry>

</row>

<row>

<entry namest="col1" nameend="col2"><para><emphasis role="bold">Server variables</emphasis></para></entry>

</row>

<row>

<entry colname="col1"><para><literal>%d</literal></para></entry>

<entry colname="col2"><para>Current server process ID</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>%h</literal></para></entry>

<entry colname="col2"><para>Samba server's DNS hostname</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>%L</literal></para></entry>

<entry colname="col2"><para>Samba server's NetBIOS name</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>%N</literal></para></entry>

<entry colname="col2"><para>Home directory server, from the automount map</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>%v</literal></para></entry>

<entry colname="col2"><para>Samba version</para></entry>

</row>

<row>

<entry namest="col1" nameend="col2"><para><emphasis role="bold">Miscellaneous variables</emphasis></para></entry>

</row>

<row>

<entry colname="col1"><para><literal>%R</literal></para></entry>

<entry colname="col2"><para>The SMB protocol level that was negotiated</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>%T</literal></para></entry>

<entry colname="col2"><para>The current date and time</para></entry>

</row>

</tbody>
</tgroup>
</table>


<para>
<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>


<programlisting>[homes]
        ...
        include = /usr/local/samba/lib/smb.conf.%m
        ...</programlisting>


<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>


<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>


<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>


<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>
<indexterm id="ch04-idx-967084-0" class="endofrange" startref="ch04-idx-967393-0"/>
<indexterm id="ch04-idx-967084-1" class="endofrange" startref="ch04-idx-967393-1"/></para>
</sect2>
</sect1>









<sect1 role="" label="4.2" id="ch04-81402">
<title>Special Sections</title>


<para><filename></filename>
<indexterm id="ch04-idx-967091-0" class="startofrange"><primary>smb.conf (Samba configuration) file</primary><secondary>special sections of</secondary></indexterm>
<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>


<sect2 role="" label="4.2.1" id="ch04-SECT-2.1">
<title>The [globals] Section</title>


<para>The <literal>[globals]</literal>
<indexterm id="ch04-idx-967171-0"><primary sortas="globals section">[globals] section</primary></indexterm>
<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>


<para>To illustrate this, let's again look at the opening example of the chapter:</para>


<programlisting>[global]
        log level = 1
        max log size = 1000
        socket options = TCP_NODELAY IPTOS_LOWDELAY
        guest ok = no
[homes]
        browseable = no
        map archive = yes
[printers]
        path = /usr/tmp
        guest ok = yes
        printable = yes
        min print space = 2000
[test]
        browseable = yes
        read only = yes
        guest ok = yes
        path = /export/samba/test</programlisting>


<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>


<para>Any option that appears outside of a section (before the first marked section) is also assumed to be a global option.</para>
</sect2>





<sect2 role="" label="4.2.2" id="ch04-SECT-2.2">
<title>The [ homes] Section</title>


<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>
<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>


<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>


<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>
</sect2>





<sect2 role="" label="4.2.3" id="ch04-SECT-2.3">
<title>The [printers] Section</title>


<para>The third special section is called <literal>[printers]</literal>
<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">


<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>


</footnote> If it does, Samba creates a share named after the printer.</para>


<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>


<para>The process of setting up the <literal>[printers]</literal>
<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>
<indexterm id="ch04-idx-968225-0"><primary>configuration files</primary><secondary>smb.conf (Samba configuration) file</secondary><see>smb.conf file</see></indexterm></para>
</sect2>





<sect2 role="" label="4.2.4" id="ch04-SECT-2.4">
<title>Configuration Options</title>


<para><filename></filename>
<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>


<variablelist>
<varlistentry><term>Global</term>
<listitem><para>
<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>
</varlistentry>


<varlistentry><term>Share</term>
<listitem><para>
<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>
</varlistentry>
</variablelist>


<para>In addition, the values that a configuration option can take can be divided into four categories. They are as follows:</para>


<variablelist>
<varlistentry><term>Boolean</term>
<listitem><para>
<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>
</varlistentry>


<varlistentry><term>Numerical</term>
<listitem><para>
<indexterm id="ch04-idx-967220-0"><primary>numerical type</primary></indexterm>An integer, hexidecimal, 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>
</varlistentry>


<varlistentry><term>String</term>
<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>
</varlistentry>


<varlistentry><term>Enumerated list</term>
<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>
<indexterm id="ch04-idx-967166-0" class="endofrange" startref="ch04-idx-967091-0"/>
<indexterm id="ch04-idx-967166-1" class="endofrange" startref="ch04-idx-967091-1"/></para></listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>









<sect1 role="" label="4.3" id="ch04-46076">
<title>Configuration File Options</title>


<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>


<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>


<table label="4.2" id="ch04-94939">
<title>Configuration File Options </title>

<tgroup cols="5">
<colspec colnum="1" colname="col1"/>
<colspec colnum="2" colname="col2"/>
<colspec colnum="3" colname="col3"/>
<colspec colnum="4" colname="col4"/>
<colspec colnum="5" colname="col5"/>
<thead>
<row>

<entry colname="col1"><para>Option</para></entry>

<entry colname="col2"><para>Parameters</para></entry>

<entry colname="col3"><para>Function</para></entry>

<entry colname="col4"><para>Default</para></entry>

<entry colname="col5"><para>Scope</para></entry>

</row>

</thead>

<tbody>
<row>

<entry colname="col1"><para><literal>config file</literal></para></entry>

<entry colname="col2"><para>string (fully-qualified name)</para></entry>

<entry colname="col3"><para>Sets the location of a configuration file to use instead of the current one.</para></entry>

<entry colname="col4"><para>None</para></entry>

<entry colname="col5"><para>Global</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>include</literal></para></entry>

<entry colname="col2"><para>string (fully-qualified name)</para></entry>

<entry colname="col3"><para>Specifies an additional segment of configuration options to be included at this point in the configuration file.</para></entry>

<entry colname="col4"><para>None</para></entry>

<entry colname="col5"><para>Global</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>copy</literal></para></entry>

<entry colname="col2"><para>string (name of share)</para></entry>

<entry colname="col3"><para>Allows you to clone the configuration options of another share in the current share.</para></entry>

<entry colname="col4"><para>None</para></entry>

<entry colname="col5"><para>Share</para></entry>

</row>

</tbody>
</tgroup>
</table>


<sect2 role="" label="4.3.1" id="ch04-SECT-3.0.1">
<indexterm id="ch04-idx-968272-0"><primary>config file option</primary></indexterm>
<title>
config file</title>


<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>


<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>


<programlisting>[global]
        config file = /usr/local/samba/lib/smb.conf.%m</programlisting>


<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>
</sect2>





<sect2 role="" label="4.3.2" id="ch04-SECT-3.0.2">
<indexterm id="ch04-idx-968282-0"><primary>include option</primary></indexterm>
<title>
include</title>


<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>


<programlisting>[global]
        include = /usr/local/samba/lib/smb.conf.%m</programlisting>


<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>


<figure label="4.1" id="ch04-97340">
<title>The include option in a Samba configuration file</title>

<graphic width="502" depth="232" fileref="figs/sam.0401.gif"></graphic>
</figure>

<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>
</sect2>





<sect2 role="" label="4.3.3" id="ch04-SECT-3.0.3">
<indexterm id="ch04-idx-968285-0"><primary>copy option</primary></indexterm>
<title>
copy</title>


<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>


<programlisting>[template]
        writable = yes
        browsable = yes
        valid users = andy, dave, peter

[data]
        path = /usr/local/samba
        copy = template</programlisting>


<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>
<indexterm id="ch04-idx-968230-0" class="endofrange" startref="ch04-idx-967407-0"/> directive.<filename></filename>
<indexterm id="ch04-idx-967416-0" class="endofrange" startref="ch04-idx-968372-0"/></para>
</sect2>
</sect1>









<sect1 role="" label="4.4" id="ch04-71382">
<title>Server Configuration</title>


<para>
<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>


<programlisting>[global]
        #  Server configuration parameters
        netbios name = HYDRA
        server string = Samba %v on (%L)
        workgroup = SIMPLE</programlisting>


<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>


<tip role="ora">
<para>If you had to enter <literal>encrypt passwords=yes</literal> in your earlier configuration file, you should do so here as well.</para>

</tip>

<para>Go ahead and try this configuration file. Create a file named <filename>smb.conf</filename>
<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>


<figure label="4.2" id="ch04-38915">
<title>Network Neighborhood showing the Samba server</title>

<graphic width="502" depth="206" fileref="figs/sam.0402.gif"></graphic>
</figure>

<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>


<figure label="4.3" id="ch04-50900">
<title>Network Neighborhood details listing</title>

<graphic width="502" depth="220" fileref="figs/sam.0403.gif"></graphic>
</figure>

<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>


<sect2 role="" label="4.4.1" id="ch04-SECT-4.1">
<title>Server Configuration Options</title>


<para>
<indexterm id="ch04-idx-967248-0" class="startofrange"><primary>configuration options</primary><secondary>server</secondary></indexterm>
<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>


<table label="4.3" id="ch04-61150">
<title>Server Configuration Options </title>

<tgroup cols="5">
<colspec colnum="1" colname="col1"/>
<colspec colnum="2" colname="col2"/>
<colspec colnum="3" colname="col3"/>
<colspec colnum="4" colname="col4"/>
<colspec colnum="5" colname="col5"/>
<thead>
<row>

<entry colname="col1"><para>Option</para></entry>

<entry colname="col2"><para>Parameters</para></entry>

<entry colname="col3"><para>Function</para></entry>

<entry colname="col4"><para>Default</para></entry>

<entry colname="col5"><para>Scope</para></entry>

</row>

</thead>

<tbody>
<row>

<entry colname="col1"><para><literal>netbios name</literal></para></entry>

<entry colname="col2"><para>string</para></entry>

<entry colname="col3"><para>Sets the primary NetBIOS name of the Samba server.</para></entry>

<entry colname="col4"><para>Server DNS hostname</para></entry>

<entry colname="col5"><para>Global</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>server string</literal></para></entry>

<entry colname="col2"><para>string</para></entry>

<entry colname="col3"><para>Sets a descriptive string for the Samba server.</para></entry>

<entry colname="col4"><para><literal>Samba %v</literal></para></entry>

<entry colname="col5"><para>Global</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>workgroup</literal></para></entry>

<entry colname="col2"><para>string</para></entry>

<entry colname="col3"><para>Sets the NetBIOS group of machines that the server belongs to.</para></entry>

<entry colname="col4"><para>Defined at compile time</para></entry>

<entry colname="col5"><para>Global</para></entry>

</row>

</tbody>
</tgroup>
</table>


<sect3 role="" label="4.4.1.1" id="ch04-SECT-4.1.1">
<indexterm id="ch04-idx-968288-0"><primary>netbios name option</primary></indexterm>
<title>
netbios name</title>


<para>The <literal>netbios</literal> <literal>name</literal> option allows you to set the NetBIOS name of the server. For example:</para>


<programlisting>netbios name = YORKVM1</programlisting>


<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>


<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>


<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>
</sect3>



<sect3 role="" label="4.4.1.2" id="ch04-SECT-4.1.2">
<indexterm id="ch04-idx-968291-0"><primary>server string parameter</primary></indexterm>
<title>
server string</title>


<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>


<programlisting>[global]
        server string = Samba %v on (%h)</programlisting>


<para>The default for this option simply presents the current version of Samba and is equivalent to:</para>


<programlisting>server string = Samba %v</programlisting>
</sect3>



<sect3 role="" label="4.4.1.3" id="ch04-SECT-4.1.3">
<indexterm id="ch04-idx-968294-0"><primary>workgroup parameter</primary></indexterm>
<title>
workgroup</title>


<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>


<programlisting>[global]
        workgroup = SIMPLE</programlisting>


<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"/>
<indexterm id="ch04-idx-967252-1" class="endofrange" startref="ch04-idx-967248-1"/> file.<footnote label="2" id="ch04-pgfId-962322">


<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>


</footnote>
<indexterm id="ch04-idx-967243-0" class="endofrange" startref="ch04-idx-967242-0"/></para>
</sect3>
</sect2>
</sect1>









<sect1 role="" label="4.5" id="ch04-14274">
<title>Disk Share Configuration</title>


<para>
<indexterm id="ch04-idx-967244-0" class="startofrange"><primary>configuring disk shares</primary></indexterm>
<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>


<programlisting>[global]
        netbios name = HYDRA
        server string = Samba %v on (%L)
        workgroup = SIMPLE

[data]
        path = /export/samba/data
        comment = Data Drive
        volume = Sample-Data-Drive
        writeable = yes
        guest ok = yes</programlisting>


<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>


<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>


<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>


<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>


<programlisting># <emphasis role="bold">mkdir /export/samba/data</emphasis>
# <emphasis role="bold">chmod 777 /export/samba/data</emphasis></programlisting>


<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>


<figure label="4.4" id="ch04-13866">
<title>The initial data share on the Samba server</title>

<graphic width="502" depth="175" fileref="figs/sam.0404.gif"></graphic>
</figure>

<sect2 role="" label="4.5.1" id="ch04-SECT-5.1">
<title>Disk Share Configuration Options</title>


<para>
<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>


<table label="4.4" id="ch04-82964">
<title>Basic Share Configuration Options </title>

<tgroup cols="5">
<colspec colnum="1" colname="col1"/>
<colspec colnum="2" colname="col2"/>
<colspec colnum="3" colname="col3"/>
<colspec colnum="4" colname="col4"/>
<colspec colnum="5" colname="col5"/>
<thead>
<row>

<entry colname="col1"><para>Option</para></entry>

<entry colname="col2"><para>Parameters</para></entry>

<entry colname="col3"><para>Function</para></entry>

<entry colname="col4"><para>Default</para></entry>

<entry colname="col5"><para>Scope</para></entry>

</row>

</thead>

<tbody>
<row>

<entry colname="col1"><para><literal>path (directory)</literal></para></entry>

<entry colname="col2"><para>string (fully-qualified pathname)</para></entry>

<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>

<entry colname="col4"><para><literal>/tmp</literal></para></entry>

<entry colname="col5"><para>Share</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>guest ok (public)</literal></para></entry>

<entry colname="col2"><para>boolean</para></entry>

<entry colname="col3"><para>If set to <literal>yes</literal>, authentication is not needed to access this share</para></entry>

<entry colname="col4"><para><literal>no</literal></para></entry>

<entry colname="col5"><para>Share</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>comment</literal></para></entry>

<entry colname="col2"><para>string</para></entry>

<entry colname="col3"><para>Sets the comment that appears with the share</para></entry>

<entry colname="col4"><para>None</para></entry>

<entry colname="col5"><para>Share</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>volume</literal></para></entry>

<entry colname="col2"><para>string</para></entry>

<entry colname="col3"><para>Sets the volume name: the DOS name of the physical drive</para></entry>

<entry colname="col4"><para>Share name</para></entry>

<entry colname="col5"><para>Share</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>read only</literal></para></entry>

<entry colname="col2"><para>boolean</para></entry>

<entry colname="col3"><para>If <literal>yes</literal>, allows read only access to a share.</para></entry>

<entry colname="col4"><para><literal>yes</literal></para></entry>

<entry colname="col5"><para>Share</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>writeable (write ok)</literal></para></entry>

<entry colname="col2"><para>boolean</para></entry>

<entry colname="col3"><para>If <literal>no</literal>, allows read only access to a share.</para></entry>

<entry colname="col4"><para><literal>no</literal></para></entry>

<entry colname="col5"><para>Share</para></entry>

</row>

</tbody>
</tgroup>
</table>


<sect3 role="" label="4.5.1.1" id="ch04-SECT-5.1.1">
<title>path</title>


<para>
<indexterm id="ch04-idx-967257-0"><primary>pathnames</primary><secondary>option for</secondary></indexterm>
<indexterm id="ch04-idx-967257-1"><primary>shares</primary><secondary>file, path option for</secondary></indexterm>
<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>


<programlisting>[network]
        path = /export/samba/network
        writable = yes
        guest ok = yes</programlisting>


<para>And the contents of the directory <filename>/usr/local/network</filename> on the Unix side are:</para>


<programlisting>$ <emphasis role="bold">ls -al /export/samba/network</emphasis>
drwxrwxrwx  9  root   nobody  1024  Feb 16 17:17  .
drwxr-xr-x  9  nobody nobody  1024  Feb 16 17:17  ..
drwxr-xr-x  9  nobody nobody  1024  Feb 16 17:17  quicken
drwxr-xr-x  9  nobody nobody  1024  Feb 16 17:17  tax98
drwxr-xr-x  9  nobody nobody  1024  Feb 16 17:17  taxdocuments</programlisting>


<para>Then we should see the equivalent of <link linkend="ch04-88746">Figure 4.5</link> on the client side.</para>


<figure label="4.5" id="ch04-88746">
<title>Windows client view of a network filesystem specified by path</title>

<graphic width="502" depth="155" fileref="figs/sam.0405.gif"></graphic>
</figure>
</sect3>



<sect3 role="" label="4.5.1.2" id="ch04-SECT-5.1.2">
<indexterm id="ch04-idx-968300-0"><primary>guest ok option</primary></indexterm>
<title>
guest ok</title>


<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>


<programlisting>[global]
        guest account = ftp
[accounting]
        path = /usr/local/account
        guest ok = yes</programlisting>


<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>
</sect3>



<sect3 role="" label="4.5.1.3" id="ch04-SECT-5.1.3">
<indexterm id="ch04-idx-968303-0"><primary>comment option</primary></indexterm>
<title>
comment</title>


<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>


<programlisting>[network]
        comment = Network Drive
        path = /export/samba/network</programlisting>


<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>


<figure label="4.6" id="ch04-34850">
<title>Windows client view of a share comment</title>

<graphic width="502" depth="135" fileref="figs/sam.0406.gif"></graphic>
</figure>

<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>
</sect3>



<sect3 role="" label="4.5.1.4" id="ch04-SECT-5.1.4">
<indexterm id="ch04-idx-968306-0"><primary>volume option</primary></indexterm>
<title>
volume</title>


<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>


<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>


<programlisting>[network]
        comment = Network Drive
        volume = ASVP-102-RTYUIKA
        path = /home/samba/network</programlisting>
</sect3>



<sect3 role="" label="4.5.1.5" id="ch04-SECT-5.1.5">
<indexterm id="ch04-idx-968309-0"><primary>read only option</primary></indexterm>
<indexterm id="ch04-idx-968309-1"><primary>writeable/write ok option</primary></indexterm>
<title>

read only and writeable</title>


<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>


<programlisting>read only = yes
writeable = no</programlisting>


<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>


<programlisting>read only = no
writeable = yes</programlisting>


<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"/>
<indexterm id="ch04-idx-967245-1" class="endofrange" startref="ch04-idx-967244-1"/></para>
</sect3>
</sect2>
</sect1>









<sect1 role="" label="4.6" id="ch04-86705">
<title>Networking Options with Samba</title>


<para>
<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>


<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>


<programlisting>[global]
        netbios name = HYDRA
        server string = Samba %v on (%L)
        workgroup = SIMPLE

        #  Networking configuration options
        hosts allow = 192.168.220. 134.213.233. localhost
        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

[data]
        path = /home/samba/data
        guest ok = yes
        comment = Data Drive
        volume = Sample-Data-Drive
        writeable = yes</programlisting>


<para>
<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>


<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>


<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>


<orderedlist>
<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>
<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>
<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>
<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>
<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>
</orderedlist>

<warning role="ora"> <para>
<indexterm id="ch04-idx-967307-0"><primary>hosts</primary><secondary>subnets and,
caution with</secondary></indexterm>
<indexterm id="ch04-idx-967307-1"><primary>subnets</primary><secondary>hosts and,
caution with</secondary></indexterm>Take care that you don't explicity
allow a host to access a share, but then deny access to the entire
subnet of which the host is part.</para>

</warning>

<para>Let's look at another example of that final item. Consider the following options:</para>


<programlisting>hosts allow = 111.222.
hosts deny = 111.222.333.</programlisting>


<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>


<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>


<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>


<sect2 role="" label="4.6.1" id="ch04-SECT-6.1">
<title>Networking Options</title>


<para>
<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>


<table label="4.5" id="ch04-32963">
<title>Networking Configuration Options </title>

<tgroup cols="5">
<colspec colnum="1" colname="col1"/>
<colspec colnum="2" colname="col2"/>
<colspec colnum="3" colname="col3"/>
<colspec colnum="4" colname="col4"/>
<colspec colnum="5" colname="col5"/>
<thead>
<row>

<entry colname="col1"><para>Option</para></entry>

<entry colname="col2"><para>Parameters</para></entry>

<entry colname="col3"><para>Function</para></entry>

<entry colname="col4"><para>Default</para></entry>

<entry colname="col5"><para>Scope</para></entry>

</row>

</thead>

<tbody>
<row>

<entry colname="col1"><para><literal>hosts allow (allow hosts)</literal></para></entry>

<entry colname="col2"><para>string (list of hostnames)</para></entry>

<entry colname="col3"><para>Specifies the machines that can connect to Samba.</para></entry>

<entry colname="col4"><para>none</para></entry>

<entry colname="col5"><para>Share</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>hosts deny (deny hosts)</literal></para></entry>

<entry colname="col2"><para>string (list of hostnames)</para></entry>

<entry colname="col3"><para>Specifies the machines that cannot connect to Samba.</para></entry>

<entry colname="col4"><para>none</para></entry>

<entry colname="col5"><para>Share</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>interfaces</literal></para></entry>

<entry colname="col2"><para>string (list of IP/netmask combinations)</para></entry>

<entry colname="col3"><para>Sets the network interfaces Samba will respond to. Allows correcting defaults.</para></entry>

<entry colname="col4"><para>system-dependent</para></entry>

<entry colname="col5"><para>Global</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>bind</literal></para>

<para><literal>interfaces only</literal></para></entry>

<entry colname="col2"><para>boolean</para></entry>

<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>

<entry colname="col4"><para><literal>no</literal></para></entry>

<entry colname="col5"><para>Global</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>socket</literal></para>

<para><literal>address</literal></para></entry>

<entry colname="col2"><para>string (IP address)</para></entry>

<entry colname="col3"><para>Sets IP address to listen on, for use with multiple virtual interfaces on a server.</para></entry>

<entry colname="col4"><para>none</para></entry>

<entry colname="col5"><para>Global</para></entry>

</row>

</tbody>
</tgroup>
</table>


<sect3 role="" label="4.6.1.1" id="ch04-SECT-6.1.1">
<indexterm id="ch04-idx-968312-0"><primary>hosts allow option</primary></indexterm>
<title>
hosts allow</title>


<para>
<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>


<programlisting>hosts allow = 192.168.220. localhost</programlisting>


<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">


<para>Starting with Samba 2.0.5, <literal>localhost</literal> will automatically be allowed unless it is explicitly denied.</para>


</footnote></para>


<para>You can specify any of the following formats for this option:</para>


<itemizedlist>
<listitem><para>Hostnames, such as <literal>ftp.example.com </literal>.</para></listitem>
<listitem><para>IP addresses, like <literal>130.63.9.252</literal>.</para></listitem>
<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>
<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>
<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>
<listitem><para>The keyword <literal>ALL</literal>, which allows any client access.</para></listitem>
<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>
</itemizedlist>

<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>


<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>
</sect3>



<sect3 role="" label="4.6.1.2" id="ch04-SECT-6.1.2">
<indexterm id="ch04-idx-968319-0"><primary>hosts deny option</primary></indexterm>
<title>
hosts deny</title>


<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>


<programlisting>hosts deny = ALL EXCEPT .example.com</programlisting>


<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>
</sect3>



<sect3 role="" label="4.6.1.3" id="ch04-SECT-6.1.3">
<indexterm id="ch04-idx-968322-0"><primary>interfaces option</primary></indexterm>
<title>
interfaces</title>


<para>
<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>


<para>The value of this option is one or more sets of IP address/netmask pairs, such as the following:</para>


<programlisting>interfaces = 192.168.220.100/255.255.255.0 192.168.210.30/255.255.255.0</programlisting>


<para>You can optionally specify a CIDR format bitmask, as follows:</para>


<programlisting>interfaces = 192.168.220.100/24 192.168.210.30/24</programlisting>


<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>


<tip role="ora">
<para>This option may not work correctly if you are using DHCP.</para>

</tip>
</sect3>



<sect3 role="" label="4.6.1.4" id="ch04-SECT-6.1.4">
<indexterm id="ch04-idx-968325-0"><primary>bind interfaces only option</primary></indexterm>
<title>
bind interfaces only</title>


<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>


<programlisting>bind interfaces only = yes</programlisting>


<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>


<tip role="ora">
<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>

</tip>
</sect3>



<sect3 role="" label="4.6.1.5" id="ch04-SECT-6.1.5">
<indexterm id="ch04-idx-968328-0"><primary>socket address option</primary></indexterm>
<title>
socket address</title>


<para>
<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>


<programlisting>interfaces = 192.168.220.100/24 192.168.210.30/24
socket address = 192.168.210.30</programlisting>


<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>
</sect3>
</sect2>
</sect1>









<sect1 role="" label="4.7" id="ch04-16899">
<title>Virtual Servers</title>


<para>
<indexterm id="ch04-idx-967325-0" class="startofrange"><primary>servers</primary><secondary>virtual</secondary></indexterm>
<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>


<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>


<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>


<table label="4.6" id="ch04-92259">
<title>Virtual Server Configuration Options </title>

<tgroup cols="5">
<colspec colnum="1" colname="col1"/>
<colspec colnum="2" colname="col2"/>
<colspec colnum="3" colname="col3"/>
<colspec colnum="4" colname="col4"/>
<colspec colnum="5" colname="col5"/>
<thead>
<row>

<entry colname="col1"><para>Option</para></entry>

<entry colname="col2"><para>Parameters</para></entry>

<entry colname="col3"><para>Function</para></entry>

<entry colname="col4"><para>Default</para></entry>

<entry colname="col5"><para>Scope</para></entry>

</row>

</thead>

<tbody>
<row>

<entry colname="col1"><para><literal>netbios aliases</literal></para></entry>

<entry colname="col2"><para>
<indexterm id="ch04-idx-967338-0"><primary>virtual servers</primary><secondary>options for</secondary></indexterm>
<indexterm id="ch04-idx-967338-1"><primary>servers</primary><secondary>virtual</secondary><tertiary>options for</tertiary></indexterm>List of NetBIOS names</para></entry>

<entry colname="col3"><para>Additional NetBIOS names to respond to, for use with multiple "virtual" Samba servers.</para></entry>

<entry colname="col4"><para>None</para></entry>

<entry colname="col5"><para>Global</para></entry>

</row>

</tbody>
</tgroup>
</table>


<sect2 role="" label="4.7.1" id="ch04-SECT-7.0.1">
<indexterm id="ch04-idx-968331-0"><primary>netbios aliases option</primary></indexterm>
<title>
netbios aliases</title>


<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>
<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>


<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>


<programlisting>[global]
        netbios aliases = sales accounting admin
        include = /usr/local/samba/lib/smb.conf.%L</programlisting>


<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>


<programlisting>[global]
        workgroup = SALES
        hosts allow = 192.168.10.255

[sales1998]
        path = /usr/local/samba/sales/sales1998/
...</programlisting>


<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>


<figure label="4.7" id="ch04-28393">
<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
 </title>

<graphic width="502" depth="196" fileref="figs/sam.0407.gif"></graphic>
</figure>
</sect2>
</sect1>









<sect1 role="" label="4.8" id="ch04-29331">
<title>Logging Configuration Options</title>


<para>
<indexterm id="ch04-idx-967340-0" class="startofrange"><primary>log files/logging</primary><secondary>configuration options</secondary></indexterm>
<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>


<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>


<programlisting>[1999/07/21 13:23:25, 3] smbd/service.c:close_cnum(514)
  phoenix (192.168.220.101) closed connection to service IPC$
[1999/07/21 13:23:25, 3] smbd/connection.c:yield_connection(40)
  Yielding connection to IPC$
[1999/07/21 13:23:25, 3] smbd/process.c:process_smb(615)
  Transaction 923 of length 49
[1999/07/21 13:23:25, 3] smbd/process.c:switch_message(448)
  switch message SMBread (pid 467)
[1999/07/21 13:23:25, 3] lib/doscalls.c:dos_ChDir(336)
  dos_ChDir to /home/samba
[1999/07/21 13:23:25, 3] smbd/reply.c:reply_read(2199)
  read fnum=4207 num=2820 nread=2820
[1999/07/21 13:23:25, 3] smbd/process.c:process_smb(615)
  Transaction 924 of length 55
[1999/07/21 13:23:25, 3] smbd/process.c:switch_message(448)
  switch message SMBreadbraw (pid 467)
[1999/07/21 13:23:25, 3] smbd/reply.c:reply_readbraw(2053)
  readbraw fnum=4207 start=130820 max=1276 min=0 nread=1276
[1999/07/21 13:23:25, 3] smbd/process.c:process_smb(615)
  Transaction 925 of length 55
[1999/07/21 13:23:25, 3] smbd/process.c:switch_message(448)
  switch message SMBreadbraw (pid 467)</programlisting>


<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>


<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>


<programlisting>[global]
        netbios name = HYDRA
        server string = Samba %v on (%I)
        workgroup = SIMPLE

        #  Networking configuration options
        hosts allow = 192.168.220. 134.213.233. localhost
        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

        # Debug logging information
        log level = 2
        log file = /var/log/samba.log.%m
        max log size = 50
        debug timestamp = yes

[data]
        path = /home/samba/data
        browseable = yes
        guest ok = yes
        comment = Data Drive
        volume = Sample-Data-Drive
        writeable = yes</programlisting>


<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>


<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>


<programlisting>log file = /usr/local/logs/samba.log.%m</programlisting>


<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>


<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>


<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>


<sect2 role="" label="4.8.1" id="ch04-97929">
<title>Using syslog</title>


<para>If you wish to use the system logger (<filename>syslog </filename>
<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>


<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>


<programlisting>daemon.*        /var/log/daemon.log</programlisting>


<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>


<programlisting>syslog = 2</programlisting>


<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>


<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>


<programlisting>syslog only = yes</programlisting>


<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>
</sect2>




<sect2 role="" label="4.8.2" id="ch04-SECT-8.1">
<title>Logging Configuration Options</title>


<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>


<table label="4.7" id="ch04-92838">
<title>Global Configuration Options </title>

<tgroup cols="5">
<colspec colnum="1" colname="col1"/>
<colspec colnum="2" colname="col2"/>
<colspec colnum="3" colname="col3"/>
<colspec colnum="4" colname="col4"/>
<colspec colnum="5" colname="col5"/>
<thead>
<row>

<entry colname="col1"><para>Option</para></entry>

<entry colname="col2"><para>Parameters</para></entry>

<entry colname="col3"><para>Function</para></entry>

<entry colname="col4"><para>Default</para></entry>

<entry colname="col5"><para>Scope</para></entry>

</row>

</thead>

<tbody>
<row>

<entry colname="col1"><para><literal>log file</literal></para></entry>

<entry colname="col2"><para>string (fully-qualified filename)</para></entry>

<entry colname="col3"><para>Sets the name and location of the log file that Samba is to use. Uses standard variables.</para></entry>

<entry colname="col4"><para>Specified in Samba makefile</para></entry>

<entry colname="col5"><para>Global</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>log level</literal></para>

<para><literal>(debug level)</literal></para></entry>

<entry colname="col2"><para>numerical (0-10)</para></entry>

<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>

<entry colname="col4"><para><literal>1</literal></para></entry>

<entry colname="col5"><para>Global</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>max log size</literal></para></entry>

<entry colname="col2"><para>numerical (size in KB)</para></entry>

<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>

<entry colname="col4"><para><literal>5000</literal></para></entry>

<entry colname="col5"><para>Global</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>debug</literal></para>

<para><literal>timestamp (timestamp logs)</literal></para></entry>

<entry colname="col2"><para>boolean</para></entry>

<entry colname="col3"><para>If no, doesn't timestamp logs, making them easier to read during heavy debugging.</para></entry>

<entry colname="col4"><para><literal>yes</literal></para></entry>

<entry colname="col5"><para>Global</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>syslog</literal></para></entry>

<entry colname="col2"><para>numerical (0-10)</para></entry>

<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>

<entry colname="col4"><para><literal>1</literal></para></entry>

<entry colname="col5"><para>Global</para></entry>

</row>

<row>

<entry colname="col1"><para><literal>syslog only</literal></para></entry>

<entry colname="col2"><para>boolean</para></entry>

<entry colname="col3"><para>If yes, uses <emphasis>syslog</emphasis> entirely and sends no output to the standard Samba log files.</para></entry>

<entry colname="col4"><para><literal>no</literal></para></entry>

<entry colname="col5"><para>Global</para></entry>

</row>

</tbody>
</tgroup>
</table>


<sect3 role="" label="4.8.2.1" id="ch04-log-file-option">
<title>log file</title>


<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>


<programlisting>[global]
        log file = /usr/local/logs/samba.log</programlisting>


<para>You may use variable substitution to create log files specifically for individual users or clients.</para>


<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>
</sect3>



<sect3 role="" label="4.8.2.2" id="ch04-SECT-8.1.2">
<indexterm id="ch04-idx-968338-0"><primary>log level option</primary></indexterm>
<title>
log level</title>


<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>


<programlisting>[global]
log file = /usr/local/logs/samba.log.%m
log level = 3</programlisting>
</sect3>



<sect3 role="" label="4.8.2.3" id="ch04-SECT-8.1.3">
<indexterm id="ch04-idx-968341-0"><primary>max log size option</primary></indexterm>
<title>
max log size</title>


<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>


<programlisting>[global]
log file = /usr/local/logs/samba.log.%m
max log size = 1000</programlisting>


<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>
</sect3>



<sect3 role="" label="4.8.2.4" id="ch04-SECT-8.1.4">
<indexterm id="ch04-idx-968344-0"><primary>debug timestamp option</primary></indexterm>
<indexterm id="ch04-idx-968344-1"><primary>timestamp logs option</primary></indexterm>
<title>

;debug timestamp or timestamp logs</title>


<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>


<programlisting>12/31/98 12:03:34 hydra (192.168.220.101) connect to server network as user davecb</programlisting>


<para>With a <literal>no</literal> value for this option, the output would appear without the datestamp or  the timestamp:</para>


<programlisting>hydra (192.168.220.101) connect to server network as user davecb</programlisting>
</sect3>



<sect3 role="" label="4.8.2.5" id="ch04-78696">
<title>syslog</title>


<para>
<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>
<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>


<programlisting>[global]
        log level = 3
        syslog = 1</programlisting>


<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>


<table label="4.8" id="ch04-80576">
<title>Syslog Priority Conversion </title>

<tgroup cols="2">
<colspec colnum="1" colname="col1"/>
<colspec colnum="2" colname="col2"/>
<thead>
<row>

<entry colname="col1"><para>Log Level</para></entry>

<entry colname="col2"><para>Syslog Priority</para></entry>

</row>

</thead>

<tbody>
<row>

<entry colname="col1"><para>0</para></entry>

<entry colname="col2"><para><literal>LOG_ERR</literal></para></entry>

</row>

<row>

<entry colname="col1"><para>1</para></entry>

<entry colname="col2"><para><literal>LOG_WARNING</literal></para></entry>

</row>

<row>

<entry colname="col1"><para>2</para></entry>

<entry colname="col2"><para><literal>LOG_NOTICE</literal></para></entry>

</row>

<row>

<entry colname="col1"><para>3</para></entry>

<entry colname="col2"><para><literal>LOG_INFO</literal></para></entry>

</row>

<row>

<entry colname="col1"><para>4 and above</para></entry>

<entry colname="col2"><para><literal>LOG_DEBUG</literal></para></entry>

</row>

</tbody>
</tgroup>
</table>


<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>
</sect3>



<sect3 role="" label="4.8.2.6" id="ch04-SECT-8.1.6">
<indexterm id="ch04-idx-968350-0"><primary>syslog only option</primary></indexterm>
<title>
syslog only</title>


<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>


<programlisting>[global]
        syslog only = <indexterm id="ch04-idx-967342-0" class="endofrange" startref="ch04-idx-967340-0"/>
<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>
</sect3>
</sect2>
</sect1>
</chapter>