/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: 2011-07-13 02:24:39 UTC
  • mfrom: (24.1.174 mandos)
  • Revision ID: teddy@fukt.bsnet.se-20110713022439-wbv6kghshdsc2x24
Merge from Björn.

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 "2013-10-20">
 
5
<!ENTITY TIMESTAMP "2011-02-27">
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@recompile.se</email>
 
22
          <email>belorn@fukt.bsnet.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@recompile.se</email>
 
29
          <email>teddy@fukt.bsnet.se</email>
30
30
        </address>
31
31
      </author>
32
32
    </authorgroup>
35
35
      <year>2009</year>
36
36
      <year>2010</year>
37
37
      <year>2011</year>
38
 
      <year>2012</year>
39
 
      <year>2013</year>
40
38
      <holder>Teddy Hogeborn</holder>
41
39
      <holder>Björn Påhlsson</holder>
42
40
    </copyright>
96
94
      <arg><option>--no-dbus</option></arg>
97
95
      <sbr/>
98
96
      <arg><option>--no-ipv6</option></arg>
99
 
      <sbr/>
100
 
      <arg><option>--no-restore</option></arg>
101
 
      <sbr/>
102
 
      <arg><option>--statedir
103
 
      <replaceable>DIRECTORY</replaceable></option></arg>
104
 
      <sbr/>
105
 
      <arg><option>--socket
106
 
      <replaceable>FD</replaceable></option></arg>
107
 
      <sbr/>
108
 
      <arg><option>--foreground</option></arg>
109
97
    </cmdsynopsis>
110
98
    <cmdsynopsis>
111
99
      <command>&COMMANDNAME;</command>
129
117
    <para>
130
118
      <command>&COMMANDNAME;</command> is a server daemon which
131
119
      handles incoming request for passwords for a pre-defined list of
132
 
      client host computers. For an introduction, see
133
 
      <citerefentry><refentrytitle>intro</refentrytitle>
134
 
      <manvolnum>8mandos</manvolnum></citerefentry>. The Mandos server
135
 
      uses Zeroconf to announce itself on the local network, and uses
136
 
      TLS to communicate securely with and to authenticate the
137
 
      clients.  The Mandos server uses IPv6 to allow Mandos clients to
138
 
      use IPv6 link-local addresses, since the clients will probably
139
 
      not have any other addresses configured (see <xref
140
 
      linkend="overview"/>).  Any authenticated client is then given
141
 
      the stored pre-encrypted password for that specific client.
 
120
      client host computers.  The Mandos server uses Zeroconf to
 
121
      announce itself on the local network, and uses TLS to
 
122
      communicate securely with and to authenticate the clients.  The
 
123
      Mandos server uses IPv6 to allow Mandos clients to use IPv6
 
124
      link-local addresses, since the clients will probably not have
 
125
      any other addresses configured (see <xref linkend="overview"/>).
 
126
      Any authenticated client is then given the stored pre-encrypted
 
127
      password for that specific client.
142
128
    </para>
143
129
  </refsect1>
144
130
  
287
273
          <xi:include href="mandos-options.xml" xpointer="ipv6"/>
288
274
        </listitem>
289
275
      </varlistentry>
290
 
      
291
 
      <varlistentry>
292
 
        <term><option>--no-restore</option></term>
293
 
        <listitem>
294
 
          <xi:include href="mandos-options.xml" xpointer="restore"/>
295
 
          <para>
296
 
            See also <xref linkend="persistent_state"/>.
297
 
          </para>
298
 
        </listitem>
299
 
      </varlistentry>
300
 
      
301
 
      <varlistentry>
302
 
        <term><option>--statedir
303
 
        <replaceable>DIRECTORY</replaceable></option></term>
304
 
        <listitem>
305
 
          <xi:include href="mandos-options.xml" xpointer="statedir"/>
306
 
        </listitem>
307
 
      </varlistentry>
308
 
      
309
 
      <varlistentry>
310
 
        <term><option>--socket
311
 
        <replaceable>FD</replaceable></option></term>
312
 
        <listitem>
313
 
          <xi:include href="mandos-options.xml" xpointer="socket"/>
314
 
        </listitem>
315
 
      </varlistentry>
316
 
      
317
 
      <varlistentry>
318
 
        <term><option>--foreground</option></term>
319
 
        <listitem>
320
 
          <xi:include href="mandos-options.xml"
321
 
                      xpointer="foreground"/>
322
 
        </listitem>
323
 
      </varlistentry>
324
 
      
325
276
    </variablelist>
326
277
  </refsect1>
327
278
  
401
352
      for some time, the client is assumed to be compromised and is no
402
353
      longer eligible to receive the encrypted password.  (Manual
403
354
      intervention is required to re-enable a client.)  The timeout,
404
 
      extended timeout, checker program, and interval between checks
405
 
      can be configured both globally and per client; see
406
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
407
 
      <manvolnum>5</manvolnum></citerefentry>.
 
355
      checker program, and interval between checks can be configured
 
356
      both globally and per client; see <citerefentry>
 
357
      <refentrytitle>mandos-clients.conf</refentrytitle>
 
358
      <manvolnum>5</manvolnum></citerefentry>.  A client successfully
 
359
      receiving its password will also be treated as a successful
 
360
      checker run.
408
361
    </para>
409
362
  </refsect1>
410
363
  
432
385
    <title>LOGGING</title>
433
386
    <para>
434
387
      The server will send log message with various severity levels to
435
 
      <filename class="devicefile">/dev/log</filename>.  With the
 
388
      <filename>/dev/log</filename>.  With the
436
389
      <option>--debug</option> option, it will log even more messages,
437
390
      and also show them on the console.
438
391
    </para>
439
392
  </refsect1>
440
393
  
441
 
  <refsect1 id="persistent_state">
442
 
    <title>PERSISTENT STATE</title>
443
 
    <para>
444
 
      Client settings, initially read from
445
 
      <filename>clients.conf</filename>, are persistent across
446
 
      restarts, and run-time changes will override settings in
447
 
      <filename>clients.conf</filename>.  However, if a setting is
448
 
      <emphasis>changed</emphasis> (or a client added, or removed) in
449
 
      <filename>clients.conf</filename>, this will take precedence.
450
 
    </para>
451
 
  </refsect1>
452
 
  
453
394
  <refsect1 id="dbus_interface">
454
395
    <title>D-BUS INTERFACE</title>
455
396
    <para>
517
458
        </listitem>
518
459
      </varlistentry>
519
460
      <varlistentry>
520
 
        <term><filename>/run/mandos.pid</filename></term>
 
461
        <term><filename>/var/run/mandos.pid</filename></term>
521
462
        <listitem>
522
463
          <para>
523
464
            The file containing the process id of the
526
467
        </listitem>
527
468
      </varlistentry>
528
469
      <varlistentry>
529
 
        <term><filename class="devicefile">/dev/log</filename></term>
530
 
      </varlistentry>
531
 
      <varlistentry>
532
 
        <term><filename
533
 
        class="directory">/var/lib/mandos</filename></term>
534
 
        <listitem>
535
 
          <para>
536
 
            Directory where persistent state will be saved.  Change
537
 
            this with the <option>--statedir</option> option.  See
538
 
            also the <option>--no-restore</option> option.
539
 
          </para>
540
 
        </listitem>
541
 
      </varlistentry>
542
 
      <varlistentry>
543
470
        <term><filename>/dev/log</filename></term>
544
471
        <listitem>
545
472
          <para>
569
496
      backtrace.  This could be considered a feature.
570
497
    </para>
571
498
    <para>
 
499
      Currently, if a client is disabled due to having timed out, the
 
500
      server does not record this fact onto permanent storage.  This
 
501
      has some security implications, see <xref linkend="clients"/>.
 
502
    </para>
 
503
    <para>
572
504
      There is no fine-grained control over logging and debug output.
573
505
    </para>
574
506
    <para>
 
507
      Debug mode is conflated with running in the foreground.
 
508
    </para>
 
509
    <para>
 
510
      The console log messages do not show a time stamp.
 
511
    </para>
 
512
    <para>
575
513
      This server does not check the expire time of clients’ OpenPGP
576
514
      keys.
577
515
    </para>
590
528
    <informalexample>
591
529
      <para>
592
530
        Run the server in debug mode, read configuration files from
593
 
        the <filename class="directory">~/mandos</filename> directory,
594
 
        and use the Zeroconf service name <quote>Test</quote> to not
595
 
        collide with any other official Mandos server on this host:
 
531
        the <filename>~/mandos</filename> directory, and use the
 
532
        Zeroconf service name <quote>Test</quote> to not collide with
 
533
        any other official Mandos server on this host:
596
534
      </para>
597
535
      <para>
598
536
 
647
585
        compromised if they are gone for too long.
648
586
      </para>
649
587
      <para>
 
588
        If a client is compromised, its downtime should be duly noted
 
589
        by the server which would therefore disable the client.  But
 
590
        if the server was ever restarted, it would re-read its client
 
591
        list from its configuration file and again regard all clients
 
592
        therein as enabled, and hence eligible to receive their
 
593
        passwords.  Therefore, be careful when restarting servers if
 
594
        it is suspected that a client has, in fact, been compromised
 
595
        by parties who may now be running a fake Mandos client with
 
596
        the keys from the non-encrypted initial <acronym>RAM</acronym>
 
597
        image of the client host.  What should be done in that case
 
598
        (if restarting the server program really is necessary) is to
 
599
        stop the server program, edit the configuration file to omit
 
600
        any suspect clients, and restart the server program.
 
601
      </para>
 
602
      <para>
650
603
        For more details on client-side security, see
651
604
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
652
605
        <manvolnum>8mandos</manvolnum></citerefentry>.
657
610
  <refsect1 id="see_also">
658
611
    <title>SEE ALSO</title>
659
612
    <para>
660
 
      <citerefentry><refentrytitle>intro</refentrytitle>
661
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
662
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
663
 
      <manvolnum>5</manvolnum></citerefentry>,
664
 
      <citerefentry><refentrytitle>mandos.conf</refentrytitle>
665
 
      <manvolnum>5</manvolnum></citerefentry>,
666
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
667
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
668
 
      <citerefentry><refentrytitle>sh</refentrytitle>
669
 
      <manvolnum>1</manvolnum></citerefentry>
 
613
      <citerefentry>
 
614
        <refentrytitle>mandos-clients.conf</refentrytitle>
 
615
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
 
616
        <refentrytitle>mandos.conf</refentrytitle>
 
617
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
 
618
        <refentrytitle>mandos-client</refentrytitle>
 
619
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
 
620
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
 
621
      </citerefentry>
670
622
    </para>
671
623
    <variablelist>
672
624
      <varlistentry>