/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

* initramfs-tools-hook: Bug fix: Add "--userid" and "--groupid" to
                        start of "plugin-runner.conf" file instead of
                        appending, to allow any preexisting options to
                        override.
* plugin-runner.conf: Improved wording.

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 "2011-10-22">
 
5
<!ENTITY TIMESTAMP "2009-02-15">
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
36
      <holder>Teddy Hogeborn</holder>
39
37
      <holder>Björn Påhlsson</holder>
40
38
    </copyright>
88
86
      <sbr/>
89
87
      <arg><option>--debug</option></arg>
90
88
      <sbr/>
91
 
      <arg><option>--debuglevel
92
 
      <replaceable>LEVEL</replaceable></option></arg>
93
 
      <sbr/>
94
89
      <arg><option>--no-dbus</option></arg>
95
90
      <sbr/>
96
91
      <arg><option>--no-ipv6</option></arg>
97
 
      <sbr/>
98
 
      <arg><option>--no-restore</option></arg>
99
92
    </cmdsynopsis>
100
93
    <cmdsynopsis>
101
94
      <command>&COMMANDNAME;</command>
119
112
    <para>
120
113
      <command>&COMMANDNAME;</command> is a server daemon which
121
114
      handles incoming request for passwords for a pre-defined list of
122
 
      client host computers. For an introduction, see
123
 
      <citerefentry><refentrytitle>intro</refentrytitle>
124
 
      <manvolnum>8mandos</manvolnum></citerefentry>. The Mandos server
125
 
      uses Zeroconf to announce itself on the local network, and uses
126
 
      TLS to communicate securely with and to authenticate the
127
 
      clients.  The Mandos server uses IPv6 to allow Mandos clients to
128
 
      use IPv6 link-local addresses, since the clients will probably
129
 
      not have any other addresses configured (see <xref
130
 
      linkend="overview"/>).  Any authenticated client is then given
131
 
      the stored pre-encrypted password for that specific client.
 
115
      client host computers.  The Mandos server uses Zeroconf to
 
116
      announce itself on the local network, and uses TLS to
 
117
      communicate securely with and to authenticate the clients.  The
 
118
      Mandos server uses IPv6 to allow Mandos clients to use IPv6
 
119
      link-local addresses, since the clients will probably not have
 
120
      any other addresses configured (see <xref linkend="overview"/>).
 
121
      Any authenticated client is then given the stored pre-encrypted
 
122
      password for that specific client.
132
123
    </para>
133
124
  </refsect1>
134
125
  
203
194
      </varlistentry>
204
195
      
205
196
      <varlistentry>
206
 
        <term><option>--debuglevel
207
 
        <replaceable>LEVEL</replaceable></option></term>
208
 
        <listitem>
209
 
          <para>
210
 
            Set the debugging log level.
211
 
            <replaceable>LEVEL</replaceable> is a string, one of
212
 
            <quote><literal>CRITICAL</literal></quote>,
213
 
            <quote><literal>ERROR</literal></quote>,
214
 
            <quote><literal>WARNING</literal></quote>,
215
 
            <quote><literal>INFO</literal></quote>, or
216
 
            <quote><literal>DEBUG</literal></quote>, in order of
217
 
            increasing verbosity.  The default level is
218
 
            <quote><literal>WARNING</literal></quote>.
219
 
          </para>
220
 
        </listitem>
221
 
      </varlistentry>
222
 
      
223
 
      <varlistentry>
224
197
        <term><option>--priority <replaceable>
225
198
        PRIORITY</replaceable></option></term>
226
199
        <listitem>
277
250
          <xi:include href="mandos-options.xml" xpointer="ipv6"/>
278
251
        </listitem>
279
252
      </varlistentry>
280
 
      
281
 
      <varlistentry>
282
 
        <term><option>--no-restore</option></term>
283
 
        <listitem>
284
 
          <xi:include href="mandos-options.xml" xpointer="restore"/>
285
 
        </listitem>
286
 
      </varlistentry>
287
253
    </variablelist>
288
254
  </refsect1>
289
255
  
361
327
      The server will, by default, continually check that the clients
362
328
      are still up.  If a client has not been confirmed as being up
363
329
      for some time, the client is assumed to be compromised and is no
364
 
      longer eligible to receive the encrypted password.  (Manual
365
 
      intervention is required to re-enable a client.)  The timeout,
366
 
      extended timeout, checker program, and interval between checks
367
 
      can be configured both globally and per client; see
368
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
369
 
      <manvolnum>5</manvolnum></citerefentry>.  A client successfully
370
 
      receiving its password will also be treated as a successful
371
 
      checker run.
372
 
    </para>
373
 
  </refsect1>
374
 
  
375
 
  <refsect1 id="approval">
376
 
    <title>APPROVAL</title>
377
 
    <para>
378
 
      The server can be configured to require manual approval for a
379
 
      client before it is sent its secret.  The delay to wait for such
380
 
      approval and the default action (approve or deny) can be
381
 
      configured both globally and per client; see <citerefentry>
 
330
      longer eligible to receive the encrypted password.  The timeout,
 
331
      checker program, and interval between checks can be configured
 
332
      both globally and per client; see <citerefentry>
382
333
      <refentrytitle>mandos-clients.conf</refentrytitle>
383
 
      <manvolnum>5</manvolnum></citerefentry>.  By default all clients
384
 
      will be approved immediately without delay.
385
 
    </para>
386
 
    <para>
387
 
      This can be used to deny a client its secret if not manually
388
 
      approved within a specified time.  It can also be used to make
389
 
      the server delay before giving a client its secret, allowing
390
 
      optional manual denying of this specific client.
391
 
    </para>
392
 
    
 
334
      <manvolnum>5</manvolnum></citerefentry>.
 
335
    </para>
393
336
  </refsect1>
394
337
  
395
338
  <refsect1 id="logging">
396
339
    <title>LOGGING</title>
397
340
    <para>
398
341
      The server will send log message with various severity levels to
399
 
      <filename class="devicefile">/dev/log</filename>.  With the
 
342
      <filename>/dev/log</filename>.  With the
400
343
      <option>--debug</option> option, it will log even more messages,
401
344
      and also show them on the console.
402
345
    </para>
407
350
    <para>
408
351
      The server will by default provide a D-Bus system bus interface.
409
352
      This interface will only be accessible by the root user or a
410
 
      Mandos-specific user, if such a user exists.  For documentation
411
 
      of the D-Bus API, see the file <filename>DBUS-API</filename>.
 
353
      Mandos-specific user, if such a user exists.
 
354
      <!-- XXX -->
412
355
    </para>
413
356
  </refsect1>
414
357
  
472
415
        <term><filename>/var/run/mandos.pid</filename></term>
473
416
        <listitem>
474
417
          <para>
475
 
            The file containing the process id of the
476
 
            <command>&COMMANDNAME;</command> process started last.
 
418
            The file containing the process id of
 
419
            <command>&COMMANDNAME;</command>.
477
420
          </para>
478
421
        </listitem>
479
422
      </varlistentry>
480
423
      <varlistentry>
481
 
        <term><filename class="devicefile">/dev/log</filename></term>
 
424
        <term><filename>/dev/log</filename></term>
482
425
        <listitem>
483
426
          <para>
484
427
            The Unix domain socket to where local syslog messages are
507
450
      backtrace.  This could be considered a feature.
508
451
    </para>
509
452
    <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"/>.
 
453
      Currently, if a client is declared <quote>invalid</quote> due to
 
454
      having timed out, the server does not record this fact onto
 
455
      permanent storage.  This has some security implications, see
 
456
      <xref linkend="clients"/>.
 
457
    </para>
 
458
    <para>
 
459
      There is currently no way of querying the server of the current
 
460
      status of clients, other than analyzing its <systemitem
 
461
      class="service">syslog</systemitem> output.
513
462
    </para>
514
463
    <para>
515
464
      There is no fine-grained control over logging and debug output.
518
467
      Debug mode is conflated with running in the foreground.
519
468
    </para>
520
469
    <para>
 
470
      The console log messages do not show a time stamp.
 
471
    </para>
 
472
    <para>
521
473
      This server does not check the expire time of clients’ OpenPGP
522
474
      keys.
523
475
    </para>
594
546
      </para>
595
547
      <para>
596
548
        If a client is compromised, its downtime should be duly noted
597
 
        by the server which would therefore disable the client.  But
598
 
        if the server was ever restarted, it would re-read its client
599
 
        list from its configuration file and again regard all clients
600
 
        therein as enabled, and hence eligible to receive their
601
 
        passwords.  Therefore, be careful when restarting servers if
602
 
        it is suspected that a client has, in fact, been compromised
603
 
        by parties who may now be running a fake Mandos client with
604
 
        the keys from the non-encrypted initial <acronym>RAM</acronym>
605
 
        image of the client host.  What should be done in that case
606
 
        (if restarting the server program really is necessary) is to
607
 
        stop the server program, edit the configuration file to omit
608
 
        any suspect clients, and restart the server program.
 
549
        by the server which would therefore declare the client
 
550
        invalid.  But if the server was ever restarted, it would
 
551
        re-read its client list from its configuration file and again
 
552
        regard all clients therein as valid, and hence eligible to
 
553
        receive their passwords.  Therefore, be careful when
 
554
        restarting servers if it is suspected that a client has, in
 
555
        fact, been compromised by parties who may now be running a
 
556
        fake Mandos client with the keys from the non-encrypted
 
557
        initial <acronym>RAM</acronym> image of the client host.  What
 
558
        should be done in that case (if restarting the server program
 
559
        really is necessary) is to stop the server program, edit the
 
560
        configuration file to omit any suspect clients, and restart
 
561
        the server program.
609
562
      </para>
610
563
      <para>
611
564
        For more details on client-side security, see
618
571
  <refsect1 id="see_also">
619
572
    <title>SEE ALSO</title>
620
573
    <para>
621
 
      <citerefentry><refentrytitle>intro</refentrytitle>
622
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
623
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
624
 
      <manvolnum>5</manvolnum></citerefentry>,
625
 
      <citerefentry><refentrytitle>mandos.conf</refentrytitle>
626
 
      <manvolnum>5</manvolnum></citerefentry>,
627
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
628
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
629
 
      <citerefentry><refentrytitle>sh</refentrytitle>
630
 
      <manvolnum>1</manvolnum></citerefentry>
 
574
      <citerefentry>
 
575
        <refentrytitle>mandos-clients.conf</refentrytitle>
 
576
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
 
577
        <refentrytitle>mandos.conf</refentrytitle>
 
578
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
 
579
        <refentrytitle>mandos-client</refentrytitle>
 
580
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
 
581
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
 
582
      </citerefentry>
631
583
    </para>
632
584
    <variablelist>
633
585
      <varlistentry>