Overview

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.

Back to top

Prerequisites

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.

Back to top

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/xinetd.pid -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.

	
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 = /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. [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.

Back to top

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.

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.

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.

Back to top

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.

Back to top

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.

Resources

Learn

• The official Samba SWAT documentation provides additional details about how to configure and use SWAT.
  
  
• At the LPIC Program site, find detailed objectives, task lists, and sample questions for the three levels of the LPI's Linux systems administration certification. In particular, look at the LPI-302 detailed objectives and the tasks and sample questions.
  
  
• Review the entire LPI exam prep series on developerWorks to learn Linux fundamentals and prepare for systems administrator certification based on LPI exam objectives prior to April 2009.
  
  
• Exam Preparation Resources for Revised LPIC Exams provides a list of other certification training resources maintained by LPI.
  
  
• In the developerWorks Linux zone, find hundreds of how-to articles and tutorials as well as downloads, discussion forums, and a wealth of other resources for Linux developers and administrators.
  
  
• Follow developerWorks on Twitter, or subscribe to a feed of Linux tweets on developerWorks.
  
  
• Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
  
  
• Attend a free developerWorks Live! briefing to get up to speed quickly on IBM products and tools as well as IT industry trends.
  
  
• Watch developerWorks on-demand demos ranging from product installation and setup demos for beginners to advanced functionality for experienced developers.
  
  

Get products and technologies

• The stunnel website provides downloads and documentation on this program.
  
  
• The OpenSSL website provides downloads and documentation on this software.
  
  

Discuss

• Get involved in the My developerWorks community. Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups, and wikis.
  
  

About the author

Roderick W. Smith is a consultant and author of over a dozen books on UNIX and Linux, including The Definitive Guide to Samba 3, Linux in a Windows World, and Linux Professional Institute Certification Study Guide. He is also the author of the GPT fdisk partitioning software. He currently resides in Woonsocket, Rhode Island.

Rate this article

Comments

Back to top

Table of contents

• Overview
• Prerequisites
• Installing and running SWAT
• Using SWAT
• SWAT caveats
• Moving forward
• Resources
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

Dig deeper into Linux on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers