/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: Björn Påhlsson
  • Date: 2011-10-02 19:18:24 UTC
  • mto: This revision was merged to the branch mainline in revision 505.
  • Revision ID: belorn@fukt.bsnet.se-20111002191824-eweh4pvneeg3qzia
transitional stuff actually working
documented change to D-Bus API

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-12-06">
 
5
<!ENTITY TIMESTAMP "2011-08-08">
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
38
      <holder>Teddy Hogeborn</holder>
43
39
      <holder>Björn Påhlsson</holder>
44
40
    </copyright>
98
94
      <arg><option>--no-dbus</option></arg>
99
95
      <sbr/>
100
96
      <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
97
    </cmdsynopsis>
114
98
    <cmdsynopsis>
115
99
      <command>&COMMANDNAME;</command>
291
275
          <xi:include href="mandos-options.xml" xpointer="ipv6"/>
292
276
        </listitem>
293
277
      </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
278
    </variablelist>
337
279
  </refsect1>
338
280
  
415
357
      extended timeout, checker program, and interval between checks
416
358
      can be configured both globally and per client; see
417
359
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
418
 
      <manvolnum>5</manvolnum></citerefentry>.
 
360
      <manvolnum>5</manvolnum></citerefentry>.  A client successfully
 
361
      receiving its password will also be treated as a successful
 
362
      checker run.
419
363
    </para>
420
364
  </refsect1>
421
365
  
443
387
    <title>LOGGING</title>
444
388
    <para>
445
389
      The server will send log message with various severity levels to
446
 
      <filename class="devicefile">/dev/log</filename>.  With the
 
390
      <filename>/dev/log</filename>.  With the
447
391
      <option>--debug</option> option, it will log even more messages,
448
392
      and also show them on the console.
449
393
    </para>
450
394
  </refsect1>
451
395
  
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
396
  <refsect1 id="dbus_interface">
465
397
    <title>D-BUS INTERFACE</title>
466
398
    <para>
528
460
        </listitem>
529
461
      </varlistentry>
530
462
      <varlistentry>
531
 
        <term><filename>/run/mandos.pid</filename></term>
 
463
        <term><filename>/var/run/mandos.pid</filename></term>
532
464
        <listitem>
533
465
          <para>
534
466
            The file containing the process id of the
535
467
            <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
545
 
        class="directory">/var/lib/mandos</filename></term>
546
 
        <listitem>
547
 
          <para>
548
 
            Directory where persistent state will be saved.  Change
549
 
            this with the <option>--statedir</option> option.  See
550
 
            also the <option>--no-restore</option> option.
551
 
          </para>
552
 
        </listitem>
553
 
      </varlistentry>
554
 
      <varlistentry>
555
 
        <term><filename class="devicefile">/dev/log</filename></term>
 
468
          </para>
 
469
        </listitem>
 
470
      </varlistentry>
 
471
      <varlistentry>
 
472
        <term><filename>/dev/log</filename></term>
556
473
        <listitem>
557
474
          <para>
558
475
            The Unix domain socket to where local syslog messages are
581
498
      backtrace.  This could be considered a feature.
582
499
    </para>
583
500
    <para>
 
501
      Currently, if a client is disabled due to having timed out, the
 
502
      server does not record this fact onto permanent storage.  This
 
503
      has some security implications, see <xref linkend="clients"/>.
 
504
    </para>
 
505
    <para>
584
506
      There is no fine-grained control over logging and debug output.
585
507
    </para>
586
508
    <para>
 
509
      Debug mode is conflated with running in the foreground.
 
510
    </para>
 
511
    <para>
 
512
      The console log messages do not show a time stamp.
 
513
    </para>
 
514
    <para>
587
515
      This server does not check the expire time of clients’ OpenPGP
588
516
      keys.
589
517
    </para>
602
530
    <informalexample>
603
531
      <para>
604
532
        Run the server in debug mode, read configuration files from
605
 
        the <filename class="directory">~/mandos</filename> directory,
606
 
        and use the Zeroconf service name <quote>Test</quote> to not
607
 
        collide with any other official Mandos server on this host:
 
533
        the <filename>~/mandos</filename> directory, and use the
 
534
        Zeroconf service name <quote>Test</quote> to not collide with
 
535
        any other official Mandos server on this host:
608
536
      </para>
609
537
      <para>
610
538
 
659
587
        compromised if they are gone for too long.
660
588
      </para>
661
589
      <para>
 
590
        If a client is compromised, its downtime should be duly noted
 
591
        by the server which would therefore disable the client.  But
 
592
        if the server was ever restarted, it would re-read its client
 
593
        list from its configuration file and again regard all clients
 
594
        therein as enabled, and hence eligible to receive their
 
595
        passwords.  Therefore, be careful when restarting servers if
 
596
        it is suspected that a client has, in fact, been compromised
 
597
        by parties who may now be running a fake Mandos client with
 
598
        the keys from the non-encrypted initial <acronym>RAM</acronym>
 
599
        image of the client host.  What should be done in that case
 
600
        (if restarting the server program really is necessary) is to
 
601
        stop the server program, edit the configuration file to omit
 
602
        any suspect clients, and restart the server program.
 
603
      </para>
 
604
      <para>
662
605
        For more details on client-side security, see
663
606
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
664
607
        <manvolnum>8mandos</manvolnum></citerefentry>.
705
648
      </varlistentry>
706
649
      <varlistentry>
707
650
        <term>
708
 
          <ulink url="http://gnutls.org/">GnuTLS</ulink>
 
651
          <ulink url="http://www.gnu.org/software/gnutls/"
 
652
          >GnuTLS</ulink>
709
653
        </term>
710
654
      <listitem>
711
655
        <para>
749
693
      </varlistentry>
750
694
      <varlistentry>
751
695
        <term>
752
 
          RFC 5246: <citetitle>The Transport Layer Security (TLS)
753
 
          Protocol Version 1.2</citetitle>
 
696
          RFC 4346: <citetitle>The Transport Layer Security (TLS)
 
697
          Protocol Version 1.1</citetitle>
754
698
        </term>
755
699
      <listitem>
756
700
        <para>
757
 
          TLS 1.2 is the protocol implemented by GnuTLS.
 
701
          TLS 1.1 is the protocol implemented by GnuTLS.
758
702
        </para>
759
703
      </listitem>
760
704
      </varlistentry>
770
714
      </varlistentry>
771
715
      <varlistentry>
772
716
        <term>
773
 
          RFC 6091: <citetitle>Using OpenPGP Keys for Transport Layer
774
 
          Security (TLS) Authentication</citetitle>
 
717
          RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer
 
718
          Security</citetitle>
775
719
        </term>
776
720
      <listitem>
777
721
        <para>