/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: 2008-08-17 22:42:28 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080817224228-nhor2yuv230if01i
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
                           not rely on a stylesheet declaration.

* mandos.xml: Removed <?xml-stylesheet>.  New entity "&OVERVIEW;"
              refers to "overview.xml". Changed all single quotes to
              double quotes for consistency.
  (DESCRIPTION): Use the term "TLS" and not "GnuTLS" for the protocol.
                 Refer to the "OVERVIEW" section for reason for IPv6
                 link-local addresses.
  (PURPOSE): Shortened a lot.  Refer to "OVERVIEW" section for details.
  (OVERVIEW): New section.  Include &OVERVIEW; and add a paragraph
              about what the role of this program is.
  (SECURITY/CLIENTS): Refer to the "CHECKING" section for details on
                      checking.
  (SEE ALSO): Changed from an <itemizedlist> to a <variablelist>.
              Added a short text for each entry.  Removed reference to
              plugin-runner(8mandos).  Add reference to RFC 4291 and
              RFC 4346.

* overview.xml: New file, containing a single <para>.  The idea is to
                use this in all the man pages.

* plugins.d/password-request.c: Updated comments about spurious
                                warnings.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos.xml
1
 
<?xml version='1.0' encoding='UTF-8'?>
2
 
<?xml-stylesheet type="text/xsl"
3
 
        href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>
 
1
<?xml version="1.0" encoding="UTF-8"?>
4
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
5
 
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
 
3
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
6
4
<!ENTITY VERSION "1.0">
7
5
<!ENTITY COMMANDNAME "mandos">
 
6
<!ENTITY OVERVIEW SYSTEM "overview.xml">
8
7
]>
9
8
 
10
9
<refentry>
11
10
  <refentryinfo>
12
11
    <title>&COMMANDNAME;</title>
13
 
    <!-- NWalsh's docbook scripts use this to generate the footer: -->
 
12
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
14
13
    <productname>&COMMANDNAME;</productname>
15
14
    <productnumber>&VERSION;</productnumber>
16
15
    <authorgroup>
74
73
  <refsynopsisdiv>
75
74
    <cmdsynopsis>
76
75
      <command>&COMMANDNAME;</command>
77
 
      <arg choice='opt'>--interface<arg choice='plain'>IF</arg></arg>
78
 
      <arg choice='opt'>--address<arg choice='plain'>ADDRESS</arg></arg>
79
 
      <arg choice='opt'>--port<arg choice='plain'>PORT</arg></arg>
80
 
      <arg choice='opt'>--priority<arg choice='plain'>PRIORITY</arg></arg>
81
 
      <arg choice='opt'>--servicename<arg choice='plain'>NAME</arg></arg>
82
 
      <arg choice='opt'>--configdir<arg choice='plain'>DIRECTORY</arg></arg>
83
 
      <arg choice='opt'>--debug</arg>
84
 
    </cmdsynopsis>
85
 
    <cmdsynopsis>
86
 
      <command>&COMMANDNAME;</command>
87
 
      <arg choice='opt'>-i<arg choice='plain'>IF</arg></arg>
88
 
      <arg choice='opt'>-a<arg choice='plain'>ADDRESS</arg></arg>
89
 
      <arg choice='opt'>-p<arg choice='plain'>PORT</arg></arg>
90
 
      <arg choice='opt'>--priority<arg choice='plain'>PRIORITY</arg></arg>
91
 
      <arg choice='opt'>--servicename<arg choice='plain'>NAME</arg></arg>
92
 
      <arg choice='opt'>--configdir<arg choice='plain'>DIRECTORY</arg></arg>
93
 
      <arg choice='opt'>--debug</arg>
94
 
    </cmdsynopsis>
95
 
    <cmdsynopsis>
96
 
      <command>&COMMANDNAME;</command>
97
 
      <arg choice='plain'>--help</arg>
98
 
    </cmdsynopsis>
99
 
    <cmdsynopsis>
100
 
      <command>&COMMANDNAME;</command>
101
 
      <arg choice='plain'>--version</arg>
102
 
    </cmdsynopsis>
103
 
    <cmdsynopsis>
104
 
      <command>&COMMANDNAME;</command>
105
 
      <arg choice='plain'>--check</arg>
 
76
      <arg choice="opt">--interface<arg choice="plain">IF</arg></arg>
 
77
      <arg choice="opt">--address<arg choice="plain">ADDRESS</arg></arg>
 
78
      <arg choice="opt">--port<arg choice="plain">PORT</arg></arg>
 
79
      <arg choice="opt">--priority<arg choice="plain">PRIORITY</arg></arg>
 
80
      <arg choice="opt">--servicename<arg choice="plain">NAME</arg></arg>
 
81
      <arg choice="opt">--configdir<arg choice="plain">DIRECTORY</arg></arg>
 
82
      <arg choice="opt">--debug</arg>
 
83
    </cmdsynopsis>
 
84
    <cmdsynopsis>
 
85
      <command>&COMMANDNAME;</command>
 
86
      <arg choice="opt">-i<arg choice="plain">IF</arg></arg>
 
87
      <arg choice="opt">-a<arg choice="plain">ADDRESS</arg></arg>
 
88
      <arg choice="opt">-p<arg choice="plain">PORT</arg></arg>
 
89
      <arg choice="opt">--priority<arg choice="plain">PRIORITY</arg></arg>
 
90
      <arg choice="opt">--servicename<arg choice="plain">NAME</arg></arg>
 
91
      <arg choice="opt">--configdir<arg choice="plain">DIRECTORY</arg></arg>
 
92
      <arg choice="opt">--debug</arg>
 
93
    </cmdsynopsis>
 
94
    <cmdsynopsis>
 
95
      <command>&COMMANDNAME;</command>
 
96
      <arg choice="plain">--help</arg>
 
97
    </cmdsynopsis>
 
98
    <cmdsynopsis>
 
99
      <command>&COMMANDNAME;</command>
 
100
      <arg choice="plain">--version</arg>
 
101
    </cmdsynopsis>
 
102
    <cmdsynopsis>
 
103
      <command>&COMMANDNAME;</command>
 
104
      <arg choice="plain">--check</arg>
106
105
    </cmdsynopsis>
107
106
  </refsynopsisdiv>
108
107
 
112
111
      <command>&COMMANDNAME;</command> is a server daemon which
113
112
      handles incoming request for passwords for a pre-defined list of
114
113
      client host computers.  The Mandos server uses Zeroconf to
115
 
      announce itself on the local network, and uses GnuTLS to
116
 
      communicate securely with and to authenticate the clients.
117
 
      Mandos uses IPv6 link-local addresses, since the clients are
118
 
      assumed to not have any other addresses configured.  Any
119
 
      authenticated client is then given the pre-encrypted password
120
 
      for that specific client.
 
114
      announce itself on the local network, and uses TLS to
 
115
      communicate securely with and to authenticate the clients.  The
 
116
      Mandos server uses IPv6 to allow Mandos clients to use IPv6
 
117
      link-local addresses, since the clients will probably not have
 
118
      any other addresses configured (see <xref linkend="overview"/>).
 
119
      Any authenticated client is then given the stored pre-encrypted
 
120
      password for that specific client.
121
121
    </para>
122
122
 
123
123
  </refsect1>
127
127
 
128
128
    <para>
129
129
      The purpose of this is to enable <emphasis>remote and unattended
130
 
      rebooting</emphasis> of any client host computer with an
131
 
      <emphasis>encrypted root file system</emphasis>.  The client
132
 
      host computer should start a Mandos client in the initial RAM
133
 
      disk environment, the Mandos client program communicates with
134
 
      this server program to get an encrypted password, which is then
135
 
      decrypted and used to unlock the encrypted root file system.
136
 
      The client host computer can then continue its boot sequence
137
 
      normally.
 
130
      rebooting</emphasis> of client host computer with an
 
131
      <emphasis>encrypted root file system</emphasis>.  See <xref
 
132
      linkend="overview"/> for details.
138
133
    </para>
139
134
 
140
135
  </refsect1>
197
192
        <term><literal>--check</literal></term>
198
193
        <listitem>
199
194
          <para>
200
 
            Run the server's self-tests.  This includes any unit
 
195
            Run the server’s self-tests.  This includes any unit
201
196
            tests, etc.
202
197
          </para>
203
198
        </listitem>
220
215
        <listitem>
221
216
          <para>
222
217
            GnuTLS priority string for the TLS handshake with the
223
 
            clients.  See
224
 
            <citerefentry><refentrytitle>gnutls_priority_init
 
218
            clients.  The default is
 
219
            <quote><literal>SECURE256:!CTYPE-X.509:+CTYPE-OPENPGP</literal></quote>.
 
220
            See <citerefentry><refentrytitle>gnutls_priority_init
225
221
            </refentrytitle><manvolnum>3</manvolnum></citerefentry>
226
 
            for the syntax.  The default is
227
 
            <quote><literal>SECURE256:!CTYPE-X.509:+CTYPE-OPENPGP</literal></quote>.
228
 
            <emphasis>Warning</emphasis>: changing this may make the
229
 
            TLS handshake fail, making communication with clients
230
 
            impossible.
 
222
            for the syntax.  <emphasis>Warning</emphasis>: changing
 
223
            this may make the TLS handshake fail, making communication
 
224
            with clients impossible.
231
225
          </para>
232
226
        </listitem>
233
227
      </varlistentry>
244
238
            which would not normally be useful.  If there are name
245
239
            collisions on the same <emphasis>network</emphasis>, the
246
240
            newer server will automatically rename itself to
247
 
            <quote><literal>Mandos #2</literal></quote>, and so on,
248
 
            therefore this option is not needed in that case.
 
241
            <quote><literal>Mandos #2</literal></quote>, and so on;
 
242
            therefore, this option is not needed in that case.
249
243
          </para>
250
244
        </listitem>
251
245
      </varlistentry>
276
270
    </variablelist>
277
271
  </refsect1>
278
272
 
 
273
  <refsect1 id="overview">
 
274
    <title>OVERVIEW</title>
 
275
    &OVERVIEW;
 
276
    <para>
 
277
      This program is the server part.  It is a normal server program
 
278
      and will run in a normal system environment, not in an initial
 
279
      RAM disk environment.
 
280
    </para>
 
281
  </refsect1>
 
282
 
279
283
  <refsect1 id="protocol">
280
284
    <title>NETWORK PROTOCOL</title>
281
285
    <para>
341
345
      are still up.  If a client has not been confirmed as being up
342
346
      for some time, the client is assumed to be compromised and is no
343
347
      longer eligible to receive the encrypted password.  The timeout,
344
 
      checker program and interval between checks can be configured
 
348
      checker program, and interval between checks can be configured
345
349
      both globally and per client; see <citerefentry>
346
350
      <refentrytitle>mandos.conf</refentrytitle>
347
351
      <manvolnum>5</manvolnum></citerefentry> and <citerefentry>
437
441
    </informalexample>
438
442
    <informalexample>
439
443
      <para>
440
 
        Run the server in debug mode and read configuration files from
441
 
        the <filename>~/mandos</filename> directory:
 
444
        Run the server in debug mode, read configuration files from
 
445
        the <filename>~/mandos</filename> directory, and use the
 
446
        Zeroconf service name <quote>Test</quote> to not collide with
 
447
        any other official Mandos server on this host:
442
448
      </para>
443
449
      <para>
444
450
 
466
472
    <refsect2>
467
473
      <title>SERVER</title>
468
474
      <para>
469
 
        Running the server should not in itself present any security
470
 
        risk to the host computer running it.
 
475
        Running this &COMMANDNAME; server program should not in itself
 
476
        present any security risk to the host computer running it.
 
477
        The program does not need any special privileges to run, and
 
478
        is designed to run as a non-root user.
471
479
      </para>
472
480
    </refsect2>
473
481
    <refsect2>
481
489
        itself and looks up the fingerprint in its list of
482
490
        clients. The <filename>clients.conf</filename> file (see
483
491
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
484
 
        <manvolnum>5</manvolnum></citerefentry>) must be non-readable
485
 
        by anyone except the user running the server.
 
492
        <manvolnum>5</manvolnum></citerefentry>)
 
493
        <emphasis>must</emphasis> be made non-readable by anyone
 
494
        except the user running the server.
 
495
      </para>
 
496
      <para>
 
497
        As detailed in <xref linkend="checking"/>, the status of all
 
498
        client computers will continually be checked and be assumed
 
499
        compromised if they are gone for too long.
486
500
      </para>
487
501
      <para>
488
502
        For more details on client-side security, see
494
508
 
495
509
  <refsect1 id="see_also">
496
510
    <title>SEE ALSO</title>
497
 
    <itemizedlist spacing="compact">
498
 
      <listitem><para>
499
 
        <citerefentry><refentrytitle>password-request</refentrytitle>
500
 
        <manvolnum>8mandos</manvolnum></citerefentry>
501
 
      </para></listitem>
502
 
      
503
 
      <listitem><para>
504
 
        <citerefentry><refentrytitle>plugin-runner</refentrytitle>
505
 
        <manvolnum>8mandos</manvolnum></citerefentry>
506
 
      </para></listitem>
507
 
      
508
 
      <listitem><para>
509
 
        <ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
510
 
      </para></listitem>
511
 
      
512
 
      <listitem><para>
513
 
        <ulink url="http://www.avahi.org/">Avahi</ulink>
514
 
      </para></listitem>
515
 
      
516
 
      <listitem><para>
517
 
        <ulink
518
 
            url="http://www.gnu.org/software/gnutls/">GnuTLS</ulink>
519
 
      </para></listitem>
520
 
      
521
 
      <listitem><para>
522
 
        <citation>RFC 4880: <citetitle>OpenPGP Message
523
 
        Format</citetitle></citation>
524
 
      </para></listitem>
525
 
      
526
 
      <listitem><para>
527
 
        <citation>RFC 5081: <citetitle>Using OpenPGP Keys for
528
 
        Transport Layer Security</citetitle></citation>
529
 
      </para></listitem>
530
 
      
531
 
      <listitem><para>
532
 
        <citation>RFC 4291: <citetitle>IP Version 6 Addressing
533
 
        Architecture</citetitle>, section 2.5.6, Link-Local IPv6
534
 
        Unicast Addresses</citation>
535
 
      </para></listitem>
536
 
    </itemizedlist>
 
511
    <variablelist>
 
512
      <varlistentry>
 
513
        <term>
 
514
          <citerefentry>
 
515
            <refentrytitle>password-request</refentrytitle>
 
516
            <manvolnum>8mandos</manvolnum>
 
517
          </citerefentry>
 
518
        </term>
 
519
        <listitem>
 
520
          <para>
 
521
            This is the actual program which talks to this server.
 
522
            Note that it is normally not invoked directly, and is only
 
523
            run in the initial RAM disk environment, and not on a
 
524
            fully started system.
 
525
          </para>
 
526
        </listitem>
 
527
      </varlistentry>
 
528
      <varlistentry>
 
529
        <term>
 
530
          <ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
 
531
        </term>
 
532
        <listitem>
 
533
          <para>
 
534
            Zeroconf is the network protocol standard used by clients
 
535
            for finding this Mandos server on the local network.
 
536
          </para>
 
537
        </listitem>
 
538
      </varlistentry>
 
539
      <varlistentry>
 
540
        <term>
 
541
          <ulink url="http://www.avahi.org/">Avahi</ulink>
 
542
        </term>
 
543
      <listitem>
 
544
        <para>
 
545
          Avahi is the library this server calls to implement
 
546
          Zeroconf service announcements.
 
547
        </para>
 
548
      </listitem>
 
549
      </varlistentry>
 
550
      <varlistentry>
 
551
        <term>
 
552
          <ulink
 
553
              url="http://www.gnu.org/software/gnutls/">GnuTLS</ulink>
 
554
        </term>
 
555
      <listitem>
 
556
        <para>
 
557
          GnuTLS is the library this server uses to implement TLS for
 
558
          communicating securely with the client, and at the same time
 
559
          confidently get the client’s public OpenPGP key.
 
560
        </para>
 
561
      </listitem>
 
562
      </varlistentry>
 
563
      <varlistentry>
 
564
        <term>
 
565
          <citation>RFC 4291: <citetitle>IP Version 6 Addressing
 
566
          Architecture</citetitle>, section 2.5.6, Link-Local IPv6
 
567
          Unicast Addresses</citation>
 
568
        </term>
 
569
        <listitem>
 
570
          <para>
 
571
            The clients use IPv6 link-local addresses, which are
 
572
            immediately usable since a link-local addresses is
 
573
            automatically assigned to a network interfaces when it is
 
574
            brought up.
 
575
          </para>
 
576
        </listitem>
 
577
      </varlistentry>
 
578
      <varlistentry>
 
579
        <term>
 
580
          <citation>RFC 4346: <citetitle>The Transport Layer Security
 
581
          (TLS) Protocol Version 1.1</citetitle></citation>
 
582
        </term>
 
583
      <listitem>
 
584
        <para>
 
585
          TLS 1.1 is the protocol implemented by GnuTLS.
 
586
        </para>
 
587
      </listitem>
 
588
      </varlistentry>
 
589
      <varlistentry>
 
590
        <term>
 
591
          <citation>RFC 4880: <citetitle>OpenPGP Message
 
592
          Format</citetitle></citation>
 
593
        </term>
 
594
      <listitem>
 
595
        <para>
 
596
          The data sent to clients is binary encrypted OpenPGP data.
 
597
        </para>
 
598
      </listitem>
 
599
      </varlistentry>
 
600
      <varlistentry>
 
601
        <term>
 
602
          <citation>RFC 5081: <citetitle>Using OpenPGP Keys for
 
603
          Transport Layer Security</citetitle></citation>
 
604
        </term>
 
605
      <listitem>
 
606
        <para>
 
607
          This is implemented by GnuTLS and used by this server so
 
608
          that OpenPGP keys can be used.
 
609
        </para>
 
610
      </listitem>
 
611
      </varlistentry>
 
612
    </variablelist>
537
613
  </refsect1>
538
614
</refentry>