docs/docbook/manpages/swat.8.sgml

   1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
   2 <!ENTITY % globalentities SYSTEM '../global.ent'> %globalentities;
   3 ]>
   4 <refentry id="swat.8">
   5
   6 <refmeta>
   7         <refentrytitle>swat</refentrytitle>
   8         <manvolnum>8</manvolnum>
   9 </refmeta>
  10
  11
  12 <refnamediv>
  13         <refname>swat</refname>
  14         <refpurpose>Samba Web Administration Tool</refpurpose>
  15 </refnamediv>
  16
  17 <refsynopsisdiv>
  18         <cmdsynopsis>
  19                 <command>swat</command>
  20                 <arg choice="opt">-s &lt;smb config file&gt;</arg>
  21                 <arg choice="opt">-a</arg>
  22         </cmdsynopsis>
  23 </refsynopsisdiv>
  24
  25 <refsect1>
  26         <title>DESCRIPTION</title>
  27
  28         <para>This tool is part of the <citerefentry><refentrytitle>Samba</refentrytitle>
  29         <manvolnum>7</manvolnum></citerefentry> suite.</para>
  30
  31
  32         <para><command>swat</command> allows a Samba administrator to
  33         configure the complex <citerefentry><refentrytitle>smb.conf</refentrytitle>
  34         <manvolnum>5</manvolnum></citerefentry> file via a Web browser. In addition,
  35         a <command>swat</command> configuration page has help links
  36         to all the configurable options in the <filename>smb.conf</filename> file allowing an
  37         administrator to easily look up the effects of any change. </para>
  38
  39         <para><command>swat</command> is run from <command>inetd</command> </para>
  40 </refsect1>
  41
  42
  43 <refsect1>
  44         <title>OPTIONS</title>
  45
  46         <variablelist>
  47                 <varlistentry>
  48                 <term>-s smb configuration file</term>
  49                 <listitem><para>The default configuration file path is
  50                 determined at compile time.  The file specified contains
  51                 the configuration details required by the <citerefentry><refentrytitle>smbd</refentrytitle>
  52                 <manvolnum>8</manvolnum></citerefentry> server. This is the file
  53                 that <command>swat</command> will modify.
  54                 The information in this file includes server-specific
  55                 information such as what printcap file to use, as well as
  56                 descriptions of all the services that the server is to provide.
  57                 See <filename>smb.conf</filename> for more information.
  58                 </para></listitem>
  59                 </varlistentry>
  60
  61
  62                 <varlistentry>
  63                 <term>-a</term>
  64                 <listitem><para>This option disables authentication and puts
  65                 <command>swat</command> in demo mode. In that mode anyone will be able to modify
  66                 the <filename>smb.conf</filename> file. </para>
  67
  68                 <para><emphasis>WARNING: Do NOT enable this option on a production
  69                 server. </emphasis></para></listitem>
  70                 </varlistentry>
  71
  72                 &popt.common.samba;
  73                 &stdarg.help;
  74
  75         </variablelist>
  76
  77 </refsect1>
  78
  79 <refsect1>
  80
  81         <title>INSTALLATION</title>
  82
  83         <para>Swat is included as binary package with most distributions. The
  84         package manager in this case takes care of the installation and
  85         configuration. This section is only for those who have compiled
  86         swat from scratch.
  87         </para>
  88
  89         <para>After you compile SWAT you need to run <command>make install
  90         </command> to install the <command>swat</command> binary
  91         and the various help files and images. A default install would put
  92         these in: </para>
  93
  94         <itemizedlist>
  95                 <listitem><para>/usr/local/samba/bin/swat</para></listitem>
  96                 <listitem><para>/usr/local/samba/swat/images/*</para></listitem>
  97                 <listitem><para>/usr/local/samba/swat/help/*</para></listitem>
  98         </itemizedlist>
  99
 100         <refsect2>
 101                 <title>Inetd Installation</title>
 102
 103                 <para>You need to edit your <filename>/etc/inetd.conf
 104                 </filename> and <filename>/etc/services</filename>
 105                 to enable SWAT to be launched via <command>inetd</command>.</para>
 106
 107                 <para>In <filename>/etc/services</filename> you need to
 108                 add a line like this: </para>
 109
 110                 <para><command>swat            901/tcp</command></para>
 111
 112                 <para>Note for NIS/YP and LDAP users - you may need to rebuild the
 113                 NIS service maps rather than alter your local <filename>
 114                 /etc/services</filename> file. </para>
 115
 116                 <para>the choice of port number isn't really important
 117                 except that it should be less than 1024 and not currently
 118                 used (using a number above 1024 presents an obscure security
 119                 hole depending on the implementation details of your
 120                 <command>inetd</command> daemon). </para>
 121
 122                 <para>In <filename>/etc/inetd.conf</filename> you should
 123                 add a line like this: </para>
 124
 125                 <para><command>swat    stream  tcp     nowait.400  root
 126                 /usr/local/samba/bin/swat swat</command></para>
 127
 128                 <para>One you have edited <filename>/etc/services</filename>
 129                 and <filename>/etc/inetd.conf</filename> you need to send a
 130                 HUP signal to inetd. To do this use <command>kill -1 PID
 131                 </command> where PID is the process ID of the inetd daemon. </para>
 132
 133         </refsect2>
 134
 135
 136
 137 </refsect1>
 138
 139 <refsect1>
 140         <title>LAUNCHING</title>
 141
 142         <para>To launch SWAT just run your favorite web browser and
 143         point it at "http://localhost:901/".</para>
 144
 145         <para>Note that you can attach to SWAT from any IP connected
 146         machine but connecting from a remote machine leaves your
 147         connection open to password sniffing as passwords will be sent
 148         in the clear over the wire. </para>
 149 </refsect1>
 150
 151 <refsect1>
 152         <title>FILES</title>
 153
 154         <variablelist>
 155                 <varlistentry>
 156                 <term><filename>/etc/inetd.conf</filename></term>
 157                 <listitem><para>This file must contain suitable startup
 158                 information for the meta-daemon.</para></listitem>
 159                 </varlistentry>
 160
 161                 <varlistentry>
 162                 <term><filename>/etc/services</filename></term>
 163                 <listitem><para>This file must contain a mapping of service name
 164                 (e.g., swat) to service port (e.g., 901) and protocol type
 165                 (e.g., tcp).  </para></listitem>
 166                 </varlistentry>
 167
 168                 <varlistentry>
 169                 <term><filename>/usr/local/samba/lib/smb.conf</filename></term>
 170                 <listitem><para>This is the default location of the <citerefentry>
 171                 <refentrytitle>smb.conf</refentrytitle><manvolnum>5</manvolnum>
 172                 </citerefentry> server configuration file that swat edits. Other
 173                 common places that systems install this file are <filename>
 174                 /usr/samba/lib/smb.conf</filename> and <filename>/etc/smb.conf
 175                 </filename>.  This file describes all the services the server
 176                 is to make available to clients. </para></listitem>
 177                 </varlistentry>
 178         </variablelist>
 179 </refsect1>
 180
 181
 182 <refsect1>
 183         <title>WARNINGS</title>
 184
 185         <para><command>swat</command> will rewrite your <citerefentry>
 186         <refentrytitle>smb.conf</refentrytitle><manvolnum>5</manvolnum>
 187         </citerefentry> file. It will rearrange the entries and delete all
 188         comments, <parameter>include=</parameter> and <parameter>copy=
 189         </parameter> options. If you have a carefully crafted <filename>
 190         smb.conf</filename> then back it up or don't use swat! </para>
 191 </refsect1>
 192
 193
 194 <refsect1>
 195         <title>VERSION</title>
 196
 197         <para>This man page is correct for version 3.0 of the Samba suite.</para>
 198 </refsect1>
 199
 200 <refsect1>
 201         <title>SEE ALSO</title>
 202         <para><command>inetd(5)</command>, <citerefentry>
 203         <refentrytitle>smbd</refentrytitle><manvolnum>8</manvolnum>
 204         </citerefentry>, <citerefentry><refentrytitle>smb.conf</refentrytitle>
 205         <manvolnum>5</manvolnum></citerefentry></para>
 206 </refsect1>
 207
 208 <refsect1>
 209         <title>AUTHOR</title>
 210
 211         <para>The original Samba software and related utilities
 212         were created by Andrew Tridgell. Samba is now developed
 213         by the Samba Team as an Open Source project similar
 214         to the way the Linux kernel is developed.</para>
 215
 216         <para>The original Samba man pages were written by Karl Auer.
 217         The man page sources were converted to YODL format (another
 218         excellent piece of Open Source software, available at <ulink url="ftp://ftp.icce.rug.nl/pub/unix/">
 219         ftp://ftp.icce.rug.nl/pub/unix/</ulink>) and updated for the Samba 2.0
 220         release by Jeremy Allison.  The conversion to DocBook for
 221         Samba 2.2 was done by Gerald Carter. The conversion to DocBook XML 4.2 for
 222         Samba 3.0 was done by Alexander Bokovoy.</para>
 223 </refsect1>
 224
 225 </refentry>