/mandos/trunk

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

  • Committer: Teddy Hogeborn
  • Date: 2012-01-01 20:45:53 UTC
  • Revision ID: teddy@recompile.se-20120101204553-f1zlty873gswtf5n
* README: Hint that the intro(8mandos) manual page is in the server
          package.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos.xml
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
4
<!ENTITY COMMANDNAME "mandos">
5
 
<!ENTITY TIMESTAMP "2009-01-04">
 
5
<!ENTITY TIMESTAMP "2012-01-01">
6
6
<!ENTITY % common SYSTEM "common.ent">
7
7
%common;
8
8
]>
19
19
        <firstname>Björn</firstname>
20
20
        <surname>Påhlsson</surname>
21
21
        <address>
22
 
          <email>belorn@fukt.bsnet.se</email>
 
22
          <email>belorn@recompile.se</email>
23
23
        </address>
24
24
      </author>
25
25
      <author>
26
26
        <firstname>Teddy</firstname>
27
27
        <surname>Hogeborn</surname>
28
28
        <address>
29
 
          <email>teddy@fukt.bsnet.se</email>
 
29
          <email>teddy@recompile.se</email>
30
30
        </address>
31
31
      </author>
32
32
    </authorgroup>
33
33
    <copyright>
34
34
      <year>2008</year>
35
35
      <year>2009</year>
 
36
      <year>2010</year>
 
37
      <year>2011</year>
 
38
      <year>2012</year>
36
39
      <holder>Teddy Hogeborn</holder>
37
40
      <holder>Björn Påhlsson</holder>
38
41
    </copyright>
86
89
      <sbr/>
87
90
      <arg><option>--debug</option></arg>
88
91
      <sbr/>
 
92
      <arg><option>--debuglevel
 
93
      <replaceable>LEVEL</replaceable></option></arg>
 
94
      <sbr/>
89
95
      <arg><option>--no-dbus</option></arg>
 
96
      <sbr/>
 
97
      <arg><option>--no-ipv6</option></arg>
 
98
      <sbr/>
 
99
      <arg><option>--no-restore</option></arg>
 
100
      <sbr/>
 
101
      <arg><option>--statedir
 
102
      <replaceable>DIRECTORY</replaceable></option></arg>
90
103
    </cmdsynopsis>
91
104
    <cmdsynopsis>
92
105
      <command>&COMMANDNAME;</command>
110
123
    <para>
111
124
      <command>&COMMANDNAME;</command> is a server daemon which
112
125
      handles incoming request for passwords for a pre-defined list of
113
 
      client host computers.  The Mandos server uses Zeroconf to
114
 
      announce itself on the local network, and uses TLS to
115
 
      communicate securely with and to authenticate the clients.  The
116
 
      Mandos server uses IPv6 to allow Mandos clients to use IPv6
117
 
      link-local addresses, since the clients will probably not have
118
 
      any other addresses configured (see <xref linkend="overview"/>).
119
 
      Any authenticated client is then given the stored pre-encrypted
120
 
      password for that specific client.
 
126
      client host computers. For an introduction, see
 
127
      <citerefentry><refentrytitle>intro</refentrytitle>
 
128
      <manvolnum>8mandos</manvolnum></citerefentry>. The Mandos server
 
129
      uses Zeroconf to announce itself on the local network, and uses
 
130
      TLS to communicate securely with and to authenticate the
 
131
      clients.  The Mandos server uses IPv6 to allow Mandos clients to
 
132
      use IPv6 link-local addresses, since the clients will probably
 
133
      not have any other addresses configured (see <xref
 
134
      linkend="overview"/>).  Any authenticated client is then given
 
135
      the stored pre-encrypted password for that specific client.
121
136
    </para>
122
137
  </refsect1>
123
138
  
192
207
      </varlistentry>
193
208
      
194
209
      <varlistentry>
 
210
        <term><option>--debuglevel
 
211
        <replaceable>LEVEL</replaceable></option></term>
 
212
        <listitem>
 
213
          <para>
 
214
            Set the debugging log level.
 
215
            <replaceable>LEVEL</replaceable> is a string, one of
 
216
            <quote><literal>CRITICAL</literal></quote>,
 
217
            <quote><literal>ERROR</literal></quote>,
 
218
            <quote><literal>WARNING</literal></quote>,
 
219
            <quote><literal>INFO</literal></quote>, or
 
220
            <quote><literal>DEBUG</literal></quote>, in order of
 
221
            increasing verbosity.  The default level is
 
222
            <quote><literal>WARNING</literal></quote>.
 
223
          </para>
 
224
        </listitem>
 
225
      </varlistentry>
 
226
      
 
227
      <varlistentry>
195
228
        <term><option>--priority <replaceable>
196
229
        PRIORITY</replaceable></option></term>
197
230
        <listitem>
241
274
          </para>
242
275
        </listitem>
243
276
      </varlistentry>
 
277
      
 
278
      <varlistentry>
 
279
        <term><option>--no-ipv6</option></term>
 
280
        <listitem>
 
281
          <xi:include href="mandos-options.xml" xpointer="ipv6"/>
 
282
        </listitem>
 
283
      </varlistentry>
 
284
      
 
285
      <varlistentry>
 
286
        <term><option>--no-restore</option></term>
 
287
        <listitem>
 
288
          <xi:include href="mandos-options.xml" xpointer="restore"/>
 
289
          <para>
 
290
            See also <xref linkend="persistent_state"/>.
 
291
          </para>
 
292
        </listitem>
 
293
      </varlistentry>
 
294
      
 
295
      <varlistentry>
 
296
        <term><option>--statedir
 
297
        <replaceable>DIRECTORY</replaceable></option></term>
 
298
        <listitem>
 
299
          <xi:include href="mandos-options.xml" xpointer="statedir"/>
 
300
        </listitem>
 
301
      </varlistentry>
244
302
    </variablelist>
245
303
  </refsect1>
246
304
  
318
376
      The server will, by default, continually check that the clients
319
377
      are still up.  If a client has not been confirmed as being up
320
378
      for some time, the client is assumed to be compromised and is no
321
 
      longer eligible to receive the encrypted password.  The timeout,
322
 
      checker program, and interval between checks can be configured
323
 
      both globally and per client; see <citerefentry>
 
379
      longer eligible to receive the encrypted password.  (Manual
 
380
      intervention is required to re-enable a client.)  The timeout,
 
381
      extended timeout, checker program, and interval between checks
 
382
      can be configured both globally and per client; see
 
383
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
 
384
      <manvolnum>5</manvolnum></citerefentry>.  A client successfully
 
385
      receiving its password will also be treated as a successful
 
386
      checker run.
 
387
    </para>
 
388
  </refsect1>
 
389
  
 
390
  <refsect1 id="approval">
 
391
    <title>APPROVAL</title>
 
392
    <para>
 
393
      The server can be configured to require manual approval for a
 
394
      client before it is sent its secret.  The delay to wait for such
 
395
      approval and the default action (approve or deny) can be
 
396
      configured both globally and per client; see <citerefentry>
324
397
      <refentrytitle>mandos-clients.conf</refentrytitle>
325
 
      <manvolnum>5</manvolnum></citerefentry>.
326
 
    </para>
 
398
      <manvolnum>5</manvolnum></citerefentry>.  By default all clients
 
399
      will be approved immediately without delay.
 
400
    </para>
 
401
    <para>
 
402
      This can be used to deny a client its secret if not manually
 
403
      approved within a specified time.  It can also be used to make
 
404
      the server delay before giving a client its secret, allowing
 
405
      optional manual denying of this specific client.
 
406
    </para>
 
407
    
327
408
  </refsect1>
328
409
  
329
410
  <refsect1 id="logging">
330
411
    <title>LOGGING</title>
331
412
    <para>
332
413
      The server will send log message with various severity levels to
333
 
      <filename>/dev/log</filename>.  With the
 
414
      <filename class="devicefile">/dev/log</filename>.  With the
334
415
      <option>--debug</option> option, it will log even more messages,
335
416
      and also show them on the console.
336
417
    </para>
337
418
  </refsect1>
338
419
  
 
420
  <refsect1 id="persistent_state">
 
421
    <title>PERSISTENT STATE</title>
 
422
    <para>
 
423
      Client settings, initially read from
 
424
      <filename>clients.conf</filename>, are persistent across
 
425
      restarts, and run-time changes will override settings in
 
426
      <filename>clients.conf</filename>.  However, if a setting is
 
427
      <emphasis>changed</emphasis> (or a client added, or removed) in
 
428
      <filename>clients.conf</filename>, this will take precedence.
 
429
    </para>
 
430
  </refsect1>
 
431
  
339
432
  <refsect1 id="dbus_interface">
340
433
    <title>D-BUS INTERFACE</title>
341
434
    <para>
342
435
      The server will by default provide a D-Bus system bus interface.
343
436
      This interface will only be accessible by the root user or a
344
 
      Mandos-specific user, if such a user exists.
345
 
      <!-- XXX -->
 
437
      Mandos-specific user, if such a user exists.  For documentation
 
438
      of the D-Bus API, see the file <filename>DBUS-API</filename>.
346
439
    </para>
347
440
  </refsect1>
348
 
 
 
441
  
349
442
  <refsect1 id="exit_status">
350
443
    <title>EXIT STATUS</title>
351
444
    <para>
406
499
        <term><filename>/var/run/mandos.pid</filename></term>
407
500
        <listitem>
408
501
          <para>
409
 
            The file containing the process id of
410
 
            <command>&COMMANDNAME;</command>.
 
502
            The file containing the process id of the
 
503
            <command>&COMMANDNAME;</command> process started last.
 
504
          </para>
 
505
        </listitem>
 
506
      </varlistentry>
 
507
      <varlistentry>
 
508
        <term><filename class="devicefile">/dev/log</filename></term>
 
509
      </varlistentry>
 
510
      <varlistentry>
 
511
        <term><filename
 
512
        class="directory">/var/lib/mandos</filename></term>
 
513
        <listitem>
 
514
          <para>
 
515
            Directory where persistent state will be saved.  Change
 
516
            this with the <option>--statedir</option> option.  See
 
517
            also the <option>--no-restore</option> option.
411
518
          </para>
412
519
        </listitem>
413
520
      </varlistentry>
441
548
      backtrace.  This could be considered a feature.
442
549
    </para>
443
550
    <para>
444
 
      Currently, if a client is declared <quote>invalid</quote> due to
445
 
      having timed out, the server does not record this fact onto
446
 
      permanent storage.  This has some security implications, see
447
 
      <xref linkend="clients"/>.
448
 
    </para>
449
 
    <para>
450
 
      There is currently no way of querying the server of the current
451
 
      status of clients, other than analyzing its <systemitem
452
 
      class="service">syslog</systemitem> output.
453
 
    </para>
454
 
    <para>
455
551
      There is no fine-grained control over logging and debug output.
456
552
    </para>
457
553
    <para>
458
554
      Debug mode is conflated with running in the foreground.
459
555
    </para>
460
556
    <para>
461
 
      The console log messages does not show a time stamp.
462
 
    </para>
463
 
    <para>
464
557
      This server does not check the expire time of clients’ OpenPGP
465
558
      keys.
466
559
    </para>
479
572
    <informalexample>
480
573
      <para>
481
574
        Run the server in debug mode, read configuration files from
482
 
        the <filename>~/mandos</filename> directory, and use the
483
 
        Zeroconf service name <quote>Test</quote> to not collide with
484
 
        any other official Mandos server on this host:
 
575
        the <filename class="directory">~/mandos</filename> directory,
 
576
        and use the Zeroconf service name <quote>Test</quote> to not
 
577
        collide with any other official Mandos server on this host:
485
578
      </para>
486
579
      <para>
487
580
 
536
629
        compromised if they are gone for too long.
537
630
      </para>
538
631
      <para>
539
 
        If a client is compromised, its downtime should be duly noted
540
 
        by the server which would therefore declare the client
541
 
        invalid.  But if the server was ever restarted, it would
542
 
        re-read its client list from its configuration file and again
543
 
        regard all clients therein as valid, and hence eligible to
544
 
        receive their passwords.  Therefore, be careful when
545
 
        restarting servers if it is suspected that a client has, in
546
 
        fact, been compromised by parties who may now be running a
547
 
        fake Mandos client with the keys from the non-encrypted
548
 
        initial <acronym>RAM</acronym> image of the client host.  What
549
 
        should be done in that case (if restarting the server program
550
 
        really is necessary) is to stop the server program, edit the
551
 
        configuration file to omit any suspect clients, and restart
552
 
        the server program.
553
 
      </para>
554
 
      <para>
555
632
        For more details on client-side security, see
556
633
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
557
634
        <manvolnum>8mandos</manvolnum></citerefentry>.
562
639
  <refsect1 id="see_also">
563
640
    <title>SEE ALSO</title>
564
641
    <para>
565
 
      <citerefentry>
566
 
        <refentrytitle>mandos-clients.conf</refentrytitle>
567
 
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
568
 
        <refentrytitle>mandos.conf</refentrytitle>
569
 
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
570
 
        <refentrytitle>mandos-client</refentrytitle>
571
 
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
572
 
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
573
 
      </citerefentry>
 
642
      <citerefentry><refentrytitle>intro</refentrytitle>
 
643
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
644
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
 
645
      <manvolnum>5</manvolnum></citerefentry>,
 
646
      <citerefentry><refentrytitle>mandos.conf</refentrytitle>
 
647
      <manvolnum>5</manvolnum></citerefentry>,
 
648
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
649
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
650
      <citerefentry><refentrytitle>sh</refentrytitle>
 
651
      <manvolnum>1</manvolnum></citerefentry>
574
652
    </para>
575
653
    <variablelist>
576
654
      <varlistentry>