Bundled Versions

Samba is in such popular use that many Unix distributions come with it already installed. If you choose to use a bundled version of Samba, you can breeze through most of this chapter, but you'll be stuck with the Samba version and compile-time options your vendor selected for you. That version of Samba can't be any newer than the operating system release, so you're likely to be pretty far behind the latest developments. On the other hand, you can be fairly sure that a bundled version has been installed properly, and perhaps it will take only a few simple modifications to your smb.conf file for you to be off and running. Samba is mature enough that you probably don't need the latest release to meet your basic needs, so you might be perfectly happy running a bundled version.

If you choose this option, be aware that your Samba files, including the very important smb.conf, might be in different places than they would be if you were to install from a binary or source distribution. For example, with the Red Hat, Debian, and Mandrake Linux distributions, smb.conf and some other Samba-related files are in the /etc/samba directory.

If Samba is already installed on your system, you can check to see what version you have by using the command:

$ smbd -V
Version 2.2.6

(If this doesn't work, it might be because smbd is not in your shell's search path. If you have the locate or whereis command in your Unix variant, you can use it to locate the smbd executable.)

You might also be able to use a system-specific tool to query a software-package maintenance utility. On Red Hat Linux, you can use the rpm command to query the installed packages for Samba:

$ rpm -qa | grep samba
samba-client-2.0.8-1.7.1
samba-2.0.8-1.7.1
samba-common-2.0.8-1.7.1

This shows we have Samba 2.0.8, divided into three Red Hat Package Manager (RPM) packages, bundled with Red Hat 7.1. If your version of Samba is old, you might at the very least want to check with your vendor for an update.

Otherwise, if you're sure you are going to install from a binary or source distribution, you can remove the RPM packages as follows:

# rpm -e samba
# rpm -e samba-client
# rpm -e samba-common

If you are not using Red Hat Linux, consult your system's documentation to find the method that works for you.

Binary or Source?

Precompiled "binary" packages are also available for a large number of Unix platforms. These packages contain binaries for each Samba executable, as well as the standard Samba documentation. Note that while installing a binary distribution can save you a fair amount of time and trouble, you should keep a couple of issues in mind when deciding whether to use the binary or compile the source yourself:

The binary packages can lag behind the latest version of the software by one or two (maybe more) minor releases, especially after a series of small changes and for less popular platforms. Compare the release notes for the source and binary packages to make sure there aren't any new features that you need on your platform.
If you use a precompiled binary that is dynamically linked, you will need to ensure that you have the correct libraries required by the executables. If your system does not already have the required version of a library, you might have to install a new version. The README file or makefile that accompanies the binary distribution should list any special requirements.

Many systems with shared libraries come with a nifty tool called ldd. This tool will tell you which libraries a specific binary requires and which libraries on the system satisfy that requirement. For example, checking the smbd program on our test machine gave us:
```
$ ldd smbd
        libdl.so.2 => /lib/libdl.so.2 (0x40026000)
        libnsl.so.1 => /lib/libnsl.so.1 (0x4002a000)
        libpam.so.0 => /lib/libpam.so.0 (0x40041000)
        libc.so.6 => /lib/libc.so.6 (0x40049000)
        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
```
If there are any incompatibilities between Samba and specific libraries on your machine, the distribution-specific documentation should highlight them.
If your precompiled binary is statically linked, it is still possible to have problems. There have been cases in which the statically linked C library calls in Samba programs have been out of sync with the operating-system kernel, even though this is "not supposed to happen."
Keep in mind that each binary distribution carries preset values about the target platform, such as default directories and configuration option values. Again, check the documentation and the makefile included in the source directory to see which directives and variables were used when the binary was compiled. In some cases, these will not be appropriate for your situation.

A few configuration items can be reset with command-line options at runtime rather than at compile time. For example, if your binary tries to place any log, lock, or status files in the "wrong" place (for example, in /usr/local ), you can override this without recompiling.

One point worth mentioning is that the Samba source requires an ANSI C compiler. If you are on a legacy platform with a non-ANSI compiler, such as the cc compiler on SunOS Version 4, you'll have to install an ANSI-compliant compiler such as gcc before you do anything else.[1] If installing a compiler isn't something you want to wrestle with, you can start off with a binary package. However, for the most flexibility and compatibility on your system, we always recommend compiling from the latest stable or production source.

A typical installation will take about an hour to complete, including downloading the source files and compiling them, setting up the configuration files, and testing the server.

Here is an overview of the steps:

Download the source or binary files.
Read the installation documentation.
Configure a makefile.
Compile the server and utility programs.
Install the server files.
Create a Samba configuration file.
Test the configuration file.
Start the Samba daemons.
Test the Samba daemons.

Downloading the Samba Distribution

If you would like to download the latest version of the Samba software, the primary web site is http://www.samba.org. Once connected to this page, you'll see links to several Samba mirror sites across the world, both for the standard Samba web pages and for sites devoted exclusively to downloading Samba. For the best performance, choose a site that is closest to your own geographic location.

The standard Samba web sites have Samba documentation and tutorials, mailing-list archives, and the latest Samba news, as well as source and binary distributions of Samba. The download sites (sometimes called F T P sites) have only the source and binary distributions. Unless you specifically want an older version of the Samba server or are going to install a binary distribution, download the latest source distribution from the closest mirror site. This distribution is always named:

samba-latest.tar.gz

which for the 2.2.6 release is an approximately 5MB file.

The source distribution has been archived with tar and then compressed with the GNU gzip program. To unpack it, move the file to the directory in which you want the Samba source directory to be located, then cd to that directory and run the command:

$ tar xvfz samba-latest.tar.gz

Or, if you do not have the GNU tar program (which also handles the unzipping):

$ gunzip samba-latest.tar.gz
$ tar xvf samba-latest.tar

In that latter case, you might need to install the GNU gunzip program first. While the tar command runs, it will print out a list of the files it installs.

Read the Documentation

This part might seem obvious, but at one time or other you probably uncompressed a package, blindly typed:

$ configure; make; make install

and walked away to get another cup of coffee. Do yourself a favor and be a little more careful this time.

In the top-level directory that you just installed, there is a file named WHATSNEW.txt, which contains the latest news about the release. If you are upgrading, you can find important information about bug fixes or configuration parameters that have been added or are no longer supported.

With both source and binary packages you'll find a large number of documents in the docs directory, in a variety of formats. One file is especially important:

docs/htmldocs/UNIX_INSTALL.html

This is the Samba Team's official instructions on installing Samba on a Unix system, which you might like to use as another perspective besides what we are telling you here.

In general, we expect you'll find to be most useful the files in the following directories:

docs/faq: This is the Samba Frequently Asked Questions (FAQ) files.
docs/htmldocs: This is the miscellaneous documentation in HTML format.
docs/textdocs: Here is more documentation, in simple text format.
docs/manpages: You don't need to worry about these yet; during the installation, the files will be installed so that you can use the man command to read them. But you can take a look in the directory to see which manpages are available.

Configuring Samba

Samba automatically configures itself prior to compilation. This reduces the likelihood of a machine-specific problem, but you might end up wishing for an option after Samba has been installed.

The source distribution of Samba 2.2 and above doesn't initially have a makefile. Instead, one is generated through a GNU configure script, which is located in the samba-2.2.x /source/ directory. The configure script takes care of the machine-specific issues of building Samba.

NOTE

Before running the configure script, it is important that you become the root user on the system. Otherwise, you might get a warning such as:
configure: warning: running as non-root will disable some tests
You don't want any test to be disabled when the Samba makefile is being created; it would leave the potential for errors down the road when compiling or running Samba on your system.

When the configure script is run, it prints out messages telling what it is doing, and error messages might be mixed in. To make sure you see those very important error messages, we suggest you run configure with its standard output passed through some filter to capture the output and keep it from scrolling out of sight. One method is using the more command:

# ./configure | more

We will show you another in a moment.

Although you can run configure as previously with no options, you might want to add support for extra features by passing options on the command line. For example:

# ./configure --with-winbind

will configure the Samba makefile with support for winbind authentication. If you would like a complete list of options, type the following:

# ./configure --help

Each option enables or disables various features. You typically enable a feature by specifying the --with-feature option, which will cause the feature to be compiled and installed. Likewise, if you specify a --without-feature option, the feature will be disabled. A full list of configuration options is provided in Appendix E, but for now we want to point out three of them, which are features we cover later in this book:

--with-msdfs: Include support for Microsoft Distributed filesystem (Dfs), which allows dispersed network resources to be clumped together into one easy-to-navigate directory tree. See Chapter 8.
--with-smbwrapper: Include SMB wrapper support, which allows programs running on the Unix host to access SMB shared folders as if they were Unix filesystems. We recommend using this option. See Chapter 5.
--with-smbmount: Include smbmount support, which allows SMB shared folders to be mounted in the Unix filesystem. At the time of this writing, support for this feature exists only for Linux. This is also covered in Chapter 5.

Each option is disabled by default, and none of the features is essential to Samba. However, you may want to include them in your configuration (as we will in our example) at least to be able to try out the options in later chapters.

In addition, Table 2-1 shows some other parameters that you can give the configure script if you wish to store parts of the Samba distribution in different places, perhaps to make use of multiple disks or partitions. Note that the defaults sometimes refer to a prefix specified earlier in the table.

Table 2-1. Additional configure options

Option	Meaning	Default
`--prefix`=directory	Install architecture-independent files at the base directory specified.	/usr/local/samba
`--eprefix`=directory	Install architecture-dependent files at the base directory specified.	/usr/local/samba
`--bindir`=directory	Install user executables in the directory specified.	eprefix/bin
`--sbindir`=directory	Install administrator executables in the directory specified.	eprefix/bin
`--libexecdir`=directory	Install program executables in the directory specified.	eprefix/libexec
`--datadir`=directory	Install read-only architecture-independent data in the directory specified.	prefix/share
`--libdir`=directory	Install program libraries in the directory specified.	eprefix/lib
`--includedir`=directory	Install package-include files in the directory specified.	prefix/include
`--infodir`=directory	Install additional information files in the directory specified.	prefix/info
`--mandir`=directory	Install manual pages in the directory specified.	prefix/man

Here is a sample execution of the configure script, which creates a Samba 2.2.6 makefile for the Linux platform. Note that you must run the configure script in the source directory and that we are showing you yet another way to capture the output of the script:

$ cd samba-2.2.6/source/
$ su
Password:
# ./configure --with-smbwrapper --with-smbmount \
--with-msdfs --with-syslog --with-utmp 2>&1 | tee config.my.log
loading cache ./config.cache
checking for gcc... (cached) gcc
checking whether the C compiler (gcc -O ) works... yes
checking whether the C compiler (gcc -O ) is a cross-compiler... no
checking whether we are using GNU C... (cached) yes
checking whether gcc accepts -g... (cached) yes
checking for a BSD-compatible install... (cached) /usr/bin/install -c

...(content omitted)...

checking configure summary
configure OK
creating ./config.status
creating include/stamp-h
creating Makefile
creating include/config.h

In general, any message from configure that doesn't begin with the words checking or creating is an error; it often helps to redirect the output of the configure script to a file so that you can quickly search for errors, as we did with the tee command earlier. If there was an error during configuration, more detailed information about it can be found in the config.log file, which is written to the local directory by the configure script, as well as in the config.my.log file, which we created by piping through the tee command. These files are very similar in both name and content, but be careful to check both of them for error messages before continuing!

If the configuration works, you'll see a checking configure summary message followed by a configure OK message and four or five file-creation messages. So far, so good.

Compiling and Installing Samba

At this point you should be ready to build the Samba executables. Compiling is also easy: in the source directory, type make on the command line. The make utility will produce a stream of explanatory and success messages, beginning with:

Using FLAGS = -O -Iinclude ...

This build includes compiles for both smbd and nmbd and ends in a linking command for bin/nmblookup. For example, here is a sample make of Samba Version 2.2.6 on a Linux server:

# make 2>&1 | tee make.log
Using FLAGS =  -O  -Iinclude -I./include -I./ubiqx -I./smbwrapper -D_LARGEFILE64
_SOURCE -D_FILE_OFFSET_BITS=64 -D_GNU_SOURCE  -DLOGFILEBASE="/usr/local/samba/va
r" -DCONFIGFILE="/usr/local/samba/lib/smb.conf" -DLMHOSTSFILE="/usr/local/samba/
lib/lmhosts"   -DSWATDIR="/usr/local/samba/swat" -DSBINDIR="/usr/local/samba/bin
" -DLOCKDIR="/usr/local/samba/var/locks" -DCODEPAGEDIR="/usr/local/samba/lib/cod
epages" -DDRIVERFILE="/usr/local/samba/lib/printers.def" -DBINDIR="/usr/local/sa
mba/bin"  -DHAVE_INCLUDES_H -DPASSWD_PROGRAM="/bin/passwd" -DSMB_PASSWD_FILE="/u
sr/local/samba/private/smbpasswd" -DTDB_PASSWD_FILE="/usr/local/samba/private/sm
bpasswd.tdb"
Using FLAGS32 =  -O  -Iinclude -I./include -I./ubiqx -I./smbwrapper -D_LARGEFILE
64_SOURCE -D_FILE_OFFSET_BITS=64 -D_GNU_SOURCE  -DLOGFILEBASE="/usr/local/samba/
var" -DCONFIGFILE="/usr/local/samba/lib/smb.conf" -DLMHOSTSFILE="/usr/local/samb
a/lib/lmhosts"   -DSWATDIR="/usr/local/samba/swat" -DSBINDIR="/usr/local/samba/b
in" -DLOCKDIR="/usr/local/samba/var/locks" -DCODEPAGEDIR="/usr/local/samba/lib/c
odepages" -DDRIVERFILE="/usr/local/samba/lib/printers.def" -DBINDIR="/usr/local/
samba/bin"  -DHAVE_INCLUDES_H -DPASSWD_PROGRAM="/bin/passwd" -DSMB_PASSWD_FILE="
/usr/local/samba/private/smbpasswd" -DTDB_PASSWD_FILE="/usr/local/samba/private/
smbpasswd.tdb"
Using LIBS = -ldl -lnsl -lpam
Compiling smbd/server.c
Compiling smbd/files.c
Compiling smbd/chgpasswd.c
Compiling smbd/connection.c
Compiling smbd/utmp.c
Compiling smbd/session.c
Compiling smbd/dfree.c
Compiling smbd/dir.c

...(content omitted)...

Compiling rpc_server/srv_srvsvc.c
Compiling rpc_server/srv_srvsvc_nt.c
Compiling rpc_server/srv_util.c
Compiling rpc_server/srv_wkssvc.c
Compiling rpc_server/srv_wkssvc_nt.c
Compiling rpc_server/srv_pipe.c
Compiling rpc_server/srv_dfs.c
Compiling rpc_server/srv_dfs_nt.c
Compiling rpc_server/srv_spoolss.c
Compiling rpc_server/srv_spoolss_nt.c
Compiling lib/util_getent.c
Compiling rpc_parse/parse_lsa.c
Compiling rpc_parse/parse_net.c
Compiling rpc_parse/parsen/smbmount
Compiling client/smbmnt.c
Linking bin/smbmnt
Compiling client/smbumount.c
Linking bin/smbumount
Compiling utils/nmblookup.c
Linking bin/nmblookup

If you encounter a problem when compiling, first check the Samba documentation to see if it is easily fixable. Another possibility is to search or post to the Samba mailing lists, which are given at the end of Chapter 12 and on the Samba home page. Most compilation issues are system-specific and almost always easy to overcome.

Now that the files have been compiled, you can install them into the directories you identified with the command:

# make install

If you happen to be upgrading, your old Samba files will be saved with the extension .old, and you can go back to that previous version with the command make revert. After doing a make install, you should copy the .old files (if they exist) to a new location or name. Otherwise, the next time you install Samba, the original .old will be overwritten without warning and you could lose your earlier version. If you configured Samba to use the default locations for files, the new files will be installed in the directories listed in Table 2-2. Remember that you need to perform the installation from an account that has write privileges on these target directories; this is typically the root account.

Table 2-2. Samba installation directories

Directory	Description
/usr/local/samba	Main tree
/usr/local/samba/bin	Binaries
/usr/local/samba/lib	smb.conf, lmhosts, configuration files, etc.
/usr/local/samba/man	Samba documentation
/usr/local/samba/private	Samba-encrypted password file
/usr/local/samba/swat	SWAT files
/usr/local/samba/var	Samba log files, lock files, browse list info, shared memory files, process ID files

Throughout the remainder of the book, we occasionally refer to the location of the main tree as /usr/local/samba. In most configurations, this is the base directory of the installed Samba package; however, it can vary from system to system .

TIP

Watch out if you've made /usr a read-only partition. You will want to put the logs, locks, and password files somewhere else.

Here is the installation that we performed on our machine. You can see that we used /usr/local/samba as the base directory for the distribution:

# make install 2>&1 | tee make-install.log
Using FLAGS =  -O  -Iinclude -I./include -I./ubiqx -I./smbwrapper -D_LARGEFILE64
_SOURCE -D_FILE_OFFSET_BITS=64 -D_GNU_SOURCE  -DLOGFILEBASE="/usr/local/samba/va
r" -DCONFIGFILE="/usr/local/samba/lib/smb.conf"

...(content omitted)...

The binaries are installed. You can restore the old binaries (if there
were any) using the command "make revert". You can uninstall the binaries
using the command "make uninstallbin" or "make uninstall" to uninstall
binaries, manpages and shell scripts.

...(content omitted)...

======================================================================
The SWAT files have been installed. Remember to read the swat/README
for information on enabling and using SWAT.
======================================================================

If the last message is about SWAT, you've successfully installed all the files. Congratulations! You now have Samba on your system!

Upgrading Your Installation

Eventually a new version of Samba will be released, and you will want to upgrade. This is simple; just repeat the same steps you used to install your current version. Download the source distribution from the Samba web site and install it, then run the ./configure, make, and make install commands as before. If you've forgotten which options you used with the configure script, take a look at the source/config.status file in your previous version's source distribution. The first few lines of this file show the options used the last time configure was run.

When you run the make install command to install your new version, the files of the previous version are replaced with the new ones, and then all you have to do is restart the Samba daemons to get your new version running. See Section 2.8 later in this chapter for directions on how to do this.

Reconfiguring Samba

If you have already compiled Samba and wish to recompile the same source code with different configure options, you should run the following three commands in the source directory before rerunning the configure script:

# autoconf
# make clean
# rm config.cache

This ensures that you are starting with a clean slate and that your previous configure command does not leave any data around that can affect your new build. From here, you can rerun ./configure and then make and make install.

Setting Search Paths

You will probably want to run commands included in the Samba distribution without having to specify their full directory paths. For that to work, the directory in which the Samba executables are located, /usr/local/samba/bin by default, must be added to your shell's PATH environment variable. This environment variable is usually set in one or more of the shell's startup files, which in the case of bash are /etc/profile (systemwide) and the .bash_profile and .bashrc files in each user's home directory.

To be able to read the Samba manual pages using the man command, the directory where Samba's manual pages reside, /usr/local/samba/man by default, must be in your MANPATH environment variable. On Red Hat Linux, this can be accomplished by adding the following two lines to /etc/man.config:

MANPATH            /usr/local/samba/man
MANPATH_MAP        /usr/local/samba/bin     /usr/local/samba/man

Enabling SWAT

The Samba Web Administration Tool (SWAT) runs as a daemon under inetd or xinetd and provides a forms-based editor in your web browser for creating and modifying Samba's configuration file. For SWAT to work, entries must be added for it in the /etc/services and /etc/inetd.conf (or /etc/xinetd.d/swat) configuration files. To add the entries, follow these two steps:

Check your /etc/services file, and if it does not contain the following line, add it to the end of the file:

swat   901/tcp

Now for inetd or xinetd. These are "Internet super daemons" that handle starting daemons on demand, instead of letting them sit around in memory consuming system resources. Most systems use inetd, but xinetd is also used in some versions of Unix, notably the Red Hat Linux (Versions 7 and newer) that we use in our examples. You can use the ps command to see which of the two your system is running.

For inetd, add a line to the /etc/inetd.conf file. (Check your inetd.conf manual page to see the exact format of the inetd.conf file if it differs from the following example.) Don't forget to change the path to the SWAT binary if you installed it in a different location from the default /usr/local/samba:

swat   stream  tcp  nowait  root  /usr/local/samba/bin/swat  swat

Then force inetd to reread its configuration file by sending it a SIGHUP (hangup) signal:

# /bin/kill -HUP -a inetd

Notice that we are using a version of the kill command that supports the -a option, so as to allow us to specify the process by name. On FreeBSD and Linux, you can use the killall command [2] as follows:

# killall -HUP inetd

If you are not running Linux or FreeBSD and your version of kill doesn't have the -a option, you will need to use the ps command to find the process ID and then supply that to kill:

# ps ax | grep inetd
  780 ?        S      0:00 inetd
 1981 pts/4    S      0:00 grep inetd                                         
# kill -HUP 780

If your system is using xinet, add a file named swat in your /etc/xinetd.d directory, containing the following:

# description: swat is the Samba Web Administration Tool, which
#       allows an administrator to configure Samba using a web
#       browser interface, with the URL http://localhost:901
service swat.
{
        socket_type             = stream
        wait                    = no
        protocol                = tcp
        only_from               = localhost
        user                    = root
        log_on_failure          += USERID
        server                  = /usr/local/samba/bin/swat
        port                    = 901
        disable                 = no
}

Then xinetd needs to be sent a signal [3] to make it reread its configuration files:

# /bin/kill -HUP -a xinetd

And that's pretty much it for the installation. Before you can start up Samba, however, you need to create a configuration file for it.

A Basic Samba Configuration File

The key to configuring Samba is its configuration file, smb.conf. This configuration file can be very simple or extremely complex, and the rest of this book is devoted to helping you get deeply personal with this file. For now, however, we'll show you how to set up a single file service, which will allow you to fire up the Samba daemons and see that everything is running as it should be. In later chapters, you will see how to configure Samba for more complicated and interesting tasks.

The installation process does not automatically create an smb.conf configuration file, although several example files are included in the Samba distribution. To test the server software, though, we'll use the following file, which you can create in a text editor. It should be named smb.conf and placed in the /usr/local/samba/lib directory:[4]

[global]
    workgroup = METRAN 
[test] 
    comment = For testing only, please
    path = /usr/local/samba/tmp
    read only = no
    guest ok = yes

This brief configuration file tells the Samba server to offer the /usr/local/samba/tmp directory on the server as an SMB share called test. The server also becomes part of the METRAN workgroup, of which each client must also be a part. If you have already chosen a name for your own workgroup, use the name of your workgroup instead of METRAN in the previous example. In case you are connecting your Samba system into an existing network and need to know the workgroup name, you can ask another system administrator or go to a Windows system in the workgroup and follow these instructions:

Windows 95/98/Me/NT: open the Control Panel, then double-click the Network icon. Click the Identification tab, and look for the "Workgroup:" label.
Windows 2000: open the Control Panel and double-click the System icon. Click the Network Identification tab. The workgroup name will appear below the computer name.
Windows XP: open the Control Panel in Classic View mode and double-click the System icon. Then click the Computer Name tab.

We'll use the [test] share in the next chapter to set up the Windows clients. For now, you can complete the setup by performing the following commands as root on your Unix server:

# mkdir /usr/local/samba/tmp
# chmod 777 /usr/local/samba/tmp

You might also want to put a file or two in the /usr/local/samba/tmp directory so that after your Windows systems are initially configured, you will have something to use to check that everything works.

We should point out that in terms of system security, this is the worst setup possible. For the moment, however, we only wish to test Samba, so we'll leave security out of the picture. In addition, we will encounter some encrypted password issues with Windows clients later on, so this setup will afford us the least amount of headaches.

Encrypted Passwords

If your Windows clients are using Windows 98 or Windows NT 4 Service Pack 3 or above (including Windows 2000 and Windows XP) and you are using a version of Samba earlier than 3.0, you must add the following entry to the [global] section of the Samba configuration file:

[global]
    encrypt passwords = yes

In addition, you must use the smbpasswd program (typically located in the directory /usr/local/samba/bin/ ) to enter the username/password combinations of the Samba users into Samba's encrypted password database. For example, if you wanted to allow Unix user steve to access shares from a client system, you would use this command:

# smbpasswd -a steve
New SMB password:
Retype new SMB password:
Added user steve.

When the first user is added, the program will output a message saying that the encrypted password database does not exist. Don't worry: it will then create the database for you. Make sure that the username/password combinations you add to the encrypted database match the usernames and passwords you intend to use on the Windows client side. You must run smbpasswd for each client user.

In Samba 3.0, passwords are encrypted by default, so the encrypt passwords = yes parameter in the configuration file is optional. However, you will still need to run the smbpasswd command to add users to the encrypted password file.

Using SWAT

Creating a configuration file with SWAT is even easier than writing a configuration file by hand. To invoke SWAT, use your web browser to connect to http://localhost:901, and log on as root with the root password, as shown in Figure 2-1.

Figure 2-1. SWAT login

After logging in, click the GLOBALS button at the top of the screen. You should see the Global Variables page shown in Figure 2-2.

Figure 2-2. SWAT Global Variables page

In this example, notice that SWAT retrieved the workgroup name from the smb.conf file that you created. (If it didn't, go back and perform that step correctly.) Make sure that the security field is set to USER.

If you are running Samba 2.2 and your Windows clients are at least Windows 98 or Windows NT 4 SP 3 or later versions, find encrypt passwords in the Security Options section and select yes.

The only other option you need to change from the menu is one determining which system on the LAN resolves NetBIOS addresses; this system is called the WINS server. At the very bottom of the page, set the wins support field to Yes, unless you already have a WINS server on your network. If you do, put the WINS server's IP address in the wins server field instead. Then return to the top of the screen, and press the Commit Changes button to write the changes out to the smb.conf file.

Next, click the SHARES icon. You should see a page similar to Figure 2-3. Select test (to the right of the Choose Share button), and click the Choose Share button. You will see the Share Parameters screen, as shown in Figure 2-3, with the comment and path fields filled in from your smb.conf file.

Figure 2-3. SWAT Share Parameters screen

If you specified that you want to use encrypted passwords on the GLOBALS page, click the PASSWORD button. Near the top of the screen, you will see the Server Password Management section. Enter your Unix username and password in the spaces, and click the Add New User button. This functions the same as the smbpasswd utility and creates an entry in the /usr/local/samba/private/smbpasswd file to allow you to authenticate from a Windows client.

Now click the VIEW button at the top, and SWAT shows you the following smb.conf file:

# Samba config file created using SWAT
# from localhost (127.0.0.1)
# Date: 2002/09/05 04:56:43

# Global parameters
        workgroup = METRAN
        encrypt passwords = Yes
        wins support = Yes

[test]
        comment = For testing only!
        path = /usr/local/samba/tmp
        read only = No

Once this configuration file is completed, you can skip the next step because the output of SWAT is guaranteed to be syntactically correct.

Disabling Oplocks

The smb.conf file you have just created is certainly good enough for the purpose of initial setup and testing, and you can use it as a starting point from which to develop the configuration of your production Samba server. But before you get too far with that, we want to bring one thing to your attention.

If you are the type of administrator who is highly concerned about data integrity, you might want to make the following modification to your smb.conf file before continuing:

[global]
    oplocks = no

That is, use a text editor to add the line oplocks = no to the [global] section of your smb.conf file. With this example, as with other examples we will present throughout this book, you do not need to enter the [global] line again in your configuration file. We include it only to indicate in which section the parameter belongs.

The oplocks = no parameter disables opportunistic locking by clients. This will result in significantly poorer performance, but will help ensure that flaky Windows clients and/or unreliable network hardware will not lead to corrupted files on the Samba server.

We will cover opportunistic locking (oplocks) in more detail in the section "Locks and Oplocks" in Chapter 8, and recommend that you understand the ideas presented there before implementing a production Samba server that serves database files or other valuable data.

Testing the Configuration File

If you didn't use SWAT to create your configuration file, you should probably test it to ensure that it is syntactically correct. It might seem silly to run a test program against an eight-line configuration file, but it's good practice for the real ones that we'll be writing later on.

The test parser, testparm, examines an smb.conf file for syntax errors and reports any it finds along with a list of the services enabled on your machine. An example follows; you'll notice that in our haste to get the server running we mistyped workgroup as workgrp (the output is often lengthy, so we recommend capturing it with the tee command):

Load smb config files from smb.conf
Unknown parameter encountered: "workgrp"
Ignoring unknown parameter "workgrp"
Processing section "[test]"
Loaded services file OK.
Press Enter to see a dump of your service definitions
# Global parameters
[global]
    workgroup = WORKGROUP
    netbios name = 
    netbios aliases = 
    server string = Samba 2.2.6
    interfaces = 
    bind interfaces only = No

...(content omitted)...

[test]
    comment = For testing only!
    path = /usr/local/samba/tmp
    read only = No

The interesting parts are at the top and bottom. The top of the output will flag any syntax errors that you might have made, and the bottom lists the services that the server thinks it should offer. A word of advice: make sure you and the server have the same expectations.

Firewall Configuration

As with any services that run on TCP/IP, the SMB networking services offered by Samba can be accessed from across the Internet unless your organization's firewall is properly configured. The following ports are used by Samba for SMB networking and SWAT:

Port 137: Used for NetBIOS network browsing
Port 138: Used for NetBIOS name service
Port 139: Used for file and printer sharing and other operations
Port 445: Used by Windows 2000/XP when NetBIOS over TCP/IP is disabled
Port 901: Used by SWAT

At the minimum, your organization's Internet firewall should shut down all the ports in the list to traffic in both directions. Do not assume that preventing incoming connections is sufficient; there are cracks that trick Windows clients into sending data out of the local area network and into the Internet by SMB protocol, even from a local network that uses private IP addresses not forwarded by routers. If you want SMB traffic to travel across the Internet to remote sites, the best way is to use a virtual private network (VPN). See the O'Reilly book, Virtual Private Networks, for more information on this subject.

In addition, you might wish to configure a firewall on the Samba host system to keep SMB packets from traveling further than necessary within your organization's network. For example, port 901 can be shut down for remote accesses so that SWAT can be run only on the Samba host system. If you are using Samba to serve only a fraction of the client systems within your organization, consider allowing SMB packets (i.e., packets on ports 137-139 and 445) to go to or come from only those clients.

For more information on configuring firewalls, see the O'Reilly book Building Internet Firewalls.

Starting the Samba Daemons

Two Samba processes, smbd and nmbd, need to be running for Samba to work correctly. There are three ways to start them:

Manually
Automatically, during system boot
From inetd or xinetd

Starting the Daemons Manually

If you're in a hurry, you can start the Samba daemons by hand. As root, simply enter the following commands:

# /usr/local/samba/bin/smbd -D
# /usr/local/samba/bin/nmbd -D

Samba will now be running on your system and is ready to accept connections. However, keep in mind that if either of the daemons exit for any reason (including system reboots), they will need to be restarted manually.

Automatic Startup

To have the Samba daemons started automatically when the system boots, you need to add the commands listed in the previous section to your standard Unix startup scripts. The exact method varies depending on the flavor of Unix you're using.

BSD Unix

With a BSD-style Unix, you need to append the following code to the rc.local file, which is typically found in the /etc or /etc/rc.d directories:

if [ -x /usr/local/samba/bin/smbd]; then
    echo "Starting smbd..."
    /usr/local/samba/bin/smbd -D
    echo "Starting nmbd..."
    /usr/local/samba/bin/nmbd -D
fi

This code is very simple: it checks to see if the smbd file exists and has execute permissions, and if it does, it starts up both of the Samba daemons on system boot.

System V Unix

With System V, things can get a little more complex. Depending on your Unix version, you might be able to get away with making a simple change to an rc.local file as with BSD Unix, but System V typically uses directories containing links to scripts that control daemons on the system. Hence, you need to instruct the system how to start and stop the Samba daemons. The first step to implement this is to modify the contents of the /etc/rc.d/init.d directory by adding something similar to the following shell script, which for this example we will name smb :

#!/bin/sh

# Check that the Samba configuration file exists
[ -f /usr/local/samba/lib/smb.conf ] || exit 0

start(  )
{
        echo -n "Starting SMB services: "
        /usr/local/samba/bin/smbd -D
        ERROR=$?
        echo

        echo -n "Starting NMB services: "
        /usr/local/samba/bin/nmbd -D
        ERROR2=$?
        if [ $ERROR2 -ne 0 ]
        then
                ERROR=1
        fi
        echo

        return $ERROR
}

stop(  )
{
        echo -n "Shutting down SMB services: "
        /bin/kill -TERM -a smbd
        ERROR=$?
        echo

        echo -n "Shutting down NMB services: "
        /bin/kill -TERM -a nmbd
        ERROR2=$?
        if [ $ERROR2 -ne 0 ]
        then
                ERROR=1
        fi
        echo

        return $ERROR
}

case "$1" in
  start)
        start
        ;;
  stop)
        stop
        ;;
  *)
        echo "Usage: $0 {start|stop}"
        exit 1
esac

exit $?

With this script, you can start and stop smbd and nmbd like this:

# /etc/rc.d/init.d/smb start
Starting SMB services:
Starting NMB services:
# ps ax | grep mbd
 1268 ?        S      0:00 /usr/local/samba/bin/smbd -D
 1270 ?        S      0:00 /usr/local/samba/bin/nmbd -D
 1465 pts/2    S      0:00 grep mbd
# /etc/rc.d/init.d/smb stop
Shutting down SMB services:
Shutting down NMB services:

If you are having trouble writing a startup script for your system, check to see if there is a packaged release of Samba (available from your Unix vendor or the Samba FTP site). If so, you might be able to extract a startup script from it to use as a starting point. Typically, this script doesn't change much (if at all) from release to release, so using a script from an older Samba version should not be a problem. Another possibility is to check the packaging directory in the Samba source distribution. In that directory, there are subdirectories for many Unix versions in which you can find a startup script for those versions. Even if your version isn't included, you can probably find a startup script for a similar version to use as a starting point.

Finally, we need to add symbolic links to the smb script in the /etc/rc.d/rcX.d directories:

# ln -s /etc/rc.d/init.d/smb /etc/rc.d/rc3.d/S35smb
# ln -s /etc/rc.d/init.d/smb /etc/rc.d/rc5.d/S35smb

# ln -s /etc/rc.d/init.d/smb /etc/rc.d/rc0.d/K35smb
# ln -s /etc/rc.d/init.d/smb /etc/rc.d/rc1.d/K35smb
# ln -s /etc/rc.d/init.d/smb /etc/rc.d/rc2.d/K35smb
# ln -s /etc/rc.d/init.d/smb /etc/rc.d/rc4.d/K35smb
# ln -s /etc/rc.d/init.d/smb /etc/rc.d/rc6.d/K35smb

The first two commands, with link names starting with an "S", cause Samba to be started when entering runlevels 3 or 5, which are the runlevels in which network file sharing (NFS) is normally enabled. The second group of commands, with link names starting with a "K", cause Samba to be shut down when entering any of the other runlevels (0, 1, 2, 4, or 6).

The links starting with "S" are used to start the daemons, and the links starting with "K" are used for killing them. When the runlevel is changed, the links starting with "K" in the corresponding directory (e.g., the rc3.d directory for runlevel 3) are executed, followed by the links starting with "S". If we wanted, we could have Samba restarted when switching between runlevels 3 and 5 by adding a K35smb link to each rc3.d and rc5.d directory.

The number after the K or S in the link names is used to set the order in which all the daemons with links in the directory are started or killed off. Get a long listing of the rc3.d or rc5.d directories to see how this is set up on your system. We use 35 to match the behavior of Red Hat's Samba RPM package. The important thing is to make sure when starting Samba that all services it requires are started before it. When shutting down, it is a good idea to shut down Samba before services it requires to avoid excess error messages in the log files, but the order is not as crucial.

Darwin and Mac OS X

An installation of Samba is bundled with the Darwin distribution, which is included in Mac OS X.[5]

The Samba daemons are started during system boot by the script /System/Library/StartupItems/Samba/Samba. To trigger the execution of this script, edit the file /etc/hostconfig and change the SMBSERVER parameter to look like this:

SMBSERVER=-YES-

On Mac OS X, the graphical user interface (GUI) provides an alternative to using the command line. Launch the System Preferences application, and select Sharing (see Figure 2-4). Under the Services tab, turn on Windows File Sharing. This will make the aforementioned change to /etc/hostconfig and immediately execute the startup item.

Figure 2-4. Mac OS X sharing preferences

If you decide to install Samba yourself on Mac OS X, it's best not to stomp on the installation provided with the OS. Use the procedures detailed earlier in this chapter to install the software into /usr/local/samba or some other area unaffected by OS upgrades. (Remember to set up users with smbpasswd if you're using encrypted passwords, as described earlier in this chapter. This step is handled automatically with entries in /var/db/samba/hash if you're using the built-in server on Mac OS X.) Once you've got that working, you can edit the Samba startup item script to refer to your installation, like this:

    #!/bin/sh
    # Start Samba

    . /etc/rc.common

    if [ "${SMBSERVER:=-NO-}" = "-YES-" ]; then
        ConsoleMessage "Starting SMB server"

        if [ -f /usr/local/samba/lib/smb.conf ]; then
            /usr/local/samba/bin/smbd -D
            /usr/local/samba/bin/nmbd -D
        fi
    fi

However, beware of OS updates, which can wipe out your changes. One solution is to make the script immutable, like this:

# chflags uchg /System/Library/StartupItems/Samba/Samba

Testing automatic startup

If you can afford a few minutes of downtime, reboot your system and again use the ps command to check that the smbd and nmbd daemons are running. And if you are managing a 24/7 server, we highly recommend that you find some downtime in which to reboot and perform this check. Otherwise, your next unscheduled downtime might surprise you with a mysterious absence of SMB networking services when the system comes up again!

Starting from inetd

The inetd [6] daemon is a Unix system's Internet "super daemon." It listens on ports defined in /etc/services and executes the appropriate program for each port, which is defined in /etc/inetd.conf. The advantage of this scheme is that you can have a large number of daemons ready to answer queries, but they don't all have to be running all the time. Instead, inetd listens for connection requests and starts the appropriate daemon when it is needed. The penalty is a small overhead cost of creating a new daemon process, as well as the fact that you need to edit two files rather than one to set things up. The inetd daemon is handy if you have only one or two Samba users or your machine is running too many daemons already. It's also easier to perform an upgrade without disturbing an existing connection.

If you wish to start from inetd, first open /etc/services in your text editor. If you don't already have them defined, add the following two lines:

netbios-ssn     139/tcp
netbios-ns      137/udp

Next, edit /etc/inetd.conf. Look for the following two lines and add them if they don't exist. If you already have smbd and nmbd lines in the file, edit them to point at the new smbd and nmbd you've installed. Your brand of Unix might use a slightly different syntax in this file; use the existing entries and the inetd.conf manual page as a guide:

netbios-ssn stream tcp nowait root /usr/local/samba/bin/smbd smbd 
netbios-ns  dgram  udp wait   root /usr/local/samba/bin/nmbd nmbd

Finally, kill any smbd or nmbd processes and send the inetd process a hangup (HUP) signal to tell it to reread its configuration file:

# /bin/kill -TERM -a smbd
# /bin/kill -TERM -a nmbd
# /bin/kill -HUP -a inetd

After that, Samba should be up and running.

As we've pointed out before, Red Hat and perhaps other Unix vendors supply xinetd rather than inetd. If you need to use xinetd, you will need to supply a configuration file in the /etc/xinetd.d directory.

Testing the Samba Daemons

We're nearly done with the Samba server setup. All that's left to do is to make sure everything is working as we think it should. A convenient way to do this is to use the smbclient program to examine what the server is offering to the network. If everything is set up properly, you should be able to do the following:

# /usr/local/samba/bin/smbclient -U% -L localhost
added interface ip=172.16.1.1 bcast=172.16.1.255 nmask=255.255.255.0
Domain=[METRAN] OS=[Unix] Server=[Samba 2.2.6]

        Sharename      Type      Comment
        ---------      ----      -------
        test           Disk      For testing only, please
        IPC$           IPC       IPC Service (Samba 2.2.6)
        ADMIN$         Disk      IPC Service (Samba 2.2.6)
        
        Server               Comment
        ---------            -------
        TOLTEC               Samba 2.2.6 on toltec

        Workgroup            Master
        ---------            -------
        METRAN               TOLTEC

If there is a problem, don't panic! Try to start the daemons manually, and check the system output or the debug files at /usr/local/samba/var/log.smb to see if you can determine what happened. If you think it might be a more serious problem, skip to Chapter 12 for help on troubleshooting the Samba daemons.

If it worked, congratulations! You now have successfully set up the Samba server with a disk share. It's a simple one, but we can use it to set up and test the Windows 95/98/Me and NT/2000/XP clients in the next chapter. Then we will start making it more interesting by adding services such as home directories, printers, and security, and by seeing how to integrate the server into a larger Windows domain.

Chapter 2. Installing Samba on a Unix System