1
<?xml version='1.0' encoding='UTF-8'?>
1
<?xml version="1.0" encoding="UTF-8"?>
2
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
3
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
<!ENTITY VERSION "1.0">
5
4
<!ENTITY CONFNAME "mandos-clients.conf">
6
5
<!ENTITY CONFPATH "<filename>/etc/mandos/clients.conf</filename>">
7
<!ENTITY TIMESTAMP "2008-08-29">
6
<!ENTITY TIMESTAMP "2011-09-24">
7
<!ENTITY % common SYSTEM "common.ent">
11
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
12
13
<title>Mandos Manual</title>
13
14
<!-- NWalsh’s docbook scripts use this to generate the footer: -->
14
15
<productname>Mandos</productname>
15
<productnumber>&VERSION;</productnumber>
16
<productnumber>&version;</productnumber>
16
17
<date>&TIMESTAMP;</date>
35
39
<holder>Teddy Hogeborn</holder>
36
40
<holder>Björn Påhlsson</holder>
40
This manual page is free software: you can redistribute it
41
and/or modify it under the terms of the GNU General Public
42
License as published by the Free Software Foundation,
43
either version 3 of the License, or (at your option) any
48
This manual page is distributed in the hope that it will
49
be useful, but WITHOUT ANY WARRANTY; without even the
50
implied warranty of MERCHANTABILITY or FITNESS FOR A
51
PARTICULAR PURPOSE. See the GNU General Public License
56
You should have received a copy of the GNU General Public
57
License along with this program; If not, see
58
<ulink url="http://www.gnu.org/licenses/"/>.
42
<xi:include href="legalnotice.xml"/>
64
46
<refentrytitle>&CONFNAME;</refentrytitle>
65
47
<manvolnum>5</manvolnum>
117
96
start time expansion, see <xref linkend="expansion"/>.
120
Uknown options are ignored. The used options are as follows:
99
Unknown options are ignored. The used options are as follows:
126
<term><literal><varname>timeout</varname></literal></term>
128
<synopsis><literal>timeout = </literal><replaceable
132
The timeout is how long the server will wait for a
133
successful checker run until a client is considered
134
invalid - that is, ineligible to get the data this server
135
holds. By default Mandos will use 1 hour.
138
The <replaceable>TIME</replaceable> is specified as a
139
space-separated number of values, each of which is a
140
number and a one-character suffix. The suffix must be one
141
of <quote>d</quote>, <quote>s</quote>, <quote>m</quote>,
142
<quote>h</quote>, and <quote>w</quote> for days, seconds,
143
minutes, hours, and weeks, respectively. The values are
144
added together to give the total time value, so all of
145
<quote><literal>330s</literal></quote>,
146
<quote><literal>110s 110s 110s</literal></quote>, and
147
<quote><literal>5m 30s</literal></quote> will give a value
148
of five minutes and thirty seconds.
154
<term><literal><varname>interval</varname></literal></term>
156
<synopsis><literal>interval = </literal><replaceable
160
How often to run the checker to confirm that a client is
161
still up. <emphasis>Note:</emphasis> a new checker will
162
not be started if an old one is still running. The server
163
will wait for a checker to complete until the above
164
<quote><varname>timeout</varname></quote> occurs, at which
165
time the client will be marked invalid, and any running
166
checker killed. The default interval is 5 minutes.
169
The format of <replaceable>TIME</replaceable> is the same
170
as for <varname>timeout</varname> above.
176
<term><literal>checker</literal></term>
178
<synopsis><literal>checker = </literal><replaceable
179
>COMMAND</replaceable>
105
<term><option>approval_delay<literal> = </literal><replaceable
106
>TIME</replaceable></option></term>
109
This option is <emphasis>optional</emphasis>.
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.
117
The format of <replaceable>TIME</replaceable> is the same
118
as for <varname>timeout</varname> below.
124
<term><option>approval_duration<literal> = </literal
125
><replaceable>TIME</replaceable></option></term>
128
This option is <emphasis>optional</emphasis>.
131
How long an external approval lasts. The default is 1
135
The format of <replaceable>TIME</replaceable> is the same
136
as for <varname>timeout</varname> below.
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>
149
Whether to approve a client by default after
150
the <option>approval_delay</option>. The default
151
is <quote>True</quote>.
157
<term><option>checker<literal> = </literal><replaceable
158
>COMMAND</replaceable></option></term>
161
This option is <emphasis>optional</emphasis>.
182
164
This option allows you to override the default shell
183
165
command that the server will use to check if the client is
203
<term><literal>fingerprint</literal></term>
205
<synopsis><literal>fingerprint = </literal><replaceable
206
>HEXSTRING</replaceable>
185
<term><option>extended_timeout<literal> = </literal><replaceable
186
>TIME</replaceable></option></term>
189
This option is <emphasis>optional</emphasis>.
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.
201
The format of <replaceable>TIME</replaceable> is the same
202
as for <varname>timeout</varname> below.
208
<term><option>fingerprint<literal> = </literal
209
><replaceable>HEXSTRING</replaceable></option></term>
212
This option is <emphasis>required</emphasis>.
209
215
This option sets the OpenPGP fingerprint that identifies
210
216
the public key that clients authenticate themselves with
218
<term><literal>secret</literal></term>
220
<synopsis><literal>secret = </literal><replaceable
221
>BASE64_ENCODED_DATA</replaceable>
224
<term><option><literal>host = </literal><replaceable
225
>STRING</replaceable></option></term>
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.
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.
242
<term><option>interval<literal> = </literal><replaceable
243
>TIME</replaceable></option></term>
246
This option is <emphasis>optional</emphasis>.
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.
258
The format of <replaceable>TIME</replaceable> is the same
259
as for <varname>timeout</varname> below.
265
<term><option>secfile<literal> = </literal><replaceable
266
>FILENAME</replaceable></option></term>
269
This option is only used if <option>secret</option> is not
270
specified, in which case this option is
271
<emphasis>required</emphasis>.
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.
280
File names of the form <filename>~user/foo/bar</filename>
281
and <filename>$<envar>ENVVAR</envar>/foo/bar</filename>
288
<term><option>secret<literal> = </literal><replaceable
289
>BASE64_ENCODED_DATA</replaceable></option></term>
292
If this option is not specified, the <option
293
>secfile</option> option is <emphasis>required</emphasis>
224
297
If present, this option must be set to a string of
225
298
base64-encoded binary data. It will be decoded and sent
238
311
lines is that a line beginning with white space adds to
239
312
the value of the previous line, RFC 822-style.
242
If this option is not specified, the <option
243
>secfile</option> option is used instead, but one of them
244
<emphasis>must</emphasis> be present.
250
<term><literal>secfile</literal></term>
252
<synopsis><literal>secfile = </literal><replaceable
253
>FILENAME</replaceable>
256
The same as <option>secret</option>, but the secret data
257
is in an external file. The contents of the file should
258
<emphasis>not</emphasis> be base64-encoded, but will be
259
sent to clients verbatim.
262
This option is only used, and <emphasis>must</emphasis> be
263
present, if <option>secret</option> is not specified.
269
<term><literal>host</literal></term>
271
<synopsis><literal>host = </literal><replaceable
272
>STRING</replaceable>
275
Host name for this client. This is not used by the server
276
directly, but can be, and is by default, used by the
277
checker. See the <option>checker</option> option.
318
<term><option>timeout<literal> = </literal><replaceable
319
>TIME</replaceable></option></term>
322
This option is <emphasis>optional</emphasis>.
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.
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.
285
350
<refsect1 id="expansion">
286
351
<title>EXPANSION</title>
317
382
<quote><literal>%%(<replaceable>foo</replaceable>)s</literal
318
383
></quote> will be replaced by the value of the attribute
319
384
<varname>foo</varname> of the internal
320
<quote><classname>Client</classname></quote> object. See the
321
source code for details, and let the authors know of any
322
attributes that are useful so they may be preserved to any new
323
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.
326
409
Note that this means that, in order to include an actual
392
475
fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27
393
476
secfile = /etc/mandos/bar-secret
478
approved_by_default = False
396
480
</programlisting>
397
481
</informalexample>
400
484
<refsect1 id="see_also">
401
485
<title>SEE ALSO</title>
404
<refentrytitle>mandos</refentrytitle>
405
<manvolnum>8</manvolnum></citerefentry>, <citerefentry>
406
<refentrytitle>mandos-keygen</refentrytitle>
407
<manvolnum>8</manvolnum></citerefentry>, <citerefentry>
408
<refentrytitle>mandos.conf</refentrytitle>
409
<manvolnum>5</manvolnum></citerefentry>
487
<citerefentry><refentrytitle>intro</refentrytitle>
488
<manvolnum>8mandos</manvolnum></citerefentry>,
489
<citerefentry><refentrytitle>mandos-keygen</refentrytitle>
490
<manvolnum>8</manvolnum></citerefentry>,
491
<citerefentry><refentrytitle>mandos.conf</refentrytitle>
492
<manvolnum>5</manvolnum></citerefentry>,
493
<citerefentry><refentrytitle>mandos</refentrytitle>
494
<manvolnum>8</manvolnum></citerefentry>