Chapter 6. The Samba Configuration File

Whitespace, quotes, and commas

An important item to remember about configuration options is that all whitespace within the value is significant. For example, consider the following option:

volume = The Big Bad Hard Drive Number 3543

Samba strips away the spaces up to the first T in The. 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 read only), but we recommend you follow convention and keep spaces between the words of options.

If you feel safer including quotation marks at the beginning and end of a configuration option's value, you can do so. Samba will ignore these quotation marks when it encounters them. Never use quotation marks around an option name; Samba will treat this as an error.

Usually, you can use whitespaces or commas to separate a series of values in a list. These two options are equivalent:

netbios aliases = sales, accounting, payroll
netbios aliases = sales accounting payroll

In some cases, you must use one form of separation—sometimes spaces are required, and sometimes commas.

Capitalization

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 /export/samba/simple :

PATH = /EXPORT/SAMBA/SIMPLE

Samba would have no problem with the path 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 is case-sensitive. Consequently, the path listed would not be found, and clients could not connect to the share.

Line continuation

You can continue a line in the Samba configuration file using the backslash, like this:

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

Because of the backslash, these two lines will be treated as one line by Samba. The second line begins at the first nonwhitespace character that Samba encounters; in this case, the o in of.

Comments

You can insert comments in the smb.conf configuration file by starting a line with either a hash (#) or a semicolon ( ; ). For this purpose, both characters are equivalent. For example, the first three lines in the following example would be considered comments:

#  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

Samba will ignore all comment lines in its configuration file; there are no limitations to what can be placed on a comment line after the initial hash mark or semicolon. Note that the line continuation character (\) will not be honored on a commented line. Like the rest of the line, it is ignored.

WARNING

Samba does not allow mixing of comment lines and parameters. Be careful not to put comments on the same line as anything else, such as:

path = /d # server's data partition

Errors such as this, where the parameter value is defined with a string, can be tricky to notice. The testparm program won't complain, and the only clues you'll receive are that testparm reports the path parameter set to /d # server's data partition, and the failures that result when clients attempt to access the share.

Changes at runtime

You can modify the smb.conf configuration file and any of its options at any time while the Samba daemons are running. By default, Samba checks the configuration file every 60 seconds. If it finds any changes, they are immediately put into effect.

TIP

Having Samba check the configuration file automatically can be convenient, but it also means that if you edit smb.conf directly, you might be immediately changing your network's configuration every time you save the file. If you're making anything more than a minor change, it may be wiser to copy smb.conf to a temporary file, edit that, run testparm filename to check it, and then copy the temporary file back to smb.conf. That way, you can be sure to put all your changes into effect at once, and only after you are confident that you have created the exact configuration you wish to implement.

If you don't want to wait for the configuration file to be reloaded automatically, you can force a reload either by sending a hangup signal to the smbd and nmbd processes or simply by restarting the daemons. Actually, it can be a good idea to restart the daemons because it forces the clients to disconnect and reconnect, ensuring that the new configuration is applied to all clients. We showed you how to restart the daemons in Chapter 2, and sending them a hangup (HUP) signal is very similar. On Linux, it can be done with the command:

# killall -HUP smbd nmbd

In this case, not all changes will be immediately recognized by clients. For example, changes to a share that is currently in use will not be registered until the client disconnects and reconnects to that share. In addition, server-specific parameters such as the workgroup or NetBIOS name of the server will not go into effect immediately either. (This behavior was implemented intentionally because it keeps active clients from being suddenly disconnected or encountering unexpected access problems while a session is open.)

config file

The global config file option specifies a replacement configuration file that will be loaded when the option is encountered. If the target file exists, the remainder of the current configuration file, as well as the options encountered so far, will be discarded, and Samba will configure itself entirely with the options in the new file. Variables can be used with the config file option, which is useful in the event that you want to use a special configuration file based on the NetBIOS machine name or user of the client that is connecting.

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:

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

If the configuration file specified does not exist, the option is ignored, and Samba will continue to configure itself based on the current file. This allows a default configuration file to serve most clients, while providing for exceptions with customized configuration files.

include

This option, discussed in greater detail earlier, copies the target file into the current configuration file at the point specified, as shown in Figure 6-1. This option also can be used with variables. You can use this option as follows:

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

If the configuration file specified does not exist, the option is ignored. Options in the include file override any option specified previously, but not options that are specified later. In Figure 6-1, all three options will override their previous values.

Figure 6-1. The include option in a Samba configuration file

The include option does not work with the variables %u (user), %P (current share's root directory), or %S (current share's name) because they are not set at the time the include parameter is processed.

copy

The copy 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:

[template]
    writable = yes
    browsable = yes
    valid users = andy, dave, jay

[data]
    path = /usr/local/samba
    copy = template

Note that any options in the share that invoked the copy directive will override those in the cloned share; it does not matter whether they appear before or after the copy directive.

netbios name

The netbios name option allows you to set the NetBIOS name of the server. For example:

netbios name = YORKVM1

The default value for this configuration option is the server's hostname—that is, the first part of its fully qualified domain name. For example, a system with the DNS name ruby.ora.com would be given the NetBIOS name RUBY by default. While you can use this option to restate the system's NetBIOS name in the configuration file (as we did previously), it is more commonly used to assign the Samba server a NetBIOS name other than its current DNS name. Remember that the name given must follow the rules for valid NetBIOS machine names as outlined in Chapter 1.

Changing the NetBIOS name of the server is not recommended unless you have a good reason. One such reason might be if the hostname of the system is not unique because the LAN is divided over two or more DNS domains. For example, YORKVM1 is a good NetBIOS candidate for vm1.york.example.com to differentiate it from vm1.falkirk.example.com, which has the same hostname but resides in a different DNS domain.

Another use of this option is for relocating SMB services from a dead or retired system. For example, if SALES is the SMB server for the department and it suddenly dies, you could immediately reset netbios name = SALES on a backup Samba server that's taking over for it. Users won't have to change their drive mappings to a different server; new connections to SALES will simply go to the new server.

workgroup

The workgroup parameter sets the current workgroup (or domain) in which the Samba server will advertise itself. Clients that wish to access shares on the Samba server should be in the same NetBIOS group. Remember that workgroups are really just NetBIOS group names and must follow the standard NetBIOS naming conventions outlined in Chapter 1.

The default option for this parameter is set at compile time to WORKGROUP. Because this is the default workgroup name of every unconfigured Windows and Samba system, we recommend that you always set your workgroup name in the Samba configuration file. When choosing your workgroup name, try to avoid making it the same name as a server or user. This will avoid possible problems with WINS name resolution.

server string

The server string parameter defines a comment string that will appear next to the server name in both the Network Neighborhood (when shown with the Details view) and the comment entry of the Microsoft Windows printer manager.[2]

You can use variables to provide information in the description. For example, our entry earlier was:

[global]
    server string = Samba %v on (%h)

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

server string = Samba %v

path

This option, which has the synonym directory, indicates the pathname for the root of the shared directory or printer. You can choose any directory on the Samba server, so long as the owner of the Samba process that is connecting has read and write access to that directory. If the path is for a printing share, it should point to a temporary directory where files can be written on the server before being spooled to the target printer ( /tmp and /var/spool are popular choices). If this path is for a disk share, the contents of the folder representing the share name on the client will match the contents of the directory on the Samba server.

The directory specified as the value for path can be given as a relative path, in which case it will be relative to the directory specified by the root directory parameter. Because root directory defaults to root (/ ), it is generally a good idea to use absolute paths for the path parameter, unless root directory has been set to something other than the default.

comment

The comment option allows you to enter a comment that will be sent to the client when it attempts to browse the share. The user can see the comment by using the Details view on the share folder or with the net view command at an MS-DOS prompt. For example, here is how you might insert a comment for a share:

[network]
    comment = Network Drive
    path = /export/samba/network

Be sure not to confuse the comment option, which documents a Samba server's shares, with the server string option, which documents the server itself.

volume

This option allows you to specify the volume name of the share, which would otherwise default to the name of the share given in the smb.conf file.

Some software installation programs check the volume name of the dist