Docbook XML conversion: projdoc

(This used to be commit f7c9df751459da2d4a996d5f0135334fb3f87f69)

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>