diff options
Diffstat (limited to 'docs/docbook/projdoc/SWAT.xml')
| -rw-r--r-- | docs/docbook/projdoc/SWAT.xml | 351 |
1 files changed, 351 insertions, 0 deletions
diff --git a/docs/docbook/projdoc/SWAT.xml b/docs/docbook/projdoc/SWAT.xml new file mode 100644 index 0000000000..f238e8e1b0 --- /dev/null +++ b/docs/docbook/projdoc/SWAT.xml @@ -0,0 +1,351 @@ +<chapter id="SWAT"> +<chapterinfo> + &author.jht; + <pubdate>April 21, 2003</pubdate> +</chapterinfo> + +<title>SWAT - The Samba Web Admininistration Tool</title> + +<para> +There are many and varied opinions regarding the usefulness or otherwise 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>SWAT Features and Benefits</title> + +<para> +There are network administrators who believe that it is a good idea to write systems +documentation inside configuration files, 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 +will be lost from the smb.conf file. Additionally, the parameters will be written back in +internal ordering. +</para> + +<note><para> +So before using SWAT please be warned - SWAT will completely replace your smb.conf with +a fully optimised 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> + +<sect2> +<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 <filename>inetd</filename> or +<filename>xinetd</filename> 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</filename> +or similar. +</para> + +<para> +The control entry for the older style file might be: +</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 the above examples assume that the <filename>swat</filename> 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 it's 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: <emphasis>HOME, STATUS, VIEW, PASSWORD</emphasis>. The only page that allows +change capability in this case is <emphasis>PASSWORD</emphasis>. +</para> + +<para> +So long as you log onto SWAT as the user <command>root</command> you should obtain +full change and commit ability. The buttons that will be exposed includes: +<emphasis>HOME, GLOBALS, SHARES, PRINTERS, WIZARD, STATUS, VIEW, PASSWORD</emphasis>. +</para> + +</sect2> + +<sect2> +<title>Securing SWAT through SSL</title> + +<para> +Lots of 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 following: +</para> + +<itemizedlist> + <listitem><para> + install OpenSSL + </para></listitem> + + <listitem><para> + generate certificate and private key + + <programlisting> + root# /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 + </programlisting></para></listitem> + + <listitem><para> + remove swat-entry from [x]inetd + </para></listitem> + + <listitem><para> + start stunnel + + <programlisting> + root# stunnel -p /etc/stunnel/stunnel.pem -d 901 \ + -l /usr/local/samba/bin/swat swat + </programlisting></para></listitem> +</itemizedlist> + +<para> +afterwards simply contact to swat by using the URL "https://myhost:901", accept the certificate +and the SSL connection is up. +</para> + +</sect2> + +<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 "Using Samba". +</para> + +<para> +Administrators who wish to validate their samba configuration may obtain useful information +from the man pages for the diganostic 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 <command>ethereal</command>, available from <ulink url="http://www.ethereal.com"> +http://www.ethereal.com</ulink>. +</para> + +<note><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. ie: Allows +changes to smb.conf as well as general operation with root privilidges. The option that +creates this ability is the <command>-a</command> flag to swat. DO NOT USE THIS IN ANY +PRODUCTION ENVIRONMENT - you have been warned! +</para></note> + +</sect2> + +<sect2> +<title>Global Settings</title> + +<para> +The Globals button will expose a page that allows configuration of the global parameters +in smb.conf. There are three levels of exposure of the parameters: +</para> + +<itemizedlist> + <listitem><para> + <command>Basic</command> - exposes common configuration options. + </para></listitem> + + <listitem><para> + <command>Advanced</command> - exposes configuration options needed in more + complex environments. + </para></listitem> + + <listitem><para> + <command>Developer</command> - exposes configuration options that only the brave + will want to tamper with. + </para></listitem> +</itemizedlist> + +<para> +To switch to other than <emphasis>Basic</emphasis> editing ability click on either the +<emphasis>Advanced</emphasis> or the <emphasis>Developer</emphasis> dial, then click the +<emphasis>Commit Changes</emphasis> button. +</para> + +<para> +After making any changes to configuration parameters make sure that you click on the +<emphasis>Commit Changes</emphasis> button before moving to another area otherwise +your changes will be immediately lost. +</para> + +<note><para> +SWAT has context sensitive help. To find out what each parameter is for simply click the +<command>Help</command> link to the left of the configurartion parameter. +</para></note> + +</sect2> + +<sect2> +<title>Share Settings</title> + +<para> +To affect a currenly configured share, simply click on the pull down button between the +<emphasis>Choose Share</emphasis> and the <emphasis>Delete Share</emphasis> buttons, +select the share you wish to operate on, then to edit the settings click on the +<emphasis>Choose Share</emphasis> button, to delete the share simply press the +<emphasis>Delete Share</emphasis> button. +</para> + +<para> +To create a new share, next to the button labelled <emphasis>Create Share</emphasis> enter +into the text field the name of the share to be created, then click on the +<emphasis>Create Share</emphasis> button. +</para> + +</sect2> + +<sect2> +<title>Printers Settings</title> + +<para> +To affect a currenly configured printer, simply click on the pull down button between the +<emphasis>Choose Printer</emphasis> and the <emphasis>Delete Printer</emphasis> buttons, +select the printer you wish to operate on, then to edit the settings click on the +<emphasis>Choose Printer</emphasis> button, to delete the share simply press the +<emphasis>Delete Printer</emphasis> button. +</para> + +<para> +To create a new printer, next to the button labelled <emphasis>Create Printer</emphasis> enter +into the text field the name of the share to be created, then click on the +<emphasis>Create Printer</emphasis> button. +</para> + +</sect2> + +<sect2> +<title>The SWAT Wizard</title> + +<para> +The purpose if the SWAT Wizard is to help the Microsoft knowledgable network administrator +to configure Samba with a minimum of effort. +</para> + +<para> +The Wizard page provides a tool for rewiting the smb.conf file in fully optimised format. +This will also happen if you press the commit button. The two differ in the the rewrite button +ignores any changes that may have been made, while the Commit button causes all changes to be +affected. +</para> + +<para> +The <emphasis>Edit</emphasis> 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 on one button you can elect to epose (or not) user +home directories. +</para> + +</sect2> + +<sect2> +<title>The Status Page</title> + +<para> +The status page serves a limited purpose. Firstly, it allows control of the samba daemons. +The key daemons that create the samba server environment are: <command> smbd, nmbd, winbindd</command>. +</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 optimised smb.conf file and if you are +particularly massochistic 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. This tool allows the creation, deletion, deactivation +and reactivation of MS Windows networking users on the local machine. Alternatively, 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 <command>root</command> 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> |