The Samba Configuration File

Samba uses the /etc/samba/smb.conf file to manage Samba configuration.

smb.conf File Structure Overview

The smb.conf file consists of several sections that you configure to make the required services for a specific Samba configuration available. Consider the following sample extract from an smb.conf file:


#========== Global Settings =======
[global]
security = ADS
realm = EXAMPLE.REALM
password server = krbsvr.example.com
.
.
.
load printers = yes
printing = cups
printcap name = cups

#========== Share Definitions =========

[homes]
comment = User home directories
path = /data/pchome/%S
valid users = %S, WWW.EXAMPLE.COM\%S
browsable = no
read only = no
guest ok = no

[printers]
comment = All Printers
path = /var/spool/samba
printable = yes


[test_share]
comment = Shared /usr/local/test_share directory created for tests
path = /usr/local/test_share
valid users = @examplegroup
browsable = yes
read only = no

The following list describes the sections in the preceding configuration example:

[global]

This section contains global settings for the Samba server.

In the preceding example, the security parameter value of ADS means the server is a member of an AD domain that's running in native mode. In this scenario, Samba relies on tickets issued by the Kerberos server to authenticate clients who want to access local services.

[homes]

The [homes] section provides a personal share for users that log onto the Samba server. In the example, the location of each user's home directory is set by the line path = /data/pchome/%S (the %S macro is substituted with the username). The settings for browsable = no and read only = no prevent other users from browsing home directories, while granting full access to valid users.

Important:

Be careful with settings, such as security, especially in the special sections [global], [homes], and [printers].

For example, if guest access is specified in the [homes] section, all home directories are visible to all clients without a password.

You might consider using the invalid users parameter for users such as root and other users with administrative privileges.

[printers]

Specifies print services. The path parameter specifies the location of a spooling directory that receives print jobs from Windows clients before submitting them to the local print spooler.

Samba advertises all locally configured printers on the server.

[test_share]

Specifies a share named test_share, which grants users belonging to group examplegroup browsing and write permissions to the /usr/local/test_share directory.

Note:

The read only = no configuration entry is essential to ensure Samba shares the directory as a writeable share.

For more information see /etc/samba/smb.conf.example, smb.conf(5) manual page, and https://wiki.samba.org/index.php/User_Documentation

Using the testparm Program to Validate Samba Configuration File Content

You use the testparm program to validate a Samba configuration file after making configuration changes. The testparm program detects invalid parameters and values and highlights incorrect settings such as incorrect ID mappings.

Note:

testparm checks a configuration file for internal correctness only. The testparm command isn't capable of testing whether configured services are available or work as expected.

The following example shows how you might use the command to test a copy of the file you're working on:

sudo testparm /etc/samba/smb.conf.my_copy
Load smb config files from /etc/samba/smb.conf.my_copy
Loaded services file OK.
...

If, instead of a copy, you want to test the default Samba configuration file, you don't have to specify the file as a parameter. Run testparm as follows:

sudo testparm

If the testparm command reports any errors or misconfiguration in the configuration file, you must fix the problem and then reissue the command.

For more information, see the testparm(1) manual page.

Best Practice When Editing Samba Configuration

Samba services reload their configuration as follows:

  • Most configuration values are reloaded automatically, every 3 minutes.

  • You can also manually request a reload, for example by using the smbcontrol all reload-config command.

Note:

Some parameters, such as security, require a restart of the smb service to take effect.

The frequent reloading of configuration values doesn't give you much time to validate any changes you're planning to make to /etc/samba/smb.conf. Therefore, as best practice, first test the changes on a copy of the configuration file. The following steps describe how you might do this:

  1. Make a copy of the samba configuration file.

    sudo cp /etc/samba/smb.conf /etc/samba/samba.conf.mycopy
  2. Edit the copy of the file in a text editor, such as vi:

    sudo vi /etc/samba/samba.conf.mycopy
  3. Validate the changes using testparm:

    sudo testparm /etc/samba/smb.conf.my_copy
  4. Overwrite the original file with the copy you have validated:

    sudo mv /etc/samba/samba.conf.my_copy /etc/samba/smb.conf
  5. Use the smbcontrol all reload-config command to reload the configuration:

    sudo smbcontrol all reload-config