/mandos/release

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/release

« back to all changes in this revision

Viewing changes to mandos-clients.conf.xml

* mandos-keygen (keygen): Warn about long key generation time.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos-clients.conf.xml
 
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 CONFNAME "mandos-clients.conf">
 
5
<!ENTITY CONFPATH "<filename>/etc/mandos/clients.conf</filename>">
 
6
<!ENTITY TIMESTAMP "2009-09-17">
 
7
<!ENTITY % common SYSTEM "common.ent">
 
8
%common;
 
9
]>
 
10
 
 
11
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
 
12
  <refentryinfo>
 
13
    <title>Mandos Manual</title>
 
14
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
 
15
    <productname>Mandos</productname>
 
16
    <productnumber>&version;</productnumber>
 
17
    <date>&TIMESTAMP;</date>
 
18
    <authorgroup>
 
19
      <author>
 
20
        <firstname>Björn</firstname>
 
21
        <surname>Påhlsson</surname>
 
22
        <address>
 
23
          <email>belorn@fukt.bsnet.se</email>
 
24
        </address>
 
25
      </author>
 
26
      <author>
 
27
        <firstname>Teddy</firstname>
 
28
        <surname>Hogeborn</surname>
 
29
        <address>
 
30
          <email>teddy@fukt.bsnet.se</email>
 
31
        </address>
 
32
      </author>
 
33
    </authorgroup>
 
34
    <copyright>
 
35
      <year>2008</year>
 
36
      <year>2009</year>
 
37
      <holder>Teddy Hogeborn</holder>
 
38
      <holder>Björn Påhlsson</holder>
 
39
    </copyright>
 
40
    <xi:include href="legalnotice.xml"/>
 
41
  </refentryinfo>
 
42
  
 
43
  <refmeta>
 
44
    <refentrytitle>&CONFNAME;</refentrytitle>
 
45
    <manvolnum>5</manvolnum>
 
46
  </refmeta>
 
47
  
 
48
  <refnamediv>
 
49
    <refname><filename>&CONFNAME;</filename></refname>
 
50
    <refpurpose>
 
51
      Configuration file for the Mandos server
 
52
    </refpurpose>
 
53
  </refnamediv>
 
54
  
 
55
  <refsynopsisdiv>
 
56
    <synopsis>&CONFPATH;</synopsis>
 
57
  </refsynopsisdiv>
 
58
  
 
59
  <refsect1 id="description">
 
60
    <title>DESCRIPTION</title>
 
61
    <para>
 
62
      The file &CONFPATH; is a configuration file for <citerefentry
 
63
      ><refentrytitle>mandos</refentrytitle>
 
64
      <manvolnum>8</manvolnum></citerefentry>, read by it at startup.
 
65
      The file needs to list all clients that should be able to use
 
66
      the service.  All clients listed will be regarded as valid, even
 
67
      if a client was declared invalid in a previous run of the
 
68
      server.
 
69
    </para>
 
70
    <para>
 
71
      The format starts with a <literal>[<replaceable>section
 
72
      header</replaceable>]</literal> which is either
 
73
      <literal>[DEFAULT]</literal> or <literal>[<replaceable>client
 
74
      name</replaceable>]</literal>.  The <replaceable>client
 
75
      name</replaceable> can be anything, and is not tied to a host
 
76
      name.  Following the section header is any number of
 
77
      <quote><varname><replaceable>option</replaceable
 
78
      ></varname>=<replaceable>value</replaceable></quote> entries,
 
79
      with continuations in the style of RFC 822.  <quote><varname
 
80
      ><replaceable>option</replaceable></varname>: <replaceable
 
81
      >value</replaceable></quote> is also accepted.  Note that
 
82
      leading whitespace is removed from values.  Values can contain
 
83
      format strings which refer to other values in the same section,
 
84
      or values in the <quote>DEFAULT</quote> section (see <xref
 
85
      linkend="expansion"/>).  Lines beginning with <quote>#</quote>
 
86
      or <quote>;</quote> are ignored and may be used to provide
 
87
      comments.
 
88
    </para>
 
89
  </refsect1>
 
90
  
 
91
  <refsect1 id="options">
 
92
    <title>OPTIONS</title>
 
93
    <para>
 
94
      <emphasis>Note:</emphasis> all option values are subject to
 
95
      start time expansion, see <xref linkend="expansion"/>.
 
96
    </para>
 
97
    <para>
 
98
      Unknown options are ignored.  The used options are as follows:
 
99
    </para>
 
100
    
 
101
    <variablelist>
 
102
      
 
103
      <varlistentry>
 
104
        <term><option>timeout<literal> = </literal><replaceable
 
105
        >TIME</replaceable></option></term>
 
106
        <listitem>
 
107
          <para>
 
108
            This option is <emphasis>optional</emphasis>.
 
109
          </para>
 
110
          <para>
 
111
            The timeout is how long the server will wait (for either a
 
112
            successful checker run or a client receiving its secret)
 
113
            until a client is considered invalid - that is, ineligible
 
114
            to get the data this server holds.  By default Mandos will
 
115
            use 1 hour.
 
116
          </para>
 
117
          <para>
 
118
            The <replaceable>TIME</replaceable> is specified as a
 
119
            space-separated number of values, each of which is a
 
120
            number and a one-character suffix.  The suffix must be one
 
121
            of <quote>d</quote>, <quote>s</quote>, <quote>m</quote>,
 
122
            <quote>h</quote>, and <quote>w</quote> for days, seconds,
 
123
            minutes, hours, and weeks, respectively.  The values are
 
124
            added together to give the total time value, so all of
 
125
            <quote><literal>330s</literal></quote>,
 
126
            <quote><literal>110s 110s 110s</literal></quote>, and
 
127
            <quote><literal>5m 30s</literal></quote> will give a value
 
128
            of five minutes and thirty seconds.
 
129
          </para>
 
130
        </listitem>
 
131
      </varlistentry>
 
132
      
 
133
      <varlistentry>
 
134
        <term><option>interval<literal> = </literal><replaceable
 
135
        >TIME</replaceable></option></term>
 
136
        <listitem>
 
137
          <para>
 
138
            This option is <emphasis>optional</emphasis>.
 
139
          </para>
 
140
          <para>
 
141
            How often to run the checker to confirm that a client is
 
142
            still up.  <emphasis>Note:</emphasis> a new checker will
 
143
            not be started if an old one is still running.  The server
 
144
            will wait for a checker to complete until the above
 
145
            <quote><varname>timeout</varname></quote> occurs, at which
 
146
            time the client will be marked invalid, and any running
 
147
            checker killed.  The default interval is 5 minutes.
 
148
          </para>
 
149
          <para>
 
150
            The format of <replaceable>TIME</replaceable> is the same
 
151
            as for <varname>timeout</varname> above.
 
152
          </para>
 
153
        </listitem>
 
154
      </varlistentry>
 
155
      
 
156
      <varlistentry>
 
157
        <term><option>checker<literal> = </literal><replaceable
 
158
        >COMMAND</replaceable></option></term>
 
159
        <listitem>
 
160
          <para>
 
161
            This option is <emphasis>optional</emphasis>.
 
162
          </para>
 
163
          <para>
 
164
            This option allows you to override the default shell
 
165
            command that the server will use to check if the client is
 
166
            still up.  Any output of the command will be ignored, only
 
167
            the exit code is checked:  If the exit code of the command
 
168
            is zero, the client is considered up.  The command will be
 
169
            run using <quote><command><filename>/bin/sh</filename>
 
170
            <option>-c</option></command></quote>, so
 
171
            <varname>PATH</varname> will be searched.  The default
 
172
            value for the checker command is <quote><literal
 
173
            ><command>fping</command> <option>-q</option> <option
 
174
            >--</option> %%(host)s</literal></quote>.
 
175
          </para>
 
176
          <para>
 
177
            In addition to normal start time expansion, this option
 
178
            will also be subject to runtime expansion; see <xref
 
179
            linkend="expansion"/>.
 
180
          </para>
 
181
        </listitem>
 
182
      </varlistentry>
 
183
      
 
184
      <varlistentry>
 
185
        <term><option>fingerprint<literal> = </literal
 
186
        ><replaceable>HEXSTRING</replaceable></option></term>
 
187
        <listitem>
 
188
          <para>
 
189
            This option is <emphasis>required</emphasis>.
 
190
          </para>
 
191
          <para>
 
192
            This option sets the OpenPGP fingerprint that identifies
 
193
            the public key that clients authenticate themselves with
 
194
            through TLS.  The string needs to be in hexidecimal form,
 
195
            but spaces or upper/lower case are not significant.
 
196
          </para>
 
197
        </listitem>
 
198
      </varlistentry>
 
199
      
 
200
      <varlistentry>
 
201
        <term><option>secret<literal> = </literal><replaceable
 
202
        >BASE64_ENCODED_DATA</replaceable></option></term>
 
203
        <listitem>
 
204
          <para>
 
205
            If this option is not specified, the <option
 
206
            >secfile</option> option is <emphasis>required</emphasis>
 
207
            to be present.
 
208
          </para>
 
209
          <para>
 
210
            If present, this option must be set to a string of
 
211
            base64-encoded binary data.  It will be decoded and sent
 
212
            to the client matching the above
 
213
            <option>fingerprint</option>.  This should, of course, be
 
214
            OpenPGP encrypted data, decryptable only by the client.
 
215
            The program <citerefentry><refentrytitle><command
 
216
            >mandos-keygen</command></refentrytitle><manvolnum
 
217
            >8</manvolnum></citerefentry> can, using its
 
218
            <option>--password</option> option, be used to generate
 
219
            this, if desired.
 
220
          </para>
 
221
          <para>
 
222
            Note: this value of this option will probably be very
 
223
            long.  A useful feature to avoid having unreadably-long
 
224
            lines is that a line beginning with white space adds to
 
225
            the value of the previous line, RFC 822-style.
 
226
          </para>
 
227
        </listitem>
 
228
      </varlistentry>
 
229
      
 
230
      <varlistentry>
 
231
        <term><option>secfile<literal> = </literal><replaceable
 
232
        >FILENAME</replaceable></option></term>
 
233
        <listitem>
 
234
          <para>
 
235
            This option is only used if <option>secret</option> is not
 
236
            specified, in which case this option is
 
237
            <emphasis>required</emphasis>.
 
238
          </para>
 
239
          <para>
 
240
            Similar to the <option>secret</option>, except the secret
 
241
            data is in an external file.  The contents of the file
 
242
            should <emphasis>not</emphasis> be base64-encoded, but
 
243
            will be sent to clients verbatim.
 
244
          </para>
 
245
          <para>
 
246
            File names of the form <filename>~user/foo/bar</filename>
 
247
            and <filename>$<envar>ENVVAR</envar>/foo/bar</filename>
 
248
            are supported.
 
249
          </para>
 
250
        </listitem>
 
251
      </varlistentry>
 
252
      
 
253
      <varlistentry>
 
254
        <term><option><literal>host = </literal><replaceable
 
255
        >STRING</replaceable></option></term>
 
256
        <listitem>
 
257
          <para>
 
258
            This option is <emphasis>optional</emphasis>, but highly
 
259
            <emphasis>recommended</emphasis> unless the
 
260
            <option>checker</option> option is modified to a
 
261
            non-standard value without <quote>%%(host)s</quote> in it.
 
262
          </para>
 
263
          <para>
 
264
            Host name for this client.  This is not used by the server
 
265
            directly, but can be, and is by default, used by the
 
266
            checker.  See the <option>checker</option> option.
 
267
          </para>
 
268
        </listitem>
 
269
      </varlistentry>
 
270
      
 
271
    </variablelist>
 
272
  </refsect1>
 
273
  
 
274
  <refsect1 id="expansion">
 
275
    <title>EXPANSION</title>
 
276
    <para>
 
277
      There are two forms of expansion: Start time expansion and
 
278
      runtime expansion.
 
279
    </para>
 
280
    <refsect2 id="start_time_expansion">
 
281
      <title>START TIME EXPANSION</title>
 
282
      <para>
 
283
        Any string in an option value of the form
 
284
        <quote><literal>%(<replaceable>foo</replaceable>)s</literal
 
285
        ></quote> will be replaced by the value of the option
 
286
        <varname>foo</varname> either in the same section, or, if it
 
287
        does not exist there, the <literal>[DEFAULT]</literal>
 
288
        section.  This is done at start time, when the configuration
 
289
        file is read.
 
290
      </para>
 
291
      <para>
 
292
        Note that this means that, in order to include an actual
 
293
        percent character (<quote>%</quote>) in an option value, two
 
294
        percent characters in a row (<quote>%%</quote>) must be
 
295
        entered.
 
296
      </para>
 
297
    </refsect2>
 
298
    <refsect2 id="runtime_expansion">
 
299
      <title>RUNTIME EXPANSION</title>
 
300
      <para>
 
301
        This is currently only done for the <varname>checker</varname>
 
302
        option.
 
303
      </para>
 
304
      <para>
 
305
        Any string in an option value of the form
 
306
        <quote><literal>%%(<replaceable>foo</replaceable>)s</literal
 
307
        ></quote> will be replaced by the value of the attribute
 
308
        <varname>foo</varname> of the internal
 
309
        <quote><classname>Client</classname></quote> object.  See the
 
310
        source code for details, and let the authors know of any
 
311
        attributes that are useful so they may be preserved to any new
 
312
        versions of this software.
 
313
      </para>
 
314
      <para>
 
315
        Note that this means that, in order to include an actual
 
316
        percent character (<quote>%</quote>) in a
 
317
        <varname>checker</varname> option, <emphasis>four</emphasis>
 
318
        percent characters in a row (<quote>%%%%</quote>) must be
 
319
        entered.  Also, a bad format here will lead to an immediate
 
320
        but <emphasis>silent</emphasis> run-time fatal exit; debug
 
321
        mode is needed to expose an error of this kind.
 
322
      </para>
 
323
    </refsect2>
 
324
    
 
325
  </refsect1>
 
326
  
 
327
  <refsect1 id="files">
 
328
    <title>FILES</title>
 
329
    <para>
 
330
      The file described here is &CONFPATH;
 
331
    </para>
 
332
  </refsect1>
 
333
  
 
334
  <refsect1 id="bugs">
 
335
    <title>BUGS</title>
 
336
    <para>
 
337
      The format for specifying times for <varname>timeout</varname>
 
338
      and <varname>interval</varname> is not very good.
 
339
    </para>
 
340
    <para>
 
341
      The difference between
 
342
      <literal>%%(<replaceable>foo</replaceable>)s</literal> and
 
343
      <literal>%(<replaceable>foo</replaceable>)s</literal> is
 
344
      obscure.
 
345
    </para>
 
346
  </refsect1>
 
347
  
 
348
  <refsect1 id="example">
 
349
    <title>EXAMPLE</title>
 
350
    <informalexample>
 
351
      <programlisting>
 
352
[DEFAULT]
 
353
timeout = 1h
 
354
interval = 5m
 
355
checker = fping -q -- %%(host)s
 
356
 
 
357
# Client "foo"
 
358
[foo]
 
359
fingerprint =  7788 2722 5BA7 DE53 9C5A  7CFA 59CF F7CD BD9A 5920
 
360
secret =
 
361
        hQIOA6QdEjBs2L/HEAf/TCyrDe5Xnm9esa+Pb/vWF9CUqfn4srzVgSu234
 
362
        REJMVv7lBSrPE2132Lmd2gqF1HeLKDJRSVxJpt6xoWOChGHg+TMyXDxK+N
 
363
        Xl89vGvdU1XfhKkVm9MDLOgT5ECDPysDGHFPDhqHOSu3Kaw2DWMV/iH9vz
 
364
        3Z20erVNbdcvyBnuojcoWO/6yfB5EQO0BXp7kcyy00USA3CjD5FGZdoQGI
 
365
        Tb8A/ar0tVA5crSQmaSotm6KmNLhrFnZ5BxX+TiE+eTUTqSloWRY6VAvqW
 
366
        QHC7OASxK5E6RXPBuFH5IohUA2Qbk5AHt99pYvsIPX88j2rWauOokoiKZo
 
367
        t/9leJ8VxO5l3wf/U64IH8bkPIoWmWZfd/nqh4uwGNbCgKMyT+AnvH7kMJ
 
368
        3i7DivfWl2mKLV0PyPHUNva0VQxX6yYjcOhj1R6fCr/at8/NSLe2OhLchz
 
369
        dC+Ls9h+kvJXgF8Sisv+Wk/1RadPLFmraRlqvJwt6Ww21LpiXqXHV2mIgq
 
370
        WnR98YgSvUi3TJHrUQiNc9YyBzuRo0AjgG2C9qiE3FM+Y28+iQ/sR3+bFs
 
371
        zYuZKVTObqiIslwXu7imO0cvvFRgJF/6u3HNFQ4LUTGhiM3FQmC6NNlF3/
 
372
        vJM2hwRDMcJqDd54Twx90Wh+tYz0z7QMsK4ANXWHHWHR0JchnLWmenzbtW
 
373
        5MHdW9AYsNJZAQSOpirE4Xi31CSlWAi9KV+cUCmWF5zOFy1x23P6PjdaRm
 
374
        4T2zw4dxS5NswXWU0sVEXxjs6PYxuIiCTL7vdpx8QjBkrPWDrAbcMyBr2O
 
375
        QlnHIvPzEArRQLo=
 
376
host = foo.example.org
 
377
interval = 1m
 
378
 
 
379
# Client "bar"
 
380
[bar]
 
381
fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27
 
382
secfile = /etc/mandos/bar-secret
 
383
timeout = 15m
 
384
      </programlisting>
 
385
    </informalexample>
 
386
  </refsect1>
 
387
  
 
388
  <refsect1 id="see_also">
 
389
    <title>SEE ALSO</title>
 
390
    <para>
 
391
      <citerefentry><refentrytitle>mandos-keygen</refentrytitle>
 
392
      <manvolnum>8</manvolnum></citerefentry>,
 
393
      <citerefentry><refentrytitle>mandos.conf</refentrytitle>
 
394
      <manvolnum>5</manvolnum></citerefentry>,
 
395
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
396
      <manvolnum>8</manvolnum></citerefentry>
 
397
    </para>
 
398
  </refsect1>
 
399
</refentry>
 
400
<!-- Local Variables: -->
 
401
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
 
402
<!-- time-stamp-end: "[\"']>" -->
 
403
<!-- time-stamp-format: "%:y-%02m-%02d" -->
 
404
<!-- End: -->