/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

Merge from trunk.  Just a minor release to make it lintian clean.

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 "2016-03-05">
 
5
<!ENTITY TIMESTAMP "2010-09-26">
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>
34
34
      <year>2008</year>
35
35
      <year>2009</year>
36
36
      <year>2010</year>
37
 
      <year>2011</year>
38
 
      <year>2012</year>
39
 
      <year>2013</year>
40
 
      <year>2014</year>
41
 
      <year>2015</year>
42
 
      <year>2016</year>
43
37
      <holder>Teddy Hogeborn</holder>
44
38
      <holder>Björn Påhlsson</holder>
45
39
    </copyright>
99
93
      <arg><option>--no-dbus</option></arg>
100
94
      <sbr/>
101
95
      <arg><option>--no-ipv6</option></arg>
102
 
      <sbr/>
103
 
      <arg><option>--no-restore</option></arg>
104
 
      <sbr/>
105
 
      <arg><option>--statedir
106
 
      <replaceable>DIRECTORY</replaceable></option></arg>
107
 
      <sbr/>
108
 
      <arg><option>--socket
109
 
      <replaceable>FD</replaceable></option></arg>
110
 
      <sbr/>
111
 
      <arg><option>--foreground</option></arg>
112
 
      <sbr/>
113
 
      <arg><option>--no-zeroconf</option></arg>
114
96
    </cmdsynopsis>
115
97
    <cmdsynopsis>
116
98
      <command>&COMMANDNAME;</command>
134
116
    <para>
135
117
      <command>&COMMANDNAME;</command> is a server daemon which
136
118
      handles incoming request for passwords for a pre-defined list of
137
 
      client host computers. For an introduction, see
138
 
      <citerefentry><refentrytitle>intro</refentrytitle>
139
 
      <manvolnum>8mandos</manvolnum></citerefentry>. The Mandos server
140
 
      uses Zeroconf to announce itself on the local network, and uses
141
 
      TLS to communicate securely with and to authenticate the
142
 
      clients.  The Mandos server uses IPv6 to allow Mandos clients to
143
 
      use IPv6 link-local addresses, since the clients will probably
144
 
      not have any other addresses configured (see <xref
145
 
      linkend="overview"/>).  Any authenticated client is then given
146
 
      the stored pre-encrypted password for that specific client.
 
119
      client host computers.  The Mandos server uses Zeroconf to
 
120
      announce itself on the local network, and uses TLS to
 
121
      communicate securely with and to authenticate the clients.  The
 
122
      Mandos server uses IPv6 to allow Mandos clients to use IPv6
 
123
      link-local addresses, since the clients will probably not have
 
124
      any other addresses configured (see <xref linkend="overview"/>).
 
125
      Any authenticated client is then given the stored pre-encrypted
 
126
      password for that specific client.
147
127
    </para>
148
128
  </refsect1>
149
129
  
292
272
          <xi:include href="mandos-options.xml" xpointer="ipv6"/>
293
273
        </listitem>
294
274
      </varlistentry>
295
 
      
296
 
      <varlistentry>
297
 
        <term><option>--no-restore</option></term>
298
 
        <listitem>
299
 
          <xi:include href="mandos-options.xml" xpointer="restore"/>
300
 
          <para>
301
 
            See also <xref linkend="persistent_state"/>.
302
 
          </para>
303
 
        </listitem>
304
 
      </varlistentry>
305
 
      
306
 
      <varlistentry>
307
 
        <term><option>--statedir
308
 
        <replaceable>DIRECTORY</replaceable></option></term>
309
 
        <listitem>
310
 
          <xi:include href="mandos-options.xml" xpointer="statedir"/>
311
 
        </listitem>
312
 
      </varlistentry>
313
 
      
314
 
      <varlistentry>
315
 
        <term><option>--socket
316
 
        <replaceable>FD</replaceable></option></term>
317
 
        <listitem>
318
 
          <xi:include href="mandos-options.xml" xpointer="socket"/>
319
 
        </listitem>
320
 
      </varlistentry>
321
 
      
322
 
      <varlistentry>
323
 
        <term><option>--foreground</option></term>
324
 
        <listitem>
325
 
          <xi:include href="mandos-options.xml"
326
 
                      xpointer="foreground"/>
327
 
        </listitem>
328
 
      </varlistentry>
329
 
      
330
 
      <varlistentry>
331
 
        <term><option>--no-zeroconf</option></term>
332
 
        <listitem>
333
 
          <xi:include href="mandos-options.xml" xpointer="zeroconf"/>
334
 
        </listitem>
335
 
      </varlistentry>
336
 
      
337
275
    </variablelist>
338
276
  </refsect1>
339
277
  
413
351
      for some time, the client is assumed to be compromised and is no
414
352
      longer eligible to receive the encrypted password.  (Manual
415
353
      intervention is required to re-enable a client.)  The timeout,
416
 
      extended timeout, checker program, and interval between checks
417
 
      can be configured both globally and per client; see
418
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
419
 
      <manvolnum>5</manvolnum></citerefentry>.
 
354
      checker program, and interval between checks can be configured
 
355
      both globally and per client; see <citerefentry>
 
356
      <refentrytitle>mandos-clients.conf</refentrytitle>
 
357
      <manvolnum>5</manvolnum></citerefentry>.  A client successfully
 
358
      receiving its password will also be treated as a successful
 
359
      checker run.
420
360
    </para>
421
361
  </refsect1>
422
362
  
444
384
    <title>LOGGING</title>
445
385
    <para>
446
386
      The server will send log message with various severity levels to
447
 
      <filename class="devicefile">/dev/log</filename>.  With the
 
387
      <filename>/dev/log</filename>.  With the
448
388
      <option>--debug</option> option, it will log even more messages,
449
389
      and also show them on the console.
450
390
    </para>
451
391
  </refsect1>
452
392
  
453
 
  <refsect1 id="persistent_state">
454
 
    <title>PERSISTENT STATE</title>
455
 
    <para>
456
 
      Client settings, initially read from
457
 
      <filename>clients.conf</filename>, are persistent across
458
 
      restarts, and run-time changes will override settings in
459
 
      <filename>clients.conf</filename>.  However, if a setting is
460
 
      <emphasis>changed</emphasis> (or a client added, or removed) in
461
 
      <filename>clients.conf</filename>, this will take precedence.
462
 
    </para>
463
 
  </refsect1>
464
 
  
465
393
  <refsect1 id="dbus_interface">
466
394
    <title>D-BUS INTERFACE</title>
467
395
    <para>
529
457
        </listitem>
530
458
      </varlistentry>
531
459
      <varlistentry>
532
 
        <term><filename>/run/mandos.pid</filename></term>
 
460
        <term><filename>/var/run/mandos.pid</filename></term>
533
461
        <listitem>
534
462
          <para>
535
463
            The file containing the process id of the
536
464
            <command>&COMMANDNAME;</command> process started last.
537
 
            <emphasis >Note:</emphasis> If the <filename
538
 
            class="directory">/run</filename> directory does not
539
 
            exist, <filename>/var/run/mandos.pid</filename> will be
540
 
            used instead.
541
 
          </para>
542
 
        </listitem>
543
 
      </varlistentry>
544
 
      <varlistentry>
545
 
        <term><filename
546
 
        class="directory">/var/lib/mandos</filename></term>
547
 
        <listitem>
548
 
          <para>
549
 
            Directory where persistent state will be saved.  Change
550
 
            this with the <option>--statedir</option> option.  See
551
 
            also the <option>--no-restore</option> option.
552
 
          </para>
553
 
        </listitem>
554
 
      </varlistentry>
555
 
      <varlistentry>
556
 
        <term><filename class="devicefile">/dev/log</filename></term>
 
465
          </para>
 
466
        </listitem>
 
467
      </varlistentry>
 
468
      <varlistentry>
 
469
        <term><filename>/dev/log</filename></term>
557
470
        <listitem>
558
471
          <para>
559
472
            The Unix domain socket to where local syslog messages are
582
495
      backtrace.  This could be considered a feature.
583
496
    </para>
584
497
    <para>
 
498
      Currently, if a client is disabled due to having timed out, the
 
499
      server does not record this fact onto permanent storage.  This
 
500
      has some security implications, see <xref linkend="clients"/>.
 
501
    </para>
 
502
    <para>
585
503
      There is no fine-grained control over logging and debug output.
586
504
    </para>
587
505
    <para>
 
506
      Debug mode is conflated with running in the foreground.
 
507
    </para>
 
508
    <para>
 
509
      The console log messages do not show a time stamp.
 
510
    </para>
 
511
    <para>
588
512
      This server does not check the expire time of clients’ OpenPGP
589
513
      keys.
590
514
    </para>
591
 
    <xi:include href="bugs.xml"/>
592
515
  </refsect1>
593
516
  
594
517
  <refsect1 id="example">
604
527
    <informalexample>
605
528
      <para>
606
529
        Run the server in debug mode, read configuration files from
607
 
        the <filename class="directory">~/mandos</filename> directory,
608
 
        and use the Zeroconf service name <quote>Test</quote> to not
609
 
        collide with any other official Mandos server on this host:
 
530
        the <filename>~/mandos</filename> directory, and use the
 
531
        Zeroconf service name <quote>Test</quote> to not collide with
 
532
        any other official Mandos server on this host:
610
533
      </para>
611
534
      <para>
612
535
 
661
584
        compromised if they are gone for too long.
662
585
      </para>
663
586
      <para>
 
587
        If a client is compromised, its downtime should be duly noted
 
588
        by the server which would therefore disable the client.  But
 
589
        if the server was ever restarted, it would re-read its client
 
590
        list from its configuration file and again regard all clients
 
591
        therein as enabled, and hence eligible to receive their
 
592
        passwords.  Therefore, be careful when restarting servers if
 
593
        it is suspected that a client has, in fact, been compromised
 
594
        by parties who may now be running a fake Mandos client with
 
595
        the keys from the non-encrypted initial <acronym>RAM</acronym>
 
596
        image of the client host.  What should be done in that case
 
597
        (if restarting the server program really is necessary) is to
 
598
        stop the server program, edit the configuration file to omit
 
599
        any suspect clients, and restart the server program.
 
600
      </para>
 
601
      <para>
664
602
        For more details on client-side security, see
665
603
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
666
604
        <manvolnum>8mandos</manvolnum></citerefentry>.
671
609
  <refsect1 id="see_also">
672
610
    <title>SEE ALSO</title>
673
611
    <para>
674
 
      <citerefentry><refentrytitle>intro</refentrytitle>
675
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
676
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
677
 
      <manvolnum>5</manvolnum></citerefentry>,
678
 
      <citerefentry><refentrytitle>mandos.conf</refentrytitle>
679
 
      <manvolnum>5</manvolnum></citerefentry>,
680
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
681
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
682
 
      <citerefentry><refentrytitle>sh</refentrytitle>
683
 
      <manvolnum>1</manvolnum></citerefentry>
 
612
      <citerefentry>
 
613
        <refentrytitle>mandos-clients.conf</refentrytitle>
 
614
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
 
615
        <refentrytitle>mandos.conf</refentrytitle>
 
616
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
 
617
        <refentrytitle>mandos-client</refentrytitle>
 
618
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
 
619
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
 
620
      </citerefentry>
684
621
    </para>
685
622
    <variablelist>
686
623
      <varlistentry>
707
644
      </varlistentry>
708
645
      <varlistentry>
709
646
        <term>
710
 
          <ulink url="http://gnutls.org/">GnuTLS</ulink>
 
647
          <ulink url="http://www.gnu.org/software/gnutls/"
 
648
          >GnuTLS</ulink>
711
649
        </term>
712
650
      <listitem>
713
651
        <para>
751
689
      </varlistentry>
752
690
      <varlistentry>
753
691
        <term>
754
 
          RFC 5246: <citetitle>The Transport Layer Security (TLS)
755
 
          Protocol Version 1.2</citetitle>
 
692
          RFC 4346: <citetitle>The Transport Layer Security (TLS)
 
693
          Protocol Version 1.1</citetitle>
756
694
        </term>
757
695
      <listitem>
758
696
        <para>
759
 
          TLS 1.2 is the protocol implemented by GnuTLS.
 
697
          TLS 1.1 is the protocol implemented by GnuTLS.
760
698
        </para>
761
699
      </listitem>
762
700
      </varlistentry>
772
710
      </varlistentry>
773
711
      <varlistentry>
774
712
        <term>
775
 
          RFC 6091: <citetitle>Using OpenPGP Keys for Transport Layer
776
 
          Security (TLS) Authentication</citetitle>
 
713
          RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer
 
714
          Security</citetitle>
777
715
        </term>
778
716
      <listitem>
779
717
        <para>