Example 3-1 shows a short but complete smb.conf configuration file. In this file, the section names appear between square brackets ([ ]). In this example, the section names are [global], [homes], and [freefiles].

[global]
   workgroup = GREENHOUSE
   netbios name = MANDRAKE
   server string = Free files for all
   encrypt passwords = Yes
   security = User
   os level = 2
   domain master = No
   preferred master = No
   domain logons = No

[homes]
   browseable = No
   writeable = Yes

# Put all our public files in a logical place....
[freefiles]
   path = /usr/share/samba/public
   browseable = Yes
   writeable = No

The [global] section of smb.conf is the only section that’s really required. It sets global-level parameters that affect the operation of the server as a whole, such as setting its NetBIOS name and password encryption settings. In addition, you can place most share-level parameters in the [global] section, in which case the parameter effectively changes the default behavior. For instance, the writeable parameter is share-level, meaning that you can set it differently for each share. If placed in the [global] section, though, this parameter sets the default for the rest of the shares. This can be handy if you have many shares that use similar options; rather than set the same parameter in all the shares, you can set it just once, in the [global] section.

Sections after the [global] section—the [homes] and [freefiles] sections in Example 3-1—all define individual Samba shares. Each share definition begins with its name and ends with the next share definition or the end of the file. All the parameters in a share definition must be share-level parameters.

Frequently, the share names are not indented, while parameters belonging to a share are indented. This practice makes it easy to locate the parameters you want to adjust, but it’s not required; Samba ignores most whitespace in smb.conf, including indentation of configuration lines.

If you examine Example 3-1, you’ll quickly discern the basic form of an smb.conf parameter line:

                  parameter = Value

The parameter is a keyword that holds particular meaning to Samba. Some Samba functions can be accessed through multiple parameter names; for instance, writeable is synonymous with writable and write ok, and read only is an antonym for these. In other words, writeable = Yes has the same effect as read only = No.

The Value is the value that’s assigned to the parameter. Several different types of values exist:

For the most part, Samba doesn’t care about the case of its parameters or values; domain master = No has the same effect as DOMAIN MASTER = no or any other variant. Some values, though, are case-sensitive for reasons other than Samba. For instance, a Linux filename provided as a value is case-sensitive because the underlying Linux filesystem is case-sensitive.

Similarly, parameters aren’t sensitive to whitespace; you can insert or remote spaces from parameters without causing problems. For instance, server string = Free files for all is identical to serverstring = Free files for all. Whitespace may be important to parameters’ values, though.

If a configuration line is very long, you can break it across multiple lines by ending the first line (and any subsequent nonterminal lines) with a backslash (\):

hosts allow = daisy.greenhouse.example.com, 172.24.21.27, \
              192.168.7.107

This example sets the hosts allow parameter to three values—a hostname and two IP addresses.

Instead of or in addition to a parameter and value, an smb.conf line may hold a comment. These are denoted by a hash mark (#) or a semicolon (;); Samba ignores lines that begin with one of these characters. (Whitespace before comments is ignored.) Many sample smb.conf files contain numerous comments describing the function of each configuration line in the file.

In most cases, you can set a Samba parameter to a constant value. All the parameters in Example 3-1 do this. Samba also supports variables as parameter values. A variable is a placeholder, denoted by a leading percent symbol (%), that can take on a particular value depending upon the machine on which Samba is running, the Samba version, the username of the person accessing the share, and so on. Table 3-1 summarizes Samba’s variables. Note that variable identifiers are case-sensitive; for instance, %d and %D are distinct variables.

You can use a variable much as you’d use any other value in a parameter. It will be expanded to its full replacement value when Samba needs to do so. You can even combine variables with regular text or with other variables. For instance, consider the following parameter:

log file = /var/log/samba/log.%m

A line like this is a common sight in the global sections of smb.conf files. If the client’s NetBIOS name is DAISY, Samba logs information on accesses by this client in /var/log/samba/log.daisy. (Samba usually converts NetBIOS names to lowercase.) If Samba doesn’t know the client’s NetBIOS name, the IP address is substituted for the NetBIOS name. Separating logfiles in this way can be handy when debugging problems or tracing usage patterns for the server.

Some environment variables aren’t guaranteed to be available. For instance, %L is only available if the client uses the NetBIOS over TCP/IP (NBT) method of connecting to the server, using TCP port 139. This variable is meaningless or will return an IP address for a client that uses the newer “raw” SMB/CIFS over on TCP port 445. Similarly, %h and %M work correctly only if your network’s DNS server is working correctly. Variables that convert IP addresses to DNS names also require you to set the hostname lookups = Yes parameter to work correctly. Some parameters have meaning only in particular contexts; for instance, %S is meaningless when used with global parameters because a share name can apply only to an individual share and not to the system as a whole.

Normally, a Samba server uses a single smb.conf configuration file; however, you can use the include parameter to merge in multiple files. This parameter takes a filename as an option. Samba reads the specified file and uses its contents as if they were part of the main smb.conf file, at the location of the include parameter.

Typically, you pass a variable as part of the filename that you give to include. You can use this ability to provide customized configurations for different client computers, client OSs, users, and so on. For instance, you can set options that adjust the server’s delivery of filenames to clients (as described in Chapter 4) based on the client OS:

include = /etc/samba/smb-%a.conf

You then create files called smb-Win95.conf, smb-Samba.conf, or other appropriate values, and place OS-specific options in each file. You can place such a call in the [global] section or in a share definition. In fact, you can even place entire share definitions in an included configuration file. This type of configuration can be useful when one OS works better with one set of options than another. For instance, you might want to set different case-sensitivity options depending on the client OS’s capabilities.