Using Samba: A File and Print Server for Linux, Unix & Mac OS X, 3rd Edition

4.1. Basic Syntax and Rules

The Samba configuration file, called smb.conf by default, uses the same format as the Windows ini files. If you have ever worked with such a file on a Microsoft client, you will find smb.conf easy to create and modify. And even if you haven't, you will find the format to be simple and easy to learn. Here is an example of a Samba configuration file:

[global] ## core networking options netbios name = RAIN workgroup = GARDEN encrypt passwords = yes ## netbios name service settings wins support = yes ## logging log level = 1 max log size = 1000 ## default service options read only = no [homes] browseable = no [test] comment = For testing only, please path = /export/tmp

This configuration file, based on the one we created in Chapter 2, sets up a workgroup in which Samba authenticates users using encrypted passwords and the default user-level security method. WINS server support is enabled and to be provided by the nmbd daemon. We've configured very basic event logging to use a logfile not to exceed 1 MB in size and added the [homes] share to allow Samba to export the home directory of each user who has a Unix account on the server.

4.1.1. Configuration File Structure

Let's take another look at this configuration file, this time from a higher level:

[global] ... [homes] ... [test] ...

The names inside the square brackets delineate unique sections of the smb.conf file; the section name corresponds to the name of each share (or service) as viewed by CIFS clients. For example, the [test] and [homes] sections are unique disk shares; they contain options that map to specific directories on the Samba server. All the sections defined in the smb.conf file, with the exception of the [global] section, are available as a file or printer share to clients connecting to the Samba server.

These sections help to group settings together by defining the scope of a parameter. There are two types of parameter scope:

Global

Global options must appear in the [global] section and nowhere else. These options apply to the behavior of the Samba server itself and not to any of its shares.

Share or service

Share options can appear in share definitions, the [global] section, or both. If they appear in the [global] section, they define a default behavior for all services, unless a specific share overrides the option with a value of its own.

The remaining lines of our smb.conf example are individual configuration options for each section. An option's specific scope continues until a new section is encountered or until the end of the file is reached. Because parameters are parsed in a top-down fashion, if you set the same option more than once in the same section, the last value specified is the only one that will be applied. Each configuration option follows a simple format:

option = value

Options in the smb.conf file are set by assigning a value to them. Some of the option names are self-explanatory. Others might require consulting the smb.conf manpage. For example, read only is self-explanatory and is typical of many recent Samba options. In many cases, the common settings are easily understood.

Parameter values in smb.conf fall into five categories:

Boolean

Yes/No, True/False, 1/0.

Integer

The maximum value of the integer depends on the use of the parameter. Note that some options accept a range of valid integers such as a minimum and maximum uid. Certain values, such as 0, may have special meaningsin this case, to not apply the option at all.

Character string or list

Aside from boolean, this is the most common parameter type. Strings are often free-form, such as comment fields, lists of users and groups, or directory paths.

Enumerated types

Some parameters accept a value from discrete list of possibilities. The most common option of this type is the security parameter, which accepts values of share, user, server, domain, or ads. Anything other than the values in this list are reported as syntax errors and the parameter reverts to its default value.

Plug-ins

These are predominately new to Samba 3.0. Several smb.conf settings accept the name of an internal or external module. For example, user account information can be stored in an smbpasswd file or in an LDAP directory. The storage location is controlled by the plug-in value for the passdb backend parameter.

4.1.1.1. Whitespace, delimiters, and capitalization

Parameter names are case- and whitespace-insensitive. For example, READONLY is the same as Read Only or read only. For consistency, option names in this book are usually lowercase and usually follow the spacing conventions as they appear in the smb.conf manpage.

The rules are a little less clear when dealing with parameter values. Generally, the whitespace and capitalization rules are defined by the use of the value. For example, case does not matter for Boolean values: YES is the same as Yes. But string or list values might be case-sensitive, and at a minimum should be assumed to be case-preserving.

Consider the case of a directory path on disk. Common Unix filesystems honor case in file and directory names. This means that /EXPORT is not the same path as /export. However, what if Samba were sharing a FAT filesystem in which case does not matter? What about user or group names? Should they be considered case-sensitive in smb.conf? Normally Unix does treat account names as case-sensitive strings. The bottom line is that string values are case-sensitive when the underlying system that makes use of them is case-sensitve.

When a string is used by Samba itself or as a value transmitted to Windows clients, it can generally be considered as case-preserving but case-insensitive. The comment option for a share is a good example here. The [test] in our smb.conf specifies:

comment = For testing only, please

Samba strips away the spaces up to the first F in For. The remainder of the string is seen as it is by Windows clients. The character case here is only cosmetic.

If an option accepts multiple strings such as a list of usernames or groups, there are two issues of which you must be aware. The first is knowing which characters Samba will interpret as entry delimiters.

The standard delimiting characters in smb.conf are:

• Whitespace

• Comma (,)

• Semicolon (;)

• New line (\n)

• Carriage return (\r)

You haven't been introduced to a parameter that accepts a list of values yet, but imagine a list of users. All of the following lists of three items are semantically the same:

rose, smitty, foo rose smitty, foo rose; smitty foo

So this brings us to to the second question: how can we define a list entry that contains one of these delimiting characters? The most common example is a username that contains a space. The answer is that we explicitly group the tokens in an entry together by surrounding the string with double quotes.

"Alex Rose", smitty, foo

However, never use quotation marks around an option name; Samba will treat this as an error.

smb.conf section names are case-insensitive, but the whitespace does matter when a client attempts to access the share. For this reason, many admins find it easier to avoid share names with whitespace in them.

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

4.1.1.3. Comments

You can insert single-line comments in the smb.conf configuration file (not to be confused with the comment parameter) by starting a line with either a hash (#) or a semicolon (;). For example, the first three lines in the following example would be considered comments:

# Export the home directory for a each user ; Pulls the home directory path via the getpwnam( ) call ; (e.g. a lookup in /etc/passwd) [homes] browseable = no

Samba ignores 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 (\) is not honored on a commented line. Like the rest of the line, it is ignored.

4.1.2. Updating a Live System

You can modify the smb.conf configuration file and any of its options at any time while the Samba daemons are running. The question when they will take effect on the server (and be seen by clients) requires a detailed response.

When changing core NetBIOS or networking settings, such as modifying the name of the server or joining a domain, it is best to assume that a restart of all Samba daemons is necessary. For other global parameters and most changes to shares, apply these rules:

• When a new connection is received, the main smbd process spawns a child process to handle the incoming request. The new child rereads smb.conf upon startup, and therefore sees the change.

• Once started, Samba daemons check every three minutes to determine whether any configuration files have been modified, and if so, reload and act on the parameters.

• An administrator can force an immediate reload of smb.conf by sending the smbd process the Hangup (HUP) signal or by sending a reload-config message via the smbcontrol utility.

• Scanning for new printers in the underlying printing system (e.g., CUPS or /etc/printcap) is controlled by the printcap cache time parameter, which specifies the monitoring interval in seconds.

The next question that should be asked is what happens to active client connections when you restart Samba. The daemon that directly handles client connections is smbd. smbd's architecture uses a fork-on-connect model of handling incoming TCP connections. If you kill the main smbd process, all child processes continue until the client disconnects, and each smbd exits normally. However, until the parent is restarted, the host machine does not allow additional incoming CIFS connections.

If an smbd child that is handling an active connection is killed, all files and shares that the client had open become invalid. Windows clients will automatically reconnect to the server as soon as the user attempts to access one of these previously valid resources. In many instances, the user will never know that the connection was dropped and reestablished. There are a few exceptions:

• If the server does not support encrypted passwords, current releases of Windows cannot reauthenticate the user, because they cache only the hash of the user's password and not the clear text.

• Many applications, when stored on a remote system and run from a network drive, crash when the connection is dropped. However, local applications simply accessing datafiles or documents on a network drive frequently experience no problems during the reconnection.

4.1.3. Variables

Because a new copy of the smbd daemon is created for each connecting client, each client can have its own customized configuration file. Samba allows a limited yet useful form of variable substitution in the configuration file to allow information about the Samba server and the client to be included in the configuration at the time the client connects. A variable in the configuration file consists of a percent sign (%), followed by a single upper- or lowercase letter. Variables can be used only on the right side of a configuration option (i.e., after the equal sign). An example is:

[pub] path = /home/ftp/pub/%a

The %a stands for the client system's architecture and is replaced according to Table 4-1.

In this example, Samba assigns a unique path for the [pub] share to client systems based on what operating system they are running. The path that each client would see as its share differ according to the client's architecture:

/home/ftp/pub/WinNT /home/ftp/pub/Win2K /home/ftp/pub/Samba ... /home/ftp/pub/UNKNOWN

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 more than 20 variables, shown in Table 4-2.

Here's another example of using variables: suppose that you do not want to share the user's Unix home directory, but prefer instead to keep a separate set of home directories specifically for SMB/CIFS clients. You can do this by defining a path in the [homes] service that includes the %U variable.

[homes] path = /export/smb/home/%U ...

When user rose connects to the UNC path \\RAIN\homes, the path statement expands to /export/smb/home/rose. Samba does not automatically create this directory if it does not already exist. One way to solve this this problem is to instruct Samba to run an external program or script when a user connects to a specific share. More about this technique is discussed in Chapter 6.