/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-19 23:44:17 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080819234417-8dz5prw19ihrklx6
* Makefile (DOCBOOKTOMAN): Include all DocBook-to-manpage-related
                           commands here, and use it everywhere.
  (mandos.8, mandos.conf.5): New; also depend on "mandos-options.xml".

* mandos-keygen.xml: Removed OVERVIEW entity.  Add XInclude namespace.
  (OVERVIEW): Changed to do <xi:include/>.

* mandos-options.xml (<simplesect>): Changed to a <section>.
  ([@id="address"]): Reordered sentences.

* mandos.conf.xml (OPTIONS): Removed illegal <arg> tags.
  (EXAMPLE): Added empty example.

* mandos.xml (NETWORK PROTOCOL): Bug fix: Changed "1\r\en" back to
                                 "1\r\n".
  (CHECKING): Do not refer to the non-relevant mandos.conf(5) manual.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos.xml
3
3
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
4
<!ENTITY VERSION "1.0">
5
5
<!ENTITY COMMANDNAME "mandos">
6
 
<!ENTITY TIMESTAMP "2008-09-04">
7
6
]>
8
7
 
9
8
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
10
9
  <refentryinfo>
11
 
    <title>Mandos Manual</title>
 
10
    <title>&COMMANDNAME;</title>
12
11
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
 
    <productname>Mandos</productname>
 
12
    <productname>&COMMANDNAME;</productname>
14
13
    <productnumber>&VERSION;</productnumber>
15
 
    <date>&TIMESTAMP;</date>
16
14
    <authorgroup>
17
15
      <author>
18
16
        <firstname>Björn</firstname>
34
32
      <holder>Teddy Hogeborn</holder>
35
33
      <holder>Björn Påhlsson</holder>
36
34
    </copyright>
37
 
    <xi:include href="legalnotice.xml"/>
 
35
    <legalnotice>
 
36
      <para>
 
37
        This manual page is free software: you can redistribute it
 
38
        and/or modify it under the terms of the GNU General Public
 
39
        License as published by the Free Software Foundation,
 
40
        either version 3 of the License, or (at your option) any
 
41
        later version.
 
42
      </para>
 
43
 
 
44
      <para>
 
45
        This manual page is distributed in the hope that it will
 
46
        be useful, but WITHOUT ANY WARRANTY; without even the
 
47
        implied warranty of MERCHANTABILITY or FITNESS FOR A
 
48
        PARTICULAR PURPOSE.  See the GNU General Public License
 
49
        for more details.
 
50
      </para>
 
51
 
 
52
      <para>
 
53
        You should have received a copy of the GNU General Public
 
54
        License along with this program; If not, see
 
55
        <ulink url="http://www.gnu.org/licenses/"/>.
 
56
      </para>
 
57
    </legalnotice>
38
58
  </refentryinfo>
39
59
 
40
60
  <refmeta>
45
65
  <refnamediv>
46
66
    <refname><command>&COMMANDNAME;</command></refname>
47
67
    <refpurpose>
48
 
      Gives encrypted passwords to authenticated Mandos clients
 
68
      Sends encrypted passwords to authenticated Mandos clients
49
69
    </refpurpose>
50
70
  </refnamediv>
51
71
 
52
72
  <refsynopsisdiv>
53
73
    <cmdsynopsis>
54
74
      <command>&COMMANDNAME;</command>
55
 
      <group>
56
 
        <arg choice="plain"><option>--interface
57
 
        <replaceable>NAME</replaceable></option></arg>
58
 
        <arg choice="plain"><option>-i
59
 
        <replaceable>NAME</replaceable></option></arg>
60
 
      </group>
61
 
      <sbr/>
62
 
      <group>
63
 
        <arg choice="plain"><option>--address
64
 
        <replaceable>ADDRESS</replaceable></option></arg>
65
 
        <arg choice="plain"><option>-a
66
 
        <replaceable>ADDRESS</replaceable></option></arg>
67
 
      </group>
68
 
      <sbr/>
69
 
      <group>
70
 
        <arg choice="plain"><option>--port
71
 
        <replaceable>PORT</replaceable></option></arg>
72
 
        <arg choice="plain"><option>-p
73
 
        <replaceable>PORT</replaceable></option></arg>
74
 
      </group>
75
 
      <sbr/>
76
 
      <arg><option>--priority
77
 
      <replaceable>PRIORITY</replaceable></option></arg>
78
 
      <sbr/>
79
 
      <arg><option>--servicename
80
 
      <replaceable>NAME</replaceable></option></arg>
81
 
      <sbr/>
82
 
      <arg><option>--configdir
83
 
      <replaceable>DIRECTORY</replaceable></option></arg>
84
 
      <sbr/>
85
 
      <arg><option>--debug</option></arg>
 
75
      <arg>--interface<arg choice="plain">IF</arg></arg>
 
76
      <arg>--address<arg choice="plain">ADDRESS</arg></arg>
 
77
      <arg>--port<arg choice="plain">PORT</arg></arg>
 
78
      <arg>--priority<arg choice="plain">PRIORITY</arg></arg>
 
79
      <arg>--servicename<arg choice="plain">NAME</arg></arg>
 
80
      <arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>
 
81
      <arg>--debug</arg>
 
82
    </cmdsynopsis>
 
83
    <cmdsynopsis>
 
84
      <command>&COMMANDNAME;</command>
 
85
      <arg>-i<arg choice="plain">IF</arg></arg>
 
86
      <arg>-a<arg choice="plain">ADDRESS</arg></arg>
 
87
      <arg>-p<arg choice="plain">PORT</arg></arg>
 
88
      <arg>--priority<arg choice="plain">PRIORITY</arg></arg>
 
89
      <arg>--servicename<arg choice="plain">NAME</arg></arg>
 
90
      <arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>
 
91
      <arg>--debug</arg>
86
92
    </cmdsynopsis>
87
93
    <cmdsynopsis>
88
94
      <command>&COMMANDNAME;</command>
89
95
      <group choice="req">
90
 
        <arg choice="plain"><option>--help</option></arg>
91
 
        <arg choice="plain"><option>-h</option></arg>
 
96
        <arg choice="plain">-h</arg>
 
97
        <arg choice="plain">--help</arg>
92
98
      </group>
93
99
    </cmdsynopsis>
94
100
    <cmdsynopsis>
95
101
      <command>&COMMANDNAME;</command>
96
 
      <arg choice="plain"><option>--version</option></arg>
 
102
      <arg choice="plain">--version</arg>
97
103
    </cmdsynopsis>
98
104
    <cmdsynopsis>
99
105
      <command>&COMMANDNAME;</command>
100
 
      <arg choice="plain"><option>--check</option></arg>
 
106
      <arg choice="plain">--check</arg>
101
107
    </cmdsynopsis>
102
108
  </refsynopsisdiv>
103
109
 
115
121
      Any authenticated client is then given the stored pre-encrypted
116
122
      password for that specific client.
117
123
    </para>
 
124
 
118
125
  </refsect1>
119
126
  
120
127
  <refsect1 id="purpose">
121
128
    <title>PURPOSE</title>
 
129
 
122
130
    <para>
123
131
      The purpose of this is to enable <emphasis>remote and unattended
124
132
      rebooting</emphasis> of client host computer with an
125
133
      <emphasis>encrypted root file system</emphasis>.  See <xref
126
134
      linkend="overview"/> for details.
127
135
    </para>
 
136
 
128
137
  </refsect1>
129
138
  
130
139
  <refsect1 id="options">
131
140
    <title>OPTIONS</title>
 
141
 
132
142
    <variablelist>
133
143
      <varlistentry>
134
 
        <term><option>--help</option></term>
135
 
        <term><option>-h</option></term>
 
144
        <term><literal>-h</literal>, <literal>--help</literal></term>
136
145
        <listitem>
137
146
          <para>
138
147
            Show a help message and exit
139
148
          </para>
140
149
        </listitem>
141
150
      </varlistentry>
142
 
      
 
151
 
143
152
      <varlistentry>
144
 
        <term><option>--interface</option>
145
 
        <replaceable>NAME</replaceable></term>
146
 
        <term><option>-i</option>
147
 
        <replaceable>NAME</replaceable></term>
 
153
        <term><literal>-i</literal>, <literal>--interface <replaceable>
 
154
        IF</replaceable></literal></term>
148
155
        <listitem>
149
156
          <xi:include href="mandos-options.xml" xpointer="interface"/>
150
157
        </listitem>
151
158
      </varlistentry>
152
 
      
 
159
 
153
160
      <varlistentry>
154
 
        <term><option>--address
155
 
        <replaceable>ADDRESS</replaceable></option></term>
156
 
        <term><option>-a
157
 
        <replaceable>ADDRESS</replaceable></option></term>
 
161
        <term><literal>-a</literal>, <literal>--address <replaceable>
 
162
        ADDRESS</replaceable></literal></term>
158
163
        <listitem>
159
164
          <xi:include href="mandos-options.xml" xpointer="address"/>
160
165
        </listitem>
161
166
      </varlistentry>
162
 
      
 
167
 
163
168
      <varlistentry>
164
 
        <term><option>--port
165
 
        <replaceable>PORT</replaceable></option></term>
166
 
        <term><option>-p
167
 
        <replaceable>PORT</replaceable></option></term>
 
169
        <term><literal>-p</literal>, <literal>--port <replaceable>
 
170
        PORT</replaceable></literal></term>
168
171
        <listitem>
169
172
          <xi:include href="mandos-options.xml" xpointer="port"/>
170
173
        </listitem>
171
174
      </varlistentry>
172
 
      
 
175
 
173
176
      <varlistentry>
174
 
        <term><option>--check</option></term>
 
177
        <term><literal>--check</literal></term>
175
178
        <listitem>
176
179
          <para>
177
180
            Run the server’s self-tests.  This includes any unit
179
182
          </para>
180
183
        </listitem>
181
184
      </varlistentry>
182
 
      
 
185
 
183
186
      <varlistentry>
184
 
        <term><option>--debug</option></term>
 
187
        <term><literal>--debug</literal></term>
185
188
        <listitem>
186
189
          <xi:include href="mandos-options.xml" xpointer="debug"/>
187
190
        </listitem>
188
191
      </varlistentry>
189
192
 
190
193
      <varlistentry>
191
 
        <term><option>--priority <replaceable>
192
 
        PRIORITY</replaceable></option></term>
 
194
        <term><literal>--priority <replaceable>
 
195
        PRIORITY</replaceable></literal></term>
193
196
        <listitem>
194
197
          <xi:include href="mandos-options.xml" xpointer="priority"/>
195
198
        </listitem>
196
199
      </varlistentry>
197
200
 
198
201
      <varlistentry>
199
 
        <term><option>--servicename
200
 
        <replaceable>NAME</replaceable></option></term>
 
202
        <term><literal>--servicename <replaceable>NAME</replaceable>
 
203
        </literal></term>
201
204
        <listitem>
202
205
          <xi:include href="mandos-options.xml"
203
206
                      xpointer="servicename"/>
205
208
      </varlistentry>
206
209
 
207
210
      <varlistentry>
208
 
        <term><option>--configdir
209
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
211
        <term><literal>--configdir <replaceable>DIR</replaceable>
 
212
        </literal></term>
210
213
        <listitem>
211
214
          <para>
212
215
            Directory to search for configuration files.  Default is
220
223
      </varlistentry>
221
224
 
222
225
      <varlistentry>
223
 
        <term><option>--version</option></term>
 
226
        <term><literal>--version</literal></term>
224
227
        <listitem>
225
228
          <para>
226
229
            Prints the program version and exit.
236
239
    <para>
237
240
      This program is the server part.  It is a normal server program
238
241
      and will run in a normal system environment, not in an initial
239
 
      <acronym>RAM</acronym> disk environment.
 
242
      RAM disk environment.
240
243
    </para>
241
244
  </refsect1>
242
245
 
334
337
    <title>ENVIRONMENT</title>
335
338
    <variablelist>
336
339
      <varlistentry>
337
 
        <term><envar>PATH</envar></term>
 
340
        <term><varname>PATH</varname></term>
338
341
        <listitem>
339
342
          <para>
340
343
            To start the configured checker (see <xref
434
437
      Debug mode is conflated with running in the foreground.
435
438
    </para>
436
439
    <para>
437
 
      The console log messages does not show a time stamp.
438
 
    </para>
439
 
    <para>
440
 
      This server does not check the expire time of clients’ OpenPGP
441
 
      keys.
 
440
      The console log messages does not show a timestamp.
442
441
    </para>
443
442
  </refsect1>
444
443
  
449
448
        Normal invocation needs no options:
450
449
      </para>
451
450
      <para>
452
 
        <userinput>&COMMANDNAME;</userinput>
 
451
        <userinput>mandos</userinput>
453
452
      </para>
454
453
    </informalexample>
455
454
    <informalexample>
462
461
      <para>
463
462
 
464
463
<!-- do not wrap this line -->
465
 
<userinput>&COMMANDNAME; --debug --configdir ~/mandos --servicename Test</userinput>
 
464
<userinput>mandos --debug --configdir ~/mandos --servicename Test</userinput>
466
465
 
467
466
      </para>
468
467
    </informalexample>
474
473
      <para>
475
474
 
476
475
<!-- do not wrap this line -->
477
 
<userinput>&COMMANDNAME; --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>
 
476
<userinput>mandos --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>
478
477
 
479
478
      </para>
480
479
    </informalexample>
521
520
        restarting servers if it is suspected that a client has, in
522
521
        fact, been compromised by parties who may now be running a
523
522
        fake Mandos client with the keys from the non-encrypted
524
 
        initial <acronym>RAM</acronym> image of the client host.  What
525
 
        should be done in that case (if restarting the server program
526
 
        really is necessary) is to stop the server program, edit the
 
523
        initial RAM image of the client host.  What should be done in
 
524
        that case (if restarting the server program really is
 
525
        necessary) is to stop the server program, edit the
527
526
        configuration file to omit any suspect clients, and restart
528
527
        the server program.
529
528
      </para>
537
536
 
538
537
  <refsect1 id="see_also">
539
538
    <title>SEE ALSO</title>
540
 
    <para>
541
 
      <citerefentry>
542
 
        <refentrytitle>mandos-clients.conf</refentrytitle>
543
 
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
544
 
        <refentrytitle>mandos.conf</refentrytitle>
545
 
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
546
 
        <refentrytitle>password-request</refentrytitle>
547
 
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
548
 
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
549
 
      </citerefentry>
550
 
    </para>
551
539
    <variablelist>
552
540
      <varlistentry>
553
541
        <term>
 
542
          <citerefentry>
 
543
            <refentrytitle>password-request</refentrytitle>
 
544
            <manvolnum>8mandos</manvolnum>
 
545
          </citerefentry>
 
546
        </term>
 
547
        <listitem>
 
548
          <para>
 
549
            This is the actual program which talks to this server.
 
550
            Note that it is normally not invoked directly, and is only
 
551
            run in the initial RAM disk environment, and not on a
 
552
            fully started system.
 
553
          </para>
 
554
        </listitem>
 
555
      </varlistentry>
 
556
      <varlistentry>
 
557
        <term>
554
558
          <ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
555
559
        </term>
556
560
        <listitem>
573
577
      </varlistentry>
574
578
      <varlistentry>
575
579
        <term>
576
 
          <ulink url="http://www.gnu.org/software/gnutls/"
577
 
          >GnuTLS</ulink>
 
580
          <ulink
 
581
              url="http://www.gnu.org/software/gnutls/">GnuTLS</ulink>
578
582
        </term>
579
583
      <listitem>
580
584
        <para>
586
590
      </varlistentry>
587
591
      <varlistentry>
588
592
        <term>
589
 
          RFC 4291: <citetitle>IP Version 6 Addressing
590
 
          Architecture</citetitle>
 
593
          <citation>RFC 4291: <citetitle>IP Version 6 Addressing
 
594
          Architecture</citetitle>, section 2.5.6, Link-Local IPv6
 
595
          Unicast Addresses</citation>
591
596
        </term>
592
597
        <listitem>
593
 
          <variablelist>
594
 
            <varlistentry>
595
 
              <term>Section 2.2: <citetitle>Text Representation of
596
 
              Addresses</citetitle></term>
597
 
              <listitem><para/></listitem>
598
 
            </varlistentry>
599
 
            <varlistentry>
600
 
              <term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6
601
 
              Address</citetitle></term>
602
 
              <listitem><para/></listitem>
603
 
            </varlistentry>
604
 
            <varlistentry>
605
 
            <term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast
606
 
            Addresses</citetitle></term>
607
 
            <listitem>
608
 
              <para>
609
 
                The clients use IPv6 link-local addresses, which are
610
 
                immediately usable since a link-local addresses is
611
 
                automatically assigned to a network interfaces when it
612
 
                is brought up.
613
 
              </para>
614
 
            </listitem>
615
 
            </varlistentry>
616
 
          </variablelist>
 
598
          <para>
 
599
            The clients use IPv6 link-local addresses, which are
 
600
            immediately usable since a link-local addresses is
 
601
            automatically assigned to a network interfaces when it is
 
602
            brought up.
 
603
          </para>
617
604
        </listitem>
618
605
      </varlistentry>
619
606
      <varlistentry>
620
607
        <term>
621
 
          RFC 4346: <citetitle>The Transport Layer Security (TLS)
622
 
          Protocol Version 1.1</citetitle>
 
608
          <citation>RFC 4346: <citetitle>The Transport Layer Security
 
609
          (TLS) Protocol Version 1.1</citetitle></citation>
623
610
        </term>
624
611
      <listitem>
625
612
        <para>
629
616
      </varlistentry>
630
617
      <varlistentry>
631
618
        <term>
632
 
          RFC 4880: <citetitle>OpenPGP Message Format</citetitle>
 
619
          <citation>RFC 4880: <citetitle>OpenPGP Message
 
620
          Format</citetitle></citation>
633
621
        </term>
634
622
      <listitem>
635
623
        <para>
639
627
      </varlistentry>
640
628
      <varlistentry>
641
629
        <term>
642
 
          RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer
643
 
          Security</citetitle>
 
630
          <citation>RFC 5081: <citetitle>Using OpenPGP Keys for
 
631
          Transport Layer Security</citetitle></citation>
644
632
        </term>
645
633
      <listitem>
646
634
        <para>
652
640
    </variablelist>
653
641
  </refsect1>
654
642
</refentry>
655
 
<!-- Local Variables: -->
656
 
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
657
 
<!-- time-stamp-end: "[\"']>" -->
658
 
<!-- time-stamp-format: "%:y-%02m-%02d" -->
659
 
<!-- End: -->