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.xml
- browse files at revision 83
- compare with another revision
- download diff
- download tarball
- view history from revision 83
- Committer: Teddy Hogeborn
- Date: 2008-08-17 20:34:18 UTC
- Revision ID: teddy@fukt.bsnet.se-20080817203418-l691ahxyc7vmezad
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
* mandos.xml: More improvements. Replaced " with <quote>'s.
(NETWORK PROTOCOL): Replaced <informaltable> with <table> with a
<title>.
(CHECKING): New section describing the continual checking of
clients.
(LOGGING): We log to /dev/log, not syslog(3).
(FILES): Changed to use a <variablelist> instead of an
<itemizedlist>. Added "/dev/log" and brief descriptions of
all files.
(BUGS): Added content.
(EXAMPLES): - '' -
(SECURITY): Added content to subsections "SERVER" and "CLIENTS".
* mandos.xml: More improvements. Replaced " with <quote>'s.
(NETWORK PROTOCOL): Replaced <informaltable> with <table> with a
<title>.
(CHECKING): New section describing the continual checking of
clients.
(LOGGING): We log to /dev/log, not syslog(3).
(FILES): Changed to use a <variablelist> instead of an
<itemizedlist>. Added "/dev/log" and brief descriptions of
all files.
(BUGS): Added content.
(EXAMPLES): - '' -
(SECURITY): Added content to subsections "SERVER" and "CLIENTS".
- files modified:
- Makefile
added
removed
mandos.xml
103
103
<cmdsynopsis>
104
104
<command>&COMMANDNAME;</command>
105
105
<arg choice='plain'>--check</arg>
106
</cmdsynopsis>
106
</cmdsynopsis>
107
107
</refsynopsisdiv>
108
108
109
109
<refsect1 id="description">
115
115
announce itself on the local network, and uses GnuTLS to
116
116
communicate securely with and to authenticate the clients.
117
117
Mandos uses IPv6 link-local addresses, since the clients are
118
assumed to not have any other addresses configured yet. Any
118
assumed to not have any other addresses configured. Any
119
119
authenticated client is then given the pre-encrypted password
120
120
for that specific client.
121
121
</para>
122
122
123
</refsect1>
123
</refsect1>
124
124
125
125
<refsect1 id="purpose">
126
126
<title>PURPOSE</title>
137
137
normally.
138
138
</para>
139
139
140
</refsect1>
140
</refsect1>
141
141
142
142
<refsect1 id="options">
143
143
<title>OPTIONS</title>
162
162
use all available interfaces.
163
163
</para>
164
164
</listitem>
165
</varlistentry>
165
</varlistentry>
166
166
167
167
<varlistentry>
168
168
<term><literal>-a</literal>, <literal>--address <replaceable>
172
172
If this option is used, the server will only listen to a
173
173
specific address. This must currently be an IPv6 address;
174
174
an IPv4 address can be specified using the
175
"<literal>::FFFF:192.0.2.3</literal>" syntax. Also, if a
176
link-local address is specified, an interface should be
177
set, since a link-local address is only valid on a single
178
interface. By default, the server will listen to all
179
available addresses.
175
<quote><literal>::FFFF:192.0.2.3</literal></quote> syntax.
176
Also, if a link-local address is specified, an interface
177
should be set, since a link-local address is only valid on
178
a single interface. By default, the server will listen to
179
all available addresses.
180
180
</para>
181
181
</listitem>
182
</varlistentry>
182
</varlistentry>
183
183
184
184
<varlistentry>
185
185
<term><literal>-p</literal>, <literal>--port <replaceable>
191
191
port given by the operating system.
192
192
</para>
193
193
</listitem>
194
</varlistentry>
194
</varlistentry>
195
195
196
196
<varlistentry>
197
197
<term><literal>--check</literal></term>
201
201
tests, etc.
202
202
</para>
203
203
</listitem>
204
</varlistentry>
204
</varlistentry>
205
205
206
206
<varlistentry>
207
207
<term><literal>--debug</literal></term>
224
224
<citerefentry><refentrytitle>gnutls_priority_init
225
225
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
226
226
for the syntax. The default is
227
"<literal>SECURE256:!CTYPE-X.509:+CTYPE-OPENPGP</literal>".
227
<quote><literal>SECURE256:!CTYPE-X.509:+CTYPE-OPENPGP</literal></quote>.
228
228
<emphasis>Warning</emphasis>: changing this may make the
229
229
TLS handshake fail, making communication with clients
230
230
impossible.
231
231
</para>
232
232
</listitem>
233
</varlistentry>
233
</varlistentry>
234
234
235
235
<varlistentry>
236
236
<term><literal>--servicename <replaceable>NAME</replaceable>
238
238
<listitem>
239
239
<para>
240
240
Zeroconf service name. The default is
241
"<literal>Mandos</literal>". You only need to change this
242
if you for some reason want to run more than one server on
243
the same <emphasis>host</emphasis>. If there are name
241
<quote><literal>Mandos</literal></quote>. You only need
242
to change this if you for some reason want to run more
243
than one server on the same <emphasis>host</emphasis>,
244
which would not normally be useful. If there are name
244
245
collisions on the same <emphasis>network</emphasis>, the
245
new server will automatically rename itself to "Mandos
246
#2", etc.
246
newer server will automatically rename itself to
247
<quote><literal>Mandos #2</literal></quote>, and so on,
248
therefore this option is not needed in that case.
247
249
</para>
248
250
</listitem>
249
</varlistentry>
251
</varlistentry>
250
252
251
253
<varlistentry>
252
254
<term><literal>--configdir <replaceable>DIR</replaceable>
254
256
<listitem>
255
257
<para>
256
258
Directory to search for configuration files. Default is
257
"<literal>/etc/mandos</literal>". See <citerefentry>
258
<refentrytitle>mandos.conf</refentrytitle>
259
<quote><literal>/etc/mandos</literal></quote>. See
260
<citerefentry><refentrytitle>mandos.conf</refentrytitle>
259
261
<manvolnum>5</manvolnum></citerefentry> and <citerefentry>
260
262
<refentrytitle>mandos-clients.conf</refentrytitle>
261
263
<manvolnum>5</manvolnum></citerefentry>.
270
272
Prints the program version and exit.
271
273
</para>
272
274
</listitem>
273
</varlistentry>
275
</varlistentry>
274
276
</variablelist>
275
277
</refsect1>
276
278
278
280
<title>NETWORK PROTOCOL</title>
279
281
<para>
280
282
The Mandos server announces itself as a Zeroconf service of type
281
"<literal>_mandos._tcp</literal>". The Mandos client connects
282
to the announced address and port, and sends a line of text
283
where the first whitespace-separated field is the protocol
284
version, which currently is "<literal>1</literal>". The client
285
and server then start a TLS protocol handshake with a slight
286
quirk: the Mandos server program acts as a TLS "client" while
287
the connecting Mandos client acts as a TLS "server". The Mandos
288
client must supply an OpenPGP certificate, and the fingerprint
289
of this certificate is used by the Mandos server to look up (in
290
a list read from a file at start time) which binary blob to give
291
the client. No other authentication or authorization is done by
292
the server.
283
<quote><literal>_mandos._tcp</literal></quote>. The Mandos
284
client connects to the announced address and port, and sends a
285
line of text where the first whitespace-separated field is the
286
protocol version, which currently is
287
<quote><literal>1</literal></quote>. The client and server then
288
start a TLS protocol handshake with a slight quirk: the Mandos
289
server program acts as a TLS <quote>client</quote> while the
290
connecting Mandos client acts as a TLS <quote>server</quote>.
291
The Mandos client must supply an OpenPGP certificate, and the
292
fingerprint of this certificate is used by the Mandos server to
293
look up (in a list read from <filename>clients.conf</filename>
294
at start time) which binary blob to give the client. No other
295
authentication or authorization is done by the server.
293
296
</para>
294
<informaltable><tgroup cols="3"><thead>
297
<table>
298
<title>Mandos Protocol (Version 1)</title><tgroup cols="3"><thead>
295
299
<row>
296
300
<entry>Mandos Client</entry>
297
301
<entry>Direction</entry>
303
307
<entry>-><!-- → --></entry>
304
308
</row>
305
309
<row>
306
<entry>"<literal>1\r\en</literal>"</entry>
310
<entry><quote><literal>1\r\en</literal></quote></entry>
307
311
<entry>-><!-- → --></entry>
308
312
</row>
309
313
<row>
310
<entry>TLS handshake</entry>
314
<entry>TLS handshake <emphasis>as TLS <quote>server</quote>
315
</emphasis></entry>
311
316
<entry><-><!-- ⟷ --></entry>
312
<entry>TLS handshake</entry>
317
<entry>TLS handshake <emphasis>as TLS <quote>client</quote>
318
</emphasis></entry>
313
319
</row>
314
320
<row>
315
321
<entry>OpenPGP public key (part of TLS handshake)</entry>
318
324
<row>
319
325
<entry/>
320
326
<entry><-<!-- ← --></entry>
321
<entry>Binary blob</entry>
327
<entry>Binary blob (client will assume OpenPGP data)</entry>
322
328
</row>
323
329
<row>
324
330
<entry/>
325
331
<entry><-<!-- ← --></entry>
326
332
<entry>Close</entry>
327
333
</row>
328
</tbody></tgroup></informaltable>
334
</tbody></tgroup></table>
335
</refsect1>
336
337
<refsect1 id="checking">
338
<title>CHECKING</title>
339
<para>
340
The server will, by default, continually check that the clients
341
are still up. If a client has not been confirmed as being up
342
for some time, the client is assumed to be compromised and is no
343
longer eligible to receive the encrypted password. The timeout,
344
checker program and interval between checks can be configured
345
both globally and per client; see <citerefentry>
346
<refentrytitle>mandos.conf</refentrytitle>
347
<manvolnum>5</manvolnum></citerefentry> and <citerefentry>
348
<refentrytitle>mandos-clients.conf</refentrytitle>
349
<manvolnum>5</manvolnum></citerefentry>.
350
</para>
329
351
</refsect1>
330
352
331
353
<refsect1 id="logging">
332
354
<title>LOGGING</title>
333
355
<para>
334
The server will log a lot of information with various severity
335
levels to
336
<citerefentry><refentrytitle>syslog</refentrytitle>
337
<manvolnum>8</manvolnum></citerefentry>. With the
356
The server will send log messaged with various severity levels
357
to <filename>/dev/log</filename>. With the
338
358
<option>--debug</option> option, it will log even more messages,
339
359
and also show them on the console.
340
360
</para>
351
371
<refsect1 id="file">
352
372
<title>FILES</title>
353
373
<para>
354
<itemizedlist>
355
<listitem><para>
356
<filename>/etc/mandos/mandos.conf</filename> See <citerefentry>
357
<refentrytitle>mandos.conf</refentrytitle>
358
<manvolnum>5</manvolnum></citerefentry>.
359
</para></listitem>
360
<listitem><para>
361
<filename>/etc/mandos/clients.conf</filename> See <citerefentry>
362
<refentrytitle>mandos-clients.conf</refentrytitle>
363
<manvolnum>5</manvolnum></citerefentry>.
364
</para></listitem>
365
<listitem><para>
366
<filename>/var/run/mandos/mandos.pid</filename>
367
</para></listitem>
368
</itemizedlist>
374
Use the <option>--configdir</option> option to change where
375
<command>&COMMANDNAME;</command> looks for its configurations
376
files. The default file names are listed here.
369
377
</para>
370
</refsect1>
378
<variablelist>
379
<varlistentry>
380
<term><filename>/etc/mandos/mandos.conf</filename></term>
381
<listitem>
382
<para>
383
Server-global settings. See
384
<citerefentry><refentrytitle>mandos.conf</refentrytitle>
385
<manvolnum>5</manvolnum></citerefentry> for details.
386
</para>
387
</listitem>
388
</varlistentry>
389
<varlistentry>
390
<term><filename>/etc/mandos/clients.conf</filename></term>
391
<listitem>
392
<para>
393
List of clients and client-specific settings. See
394
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
395
<manvolnum>5</manvolnum></citerefentry> for details.
396
</para>
397
</listitem>
398
</varlistentry>
399
<varlistentry>
400
<term><filename>/var/run/mandos/mandos.pid</filename></term>
401
<listitem>
402
<para>
403
The file containing the process id of
404
<command>&COMMANDNAME;</command>.
405
</para>
406
</listitem>
407
</varlistentry>
408
<varlistentry>
409
<term><filename>/dev/log</filename></term>
410
<listitem>
411
<para>
412
The Unix domain socket to where local syslog messages are
413
sent.
414
</para>
415
</listitem>
416
</varlistentry>
417
</variablelist>
418
</refsect1>
371
419
372
420
<refsect1 id="bugs">
373
421
<title>BUGS</title>
374
422
<para>
423
This server might, on especially fatal errors, emit a Python
424
backtrace. This could be considered a feature.
375
425
</para>
376
</refsect1>
426
</refsect1>
377
427
378
428
<refsect1 id="examples">
379
429
<title>EXAMPLES</title>
380
<para>
381
</para>
430
<informalexample>
431
<para>
432
Normal invocation needs no options:
433
</para>
434
<para>
435
<userinput>mandos</userinput>
436
</para>
437
</informalexample>
438
<informalexample>
439
<para>
440
Run the server in debug mode and read configuration files from
441
the <filename>~/mandos</filename> directory:
442
</para>
443
<para>
444
445
<!-- do not wrap this line -->
446
<userinput>mandos --debug --configdir ~/mandos --servicename Test</userinput>
447
448
</para>
449
</informalexample>
450
<informalexample>
451
<para>
452
Run the server normally, but only listen to one interface and
453
only on the link-local address on that interface:
454
</para>
455
<para>
456
457
<!-- do not wrap this line -->
458
<userinput>mandos --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>
459
460
</para>
461
</informalexample>
382
462
</refsect1>
383
463
384
464
<refsect1 id="security">
385
465
<title>SECURITY</title>
386
<para>
387
</para>
466
<refsect2>
467
<title>SERVER</title>
468
<para>
469
Running the server should not in itself present any security
470
risk to the host computer running it.
471
</para>
472
</refsect2>
473
<refsect2>
474
<title>CLIENTS</title>
475
<para>
476
The server only gives out its stored data to clients which
477
does have the OpenPGP key of the stored fingerprint. This is
478
guaranteed by the fact that the client sends its OpenPGP
479
public key in the TLS handshake; this ensures it to be
480
genuine. The server computes the fingerprint of the key
481
itself and looks up the fingerprint in its list of
482
clients. The <filename>clients.conf</filename> file (see
483
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
484
<manvolnum>5</manvolnum></citerefentry>) must be non-readable
485
by anyone except the user running the server.
486
</para>
487
<para>
488
For more details on client-side security, see
489
<citerefentry><refentrytitle>password-request</refentrytitle>
490
<manvolnum>8mandos</manvolnum></citerefentry>.
491
</para>
492
</refsect2>
388
493
</refsect1>
389
494
390
495
<refsect1 id="see_also">
Loggerhead is a web-based interface for Breezy
Version: 2.0.2.dev0