mirror of
https://github.com/samba-team/samba.git
synced 2024-12-24 21:34:56 +03:00
d4b35b895c
(This used to be commit 20f8bde1d0
)
607 lines
20 KiB
XML
607 lines
20 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
|
|
<chapter id="SWAT">
|
|
<chapterinfo>
|
|
&author.jht;
|
|
<pubdate>April 21, 2003</pubdate>
|
|
</chapterinfo>
|
|
|
|
<title>SWAT &smbmdash; The Samba Web Administration Tool</title>
|
|
|
|
<para>
|
|
There are many and varied opinions regarding the usefulness of SWAT.
|
|
No matter how hard one tries to produce the perfect configuration tool, it remains
|
|
an object of personal taste. SWAT is a tool that will allow Web-based configuration
|
|
of Samba. It has a wizard that may help to get Samba configured
|
|
quickly, it has context-sensitive help on each &smb.conf; parameter, it provides for monitoring of current state
|
|
of connection information, and it allows network-wide MS Windows network password
|
|
management.
|
|
</para>
|
|
|
|
<sect1>
|
|
<title>Features and Benefits</title>
|
|
|
|
<para>
|
|
SWAT is a facility that is part of the Samba suite. The main executable is called
|
|
<command>swat</command> and is invoked by the inter-networking super daemon.
|
|
See <link linkend="xinetd">appropriate section</link> for details.
|
|
</para>
|
|
|
|
<para>
|
|
SWAT uses integral samba components to locate parameters supported by the particular
|
|
version of Samba. Unlike tools and utilities that are external to Samba, SWAT is always
|
|
up to date as known Samba parameters change. SWAT provides context-sensitive help for each
|
|
configuration parameter, directly from <command>man</command> page entries.
|
|
</para>
|
|
|
|
<para>
|
|
There are network administrators who believe that it is a good idea to write systems
|
|
documentation inside configuration files, and for them SWAT will always be a nasty tool. SWAT
|
|
does not store the configuration file in any intermediate form, rather, it stores only the
|
|
parameter settings, so when SWAT writes the &smb.conf; file to disk, it will write only
|
|
those parameters that are at other than the default settings. The result is that all comments,
|
|
as well as parameters that are no longer supported, will be lost from the &smb.conf; file.
|
|
Additionally, the parameters will be written back in internal ordering.
|
|
</para>
|
|
|
|
<note><para>
|
|
Before using SWAT, please be warned &smbmdash; SWAT will completely replace your &smb.conf; with
|
|
a fully-optimized file that has been stripped of all comments you might have placed there
|
|
and only non-default settings will be written to the file.
|
|
</para></note>
|
|
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>Guidelines and Technical Tips</title>
|
|
|
|
<para>
|
|
This section aims to unlock the dark secrets behind how SWAT may be made to work,
|
|
may be made more secure, and how to solve Internationalization support problems.
|
|
</para>
|
|
|
|
<sect2>
|
|
<title>Validate SWAT Installation</title>
|
|
|
|
<para>
|
|
The very first step that should be taken before attempting to configure a host
|
|
system for SWAT operation is to check that it is installed. This may seem a trivial
|
|
point to some, however several Linux distributions do not install SWAT by default,
|
|
even though they do ship an install-able binary support package containing SWAT
|
|
on the distribution media.
|
|
</para>
|
|
|
|
<para>
|
|
When you have confirmed that SWAT is installed it is necessary to validate
|
|
that the installation includes the binary <command>swat</command> file as well
|
|
as all the supporting text and Web files. A number of operating system distributions
|
|
in the past have failed to include the necessary support files, even though the
|
|
<command>swat</command> binary executable file was installed.
|
|
</para>
|
|
|
|
<para>
|
|
Finally, when you are sure that SWAT has been fully installed, please check the SWAT
|
|
has been enabled in the control file for the inter-networking super-daemon (inetd or xinetd)
|
|
that is used on your operating system platform.
|
|
</para>
|
|
|
|
<sect3>
|
|
<title>Locating the <command>swat</command> File</title>
|
|
|
|
<para>
|
|
To validate that SWAT is installed, first locate the <command>swat</command> binary
|
|
file on the system. It may be found under the following directories:
|
|
<simplelist>
|
|
<member><filename>/usr/local/samba/bin</filename> &smbmdash; the default Samba location.</member>
|
|
<member><filename>/usr/sbin</filename> &smbmdash; the default location on most Linux systems.</member>
|
|
<member><filename>/opt/samba/bin</filename></member>
|
|
</simplelist>
|
|
</para>
|
|
|
|
<para>
|
|
The actual location is much dependant on the choice of the operating system vendor, or as determined
|
|
by the administrator who compiled and installed Samba.
|
|
</para>
|
|
|
|
<para>
|
|
There are a number methods that may be used to locate the <command>swat</command> binary file.
|
|
The following methods may be helpful:
|
|
</para>
|
|
|
|
<para>
|
|
If <command>swat</command> is in your current operating system search path it will be easy to
|
|
find it. You can ask what are the command-line options for <command>swat</command> as shown here:
|
|
<screen>
|
|
frodo:~ # swat -?
|
|
Usage: swat [OPTION...]
|
|
-a, --disable-authentication Disable authentication (demo mode)
|
|
|
|
Help options:
|
|
-?, --help Show this help message
|
|
--usage Display brief usage message
|
|
|
|
Common samba options:
|
|
-d, --debuglevel=DEBUGLEVEL Set debug level
|
|
-s, --configfile=CONFIGFILE Use alternative configuration file
|
|
-l, --log-basename=LOGFILEBASE Basename for log/debug files
|
|
-V, --version Print version
|
|
</screen>
|
|
</para>
|
|
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>Locating the SWAT Support Files</title>
|
|
|
|
<para>
|
|
Now that you have found that <command>swat</command> is in the search path, it is easy
|
|
to identify where the file is located. Here is another simple way this may be done:
|
|
<screen>
|
|
frodo:~ # whereis swat
|
|
swat: /usr/sbin/swat /usr/share/man/man8/swat.8.gz
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
If the above measures fail to locate the <command>swat</command> binary, another approach
|
|
is needed. The following may be used:
|
|
<screen>
|
|
frodo:/ # find / -name swat -print
|
|
/etc/xinetd.d/swat
|
|
/usr/sbin/swat
|
|
/usr/share/samba/swat
|
|
frodo:/ #
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
This list shows that there is a control file for <command>xinetd</command>, the internetwork
|
|
super-daemon that is installed on this server. The location of the SWAT binary file is
|
|
<filename>/usr/sbin/swat</filename>, and the support files for it are located under the
|
|
directory <filename>/usr/share/samba/swat</filename>.
|
|
</para>
|
|
|
|
<para>
|
|
We must now check where <command>swat</command> expects to find its support files. This can
|
|
be done as follows:
|
|
<screen>
|
|
frodo:/ # strings /usr/sbin/swat | grep "/swat"
|
|
/swat/
|
|
...
|
|
/usr/share/samba/swat
|
|
frodo:/ #
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
The <filename>/usr/share/samba/swat/</filename> entry shown in this listing is the location of the
|
|
support files. You should verify that the support files exist under this directory. A sample
|
|
list is as shown:
|
|
<screen>
|
|
jht@frodo:/> find /usr/share/samba/swat -print
|
|
/usr/share/samba/swat
|
|
/usr/share/samba/swat/help
|
|
/usr/share/samba/swat/lang
|
|
/usr/share/samba/swat/lang/ja
|
|
/usr/share/samba/swat/lang/ja/help
|
|
/usr/share/samba/swat/lang/ja/help/welcome.html
|
|
/usr/share/samba/swat/lang/ja/images
|
|
/usr/share/samba/swat/lang/ja/images/home.gif
|
|
...
|
|
/usr/share/samba/swat/lang/ja/include
|
|
/usr/share/samba/swat/lang/ja/include/header.nocss.html
|
|
...
|
|
/usr/share/samba/swat/lang/tr
|
|
/usr/share/samba/swat/lang/tr/help
|
|
/usr/share/samba/swat/lang/tr/help/welcome.html
|
|
/usr/share/samba/swat/lang/tr/images
|
|
/usr/share/samba/swat/lang/tr/images/home.gif
|
|
...
|
|
/usr/share/samba/swat/lang/tr/include
|
|
/usr/share/samba/swat/lang/tr/include/header.html
|
|
/usr/share/samba/swat/using_samba
|
|
...
|
|
/usr/share/samba/swat/images
|
|
/usr/share/samba/swat/images/home.gif
|
|
...
|
|
/usr/share/samba/swat/include
|
|
/usr/share/samba/swat/include/footer.html
|
|
/usr/share/samba/swat/include/header.html
|
|
jht@frodo:/>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
If the files needed are not available it will be necessary to obtain and install them
|
|
before SWAT can be used.
|
|
</para>
|
|
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2 id="xinetd">
|
|
<title>Enabling SWAT for Use</title>
|
|
|
|
<para>
|
|
SWAT should be installed to run via the network super-daemon. Depending on which system
|
|
your UNIX/Linux system has, you will have either an <command>inetd</command>- or
|
|
<command>xinetd</command>-based system.
|
|
</para>
|
|
|
|
<para>
|
|
The nature and location of the network super-daemon varies with the operating system
|
|
implementation. The control file (or files) can be located in the file
|
|
<filename>/etc/inetd.conf</filename> or in the directory <filename>/etc/[x]inet[d].d</filename>
|
|
or similar.
|
|
</para>
|
|
|
|
<para>
|
|
The control entry for the older style file might be:
|
|
<indexterm><primary>swat</primary><secondary>enable</secondary></indexterm>
|
|
</para>
|
|
|
|
|
|
<para><programlisting>
|
|
# swat is the Samba Web Administration Tool
|
|
swat stream tcp nowait.400 root /usr/sbin/swat swat
|
|
</programlisting></para>
|
|
|
|
<para>
|
|
A control file for the newer style xinetd could be:
|
|
</para>
|
|
|
|
<para>
|
|
<smbfile name="xinetd.swat">
|
|
<programlisting>
|
|
# default: off
|
|
# description: SWAT is the Samba Web Admin Tool. Use swat \
|
|
# to configure your Samba server. To use SWAT, \
|
|
# connect to port 901 with your favorite web browser.
|
|
service swat
|
|
{
|
|
port = 901
|
|
socket_type = stream
|
|
wait = no
|
|
only_from = localhost
|
|
user = root
|
|
server = /usr/sbin/swat
|
|
log_on_failure += USERID
|
|
disable = no
|
|
}
|
|
</programlisting>
|
|
</smbfile>
|
|
In the above, the default setting for <parameter>disable</parameter> is <constant>yes</constant>.
|
|
This means that SWAT is disabled. To enable use of SWAT, set this parameter to <constant>no</constant>
|
|
as shown.
|
|
</para>
|
|
|
|
<para>
|
|
Both of the above examples assume that the <command>swat</command> binary has been
|
|
located in the <filename>/usr/sbin</filename> directory. In addition to the above,
|
|
SWAT will use a directory access point from which it will load its Help files
|
|
as well as other control information. The default location for this on most Linux
|
|
systems is in the directory <filename>/usr/share/samba/swat</filename>. The default
|
|
location using Samba defaults will be <filename>/usr/local/samba/swat</filename>.
|
|
</para>
|
|
|
|
<para>
|
|
Access to SWAT will prompt for a logon. If you log onto SWAT as any non-root user,
|
|
the only permission allowed is to view certain aspects of configuration as well as
|
|
access to the password change facility. The buttons that will be exposed to the non-root
|
|
user are: <guibutton>HOME</guibutton>, <guibutton>STATUS</guibutton>, <guibutton>VIEW</guibutton>,
|
|
<guibutton>PASSWORD</guibutton>. The only page that allows
|
|
change capability in this case is <guibutton>PASSWORD</guibutton>.
|
|
</para>
|
|
|
|
<para>
|
|
As long as you log onto SWAT as the user <emphasis>root</emphasis>, you should obtain
|
|
full change and commit ability. The buttons that will be exposed include:
|
|
<guibutton>HOME</guibutton>, <guibutton>GLOBALS</guibutton>, <guibutton>SHARES</guibutton>, <guibutton>PRINTERS</guibutton>,
|
|
<guibutton>WIZARD</guibutton>, <guibutton>STATUS</guibutton>, <guibutton>VIEW</guibutton>, <guibutton>PASSWORD</guibutton>.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Securing SWAT through SSL</title>
|
|
|
|
|
|
<para>
|
|
<indexterm><primary>swat</primary><secondary>security</secondary></indexterm>
|
|
Many people have asked about how to setup SWAT with SSL to allow for secure remote
|
|
administration of Samba. Here is a method that works, courtesy of Markus Krieger.
|
|
</para>
|
|
|
|
<para>
|
|
Modifications to the SWAT setup are as follows:
|
|
</para>
|
|
|
|
<procedure>
|
|
<step><para>
|
|
Install OpenSSL.
|
|
</para></step>
|
|
|
|
<step><para>
|
|
Generate certificate and private key.
|
|
|
|
<screen>
|
|
&rootprompt;<userinput>/usr/bin/openssl req -new -x509 -days 365 -nodes -config \
|
|
/usr/share/doc/packages/stunnel/stunnel.cnf \
|
|
-out /etc/stunnel/stunnel.pem -keyout /etc/stunnel/stunnel.pem</userinput>
|
|
</screen></para></step>
|
|
|
|
<step><para>
|
|
Remove swat-entry from [x]inetd.
|
|
</para></step>
|
|
|
|
<step><para>
|
|
Start <command>stunnel</command>.
|
|
|
|
<screen>
|
|
&rootprompt;<userinput>stunnel -p /etc/stunnel/stunnel.pem -d 901 \
|
|
-l /usr/local/samba/bin/swat swat </userinput>
|
|
</screen></para></step>
|
|
</procedure>
|
|
|
|
<para>
|
|
Afterward, simply connect to swat by using the URL <ulink noescape="1" url="https://myhost:901">https://myhost:901</ulink>, accept the certificate
|
|
and the SSL connection is up.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Enabling SWAT Internationalization Support</title>
|
|
|
|
<para>
|
|
SWAT can be configured to display its messages to match the settings of
|
|
the language configurations of your Web browser. It will be passed to SWAT
|
|
in the Accept-Language header of the HTTP request.
|
|
</para>
|
|
|
|
<para>
|
|
To enable this feature:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
Install the proper <command>msg</command> files from the Samba
|
|
<filename>source/po</filename> directory into $LIBDIR.
|
|
</para></listitem>
|
|
|
|
<listitem><para>
|
|
Set your browsers language setting.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
The name of msg file is same as the language ID sent by the browser. For
|
|
example en means "English", ja means "Japanese", fr means "French.
|
|
</para>
|
|
|
|
<para>
|
|
If you do not like some of messages, or there are no <command>msg</command> files for
|
|
your locale, you can create them simply by copying the <command>en.msg</command> files
|
|
to the directory for <quote>your language ID.msg</quote> and filling in proper strings
|
|
to each <quote>msgstr</quote>. For example, in <filename>it.msg</filename>, the
|
|
<command>msg</command> file for the Italian locale, just set:
|
|
<screen>
|
|
msgid "Set Default"
|
|
msgstr "Imposta Default"
|
|
</screen>
|
|
and so on. If you find a mistake or create a new <command>msg</command> file, please email it
|
|
to us so we will include this in the next release of Samba. The <command>msg</command> file should be encoded in UTF-8.
|
|
</para>
|
|
|
|
<para>
|
|
Note that if you enable this feature and the <smbconfoption name="display charset"/> is not
|
|
matched to your browsers setting, the SWAT display may be corrupted. In a future version of
|
|
Samba, SWAT will always display messages with UTF-8 encoding. You will then not need to set
|
|
this &smb.conf; file parameter.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>Overview and Quick Tour</title>
|
|
|
|
<para>
|
|
SWAT is a tools that many be used to configure Samba, or just to obtain useful links
|
|
to important reference materials such as the contents of this book, as well as other
|
|
documents that have been found useful for solving Windows networking problems.
|
|
</para>
|
|
|
|
<sect2>
|
|
<title>The SWAT Home Page</title>
|
|
|
|
<para>
|
|
The SWAT title page provides access to the latest Samba documentation. The manual page for
|
|
each Samba component is accessible from this page, as are the Samba HOWTO-Collection (this
|
|
document) as well as the O'Reilly book <quote>Using Samba.</quote>
|
|
</para>
|
|
|
|
<para>
|
|
Administrators who wish to validate their Samba configuration may obtain useful information
|
|
from the man pages for the diagnostic utilities. These are available from the SWAT home page
|
|
also. One diagnostic tool that is not mentioned on this page, but that is particularly
|
|
useful is <ulink url="http://www.ethereal.com/"><command>ethereal</command>.</ulink>
|
|
</para>
|
|
|
|
<warning><para>
|
|
SWAT can be configured to run in <emphasis>demo</emphasis> mode. This is not recommended
|
|
as it runs SWAT without authentication and with full administrative ability. Allows
|
|
changes to &smb.conf; as well as general operation with root privileges. The option that
|
|
creates this ability is the <option>-a</option> flag to swat. <emphasis>Do not use this in a
|
|
production environment.</emphasis>
|
|
</para></warning>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Global Settings</title>
|
|
|
|
<para>
|
|
The <guibutton>GLOBALS</guibutton> button will expose a page that allows configuration of the global parameters
|
|
in &smb.conf;. There are two levels of exposure of the parameters:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<guibutton>Basic</guibutton> &smbmdash; exposes common configuration options.
|
|
</para></listitem>
|
|
|
|
<listitem><para>
|
|
<guibutton>Advanced</guibutton> &smbmdash; exposes configuration options needed in more
|
|
complex environments.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
To switch to other than <guibutton>Basic</guibutton> editing ability, click on <guibutton>Advanced</guibutton>.
|
|
You may also do this by clicking on the radio button, then click on the <guibutton>Commit Changes</guibutton> button.
|
|
</para>
|
|
|
|
<para>
|
|
After making any changes to configuration parameters, make sure that
|
|
you click on the
|
|
<guibutton>Commit Changes</guibutton> button before moving to another area, otherwise
|
|
your changes will be lost.
|
|
</para>
|
|
|
|
<note><para>
|
|
SWAT has context-sensitive help. To find out what each parameter is
|
|
for, simply click on the
|
|
<guibutton>Help</guibutton> link to the left of the configuration parameter.
|
|
</para></note>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Share Settings</title>
|
|
|
|
<para>
|
|
To effect a currently configured share, simply click on the pull down button between the
|
|
<guibutton>Choose Share</guibutton> and the <guibutton>Delete Share</guibutton> buttons,
|
|
select the share you wish to operate on, then to edit the settings
|
|
click on the
|
|
<guibutton>Choose Share</guibutton> button. To delete the share, simply press the
|
|
<guibutton>Delete Share</guibutton> button.
|
|
</para>
|
|
|
|
<para>
|
|
To create a new share, next to the button labeled <guibutton>Create Share</guibutton> enter
|
|
into the text field the name of the share to be created, then click on the
|
|
<guibutton>Create Share</guibutton> button.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Printers Settings</title>
|
|
|
|
<para>
|
|
To affect a currently configured printer, simply click on the pull down button between the
|
|
<guibutton>Choose Printer</guibutton> and the <guibutton>Delete Printer</guibutton> buttons,
|
|
select the printer you wish to operate on, then to edit the settings
|
|
click on the
|
|
<guibutton>Choose Printer</guibutton> button. To delete the share, simply press the
|
|
<guibutton>Delete Printer</guibutton> button.
|
|
</para>
|
|
|
|
<para>
|
|
To create a new printer, next to the button labeled <guibutton>Create Printer</guibutton> enter
|
|
into the text field the name of the share to be created, then click on the
|
|
<guibutton>Create Printer</guibutton> button.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>The SWAT Wizard</title>
|
|
|
|
<para>
|
|
The purpose if the SWAT Wizard is to help the Microsoft-knowledgeable network administrator
|
|
to configure Samba with a minimum of effort.
|
|
</para>
|
|
|
|
<para>
|
|
The Wizard page provides a tool for rewriting the &smb.conf; file in fully optimized format.
|
|
This will also happen if you press the <guibutton>Commit</guibutton> button. The two differ
|
|
since the <guibutton>Rewrite</guibutton> button ignores any changes that may have been made,
|
|
while the <guibutton>Commit</guibutton> button causes all changes to be affected.
|
|
</para>
|
|
|
|
<para>
|
|
The <guibutton>Edit</guibutton> button permits the editing (setting) of the minimal set of
|
|
options that may be necessary to create a working Samba server.
|
|
</para>
|
|
|
|
<para>
|
|
Finally, there are a limited set of options that will determine what type of server Samba
|
|
will be configured for, whether it will be a WINS server, participate as a WINS client, or
|
|
operate with no WINS support. By clicking one button, you can elect to expose (or not) user
|
|
home directories.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>The Status Page</title>
|
|
|
|
<para>
|
|
The status page serves a limited purpose. First, it allows control of the Samba daemons.
|
|
The key daemons that create the Samba server environment are: &smbd;, &nmbd;, &winbindd;.
|
|
</para>
|
|
|
|
<para>
|
|
The daemons may be controlled individually or as a total group. Additionally, you may set
|
|
an automatic screen refresh timing. As MS Windows clients interact with Samba, new smbd processes
|
|
will be continually spawned. The auto-refresh facility will allow you to track the changing
|
|
conditions with minimal effort.
|
|
</para>
|
|
|
|
<para>
|
|
Lastly, the Status page may be used to terminate specific smbd client connections in order to
|
|
free files that may be locked.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>The View Page</title>
|
|
|
|
<para>
|
|
This page allows the administrator to view the optimized &smb.conf; file and, if you are
|
|
particularly masochistic, will permit you also to see all possible global configuration
|
|
parameters and their settings.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>The Password Change Page</title>
|
|
|
|
<para>
|
|
The Password Change page is a popular tool that allows the creation, deletion, deactivation,
|
|
and reactivation of MS Windows networking users on the local machine. Alternately, you can use
|
|
this tool to change a local password for a user account.
|
|
</para>
|
|
|
|
<para>
|
|
When logged in as a non-root account, the user will have to provide the old password as well as
|
|
the new password (twice). When logged in as <emphasis>root</emphasis>, only the new password is
|
|
required.
|
|
</para>
|
|
|
|
<para>
|
|
One popular use for this tool is to change user passwords across a range of remote MS Windows
|
|
servers.
|
|
</para>
|
|
|
|
</sect2>
|
|
</sect1>
|
|
|
|
</chapter>
|