Learn Linux, 302 (Mixed environments)

SWAT configuration

Managing Samba through a web-based interface

Content series:

This content is part # of # in the series: Learn Linux, 302 (Mixed environments)

Stay tuned for additional content in this series.

This content is part of the series:Learn Linux, 302 (Mixed environments)

Stay tuned for additional content in this series.


In this article, learn about these concepts:

  • Overview of Samba Web Administration Tool (SWAT) features
  • Installing and setting up SWAT
  • Using SWAT to configure Samba

This article helps you prepare for Objective 312.5 in Topic 312 of the Linux Professional Institute's (LPI) Mixed Environment specialty exam (302). The objective has a weight of 4.


This article assumes that you have a working knowledge of Linux command-line functions and that you understand the basics of Samba configuration. You should be familiar with the overall structure of the smb.conf configuration file. You should also understand how servers in general are run, including use of System V (SysV) startup scripts and super servers.

Installing and running SWAT

In Samba version 3.x, SWAT is a separate server from the two main Samba servers, smbd and nmbd. Thus, you must configure it to run separately from the main Samba server. Depending on how you installed Samba, you may need to install SWAT separately, as well. For added security, you may want to configure SWAT to run using Secure Sockets Layer (SSL) encryption.

Note: Samba 4, which is still under development, makes some major architectural changes, including major changes to SWAT. This article describes the state of SWAT in Samba 3.x, which is the version of Samba currently recommended for production environments.

Installing SWAT

If you build Samba from source code, as described in Objective 311.1, SWAT should be built by default and installed along with other Samba components. The --disable-swat option to configure causes SWAT not to be compiled. If you want to explicitly enable SWAT, rather than rely on the default, you can pass --enable-swat to configure.

If you install Samba using a binary package provided by your distribution maintainer, check your packages to determine how to install SWAT. Many distributions provide a package called swat or samba-swat that includes the SWAT server. This package must be installed separately from the basic Samba packages; however, it may be installed automatically. Use your packaging tools to see what packages exist on your system.

If you can't find a separate SWAT package, it may have been installed as part of another Samba package. The SWAT binary is called, unsurprisingly, swat, so you can search for that program file to see if SWAT is available on your computer. If you're using Gentoo Linux, be aware that you must set swat as a USE flag when you emerge the samba package to build SWAT.

With SWAT installed, you can move on to running it. SWAT is designed to be run via a super server, such as xinetd or inetd. Because these super servers' configurations are so different, I describe them separately.

Running SWAT with xinetd

Most Linux distributions today use xinetd as a super server. If you're uncertain which super server your computer uses, try using ps to search for the string inetd:

$ ps ax | grep inetd
17996 ?        Ss     0:00 /usr/sbin/xinetd -pidfile /var/run/ -stayalive -reuse

In this example, xinetd is running. If the ps output shows a process called inetd, you should follow the directions in the next section, Running SWAT with inetd. If no super server process is running, you may need to install either xinetd or inetd.

The xinetd server uses a configuration file called /etc/xinetd.conf. In most installations, this file contains global settings and relies on server-specific files in the /etc/xinetd.d directory. SWAT's configuration file is likely to be called /etc/xinetd.d/swat, and it's likely to look something like Listing 1.

Listing 1. Example SWAT configuration file
service swat
        port            = 901
        socket_type     = stream
        protocol        = tcp
        wait            = no
        only_from       = localhost
        user            = root
        server          = /usr/sbin/swat
        log_on_failure += USERID
        disable         = yes

Your default file may vary in some details, but the key points should be similar. If your system lacks such a file, you can create one or add an entry defining the SWAT service to /etc/xinetd.conf. You should leave most options at their default values (either in the file provided by your distribution or as shown in the preceding example); however, you might need to change some entries:

  • The only_from line defines an access restriction. In this example, xinetd permits access only from the computer on which SWAT runs. This is a useful security precaution, but if you need to administer your Samba server from another computer or a set of computers, you can specify other addresses. Several types of addresses are accepted; consult the man page for xinetd.conf for details.
  • The server line specifies the complete path to the SWAT binary. Be sure that your swat binary resides there.
  • The disable = yes line tells xinetd that it should not start SWAT. You must change this line to read disable = no to use SWAT.

That last point is critically important: Many distributions ship their /etc/xinetd.d/swat configuration files to disable SWAT by default as a security precaution. Servers can also be disabled by a line in /etc/xinetd.conf:

disabled = swat

If you see swat on such a line, you must remove it to launch the server.

Once you've made any desired changes to /etc/xinetd.d/swat, you must tell xinetd to reload its configuration file. With most distributions, you can do this by passing the reload option to xinetd's SysV startup script:

# /etc/init.d/xinetd reload

Once you've done this, you can begin using SWAT. If you want to enable SSL security, though, you should read the section Enabling SSL encryption.

Running SWAT with inetd

If you're using inetd, the configuration process is similar to that for xinetd, but several critical details differ. As you might expect, inetd's configuration file is called /etc/inetd.conf. Recent versions of inetd support splitting off separate per-server configuration files, much as xinetd does, so you may find an /etc/inetd.d directory with separate configuration files.

Whether you use a single /etc/inetd.conf file or an /etc/inetd.d/samba configuration file, Samba's entry consists of a single line:

swat  stream  tcp  nowait  root  /usr/sbin/tcpd  /usr/sbin/swat

This line contains much of the same information as does a xinetd entry. You determine the port number by looking up the name at the start of the line (swat) in /etc/services. The /usr/sbin/tcpd entry in this example has no equivalent in the xinetd configuration, because this entry specifies the program that inetd runs when a client attempts to contact the server. In this example, inetd launches TCP Wrappers (using a program file name of /usr/sbin/tcpd). TCP Wrappers then performs its own security checks and launches SWAT—that is, the program specified in the final entry of the line (/usr/sbin/swat).

You may find an entry for SWAT in your /etc/inetd.conf file that is commented out by a leading hash mark (#). If so, you will have to un-comment the entry to activate SWAT. Once you've done this and modified the entry in any other way you desire, tell inetd to reload its configuration file. You can do this in the same way you reload a xinetd configuration, as described earlier.

Enabling SSL encryption

As just described, a standard SWAT configuration does not support encryption. This is fine if you've restricted access to localhost, as in the xinetd configuration shown earlier, or if you implement similar restrictions using TCP Wrappers. However, if you use SWAT for remote access, running it without encryption means that your root password will traverse your network unencrypted. This risk may be unacceptable, particularly if you need to use SWAT to configure Samba from a computer on the Internet at large rather than from a computer on the same subnet as the Samba server.

To improve security, you can add SSL encryption to your SWAT configuration. To do so, you must install additional software and make configuration changes. The required software is OpenSSL and stunnel. Most distributions make both packages available in their package databases, so installation should be easy.

Note: It's probably best to configure and test SWAT without SSL encryption first. That way, you'll know that the server works as expected in its simplest possible configuration. If you have problems, you can debug them and be sure that the SSL configuration isn't at fault. When everything works, modify your setup to use encryption.

After you've installed the OpenSSL and stunnel programs, complete these steps:

  1. If necessary, create a user and group for stunnel.

    Your stunnel package may have done this on installation, so this step may not be necessary.

  2. Generate an SSL certificate and private key by typing the following (as a single line) as root:
    # openssl req -new -x509 -days 365 -nodes -out 
       /etc/stunnel/stunnel.pem -keyout /etc/stunnel/stunnel.pem

    You'll be asked for various information, such as your hostname and email address. Note that this command creates a certificate that expires in 365 days, so you'll need to repeat this step in a year.

  3. Modify the ownership on the /etc/stunnel/stunnel.pem file so that it's owned by the stunnel user and group you created in step 1.
  4. Create or modify the /etc/stunnel/stunnel.conf file.

    Listing 2 shows a sample configuration file. If your system already contains such a file, leave most options as they are, but ensure that the file has the three final lines shown in Listing 2, beginning with [swat]. These lines tell stunnel how to handle SWAT connections—specifically, stunnel listens on port 901 and passes decrypted traffic to port 902. Also, ensure that the cert and key lines point to the certificate file you generated earlier.

    Listing 2. The stunnel utility requires its own configuration file
    chroot  = /var/lib/stunnel/
    pid     = /
    setuid  = stunnel
    setgid  = stunnel
    debug   = 7
    output  = /var/log/messages
    client  = no
    cert    = /etc/stunnel/stunnel.pem
    key     = /etc/stunnel/stunnel.pem
    # Accept SSL connections on port 901 and funnel it to
    # port 902 for swat. 
    accept   = 901
    connect  = 902
  5. Create a new SWAT entry in your xinetd or inetd configuration.

    This configuration should be just like a regular unencrypted configuration, except that it should listen on port 902 and use a name of swat-stunnel rather than swat. It should accept connections only on the localhost interface.

  6. Disable your original SWAT configuration in xinetd or inetd.
  7. Edit /etc/services:
    1. Duplicate the swat entry.
    2. Rename the duplicate swat-stunnel.
    3. Change the port number to 902.
  8. On some distributions, you may need to edit /etc/default/stunnel4 to enable stunnel to start. Specifically, change the ENABLED line from 0 to 1.
  9. Restart your super server.
  10. Launch stunnel.

    You can usually do this temporarily by typing /etc/initd.d/stunnel start as root, but to run stunnel permanently, you may need to adjust your SysV configuration.

With these changes in place, you should be able to access SWAT using an encrypted connection by specifying https:// rather than http:// as the protocol in your web browser. Note that the first time you connect, your browser is likely to complain about an untrusted certificate, because you generated your certificate yourself. Accept this certificate.

Using SWAT

Once you've configured SWAT, you can begin using it. You can access it using any web browser. When you're in, you can begin using SWAT to manage your Samba server.

Accessing SWAT

Using your favorite web browser on the Samba server computer, type http://localhost:901 as the Uniform Resource Locator (URL); or, if you've configured SWAT to be accessible to other computers, substitute the hostname for localhost in the URL using any computer that should be able to access the server. If you've configured SSL encryption, substitute https:// for http:// at the start of the URL. If you've configured SWAT to accept logins from other than the localhost, you can use a web browser on any operating system you like—Linux, Mac OS X, Windows, and more. You can even use a browser in a mobile phone.

When you first access the server, your web browser will prompt for a user name and password. Enter root as the user name and the root password as the password. You will then be shown the main SWAT page, as shown in Figure 1.

Figure 1. The main SWAT page enables you to choose from SWAT's options
Screenshot shows the SWAT console with configuration buttons to handle sections such as GLOBALS, SHARES, PRINTERS, etc.
Screenshot shows the SWAT console with configuration buttons to handle sections such as GLOBALS, SHARES, PRINTERS, etc.

The buttons just below the Samba logo enable you to configure specific Samba features—the [global] section, file shares, printer shares, and so on. For the most part, Samba configuration via SWAT is self-explanatory if you're familiar with Samba configuration via the smb.conf file.

If you scroll down on the SWAT home page, you'll find links to Samba documentation. This documentation consists of the man pages for the various Samba daemons, configuration files, utilities, and so on.

Examining SWAT features

As an example of SWAT configuration, click GLOBALS. The page refreshes, showing the options you can set in the [global] section of smb.conf, as shown in Figure 2. Click Advanced if you want to see more obscure options; the default Basic view shows only the most common options.

Figure 2. You can set options using web forms in many of the SWAT menus
Screenshot shows the Global parameters entry screen with choices for Basic/Advanced views, Committing and resetting values, and configuration fields to be edited
Screenshot shows the Global parameters entry screen with choices for Basic/Advanced views, Committing and resetting values, and configuration fields to be edited

Peruse the options available on this page, and try changing a few. You must click Commit Changes to enter your changes into the smb.conf file and reload the configuration.

If you click SHARES or PRINTERS, you will be given the opportunity to edit file and printer shares, respectively. The interface is similar to that for the [globals] section, but you must select the share you want to edit from a drop-down menu, then click Choose Share. You can also create a new share by typing its name in a text field next to the Create Share button, and then clicking that button.

Additional buttons enable you to perform other actions:

  • The WIZARD button brings you to a page that enables you to quickly make some common configuration changes, such as setting common domain configurations.
  • The STATUS button shows you the current status of the Samba server, such as how many active connections it's managing and what files it's accessing. You can also start, stop, and restart the smbd, nmbd, and winbindd servers.
  • The VIEW button shows you the current smb.conf configuration file.
  • The PASSWORD button enables you to manage users—change passwords, add users, delete users, and so on. You can do this either on the local machine or on another Server Message Block (SMB)/Common Internet File System (CIFS) server.

Most of these features are accessible only to root. The HOME, STATUS, VIEW, and PASSWORD pages can be accessed by ordinary users, although some options aren't available to them. Ordinary users are most likely to use the PASSWORD page, because they can use it to change their own passwords.

SWAT caveats

SWAT is a useful tool; however, it's not without its limitations and problems. The single biggest SWAT limitation is that it doesn't support the include directive, which you can use in smb.conf to split a configuration across multiple files, possibly even including different configuration files for different clients. If you rely on such configurations, you'll find SWAT inadequate—at least for Samba configuration. (You could still employ SWAT to enable users to change their passwords.)

The other main SWAT caveat is that it's a security risk. You can minimize this risk by having it accept only localhost logins and, if you must log in remotely, by configuring it to use SSL encryption, as described earlier. Even with such measures in place, though, any server is a potential security risk: The software could have undiscovered bugs or be misconfigured in some way. You should be aware of these risks and take appropriate precautions, such as using TCP Wrappers, xinetd options, or iptables firewall rules to limit access to the computer. The more exposed the server is to the Internet, the riskier the configuration.

Moving forward

The next topic in this series, LPIC-3 objective 312.6, covers Samba internationalization issues, including the use of code pages and other Samba options to support non-English file names on a Samba server.

Downloadable resources

Related topics

ArticleTitle=Learn Linux, 302 (Mixed environments): SWAT configuration