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