Added swat html & manpage.

Jeremy.
(This used to be commit cce693135e146c9f4c9243f3dcb5091c46d1fcdb)

1 files changed, 210 insertions, 0 deletions

diff --git a/docs/manpages/swat.8 b/docs/manpages/swat.8
new file mode 100644
index 0000000000..36b4de140a
--- /dev/null
+++ b/docs/manpages/swat.8
@@ -0,0 +1,210 @@
+.TH "swat" "8" "23 Oct 1998" "Samba" "SAMBA" 
+.PP 
+.SH "NAME" 
+swat \- swat - Samba Web Administration Tool
+.PP 
+.SH "SYNOPSIS" 
+.PP 
+\fBswat\fP [-s smb config file] [-a]
+.PP 
+.SH "DESCRIPTION" 
+.PP 
+This program is part of the \fBSamba\fP suite\&.
+.PP 
+\fBswat\fP allows a Samba administrator to configure the complex
+\fBsmb\&.conf\fP file via a Web browser\&. In
+addition, a swat configuration page has help links to all the
+configurable options in the \fBsmb\&.conf\fP file
+allowing an administrator to easily look up the effects of any change\&.
+.PP 
+\fBswat\fP can be run as a stand-alone daemon, from \fBinetd\fP,
+or invoked via CGI from a Web server\&.
+.PP 
+.SH "OPTIONS" 
+.PP 
+.IP 
+.IP "\fB-s smb configuration file\fP" 
+The default configuration file path is
+determined at compile time\&.
+.IP 
+The file specified contains the configuration details required by the
+\fBsmbd\fP server\&. This is the file that \fBswat\fP will
+modify\&. The information in this file includes server-specific
+information such as what printcap file to use, as well as descriptions
+of all the services that the server is to provide\&. See smb\&.conf
+(5) for more information\&.
+.IP 
+.IP "\fB-a\fP" 
+.IP 
+This option is only used if \fBswat\fP is running as it\'s own mini-web
+server (see the \fBINSTALLATION\fP section below)\&.
+.IP 
+This option removes the need for authentication needed to modify the
+\fBsmb\&.conf\fP file\&. \fI**THIS IS ONLY MEANT FOR
+DEMOING SWAT AND MUST NOT BE SET IN NORMAL SYSTEMS**\fP as it would
+allow \fI*ANYONE*\fP to modify the \fBsmb\&.conf\fP
+file, thus giving them root access\&.
+.IP 
+.PP 
+.SH "INSTALLATION" 
+.PP 
+After you compile SWAT you need to run \f(CW"make install"\fP to install the
+swat binary and the various help files and images\&. A default install
+would put these in:
+.PP 
+
+.DS 
+ 
+
+/usr/local/samba/bin/swat
+/usr/local/samba/swat/images/*
+/usr/local/samba/swat/help/*
+
+.DE 
+ 
+
+.PP 
+.SH "RUNNING VIA INETD" 
+.PP 
+You need to edit your \f(CW/etc/inetd\&.conf\fP and \f(CW/etc/services\fP to
+enable \fBSWAT\fP to be launched via inetd\&. Note that \fBswat\fP can also
+be launched via the cgi-bin mechanisms of a web server (such as
+apache) and that is described below in the section \fBRUNNING VIA
+CGI-BIN\fP\&.
+.PP 
+In \f(CW/etc/services\fP you need to add a line like this:
+.PP 
+\f(CWswat            901/tcp\fP
+.PP 
+Note for NIS/YP users - you may need to rebuild the NIS service maps
+rather than alter your local \f(CW/etc/services\fP file\&.
+.PP 
+the choice of port number isn\'t really important except that it should
+be less than 1024 and not currently used (using a number above 1024
+presents an obscure security hole depending on the implementation
+details of your \fBinetd\fP daemon)\&.
+.PP 
+In \f(CW/etc/inetd\&.conf\fP you should add a line like this:
+.PP 
+\f(CWswat    stream  tcp     nowait\&.400  root    /usr/local/samba/bin/swat swat\fP
+.PP 
+If you just want to see a demo of how swat works and don\'t want to be
+able to actually change any Samba config via swat then you may chose
+to change \f(CW"root"\fP to some other user that does not have permission
+to write to \fBsmb\&.conf\fP\&.
+.PP 
+One you have edited \f(CW/etc/services\fP and \f(CW/etc/inetd\&.conf\fP you need
+to send a HUP signal to inetd\&. To do this use \f(CW"kill -1 PID"\fP where
+PID is the process ID of the inetd daemon\&.
+.PP 
+.SH "RUNNING VIA CGI-BIN" 
+.PP 
+To run \fBswat\fP via your web servers cgi-bin capability you need to
+copy the \fBswat\fP binary to your cgi-bin directory\&. Note that you
+should run \fBswat\fP either via \fBinetd\fP or via
+cgi-bin but not both\&.
+.PP 
+Then you need to create a \f(CWswat/\fP directory in your web servers root
+directory and copy the \f(CWimages/*\fP and \f(CWhelp/*\fP files found in the
+\f(CWswat/\fP directory of your Samba source distribution into there so
+that they are visible via the URL \f(CWhttp://your\&.web\&.server/swat/\fP
+.PP 
+Next you need to make sure you modify your web servers authentication
+to require a username/pssword for the URL
+\f(CWhttp://your\&.web\&.server/cgi-bin/swat\fP\&. \fI**Don\'t forget this
+step!**\fP If you do forget it then you will be allowing anyone to edit
+your Samba configuration which would allow them to easily gain root
+access on your machine\&.
+.PP 
+After testing the authentication you need to change the ownership and
+permissions on the \fBswat\fP binary\&. It should be owned by root wth the
+setuid bit set\&. It should be ONLY executable by the user that the web
+server runs as\&. Make sure you do this carefully!
+.PP 
+for example, the following would be correct if the web server ran as
+group \f(CW"nobody"\fP\&.
+.PP 
+\f(CW-rws--x---    1 root     nobody    \fP
+.PP 
+You must also realise that this means that any user who can run
+programs as the \f(CW"nobody"\fP group can run \fBswat\fP and modify your
+Samba config\&. Be sure to think about this!
+.PP 
+.SH "LAUNCHING" 
+.PP 
+To launch \fBswat\fP just run your favourite web browser and point it at
+\f(CWhttp://localhost:901/\fP or \f(CWhttp://localhost/cgi-bin/swat/\fP
+depending on how you installed it\&.
+.PP 
+Note that you can attach to \fBswat\fP from any IP connected machine but
+connecting from a remote machine leaves your connection open to
+password sniffing as passwords will be sent in the clear over the
+wire\&.
+.PP 
+If installed via \fBinetd\fP then you should be prompted for a
+username/password when you connect\&. You will need to provide the
+username \f(CW"root"\fP and the correct root password\&. More sophisticated
+authentication options are planned for future versions of \fBswat\fP\&.
+.PP 
+If installed via cgi-bin then you should receive whatever
+authentication request you configured in your web server\&.
+.PP 
+.SH "FILES" 
+.PP 
+\fB/etc/inetd\&.conf\fP
+.PP 
+If the server is to be run by the inetd meta-daemon, this file must
+contain suitable startup information for the meta-daemon\&. See the
+section \fBRUNNING VIA INETD\fP above\&.
+.PP 
+\fB/etc/services\fP
+.PP 
+If running the server via the meta-daemon inetd, this file must
+contain a mapping of service name (eg\&., swat) to service port
+(eg\&., 901) and protocol type (eg\&., tcp)\&. See the section
+\fBRUNNING VIA INETD\fP above\&.
+.PP 
+\fB/usr/local/samba/lib/smb\&.conf\fP
+.PP 
+This is the default location of the \fIsmb\&.conf\fP server configuration
+file that \fBswat\fP edits\&. Other common places that systems install
+this file are \fI/usr/samba/lib/smb\&.conf\fP and \fI/etc/smb\&.conf\fP\&.
+.PP 
+This file describes all the services the server is to make available
+to clients\&. See \fBsmb\&.conf (5)\fP for more information\&.
+.PP 
+.SH "WARNINGS" 
+.PP 
+\fBswat\fP will rewrite your \fBsmb\&.conf\fP file\&. It
+will rearrange the entries and delete all comments,
+\fB"include="\fP and
+\fB"copy="\fP options\&. If you have a
+carefully crafted \fBsmb\&.conf\fP then back it up
+or don\'t use \fBswat\fP!
+.PP 
+.SH "VERSION" 
+.PP 
+This man page is correct for version 2\&.0 of the Samba suite\&.
+.PP 
+.SH "SEE ALSO" 
+.PP 
+\fBinetd (8)\fP, \fBnmbd (8)\fP,
+\fBsmb\&.conf (5)\fP\&.
+.PP 
+.SH "AUTHOR" 
+.PP 
+The original Samba software and related utilities were created by
+Andrew Tridgell (samba-bugs@samba\&.anu\&.edu\&.au)\&. Samba is now developed
+by the Samba Team as an Open Source project similar to the way the
+Linux kernel is developed\&.
+.PP 
+The original Samba man pages were written by Karl Auer\&. The man page
+sources were converted to YODL format (another excellent piece of Open
+Source software, available at
+\fBftp://ftp\&.icce\&.rug\&.nl/pub/unix/\fP)
+and updated for the Samba2\&.0 release by Jeremy Allison\&.
+\fIsamba-bugs@samba\&.anu\&.edu\&.au\fP\&.
+.PP 
+See \fBsamba (7)\fP to find out how to get a full
+list of contributors and details on how to submit bug reports,
+comments etc\&.