Learn Linux, 302 (Mixed environments): SWAT configuration

Managing Samba through a web-based interface

The Samba Web Administration Tool (SWAT) is a web-based administration tool for Samba, enabling GUI configuration from any computer with a web browser. SWAT is a server in its own right, and like all servers, it requires at least minimal configuration. In this article, learn how to install and configure SWAT itself and how to use SWAT to manage Samba.

Roderick W. Smith, Consultant and author

Roderick Smith author photoRoderick 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.



27 September 2011

Also available in Chinese Russian Japanese Spanish

About this series

This series of articles helps you learn Linux systems administration tasks. You can also use the material in these articles to prepare for the Linux Professional Institute Certification level 3 (LPIC-3) exams.

See our developerWorks roadmap for LPI-302 for a description of and link to each article in this series. The roadmap is in progress and reflects the current objectives (March 2011) for the LPIC-3 exams. As each article is completed, it is added to the roadmap.

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.


Prerequisites

About the elective LPI-302 exam

Linux Professional Institute Certification (LPIC) is like many other certifications in that different levels are offered, with each level requiring more knowledge and experience than the previous one. The LPI-302 exam is an elective specialty exam in the third level of the LPIC hierarchy and requires an advanced level of Linux systems administration knowledge.

To get your LPIC-3 certification, you must pass the two first-level exams (101 and 102), the two second-level exams (201 and 202), and the LPIC-3 core exam (301). After you have achieved this level, you can take the elective specialty exams, such as LPI-302.

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.

Build your own feed

You can build a custom RSS, Atom, or HTML feed so you will be notified as we add new articles or update content to this series. Go to developerWorks RSS feeds. Select Linux for the zone and Articles for the type, and type Linux Professional Institute for the keywords. Then, choose your preferred feed type.

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.

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


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.

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

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.

Resources

Learn

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.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Linux on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Linux
ArticleID=762014
ArticleTitle=Learn Linux, 302 (Mixed environments): SWAT configuration
publish-date=09272011