/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>
94 by Teddy Hogeborn
* clients.conf ([DEFAULT]/checker): Update to new default value.
91
      The format starts with a <literal>[<replaceable>section
92
      header</replaceable>]</literal> which is either
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
93
      <literal>[DEFAULT]</literal> or <literal>[<replaceable>client
94 by Teddy Hogeborn
* clients.conf ([DEFAULT]/checker): Update to new default value.
94
      name</replaceable>]</literal>.  The <replaceable>client
95
      name</replaceable> can be anything, and is not tied to a host
96
      name.  Following the section header is any number of
97
      <quote><varname><replaceable>option</replaceable
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
98
      ></varname>=<replaceable>value</replaceable></quote> entries,
99
      with continuations in the style of RFC 822.  <quote><varname
100
      ><replaceable>option</replaceable></varname>: <replaceable
101
      >value</replaceable></quote> is also accepted.  Note that
102
      leading whitespace is removed from values.  Values can contain
103
      format strings which refer to other values in the same section,
94 by Teddy Hogeborn
* clients.conf ([DEFAULT]/checker): Update to new default value.
104
      or values in the <quote>DEFAULT</quote> section (see <xref
105
      linkend="expansion"/>).  Lines beginning with <quote>#</quote>
106
      or <quote>;</quote> are ignored and may be used to provide
107
      comments.
24.1.23 by Björn Påhlsson
Added manual pages for:
108
    </para>
109
  </refsect1>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
110
  
111
  <refsect1 id="options">
112
    <title>OPTIONS</title>
24.1.23 by Björn Påhlsson
Added manual pages for:
113
    <para>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
114
      The possible options are:
24.1.23 by Björn Påhlsson
Added manual pages for:
115
    </para>
116
117
    <variablelist>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
118
24.1.23 by Björn Påhlsson
Added manual pages for:
119
      <varlistentry>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
120
	<term><literal><varname>timeout</varname></literal></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
121
	<listitem>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
122
	  <synopsis><literal>timeout = </literal><replaceable
123
	  >TIME</replaceable>
124
	  </synopsis>
125
	  <para>
126
	    The timeout is how long the server will wait for a
127
	    successful checker run until a client is considered
128
	    invalid - that is, ineligible to get the data this server
129
	    holds.  By default Mandos will use 1 hour.
130
	  </para>
131
	  <para>
132
	    The <replaceable>TIME</replaceable> is specified as a
133
	    space-separated number of values, each of which is a
134
	    number and a one-character suffix.  The suffix must be one
135
	    of <quote>d</quote>, <quote>s</quote>, <quote>m</quote>,
136
	    <quote>h</quote>, and <quote>w</quote> for days, seconds,
137
	    minutes, hours, and weeks, respectively.  The values are
138
	    added together to give the total time value, so all of
139
	    <quote><literal>330s</literal></quote>,
140
	    <quote><literal>110s 110s 110s</literal></quote>, and
141
	    <quote><literal>5m 30s</literal></quote> will give a value
142
	    of five minutes and thirty seconds.
24.1.23 by Björn Påhlsson
Added manual pages for:
143
	  </para>
144
	</listitem>
145
      </varlistentry>
146
147
      <varlistentry>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
148
	<term><literal><varname>interval</varname></literal></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
149
	<listitem>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
150
	  <synopsis><literal>interval = </literal><replaceable
151
	  >TIME</replaceable>
152
	  </synopsis>
153
	  <para>
154
	    How often to run the checker to confirm that a client is
155
	    still up.  <emphasis>Note:</emphasis> a new checker will
156
	    not be started if an old one is still running.  The server
157
	    will wait for a checker to complete until the above
158
	    <quote><varname>timeout</varname></quote> occurs, at which
159
	    time the client will be marked invalid, and any running
160
	    checker killed.  The default interval is 5 minutes.
161
	  </para>
162
	  <para>
163
	    The format of <replaceable>TIME</replaceable> is the same
164
	    as for <varname>timeout</varname> above.
24.1.23 by Björn Påhlsson
Added manual pages for:
165
	  </para>
166
	</listitem>
167
      </varlistentry>      
168
169
      <varlistentry>
170
	<term><literal>checker</literal></term>
171
	<listitem>
94 by Teddy Hogeborn
* clients.conf ([DEFAULT]/checker): Update to new default value.
172
	  <synopsis><literal>checker = </literal><replaceable
173
	  >COMMAND</replaceable>
174
	  </synopsis>
24.1.23 by Björn Påhlsson
Added manual pages for:
175
	  <para>
176
	    This option allows you to override the default shell
94 by Teddy Hogeborn
* clients.conf ([DEFAULT]/checker): Update to new default value.
177
	    command that the server will use to check if the client is
178
	    still up.  The output of the command will be ignored, only
179
	    the exit code is checked.  The command will be run using
180
	    <quote><command><filename>/bin/sh</filename>
181
	    <option>-c</option></command></quote>.  The default
182
	    command is <quote><literal><command>fping</command>
183
	    <option>-q</option> <option>--</option>
184
	    %(host)s</literal></quote>.
185
	  </para>
186
	  <para>
187
	    In addition to normal start time expansion, this option
188
	    will also be subject to runtime expansion; see <xref
189
	    linkend="expansion"/>.
24.1.23 by Björn Påhlsson
Added manual pages for:
190
	  </para>
191
	</listitem>
192
      </varlistentry>
193
      
194
      <varlistentry>
195
	<term><literal>fingerprint</literal></term>
196
	<listitem>
94 by Teddy Hogeborn
* clients.conf ([DEFAULT]/checker): Update to new default value.
197
	  <synopsis><literal>fingerprint = </literal><replaceable
198
	  >HEXSTRING</replaceable>
199
	  </synopsis>
24.1.23 by Björn Påhlsson
Added manual pages for:
200
	  <para>
94 by Teddy Hogeborn
* clients.conf ([DEFAULT]/checker): Update to new default value.
201
	    This option sets the OpenPGP fingerprint that identifies
202
	    the public key that clients authenticate themselves with
203
	    through TLS.  The string needs to be in hexidecimal form,
204
	    but spaces or upper/lower case are not significant.
24.1.23 by Björn Påhlsson
Added manual pages for:
205
	  </para>
206
	</listitem>
207
      </varlistentry>
208
      
209
      <varlistentry>
210
	<term><literal>secret</literal></term>
211
	<listitem>
94 by Teddy Hogeborn
* clients.conf ([DEFAULT]/checker): Update to new default value.
212
	  <synopsis><literal>secret = </literal><replaceable
213
	  >BASE64_ENCODED_DATA</replaceable>
214
	  </synopsis>
215
	  <para>
216
	    If present, this option must be set to a string of
217
	    base64-encoded binary data.  It will be decoded and sent
218
	    to the client matching the above
219
	    <option>fingerprint</option>.  This should, of course, be
220
	    OpenPGP encrypted data, decryptable only by the client.
221
<!-- 	    The program <citerefentry><refentrytitle><command -->
222
<!-- 	    >mandos-keygen</command></refentrytitle><manvolnum -->
223
<!-- 	    >8</manvolnum></citerefentry> can be used to generate it, -->
224
<!-- 	    if desired. -->
225
	  </para>
226
	  <para>
227
	    Note: this value of this option will probably run over
228
	    many lines, and will then have to use the fact that a line
229
	    beginning with white space adds to the value of the
230
	    previous line, RFC 822-style.
24.1.23 by Björn Påhlsson
Added manual pages for:
231
	  </para>
232
	</listitem>
233
      </varlistentry>
234
235
      <varlistentry>
236
	<term><literal>secfile</literal></term>
237
	<listitem>
238
	  <para>
239
	    Base 64 encoded OpenPGP encrypted password encrypted by
240
	    the clients openpgp certificate as a binary file.
241
	  </para>
242
	</listitem>
243
      </varlistentry>
244
245
      <varlistentry>
51 by Teddy Hogeborn
* clients.conf: Better comments.
246
	<term><literal>host</literal></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
247
	<listitem>
248
	  <para>
51 by Teddy Hogeborn
* clients.conf: Better comments.
249
	    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:
250
	  </para>
251
	</listitem>
252
      </varlistentry>
253
254
      <varlistentry>
255
	<term><literal>checker</literal></term>
256
	<listitem>
257
	  <para>
24.1.24 by Björn Påhlsson
minor edits
258
	    Shell command that the server will use to check up if a
24.1.23 by Björn Påhlsson
Added manual pages for:
259
	    client is still up.
260
	  </para>
261
	</listitem>
262
      </varlistentry>      
263
264
      <varlistentry>
265
	<term><literal>timeout</literal></term>
266
	<listitem>
267
	  <para>
268
	    Duration that a client can be down whitout be removed from
269
	    the client list.
270
	  </para>
271
	</listitem>
272
      </varlistentry> 
273
      
274
    </variablelist>
275
  </refsect1>  
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
276
  
277
  <refsect1 id="expansion">
278
    <title>EXPANSION</title>
279
    <para>
280
      There are two forms of expansion: Start time expansion and
281
      runtime expansion.
282
    </para>
94 by Teddy Hogeborn
* clients.conf ([DEFAULT]/checker): Update to new default value.
283
    <refsect2 id="start_time_expansion">
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
284
      <title>START TIME EXPANSION</title>
285
      <para>
286
	Any string in an option value of the form
287
	<quote><literal>%(<replaceable>foo</replaceable>)s</literal
288
	></quote> will be replaced by the value of the option
289
	<varname>foo</varname> either in the same section, or, if it
290
	does not exist there, the <literal>[DEFAULT]</literal>
291
	section.  This is done at start time, when the configuration
292
	file is read.
293
      </para>
294
      <para>
295
	Note that this means that, in order to include an actual
296
	percent character (<quote>%</quote>) in an option value, two
297
	percent characters in a row (<quote>%%</quote>) must be
298
	entered.
299
      </para>
300
    </refsect2>
94 by Teddy Hogeborn
* clients.conf ([DEFAULT]/checker): Update to new default value.
301
    <refsect2 id="runtime_expansion">
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
302
      <title>RUNTIME EXPANSION</title>
303
      <para>
304
	This is currently only done for the <varname>checker</varname>
305
	option.
306
      </para>
307
      <para>
308
	Any string in an option value of the form
309
	<quote><literal>%%(<replaceable>foo</replaceable>)s</literal
310
	></quote> will be replaced by the value of the attribute
311
	<varname>foo</varname> of the internal
312
	<quote><classname>Client</classname></quote> object.  See the
313
	source code for details, and let the authors know of any
314
	attributes that are useful so they may be preserved to any new
315
	versions of this software.
316
      </para>
317
      <para>
318
	Note that this means that, in order to include an actual
319
	percent character (<quote>%</quote>) in a
320
	<varname>checker</varname> options, <emphasis>four</emphasis>
321
	percent characters in a row (<quote>%%%%</quote>) must be
322
	entered.  Also, a bad format here will lead to an immediate
323
	but <emphasis>silent</emphasis> run-time fatal exit; debug
324
	mode is needed to track down an error of this kind.
325
      </para>
326
    </refsect2>
24.1.23 by Björn Påhlsson
Added manual pages for:
327
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
328
  </refsect1>  
329
  
330
  <refsect1 id="files">
331
    <title>FILES</title>
332
    <para>
333
      The file described here is &CONFPATH;
334
    </para>
335
  </refsect1>
336
  
337
  <refsect1 id="bugs">
338
    <title>BUGS</title>
339
    <para>
340
      The format for specifying times for <varname>timeout</varname>
341
      and <varname>interval</varname> is not very good.
342
    </para>
343
    <para>
344
      The difference between
345
      <literal>%%(<replaceable>foo</replaceable>)s</literal> and
346
      <literal>%(<replaceable>foo</replaceable>)s</literal> is
347
      obscure.
348
    </para>
349
  </refsect1>
350
  
351
  <refsect1 id="example">
352
    <title>EXAMPLE</title>
24.1.23 by Björn Påhlsson
Added manual pages for:
353
    <informalexample>
354
      <programlisting>
355
[DEFAULT]
356
timeout = 1h
357
interval = 5m
94 by Teddy Hogeborn
* clients.conf ([DEFAULT]/checker): Update to new default value.
358
checker = fping -q -- %(host)s
24.1.23 by Björn Påhlsson
Added manual pages for:
359
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
360
# Client "foo"
361
[foo]
24.1.23 by Björn Påhlsson
Added manual pages for:
362
fingerprint =  7788 2722 5BA7 DE53 9C5A  7CFA 59CF F7CD BD9A 5920
363
secret =
24.1.24 by Björn Påhlsson
minor edits
364
        hQIOA6QdEjBs2L/HEAf/TCyrDe5Xnm9esa+Pb/vWF9CUqfn4srzVgSu234
365
        REJMVv7lBSrPE2132Lmd2gqF1HeLKDJRSVxJpt6xoWOChGHg+TMyXDxK+N
366
        Xl89vGvdU1XfhKkVm9MDLOgT5ECDPysDGHFPDhqHOSu3Kaw2DWMV/iH9vz
367
        3Z20erVNbdcvyBnuojcoWO/6yfB5EQO0BXp7kcyy00USA3CjD5FGZdoQGI
368
        Tb8A/ar0tVA5crSQmaSotm6KmNLhrFnZ5BxX+TiE+eTUTqSloWRY6VAvqW
369
        QHC7OASxK5E6RXPBuFH5IohUA2Qbk5AHt99pYvsIPX88j2rWauOokoiKZo
370
        t/9leJ8VxO5l3wf/U64IH8bkPIoWmWZfd/nqh4uwGNbCgKMyT+AnvH7kMJ
371
        3i7DivfWl2mKLV0PyPHUNva0VQxX6yYjcOhj1R6fCr/at8/NSLe2OhLchz
372
        dC+Ls9h+kvJXgF8Sisv+Wk/1RadPLFmraRlqvJwt6Ww21LpiXqXHV2mIgq
373
        WnR98YgSvUi3TJHrUQiNc9YyBzuRo0AjgG2C9qiE3FM+Y28+iQ/sR3+bFs
374
        zYuZKVTObqiIslwXu7imO0cvvFRgJF/6u3HNFQ4LUTGhiM3FQmC6NNlF3/
375
        vJM2hwRDMcJqDd54Twx90Wh+tYz0z7QMsK4ANXWHHWHR0JchnLWmenzbtW
376
        5MHdW9AYsNJZAQSOpirE4Xi31CSlWAi9KV+cUCmWF5zOFy1x23P6PjdaRm
377
        4T2zw4dxS5NswXWU0sVEXxjs6PYxuIiCTL7vdpx8QjBkrPWDrAbcMyBr2O
378
        QlnHIvPzEArRQLo=
379
        =iHhv
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
380
host = foo.example.org
24.1.23 by Björn Påhlsson
Added manual pages for:
381
interval = 5m
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
382
383
# Client "bar"
384
[bar]
385
fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27
386
secfile = /etc/mandos/bar-secret.txt.asc
387
24.1.23 by Björn Påhlsson
Added manual pages for:
388
      </programlisting>
389
    </informalexample>
390
  </refsect1>  
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
391
24.1.23 by Björn Påhlsson
Added manual pages for:
392
</refentry>