Added swat html & manpage.
[kai/samba.git] / docs / manpages / swat.8
1 .TH "swat" "8" "23 Oct 1998" "Samba" "SAMBA" 
2 .PP 
3 .SH "NAME" 
4 swat \- swat - Samba Web Administration Tool
5 .PP 
6 .SH "SYNOPSIS" 
7 .PP 
8 \fBswat\fP [-s smb config file] [-a]
9 .PP 
10 .SH "DESCRIPTION" 
11 .PP 
12 This program is part of the \fBSamba\fP suite\&.
13 .PP 
14 \fBswat\fP allows a Samba administrator to configure the complex
15 \fBsmb\&.conf\fP file via a Web browser\&. In
16 addition, a swat configuration page has help links to all the
17 configurable options in the \fBsmb\&.conf\fP file
18 allowing an administrator to easily look up the effects of any change\&.
19 .PP 
20 \fBswat\fP can be run as a stand-alone daemon, from \fBinetd\fP,
21 or invoked via CGI from a Web server\&.
22 .PP 
23 .SH "OPTIONS" 
24 .PP 
25 .IP 
26 .IP "\fB-s smb configuration file\fP" 
27 The default configuration file path is
28 determined at compile time\&.
29 .IP 
30 The file specified contains the configuration details required by the
31 \fBsmbd\fP server\&. This is the file that \fBswat\fP will
32 modify\&. The information in this file includes server-specific
33 information such as what printcap file to use, as well as descriptions
34 of all the services that the server is to provide\&. See smb\&.conf
35 (5) for more information\&.
36 .IP 
37 .IP "\fB-a\fP" 
38 .IP 
39 This option is only used if \fBswat\fP is running as it\'s own mini-web
40 server (see the \fBINSTALLATION\fP section below)\&.
41 .IP 
42 This option removes the need for authentication needed to modify the
43 \fBsmb\&.conf\fP file\&. \fI**THIS IS ONLY MEANT FOR
44 DEMOING SWAT AND MUST NOT BE SET IN NORMAL SYSTEMS**\fP as it would
45 allow \fI*ANYONE*\fP to modify the \fBsmb\&.conf\fP
46 file, thus giving them root access\&.
47 .IP 
48 .PP 
49 .SH "INSTALLATION" 
50 .PP 
51 After you compile SWAT you need to run \f(CW"make install"\fP to install the
52 swat binary and the various help files and images\&. A default install
53 would put these in:
54 .PP 
55
56 .DS 
57  
58
59 /usr/local/samba/bin/swat
60 /usr/local/samba/swat/images/*
61 /usr/local/samba/swat/help/*
62
63 .DE 
64  
65
66 .PP 
67 .SH "RUNNING VIA INETD" 
68 .PP 
69 You need to edit your \f(CW/etc/inetd\&.conf\fP and \f(CW/etc/services\fP to
70 enable \fBSWAT\fP to be launched via inetd\&. Note that \fBswat\fP can also
71 be launched via the cgi-bin mechanisms of a web server (such as
72 apache) and that is described below in the section \fBRUNNING VIA
73 CGI-BIN\fP\&.
74 .PP 
75 In \f(CW/etc/services\fP you need to add a line like this:
76 .PP 
77 \f(CWswat            901/tcp\fP
78 .PP 
79 Note for NIS/YP users - you may need to rebuild the NIS service maps
80 rather than alter your local \f(CW/etc/services\fP file\&.
81 .PP 
82 the choice of port number isn\'t really important except that it should
83 be less than 1024 and not currently used (using a number above 1024
84 presents an obscure security hole depending on the implementation
85 details of your \fBinetd\fP daemon)\&.
86 .PP 
87 In \f(CW/etc/inetd\&.conf\fP you should add a line like this:
88 .PP 
89 \f(CWswat    stream  tcp     nowait\&.400  root    /usr/local/samba/bin/swat swat\fP
90 .PP 
91 If you just want to see a demo of how swat works and don\'t want to be
92 able to actually change any Samba config via swat then you may chose
93 to change \f(CW"root"\fP to some other user that does not have permission
94 to write to \fBsmb\&.conf\fP\&.
95 .PP 
96 One you have edited \f(CW/etc/services\fP and \f(CW/etc/inetd\&.conf\fP you need
97 to send a HUP signal to inetd\&. To do this use \f(CW"kill -1 PID"\fP where
98 PID is the process ID of the inetd daemon\&.
99 .PP 
100 .SH "RUNNING VIA CGI-BIN" 
101 .PP 
102 To run \fBswat\fP via your web servers cgi-bin capability you need to
103 copy the \fBswat\fP binary to your cgi-bin directory\&. Note that you
104 should run \fBswat\fP either via \fBinetd\fP or via
105 cgi-bin but not both\&.
106 .PP 
107 Then you need to create a \f(CWswat/\fP directory in your web servers root
108 directory and copy the \f(CWimages/*\fP and \f(CWhelp/*\fP files found in the
109 \f(CWswat/\fP directory of your Samba source distribution into there so
110 that they are visible via the URL \f(CWhttp://your\&.web\&.server/swat/\fP
111 .PP 
112 Next you need to make sure you modify your web servers authentication
113 to require a username/pssword for the URL
114 \f(CWhttp://your\&.web\&.server/cgi-bin/swat\fP\&. \fI**Don\'t forget this
115 step!**\fP If you do forget it then you will be allowing anyone to edit
116 your Samba configuration which would allow them to easily gain root
117 access on your machine\&.
118 .PP 
119 After testing the authentication you need to change the ownership and
120 permissions on the \fBswat\fP binary\&. It should be owned by root wth the
121 setuid bit set\&. It should be ONLY executable by the user that the web
122 server runs as\&. Make sure you do this carefully!
123 .PP 
124 for example, the following would be correct if the web server ran as
125 group \f(CW"nobody"\fP\&.
126 .PP 
127 \f(CW-rws--x---    1 root     nobody    \fP
128 .PP 
129 You must also realise that this means that any user who can run
130 programs as the \f(CW"nobody"\fP group can run \fBswat\fP and modify your
131 Samba config\&. Be sure to think about this!
132 .PP 
133 .SH "LAUNCHING" 
134 .PP 
135 To launch \fBswat\fP just run your favourite web browser and point it at
136 \f(CWhttp://localhost:901/\fP or \f(CWhttp://localhost/cgi-bin/swat/\fP
137 depending on how you installed it\&.
138 .PP 
139 Note that you can attach to \fBswat\fP from any IP connected machine but
140 connecting from a remote machine leaves your connection open to
141 password sniffing as passwords will be sent in the clear over the
142 wire\&.
143 .PP 
144 If installed via \fBinetd\fP then you should be prompted for a
145 username/password when you connect\&. You will need to provide the
146 username \f(CW"root"\fP and the correct root password\&. More sophisticated
147 authentication options are planned for future versions of \fBswat\fP\&.
148 .PP 
149 If installed via cgi-bin then you should receive whatever
150 authentication request you configured in your web server\&.
151 .PP 
152 .SH "FILES" 
153 .PP 
154 \fB/etc/inetd\&.conf\fP
155 .PP 
156 If the server is to be run by the inetd meta-daemon, this file must
157 contain suitable startup information for the meta-daemon\&. See the
158 section \fBRUNNING VIA INETD\fP above\&.
159 .PP 
160 \fB/etc/services\fP
161 .PP 
162 If running the server via the meta-daemon inetd, this file must
163 contain a mapping of service name (eg\&., swat) to service port
164 (eg\&., 901) and protocol type (eg\&., tcp)\&. See the section
165 \fBRUNNING VIA INETD\fP above\&.
166 .PP 
167 \fB/usr/local/samba/lib/smb\&.conf\fP
168 .PP 
169 This is the default location of the \fIsmb\&.conf\fP server configuration
170 file that \fBswat\fP edits\&. Other common places that systems install
171 this file are \fI/usr/samba/lib/smb\&.conf\fP and \fI/etc/smb\&.conf\fP\&.
172 .PP 
173 This file describes all the services the server is to make available
174 to clients\&. See \fBsmb\&.conf (5)\fP for more information\&.
175 .PP 
176 .SH "WARNINGS" 
177 .PP 
178 \fBswat\fP will rewrite your \fBsmb\&.conf\fP file\&. It
179 will rearrange the entries and delete all comments,
180 \fB"include="\fP and
181 \fB"copy="\fP options\&. If you have a
182 carefully crafted \fBsmb\&.conf\fP then back it up
183 or don\'t use \fBswat\fP!
184 .PP 
185 .SH "VERSION" 
186 .PP 
187 This man page is correct for version 2\&.0 of the Samba suite\&.
188 .PP 
189 .SH "SEE ALSO" 
190 .PP 
191 \fBinetd (8)\fP, \fBnmbd (8)\fP,
192 \fBsmb\&.conf (5)\fP\&.
193 .PP 
194 .SH "AUTHOR" 
195 .PP 
196 The original Samba software and related utilities were created by
197 Andrew Tridgell (samba-bugs@samba\&.anu\&.edu\&.au)\&. Samba is now developed
198 by the Samba Team as an Open Source project similar to the way the
199 Linux kernel is developed\&.
200 .PP 
201 The original Samba man pages were written by Karl Auer\&. The man page
202 sources were converted to YODL format (another excellent piece of Open
203 Source software, available at
204 \fBftp://ftp\&.icce\&.rug\&.nl/pub/unix/\fP)
205 and updated for the Samba2\&.0 release by Jeremy Allison\&.
206 \fIsamba-bugs@samba\&.anu\&.edu\&.au\fP\&.
207 .PP 
208 See \fBsamba (7)\fP to find out how to get a full
209 list of contributors and details on how to submit bug reports,
210 comments etc\&.