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 237
- compare with another revision
- download diff
- download tarball
- view history from revision 237
- Committer: Teddy Hogeborn
- Date: 2008-11-08 17:26:35 UTC
- Revision ID: teddy@fukt.bsnet.se-20081108172635-6eexzbysvsk4bu1z
* mandos: Also import "with_statement" and "absolute_import" from
"__future__. Import "closing" from "contextlib".
(Client.__init__): Use "with closing" on "secfile".
(Client.checker_callback): Call "self.bump_timeout()" instead of
doing it directly.
(Client.bump_timeout): New method to bump up the timeout.
(TCP_handler.handle): Simplify code to provide fallback default for
GnuTLS priority string.
(IPv6_TCPServer): Do not inherit from
"SocketServer.ForkingTCPServer", since that is
undocumented - instead, follow the example code
from the documentation.
(if_nametoindex): Use "with closing" on the socket.
"__future__. Import "closing" from "contextlib".
(Client.__init__): Use "with closing" on "secfile".
(Client.checker_callback): Call "self.bump_timeout()" instead of
doing it directly.
(Client.bump_timeout): New method to bump up the timeout.
(TCP_handler.handle): Simplify code to provide fallback default for
GnuTLS priority string.
(IPv6_TCPServer): Do not inherit from
"SocketServer.ForkingTCPServer", since that is
undocumented - instead, follow the example code
from the documentation.
(if_nametoindex): Use "with closing" on the socket.
- files added:
- .bzr-builddeb
- debian
- debian/po
- files removed:
- plugins.d/usplash
- files renamed:
- plugins.d/password-request.c => plugins.d/mandos-client.c
- plugins.d/password-request.xml => plugins.d/mandos-client.xml
- files modified:
- Makefile
added
removed
mandos-clients.conf.xml
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>">
6
<!ENTITY TIMESTAMP "2008-10-07">
7
<!ENTITY % common SYSTEM "common.ent">
8
%common;
7
9
]>
8
10
9
<refentry>
11
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
10
12
<refentryinfo>
11
<title>&CONFNAME;</title>
13
<title>Mandos Manual</title>
12
14
<!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
<productname>&CONFNAME;</productname>
14
<productnumber>&VERSION;</productnumber>
15
<productname>Mandos</productname>
16
<productnumber>&version;</productnumber>
17
<date>&TIMESTAMP;</date>
15
18
<authorgroup>
16
19
<author>
17
20
<firstname>Björn</firstname>
33
36
<holder>Teddy Hogeborn</holder>
34
37
<holder>Björn Påhlsson</holder>
35
38
</copyright>
36
<legalnotice>
37
<para>
38
This manual page is free software: you can redistribute it
39
and/or modify it under the terms of the GNU General Public
40
License as published by the Free Software Foundation,
41
either version 3 of the License, or (at your option) any
42
later version.
43
</para>
44
45
<para>
46
This manual page is distributed in the hope that it will
47
be useful, but WITHOUT ANY WARRANTY; without even the
48
implied warranty of MERCHANTABILITY or FITNESS FOR A
49
PARTICULAR PURPOSE. See the GNU General Public License
50
for more details.
51
</para>
52
53
<para>
54
You should have received a copy of the GNU General Public
55
License along with this program; If not, see
56
<ulink url="http://www.gnu.org/licenses/"/>.
57
</para>
58
</legalnotice>
39
<xi:include href="legalnotice.xml"/>
59
40
</refentryinfo>
60
41
61
42
<refmeta>
62
43
<refentrytitle>&CONFNAME;</refentrytitle>
63
44
<manvolnum>5</manvolnum>
69
50
Configuration file for the Mandos server
70
51
</refpurpose>
71
52
</refnamediv>
72
53
73
54
<refsynopsisdiv>
74
<synopsis>
75
&CONFPATH;
76
</synopsis>
55
<synopsis>&CONFPATH;</synopsis>
77
56
</refsynopsisdiv>
78
57
79
58
<refsect1 id="description">
80
59
<title>DESCRIPTION</title>
81
60
<para>
82
The file &CONFPATH; is the configuration file for <citerefentry
61
The file &CONFPATH; is a configuration file for <citerefentry
83
62
><refentrytitle>mandos</refentrytitle>
84
<manvolnum>8</manvolnum></citerefentry>, read by it at startup,
85
where each client that will be able to use the service needs to
86
be listed. All clients listed will be regarded as valid, even
63
<manvolnum>8</manvolnum></citerefentry>, read by it at startup.
64
The file needs to list all clients that should be able to use
65
the service. All clients listed will be regarded as valid, even
87
66
if a client was declared invalid in a previous run of the
88
67
server.
89
68
</para>
90
69
<para>
91
The format starts with a section under [] which is either
70
The format starts with a <literal>[<replaceable>section
71
header</replaceable>]</literal> which is either
92
72
<literal>[DEFAULT]</literal> or <literal>[<replaceable>client
93
name</replaceable>]</literal>. Following the section is any
94
number of <quote><varname><replaceable>option</replaceable
73
name</replaceable>]</literal>. The <replaceable>client
74
name</replaceable> can be anything, and is not tied to a host
75
name. Following the section header is any number of
76
<quote><varname><replaceable>option</replaceable
95
77
></varname>=<replaceable>value</replaceable></quote> entries,
96
78
with continuations in the style of RFC 822. <quote><varname
97
79
><replaceable>option</replaceable></varname>: <replaceable
98
80
>value</replaceable></quote> is also accepted. Note that
99
81
leading whitespace is removed from values. Values can contain
100
82
format strings which refer to other values in the same section,
101
or values in the <quote>DEFAULT</quote> section. Lines
102
beginning with <quote>#</quote> or <quote>;</quote> are ignored
103
and may be used to provide comments.
83
or values in the <quote>DEFAULT</quote> section (see <xref
84
linkend="expansion"/>). Lines beginning with <quote>#</quote>
85
or <quote>;</quote> are ignored and may be used to provide
86
comments.
104
87
</para>
105
88
</refsect1>
106
89
107
90
<refsect1 id="options">
108
91
<title>OPTIONS</title>
109
92
<para>
110
The possible options are:
111
</para>
112
93
<emphasis>Note:</emphasis> all option values are subject to
94
start time expansion, see <xref linkend="expansion"/>.
95
</para>
96
<para>
97
Unknown options are ignored. The used options are as follows:
98
</para>
99
113
100
<variablelist>
114
101
115
102
<varlistentry>
116
<term><literal><varname>timeout</varname></literal></term>
103
<term><option>timeout<literal> = </literal><replaceable
104
>TIME</replaceable></option></term>
117
105
<listitem>
118
<synopsis><literal>timeout = </literal><replaceable
119
>TIME</replaceable>
120
</synopsis>
106
<para>
107
This option is <emphasis>optional</emphasis>.
108
</para>
121
109
<para>
122
110
The timeout is how long the server will wait for a
123
111
successful checker run until a client is considered
139
127
</para>
140
128
</listitem>
141
129
</varlistentry>
142
130
143
131
<varlistentry>
144
<term><literal><varname>interval</varname></literal></term>
132
<term><option>interval<literal> = </literal><replaceable
133
>TIME</replaceable></option></term>
145
134
<listitem>
146
<synopsis><literal>interval = </literal><replaceable
147
>TIME</replaceable>
148
</synopsis>
135
<para>
136
This option is <emphasis>optional</emphasis>.
137
</para>
149
138
<para>
150
139
How often to run the checker to confirm that a client is
151
140
still up. <emphasis>Note:</emphasis> a new checker will
160
149
as for <varname>timeout</varname> above.
161
150
</para>
162
151
</listitem>
163
</varlistentry>
164
152
</varlistentry>
153
165
154
<varlistentry>
166
<term><literal>checker</literal></term>
155
<term><option>checker<literal> = </literal><replaceable
156
>COMMAND</replaceable></option></term>
167
157
<listitem>
168
158
<para>
159
This option is <emphasis>optional</emphasis>.
160
</para>
161
<para>
169
162
This option allows you to override the default shell
170
command that the server will use to check up if the client
171
is still up. By default mandos will "fping -q -- %%(host)s"
172
</para>
173
</listitem>
174
</varlistentry>
175
176
<varlistentry>
177
<term><literal>fingerprint</literal></term>
178
<listitem>
179
<para>
180
This option sets the openpgp fingerprint that identifies
181
the public certificate that clients authenticates themself
182
through gnutls. The string need to be in hex-decimal form.
183
</para>
184
</listitem>
185
</varlistentry>
186
187
<varlistentry>
188
<term><literal>secret</literal></term>
189
<listitem>
190
<para>
191
Base 64 encoded OpenPGP encrypted password encrypted by
192
the clients openpgp certificate.
193
</para>
194
</listitem>
195
</varlistentry>
196
197
<varlistentry>
198
<term><literal>secfile</literal></term>
199
<listitem>
200
<para>
201
Base 64 encoded OpenPGP encrypted password encrypted by
202
the clients openpgp certificate as a binary file.
203
</para>
204
</listitem>
205
</varlistentry>
206
207
<varlistentry>
208
<term><literal>host</literal></term>
209
<listitem>
210
<para>
211
Host name that can be used in for checking that the client is up.
212
</para>
213
</listitem>
214
</varlistentry>
215
216
<varlistentry>
217
<term><literal>checker</literal></term>
218
<listitem>
219
<para>
220
Shell command that the server will use to check up if a
221
client is still up.
222
</para>
223
</listitem>
224
</varlistentry>
225
226
<varlistentry>
227
<term><literal>timeout</literal></term>
228
<listitem>
229
<para>
230
Duration that a client can be down whitout be removed from
231
the client list.
232
</para>
233
</listitem>
234
</varlistentry>
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>
168
<option>-c</option></command></quote>, so
169
<varname>PATH</varname> will be searched. The default
170
value for the checker command is <quote><literal
171
><command>fping</command> <option>-q</option> <option
172
>--</option> %(host)s</literal></quote>.
173
</para>
174
<para>
175
In addition to normal start time expansion, this option
176
will also be subject to runtime expansion; see <xref
177
linkend="expansion"/>.
178
</para>
179
</listitem>
180
</varlistentry>
181
182
<varlistentry>
183
<term><option>fingerprint<literal> = </literal
184
><replaceable>HEXSTRING</replaceable></option></term>
185
<listitem>
186
<para>
187
This option is <emphasis>required</emphasis>.
188
</para>
189
<para>
190
This option sets the OpenPGP fingerprint that identifies
191
the public key that clients authenticate themselves with
192
through TLS. The string needs to be in hexidecimal form,
193
but spaces or upper/lower case are not significant.
194
</para>
195
</listitem>
196
</varlistentry>
197
198
<varlistentry>
199
<term><option>secret<literal> = </literal><replaceable
200
>BASE64_ENCODED_DATA</replaceable></option></term>
201
<listitem>
202
<para>
203
If this option is not specified, the <option
204
>secfile</option> option is <emphasis>required</emphasis>
205
to be present.
206
</para>
207
<para>
208
If present, this option must be set to a string of
209
base64-encoded binary data. It will be decoded and sent
210
to the client matching the above
211
<option>fingerprint</option>. This should, of course, be
212
OpenPGP encrypted data, decryptable only by the client.
213
The program <citerefentry><refentrytitle><command
214
>mandos-keygen</command></refentrytitle><manvolnum
215
>8</manvolnum></citerefentry> can, using its
216
<option>--password</option> option, be used to generate
217
this, if desired.
218
</para>
219
<para>
220
Note: this value of this option will probably be very
221
long. A useful feature to avoid having unreadably-long
222
lines is that a line beginning with white space adds to
223
the value of the previous line, RFC 822-style.
224
</para>
225
</listitem>
226
</varlistentry>
227
228
<varlistentry>
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>
235
268
236
269
</variablelist>
237
</refsect1>
270
</refsect1>
238
271
239
272
<refsect1 id="expansion">
240
273
<title>EXPANSION</title>
242
275
There are two forms of expansion: Start time expansion and
243
276
runtime expansion.
244
277
</para>
245
<refsect2>
278
<refsect2 id="start_time_expansion">
246
279
<title>START TIME EXPANSION</title>
247
280
<para>
248
281
Any string in an option value of the form
260
293
entered.
261
294
</para>
262
295
</refsect2>
263
<refsect2>
296
<refsect2 id="runtime_expansion">
264
297
<title>RUNTIME EXPANSION</title>
265
298
<para>
266
299
This is currently only done for the <varname>checker</varname>
279
312
<para>
280
313
Note that this means that, in order to include an actual
281
314
percent character (<quote>%</quote>) in a
282
<varname>checker</varname> options, <emphasis>four</emphasis>
315
<varname>checker</varname> option, <emphasis>four</emphasis>
283
316
percent characters in a row (<quote>%%%%</quote>) must be
284
317
entered. Also, a bad format here will lead to an immediate
285
318
but <emphasis>silent</emphasis> run-time fatal exit; debug
286
mode is needed to track down an error of this kind.
319
mode is needed to expose an error of this kind.
287
320
</para>
288
321
</refsect2>
289
290
</refsect1>
322
323
</refsect1>
291
324
292
325
<refsect1 id="files">
293
326
<title>FILES</title>
317
350
[DEFAULT]
318
351
timeout = 1h
319
352
interval = 5m
320
checker = fping -q -- %%(host)s
353
checker = fping -q -- %(host)s
321
354
322
355
# Client "foo"
323
356
[foo]
338
371
5MHdW9AYsNJZAQSOpirE4Xi31CSlWAi9KV+cUCmWF5zOFy1x23P6PjdaRm
339
372
4T2zw4dxS5NswXWU0sVEXxjs6PYxuIiCTL7vdpx8QjBkrPWDrAbcMyBr2O
340
373
QlnHIvPzEArRQLo=
341
=iHhv
342
374
host = foo.example.org
343
interval = 5m
375
interval = 1m
344
376
345
377
# Client "bar"
346
378
[bar]
347
379
fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27
348
secfile = /etc/mandos/bar-secret.txt.asc
349
380
secfile = /etc/mandos/bar-secret
381
timeout = 15m
350
382
</programlisting>
351
383
</informalexample>
352
</refsect1>
353
384
</refsect1>
385
386
<refsect1 id="see_also">
387
<title>SEE ALSO</title>
388
<para>
389
<citerefentry><refentrytitle>mandos-keygen</refentrytitle>
390
<manvolnum>8</manvolnum></citerefentry>,
391
<citerefentry><refentrytitle>mandos.conf</refentrytitle>
392
<manvolnum>5</manvolnum></citerefentry>,
393
<citerefentry><refentrytitle>mandos</refentrytitle>
394
<manvolnum>8</manvolnum></citerefentry>
395
</para>
396
</refsect1>
354
397
</refentry>
398
<!-- Local Variables: -->
399
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
400
<!-- time-stamp-end: "[\"']>" -->
401
<!-- time-stamp-format: "%:y-%02m-%02d" -->
402
<!-- End: -->
Loggerhead is a web-based interface for Breezy
Version: 2.0.2.dev0