smb.conf (5)


23 Oct 1998


smb.conf - The configuration file for the Samba suite


smb.conf The smb.conf file is a configuration file for the Samba suite. smb.conf contains runtime configuration information for the Samba programs. The smb.conf file is designed to be configured and administered by the swat (8) program. The complete description of the file format and possible parameters held within are here for reference purposes.


The file consists of sections and parameters. A section begins with the name of the section in square brackets and continues until the next section begins. Sections contain parameters of the form

'name = value'

The file is line-based - that is, each newline-terminated line represents either a comment, a section name or a parameter.

Section and parameter names are not case sensitive.

Only the first equals sign in a parameter is significant. Whitespace before or after the first equals sign is discarded. Leading, trailing and internal whitespace in section and parameter names is irrelevant. Leading and trailing whitespace in a parameter value is discarded. Internal whitespace within a parameter value is retained verbatim.

Any line beginning with a semicolon (';') or a hash ('#') character is ignored, as are lines containing only whitespace.

Any line ending in a '\' is "continued" on the next line in the customary UNIX fashion.

The values following the equals sign in parameters are all either a string (no quotes needed) or a boolean, which may be given as yes/no, 0/1 or true/false. Case is not significant in boolean values, but is preserved in string values. Some items such as create modes are numeric.


Each section in the configuration file (except for the [global] section) describes a shared resource (known as a "share"). The section name is the name of the shared resource and the parameters within the section define the shares attributes.

There are three special sections, [global], [homes] and [printers], which are described under 'special sections'. The following notes apply to ordinary section descriptions.

A share consists of a directory to which access is being given plus a description of the access rights which are granted to the user of the service. Some housekeeping options are also specifiable.

Sections are either filespace services (used by the client as an extension of their native file systems) or printable services (used by the client to access print services on the host running the server).

Sections may be designated guest services, in which case no password is required to access them. A specified UNIX guest account is used to define access privileges in this case.

Sections other than guest services will require a password to access them. The client provides the username. As older clients only provide passwords and not usernames, you may specify a list of usernames to check against the password using the "user=" option in the share definition. For modern clients such as Windows 95/98 and Windows NT, this should not be necessary.

Note that the access rights granted by the server are masked by the access rights granted to the specified or guest UNIX user by the host system. The server does not grant more access than the host system grants.

The following sample section defines a file space share. The user has write access to the path /home/bar. The share is accessed via the share name "foo":

 		path = /home/bar
 		writeable = true

The following sample section defines a printable share. The share is readonly, but printable. That is, the only write access permitted is via calls to open, write to and close a spool file. The 'guest ok' parameter means access will be permitted as the default guest user (specified elsewhere):

 		path = /usr/spool/public
 		read only = true
 		printable = true
 		guest ok = true



Parameters define the specific attributes of sections.

Some parameters are specific to the [global] section (e.g., security). Some parameters are usable in all sections (e.g., create mode). All others are permissible only in normal sections. For the purposes of the following descriptions the [homes] and [printers] sections will be considered normal. The letter 'G' in parentheses indicates that a parameter is specific to the [global] section. The letter 'S' indicates that a parameter can be specified in a service specific section. Note that all 'S' parameters can also be specified in the [global] section - in which case they will define the default behavior for all services.

Parameters are arranged here in alphabetical order - this may not create best bedfellows, but at least you can find them! Where there are synonyms, the preferred synonym is described, others refer to the preferred synonym.


Many of the strings that are settable in the config file can take substitutions. For example the option "path = /tmp/%u" would be interpreted as "path = /tmp/john" if the user connected with the username john.

These substitutions are mostly noted in the descriptions below, but there are some general substitutions which apply whenever they might be relevant. These are:

There are some quite creative things that can be done with these substitutions and other smb.conf options.


Samba supports "name mangling" so that DOS and Windows clients can use files that don't conform to the 8.3 format. It can also be set to adjust the case of 8.3 format filenames.

There are several options that control the way mangling is performed, and they are grouped here rather than listed separately. For the defaults look at the output of the testparm program.

All of these options can be set separately for each service (or globally, of course).

The options are:

"mangle case = yes/no" controls if names that have characters that aren't of the "default" case are mangled. For example, if this is yes then a name like "Mail" would be mangled. Default no.

"case sensitive = yes/no" controls whether filenames are case sensitive. If they aren't then Samba must do a filename search and match on passed names. Default no.

"default case = upper/lower" controls what the default case is for new filenames. Default lower.

"preserve case = yes/no" controls if new files are created with the case that the client passes, or if they are forced to be the "default" case. Default Yes.

"short preserve case = yes/no" controls if new files which conform to 8.3 syntax, that is all in upper case and of suitable length, are created upper case, or if they are forced to be the "default" case. This option can be use with "preserve case = yes" to permit long filenames to retain their case, while short names are lowered. Default Yes.

By default, Samba 2.0 has the same semantics as a Windows NT server, in that it is case insensitive but case preserving.


There are a number of ways in which a user can connect to a service. The server follows the following steps in determining if it will allow a connection to a specified service. If all the steps fail then the connection request is rejected. If one of the steps pass then the following steps are not checked.

If the service is marked "guest only = yes" then steps 1 to 5 are skipped.

  1. Step 1: If the client has passed a username/password pair and that username/password pair is validated by the UNIX system's password programs then the connection is made as that username. Note that this includes the \\server\service%username method of passing a username.

  2. Step 2: If the client has previously registered a username with the system and now supplies a correct password for that username then the connection is allowed.

  3. Step 3: The client's netbios name and any previously used user names are checked against the supplied password, if they match then the connection is allowed as the corresponding user.

  4. Step 4: If the client has previously validated a username/password pair with the server and the client has passed the validation token then that username is used. This step is skipped if "revalidate = yes" for this service.

  5. Step 5: If a "user = " field is given in the smb.conf file for the service and the client has supplied a password, and that password matches (according to the UNIX system's password checking) with one of the usernames from the user= field then the connection is made as the username in the "user=" line. If one of the username in the user= list begins with a '@' then that name expands to a list of names in the group of the same name.

  6. Step 6: If the service is a guest service then a connection is made as the username given in the "guest account =" for the service, irrespective of the supplied password.


Here is a list of all global parameters. See the section of each parameter for details. Note that some are synonyms.


Here is a list of all service parameters. See the section of each parameter for details. Note that some are synonyms.