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:
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:
220.127.116.11. 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:
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.
18.104.22.168. 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.
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:
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:
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.