Getting ready for first Red Hat Linux RPMs for 1.9.19 pre-alpha release
[kai/samba.git] / swat / README
1 This is a brief description of how to install and use the Samba Web
2 Administration Tool on your machine.
3
4 Please note that SWAT is still being developed so you should not
5 expect it to be bug free. You should only install and use it if you
6 want to either get a preview of what we are doing with SWAT or you
7 want to help in the development of SWAT.
8
9 Installation
10 ------------
11
12 After you compile SWAT you need to run "make install" to install the
13 swat binary and the various help files and images. A default install
14 would put these in:
15
16 /usr/local/samba/bin/swat
17 /usr/local/samba/swat/images/*
18 /usr/local/samba/swat/help/*
19
20 Running via inetd
21 -----------------
22
23 You then need to edit your /etc/inetd.conf and /etc/services to enable
24 SWAT to be launched via inetd. Note that SWAT can also be launched via
25 the cgi-bin mechanisms of a web server (such as apache) and that is
26 described below.
27
28 In /etc/services you need to add a line like this:
29
30 swat            901/tcp
31
32 the choice of port number isn't really important except that it should
33 be less than 1024 and not currently used (using a number above 1024
34 presents an obscure security hole depending on the implementation
35 details of your inetd daemon).
36
37 In /etc/inetd.conf you should add a line like this:
38
39 swat    stream  tcp     nowait.400  root    /usr/local/samba/bin/swat swat
40
41 If you just want to see a demo of how swat works and don't want to be
42 able to actually change any Samba config via swat then you may chose
43 to change "root" to some other user that does not have permission to
44 write to smb.conf.
45
46 One you have edited /etc/services and /etc/inetd.conf you need to send
47 a HUP signal to inetd. On many systems "killall -1 inetd" will do this
48 on others you will need to use "kill -1 PID" where PID is the process
49 ID of the inetd daemon.
50
51
52 Running via cgi-bin
53 -------------------
54
55 To run SWAT via your web servers cgi-bin capability you need to copy
56 the swat binary to your cgi-bin directory. Note that you should run
57 SWAT either via inetd or via cgi-bin but not both.
58
59 Then you need to create a swat directory in your web servers root
60 directory and copy the images/* and help/* files into there so that
61 they are visible via the URL http://your.web.server/swat/
62
63 Next you need to make sure you modify your web servers authentication
64 to require a username/pssword for the URL
65 http://your.web.server/cgi-bin/swat. Don't forgt this step! If you do
66 forget it then you will be allowing anyone to edit your Samba
67 configuration which would allow them to easily gain root access on your
68 machine.
69
70 After testing the authentication you need to change the ownership and
71 permissions on the swat binary. It should be owned by root wth the
72 setuid bit set. It should be ONLY executable by the user that the web
73 server runs as. Make sure you do this carefully!
74
75 for example, the following would be correct if the web server ran as
76 group "nobody".
77
78 -rws--x---    1 root     nobody    
79
80 You must also realise that this means that any user who can run
81 programs as the "nobody" group can run swat and modify your Samba
82 config. Be sure to think about this!
83
84
85 Launching
86 ---------
87
88 To launch SWAT just run your favourite web browser and point it at
89 http://localhost:901/ or http://localhost/cgi-bin/swat/ depending on
90 how you installed it.
91
92 Note that you can attach to SWAT from any IP connected machine but
93 connecting from a remote machine leaves your connection open to
94 password sniffing as passwords will be sent in the clear over the
95 wire.
96
97 If installed via inetd then you should be prompted for a
98 username/password when you connect. You will need to provide the
99 username "root" and the correct root password. More sophisticated
100 authentication options are planned for future versions of SWAT.
101
102 If installed via cgi-bin then you should receive whatever
103 authentication request you configured in your web server.
104
105 Running
106 -------
107
108 Just follow your nose! If you can't work out how to use it then maybe
109 you should use "vi smb.conf" instead.
110
111
112 WARNINGS
113 --------
114
115 SWAT will rewrite your smb.conf file. It will rearrange the entries
116 and delete all comments, include= and copy= options. If you have a
117 carefully crafted smb.conf then back it up or don't use SWAT!
118
119
120 Development
121 -----------
122
123 Please join the samba-technical mailing list if you want to discuss
124 the development of SWAT. Note that this list is for technical developer
125 discussions and is not a general help list.
126