/mandos/trunk

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

« back to all changes in this revision

Viewing changes to mandos-clients.conf.xml

  • Committer: Teddy Hogeborn
  • Date: 2010-09-12 03:00:40 UTC
  • Revision ID: teddy@fukt.bsnet.se-20100912030040-b0uopyennste9fdh
Documentation changes:

* DBUS-API: New file documenting the server D-Bus interface.

* clients.conf: Add examples of new approval settings.

* debian/mandos.docs: Added "DBUS-API".

* mandos-clients.conf.xml (OPTIONS): Added "approved_by_default",
                                     "approval_delay", and
                                     "approval_duration".
* mandos.xml (D-BUS INTERFACE): Refer to the "DBUS-API" file.
  (BUGS): Remove mention of lack of a remote query interface.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos-clients.conf.xml
3
3
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
4
<!ENTITY CONFNAME "mandos-clients.conf">
5
5
<!ENTITY CONFPATH "<filename>/etc/mandos/clients.conf</filename>">
6
 
<!ENTITY TIMESTAMP "2017-02-23">
 
6
<!ENTITY TIMESTAMP "2010-09-12">
7
7
<!ENTITY % common SYSTEM "common.ent">
8
8
%common;
9
9
]>
20
20
        <firstname>Björn</firstname>
21
21
        <surname>Påhlsson</surname>
22
22
        <address>
23
 
          <email>belorn@recompile.se</email>
 
23
          <email>belorn@fukt.bsnet.se</email>
24
24
        </address>
25
25
      </author>
26
26
      <author>
27
27
        <firstname>Teddy</firstname>
28
28
        <surname>Hogeborn</surname>
29
29
        <address>
30
 
          <email>teddy@recompile.se</email>
 
30
          <email>teddy@fukt.bsnet.se</email>
31
31
        </address>
32
32
      </author>
33
33
    </authorgroup>
34
34
    <copyright>
35
35
      <year>2008</year>
36
36
      <year>2009</year>
37
 
      <year>2010</year>
38
 
      <year>2011</year>
39
 
      <year>2012</year>
40
 
      <year>2013</year>
41
 
      <year>2014</year>
42
 
      <year>2015</year>
43
 
      <year>2016</year>
44
 
      <year>2017</year>
45
37
      <holder>Teddy Hogeborn</holder>
46
38
      <holder>Björn Påhlsson</holder>
47
39
    </copyright>
71
63
      ><refentrytitle>mandos</refentrytitle>
72
64
      <manvolnum>8</manvolnum></citerefentry>, read by it at startup.
73
65
      The file needs to list all clients that should be able to use
74
 
      the service.  The settings in this file can be overridden by
75
 
      runtime changes to the server, which it saves across restarts.
76
 
      (See the section called <quote>PERSISTENT STATE</quote> in
77
 
      <citerefentry><refentrytitle>mandos</refentrytitle><manvolnum
78
 
      >8</manvolnum></citerefentry>.)  However, any <emphasis
79
 
      >changes</emphasis> to this file (including adding and removing
80
 
      clients) will, at startup, override changes done during runtime.
 
66
      the service.  All clients listed will be regarded as enabled,
 
67
      even if a client was disabled in a previous run of the server.
81
68
    </para>
82
69
    <para>
83
70
      The format starts with a <literal>[<replaceable>section
113
100
    <variablelist>
114
101
      
115
102
      <varlistentry>
116
 
        <term><option>approval_delay<literal> = </literal><replaceable
117
 
        >TIME</replaceable></option></term>
118
 
        <listitem>
119
 
          <para>
120
 
            This option is <emphasis>optional</emphasis>.
121
 
          </para>
122
 
          <para>
123
 
            How long to wait for external approval before resorting to
124
 
            use the <option>approved_by_default</option> value.  The
125
 
            default is <quote>PT0S</quote>, i.e. not to wait.
126
 
          </para>
127
 
          <para>
128
 
            The format of <replaceable>TIME</replaceable> is the same
129
 
            as for <varname>timeout</varname> below.
130
 
          </para>
131
 
        </listitem>
132
 
      </varlistentry>
133
 
      
134
 
      <varlistentry>
135
 
        <term><option>approval_duration<literal> = </literal
136
 
        ><replaceable>TIME</replaceable></option></term>
137
 
        <listitem>
138
 
          <para>
139
 
            This option is <emphasis>optional</emphasis>.
140
 
          </para>
141
 
          <para>
142
 
            How long an external approval lasts.  The default is 1
143
 
            second.
144
 
          </para>
145
 
          <para>
146
 
            The format of <replaceable>TIME</replaceable> is the same
147
 
            as for <varname>timeout</varname> below.
148
 
          </para>
149
 
        </listitem>
150
 
      </varlistentry>
151
 
      
152
 
      <varlistentry>
153
 
        <term><option>approved_by_default<literal> = </literal
154
 
          >{ <literal >1</literal> | <literal>yes</literal> | <literal
155
 
          >true</literal> | <literal>on</literal> | <literal
156
 
          >0</literal> | <literal>no</literal> | <literal
157
 
          >false</literal> | <literal>off</literal> }</option></term>
158
 
        <listitem>
159
 
          <para>
160
 
            Whether to approve a client by default after
161
 
            the <option>approval_delay</option>.  The default
162
 
            is <quote>True</quote>.
 
103
        <term><option>timeout<literal> = </literal><replaceable
 
104
        >TIME</replaceable></option></term>
 
105
        <listitem>
 
106
          <para>
 
107
            This option is <emphasis>optional</emphasis>.
 
108
          </para>
 
109
          <para>
 
110
            The timeout is how long the server will wait (for either a
 
111
            successful checker run or a client receiving its secret)
 
112
            until a client is disabled and not allowed to get the data
 
113
            this server holds.  By default Mandos will use 1 hour.
 
114
          </para>
 
115
          <para>
 
116
            The <replaceable>TIME</replaceable> is specified as a
 
117
            space-separated number of values, each of which is a
 
118
            number and a one-character suffix.  The suffix must be one
 
119
            of <quote>d</quote>, <quote>s</quote>, <quote>m</quote>,
 
120
            <quote>h</quote>, and <quote>w</quote> for days, seconds,
 
121
            minutes, hours, and weeks, respectively.  The values are
 
122
            added together to give the total time value, so all of
 
123
            <quote><literal>330s</literal></quote>,
 
124
            <quote><literal>110s 110s 110s</literal></quote>, and
 
125
            <quote><literal>5m 30s</literal></quote> will give a value
 
126
            of five minutes and thirty seconds.
 
127
          </para>
 
128
        </listitem>
 
129
      </varlistentry>
 
130
      
 
131
      <varlistentry>
 
132
        <term><option>interval<literal> = </literal><replaceable
 
133
        >TIME</replaceable></option></term>
 
134
        <listitem>
 
135
          <para>
 
136
            This option is <emphasis>optional</emphasis>.
 
137
          </para>
 
138
          <para>
 
139
            How often to run the checker to confirm that a client is
 
140
            still up.  <emphasis>Note:</emphasis> a new checker will
 
141
            not be started if an old one is still running.  The server
 
142
            will wait for a checker to complete until the above
 
143
            <quote><varname>timeout</varname></quote> occurs, at which
 
144
            time the client will be disabled, and any running checker
 
145
            killed.  The default interval is 5 minutes.
 
146
          </para>
 
147
          <para>
 
148
            The format of <replaceable>TIME</replaceable> is the same
 
149
            as for <varname>timeout</varname> above.
163
150
          </para>
164
151
        </listitem>
165
152
      </varlistentry>
172
159
            This option is <emphasis>optional</emphasis>.
173
160
          </para>
174
161
          <para>
175
 
            This option overrides the default shell command that the
176
 
            server will use to check if the client is still up.  Any
177
 
            output of the command will be ignored, only the exit code
178
 
            is checked:  If the exit code of the command is zero, the
179
 
            client is considered up.  The command will be run using
180
 
            <quote><command><filename>/bin/sh</filename>
 
162
            This option allows you to override the default shell
 
163
            command that the server will use to check if the client is
 
164
            still up.  Any output of the command will be ignored, only
 
165
            the exit code is checked:  If the exit code of the command
 
166
            is zero, the client is considered up.  The command will be
 
167
            run using <quote><command><filename>/bin/sh</filename>
181
168
            <option>-c</option></command></quote>, so
182
169
            <varname>PATH</varname> will be searched.  The default
183
170
            value for the checker command is <quote><literal
184
171
            ><command>fping</command> <option>-q</option> <option
185
 
            >--</option> %%(host)s</literal></quote>.  Note that
186
 
            <command>mandos-keygen</command>, when generating output
187
 
            to be inserted into this file, normally looks for an SSH
188
 
            server on the Mandos client, and, if it find one, outputs
189
 
            a <option>checker</option> option to check for the
190
 
            client’s key fingerprint – this is more secure against
191
 
            spoofing.
 
172
            >--</option> %%(host)s</literal></quote>.
192
173
          </para>
193
174
          <para>
194
175
            In addition to normal start time expansion, this option
199
180
      </varlistentry>
200
181
      
201
182
      <varlistentry>
202
 
        <term><option>extended_timeout<literal> = </literal><replaceable
203
 
        >TIME</replaceable></option></term>
204
 
        <listitem>
205
 
          <para>
206
 
            This option is <emphasis>optional</emphasis>.
207
 
          </para>
208
 
          <para>
209
 
            Extended timeout is an added timeout that is given once
210
 
            after a password has been sent successfully to a client.
211
 
            The timeout is by default longer than the normal timeout,
212
 
            and is used for handling the extra long downtime while a
213
 
            machine is booting up.  Time to take into consideration
214
 
            when changing this value is file system checks and quota
215
 
            checks.  The default value is 15 minutes.
216
 
          </para>
217
 
          <para>
218
 
            The format of <replaceable>TIME</replaceable> is the same
219
 
            as for <varname>timeout</varname> below.
220
 
          </para>
221
 
        </listitem>
222
 
      </varlistentry>
223
 
      
224
 
      <varlistentry>
225
183
        <term><option>fingerprint<literal> = </literal
226
184
        ><replaceable>HEXSTRING</replaceable></option></term>
227
185
        <listitem>
231
189
          <para>
232
190
            This option sets the OpenPGP fingerprint that identifies
233
191
            the public key that clients authenticate themselves with
234
 
            through TLS.  The string needs to be in hexadecimal form,
 
192
            through TLS.  The string needs to be in hexidecimal form,
235
193
            but spaces or upper/lower case are not significant.
236
194
          </para>
237
195
        </listitem>
238
196
      </varlistentry>
239
197
      
240
198
      <varlistentry>
241
 
        <term><option><literal>host = </literal><replaceable
242
 
        >STRING</replaceable></option></term>
243
 
        <listitem>
244
 
          <para>
245
 
            This option is <emphasis>optional</emphasis>, but highly
246
 
            <emphasis>recommended</emphasis> unless the
247
 
            <option>checker</option> option is modified to a
248
 
            non-standard value without <quote>%%(host)s</quote> in it.
249
 
          </para>
250
 
          <para>
251
 
            Host name for this client.  This is not used by the server
252
 
            directly, but can be, and is by default, used by the
253
 
            checker.  See the <option>checker</option> option.
254
 
          </para>
255
 
        </listitem>
256
 
      </varlistentry>
257
 
      
258
 
      <varlistentry>
259
 
        <term><option>interval<literal> = </literal><replaceable
260
 
        >TIME</replaceable></option></term>
261
 
        <listitem>
262
 
          <para>
263
 
            This option is <emphasis>optional</emphasis>.
264
 
          </para>
265
 
          <para>
266
 
            How often to run the checker to confirm that a client is
267
 
            still up.  <emphasis>Note:</emphasis> a new checker will
268
 
            not be started if an old one is still running.  The server
269
 
            will wait for a checker to complete until the below
270
 
            <quote><varname>timeout</varname></quote> occurs, at which
271
 
            time the client will be disabled, and any running checker
272
 
            killed.  The default interval is 2 minutes.
273
 
          </para>
274
 
          <para>
275
 
            The format of <replaceable>TIME</replaceable> is the same
276
 
            as for <varname>timeout</varname> below.
277
 
          </para>
278
 
        </listitem>
279
 
      </varlistentry>
280
 
      
281
 
      <varlistentry>
282
 
        <term><option>secfile<literal> = </literal><replaceable
283
 
        >FILENAME</replaceable></option></term>
284
 
        <listitem>
285
 
          <para>
286
 
            This option is only used if <option>secret</option> is not
287
 
            specified, in which case this option is
288
 
            <emphasis>required</emphasis>.
289
 
          </para>
290
 
          <para>
291
 
            Similar to the <option>secret</option>, except the secret
292
 
            data is in an external file.  The contents of the file
293
 
            should <emphasis>not</emphasis> be base64-encoded, but
294
 
            will be sent to clients verbatim.
295
 
          </para>
296
 
          <para>
297
 
            File names of the form <filename>~user/foo/bar</filename>
298
 
            and <filename>$<envar>ENVVAR</envar>/foo/bar</filename>
299
 
            are supported.
300
 
          </para>
301
 
        </listitem>
302
 
      </varlistentry>
303
 
      
304
 
      <varlistentry>
305
199
        <term><option>secret<literal> = </literal><replaceable
306
200
        >BASE64_ENCODED_DATA</replaceable></option></term>
307
201
        <listitem>
332
226
      </varlistentry>
333
227
      
334
228
      <varlistentry>
335
 
        <term><option>timeout<literal> = </literal><replaceable
 
229
        <term><option>secfile<literal> = </literal><replaceable
 
230
        >FILENAME</replaceable></option></term>
 
231
        <listitem>
 
232
          <para>
 
233
            This option is only used if <option>secret</option> is not
 
234
            specified, in which case this option is
 
235
            <emphasis>required</emphasis>.
 
236
          </para>
 
237
          <para>
 
238
            Similar to the <option>secret</option>, except the secret
 
239
            data is in an external file.  The contents of the file
 
240
            should <emphasis>not</emphasis> be base64-encoded, but
 
241
            will be sent to clients verbatim.
 
242
          </para>
 
243
          <para>
 
244
            File names of the form <filename>~user/foo/bar</filename>
 
245
            and <filename>$<envar>ENVVAR</envar>/foo/bar</filename>
 
246
            are supported.
 
247
          </para>
 
248
        </listitem>
 
249
      </varlistentry>
 
250
      
 
251
      <varlistentry>
 
252
        <term><option><literal>host = </literal><replaceable
 
253
        >STRING</replaceable></option></term>
 
254
        <listitem>
 
255
          <para>
 
256
            This option is <emphasis>optional</emphasis>, but highly
 
257
            <emphasis>recommended</emphasis> unless the
 
258
            <option>checker</option> option is modified to a
 
259
            non-standard value without <quote>%%(host)s</quote> in it.
 
260
          </para>
 
261
          <para>
 
262
            Host name for this client.  This is not used by the server
 
263
            directly, but can be, and is by default, used by the
 
264
            checker.  See the <option>checker</option> option.
 
265
          </para>
 
266
        </listitem>
 
267
      </varlistentry>
 
268
      
 
269
      <varlistentry>
 
270
        <term><option>approved_by_default<literal> = </literal
 
271
          >{ <literal >1</literal> | <literal>yes</literal> | <literal
 
272
          >true</literal> | <literal>on</literal> | <literal
 
273
          >0</literal> | <literal>no</literal> | <literal
 
274
          >false</literal> | <literal>off</literal> }</option></term>
 
275
        <listitem>
 
276
          <para>
 
277
            Whether to approve a client by default after
 
278
            the <option>approval_delay</option>.  The default
 
279
            is <quote>True</quote>.
 
280
          </para>
 
281
        </listitem>
 
282
      </varlistentry>
 
283
      
 
284
      <varlistentry>
 
285
        <term><option>approval_delay<literal> = </literal><replaceable
336
286
        >TIME</replaceable></option></term>
337
287
        <listitem>
338
288
          <para>
339
289
            This option is <emphasis>optional</emphasis>.
340
290
          </para>
341
291
          <para>
342
 
            The timeout is how long the server will wait, after a
343
 
            successful checker run, until a client is disabled and not
344
 
            allowed to get the data this server holds.  By default
345
 
            Mandos will use 5 minutes.  See also the
346
 
            <option>extended_timeout</option> option.
 
292
            How long to wait for external approval before resorting to
 
293
            use the <option>approved_by_default</option> value.  The
 
294
            default is <quote>0s</quote>, i.e. not to wait.
347
295
          </para>
348
296
          <para>
349
 
            The <replaceable>TIME</replaceable> is specified as an RFC
350
 
            3339 duration; for example
351
 
            <quote><literal>P1Y2M3DT4H5M6S</literal></quote> meaning
352
 
            one year, two months, three days, four hours, five
353
 
            minutes, and six seconds.  Some values can be omitted, see
354
 
            RFC 3339 Appendix A for details.
 
297
            The format of <replaceable>TIME</replaceable> is the same
 
298
            as for <varname>timeout</varname> above.
355
299
          </para>
356
300
        </listitem>
357
301
      </varlistentry>
358
302
      
359
303
      <varlistentry>
360
 
        <term><option>enabled<literal> = </literal>{ <literal
361
 
        >1</literal> | <literal>yes</literal> | <literal>true</literal
362
 
        > | <literal >on</literal> | <literal>0</literal> | <literal
363
 
        >no</literal> | <literal>false</literal> | <literal
364
 
        >off</literal> }</option></term>
 
304
        <term><option>approval_duration<literal> = </literal
 
305
        ><replaceable>TIME</replaceable></option></term>
365
306
        <listitem>
366
307
          <para>
367
 
            Whether this client should be enabled by default.  The
368
 
            default is <quote>true</quote>.
 
308
            This option is <emphasis>optional</emphasis>.
 
309
          </para>
 
310
          <para>
 
311
            How long an external approval lasts.  The default is 1
 
312
            second.
 
313
          </para>
 
314
          <para>
 
315
            The format of <replaceable>TIME</replaceable> is the same
 
316
            as for <varname>timeout</varname> above.
369
317
          </para>
370
318
        </listitem>
371
319
      </varlistentry>
408
356
        <quote><literal>%%(<replaceable>foo</replaceable>)s</literal
409
357
        ></quote> will be replaced by the value of the attribute
410
358
        <varname>foo</varname> of the internal
411
 
        <quote><classname>Client</classname></quote> object in the
412
 
        Mandos server.  The currently allowed values for
413
 
        <replaceable>foo</replaceable> are:
414
 
        <quote><literal>approval_delay</literal></quote>,
415
 
        <quote><literal>approval_duration</literal></quote>,
416
 
        <quote><literal>created</literal></quote>,
417
 
        <quote><literal>enabled</literal></quote>,
418
 
        <quote><literal>expires</literal></quote>,
419
 
        <quote><literal>fingerprint</literal></quote>,
420
 
        <quote><literal>host</literal></quote>,
421
 
        <quote><literal>interval</literal></quote>,
422
 
        <quote><literal>last_approval_request</literal></quote>,
423
 
        <quote><literal>last_checked_ok</literal></quote>,
424
 
        <quote><literal>last_enabled</literal></quote>,
425
 
        <quote><literal>name</literal></quote>,
426
 
        <quote><literal>timeout</literal></quote>, and, if using
427
 
        D-Bus, <quote><literal>dbus_object_path</literal></quote>.
428
 
        See the source code for details.  <emphasis role="strong"
429
 
        >Currently, <emphasis>none</emphasis> of these attributes
430
 
        except <quote><literal>host</literal></quote> are guaranteed
431
 
        to be valid in future versions.</emphasis> Therefore, please
432
 
        let the authors know of any attributes that are useful so they
433
 
        may be preserved to any new versions of this software.
 
359
        <quote><classname>Client</classname></quote> object.  See the
 
360
        source code for details, and let the authors know of any
 
361
        attributes that are useful so they may be preserved to any new
 
362
        versions of this software.
434
363
      </para>
435
364
      <para>
436
365
        Note that this means that, in order to include an actual
464
393
      <literal>%(<replaceable>foo</replaceable>)s</literal> is
465
394
      obscure.
466
395
    </para>
467
 
    <xi:include href="bugs.xml"/>
468
396
  </refsect1>
469
397
  
470
398
  <refsect1 id="example">
472
400
    <informalexample>
473
401
      <programlisting>
474
402
[DEFAULT]
475
 
timeout = PT5M
476
 
interval = PT2M
 
403
timeout = 1h
 
404
interval = 5m
477
405
checker = fping -q -- %%(host)s
478
406
 
479
407
# Client "foo"
496
424
        4T2zw4dxS5NswXWU0sVEXxjs6PYxuIiCTL7vdpx8QjBkrPWDrAbcMyBr2O
497
425
        QlnHIvPzEArRQLo=
498
426
host = foo.example.org
499
 
interval = PT1M
 
427
interval = 1m
500
428
 
501
429
# Client "bar"
502
430
[bar]
503
431
fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27
504
432
secfile = /etc/mandos/bar-secret
505
 
timeout = PT15M
 
433
timeout = 15m
506
434
approved_by_default = False
507
 
approval_delay = PT30S
 
435
approval_delay = 30s
508
436
      </programlisting>
509
437
    </informalexample>
510
438
  </refsect1>
512
440
  <refsect1 id="see_also">
513
441
    <title>SEE ALSO</title>
514
442
    <para>
515
 
      <citerefentry><refentrytitle>intro</refentrytitle>
516
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
517
443
      <citerefentry><refentrytitle>mandos-keygen</refentrytitle>
518
444
      <manvolnum>8</manvolnum></citerefentry>,
519
445
      <citerefentry><refentrytitle>mandos.conf</refentrytitle>
520
446
      <manvolnum>5</manvolnum></citerefentry>,
521
447
      <citerefentry><refentrytitle>mandos</refentrytitle>
522
 
      <manvolnum>8</manvolnum></citerefentry>,
523
 
      <citerefentry><refentrytitle>fping</refentrytitle>
524
448
      <manvolnum>8</manvolnum></citerefentry>
525
449
    </para>
526
 
    <variablelist>
527
 
      <varlistentry>
528
 
        <term>
529
 
          RFC 3339: <citetitle>Date and Time on the Internet:
530
 
          Timestamps</citetitle>
531
 
        </term>
532
 
      <listitem>
533
 
        <para>
534
 
          The time intervals are in the "duration" format, as
535
 
          specified in ABNF in Appendix A of RFC 3339.
536
 
        </para>
537
 
      </listitem>
538
 
      </varlistentry>
539
 
    </variablelist>
540
450
  </refsect1>
541
451
</refentry>
542
452
<!-- Local Variables: -->