/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-09-18 15:59:05 UTC
  • mfrom: (24.1.179 mandos)
  • Revision ID: teddy@fukt.bsnet.se-20110918155905-ngj2ig0yheralj1s
* DBUS-API: Document new "Expires" and "ExtendedTimeout" properties.
* README: Refer to the installed manual page more simply.
* mandos (Client.extended_timeout, Client.expires): New attributes.
  (Client.extended_timeout_milliseconds): New.
  (Client.__init__, Client.enable, Client.disable): Set new attributes.
  (Client.checked_ok): Take new "timeout" argument.
  (ClientDBus.expires): Transform into a property which sends a D-Bus
                        signal when changed.
  (ClientDBus._datetime_to_dbus): Return empty D-Bus string on None.
                                  All callers changed to use this.

  (ClientDBus.ApprovedByDefault_dbus_property,
  ClientDBus.ApprovalDelay_dbus_property,
  ClientDBus.ApprovalDuration_dbus_property,
  ClientDBus.Host_dbus_property, ClientDBus.Timeout_dbus_property,
  ClientDBus.Interval_dbus_property,
  ClientDBus.Checker_dbus_property): Bug fix: Only send D-Bus signal
                                     if new value is different.
  (ClientDBus.Timeout_dbus_property): Use new "expires" attribute.
  (ClientDBus.Expires_dbus_property,
  ClientDBus.ExtendedTimeout_dbus_property): New D-Bus properties.
  (ClientHandler.handle): Bump time using extended_timeout value.
  (main.client_defaults): Change default values of "timeout" and
                          "interval", added new default value for
                          "extended_timeout".
* mandos-clients.conf.xml (OPTIONS): Changed default values of
                                     "interval" and "timeout".  Add
                                     new "extended_timeout" option.
  (EXAMPLE): Updated default values.
* mandos-ctl: Show new "ExtendedTimeout" D-Bus property and change it
              using new "--extended-timeout" option.
* mandos-ctl.xml (SYNOPSIS, OPTIONS): Document new
                                      "--extended-timeout" option.
* mandos-monitor (MandosClientWidget.update): Use new "Expires" D-Bus
                                              property.
* mandos.xml (DESCRIPTION): Add reference to intro(8mandos) manual
                            page.
  (CHECKING): Refer to the new "extended_timeout" option in
  clients.conf.

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-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
 
      <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>
293
275
          <xi:include href="mandos-options.xml" xpointer="ipv6"/>
294
276
        </listitem>
295
277
      </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
278
    </variablelist>
339
279
  </refsect1>
340
280
  
417
357
      extended timeout, checker program, and interval between checks
418
358
      can be configured both globally and per client; see
419
359
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
420
 
      <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.
421
363
    </para>
422
364
  </refsect1>
423
365
  
445
387
    <title>LOGGING</title>
446
388
    <para>
447
389
      The server will send log message with various severity levels to
448
 
      <filename class="devicefile">/dev/log</filename>.  With the
 
390
      <filename>/dev/log</filename>.  With the
449
391
      <option>--debug</option> option, it will log even more messages,
450
392
      and also show them on the console.
451
393
    </para>
452
394
  </refsect1>
453
395
  
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
396
  <refsect1 id="dbus_interface">
467
397
    <title>D-BUS INTERFACE</title>
468
398
    <para>
530
460
        </listitem>
531
461
      </varlistentry>
532
462
      <varlistentry>
533
 
        <term><filename>/run/mandos.pid</filename></term>
 
463
        <term><filename>/var/run/mandos.pid</filename></term>
534
464
        <listitem>
535
465
          <para>
536
466
            The file containing the process id of the
537
467
            <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>
 
468
          </para>
 
469
        </listitem>
 
470
      </varlistentry>
 
471
      <varlistentry>
 
472
        <term><filename>/dev/log</filename></term>
558
473
        <listitem>
559
474
          <para>
560
475
            The Unix domain socket to where local syslog messages are
583
498
      backtrace.  This could be considered a feature.
584
499
    </para>
585
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>
586
506
      There is no fine-grained control over logging and debug output.
587
507
    </para>
588
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>
589
515
      This server does not check the expire time of clients’ OpenPGP
590
516
      keys.
591
517
    </para>
592
 
    <xi:include href="bugs.xml"/>
593
518
  </refsect1>
594
519
  
595
520
  <refsect1 id="example">
605
530
    <informalexample>
606
531
      <para>
607
532
        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:
 
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:
611
536
      </para>
612
537
      <para>
613
538
 
662
587
        compromised if they are gone for too long.
663
588
      </para>
664
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>
665
605
        For more details on client-side security, see
666
606
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
667
607
        <manvolnum>8mandos</manvolnum></citerefentry>.
708
648
      </varlistentry>
709
649
      <varlistentry>
710
650
        <term>
711
 
          <ulink url="https://gnutls.org/">GnuTLS</ulink>
 
651
          <ulink url="http://www.gnu.org/software/gnutls/"
 
652
          >GnuTLS</ulink>
712
653
        </term>
713
654
      <listitem>
714
655
        <para>
752
693
      </varlistentry>
753
694
      <varlistentry>
754
695
        <term>
755
 
          RFC 5246: <citetitle>The Transport Layer Security (TLS)
756
 
          Protocol Version 1.2</citetitle>
 
696
          RFC 4346: <citetitle>The Transport Layer Security (TLS)
 
697
          Protocol Version 1.1</citetitle>
757
698
        </term>
758
699
      <listitem>
759
700
        <para>
760
 
          TLS 1.2 is the protocol implemented by GnuTLS.
 
701
          TLS 1.1 is the protocol implemented by GnuTLS.
761
702
        </para>
762
703
      </listitem>
763
704
      </varlistentry>
773
714
      </varlistentry>
774
715
      <varlistentry>
775
716
        <term>
776
 
          RFC 6091: <citetitle>Using OpenPGP Keys for Transport Layer
777
 
          Security (TLS) Authentication</citetitle>
 
717
          RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer
 
718
          Security</citetitle>
778
719
        </term>
779
720
      <listitem>
780
721
        <para>