/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

Merge fix for password-prompt/plymouth conflict 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 "2017-02-23">
 
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
 
      <year>2014</year>
41
 
      <year>2015</year>
42
 
      <year>2016</year>
43
 
      <year>2017</year>
44
38
      <holder>Teddy Hogeborn</holder>
45
39
      <holder>Björn Påhlsson</holder>
46
40
    </copyright>
100
94
      <arg><option>--no-dbus</option></arg>
101
95
      <sbr/>
102
96
      <arg><option>--no-ipv6</option></arg>
103
 
      <sbr/>
104
 
      <arg><option>--no-restore</option></arg>
105
 
      <sbr/>
106
 
      <arg><option>--statedir
107
 
      <replaceable>DIRECTORY</replaceable></option></arg>
108
 
      <sbr/>
109
 
      <arg><option>--socket
110
 
      <replaceable>FD</replaceable></option></arg>
111
 
      <sbr/>
112
 
      <arg><option>--foreground</option></arg>
113
 
      <sbr/>
114
 
      <arg><option>--no-zeroconf</option></arg>
115
97
    </cmdsynopsis>
116
98
    <cmdsynopsis>
117
99
      <command>&COMMANDNAME;</command>
135
117
    <para>
136
118
      <command>&COMMANDNAME;</command> is a server daemon which
137
119
      handles incoming request for passwords for a pre-defined list of
138
 
      client host computers. For an introduction, see
139
 
      <citerefentry><refentrytitle>intro</refentrytitle>
140
 
      <manvolnum>8mandos</manvolnum></citerefentry>. The Mandos server
141
 
      uses Zeroconf to announce itself on the local network, and uses
142
 
      TLS to communicate securely with and to authenticate the
143
 
      clients.  The Mandos server uses IPv6 to allow Mandos clients to
144
 
      use IPv6 link-local addresses, since the clients will probably
145
 
      not have any other addresses configured (see <xref
146
 
      linkend="overview"/>).  Any authenticated client is then given
147
 
      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.
148
128
    </para>
149
129
  </refsect1>
150
130
  
293
273
          <xi:include href="mandos-options.xml" xpointer="ipv6"/>
294
274
        </listitem>
295
275
      </varlistentry>
296
 
      
297
 
      <varlistentry>
298
 
        <term><option>--no-restore</option></term>
299
 
        <listitem>
300
 
          <xi:include href="mandos-options.xml" xpointer="restore"/>
301
 
          <para>
302
 
            See also <xref linkend="persistent_state"/>.
303
 
          </para>
304
 
        </listitem>
305
 
      </varlistentry>
306
 
      
307
 
      <varlistentry>
308
 
        <term><option>--statedir
309
 
        <replaceable>DIRECTORY</replaceable></option></term>
310
 
        <listitem>
311
 
          <xi:include href="mandos-options.xml" xpointer="statedir"/>
312
 
        </listitem>
313
 
      </varlistentry>
314
 
      
315
 
      <varlistentry>
316
 
        <term><option>--socket
317
 
        <replaceable>FD</replaceable></option></term>
318
 
        <listitem>
319
 
          <xi:include href="mandos-options.xml" xpointer="socket"/>
320
 
        </listitem>
321
 
      </varlistentry>
322
 
      
323
 
      <varlistentry>
324
 
        <term><option>--foreground</option></term>
325
 
        <listitem>
326
 
          <xi:include href="mandos-options.xml"
327
 
                      xpointer="foreground"/>
328
 
        </listitem>
329
 
      </varlistentry>
330
 
      
331
 
      <varlistentry>
332
 
        <term><option>--no-zeroconf</option></term>
333
 
        <listitem>
334
 
          <xi:include href="mandos-options.xml" xpointer="zeroconf"/>
335
 
        </listitem>
336
 
      </varlistentry>
337
 
      
338
276
    </variablelist>
339
277
  </refsect1>
340
278
  
414
352
      for some time, the client is assumed to be compromised and is no
415
353
      longer eligible to receive the encrypted password.  (Manual
416
354
      intervention is required to re-enable a client.)  The timeout,
417
 
      extended timeout, checker program, and interval between checks
418
 
      can be configured both globally and per client; see
419
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
420
 
      <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.
421
361
    </para>
422
362
  </refsect1>
423
363
  
445
385
    <title>LOGGING</title>
446
386
    <para>
447
387
      The server will send log message with various severity levels to
448
 
      <filename class="devicefile">/dev/log</filename>.  With the
 
388
      <filename>/dev/log</filename>.  With the
449
389
      <option>--debug</option> option, it will log even more messages,
450
390
      and also show them on the console.
451
391
    </para>
452
392
  </refsect1>
453
393
  
454
 
  <refsect1 id="persistent_state">
455
 
    <title>PERSISTENT STATE</title>
456
 
    <para>
457
 
      Client settings, initially read from
458
 
      <filename>clients.conf</filename>, are persistent across
459
 
      restarts, and run-time changes will override settings in
460
 
      <filename>clients.conf</filename>.  However, if a setting is
461
 
      <emphasis>changed</emphasis> (or a client added, or removed) in
462
 
      <filename>clients.conf</filename>, this will take precedence.
463
 
    </para>
464
 
  </refsect1>
465
 
  
466
394
  <refsect1 id="dbus_interface">
467
395
    <title>D-BUS INTERFACE</title>
468
396
    <para>
530
458
        </listitem>
531
459
      </varlistentry>
532
460
      <varlistentry>
533
 
        <term><filename>/run/mandos.pid</filename></term>
 
461
        <term><filename>/var/run/mandos.pid</filename></term>
534
462
        <listitem>
535
463
          <para>
536
464
            The file containing the process id of the
537
465
            <command>&COMMANDNAME;</command> process started last.
538
 
            <emphasis >Note:</emphasis> If the <filename
539
 
            class="directory">/run</filename> directory does not
540
 
            exist, <filename>/var/run/mandos.pid</filename> will be
541
 
            used instead.
542
 
          </para>
543
 
        </listitem>
544
 
      </varlistentry>
545
 
      <varlistentry>
546
 
        <term><filename
547
 
        class="directory">/var/lib/mandos</filename></term>
548
 
        <listitem>
549
 
          <para>
550
 
            Directory where persistent state will be saved.  Change
551
 
            this with the <option>--statedir</option> option.  See
552
 
            also the <option>--no-restore</option> option.
553
 
          </para>
554
 
        </listitem>
555
 
      </varlistentry>
556
 
      <varlistentry>
557
 
        <term><filename class="devicefile">/dev/log</filename></term>
 
466
          </para>
 
467
        </listitem>
 
468
      </varlistentry>
 
469
      <varlistentry>
 
470
        <term><filename>/dev/log</filename></term>
558
471
        <listitem>
559
472
          <para>
560
473
            The Unix domain socket to where local syslog messages are
583
496
      backtrace.  This could be considered a feature.
584
497
    </para>
585
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>
586
504
      There is no fine-grained control over logging and debug output.
587
505
    </para>
588
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>
589
513
      This server does not check the expire time of clients’ OpenPGP
590
514
      keys.
591
515
    </para>
592
 
    <xi:include href="bugs.xml"/>
593
516
  </refsect1>
594
517
  
595
518
  <refsect1 id="example">
605
528
    <informalexample>
606
529
      <para>
607
530
        Run the server in debug mode, read configuration files from
608
 
        the <filename class="directory">~/mandos</filename> directory,
609
 
        and use the Zeroconf service name <quote>Test</quote> to not
610
 
        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:
611
534
      </para>
612
535
      <para>
613
536
 
662
585
        compromised if they are gone for too long.
663
586
      </para>
664
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>
665
603
        For more details on client-side security, see
666
604
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
667
605
        <manvolnum>8mandos</manvolnum></citerefentry>.
672
610
  <refsect1 id="see_also">
673
611
    <title>SEE ALSO</title>
674
612
    <para>
675
 
      <citerefentry><refentrytitle>intro</refentrytitle>
676
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
677
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
678
 
      <manvolnum>5</manvolnum></citerefentry>,
679
 
      <citerefentry><refentrytitle>mandos.conf</refentrytitle>
680
 
      <manvolnum>5</manvolnum></citerefentry>,
681
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
682
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
683
 
      <citerefentry><refentrytitle>sh</refentrytitle>
684
 
      <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>
685
622
    </para>
686
623
    <variablelist>
687
624
      <varlistentry>
708
645
      </varlistentry>
709
646
      <varlistentry>
710
647
        <term>
711
 
          <ulink url="https://gnutls.org/">GnuTLS</ulink>
 
648
          <ulink url="http://www.gnu.org/software/gnutls/"
 
649
          >GnuTLS</ulink>
712
650
        </term>
713
651
      <listitem>
714
652
        <para>
752
690
      </varlistentry>
753
691
      <varlistentry>
754
692
        <term>
755
 
          RFC 5246: <citetitle>The Transport Layer Security (TLS)
756
 
          Protocol Version 1.2</citetitle>
 
693
          RFC 4346: <citetitle>The Transport Layer Security (TLS)
 
694
          Protocol Version 1.1</citetitle>
757
695
        </term>
758
696
      <listitem>
759
697
        <para>
760
 
          TLS 1.2 is the protocol implemented by GnuTLS.
 
698
          TLS 1.1 is the protocol implemented by GnuTLS.
761
699
        </para>
762
700
      </listitem>
763
701
      </varlistentry>
773
711
      </varlistentry>
774
712
      <varlistentry>
775
713
        <term>
776
 
          RFC 6091: <citetitle>Using OpenPGP Keys for Transport Layer
777
 
          Security (TLS) Authentication</citetitle>
 
714
          RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer
 
715
          Security</citetitle>
778
716
        </term>
779
717
      <listitem>
780
718
        <para>