# Chapter 2. Installing Samba on a Unix System

Now that you know what Samba can do for you and your users, it's time to get your own network set up. Let's start with the installation of Samba. When dancing the samba, one learns by taking small steps. It's just the same when installing Samba; we need to teach it step by step. This chapter will help you start off on the right foot.

For illustrative purposes, we will be installing the 2.2.6 version of the Samba server on a Linux system running Version 2.4 of the kernel. However, the installation steps are essentially the same for all the platforms Samba supports.

## 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:

1. Download the source or binary files.

2. Read the installation documentation.

3. Configure a makefile.

4. Compile the server and utility programs.

5. Install the server files.

6. Create a Samba configuration file.

7. Test the configuration file.

8. Start the Samba daemons.

9. 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:

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

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

#### Footnotes

> [1] gcc binaries are available for almost every modern machine. See http://www.gnu.org/ for a list of sites with gcc and other GNU software.

> [2] Do not confuse this with the Solaris killall command, which performs part of the system shutdown sequence!

> [3] Depending on the version of xinetd you have and how it was compiled, you might need to send a USR1 or some other signal rather than the HUP signal. Check the manual page for xinetd (8) on your system for details.

> [4] If you did not compile Samba, but instead downloaded a binary, check with the documentation for the package to find out where it expects the smb.conf file to be. Or, try running the testparm program and look for the location of smb.conf in the first line of output. If Samba came preinstalled with your Unix system, an smb.conf file is probably already somewhere on your system.

> [5] In this book, we cover Darwin Version 6.0 and OS X Version 10.2.

> [6] With early releases of Samba 2.2, there were reports of intermittent errors when starting from inetd. We provide this information so that it will be available for later releases when the problem will hopefully have been identified and corrected.

#### TOC