diff options
Diffstat (limited to 'docs/docbook/projdoc/SWAT.xml')
| -rw-r--r-- | docs/docbook/projdoc/SWAT.xml | 603 |
1 files changed, 603 insertions, 0 deletions
diff --git a/docs/docbook/projdoc/SWAT.xml b/docs/docbook/projdoc/SWAT.xml new file mode 100644 index 0000000000..e25b6470b5 --- /dev/null +++ b/docs/docbook/projdoc/SWAT.xml @@ -0,0 +1,603 @@ +<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"/> 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 aways 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 installable binary support package containing SWAT +on the distribution media. +</para> + +<para> +When you have configrmed 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, evne 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 enebled in the control file for the internetworking 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> +<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 = yes +} +</programlisting> + +</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 the correct locale value for <smbconfoption><name>display charset</name></smbconfoption>. + </para></listitem> + + <listitem><para> + Set your browser's 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 dirertory 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. +</para> + +<para> +Note that if you enable this feature and the <smbconfoption><name>display charset</name></smbconfoption> is not +matched to your browser's 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> |