/mandos/trunk

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/trunk
129 by Teddy Hogeborn
* mandos-clients.conf.xml: Changed all single quotes to double quotes
1
<?xml version="1.0" encoding="UTF-8"?>
24.1.23 by Björn Påhlsson
Added manual pages for:
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
24.1.24 by Björn Påhlsson
minor edits
4
<!ENTITY CONFNAME "mandos-clients.conf">
24.1.23 by Björn Påhlsson
Added manual pages for:
5
<!ENTITY CONFPATH "<filename>/etc/mandos/clients.conf</filename>">
821 by Teddy Hogeborn
Add bug reporting information to manual pages
6
<!ENTITY TIMESTAMP "2016-03-05">
217 by Teddy Hogeborn
* .bzrignore: Added "man" directory (created by "make install-html").
7
<!ENTITY % common SYSTEM "common.ent">
8
%common;
24.1.23 by Björn Påhlsson
Added manual pages for:
9
]>
10
131 by Teddy Hogeborn
* Makefile: Make all DocBook rules include legalnotice.xml as a
11
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
24.1.23 by Björn Påhlsson
Added manual pages for:
12
  <refentryinfo>
112 by Teddy Hogeborn
* mandos-clients.conf.xml (/refentry/refentryinfo/title): Changed to
13
    <title>Mandos Manual</title>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
14
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
112 by Teddy Hogeborn
* mandos-clients.conf.xml (/refentry/refentryinfo/title): Changed to
15
    <productname>Mandos</productname>
217 by Teddy Hogeborn
* .bzrignore: Added "man" directory (created by "make install-html").
16
    <productnumber>&version;</productnumber>
111 by Teddy Hogeborn
* mandos-clients.conf.xml (ENTITY TIMESTAMP): New. Automatically
17
    <date>&TIMESTAMP;</date>
24.1.23 by Björn Påhlsson
Added manual pages for:
18
    <authorgroup>
19
      <author>
20
	<firstname>Björn</firstname>
21
	<surname>Påhlsson</surname>
22
	<address>
505.1.2 by Teddy Hogeborn
Change "fukt.bsnet.se" to "recompile.se" throughout.
23
	  <email>belorn@recompile.se</email>
24.1.23 by Björn Påhlsson
Added manual pages for:
24
	</address>
25
      </author>
26
      <author>
27
	<firstname>Teddy</firstname>
28
	<surname>Hogeborn</surname>
29
	<address>
505.1.2 by Teddy Hogeborn
Change "fukt.bsnet.se" to "recompile.se" throughout.
30
	  <email>teddy@recompile.se</email>
24.1.23 by Björn Påhlsson
Added manual pages for:
31
	</address>
32
      </author>
33
    </authorgroup>
34
    <copyright>
35
      <year>2008</year>
246 by Teddy Hogeborn
* README: Update copyright year; add "2009".
36
      <year>2009</year>
444 by Teddy Hogeborn
Update copyright year to "2010" wherever appropriate.
37
      <year>2010</year>
466 by Teddy Hogeborn
Update copyright year to "2011" wherever appropriate.
38
      <year>2011</year>
544 by Teddy Hogeborn
Updated year in copyright notices.
39
      <year>2012</year>
778 by Teddy Hogeborn
Update copyright year.
40
      <year>2013</year>
41
      <year>2014</year>
42
      <year>2015</year>
807 by Teddy Hogeborn
Update copyright year.
43
      <year>2016</year>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
44
      <holder>Teddy Hogeborn</holder>
45
      <holder>Björn Påhlsson</holder>
24.1.23 by Björn Påhlsson
Added manual pages for:
46
    </copyright>
131 by Teddy Hogeborn
* Makefile: Make all DocBook rules include legalnotice.xml as a
47
    <xi:include href="legalnotice.xml"/>
24.1.23 by Björn Påhlsson
Added manual pages for:
48
  </refentryinfo>
182 by Teddy Hogeborn
* Makefile (install): Use "install-client-nokey".
49
  
24.1.23 by Björn Påhlsson
Added manual pages for:
50
  <refmeta>
51
    <refentrytitle>&CONFNAME;</refentrytitle>
52
    <manvolnum>5</manvolnum>
53
  </refmeta>
54
  
55
  <refnamediv>
56
    <refname><filename>&CONFNAME;</filename></refname>
57
    <refpurpose>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
58
      Configuration file for the Mandos server
24.1.23 by Björn Påhlsson
Added manual pages for:
59
    </refpurpose>
60
  </refnamediv>
182 by Teddy Hogeborn
* Makefile (install): Use "install-client-nokey".
61
  
24.1.23 by Björn Påhlsson
Added manual pages for:
62
  <refsynopsisdiv>
119 by Teddy Hogeborn
* mandos-clients.conf.xml (SYNOPSIS): Remove line breaks.
63
    <synopsis>&CONFPATH;</synopsis>
24.1.23 by Björn Påhlsson
Added manual pages for:
64
  </refsynopsisdiv>
182 by Teddy Hogeborn
* Makefile (install): Use "install-client-nokey".
65
  
24.1.23 by Björn Påhlsson
Added manual pages for:
66
  <refsect1 id="description">
67
    <title>DESCRIPTION</title>
68
    <para>
106 by Teddy Hogeborn
* mandos-clients.conf.xml (DESCRIPTION): Do not imply that this is the
69
      The file &CONFPATH; is a configuration file for <citerefentry
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
70
      ><refentrytitle>mandos</refentrytitle>
106 by Teddy Hogeborn
* mandos-clients.conf.xml (DESCRIPTION): Do not imply that this is the
71
      <manvolnum>8</manvolnum></citerefentry>, read by it at startup.
72
      The file needs to list all clients that should be able to use
546 by Teddy Hogeborn
* debian/rules (binary-common): Exclude network-hooks.d from
73
      the service.  The settings in this file can be overridden by
74
      runtime changes to the server, which it saves across restarts.
75
      (See the section called <quote>PERSISTENT STATE</quote> in
76
      <citerefentry><refentrytitle>mandos</refentrytitle><manvolnum
77
      >8</manvolnum></citerefentry>.)  However, any <emphasis
78
      >changes</emphasis> to this file (including adding and removing
79
      clients) will, at startup, override changes done during runtime.
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
80
    </para>
81
    <para>
94 by Teddy Hogeborn
* clients.conf ([DEFAULT]/checker): Update to new default value.
82
      The format starts with a <literal>[<replaceable>section
83
      header</replaceable>]</literal> which is either
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
84
      <literal>[DEFAULT]</literal> or <literal>[<replaceable>client
94 by Teddy Hogeborn
* clients.conf ([DEFAULT]/checker): Update to new default value.
85
      name</replaceable>]</literal>.  The <replaceable>client
86
      name</replaceable> can be anything, and is not tied to a host
87
      name.  Following the section header is any number of
88
      <quote><varname><replaceable>option</replaceable
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
89
      ></varname>=<replaceable>value</replaceable></quote> entries,
90
      with continuations in the style of RFC 822.  <quote><varname
91
      ><replaceable>option</replaceable></varname>: <replaceable
92
      >value</replaceable></quote> is also accepted.  Note that
93
      leading whitespace is removed from values.  Values can contain
94
      format strings which refer to other values in the same section,
94 by Teddy Hogeborn
* clients.conf ([DEFAULT]/checker): Update to new default value.
95
      or values in the <quote>DEFAULT</quote> section (see <xref
96
      linkend="expansion"/>).  Lines beginning with <quote>#</quote>
97
      or <quote>;</quote> are ignored and may be used to provide
98
      comments.
24.1.23 by Björn Påhlsson
Added manual pages for:
99
    </para>
100
  </refsect1>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
101
  
102
  <refsect1 id="options">
103
    <title>OPTIONS</title>
24.1.23 by Björn Påhlsson
Added manual pages for:
104
    <para>
106 by Teddy Hogeborn
* mandos-clients.conf.xml (DESCRIPTION): Do not imply that this is the
105
      <emphasis>Note:</emphasis> all option values are subject to
106
      start time expansion, see <xref linkend="expansion"/>.
107
    </para>
108
    <para>
156 by Teddy Hogeborn
* mandos-clients.conf.xml (OPTIONS): Improved spelling.
109
      Unknown options are ignored.  The used options are as follows:
24.1.23 by Björn Påhlsson
Added manual pages for:
110
    </para>
182 by Teddy Hogeborn
* Makefile (install): Use "install-client-nokey".
111
    
24.1.23 by Björn Påhlsson
Added manual pages for:
112
    <variablelist>
182 by Teddy Hogeborn
* Makefile (install): Use "install-client-nokey".
113
      
24.1.23 by Björn Påhlsson
Added manual pages for:
114
      <varlistentry>
438 by Teddy Hogeborn
* mandos (Client.runtime_expansions): New attribute containing the
115
	<term><option>approval_delay<literal> = </literal><replaceable
116
	>TIME</replaceable></option></term>
117
	<listitem>
118
	  <para>
119
	    This option is <emphasis>optional</emphasis>.
120
	  </para>
121
	  <para>
122
	    How long to wait for external approval before resorting to
123
	    use the <option>approved_by_default</option> value.  The
626 by Teddy Hogeborn
* Makefile (CFLAGS, LDFLAGS): Keep default flags from environment.
124
	    default is <quote>PT0S</quote>, i.e. not to wait.
438 by Teddy Hogeborn
* mandos (Client.runtime_expansions): New attribute containing the
125
	  </para>
126
	  <para>
127
	    The format of <replaceable>TIME</replaceable> is the same
128
	    as for <varname>timeout</varname> below.
129
	  </para>
130
	</listitem>
131
      </varlistentry>
132
      
133
      <varlistentry>
134
	<term><option>approval_duration<literal> = </literal
135
        ><replaceable>TIME</replaceable></option></term>
136
	<listitem>
137
	  <para>
138
	    This option is <emphasis>optional</emphasis>.
139
	  </para>
140
	  <para>
141
	    How long an external approval lasts.  The default is 1
142
	    second.
143
	  </para>
144
	  <para>
145
	    The format of <replaceable>TIME</replaceable> is the same
146
	    as for <varname>timeout</varname> below.
147
	  </para>
148
	</listitem>
149
      </varlistentry>
150
      
151
      <varlistentry>
152
	<term><option>approved_by_default<literal> = </literal
153
          >{ <literal >1</literal> | <literal>yes</literal> | <literal
154
	  >true</literal> | <literal>on</literal> | <literal
155
	  >0</literal> | <literal>no</literal> | <literal
156
	  >false</literal> | <literal>off</literal> }</option></term>
157
	<listitem>
158
	  <para>
159
	    Whether to approve a client by default after
160
	    the <option>approval_delay</option>.  The default
161
	    is <quote>True</quote>.
24.1.23 by Björn Påhlsson
Added manual pages for:
162
	  </para>
163
	</listitem>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
164
      </varlistentry>
182 by Teddy Hogeborn
* Makefile (install): Use "install-client-nokey".
165
      
24.1.23 by Björn Påhlsson
Added manual pages for:
166
      <varlistentry>
119 by Teddy Hogeborn
* mandos-clients.conf.xml (SYNOPSIS): Remove line breaks.
167
	<term><option>checker<literal> = </literal><replaceable
168
	>COMMAND</replaceable></option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
169
	<listitem>
170
	  <para>
150 by Teddy Hogeborn
* mandos-clients.conf.xml (OPTIONS): Add info to all options about
171
	    This option is <emphasis>optional</emphasis>.
172
	  </para>
173
	  <para>
590 by Teddy Hogeborn
* mandos: Change comment.
174
	    This option overrides the default shell command that the
175
	    server will use to check if the client is still up.  Any
176
	    output of the command will be ignored, only the exit code
177
	    is checked:  If the exit code of the command is zero, the
178
	    client is considered up.  The command will be run using
179
	    <quote><command><filename>/bin/sh</filename>
106 by Teddy Hogeborn
* mandos-clients.conf.xml (DESCRIPTION): Do not imply that this is the
180
	    <option>-c</option></command></quote>, so
181
	    <varname>PATH</varname> will be searched.  The default
182
	    value for the checker command is <quote><literal
183
	    ><command>fping</command> <option>-q</option> <option
708 by Teddy Hogeborn
mandos-keygen: Generate "checker" option to use SSH fingerprints.
184
	    >--</option> %%(host)s</literal></quote>.  Note that
185
	    <command>mandos-keygen</command>, when generating output
186
	    to be inserted into this file, normally looks for an SSH
187
	    server on the Mandos client, and, if it find one, outputs
188
	    a <option>checker</option> option to check for the
189
	    client’s key fingerprint – this is more secure against
190
	    spoofing.
94 by Teddy Hogeborn
* clients.conf ([DEFAULT]/checker): Update to new default value.
191
	  </para>
192
	  <para>
193
	    In addition to normal start time expansion, this option
194
	    will also be subject to runtime expansion; see <xref
195
	    linkend="expansion"/>.
24.1.23 by Björn Påhlsson
Added manual pages for:
196
	  </para>
197
	</listitem>
198
      </varlistentry>
199
      
200
      <varlistentry>
500 by Teddy Hogeborn
* mandos-clients.conf.xml (OPTIONS): Moved up "extended_timeout" to
201
	<term><option>extended_timeout<literal> = </literal><replaceable
202
	>TIME</replaceable></option></term>
203
	<listitem>
204
	  <para>
205
	    This option is <emphasis>optional</emphasis>.
206
	  </para>
207
	  <para>
208
	    Extended timeout is an added timeout that is given once
505.1.13 by Teddy Hogeborn
Miscellaneous fixes prompted by lintian:
209
	    after a password has been sent successfully to a client.
500 by Teddy Hogeborn
* mandos-clients.conf.xml (OPTIONS): Moved up "extended_timeout" to
210
	    The timeout is by default longer than the normal timeout,
211
	    and is used for handling the extra long downtime while a
212
	    machine is booting up.  Time to take into consideration
213
	    when changing this value is file system checks and quota
214
	    checks.  The default value is 15 minutes.
215
	  </para>
216
	  <para>
217
	    The format of <replaceable>TIME</replaceable> is the same
218
	    as for <varname>timeout</varname> below.
219
	  </para>
220
	</listitem>
221
      </varlistentry>
222
      
223
      <varlistentry>
119 by Teddy Hogeborn
* mandos-clients.conf.xml (SYNOPSIS): Remove line breaks.
224
	<term><option>fingerprint<literal> = </literal
225
	><replaceable>HEXSTRING</replaceable></option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
226
	<listitem>
227
	  <para>
150 by Teddy Hogeborn
* mandos-clients.conf.xml (OPTIONS): Add info to all options about
228
	    This option is <emphasis>required</emphasis>.
229
	  </para>
230
	  <para>
94 by Teddy Hogeborn
* clients.conf ([DEFAULT]/checker): Update to new default value.
231
	    This option sets the OpenPGP fingerprint that identifies
232
	    the public key that clients authenticate themselves with
233
	    through TLS.  The string needs to be in hexidecimal form,
234
	    but spaces or upper/lower case are not significant.
24.1.23 by Björn Påhlsson
Added manual pages for:
235
	  </para>
236
	</listitem>
237
      </varlistentry>
238
      
239
      <varlistentry>
438 by Teddy Hogeborn
* mandos (Client.runtime_expansions): New attribute containing the
240
	<term><option><literal>host = </literal><replaceable
241
	>STRING</replaceable></option></term>
242
	<listitem>
243
	  <para>
244
	    This option is <emphasis>optional</emphasis>, but highly
245
	    <emphasis>recommended</emphasis> unless the
246
	    <option>checker</option> option is modified to a
247
	    non-standard value without <quote>%%(host)s</quote> in it.
248
	  </para>
249
	  <para>
250
	    Host name for this client.  This is not used by the server
251
	    directly, but can be, and is by default, used by the
252
	    checker.  See the <option>checker</option> option.
253
	  </para>
254
	</listitem>
255
      </varlistentry>
256
      
257
      <varlistentry>
258
	<term><option>interval<literal> = </literal><replaceable
259
	>TIME</replaceable></option></term>
260
	<listitem>
261
	  <para>
262
	    This option is <emphasis>optional</emphasis>.
263
	  </para>
264
	  <para>
265
	    How often to run the checker to confirm that a client is
266
	    still up.  <emphasis>Note:</emphasis> a new checker will
267
	    not be started if an old one is still running.  The server
268
	    will wait for a checker to complete until the below
269
	    <quote><varname>timeout</varname></quote> occurs, at which
270
	    time the client will be disabled, and any running checker
24.1.179 by Björn Påhlsson
New feature:
271
	    killed.  The default interval is 2 minutes.
438 by Teddy Hogeborn
* mandos (Client.runtime_expansions): New attribute containing the
272
	  </para>
273
	  <para>
274
	    The format of <replaceable>TIME</replaceable> is the same
275
	    as for <varname>timeout</varname> below.
276
	  </para>
277
	</listitem>
278
      </varlistentry>
279
      
280
      <varlistentry>
281
	<term><option>secfile<literal> = </literal><replaceable
282
	>FILENAME</replaceable></option></term>
283
	<listitem>
284
	  <para>
285
	    This option is only used if <option>secret</option> is not
286
	    specified, in which case this option is
287
	    <emphasis>required</emphasis>.
288
	  </para>
289
	  <para>
290
	    Similar to the <option>secret</option>, except the secret
291
	    data is in an external file.  The contents of the file
292
	    should <emphasis>not</emphasis> be base64-encoded, but
293
	    will be sent to clients verbatim.
294
	  </para>
295
	  <para>
296
	    File names of the form <filename>~user/foo/bar</filename>
297
	    and <filename>$<envar>ENVVAR</envar>/foo/bar</filename>
298
	    are supported.
299
	  </para>
300
	</listitem>
301
      </varlistentry>
302
      
303
      <varlistentry>
119 by Teddy Hogeborn
* mandos-clients.conf.xml (SYNOPSIS): Remove line breaks.
304
	<term><option>secret<literal> = </literal><replaceable
305
	>BASE64_ENCODED_DATA</replaceable></option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
306
	<listitem>
94 by Teddy Hogeborn
* clients.conf ([DEFAULT]/checker): Update to new default value.
307
	  <para>
150 by Teddy Hogeborn
* mandos-clients.conf.xml (OPTIONS): Add info to all options about
308
	    If this option is not specified, the <option
309
	    >secfile</option> option is <emphasis>required</emphasis>
310
	    to be present.
311
	  </para>
312
	  <para>
94 by Teddy Hogeborn
* clients.conf ([DEFAULT]/checker): Update to new default value.
313
	    If present, this option must be set to a string of
314
	    base64-encoded binary data.  It will be decoded and sent
315
	    to the client matching the above
316
	    <option>fingerprint</option>.  This should, of course, be
317
	    OpenPGP encrypted data, decryptable only by the client.
106 by Teddy Hogeborn
* mandos-clients.conf.xml (DESCRIPTION): Do not imply that this is the
318
	    The program <citerefentry><refentrytitle><command
319
	    >mandos-keygen</command></refentrytitle><manvolnum
320
	    >8</manvolnum></citerefentry> can, using its
321
	    <option>--password</option> option, be used to generate
322
	    this, if desired.
323
	  </para>
324
	  <para>
325
	    Note: this value of this option will probably be very
326
	    long.  A useful feature to avoid having unreadably-long
327
	    lines is that a line beginning with white space adds to
328
	    the value of the previous line, RFC 822-style.
329
	  </para>
24.1.23 by Björn Påhlsson
Added manual pages for:
330
	</listitem>
331
      </varlistentry>
182 by Teddy Hogeborn
* Makefile (install): Use "install-client-nokey".
332
      
24.1.23 by Björn Påhlsson
Added manual pages for:
333
      <varlistentry>
438 by Teddy Hogeborn
* mandos (Client.runtime_expansions): New attribute containing the
334
	<term><option>timeout<literal> = </literal><replaceable
423 by Teddy Hogeborn
Documentation changes:
335
	>TIME</replaceable></option></term>
336
	<listitem>
337
	  <para>
338
	    This option is <emphasis>optional</emphasis>.
339
	  </para>
340
	  <para>
501 by Teddy Hogeborn
* mandos-clients.conf.xml (OPTIONS/timeout): No longer used when
341
	    The timeout is how long the server will wait, after a
342
	    successful checker run, until a client is disabled and not
343
	    allowed to get the data this server holds.  By default
344
	    Mandos will use 5 minutes.  See also the
345
	    <option>extended_timeout</option> option.
438 by Teddy Hogeborn
* mandos (Client.runtime_expansions): New attribute containing the
346
	  </para>
347
	  <para>
609 by Teddy Hogeborn
* clients.conf: Convert all time intervals to new RFC 3339 syntax.
348
	    The <replaceable>TIME</replaceable> is specified as an RFC
349
	    3339 duration; for example
350
	    <quote><literal>P1Y2M3DT4H5M6S</literal></quote> meaning
351
	    one year, two months, three days, four hours, five
352
	    minutes, and six seconds.  Some values can be omitted, see
353
	    RFC 3339 Appendix A for details.
423 by Teddy Hogeborn
Documentation changes:
354
	  </para>
355
	</listitem>
356
      </varlistentry>
357
      
518.2.3 by Teddy Hogeborn
Make "enabled" a client config option.
358
      <varlistentry>
359
	<term><option>enabled<literal> = </literal>{ <literal
360
	>1</literal> | <literal>yes</literal> |	<literal>true</literal
361
	> | <literal >on</literal> | <literal>0</literal> | <literal
362
	>no</literal> | <literal>false</literal> | <literal
363
	>off</literal> }</option></term>
364
	<listitem>
365
	  <para>
366
	    Whether this client should be enabled by default.  The
367
	    default is <quote>true</quote>.
368
	  </para>
369
	</listitem>
370
      </varlistentry>
371
      
24.1.23 by Björn Påhlsson
Added manual pages for:
372
    </variablelist>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
373
  </refsect1>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
374
  
375
  <refsect1 id="expansion">
376
    <title>EXPANSION</title>
377
    <para>
378
      There are two forms of expansion: Start time expansion and
379
      runtime expansion.
380
    </para>
94 by Teddy Hogeborn
* clients.conf ([DEFAULT]/checker): Update to new default value.
381
    <refsect2 id="start_time_expansion">
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
382
      <title>START TIME EXPANSION</title>
383
      <para>
384
	Any string in an option value of the form
385
	<quote><literal>%(<replaceable>foo</replaceable>)s</literal
386
	></quote> will be replaced by the value of the option
387
	<varname>foo</varname> either in the same section, or, if it
388
	does not exist there, the <literal>[DEFAULT]</literal>
389
	section.  This is done at start time, when the configuration
390
	file is read.
391
      </para>
392
      <para>
393
	Note that this means that, in order to include an actual
394
	percent character (<quote>%</quote>) in an option value, two
395
	percent characters in a row (<quote>%%</quote>) must be
396
	entered.
397
      </para>
398
    </refsect2>
94 by Teddy Hogeborn
* clients.conf ([DEFAULT]/checker): Update to new default value.
399
    <refsect2 id="runtime_expansion">
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
400
      <title>RUNTIME EXPANSION</title>
401
      <para>
402
	This is currently only done for the <varname>checker</varname>
403
	option.
404
      </para>
405
      <para>
406
	Any string in an option value of the form
407
	<quote><literal>%%(<replaceable>foo</replaceable>)s</literal
408
	></quote> will be replaced by the value of the attribute
409
	<varname>foo</varname> of the internal
449 by teddy at bsnet
* mandos-clients.conf.xml (EXPANSION/RUNTIME EXPANSION): List possible
410
	<quote><classname>Client</classname></quote> object in the
411
	Mandos server.  The currently allowed values for
412
	<replaceable>foo</replaceable> are:
413
	<quote><literal>approval_delay</literal></quote>,
414
	<quote><literal>approval_duration</literal></quote>,
415
	<quote><literal>created</literal></quote>,
416
	<quote><literal>enabled</literal></quote>,
584 by Teddy Hogeborn
* mandos (Client.runtime_expansions): Add "expires" and (bug fix)
417
	<quote><literal>expires</literal></quote>,
449 by teddy at bsnet
* mandos-clients.conf.xml (EXPANSION/RUNTIME EXPANSION): List possible
418
	<quote><literal>fingerprint</literal></quote>,
419
	<quote><literal>host</literal></quote>,
420
	<quote><literal>interval</literal></quote>,
421
	<quote><literal>last_approval_request</literal></quote>,
422
	<quote><literal>last_checked_ok</literal></quote>,
423
	<quote><literal>last_enabled</literal></quote>,
424
	<quote><literal>name</literal></quote>,
425
	<quote><literal>timeout</literal></quote>, and, if using
426
	D-Bus, <quote><literal>dbus_object_path</literal></quote>.
427
	See the source code for details.  <emphasis role="strong"
428
	>Currently, <emphasis>none</emphasis> of these attributes
429
	except <quote><literal>host</literal></quote> are guaranteed
430
	to be valid in future versions.</emphasis> Therefore, please
431
	let the authors know of any attributes that are useful so they
432
	may be preserved to any new versions of this software.
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
433
      </para>
434
      <para>
435
	Note that this means that, in order to include an actual
436
	percent character (<quote>%</quote>) in a
106 by Teddy Hogeborn
* mandos-clients.conf.xml (DESCRIPTION): Do not imply that this is the
437
	<varname>checker</varname> option, <emphasis>four</emphasis>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
438
	percent characters in a row (<quote>%%%%</quote>) must be
439
	entered.  Also, a bad format here will lead to an immediate
440
	but <emphasis>silent</emphasis> run-time fatal exit; debug
119 by Teddy Hogeborn
* mandos-clients.conf.xml (SYNOPSIS): Remove line breaks.
441
	mode is needed to expose an error of this kind.
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
442
      </para>
443
    </refsect2>
182 by Teddy Hogeborn
* Makefile (install): Use "install-client-nokey".
444
    
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
445
  </refsect1>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
446
  
447
  <refsect1 id="files">
448
    <title>FILES</title>
449
    <para>
450
      The file described here is &CONFPATH;
451
    </para>
452
  </refsect1>
453
  
454
  <refsect1 id="bugs">
455
    <title>BUGS</title>
456
    <para>
457
      The format for specifying times for <varname>timeout</varname>
458
      and <varname>interval</varname> is not very good.
459
    </para>
460
    <para>
461
      The difference between
462
      <literal>%%(<replaceable>foo</replaceable>)s</literal> and
463
      <literal>%(<replaceable>foo</replaceable>)s</literal> is
464
      obscure.
465
    </para>
821 by Teddy Hogeborn
Add bug reporting information to manual pages
466
    <xi:include href="bugs.xml"/>
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
467
  </refsect1>
468
  
469
  <refsect1 id="example">
470
    <title>EXAMPLE</title>
24.1.23 by Björn Påhlsson
Added manual pages for:
471
    <informalexample>
472
      <programlisting>
473
[DEFAULT]
609 by Teddy Hogeborn
* clients.conf: Convert all time intervals to new RFC 3339 syntax.
474
timeout = PT5M
475
interval = PT2M
257 by Teddy Hogeborn
Change the default value of the "checker" option command to make the
476
checker = fping -q -- %%(host)s
24.1.23 by Björn Påhlsson
Added manual pages for:
477
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
478
# Client "foo"
479
[foo]
24.1.23 by Björn Påhlsson
Added manual pages for:
480
fingerprint =  7788 2722 5BA7 DE53 9C5A  7CFA 59CF F7CD BD9A 5920
481
secret =
24.1.24 by Björn Påhlsson
minor edits
482
        hQIOA6QdEjBs2L/HEAf/TCyrDe5Xnm9esa+Pb/vWF9CUqfn4srzVgSu234
483
        REJMVv7lBSrPE2132Lmd2gqF1HeLKDJRSVxJpt6xoWOChGHg+TMyXDxK+N
484
        Xl89vGvdU1XfhKkVm9MDLOgT5ECDPysDGHFPDhqHOSu3Kaw2DWMV/iH9vz
485
        3Z20erVNbdcvyBnuojcoWO/6yfB5EQO0BXp7kcyy00USA3CjD5FGZdoQGI
486
        Tb8A/ar0tVA5crSQmaSotm6KmNLhrFnZ5BxX+TiE+eTUTqSloWRY6VAvqW
487
        QHC7OASxK5E6RXPBuFH5IohUA2Qbk5AHt99pYvsIPX88j2rWauOokoiKZo
488
        t/9leJ8VxO5l3wf/U64IH8bkPIoWmWZfd/nqh4uwGNbCgKMyT+AnvH7kMJ
489
        3i7DivfWl2mKLV0PyPHUNva0VQxX6yYjcOhj1R6fCr/at8/NSLe2OhLchz
490
        dC+Ls9h+kvJXgF8Sisv+Wk/1RadPLFmraRlqvJwt6Ww21LpiXqXHV2mIgq
491
        WnR98YgSvUi3TJHrUQiNc9YyBzuRo0AjgG2C9qiE3FM+Y28+iQ/sR3+bFs
492
        zYuZKVTObqiIslwXu7imO0cvvFRgJF/6u3HNFQ4LUTGhiM3FQmC6NNlF3/
493
        vJM2hwRDMcJqDd54Twx90Wh+tYz0z7QMsK4ANXWHHWHR0JchnLWmenzbtW
494
        5MHdW9AYsNJZAQSOpirE4Xi31CSlWAi9KV+cUCmWF5zOFy1x23P6PjdaRm
495
        4T2zw4dxS5NswXWU0sVEXxjs6PYxuIiCTL7vdpx8QjBkrPWDrAbcMyBr2O
496
        QlnHIvPzEArRQLo=
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
497
host = foo.example.org
609 by Teddy Hogeborn
* clients.conf: Convert all time intervals to new RFC 3339 syntax.
498
interval = PT1M
93 by Teddy Hogeborn
* mandos (string_to_delta): Accept a whitespace-separated sequence of
499
500
# Client "bar"
501
[bar]
502
fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27
106 by Teddy Hogeborn
* mandos-clients.conf.xml (DESCRIPTION): Do not imply that this is the
503
secfile = /etc/mandos/bar-secret
609 by Teddy Hogeborn
* clients.conf: Convert all time intervals to new RFC 3339 syntax.
504
timeout = PT15M
423 by Teddy Hogeborn
Documentation changes:
505
approved_by_default = False
609 by Teddy Hogeborn
* clients.conf: Convert all time intervals to new RFC 3339 syntax.
506
approval_delay = PT30S
24.1.23 by Björn Påhlsson
Added manual pages for:
507
      </programlisting>
508
    </informalexample>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
509
  </refsect1>
106 by Teddy Hogeborn
* mandos-clients.conf.xml (DESCRIPTION): Do not imply that this is the
510
  
511
  <refsect1 id="see_also">
512
    <title>SEE ALSO</title>
513
    <para>
493 by Teddy Hogeborn
* Makefile (DOCS): Added "intro.8mandos".
514
      <citerefentry><refentrytitle>intro</refentrytitle>
515
      <manvolnum>8mandos</manvolnum></citerefentry>,
114 by Teddy Hogeborn
* mandos-clients.conf.xml (SEE ALSO): Alphabetized, as per
516
      <citerefentry><refentrytitle>mandos-keygen</refentrytitle>
517
      <manvolnum>8</manvolnum></citerefentry>,
518
      <citerefentry><refentrytitle>mandos.conf</refentrytitle>
519
      <manvolnum>5</manvolnum></citerefentry>,
520
      <citerefentry><refentrytitle>mandos</refentrytitle>
590 by Teddy Hogeborn
* mandos: Change comment.
521
      <manvolnum>8</manvolnum></citerefentry>,
522
      <citerefentry><refentrytitle>fping</refentrytitle>
114 by Teddy Hogeborn
* mandos-clients.conf.xml (SEE ALSO): Alphabetized, as per
523
      <manvolnum>8</manvolnum></citerefentry>
106 by Teddy Hogeborn
* mandos-clients.conf.xml (DESCRIPTION): Do not imply that this is the
524
    </para>
609 by Teddy Hogeborn
* clients.conf: Convert all time intervals to new RFC 3339 syntax.
525
    <variablelist>
526
      <varlistentry>
527
	<term>
528
	  RFC 3339: <citetitle>Date and Time on the Internet:
529
	  Timestamps</citetitle>
530
	</term>
531
      <listitem>
532
	<para>
533
	  The time intervals are in the "duration" format, as
534
	  specified in ABNF in Appendix A of RFC 3339.
535
	</para>
536
      </listitem>
537
      </varlistentry>
538
    </variablelist>
106 by Teddy Hogeborn
* mandos-clients.conf.xml (DESCRIPTION): Do not imply that this is the
539
  </refsect1>
24.1.23 by Björn Påhlsson
Added manual pages for:
540
</refentry>
111 by Teddy Hogeborn
* mandos-clients.conf.xml (ENTITY TIMESTAMP): New. Automatically
541
<!-- Local Variables: -->
542
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
543
<!-- time-stamp-end: "[\"']>" -->
544
<!-- time-stamp-format: "%:y-%02m-%02d" -->
545
<!-- End: -->