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
- browse files at revision 506
- compare with another revision
- download diff
- download tarball
- view history from revision 506
- Committer: Teddy Hogeborn
- Date: 2011-10-03 16:17:11 UTC
- mfrom: (505.1.1 teddy)
- Revision ID: teddy@recompile.se-20111003161711-q9bjy1hlov9xanxh
Some cleanup
- files added:
- DBUS-API
- debian/source
- files modified:
- .bzrignore
added
removed
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 "2009-01-08">
6
<!ENTITY TIMESTAMP "2011-09-24">
7
7
<!ENTITY % common SYSTEM "common.ent">
8
8
%common;
9
9
]>
34
34
<copyright>
35
35
<year>2008</year>
36
36
<year>2009</year>
37
<year>2010</year>
38
<year>2011</year>
37
39
<holder>Teddy Hogeborn</holder>
38
40
<holder>Björn Påhlsson</holder>
39
41
</copyright>
63
65
><refentrytitle>mandos</refentrytitle>
64
66
<manvolnum>8</manvolnum></citerefentry>, read by it at startup.
65
67
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.
68
the service. All clients listed will be regarded as enabled,
69
even if a client was disabled in a previous run of the server.
69
70
</para>
70
71
<para>
71
72
The format starts with a <literal>[<replaceable>section
101
102
<variablelist>
102
103
103
104
<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 a
112
successful checker run until a client is considered
113
invalid - that is, ineligible to get the data this server
114
holds. By default Mandos will use 1 hour.
115
</para>
116
<para>
117
The <replaceable>TIME</replaceable> is specified as a
118
space-separated number of values, each of which is a
119
number and a one-character suffix. The suffix must be one
120
of <quote>d</quote>, <quote>s</quote>, <quote>m</quote>,
121
<quote>h</quote>, and <quote>w</quote> for days, seconds,
122
minutes, hours, and weeks, respectively. The values are
123
added together to give the total time value, so all of
124
<quote><literal>330s</literal></quote>,
125
<quote><literal>110s 110s 110s</literal></quote>, and
126
<quote><literal>5m 30s</literal></quote> will give a value
127
of five minutes and thirty seconds.
128
</para>
129
</listitem>
130
</varlistentry>
131
132
<varlistentry>
133
<term><option>interval<literal> = </literal><replaceable
134
>TIME</replaceable></option></term>
135
<listitem>
136
<para>
137
This option is <emphasis>optional</emphasis>.
138
</para>
139
<para>
140
How often to run the checker to confirm that a client is
141
still up. <emphasis>Note:</emphasis> a new checker will
142
not be started if an old one is still running. The server
143
will wait for a checker to complete until the above
144
<quote><varname>timeout</varname></quote> occurs, at which
145
time the client will be marked invalid, and any running
146
checker killed. The default interval is 5 minutes.
147
</para>
148
<para>
149
The format of <replaceable>TIME</replaceable> is the same
150
as for <varname>timeout</varname> above.
105
<term><option>approval_delay<literal> = </literal><replaceable
106
>TIME</replaceable></option></term>
107
<listitem>
108
<para>
109
This option is <emphasis>optional</emphasis>.
110
</para>
111
<para>
112
How long to wait for external approval before resorting to
113
use the <option>approved_by_default</option> value. The
114
default is <quote>0s</quote>, i.e. not to wait.
115
</para>
116
<para>
117
The format of <replaceable>TIME</replaceable> is the same
118
as for <varname>timeout</varname> below.
119
</para>
120
</listitem>
121
</varlistentry>
122
123
<varlistentry>
124
<term><option>approval_duration<literal> = </literal
125
><replaceable>TIME</replaceable></option></term>
126
<listitem>
127
<para>
128
This option is <emphasis>optional</emphasis>.
129
</para>
130
<para>
131
How long an external approval lasts. The default is 1
132
second.
133
</para>
134
<para>
135
The format of <replaceable>TIME</replaceable> is the same
136
as for <varname>timeout</varname> below.
137
</para>
138
</listitem>
139
</varlistentry>
140
141
<varlistentry>
142
<term><option>approved_by_default<literal> = </literal
143
>{ <literal >1</literal> | <literal>yes</literal> | <literal
144
>true</literal> | <literal>on</literal> | <literal
145
>0</literal> | <literal>no</literal> | <literal
146
>false</literal> | <literal>off</literal> }</option></term>
147
<listitem>
148
<para>
149
Whether to approve a client by default after
150
the <option>approval_delay</option>. The default
151
is <quote>True</quote>.
151
152
</para>
152
153
</listitem>
153
154
</varlistentry>
181
182
</varlistentry>
182
183
183
184
<varlistentry>
185
<term><option>extended_timeout<literal> = </literal><replaceable
186
>TIME</replaceable></option></term>
187
<listitem>
188
<para>
189
This option is <emphasis>optional</emphasis>.
190
</para>
191
<para>
192
Extended timeout is an added timeout that is given once
193
after a password has been sent sucessfully to a client.
194
The timeout is by default longer than the normal timeout,
195
and is used for handling the extra long downtime while a
196
machine is booting up. Time to take into consideration
197
when changing this value is file system checks and quota
198
checks. The default value is 15 minutes.
199
</para>
200
<para>
201
The format of <replaceable>TIME</replaceable> is the same
202
as for <varname>timeout</varname> below.
203
</para>
204
</listitem>
205
</varlistentry>
206
207
<varlistentry>
184
208
<term><option>fingerprint<literal> = </literal
185
209
><replaceable>HEXSTRING</replaceable></option></term>
186
210
<listitem>
197
221
</varlistentry>
198
222
199
223
<varlistentry>
224
<term><option><literal>host = </literal><replaceable
225
>STRING</replaceable></option></term>
226
<listitem>
227
<para>
228
This option is <emphasis>optional</emphasis>, but highly
229
<emphasis>recommended</emphasis> unless the
230
<option>checker</option> option is modified to a
231
non-standard value without <quote>%%(host)s</quote> in it.
232
</para>
233
<para>
234
Host name for this client. This is not used by the server
235
directly, but can be, and is by default, used by the
236
checker. See the <option>checker</option> option.
237
</para>
238
</listitem>
239
</varlistentry>
240
241
<varlistentry>
242
<term><option>interval<literal> = </literal><replaceable
243
>TIME</replaceable></option></term>
244
<listitem>
245
<para>
246
This option is <emphasis>optional</emphasis>.
247
</para>
248
<para>
249
How often to run the checker to confirm that a client is
250
still up. <emphasis>Note:</emphasis> a new checker will
251
not be started if an old one is still running. The server
252
will wait for a checker to complete until the below
253
<quote><varname>timeout</varname></quote> occurs, at which
254
time the client will be disabled, and any running checker
255
killed. The default interval is 2 minutes.
256
</para>
257
<para>
258
The format of <replaceable>TIME</replaceable> is the same
259
as for <varname>timeout</varname> below.
260
</para>
261
</listitem>
262
</varlistentry>
263
264
<varlistentry>
265
<term><option>secfile<literal> = </literal><replaceable
266
>FILENAME</replaceable></option></term>
267
<listitem>
268
<para>
269
This option is only used if <option>secret</option> is not
270
specified, in which case this option is
271
<emphasis>required</emphasis>.
272
</para>
273
<para>
274
Similar to the <option>secret</option>, except the secret
275
data is in an external file. The contents of the file
276
should <emphasis>not</emphasis> be base64-encoded, but
277
will be sent to clients verbatim.
278
</para>
279
<para>
280
File names of the form <filename>~user/foo/bar</filename>
281
and <filename>$<envar>ENVVAR</envar>/foo/bar</filename>
282
are supported.
283
</para>
284
</listitem>
285
</varlistentry>
286
287
<varlistentry>
200
288
<term><option>secret<literal> = </literal><replaceable
201
289
>BASE64_ENCODED_DATA</replaceable></option></term>
202
290
<listitem>
227
315
</varlistentry>
228
316
229
317
<varlistentry>
230
<term><option>secfile<literal> = </literal><replaceable
231
>FILENAME</replaceable></option></term>
232
<listitem>
233
<para>
234
This option is only used if <option>secret</option> is not
235
specified, in which case this option is
236
<emphasis>required</emphasis>.
237
</para>
238
<para>
239
Similar to the <option>secret</option>, except the secret
240
data is in an external file. The contents of the file
241
should <emphasis>not</emphasis> be base64-encoded, but
242
will be sent to clients verbatim.
243
</para>
244
<para>
245
File names of the form <filename>~user/foo/bar</filename>
246
and <filename>$<envar>ENVVAR</envar>/foo/bar</filename>
247
are supported.
248
</para>
249
</listitem>
250
</varlistentry>
251
252
<varlistentry>
253
<term><option><literal>host = </literal><replaceable
254
>STRING</replaceable></option></term>
255
<listitem>
256
<para>
257
This option is <emphasis>optional</emphasis>, but highly
258
<emphasis>recommended</emphasis> unless the
259
<option>checker</option> option is modified to a
260
non-standard value without <quote>%(host)s</quote> in it.
261
</para>
262
<para>
263
Host name for this client. This is not used by the server
264
directly, but can be, and is by default, used by the
265
checker. See the <option>checker</option> option.
318
<term><option>timeout<literal> = </literal><replaceable
319
>TIME</replaceable></option></term>
320
<listitem>
321
<para>
322
This option is <emphasis>optional</emphasis>.
323
</para>
324
<para>
325
The timeout is how long the server will wait, after a
326
successful checker run, until a client is disabled and not
327
allowed to get the data this server holds. By default
328
Mandos will use 5 minutes. See also the
329
<option>extended_timeout</option> option.
330
</para>
331
<para>
332
The <replaceable>TIME</replaceable> is specified as a
333
space-separated number of values, each of which is a
334
number and a one-character suffix. The suffix must be one
335
of <quote>d</quote>, <quote>s</quote>, <quote>m</quote>,
336
<quote>h</quote>, and <quote>w</quote> for days, seconds,
337
minutes, hours, and weeks, respectively. The values are
338
added together to give the total time value, so all of
339
<quote><literal>330s</literal></quote>,
340
<quote><literal>110s 110s 110s</literal></quote>, and
341
<quote><literal>5m 30s</literal></quote> will give a value
342
of five minutes and thirty seconds.
266
343
</para>
267
344
</listitem>
268
345
</varlistentry>
305
382
<quote><literal>%%(<replaceable>foo</replaceable>)s</literal
306
383
></quote> will be replaced by the value of the attribute
307
384
<varname>foo</varname> of the internal
308
<quote><classname>Client</classname></quote> object. See the
309
source code for details, and let the authors know of any
310
attributes that are useful so they may be preserved to any new
311
versions of this software.
385
<quote><classname>Client</classname></quote> object in the
386
Mandos server. The currently allowed values for
387
<replaceable>foo</replaceable> are:
388
<quote><literal>approval_delay</literal></quote>,
389
<quote><literal>approval_duration</literal></quote>,
390
<quote><literal>created</literal></quote>,
391
<quote><literal>enabled</literal></quote>,
392
<quote><literal>fingerprint</literal></quote>,
393
<quote><literal>host</literal></quote>,
394
<quote><literal>interval</literal></quote>,
395
<quote><literal>last_approval_request</literal></quote>,
396
<quote><literal>last_checked_ok</literal></quote>,
397
<quote><literal>last_enabled</literal></quote>,
398
<quote><literal>name</literal></quote>,
399
<quote><literal>timeout</literal></quote>, and, if using
400
D-Bus, <quote><literal>dbus_object_path</literal></quote>.
401
See the source code for details. <emphasis role="strong"
402
>Currently, <emphasis>none</emphasis> of these attributes
403
except <quote><literal>host</literal></quote> are guaranteed
404
to be valid in future versions.</emphasis> Therefore, please
405
let the authors know of any attributes that are useful so they
406
may be preserved to any new versions of this software.
312
407
</para>
313
408
<para>
314
409
Note that this means that, in order to include an actual
349
444
<informalexample>
350
445
<programlisting>
351
446
[DEFAULT]
352
timeout = 1h
353
interval = 5m
447
timeout = 5m
448
interval = 2m
354
449
checker = fping -q -- %%(host)s
355
450
356
451
# Client "foo"
380
475
fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27
381
476
secfile = /etc/mandos/bar-secret
382
477
timeout = 15m
478
approved_by_default = False
479
approval_delay = 30s
383
480
</programlisting>
384
481
</informalexample>
385
482
</refsect1>
387
484
<refsect1 id="see_also">
388
485
<title>SEE ALSO</title>
389
486
<para>
487
<citerefentry><refentrytitle>intro</refentrytitle>
488
<manvolnum>8mandos</manvolnum></citerefentry>,
390
489
<citerefentry><refentrytitle>mandos-keygen</refentrytitle>
391
490
<manvolnum>8</manvolnum></citerefentry>,
392
491
<citerefentry><refentrytitle>mandos.conf</refentrytitle>
Loggerhead is a web-based interface for Breezy
Version: 2.0.2.dev0