Section 3.2. The Samba Configuration File Format

3.2. The Samba Configuration File Format

Before delving into Samba configuration, you should understand the Samba configuration file format. This file is called smb.conf, and it's typically located in /etc/samba, although a few distributions (particularly old ones) place it in some variant location, such as /etc/samba.d or /etc. When you compile from source code, it goes in /usr/local/samba/lib unless you change a configuration option.

Wherever it's located, the smb.conf file is broken into several distinct sections, each of which has its purposes. Within each section, lines have a simple structure consisting of a parameter that's to be set and one or more values to be assigned to the parameter, or they may be comment lines. You should also understand the use of Samba variables, which enable you to set a parameter to a value you may not know when creating the configuration file.

3.2.1. Configuration File Sections

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

Example 3-1. A short smb.conf file
[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] sectionthe [homes] and [freefiles] sections in Example 3-1all 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.

3.2.2. Parameters, Values, and Comments

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:

Boolean values

Many Samba parameters require Boolean options. For these, Yes, TRue, and 1 are all synonymous, while No, False, and 0 are their opposites. A few Booleans also accept other options to set a feature automatically or have some other parameter-specific effect.

Numeric values

Some parameters take numeric values, such as a time in seconds or a file size in bytes or kilobytes. Both integral and real numeric values are possible, although some parameters expect one type or the other. Some parameters take values that are special numbers or sets of numbers, such as IP addresses.

String values

You can provide strings to some parameters, such as the values of the workgroup, netbios name, server string, and path parameters in Example 3-1. Sometimes these strings can be almost anything you like, as in server string. Other strings must be constrained in some way, though; for instance, path is a local Linux pathname. When a string value contains spaces, you do not normally need to enclose it in quotes, although you can do so if you prefer. Quotes may also be necessary with lists of string items that contain spaces.

Delimited values

Some parameters accept a limited range of strings as values. For instance, Example 3-1 shows the security parameter, which accepts just a handful of values.


Many parameters accept multiple values as options, such as several IP addresses or hostnames. Lists are normally delimited by commas or spaces, although a few parameters use other characters as delimiters.

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 =,, \     

This example sets the hosts allow parameter to three valuesa 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.

Samba provides a parameter called comment. This is not to be confused with a comment! The comment parameter sets a free-form string that's associated with a share for the benefit of users.

3.2.3. Variables and Their Uses

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.

Table 3-1. Samba variables




The client's OS. Possible values are OS2 (OS/2), Samba, UNKNOWN, WfWg (DOS or Windows for Workgroups), Win2K (Windows 2000), Win95 (Windows 9x/Me), or WinNT (Windows NT).


A print job's length in pages, if known.


The daemon's process ID number.


The client's workgroup or NT domain name, if known.


The sender of a WinPopUp message.


The primary group of %u.


The primary group of %U.


The server's DNS hostname, if known.


The home directory of %u


The client's IP address.


A print job's name.


The server's NetBIOS name.


The client's NetBIOS name, if known.


The client's DNS hostname, if known.


The NIS home directory server.


The path to an automounted share's root directory.


The path to the share's root directory.


The level of the SMB protocol in use. Legal values are CORE, COREPLUS, LANMAN1, LANMAN2, and NT1.


A filename. In printer shares, this identifies the file passed by the client to be printed. It can also refer to a file that holds a WinPopUp message.


The share's name.


A WinPopUp message's destination.


The current date and time.


The effective Linux username. This may not be the same as %U.


The username sent by the client.


Samba's version number.


A print job's size in bytes.


The value of the environment variable envvar.

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.

3.2.4. The include Parameter

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.

    Linux in a Windows World
    Linux in a Windows World
    ISBN: 0596007582
    EAN: 2147483647
    Year: 2005
    Pages: 152

    Similar book on Amazon © 2008-2017.
    If you may any questions please contact us: