/mandos/release

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/release

« back to all changes in this revision

Viewing changes to mandos.xml

  • 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".

Show diffs side-by-side

added added

removed removed

Lines of Context:
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>-><!-- &rarr; --></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>-><!-- &rarr; --></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>&lt;-><!-- &xharr; --></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>&lt;-<!-- &larr; --></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>&lt;-<!-- &larr; --></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">