/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

* initramfs-tools-hook-conf: Security bug fix: Add code to handle
                             being called by "mkinitramfs-kpkg"
                             instead of "update-initramfs".

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 "2015-07-20">
 
5
<!ENTITY TIMESTAMP "2009-02-24">
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>
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>
39
 
      <year>2013</year>
40
 
      <year>2014</year>
41
 
      <year>2015</year>
42
36
      <holder>Teddy Hogeborn</holder>
43
37
      <holder>Björn Påhlsson</holder>
44
38
    </copyright>
92
86
      <sbr/>
93
87
      <arg><option>--debug</option></arg>
94
88
      <sbr/>
95
 
      <arg><option>--debuglevel
96
 
      <replaceable>LEVEL</replaceable></option></arg>
97
 
      <sbr/>
98
 
      <arg><option>--no-dbus</option></arg>
99
 
      <sbr/>
100
89
      <arg><option>--no-ipv6</option></arg>
101
 
      <sbr/>
102
 
      <arg><option>--no-restore</option></arg>
103
 
      <sbr/>
104
 
      <arg><option>--statedir
105
 
      <replaceable>DIRECTORY</replaceable></option></arg>
106
 
      <sbr/>
107
 
      <arg><option>--socket
108
 
      <replaceable>FD</replaceable></option></arg>
109
 
      <sbr/>
110
 
      <arg><option>--foreground</option></arg>
111
 
      <sbr/>
112
 
      <arg><option>--no-zeroconf</option></arg>
113
90
    </cmdsynopsis>
114
91
    <cmdsynopsis>
115
92
      <command>&COMMANDNAME;</command>
133
110
    <para>
134
111
      <command>&COMMANDNAME;</command> is a server daemon which
135
112
      handles incoming request for passwords for a pre-defined list of
136
 
      client host computers. For an introduction, see
137
 
      <citerefentry><refentrytitle>intro</refentrytitle>
138
 
      <manvolnum>8mandos</manvolnum></citerefentry>. The Mandos server
139
 
      uses Zeroconf to announce itself on the local network, and uses
140
 
      TLS to communicate securely with and to authenticate the
141
 
      clients.  The Mandos server uses IPv6 to allow Mandos clients to
142
 
      use IPv6 link-local addresses, since the clients will probably
143
 
      not have any other addresses configured (see <xref
144
 
      linkend="overview"/>).  Any authenticated client is then given
145
 
      the stored pre-encrypted password for that specific client.
 
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.
146
121
    </para>
147
122
  </refsect1>
148
123
  
217
192
      </varlistentry>
218
193
      
219
194
      <varlistentry>
220
 
        <term><option>--debuglevel
221
 
        <replaceable>LEVEL</replaceable></option></term>
222
 
        <listitem>
223
 
          <para>
224
 
            Set the debugging log level.
225
 
            <replaceable>LEVEL</replaceable> is a string, one of
226
 
            <quote><literal>CRITICAL</literal></quote>,
227
 
            <quote><literal>ERROR</literal></quote>,
228
 
            <quote><literal>WARNING</literal></quote>,
229
 
            <quote><literal>INFO</literal></quote>, or
230
 
            <quote><literal>DEBUG</literal></quote>, in order of
231
 
            increasing verbosity.  The default level is
232
 
            <quote><literal>WARNING</literal></quote>.
233
 
          </para>
234
 
        </listitem>
235
 
      </varlistentry>
236
 
      
237
 
      <varlistentry>
238
195
        <term><option>--priority <replaceable>
239
196
        PRIORITY</replaceable></option></term>
240
197
        <listitem>
276
233
      </varlistentry>
277
234
      
278
235
      <varlistentry>
279
 
        <term><option>--no-dbus</option></term>
280
 
        <listitem>
281
 
          <xi:include href="mandos-options.xml" xpointer="dbus"/>
282
 
          <para>
283
 
            See also <xref linkend="dbus_interface"/>.
284
 
          </para>
285
 
        </listitem>
286
 
      </varlistentry>
287
 
      
288
 
      <varlistentry>
289
236
        <term><option>--no-ipv6</option></term>
290
237
        <listitem>
291
238
          <xi:include href="mandos-options.xml" xpointer="ipv6"/>
292
239
        </listitem>
293
240
      </varlistentry>
294
 
      
295
 
      <varlistentry>
296
 
        <term><option>--no-restore</option></term>
297
 
        <listitem>
298
 
          <xi:include href="mandos-options.xml" xpointer="restore"/>
299
 
          <para>
300
 
            See also <xref linkend="persistent_state"/>.
301
 
          </para>
302
 
        </listitem>
303
 
      </varlistentry>
304
 
      
305
 
      <varlistentry>
306
 
        <term><option>--statedir
307
 
        <replaceable>DIRECTORY</replaceable></option></term>
308
 
        <listitem>
309
 
          <xi:include href="mandos-options.xml" xpointer="statedir"/>
310
 
        </listitem>
311
 
      </varlistentry>
312
 
      
313
 
      <varlistentry>
314
 
        <term><option>--socket
315
 
        <replaceable>FD</replaceable></option></term>
316
 
        <listitem>
317
 
          <xi:include href="mandos-options.xml" xpointer="socket"/>
318
 
        </listitem>
319
 
      </varlistentry>
320
 
      
321
 
      <varlistentry>
322
 
        <term><option>--foreground</option></term>
323
 
        <listitem>
324
 
          <xi:include href="mandos-options.xml"
325
 
                      xpointer="foreground"/>
326
 
        </listitem>
327
 
      </varlistentry>
328
 
      
329
 
      <varlistentry>
330
 
        <term><option>--no-zeroconf</option></term>
331
 
        <listitem>
332
 
          <xi:include href="mandos-options.xml" xpointer="zeroconf"/>
333
 
        </listitem>
334
 
      </varlistentry>
335
 
      
336
241
    </variablelist>
337
242
  </refsect1>
338
243
  
410
315
      The server will, by default, continually check that the clients
411
316
      are still up.  If a client has not been confirmed as being up
412
317
      for some time, the client is assumed to be compromised and is no
413
 
      longer eligible to receive the encrypted password.  (Manual
414
 
      intervention is required to re-enable a client.)  The timeout,
415
 
      extended timeout, checker program, and interval between checks
416
 
      can be configured both globally and per client; see
417
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
 
318
      longer eligible to receive the encrypted password.  The timeout,
 
319
      checker program, and interval between checks can be configured
 
320
      both globally and per client; see <citerefentry>
 
321
      <refentrytitle>mandos-clients.conf</refentrytitle>
418
322
      <manvolnum>5</manvolnum></citerefentry>.
419
323
    </para>
420
324
  </refsect1>
421
325
  
422
 
  <refsect1 id="approval">
423
 
    <title>APPROVAL</title>
424
 
    <para>
425
 
      The server can be configured to require manual approval for a
426
 
      client before it is sent its secret.  The delay to wait for such
427
 
      approval and the default action (approve or deny) can be
428
 
      configured both globally and per client; see <citerefentry>
429
 
      <refentrytitle>mandos-clients.conf</refentrytitle>
430
 
      <manvolnum>5</manvolnum></citerefentry>.  By default all clients
431
 
      will be approved immediately without delay.
432
 
    </para>
433
 
    <para>
434
 
      This can be used to deny a client its secret if not manually
435
 
      approved within a specified time.  It can also be used to make
436
 
      the server delay before giving a client its secret, allowing
437
 
      optional manual denying of this specific client.
438
 
    </para>
439
 
    
440
 
  </refsect1>
441
 
  
442
326
  <refsect1 id="logging">
443
327
    <title>LOGGING</title>
444
328
    <para>
445
329
      The server will send log message with various severity levels to
446
 
      <filename class="devicefile">/dev/log</filename>.  With the
 
330
      <filename>/dev/log</filename>.  With the
447
331
      <option>--debug</option> option, it will log even more messages,
448
332
      and also show them on the console.
449
333
    </para>
450
334
  </refsect1>
451
335
  
452
 
  <refsect1 id="persistent_state">
453
 
    <title>PERSISTENT STATE</title>
454
 
    <para>
455
 
      Client settings, initially read from
456
 
      <filename>clients.conf</filename>, are persistent across
457
 
      restarts, and run-time changes will override settings in
458
 
      <filename>clients.conf</filename>.  However, if a setting is
459
 
      <emphasis>changed</emphasis> (or a client added, or removed) in
460
 
      <filename>clients.conf</filename>, this will take precedence.
461
 
    </para>
462
 
  </refsect1>
463
 
  
464
 
  <refsect1 id="dbus_interface">
465
 
    <title>D-BUS INTERFACE</title>
466
 
    <para>
467
 
      The server will by default provide a D-Bus system bus interface.
468
 
      This interface will only be accessible by the root user or a
469
 
      Mandos-specific user, if such a user exists.  For documentation
470
 
      of the D-Bus API, see the file <filename>DBUS-API</filename>.
471
 
    </para>
472
 
  </refsect1>
473
 
  
474
336
  <refsect1 id="exit_status">
475
337
    <title>EXIT STATUS</title>
476
338
    <para>
528
390
        </listitem>
529
391
      </varlistentry>
530
392
      <varlistentry>
531
 
        <term><filename>/run/mandos.pid</filename></term>
532
 
        <listitem>
533
 
          <para>
534
 
            The file containing the process id of the
535
 
            <command>&COMMANDNAME;</command> process started last.
536
 
            <emphasis >Note:</emphasis> If the <filename
537
 
            class="directory">/run</filename> directory does not
538
 
            exist, <filename>/var/run/mandos.pid</filename> will be
539
 
            used instead.
540
 
          </para>
541
 
        </listitem>
542
 
      </varlistentry>
543
 
      <varlistentry>
544
 
        <term><filename class="devicefile">/dev/log</filename></term>
545
 
      </varlistentry>
546
 
      <varlistentry>
547
 
        <term><filename
548
 
        class="directory">/var/lib/mandos</filename></term>
549
 
        <listitem>
550
 
          <para>
551
 
            Directory where persistent state will be saved.  Change
552
 
            this with the <option>--statedir</option> option.  See
553
 
            also the <option>--no-restore</option> option.
 
393
        <term><filename>/var/run/mandos.pid</filename></term>
 
394
        <listitem>
 
395
          <para>
 
396
            The file containing the process id of
 
397
            <command>&COMMANDNAME;</command>.
554
398
          </para>
555
399
        </listitem>
556
400
      </varlistentry>
584
428
      backtrace.  This could be considered a feature.
585
429
    </para>
586
430
    <para>
 
431
      Currently, if a client is declared <quote>invalid</quote> due to
 
432
      having timed out, the server does not record this fact onto
 
433
      permanent storage.  This has some security implications, see
 
434
      <xref linkend="clients"/>.
 
435
    </para>
 
436
    <para>
 
437
      There is currently no way of querying the server of the current
 
438
      status of clients, other than analyzing its <systemitem
 
439
      class="service">syslog</systemitem> output.
 
440
    </para>
 
441
    <para>
587
442
      There is no fine-grained control over logging and debug output.
588
443
    </para>
589
444
    <para>
 
445
      Debug mode is conflated with running in the foreground.
 
446
    </para>
 
447
    <para>
 
448
      The console log messages do not show a time stamp.
 
449
    </para>
 
450
    <para>
590
451
      This server does not check the expire time of clients’ OpenPGP
591
452
      keys.
592
453
    </para>
605
466
    <informalexample>
606
467
      <para>
607
468
        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:
 
469
        the <filename>~/mandos</filename> directory, and use the
 
470
        Zeroconf service name <quote>Test</quote> to not collide with
 
471
        any other official Mandos server on this host:
611
472
      </para>
612
473
      <para>
613
474
 
662
523
        compromised if they are gone for too long.
663
524
      </para>
664
525
      <para>
 
526
        If a client is compromised, its downtime should be duly noted
 
527
        by the server which would therefore declare the client
 
528
        invalid.  But if the server was ever restarted, it would
 
529
        re-read its client list from its configuration file and again
 
530
        regard all clients therein as valid, and hence eligible to
 
531
        receive their passwords.  Therefore, be careful when
 
532
        restarting servers if it is suspected that a client has, in
 
533
        fact, been compromised by parties who may now be running a
 
534
        fake Mandos client with the keys from the non-encrypted
 
535
        initial <acronym>RAM</acronym> image of the client host.  What
 
536
        should be done in that case (if restarting the server program
 
537
        really is necessary) is to stop the server program, edit the
 
538
        configuration file to omit any suspect clients, and restart
 
539
        the server program.
 
540
      </para>
 
541
      <para>
665
542
        For more details on client-side security, see
666
543
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
667
544
        <manvolnum>8mandos</manvolnum></citerefentry>.
672
549
  <refsect1 id="see_also">
673
550
    <title>SEE ALSO</title>
674
551
    <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>
 
552
      <citerefentry>
 
553
        <refentrytitle>mandos-clients.conf</refentrytitle>
 
554
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
 
555
        <refentrytitle>mandos.conf</refentrytitle>
 
556
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
 
557
        <refentrytitle>mandos-client</refentrytitle>
 
558
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
 
559
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
 
560
      </citerefentry>
685
561
    </para>
686
562
    <variablelist>
687
563
      <varlistentry>
708
584
      </varlistentry>
709
585
      <varlistentry>
710
586
        <term>
711
 
          <ulink url="http://gnutls.org/">GnuTLS</ulink>
 
587
          <ulink url="http://www.gnu.org/software/gnutls/"
 
588
          >GnuTLS</ulink>
712
589
        </term>
713
590
      <listitem>
714
591
        <para>
752
629
      </varlistentry>
753
630
      <varlistentry>
754
631
        <term>
755
 
          RFC 5246: <citetitle>The Transport Layer Security (TLS)
756
 
          Protocol Version 1.2</citetitle>
 
632
          RFC 4346: <citetitle>The Transport Layer Security (TLS)
 
633
          Protocol Version 1.1</citetitle>
757
634
        </term>
758
635
      <listitem>
759
636
        <para>
760
 
          TLS 1.2 is the protocol implemented by GnuTLS.
 
637
          TLS 1.1 is the protocol implemented by GnuTLS.
761
638
        </para>
762
639
      </listitem>
763
640
      </varlistentry>
773
650
      </varlistentry>
774
651
      <varlistentry>
775
652
        <term>
776
 
          RFC 6091: <citetitle>Using OpenPGP Keys for Transport Layer
777
 
          Security (TLS) Authentication</citetitle>
 
653
          RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer
 
654
          Security</citetitle>
778
655
        </term>
779
656
      <listitem>
780
657
        <para>