/mandos/release

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/release
24.1.23 by Björn Påhlsson
Added manual pages for:
1
<?xml version='1.0' encoding='UTF-8'?>
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
<!ENTITY VERSION "1.0">
24.1.24 by Björn Påhlsson
minor edits
5
<!ENTITY CONFNAME "mandos-clients.conf">
24.1.23 by Björn Påhlsson
Added manual pages for:
6
<!ENTITY CONFPATH "<filename>/etc/mandos/clients.conf</filename>">
7
]>
8
9
<refentry>
10
  <refentryinfo>
11
    <title>&CONFNAME;</title>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
12
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
24.1.23 by Björn Påhlsson
Added manual pages for:
13
    <productname>&CONFNAME;</productname>
14
    <productnumber>&VERSION;</productnumber>
15
    <authorgroup>
16
      <author>
17
	<firstname>Björn</firstname>
18
	<surname>Påhlsson</surname>
19
	<address>
20
	  <email>belorn@fukt.bsnet.se</email>
21
	</address>
22
      </author>
23
      <author>
24
	<firstname>Teddy</firstname>
25
	<surname>Hogeborn</surname>
26
	<address>
27
	  <email>teddy@fukt.bsnet.se</email>
28
	</address>
29
      </author>
30
    </authorgroup>
31
    <copyright>
32
      <year>2008</year>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
33
      <holder>Teddy Hogeborn</holder>
34
      <holder>Björn Påhlsson</holder>
24.1.23 by Björn Påhlsson
Added manual pages for:
35
    </copyright>
36
    <legalnotice>
37
      <para>
38
	This manual page is free software: you can redistribute it
39
	and/or modify it under the terms of the GNU General Public
40
	License as published by the Free Software Foundation,
41
	either version 3 of the License, or (at your option) any
42
	later version.
43
      </para>
44
45
      <para>
46
	This manual page is distributed in the hope that it will
47
	be useful, but WITHOUT ANY WARRANTY; without even the
48
	implied warranty of MERCHANTABILITY or FITNESS FOR A
49
	PARTICULAR PURPOSE.  See the GNU General Public License
50
	for more details.
51
      </para>
52
53
      <para>
54
	You should have received a copy of the GNU General Public
55
	License along with this program; If not, see
56
	<ulink url="http://www.gnu.org/licenses/"/>.
57
      </para>
58
    </legalnotice>
59
  </refentryinfo>
60
61
  <refmeta>
62
    <refentrytitle>&CONFNAME;</refentrytitle>
63
    <manvolnum>5</manvolnum>
64
  </refmeta>
65
  
66
  <refnamediv>
67
    <refname><filename>&CONFNAME;</filename></refname>
68
    <refpurpose>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
69
      Configuration file for the Mandos server
24.1.23 by Björn Påhlsson
Added manual pages for:
70
    </refpurpose>
71
  </refnamediv>
72
73
  <refsynopsisdiv>
74
    <synopsis>
75
      &CONFPATH;
76
    </synopsis>
77
  </refsynopsisdiv>
78
79
  <refsect1 id="description">
80
    <title>DESCRIPTION</title>
81
    <para>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
82
      The file &CONFPATH; is the configuration file for <citerefentry
83
      ><refentrytitle>mandos</refentrytitle>
84
      <manvolnum>8</manvolnum></citerefentry>, read by it at startup,
85
      where each client that will be able to use the service needs to
86
      be listed.  All clients listed will be regarded as valid, even
87
      if a client was declared invalid in a previous run of the
88
      server.
89
    </para>
90
    <para>
91
      The format starts with a section under [] which is either
92
      <literal>[DEFAULT]</literal> or <literal>[<replaceable>client
93
      name</replaceable>]</literal>.  Following the section is any
94
      number of <quote><varname><replaceable>option</replaceable
95
      ></varname>=<replaceable>value</replaceable></quote> entries,
96
      with continuations in the style of RFC 822.  <quote><varname
97
      ><replaceable>option</replaceable></varname>: <replaceable
98
      >value</replaceable></quote> is also accepted.  Note that
99
      leading whitespace is removed from values.  Values can contain
100
      format strings which refer to other values in the same section,
101
      or values in the <quote>DEFAULT</quote> section.  Lines
102
      beginning with <quote>#</quote> or <quote>;</quote> are ignored
103
      and may be used to provide comments.
24.1.23 by Björn Påhlsson
Added manual pages for:
104
    </para>
105
  </refsect1>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
106
  
107
  <refsect1 id="options">
108
    <title>OPTIONS</title>
24.1.23 by Björn Påhlsson
Added manual pages for:
109
    <para>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
110
      The possible options are:
24.1.23 by Björn Påhlsson
Added manual pages for:
111
    </para>
112
113
    <variablelist>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
114
24.1.23 by Björn Påhlsson
Added manual pages for:
115
      <varlistentry>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
116
	<term><literal><varname>timeout</varname></literal></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
117
	<listitem>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
118
	  <synopsis><literal>timeout = </literal><replaceable
119
	  >TIME</replaceable>
120
	  </synopsis>
121
	  <para>
122
	    The timeout is how long the server will wait for a
123
	    successful checker run until a client is considered
124
	    invalid - that is, ineligible to get the data this server
125
	    holds.  By default Mandos will use 1 hour.
126
	  </para>
127
	  <para>
128
	    The <replaceable>TIME</replaceable> is specified as a
129
	    space-separated number of values, each of which is a
130
	    number and a one-character suffix.  The suffix must be one
131
	    of <quote>d</quote>, <quote>s</quote>, <quote>m</quote>,
132
	    <quote>h</quote>, and <quote>w</quote> for days, seconds,
133
	    minutes, hours, and weeks, respectively.  The values are
134
	    added together to give the total time value, so all of
135
	    <quote><literal>330s</literal></quote>,
136
	    <quote><literal>110s 110s 110s</literal></quote>, and
137
	    <quote><literal>5m 30s</literal></quote> will give a value
138
	    of five minutes and thirty seconds.
24.1.23 by Björn Påhlsson
Added manual pages for:
139
	  </para>
140
	</listitem>
141
      </varlistentry>
142
143
      <varlistentry>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
144
	<term><literal><varname>interval</varname></literal></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
145
	<listitem>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
146
	  <synopsis><literal>interval = </literal><replaceable
147
	  >TIME</replaceable>
148
	  </synopsis>
149
	  <para>
150
	    How often to run the checker to confirm that a client is
151
	    still up.  <emphasis>Note:</emphasis> a new checker will
152
	    not be started if an old one is still running.  The server
153
	    will wait for a checker to complete until the above
154
	    <quote><varname>timeout</varname></quote> occurs, at which
155
	    time the client will be marked invalid, and any running
156
	    checker killed.  The default interval is 5 minutes.
157
	  </para>
158
	  <para>
159
	    The format of <replaceable>TIME</replaceable> is the same
160
	    as for <varname>timeout</varname> above.
24.1.23 by Björn Påhlsson
Added manual pages for:
161
	  </para>
162
	</listitem>
163
      </varlistentry>      
164
165
      <varlistentry>
166
	<term><literal>checker</literal></term>
167
	<listitem>
168
	  <para>
169
	    This option allows you to override the default shell
170
	    command that the server will use to check up if the client
51 by Teddy Hogeborn
* clients.conf: Better comments.
171
	    is still up. By default mandos will "fping -q -- %%(host)s"
24.1.23 by Björn Påhlsson
Added manual pages for:
172
	  </para>
173
	</listitem>
174
      </varlistentry>
175
      
176
      <varlistentry>
177
	<term><literal>fingerprint</literal></term>
178
	<listitem>
179
	  <para>
180
	    This option sets the openpgp fingerprint that identifies
181
	    the public certificate that clients authenticates themself
182
	    through gnutls. The string need to be in hex-decimal form.
183
	  </para>
184
	</listitem>
185
      </varlistentry>
186
      
187
      <varlistentry>
188
	<term><literal>secret</literal></term>
189
	<listitem>
190
	  <para>
191
	    Base 64 encoded OpenPGP encrypted password encrypted by
192
	    the clients openpgp certificate.
193
	  </para>
194
	</listitem>
195
      </varlistentry>
196
197
      <varlistentry>
198
	<term><literal>secfile</literal></term>
199
	<listitem>
200
	  <para>
201
	    Base 64 encoded OpenPGP encrypted password encrypted by
202
	    the clients openpgp certificate as a binary file.
203
	  </para>
204
	</listitem>
205
      </varlistentry>
206
207
      <varlistentry>
51 by Teddy Hogeborn
* clients.conf: Better comments.
208
	<term><literal>host</literal></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
209
	<listitem>
210
	  <para>
51 by Teddy Hogeborn
* clients.conf: Better comments.
211
	    Host name that can be used in for checking that the client is up.
24.1.23 by Björn Påhlsson
Added manual pages for:
212
	  </para>
213
	</listitem>
214
      </varlistentry>
215
216
      <varlistentry>
217
	<term><literal>checker</literal></term>
218
	<listitem>
219
	  <para>
24.1.24 by Björn Påhlsson
minor edits
220
	    Shell command that the server will use to check up if a
24.1.23 by Björn Påhlsson
Added manual pages for:
221
	    client is still up.
222
	  </para>
223
	</listitem>
224
      </varlistentry>      
225
226
      <varlistentry>
227
	<term><literal>timeout</literal></term>
228
	<listitem>
229
	  <para>
230
	    Duration that a client can be down whitout be removed from
231
	    the client list.
232
	  </para>
233
	</listitem>
234
      </varlistentry> 
235
      
236
    </variablelist>
237
  </refsect1>  
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
238
  
239
  <refsect1 id="expansion">
240
    <title>EXPANSION</title>
241
    <para>
242
      There are two forms of expansion: Start time expansion and
243
      runtime expansion.
244
    </para>
245
    <refsect2>
246
      <title>START TIME EXPANSION</title>
247
      <para>
248
	Any string in an option value of the form
249
	<quote><literal>%(<replaceable>foo</replaceable>)s</literal
250
	></quote> will be replaced by the value of the option
251
	<varname>foo</varname> either in the same section, or, if it
252
	does not exist there, the <literal>[DEFAULT]</literal>
253
	section.  This is done at start time, when the configuration
254
	file is read.
255
      </para>
256
      <para>
257
	Note that this means that, in order to include an actual
258
	percent character (<quote>%</quote>) in an option value, two
259
	percent characters in a row (<quote>%%</quote>) must be
260
	entered.
261
      </para>
262
    </refsect2>
263
    <refsect2>
264
      <title>RUNTIME EXPANSION</title>
265
      <para>
266
	This is currently only done for the <varname>checker</varname>
267
	option.
268
      </para>
269
      <para>
270
	Any string in an option value of the form
271
	<quote><literal>%%(<replaceable>foo</replaceable>)s</literal
272
	></quote> will be replaced by the value of the attribute
273
	<varname>foo</varname> of the internal
274
	<quote><classname>Client</classname></quote> object.  See the
275
	source code for details, and let the authors know of any
276
	attributes that are useful so they may be preserved to any new
277
	versions of this software.
278
      </para>
279
      <para>
280
	Note that this means that, in order to include an actual
281
	percent character (<quote>%</quote>) in a
282
	<varname>checker</varname> options, <emphasis>four</emphasis>
283
	percent characters in a row (<quote>%%%%</quote>) must be
284
	entered.  Also, a bad format here will lead to an immediate
285
	but <emphasis>silent</emphasis> run-time fatal exit; debug
286
	mode is needed to track down an error of this kind.
287
      </para>
288
    </refsect2>
24.1.23 by Björn Påhlsson
Added manual pages for:
289
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
290
  </refsect1>  
291
  
292
  <refsect1 id="files">
293
    <title>FILES</title>
294
    <para>
295
      The file described here is &CONFPATH;
296
    </para>
297
  </refsect1>
298
  
299
  <refsect1 id="bugs">
300
    <title>BUGS</title>
301
    <para>
302
      The format for specifying times for <varname>timeout</varname>
303
      and <varname>interval</varname> is not very good.
304
    </para>
305
    <para>
306
      The difference between
307
      <literal>%%(<replaceable>foo</replaceable>)s</literal> and
308
      <literal>%(<replaceable>foo</replaceable>)s</literal> is
309
      obscure.
310
    </para>
311
  </refsect1>
312
  
313
  <refsect1 id="example">
314
    <title>EXAMPLE</title>
24.1.23 by Björn Påhlsson
Added manual pages for:
315
    <informalexample>
316
      <programlisting>
317
[DEFAULT]
318
timeout = 1h
319
interval = 5m
51 by Teddy Hogeborn
* clients.conf: Better comments.
320
checker = fping -q -- %%(host)s
24.1.23 by Björn Påhlsson
Added manual pages for:
321
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
322
# Client "foo"
323
[foo]
24.1.23 by Björn Påhlsson
Added manual pages for:
324
fingerprint =  7788 2722 5BA7 DE53 9C5A  7CFA 59CF F7CD BD9A 5920
325
secret =
24.1.24 by Björn Påhlsson
minor edits
326
        hQIOA6QdEjBs2L/HEAf/TCyrDe5Xnm9esa+Pb/vWF9CUqfn4srzVgSu234
327
        REJMVv7lBSrPE2132Lmd2gqF1HeLKDJRSVxJpt6xoWOChGHg+TMyXDxK+N
328
        Xl89vGvdU1XfhKkVm9MDLOgT5ECDPysDGHFPDhqHOSu3Kaw2DWMV/iH9vz
329
        3Z20erVNbdcvyBnuojcoWO/6yfB5EQO0BXp7kcyy00USA3CjD5FGZdoQGI
330
        Tb8A/ar0tVA5crSQmaSotm6KmNLhrFnZ5BxX+TiE+eTUTqSloWRY6VAvqW
331
        QHC7OASxK5E6RXPBuFH5IohUA2Qbk5AHt99pYvsIPX88j2rWauOokoiKZo
332
        t/9leJ8VxO5l3wf/U64IH8bkPIoWmWZfd/nqh4uwGNbCgKMyT+AnvH7kMJ
333
        3i7DivfWl2mKLV0PyPHUNva0VQxX6yYjcOhj1R6fCr/at8/NSLe2OhLchz
334
        dC+Ls9h+kvJXgF8Sisv+Wk/1RadPLFmraRlqvJwt6Ww21LpiXqXHV2mIgq
335
        WnR98YgSvUi3TJHrUQiNc9YyBzuRo0AjgG2C9qiE3FM+Y28+iQ/sR3+bFs
336
        zYuZKVTObqiIslwXu7imO0cvvFRgJF/6u3HNFQ4LUTGhiM3FQmC6NNlF3/
337
        vJM2hwRDMcJqDd54Twx90Wh+tYz0z7QMsK4ANXWHHWHR0JchnLWmenzbtW
338
        5MHdW9AYsNJZAQSOpirE4Xi31CSlWAi9KV+cUCmWF5zOFy1x23P6PjdaRm
339
        4T2zw4dxS5NswXWU0sVEXxjs6PYxuIiCTL7vdpx8QjBkrPWDrAbcMyBr2O
340
        QlnHIvPzEArRQLo=
341
        =iHhv
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
342
host = foo.example.org
24.1.23 by Björn Påhlsson
Added manual pages for:
343
interval = 5m
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
344
345
# Client "bar"
346
[bar]
347
fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27
348
secfile = /etc/mandos/bar-secret.txt.asc
349
24.1.23 by Björn Påhlsson
Added manual pages for:
350
      </programlisting>
351
    </informalexample>
352
  </refsect1>  
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
353
24.1.23 by Björn Påhlsson
Added manual pages for:
354
</refentry>