Наши партнеры

Книги по Linux (с отзывами читателей)

Библиотека сайта rus-linux.net

Chapter 6. The Samba Configuration File

In previous chapters, we showed you how to install Samba on a Unix server and set up Windows clients to use a simple disk share. This chapter will show you how Samba can assume more productive roles on your network.

Samba's daemons, smbd and nmbd, are controlled through a single ASCII file, smb.conf, that can contain over 300 unique options (also called parameters). Some of these options you will use and change frequently; others you might never use, depending on how much functionality you want Samba to offer its clients.

This chapter introduces the structure of the Samba configuration file and shows you how to use options to create and modify disk shares. Subsequent chapters will discuss browsing, how to configure users, security, printing, and other topics related to implementing Samba on your network.

The Samba Configuration File

The Samba configuration file, called smb.conf by default, uses the same format as Windows .ini files. If you have ever worked with a .ini file, you will find smb.conf easy to create and modify. 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:

    workgroup = METRAN
    encrypt passwords = yes
    wins support = yes
    log level = 1 
    max log size = 1000
    read only = no
    browsable = no
    map archive = yes
    path = /var/tmp
    printable = yes
    min print space = 2000
    browsable = yes
    read only = yes
    path = /usr/local/samba/tmp

This configuration file is based on the one we created in Chapter 2 and sets up a workgroup in which Samba authenticates users using encrypted passwords and the default user-level security method. Samba is providing WINS name server support. We've configured very basic event logging to use a log file not to exceed 1MB in size. The [homes] share has been added to allow Samba to create a disk share for the home directory of each user who has a standard Unix account on the server. In addition, each printer registered on the server will be publicly available, as will a single read-only share that maps to the /usr/local/samba/tmp directory.

Configuration File Structure

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


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

The remaining lines are individual configuration options for that share. These options will continue until a new section is encountered or until the end of the file is reached. Each configuration option follows a simple format:

option = value

Options in the smb.conf file are set by assigning a value to them. We should warn you up front that some of the option names in Samba are poorly chosen. For example, read only is self-explanatory and is typical of many recent Samba options. The public option is an older option and is vague. It now has a less-confusing synonym guest ok (meaning it can be accessed by guests). Appendix B contains an alphabetical index of all the configuration options and their meanings.

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.


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


Because a new copy of the smbd daemon is created for each connecting client, it is possible for each client to 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. Inside the configuration file, a variable begins with a percent sign (%), followed by a single upper- or lowercase letter, and can be used only on the right side of a configuration option (i.e., after the equal sign). An example is:

    path = /home/ftp/pub/%a

The %a stands for the client system's architecture and will be replaced as shown in Table 6-1.

Table 6-1. %a substitution

Client operating system ("architecture")

Replacement string

Windows for Workgroups


Windows 95 and Windows 98


Windows NT


Windows 2000 and Windows XP




Any OS not listed earlier


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


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 20 variables, as shown in Table 6-2.

Table 6-2. Samba variables



Client variables


Client's architecture (see Table 6-1)


Client's IP address (e.g.,


Client's NetBIOS name


Client's DNS name

User variables


Current Unix username


Requested client username (not always used by Samba)


Home directory of %u


Primary group of %u


Primary group of %U

Share variables


Current share's name


Current share's root directory


Automounter's path to the share's root directory, if different from %P

Server variables


Current server process ID


Samba server's DNS hostname


Samba server's NetBIOS name


Home directory server, from the automount map


Samba version

Miscellaneous variables


The SMB protocol level that was negotiated


The current date and time


The value of environment variable var

Here's another example of using variables: let's say there are five clients on your network, but one client, maya, requires a slightly different [homes] configuration. With Samba, it's simple to handle this:

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

The include option here causes a separate configuration file for each particular NetBIOS machine (%m) to be read in addition to the current file. If the hostname of the client system is maya, and if a smb.conf.maya file exists in the /usr/local/samba/lib directory, Samba will insert that configuration file into the default one. If any configuration options are restated in smb.conf.maya, those values will override any options previously encountered in that share. Note that we say "previously." If any options are restated in the main configuration file after the include option, Samba will honor those restated values for the share in which they are defined.

If the file specified by the include parameter does not exist, Samba will not generate an error. In fact, it won't do anything at all. This allows you to create only one extra configuration file for maya when using this strategy, instead of one for each client that is on the network.

Client-specific configuration files can be used to customize particular clients. They also can be used to make debugging Samba easier. For example, if we have one client with a problem, we can use this approach to give it a private log file with a more verbose logging level. This allows us to see what Samba is doing without slowing down all the other clients or overflowing the disk with useless logs.

You can use the variables in Table 6-2 to give custom values to a variety of Samba options. We will highlight several of these options as we move through the next few chapters.

Special Sections

Now that we've gotten our feet wet with variables, there are a few special sections of the Samba configuration file that we should talk about. Again, don't worry if you do not understand every configuration option listed here; we'll go over each of them in the upcoming chapters.

The [printers] Section

The third special section is called [printers] and is similar to [homes]. If a client attempts to connect to a share that isn't in the smb.conf file and its name can't be found in the password file, Samba will check to see if it is a printer share. Samba does this by reading the printer capabilities file (usually /etc/printcap) to see if the share name appears there.[1] If it does, Samba creates a share named after the printer.

This means that as with [homes], you don't have to maintain a share for each system printer in the smb.conf file. Instead, Samba honors the Unix printer registry if you ask it to, and it provides the registered printers to the client systems. However, there is a potential difficulty: if you have an account named fred and a printer named fred, Samba will always find the user account first, even if the client really needed to connect to the printer.

The process of setting up the [printers] share is discussed in more detail in Chapter 10.

Configuration Options

Options in the Samba configuration files fall into one of two categories: global options or share options. Each category dictates where an option can appear in the configuration file.

Global options

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

Share options

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

In addition, configuration options can take three kinds of values. They are as follows:


These are simply yes or no values, but can be represented by any of the following: yes, no, true, false, 1, or 0. The values are case-insensitive: YES is the same as yes.


This is a decimal, hexadecimal, or octal number. The standard 0xnn syntax is used for hexadecimal and 0nnn for octal.


This is a string of case-sensitive characters, such as a filename or a username.

Configuration File Options

You can instruct Samba to include or replace configuration options as it is processing them. The options to do this are summarized in Table 6-3.

Table 6-3. Configuration file options






config file

string (name of file)

Sets the location of a configuration file to use instead of the current one




string (name of file)

Specifies an additional set of configuration options to be included in the configuration file




string (name of share)

Allows you to clone the configuration options of another share in the current share




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:

    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.

Server Configuration

We will now start from scratch and build a configuration file for our Samba server. First we will introduce three basic configuration options that can appear in the [global] section of the smb.conf file:

    #  Server configuration parameters
    netbios name = toltec
    server string = Samba %v on %L
    workgroup = METRAN
    encrypt passwords = yes

This configuration file is pretty simple; it advertises the Samba server under the NetBIOS name toltec. In addition, it places the system in the METRAN workgroup and displays a description to clients that includes the Samba version number, as well as the NetBIOS name of the Samba server.


If you used the line encrypt passwords = yes in your earlier configuration file, you should do so here as well.

If you like, you can go ahead and try this configuration file. Create a file named smb.conf under the /usr/local/samba/lib directory with the text listed earlier. Then restart the Samba server and use a Windows client to verify the results. Be sure that your Windows clients are in the METRAN workgroup as well. After double-clicking the Network Neighborhood on a Windows client, you should see a window similar to Figure 6-2. (In this figure, Mixtec is another Samba server, and Zapotec is a Windows client.)

Figure 6-2. Network Neighborhood showing Toltec, the Samba server

You can verify the server string by listing the details of the Network Neighborhood window (select Details in the View menu). You should see a window similar to Figure 6-3.

Figure 6-3. Network Neighborhood details listing

If you were to click the toltec icon, a window should appear that shows the services that it provides. In this case, the window would be completely empty because there are no shares on the server yet.

Server Configuration Options

Table 6-4 summarizes the server configuration options introduced previously. All three of these options are global in scope, so they must appear in the [global] section of the configuration file.

Table 6-4. Server configuration options






netbios name


NetBIOS name of the Samba server

Server's unqualified DNS hostname




NetBIOS group to which the server belongs

Defined at compile time


server string


Descriptive string for the Samba server

Samba %v


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.


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:

    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

Disk Share Configuration

We mentioned in the previous section that there were no disk shares on the toltec server. Let's continue building the configuration file and create an empty disk share called [data]. Here are the additions that will do it:

    path = /export/samba/data
    comment = Data Drive
    volume = Sample-Data-Drive
    writable = yes

The [data] share is typical for a Samba disk share. The share maps to the directory /export/samba/data on the Samba server. We've also provided a comment that describes the share as a Data Drive, as well as a volume name for the share itself.

Samba's default is to create a read-only share. As a result, the writable option needs to be explicitly set for each disk share you wish to make writable.

We will also need to create the /export/samba/data directory on the Samba server with the following commands:

# mkdir /export/samba/data
# chmod 777 /export/samba/data

Now, if we connect to the toltec server again by double-clicking its icon in the Windows Network Neighborhood, we will see a single share entitled data, as shown in Figure 6-4. This share has read/write access, so files can be copied to or from it.

Figure 6-4. The initial data share on the Samba server

Disk Share Configuration Options

The basic Samba configuration options for disk shares previously introduced are listed in Table 6-5.

Table 6-5. Basic share configuration options






path (directory)

string (directory name)

Sets the Unix directory that will be provided for a disk share or used for spooling by a printer share.





Sets the comment that appears with the share.





Sets the MS-DOS volume name for the share.

Share name


read only


If yes, allows read-only access to a share.



writable (write ok or writeable)


If no, allows read-only access to a share. If yes, both reading and writing are allowed.