=== modified file 'Makefile'
--- Makefile	2008-08-17 06:01:58 +0000
+++ Makefile	2008-08-17 20:34:18 +0000
@@ -39,7 +39,7 @@
 	--param man.output.quietly		1 \
 	--param man.authors.section.enabled	0
 # DocBook-to-man post-processing to fix a \n escape bug
-MANPOST=sed --in-place --expression='s,\\en,\en,g;s,\een,\en,g'
+MANPOST=sed --in-place --expression='s,\\en,\en,g;s,\\een,\\en,g'
 
 PLUGINS=plugins.d/password-prompt plugins.d/password-request
 PROGS=plugin-runner $(PLUGINS)

=== modified file 'TODO'
--- TODO	2008-08-17 06:17:10 +0000
+++ TODO	2008-08-17 20:34:18 +0000
@@ -11,7 +11,7 @@
     Text needed
 *** EXAMPLES
     Examples of normal usage, debug usage, debugging single or all
-    plugins, examples of crypttab lines with plus syntax, etc.
+    plugins, etc.
 *** FILES
     Text needed
 *** SECURITY
@@ -84,18 +84,6 @@
 
 * Mandos (server)
 ** [#A] Command man page: man8/mandos.8
-*** EXAMPLES
-    Create this section
-*** FILES
-    Describe briefly that the server gets global settings from
-    mandos.conf and clients from clients.conf, but refer to their man
-    pages for more details.
-*** DIAGNOSTICS
-    Create this section
-*** SECURITY
-    Create this section
-*** BUGS
-    Create this section
 ** [#A] Config file man page: man5/mandos.conf (mandos.conf)
 ** [#A] Config file man page: man5/mandos-clients.conf (clients.conf)
 ** [#A] /etc/init.d/mandos-server		:teddy:

=== modified file 'mandos.xml'
--- mandos.xml	2008-08-17 06:01:58 +0000
+++ mandos.xml	2008-08-17 20:34:18 +0000
@@ -103,7 +103,7 @@
     <cmdsynopsis>
       <command>&COMMANDNAME;</command>
       <arg choice='plain'>--check</arg>
-    </cmdsynopsis>    
+    </cmdsynopsis>
   </refsynopsisdiv>
 
   <refsect1 id="description">
@@ -115,12 +115,12 @@
       announce itself on the local network, and uses GnuTLS to
       communicate securely with and to authenticate the clients.
       Mandos uses IPv6 link-local addresses, since the clients are
-      assumed to not have any other addresses configured yet.  Any
+      assumed to not have any other addresses configured.  Any
       authenticated client is then given the pre-encrypted password
       for that specific client.
     </para>
 
-  </refsect1>  
+  </refsect1>
   
   <refsect1 id="purpose">
     <title>PURPOSE</title>
@@ -137,7 +137,7 @@
       normally.
     </para>
 
-  </refsect1>  
+  </refsect1>
   
   <refsect1 id="options">
     <title>OPTIONS</title>
@@ -162,7 +162,7 @@
 	    use all available interfaces.
 	  </para>
 	</listitem>
-      </varlistentry>      
+      </varlistentry>
 
       <varlistentry>
 	<term><literal>-a</literal>, <literal>--address <replaceable>
@@ -172,14 +172,14 @@
 	    If this option is used, the server will only listen to a
 	    specific address.  This must currently be an IPv6 address;
 	    an IPv4 address can be specified using the
-	    "<literal>::FFFF:192.0.2.3</literal>" syntax.  Also, if a
-	    link-local address is specified, an interface should be
-	    set, since a link-local address is only valid on a single
-	    interface.  By default, the server will listen to all
-	    available addresses.
+	    <quote><literal>::FFFF:192.0.2.3</literal></quote> syntax.
+	    Also, if a link-local address is specified, an interface
+	    should be set, since a link-local address is only valid on
+	    a single interface.  By default, the server will listen to
+	    all available addresses.
 	  </para>
 	</listitem>
-      </varlistentry>          
+      </varlistentry>
 
       <varlistentry>
 	<term><literal>-p</literal>, <literal>--port <replaceable>
@@ -191,7 +191,7 @@
 	    port given by the operating system.
 	  </para>
 	</listitem>
-      </varlistentry>          
+      </varlistentry>
 
       <varlistentry>
 	<term><literal>--check</literal></term>
@@ -201,7 +201,7 @@
 	    tests, etc.
 	  </para>
 	</listitem>
-      </varlistentry>      
+      </varlistentry>
 
       <varlistentry>
 	<term><literal>--debug</literal></term>
@@ -224,13 +224,13 @@
 	    <citerefentry><refentrytitle>gnutls_priority_init
 	    </refentrytitle><manvolnum>3</manvolnum></citerefentry>
 	    for the syntax.  The default is
-	    "<literal>SECURE256:!CTYPE-X.509:+CTYPE-OPENPGP</literal>".
+	    <quote><literal>SECURE256:!CTYPE-X.509:+CTYPE-OPENPGP</literal></quote>.
 	    <emphasis>Warning</emphasis>: changing this may make the
 	    TLS handshake fail, making communication with clients
 	    impossible.
 	  </para>
 	</listitem>
-      </varlistentry>      
+      </varlistentry>
 
       <varlistentry>
 	<term><literal>--servicename <replaceable>NAME</replaceable>
@@ -238,15 +238,17 @@
 	<listitem>
 	  <para>
 	    Zeroconf service name.  The default is
-	    "<literal>Mandos</literal>".  You only need to change this
-	    if you for some reason want to run more than one server on
-	    the same <emphasis>host</emphasis>.  If there are name
+	    <quote><literal>Mandos</literal></quote>.  You only need
+	    to change this if you for some reason want to run more
+	    than one server on the same <emphasis>host</emphasis>,
+	    which would not normally be useful.  If there are name
 	    collisions on the same <emphasis>network</emphasis>, the
-	    new server will automatically rename itself to "Mandos
-	    #2", etc.
+	    newer server will automatically rename itself to
+	    <quote><literal>Mandos #2</literal></quote>, and so on,
+	    therefore this option is not needed in that case.
 	  </para>
 	</listitem>
-      </varlistentry>     
+      </varlistentry>
 
       <varlistentry>
 	<term><literal>--configdir <replaceable>DIR</replaceable>
@@ -254,8 +256,8 @@
 	<listitem>
 	  <para>
 	    Directory to search for configuration files.  Default is
-	    "<literal>/etc/mandos</literal>".  See <citerefentry>
-	    <refentrytitle>mandos.conf</refentrytitle>
+	    <quote><literal>/etc/mandos</literal></quote>.  See
+	    <citerefentry><refentrytitle>mandos.conf</refentrytitle>
 	    <manvolnum>5</manvolnum></citerefentry> and <citerefentry>
 	    <refentrytitle>mandos-clients.conf</refentrytitle>
 	    <manvolnum>5</manvolnum></citerefentry>.
@@ -270,7 +272,7 @@
 	    Prints the program version and exit.
 	  </para>
 	</listitem>
-      </varlistentry>      
+      </varlistentry>
     </variablelist>
   </refsect1>
 
@@ -278,20 +280,22 @@
     <title>NETWORK PROTOCOL</title>
     <para>
       The Mandos server announces itself as a Zeroconf service of type
-      "<literal>_mandos._tcp</literal>".  The Mandos client connects
-      to the announced address and port, and sends a line of text
-      where the first whitespace-separated field is the protocol
-      version, which currently is "<literal>1</literal>".  The client
-      and server then start a TLS protocol handshake with a slight
-      quirk: the Mandos server program acts as a TLS "client" while
-      the connecting Mandos client acts as a TLS "server".  The Mandos
-      client must supply an OpenPGP certificate, and the fingerprint
-      of this certificate is used by the Mandos server to look up (in
-      a list read from a file at start time) which binary blob to give
-      the client.  No other authentication or authorization is done by
-      the server.
+      <quote><literal>_mandos._tcp</literal></quote>.  The Mandos
+      client connects to the announced address and port, and sends a
+      line of text where the first whitespace-separated field is the
+      protocol version, which currently is
+      <quote><literal>1</literal></quote>.  The client and server then
+      start a TLS protocol handshake with a slight quirk: the Mandos
+      server program acts as a TLS <quote>client</quote> while the
+      connecting Mandos client acts as a TLS <quote>server</quote>.
+      The Mandos client must supply an OpenPGP certificate, and the
+      fingerprint of this certificate is used by the Mandos server to
+      look up (in a list read from <filename>clients.conf</filename>
+      at start time) which binary blob to give the client.  No other
+      authentication or authorization is done by the server.
     </para>
-    <informaltable><tgroup cols="3"><thead>
+    <table>
+      <title>Mandos Protocol (Version 1)</title><tgroup cols="3"><thead>
       <row>
 	<entry>Mandos Client</entry>
 	<entry>Direction</entry>
@@ -303,13 +307,15 @@
 	<entry>-><!-- &rarr; --></entry>
       </row>
       <row>
-	<entry>"<literal>1\r\en</literal>"</entry>
+	<entry><quote><literal>1\r\en</literal></quote></entry>
 	<entry>-><!-- &rarr; --></entry>
       </row>
       <row>
-	<entry>TLS handshake</entry>
+	<entry>TLS handshake <emphasis>as TLS <quote>server</quote>
+	</emphasis></entry>
 	<entry>&lt;-><!-- &xharr; --></entry>
-	<entry>TLS handshake</entry>
+	<entry>TLS handshake <emphasis>as TLS <quote>client</quote>
+	</emphasis></entry>
       </row>
       <row>
 	<entry>OpenPGP public key (part of TLS handshake)</entry>
@@ -318,23 +324,37 @@
       <row>
 	<entry/>
 	<entry>&lt;-<!-- &larr; --></entry>
-	<entry>Binary blob</entry>
+	<entry>Binary blob (client will assume OpenPGP data)</entry>
       </row>
       <row>
 	<entry/>
 	<entry>&lt;-<!-- &larr; --></entry>
 	<entry>Close</entry>
       </row>
-    </tbody></tgroup></informaltable>
+    </tbody></tgroup></table>
+  </refsect1>
+
+  <refsect1 id="checking">
+    <title>CHECKING</title>
+    <para>
+      The server will, by default, continually check that the clients
+      are still up.  If a client has not been confirmed as being up
+      for some time, the client is assumed to be compromised and is no
+      longer eligible to receive the encrypted password.  The timeout,
+      checker program and interval between checks can be configured
+      both globally and per client; see <citerefentry>
+      <refentrytitle>mandos.conf</refentrytitle>
+      <manvolnum>5</manvolnum></citerefentry> and <citerefentry>
+      <refentrytitle>mandos-clients.conf</refentrytitle>
+      <manvolnum>5</manvolnum></citerefentry>.
+    </para>
   </refsect1>
 
   <refsect1 id="logging">
     <title>LOGGING</title>
     <para>
-      The server will log a lot of information with various severity
-      levels to
-      <citerefentry><refentrytitle>syslog</refentrytitle>
-      <manvolnum>8</manvolnum></citerefentry>.  With the
+      The server will send log messaged with various severity levels
+      to <filename>/dev/log</filename>.  With the
       <option>--debug</option> option, it will log even more messages,
       and also show them on the console.
     </para>
@@ -351,40 +371,125 @@
   <refsect1 id="file">
     <title>FILES</title>
     <para>
-      <itemizedlist>
-	<listitem><para>
-	  <filename>/etc/mandos/mandos.conf</filename>  See <citerefentry>
-	    <refentrytitle>mandos.conf</refentrytitle>
-	    <manvolnum>5</manvolnum></citerefentry>.
-	</para></listitem>
-	<listitem><para>
-	  <filename>/etc/mandos/clients.conf</filename> See <citerefentry>
-	    <refentrytitle>mandos-clients.conf</refentrytitle>
-	    <manvolnum>5</manvolnum></citerefentry>.
-	</para></listitem>
-	<listitem><para>
-	  <filename>/var/run/mandos/mandos.pid</filename>
-	</para></listitem>
-      </itemizedlist>
+      Use the <option>--configdir</option> option to change where
+      <command>&COMMANDNAME;</command> looks for its configurations
+      files.  The default file names are listed here.
     </para>
-  </refsect1>  
+    <variablelist>
+      <varlistentry>
+	<term><filename>/etc/mandos/mandos.conf</filename></term>
+	<listitem>
+	  <para>
+	    Server-global settings.  See
+	    <citerefentry><refentrytitle>mandos.conf</refentrytitle>
+	    <manvolnum>5</manvolnum></citerefentry> for details.
+	  </para>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><filename>/etc/mandos/clients.conf</filename></term>
+	<listitem>
+	  <para>
+	    List of clients and client-specific settings.  See
+	    <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
+	    <manvolnum>5</manvolnum></citerefentry> for details.
+	  </para>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><filename>/var/run/mandos/mandos.pid</filename></term>
+	<listitem>
+	  <para>
+	    The file containing the process id of
+	    <command>&COMMANDNAME;</command>.
+	  </para>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><filename>/dev/log</filename></term>
+	<listitem>
+	  <para>
+	    The Unix domain socket to where local syslog messages are
+	    sent.
+	  </para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
 
   <refsect1 id="bugs">
     <title>BUGS</title>
     <para>
+      This server might, on especially fatal errors, emit a Python
+      backtrace.  This could be considered a feature.
     </para>
-  </refsect1>  
+  </refsect1>
 
   <refsect1 id="examples">
     <title>EXAMPLES</title>
-    <para>
-    </para>
+    <informalexample>
+      <para>
+	Normal invocation needs no options:
+      </para>
+      <para>
+	<userinput>mandos</userinput>
+      </para>
+    </informalexample>
+    <informalexample>
+      <para>
+	Run the server in debug mode and read configuration files from
+	the <filename>~/mandos</filename> directory:
+      </para>
+      <para>
+
+<!-- do not wrap this line -->
+<userinput>mandos --debug --configdir ~/mandos --servicename Test</userinput>
+
+      </para>
+    </informalexample>
+    <informalexample>
+      <para>
+	Run the server normally, but only listen to one interface and
+	only on the link-local address on that interface:
+      </para>
+      <para>
+
+<!-- do not wrap this line -->
+<userinput>mandos --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>
+
+      </para>
+    </informalexample>
   </refsect1>
 
   <refsect1 id="security">
     <title>SECURITY</title>
-    <para>
-    </para>
+    <refsect2>
+      <title>SERVER</title>
+      <para>
+	Running the server should not in itself present any security
+	risk to the host computer running it.
+      </para>
+    </refsect2>
+    <refsect2>
+      <title>CLIENTS</title>
+      <para>
+	The server only gives out its stored data to clients which
+	does have the OpenPGP key of the stored fingerprint.  This is
+	guaranteed by the fact that the client sends its OpenPGP
+	public key in the TLS handshake; this ensures it to be
+	genuine.  The server computes the fingerprint of the key
+	itself and looks up the fingerprint in its list of
+	clients. The <filename>clients.conf</filename> file (see
+	<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
+	<manvolnum>5</manvolnum></citerefentry>) must be non-readable
+	by anyone except the user running the server.
+      </para>
+      <para>
+	For more details on client-side security, see
+	<citerefentry><refentrytitle>password-request</refentrytitle>
+	<manvolnum>8mandos</manvolnum></citerefentry>.
+      </para>
+    </refsect2>
   </refsect1>
 
   <refsect1 id="see_also">