/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

  • Committer: Björn Påhlsson
  • Date: 2011-11-09 11:16:17 UTC
  • mto: (237.14.5 persistent-state-gpgme)
  • mto: This revision was merged to the branch mainline in revision 290.
  • Revision ID: belorn@fukt.bsnet.se-20111109111617-jpey2sy4dupqzabc
Persistent state: New feature. Client state is now stored when mandos
                  server exits, and restored when starting up. Secrets
                  are encrypted with key based on clients config file.
--no-restore: New argument to mandos server. Disables restore
              functionallity
minor changes: clients are now dicts!

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 "2013-10-26">
 
5
<!ENTITY TIMESTAMP "2011-10-03">
6
6
<!ENTITY % common SYSTEM "common.ent">
7
7
%common;
8
8
]>
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>
98
96
      <arg><option>--no-ipv6</option></arg>
99
97
      <sbr/>
100
98
      <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
99
    </cmdsynopsis>
110
100
    <cmdsynopsis>
111
101
      <command>&COMMANDNAME;</command>
234
224
        <term><option>--priority <replaceable>
235
225
        PRIORITY</replaceable></option></term>
236
226
        <listitem>
237
 
          <xi:include href="mandos-options.xml"
238
 
                      xpointer="priority_compat"/>
 
227
          <xi:include href="mandos-options.xml" xpointer="priority"/>
239
228
        </listitem>
240
229
      </varlistentry>
241
230
      
293
282
        <term><option>--no-restore</option></term>
294
283
        <listitem>
295
284
          <xi:include href="mandos-options.xml" xpointer="restore"/>
296
 
          <para>
297
 
            See also <xref linkend="persistent_state"/>.
298
 
          </para>
299
 
        </listitem>
300
 
      </varlistentry>
301
 
      
302
 
      <varlistentry>
303
 
        <term><option>--statedir
304
 
        <replaceable>DIRECTORY</replaceable></option></term>
305
 
        <listitem>
306
 
          <xi:include href="mandos-options.xml" xpointer="statedir"/>
307
 
        </listitem>
308
 
      </varlistentry>
309
 
      
310
 
      <varlistentry>
311
 
        <term><option>--socket
312
 
        <replaceable>FD</replaceable></option></term>
313
 
        <listitem>
314
 
          <xi:include href="mandos-options.xml" xpointer="socket"/>
315
 
        </listitem>
316
 
      </varlistentry>
317
 
      
318
 
      <varlistentry>
319
 
        <term><option>--foreground</option></term>
320
 
        <listitem>
321
 
          <xi:include href="mandos-options.xml"
322
 
                      xpointer="foreground"/>
323
 
        </listitem>
324
 
      </varlistentry>
325
 
      
 
285
        </listitem>
 
286
      </varlistentry>
326
287
    </variablelist>
327
288
  </refsect1>
328
289
  
405
366
      extended timeout, checker program, and interval between checks
406
367
      can be configured both globally and per client; see
407
368
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
408
 
      <manvolnum>5</manvolnum></citerefentry>.
 
369
      <manvolnum>5</manvolnum></citerefentry>.  A client successfully
 
370
      receiving its password will also be treated as a successful
 
371
      checker run.
409
372
    </para>
410
373
  </refsect1>
411
374
  
433
396
    <title>LOGGING</title>
434
397
    <para>
435
398
      The server will send log message with various severity levels to
436
 
      <filename class="devicefile">/dev/log</filename>.  With the
 
399
      <filename>/dev/log</filename>.  With the
437
400
      <option>--debug</option> option, it will log even more messages,
438
401
      and also show them on the console.
439
402
    </para>
440
403
  </refsect1>
441
404
  
442
 
  <refsect1 id="persistent_state">
443
 
    <title>PERSISTENT STATE</title>
444
 
    <para>
445
 
      Client settings, initially read from
446
 
      <filename>clients.conf</filename>, are persistent across
447
 
      restarts, and run-time changes will override settings in
448
 
      <filename>clients.conf</filename>.  However, if a setting is
449
 
      <emphasis>changed</emphasis> (or a client added, or removed) in
450
 
      <filename>clients.conf</filename>, this will take precedence.
451
 
    </para>
452
 
  </refsect1>
453
 
  
454
405
  <refsect1 id="dbus_interface">
455
406
    <title>D-BUS INTERFACE</title>
456
407
    <para>
518
469
        </listitem>
519
470
      </varlistentry>
520
471
      <varlistentry>
521
 
        <term><filename>/run/mandos.pid</filename></term>
 
472
        <term><filename>/var/run/mandos.pid</filename></term>
522
473
        <listitem>
523
474
          <para>
524
475
            The file containing the process id of the
525
476
            <command>&COMMANDNAME;</command> process started last.
526
 
            <emphasis >Note:</emphasis> If the <filename
527
 
            class="directory">/run</filename> directory does not
528
 
            exist, <filename>/var/run/mandos.pid</filename> will be
529
 
            used instead.
530
 
          </para>
531
 
        </listitem>
532
 
      </varlistentry>
533
 
      <varlistentry>
534
 
        <term><filename class="devicefile">/dev/log</filename></term>
535
 
      </varlistentry>
536
 
      <varlistentry>
537
 
        <term><filename
538
 
        class="directory">/var/lib/mandos</filename></term>
539
 
        <listitem>
540
 
          <para>
541
 
            Directory where persistent state will be saved.  Change
542
 
            this with the <option>--statedir</option> option.  See
543
 
            also the <option>--no-restore</option> option.
544
477
          </para>
545
478
        </listitem>
546
479
      </varlistentry>
574
507
      backtrace.  This could be considered a feature.
575
508
    </para>
576
509
    <para>
 
510
      Currently, if a client is disabled due to having timed out, the
 
511
      server does not record this fact onto permanent storage.  This
 
512
      has some security implications, see <xref linkend="clients"/>.
 
513
    </para>
 
514
    <para>
577
515
      There is no fine-grained control over logging and debug output.
578
516
    </para>
579
517
    <para>
 
518
      Debug mode is conflated with running in the foreground.
 
519
    </para>
 
520
    <para>
 
521
      The console log messages do not show a time stamp.
 
522
    </para>
 
523
    <para>
580
524
      This server does not check the expire time of clients’ OpenPGP
581
525
      keys.
582
526
    </para>
595
539
    <informalexample>
596
540
      <para>
597
541
        Run the server in debug mode, read configuration files from
598
 
        the <filename class="directory">~/mandos</filename> directory,
599
 
        and use the Zeroconf service name <quote>Test</quote> to not
600
 
        collide with any other official Mandos server on this host:
 
542
        the <filename>~/mandos</filename> directory, and use the
 
543
        Zeroconf service name <quote>Test</quote> to not collide with
 
544
        any other official Mandos server on this host:
601
545
      </para>
602
546
      <para>
603
547
 
652
596
        compromised if they are gone for too long.
653
597
      </para>
654
598
      <para>
 
599
        If a client is compromised, its downtime should be duly noted
 
600
        by the server which would therefore disable the client.  But
 
601
        if the server was ever restarted, it would re-read its client
 
602
        list from its configuration file and again regard all clients
 
603
        therein as enabled, and hence eligible to receive their
 
604
        passwords.  Therefore, be careful when restarting servers if
 
605
        it is suspected that a client has, in fact, been compromised
 
606
        by parties who may now be running a fake Mandos client with
 
607
        the keys from the non-encrypted initial <acronym>RAM</acronym>
 
608
        image of the client host.  What should be done in that case
 
609
        (if restarting the server program really is necessary) is to
 
610
        stop the server program, edit the configuration file to omit
 
611
        any suspect clients, and restart the server program.
 
612
      </para>
 
613
      <para>
655
614
        For more details on client-side security, see
656
615
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
657
616
        <manvolnum>8mandos</manvolnum></citerefentry>.