Chapter 1. How to Install and Test SAMBA

Andrew Tridgell

Samba Team

Jelmer R. Vernooij

The Samba Team

John H. Terpstra

Samba Team

Karl Auer

Dan Shearer

Samba Team

Table of Contents

Obtaining and Installing Samba
Configuring Samba (smb.conf)
Configuration File Syntax
TDB Database File Information
Starting Samba
Example Configuration
SWAT
List Shares Available on the Server
Connect with a UNIX Client
Connect from a Remote SMB Client
What If Things Don't Work?
Still Stuck?
Common Errors
Large Number of smbd Processes
Error Message: open_oplock_ipc
The network name cannot be found

Obtaining and Installing Samba

Binary packages of Samba are included in almost any Linux or UNIX distribution. There are also some packages available at the Samba home page. Refer to the manual of your operating system for details on installing packages for your specific operating system.

If you need to compile Samba from source, check How to Compile Samba.

Configuring Samba (smb.conf)

Samba's configuration is stored in the smb.conf file, which usually resides in /etc/samba/smb.conf or /usr/local/samba/lib/smb.conf. You can either edit this file yourself or do it using one of the many graphical tools that are available, such as the Web-based interface SWAT, that is included with Samba.

Configuration File Syntax

The smb.conf file uses the same syntax as the various old .ini files in Windows 3.1: Each file consists of various sections, which are started by putting the section name between brackets ([]) on a new line. Each contains zero or more key/value pairs separated by an equality sign (=). The file is just a plaintext file, so you can open and edit it with your favorite editing tool.

Each section in the smb.conf file represents either a share or a meta-service on the Samba server. The section [global] is special, since it contains settings that apply to the whole Samba server. Samba supports a number of meta-services, each of which serves its own purpose. For example, the [homes] share is a meta-service that causes Samba to provide a personal home share for each user. The [printers] share is a meta-service that establishes print queue support and that specifies the location of the intermediate spool directory into which print jobs are received from Windows clients prior to being dispatched to the UNIX/Linux print spooler.

The printers meta-service will cause every printer that is either specified in a printcap file, via the lpstat, or via the CUPS API, to be published as a shared print queue. The printers stanza in the smb.conf file can be set as not browseable. If it is set to be browseable, then it will be visible as if it is a share. That makes no sense given that this meta-service is responsible only for making UNIX system printers available as Windows print queues. If a comment parameter is specified, the value of it will be displayed as part of the printer name in Windows Explorer browse lists.

Each section of the smb.conf file that specifies a share, or a meta-service, is called a stanza. The global stanza specifies settings that affect all the other stanzas in the smb.conf file. Configuration parameters are documented in the smb.conf man page. Some parameters can be used only in the global stanza, some only in share or meta-service stanzas, and some can be used globally or just within a share or meta-service stanza.

A minimal smb.conf contains a very minimal smb.conf.

Example 1.1. A minimal smb.conf

[global]
workgroup = WKG
netbios name = MYNAME
[share1]
path = /tmp
[share2]
path = /my_shared_folder
comment = Some random files

TDB Database File Information

This section contains brief descriptions of the databases that are used by Samba-3.

The directory in which Samba stores the tdb files is determined by compile-time directives. Samba-3 stores tdb files in two locations. The best way to determine these locations is to execute the following command:

root#  smbd -b | grep PRIVATE_DIR
   PRIVATE_DIR: /etc/samba/private

This means that the confidential tdb files are stored in the /etc/samba/private directory. Samba-3 also uses a number of tdb files that contain more mundane data. The location of these files can be found by executing:

root#  smbd -b | grep LOCKDIR
   LOCKDIR: /var/lib/samba

Therefore the remaining control files will, in the example shown, be stored in the /var/lib/samba directory.

The persistent tdb files are described in the Persistent TDB File Descriptions table. All persistent tdb files should be regularly backed up. Use the tdbbackup utility to backup the tdb files. All persistent tdb files must be preserved during machine migrations, updates and upgrades.

The temporary tdb files do not need to be backed up, nor do they need to be preseved across machine migrations, updates or upgrades. The temporary tdb files are described in the Temporary TDB File Descriptions.

Table 1.1. Persistent TDB File Descriptions

NameDescription
account_policy

Samba/NT account policy settings, includes password expiration settings.

group_mapping

Mapping table from Windows groups/SID to UNIX groups.

ntdrivers

Stores per-printer installed driver information.

ntforms

Stores per-printer installed forms information.

ntprinters

Stores the per-printer devmode configuration settings.

passdb

Exists only when the tdbsam passwd backend is used. This file stores the SambaSAMAccount information. Note: This file requires that user POSIX account information is availble from either the /etc/passwd file, or from an alternative system source.

registry

Read-only Samba database of a Windows registry skeleton that provides support for exporting various database tables via the winreg RPCs.

secrets

This file stores the Workgroup/Domain/Machine SID, the LDAP directory update password, and a further collection of critical environmental data that is necessary for Samba to operate correctly. This file contains very sensitive information that must be protected. It is stored in the PRIVARE_DIR directory.

share_info

Stores per-share ACL information.

winbindd_idmap

Winbindd's local IDMAP database.

Table 1.2. Temporary TDB File Descriptions

NameDescriptionBackup
brlock

Byte-range locking information.

No
connections

A temporary cache for current connection information used to enforce max connections.

no
eventlog/*tdb

Records of eventlog entries. In most circumstances this is just a cache of system logs.

no
gencache

Generic caching database for dead WINS servers and trusted domain data.

no
login_cache

A temporary cache for login information, in particular bad password attempts.

no
messages

Temporary storage of messages being processed by smbd.

no
netsamlogon_cache

Caches user net_info_3 structure data from net_samlogon requests (as a domain member).

no
perfmon/*.tdb

Performance counter information.

no
printing/*.tdb

Cached output from lpq command created on a per-print-service basis.

no
schannel_store

A confidential file, stored in the PRIVATE_DIR, containing crytographic connection information so that clients that have temporarily disconnected can reconnect without needing to renegotiate the connection setup process.

no
sessionid

Temporary cache for miscellaneous session information and for utmp handling.

no
unexpected

Stores packets received for which no process is actively listening.

no
winbindd_cache

Cache of Identity information received from an NT4 domain or from ADS. Includes user lists, etc.

yes

Starting Samba

Samba essentially consists of two or three daemons. A daemon is a UNIX application that runs in the background and provides services. An example of a service is the Apache Web server for which the daemon is called httpd. In the case of Samba there are three daemons, two of which are needed as a minimum.

The Samba server is made up of the following daemons:

nmbd

This daemon handles all name registration and resolution requests. It is the primary vehicle involved in network browsing. It handles all UDP-based protocols. The nmbd daemon should be the first command started as part of the Samba startup process.

smbd

This daemon handles all TCP/IP-based connection services for file- and print-based operations. It also manages local authentication. It should be started immediately following the startup of nmbd.

winbindd

This daemon should be started when Samba is a member of a Windows NT4 or ADS domain. It is also needed when Samba has trust relationships with another domain. The winbindd daemon will check the smb.conf file for the presence of the idmap uid and idmap gid parameters. If they are are found, winbindd will use the values specified for for UID and GID allocation. If these parameters are not specified, winbindd will start but it will not be able to allocate UIDs or GIDs.

When Samba has been packaged by an operating system vendor, the startup process is typically a custom feature of its integration into the platform as a whole. Please refer to your operating system platform administration manuals for specific information pertaining to correct management of Samba startup.

Example Configuration

There are sample configuration files in the examples subdirectory in the source code distribution tarball package. It is suggested you read them carefully so you can see how the options go together in practice. See the man page for all the options. It might be worthwhile to start out with the smb.conf.default configuration file and adapt it to your needs. It contains plenty of comments.

The simplest useful configuration file would contain something like that shown in Another simple smb.conf File.

Example 1.2. Another simple smb.conf File

[global]
workgroup = MIDEARTH
[homes]
guest ok = no
read only = no

This will allow connections by anyone with an account on the server, using either their login name or homes as the service name. (Note: The workgroup that Samba should appear in must also be set. The default workgroup name is WORKGROUP.)

Make sure you put the smb.conf file in the correct place. Note, the correct location of this file depends on how the binary files were built. You can discover the correct location by executing from the directory that contains the smbd command file:

root#  smbd -b | grep smb.conf

For more information about security settings for the [homes] share, please refer to Securing Samba.

Test Your Config File with testparm

It's important to validate the contents of the smb.conf file using the testparm program. If testparm runs correctly, it will list the loaded services. If not, it will give an error message. Make sure it runs correctly and that the services look reasonable before proceeding. Enter the command:

	root#  testparm /etc/samba/smb.conf
	

Testparm will parse your configuration file and report any unknown parameters or incorrect syntax. It also performs a check for common misconfigurations and will issue a warning if one is found.

Always run testparm again whenever the smb.conf file is changed!

The smb.conf file is constantly checked by the Samba daemons smbd and every instance of itself that it spawns, nmbd and winbindd. It is good practice to keep this file as small as possible. Many administrators prefer to document Samba configuration settings and thus the need to keep this file small goes against good documentation wisdom. One solution that may be adopted is to do all documentation and configuration in a file that has another name, such as smb.conf.master. The testparm utility can be used to generate a fully optimized smb.conf file from this master configuration and documtenation file as shown here:

root#  testparm -s smb.conf.master > smb.conf

This administrative method makes it possible to maintain detailed configuration change records while at the same time keeping the working smb.conf file size to the minimum necessary.

SWAT

SWAT is a Web-based interface that can be used to facilitate the configuration of Samba. SWAT might not be available in the Samba package that shipped with your platform, but in a separate package. If it is necesaary to built SWAT please read the SWAT man page regarding compilation, installation, and configuration of SWAT from the source code.

To launch SWAT, just run your favorite Web browser and point it to http://localhost:901/. Replace localhost with the name of the computer on which Samba is running if that is a different computer than your browser.

SWAT can be used from a browser on any IP-connected machine, but be aware that connecting from a remote machine leaves your connection open to password sniffing because passwords will be sent over the wire in the clear.

More information about SWAT can be found in The Samba Web Administration Tool.

List Shares Available on the Server

To list shares that are available from the configured Samba server, execute the following command:

$ smbclient -L yourhostname

You should see a list of shares available on your server. If you do not, then something is incorrectly configured. This method can also be used to see what shares are available on other SMB servers, such as Windows 2000.

If you choose user-level security, you may find that Samba requests a password before it will list the shares. See the smbclient man page for details. You can force it to list the shares without a password by adding the option -N to the command line.

Connect with a UNIX Client

Enter the following command:

$ smbclient  //yourhostname/aservice

Typically yourhostname is the name of the host on which smbd has been installed. The aservice is any service that has been defined in the smb.conf file. Try your username if you just have a [homes] section in the smb.conf file.

Example: If the UNIX host is called bambi and a valid login name is fred, you would type:

$ smbclient //bambi/fred

Connect from a Remote SMB Client

Now that Samba is working correctly locally, you can try to access it from other clients. Within a few minutes, the Samba host should be listed in the Network Neighborhood on all Windows clients of its subnet. Try browsing the server from another client or "mounting" it.

Mounting disks from a DOS, Windows, or OS/2 client can be done by running a command such as:

C:\> net use m: \\servername\service

Where the drive letter m: is any available drive letter. It is important to double-check that the service (share) name that you used does actually exist.

Try printing, for example,

C:\> net use lpt1:	\\servername\spoolservice

The spoolservice is the name of the printer (actually the print queue) on the target server. This will permit all print jobs that are captured by the lpt1: port on the Windows client to be sent to the printer that owns the spoolservice that has been specified.

C:\> print filename

What If Things Don't Work?

You might want to read The Samba Checklist. If you are still stuck, refer to Analyzing and Solving Samba Problems. Samba has been successfully installed at thousands of sites worldwide. It is unlikely that your particular problem is unique, so it might be productive to perform an Internet search to see if someone else has encountered your problem and has found a way to overcome it.

If you are new to Samba, and particularly if you are new to Windows networking, or to UNIX/Linux, the book “Samba-3 by Example” will help you to create a validated network environment. Simply choose from the first five chapters the network design that most closely matches site needs, then follow the simple step-by-step procedure to deploy it. Later, when you have a working network you may well want to refer back to this book for further insight into opportunities for improvement.

Still Stuck?

The best advice under the stress of abject frustration is to cool down! That may be challenging of itself, but while you are angry or annoyed your ability to seek out a solution is somewhat undermined. A cool head clears the way to finding the answer you are looking for. Just remember, every problem has a solution there is a good chance that someone else has found it even though you can't right now. That will change with time, patience and learning.

Now that you have cooled down a bit, please refer to the Samba Checklist for a process that can be followed to identify the cause of your problem.

Common Errors

The following questions and issues are raised repeatedly on the Samba mailing list.

Large Number of smbd Processes

Samba consists of three core programs: nmbd, smbd, and winbindd. nmbd is the name server message daemon, smbd is the server message daemon, and winbindd is the daemon that handles communication with domain controllers.

If Samba is not running as a WINS server, then there will be one single instance of nmbd running on your system. If it is running as a WINS server, then there will be two instances one to handle the WINS requests.

smbd handles all connection requests. It spawns a new process for each client connection made. That is why you may see so many of them, one per client connection.

winbindd will run as one or two daemons, depending on whether or not it is being run in split mode (in which case there will be two instances).

Error Message: open_oplock_ipc

An error message is observed in the log files when smbd is started: “open_oplock_ipc: Failed to get local UDP socket for address 100007f. Error was Cannot assign requested.

Your loopback device isn't working correctly. Make sure it is configured correctly. The loopback device is an internal (virtual) network device with the IP address 127.0.0.1. Read your OS documentation for details on how to configure the loopback on your system.

The network name cannot be found

This error can be caused by one of these misconfigurations:

  • You specified a nonexisting path for the share in smb.conf.

  • The user you are trying to access the share with does not have sufficient permissions to access the path for the share. Both read (r) and access (x) should be possible.

  • The share you are trying to access does not exist.