/mandos/trunk

<?xml version='1.0' encoding='UTF-8'?>

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"

	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [

<!ENTITY VERSION "1.0">

<!ENTITY CONFNAME "mandos-clients.conf">

<!ENTITY CONFPATH "<filename>/etc/mandos/clients.conf</filename>">

]>

<refentry>

  <refentryinfo>

    <title>&CONFNAME;</title>

    <!-- NWalsh’s docbook scripts use this to generate the footer: -->

    <productname>&CONFNAME;</productname>

    <productnumber>&VERSION;</productnumber>

    <authorgroup>

      <author>

	<firstname>Björn</firstname>

	<surname>Påhlsson</surname>

	<address>

	  <email>belorn@fukt.bsnet.se</email>

	</address>

      </author>

      <author>

	<firstname>Teddy</firstname>

	<surname>Hogeborn</surname>

	<address>

	  <email>teddy@fukt.bsnet.se</email>

	</address>

      </author>

    </authorgroup>

    <copyright>

      <year>2008</year>

      <holder>Teddy Hogeborn</holder>

      <holder>Björn Påhlsson</holder>

    </copyright>

    <legalnotice>

      <para>

	This manual page is free software: you can redistribute it

	and/or modify it under the terms of the GNU General Public

	License as published by the Free Software Foundation,

	either version 3 of the License, or (at your option) any

	later version.

      </para>

      <para>

	This manual page is distributed in the hope that it will

	be useful, but WITHOUT ANY WARRANTY; without even the

	implied warranty of MERCHANTABILITY or FITNESS FOR A

	PARTICULAR PURPOSE.  See the GNU General Public License

	for more details.

      </para>

      <para>

	You should have received a copy of the GNU General Public

	License along with this program; If not, see

	<ulink url="http://www.gnu.org/licenses/"/>.

      </para>

    </legalnotice>

  </refentryinfo>

  <refmeta>

    <refentrytitle>&CONFNAME;</refentrytitle>

    <manvolnum>5</manvolnum>

  </refmeta>

  <refnamediv>

    <refname><filename>&CONFNAME;</filename></refname>

    <refpurpose>

      Configuration file for the Mandos server

    </refpurpose>

  </refnamediv>

  <refsynopsisdiv>

    <synopsis>

      &CONFPATH;

    </synopsis>

  </refsynopsisdiv>

  <refsect1 id="description">

    <title>DESCRIPTION</title>

    <para>

      The file &CONFPATH; is the configuration file for <citerefentry

      ><refentrytitle>mandos</refentrytitle>

      <manvolnum>8</manvolnum></citerefentry>, read by it at startup,

      where each client that will be able to use the service needs to

      be listed.  All clients listed will be regarded as valid, even

      if a client was declared invalid in a previous run of the

      server.

    </para>

    <para>

      The format starts with a section under [] which is either

      <literal>[DEFAULT]</literal> or <literal>[<replaceable>client

      name</replaceable>]</literal>.  Following the section is any

      number of <quote><varname><replaceable>option</replaceable

      ></varname>=<replaceable>value</replaceable></quote> entries,

      with continuations in the style of RFC 822.  <quote><varname

      ><replaceable>option</replaceable></varname>: <replaceable

      >value</replaceable></quote> is also accepted.  Note that

      leading whitespace is removed from values.  Values can contain

      format strings which refer to other values in the same section,

      or values in the <quote>DEFAULT</quote> section.  Lines

      beginning with <quote>#</quote> or <quote>;</quote> are ignored

      and may be used to provide comments.

    </para>

  </refsect1>

  <refsect1 id="options">

    <title>OPTIONS</title>

    <para>

      The possible options are:

    </para>

    <variablelist>

      <varlistentry>

	<term><literal><varname>timeout</varname></literal></term>

	<listitem>

	  <synopsis><literal>timeout = </literal><replaceable

	  >TIME</replaceable>

	  </synopsis>

	  <para>

	    The timeout is how long the server will wait for a

	    successful checker run until a client is considered

	    invalid - that is, ineligible to get the data this server

	    holds.  By default Mandos will use 1 hour.

	  </para>

	  <para>

	    The <replaceable>TIME</replaceable> is specified as a

	    space-separated number of values, each of which is a

	    number and a one-character suffix.  The suffix must be one

	    of <quote>d</quote>, <quote>s</quote>, <quote>m</quote>,

	    <quote>h</quote>, and <quote>w</quote> for days, seconds,

	    minutes, hours, and weeks, respectively.  The values are

	    added together to give the total time value, so all of

	    <quote><literal>330s</literal></quote>,

	    <quote><literal>110s 110s 110s</literal></quote>, and

	    <quote><literal>5m 30s</literal></quote> will give a value

	    of five minutes and thirty seconds.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><literal><varname>interval</varname></literal></term>

	<listitem>

	  <synopsis><literal>interval = </literal><replaceable

	  >TIME</replaceable>

	  </synopsis>

	  <para>

	    How often to run the checker to confirm that a client is

	    still up.  <emphasis>Note:</emphasis> a new checker will

	    not be started if an old one is still running.  The server

	    will wait for a checker to complete until the above

	    <quote><varname>timeout</varname></quote> occurs, at which

	    time the client will be marked invalid, and any running

	    checker killed.  The default interval is 5 minutes.

	  </para>

	  <para>

	    The format of <replaceable>TIME</replaceable> is the same

	    as for <varname>timeout</varname> above.

	  </para>

	</listitem>

      </varlistentry>      

      <varlistentry>

	<term><literal>checker</literal></term>

	<listitem>

	  <para>

	    This option allows you to override the default shell

	    command that the server will use to check up if the client

	    is still up. By default mandos will "fping -q -- %%(host)s"

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><literal>fingerprint</literal></term>

	<listitem>

	  <para>

	    This option sets the openpgp fingerprint that identifies

	    the public certificate that clients authenticates themself

	    through gnutls. The string need to be in hex-decimal form.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><literal>secret</literal></term>

	<listitem>

	  <para>

	    Base 64 encoded OpenPGP encrypted password encrypted by

	    the clients openpgp certificate.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><literal>secfile</literal></term>

	<listitem>

	  <para>

	    Base 64 encoded OpenPGP encrypted password encrypted by

	    the clients openpgp certificate as a binary file.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><literal>host</literal></term>

	<listitem>

	  <para>

	    Host name that can be used in for checking that the client is up.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><literal>checker</literal></term>

	<listitem>

	  <para>

	    Shell command that the server will use to check up if a

	    client is still up.

	  </para>

	</listitem>

      </varlistentry>      

      <varlistentry>

	<term><literal>timeout</literal></term>

	<listitem>

	  <para>

	    Duration that a client can be down whitout be removed from

	    the client list.

	  </para>

	</listitem>

      </varlistentry> 

    </variablelist>

  </refsect1>  

  <refsect1 id="expansion">

    <title>EXPANSION</title>

    <para>

      There are two forms of expansion: Start time expansion and

      runtime expansion.

    </para>

    <refsect2>

      <title>START TIME EXPANSION</title>

      <para>

	Any string in an option value of the form

	<quote><literal>%(<replaceable>foo</replaceable>)s</literal

	></quote> will be replaced by the value of the option

	<varname>foo</varname> either in the same section, or, if it

	does not exist there, the <literal>[DEFAULT]</literal>

	section.  This is done at start time, when the configuration

	file is read.

      </para>

      <para>

	Note that this means that, in order to include an actual

	percent character (<quote>%</quote>) in an option value, two

	percent characters in a row (<quote>%%</quote>) must be

	entered.

      </para>

    </refsect2>

    <refsect2>

      <title>RUNTIME EXPANSION</title>

      <para>

	This is currently only done for the <varname>checker</varname>

	option.

      </para>

      <para>

	Any string in an option value of the form

	<quote><literal>%%(<replaceable>foo</replaceable>)s</literal

	></quote> will be replaced by the value of the attribute

	<varname>foo</varname> of the internal

	<quote><classname>Client</classname></quote> object.  See the

	source code for details, and let the authors know of any

	attributes that are useful so they may be preserved to any new

	versions of this software.

      </para>

      <para>

	Note that this means that, in order to include an actual

	percent character (<quote>%</quote>) in a

	<varname>checker</varname> options, <emphasis>four</emphasis>

	percent characters in a row (<quote>%%%%</quote>) must be

	entered.  Also, a bad format here will lead to an immediate

	but <emphasis>silent</emphasis> run-time fatal exit; debug

	mode is needed to track down an error of this kind.

      </para>

    </refsect2>

  </refsect1>  

  <refsect1 id="files">

    <title>FILES</title>

    <para>

      The file described here is &CONFPATH;

    </para>

  </refsect1>

  <refsect1 id="bugs">

    <title>BUGS</title>

    <para>

      The format for specifying times for <varname>timeout</varname>

      and <varname>interval</varname> is not very good.

    </para>

    <para>

      The difference between

      <literal>%%(<replaceable>foo</replaceable>)s</literal> and

      <literal>%(<replaceable>foo</replaceable>)s</literal> is

      obscure.

    </para>

  </refsect1>

  <refsect1 id="example">

    <title>EXAMPLE</title>

    <informalexample>

      <programlisting>

[DEFAULT]

timeout = 1h

interval = 5m

checker = fping -q -- %%(host)s

# Client "foo"

[foo]

fingerprint =  7788 2722 5BA7 DE53 9C5A  7CFA 59CF F7CD BD9A 5920

secret =

        hQIOA6QdEjBs2L/HEAf/TCyrDe5Xnm9esa+Pb/vWF9CUqfn4srzVgSu234

        REJMVv7lBSrPE2132Lmd2gqF1HeLKDJRSVxJpt6xoWOChGHg+TMyXDxK+N

        Xl89vGvdU1XfhKkVm9MDLOgT5ECDPysDGHFPDhqHOSu3Kaw2DWMV/iH9vz

        3Z20erVNbdcvyBnuojcoWO/6yfB5EQO0BXp7kcyy00USA3CjD5FGZdoQGI

        Tb8A/ar0tVA5crSQmaSotm6KmNLhrFnZ5BxX+TiE+eTUTqSloWRY6VAvqW

        QHC7OASxK5E6RXPBuFH5IohUA2Qbk5AHt99pYvsIPX88j2rWauOokoiKZo

        t/9leJ8VxO5l3wf/U64IH8bkPIoWmWZfd/nqh4uwGNbCgKMyT+AnvH7kMJ

        3i7DivfWl2mKLV0PyPHUNva0VQxX6yYjcOhj1R6fCr/at8/NSLe2OhLchz

        dC+Ls9h+kvJXgF8Sisv+Wk/1RadPLFmraRlqvJwt6Ww21LpiXqXHV2mIgq

        WnR98YgSvUi3TJHrUQiNc9YyBzuRo0AjgG2C9qiE3FM+Y28+iQ/sR3+bFs

        zYuZKVTObqiIslwXu7imO0cvvFRgJF/6u3HNFQ4LUTGhiM3FQmC6NNlF3/

        vJM2hwRDMcJqDd54Twx90Wh+tYz0z7QMsK4ANXWHHWHR0JchnLWmenzbtW

        5MHdW9AYsNJZAQSOpirE4Xi31CSlWAi9KV+cUCmWF5zOFy1x23P6PjdaRm

        4T2zw4dxS5NswXWU0sVEXxjs6PYxuIiCTL7vdpx8QjBkrPWDrAbcMyBr2O

        QlnHIvPzEArRQLo=

        =iHhv

host = foo.example.org

interval = 5m

# Client "bar"

[bar]

fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27

secfile = /etc/mandos/bar-secret.txt.asc

      </programlisting>

    </informalexample>

  </refsect1>  

</refentry>