/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-03-17 18:14:34 UTC
  • Revision ID: teddy@fukt.bsnet.se-20110317181434-si1m0l8q5fakzgjx
* DBUS-API: Fix grammar.

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-01-25">
 
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
 
      <sbr/>
110
 
      <arg><option>--no-zeroconf</option></arg>
111
97
    </cmdsynopsis>
112
98
    <cmdsynopsis>
113
99
      <command>&COMMANDNAME;</command>
131
117
    <para>
132
118
      <command>&COMMANDNAME;</command> is a server daemon which
133
119
      handles incoming request for passwords for a pre-defined list of
134
 
      client host computers. For an introduction, see
135
 
      <citerefentry><refentrytitle>intro</refentrytitle>
136
 
      <manvolnum>8mandos</manvolnum></citerefentry>. The Mandos server
137
 
      uses Zeroconf to announce itself on the local network, and uses
138
 
      TLS to communicate securely with and to authenticate the
139
 
      clients.  The Mandos server uses IPv6 to allow Mandos clients to
140
 
      use IPv6 link-local addresses, since the clients will probably
141
 
      not have any other addresses configured (see <xref
142
 
      linkend="overview"/>).  Any authenticated client is then given
143
 
      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.
144
128
    </para>
145
129
  </refsect1>
146
130
  
236
220
        <term><option>--priority <replaceable>
237
221
        PRIORITY</replaceable></option></term>
238
222
        <listitem>
239
 
          <xi:include href="mandos-options.xml"
240
 
                      xpointer="priority_compat"/>
 
223
          <xi:include href="mandos-options.xml" xpointer="priority"/>
241
224
        </listitem>
242
225
      </varlistentry>
243
226
      
290
273
          <xi:include href="mandos-options.xml" xpointer="ipv6"/>
291
274
        </listitem>
292
275
      </varlistentry>
293
 
      
294
 
      <varlistentry>
295
 
        <term><option>--no-restore</option></term>
296
 
        <listitem>
297
 
          <xi:include href="mandos-options.xml" xpointer="restore"/>
298
 
          <para>
299
 
            See also <xref linkend="persistent_state"/>.
300
 
          </para>
301
 
        </listitem>
302
 
      </varlistentry>
303
 
      
304
 
      <varlistentry>
305
 
        <term><option>--statedir
306
 
        <replaceable>DIRECTORY</replaceable></option></term>
307
 
        <listitem>
308
 
          <xi:include href="mandos-options.xml" xpointer="statedir"/>
309
 
        </listitem>
310
 
      </varlistentry>
311
 
      
312
 
      <varlistentry>
313
 
        <term><option>--socket
314
 
        <replaceable>FD</replaceable></option></term>
315
 
        <listitem>
316
 
          <xi:include href="mandos-options.xml" xpointer="socket"/>
317
 
        </listitem>
318
 
      </varlistentry>
319
 
      
320
 
      <varlistentry>
321
 
        <term><option>--foreground</option></term>
322
 
        <listitem>
323
 
          <xi:include href="mandos-options.xml"
324
 
                      xpointer="foreground"/>
325
 
        </listitem>
326
 
      </varlistentry>
327
 
      
328
 
      <varlistentry>
329
 
        <term><option>--no-zeroconf</option></term>
330
 
        <listitem>
331
 
          <xi:include href="mandos-options.xml" xpointer="zeroconf"/>
332
 
        </listitem>
333
 
      </varlistentry>
334
 
      
335
276
    </variablelist>
336
277
  </refsect1>
337
278
  
411
352
      for some time, the client is assumed to be compromised and is no
412
353
      longer eligible to receive the encrypted password.  (Manual
413
354
      intervention is required to re-enable a client.)  The timeout,
414
 
      extended timeout, checker program, and interval between checks
415
 
      can be configured both globally and per client; see
416
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
417
 
      <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.
418
361
    </para>
419
362
  </refsect1>
420
363
  
442
385
    <title>LOGGING</title>
443
386
    <para>
444
387
      The server will send log message with various severity levels to
445
 
      <filename class="devicefile">/dev/log</filename>.  With the
 
388
      <filename>/dev/log</filename>.  With the
446
389
      <option>--debug</option> option, it will log even more messages,
447
390
      and also show them on the console.
448
391
    </para>
449
392
  </refsect1>
450
393
  
451
 
  <refsect1 id="persistent_state">
452
 
    <title>PERSISTENT STATE</title>
453
 
    <para>
454
 
      Client settings, initially read from
455
 
      <filename>clients.conf</filename>, are persistent across
456
 
      restarts, and run-time changes will override settings in
457
 
      <filename>clients.conf</filename>.  However, if a setting is
458
 
      <emphasis>changed</emphasis> (or a client added, or removed) in
459
 
      <filename>clients.conf</filename>, this will take precedence.
460
 
    </para>
461
 
  </refsect1>
462
 
  
463
394
  <refsect1 id="dbus_interface">
464
395
    <title>D-BUS INTERFACE</title>
465
396
    <para>
527
458
        </listitem>
528
459
      </varlistentry>
529
460
      <varlistentry>
530
 
        <term><filename>/run/mandos.pid</filename></term>
 
461
        <term><filename>/var/run/mandos.pid</filename></term>
531
462
        <listitem>
532
463
          <para>
533
464
            The file containing the process id of the
534
465
            <command>&COMMANDNAME;</command> process started last.
535
 
            <emphasis >Note:</emphasis> If the <filename
536
 
            class="directory">/run</filename> directory does not
537
 
            exist, <filename>/var/run/mandos.pid</filename> will be
538
 
            used instead.
539
 
          </para>
540
 
        </listitem>
541
 
      </varlistentry>
542
 
      <varlistentry>
543
 
        <term><filename class="devicefile">/dev/log</filename></term>
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
466
          </para>
554
467
        </listitem>
555
468
      </varlistentry>
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>
604
528
    <informalexample>
605
529
      <para>
606
530
        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:
 
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:
610
534
      </para>
611
535
      <para>
612
536
 
661
585
        compromised if they are gone for too long.
662
586
      </para>
663
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>
664
603
        For more details on client-side security, see
665
604
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
666
605
        <manvolnum>8mandos</manvolnum></citerefentry>.
671
610
  <refsect1 id="see_also">
672
611
    <title>SEE ALSO</title>
673
612
    <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>
 
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>
684
622
    </para>
685
623
    <variablelist>
686
624
      <varlistentry>
707
645
      </varlistentry>
708
646
      <varlistentry>
709
647
        <term>
710
 
          <ulink url="http://gnutls.org/">GnuTLS</ulink>
 
648
          <ulink url="http://www.gnu.org/software/gnutls/"
 
649
          >GnuTLS</ulink>
711
650
        </term>
712
651
      <listitem>
713
652
        <para>
751
690
      </varlistentry>
752
691
      <varlistentry>
753
692
        <term>
754
 
          RFC 5246: <citetitle>The Transport Layer Security (TLS)
755
 
          Protocol Version 1.2</citetitle>
 
693
          RFC 4346: <citetitle>The Transport Layer Security (TLS)
 
694
          Protocol Version 1.1</citetitle>
756
695
        </term>
757
696
      <listitem>
758
697
        <para>
759
 
          TLS 1.2 is the protocol implemented by GnuTLS.
 
698
          TLS 1.1 is the protocol implemented by GnuTLS.
760
699
        </para>
761
700
      </listitem>
762
701
      </varlistentry>
772
711
      </varlistentry>
773
712
      <varlistentry>
774
713
        <term>
775
 
          RFC 6091: <citetitle>Using OpenPGP Keys for Transport Layer
776
 
          Security (TLS) Authentication</citetitle>
 
714
          RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer
 
715
          Security</citetitle>
777
716
        </term>
778
717
      <listitem>
779
718
        <para>