/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-21">
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>
41
61
    <refentrytitle>&COMMANDNAME;</refentrytitle>
42
62
    <manvolnum>8</manvolnum>
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
 
104
110
  <refsect1 id="description">
105
111
    <title>DESCRIPTION</title>
106
112
    <para>
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"/>
204
207
        </listitem>
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
218
221
          </para>
219
222
        </listitem>
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.
229
232
      </varlistentry>
230
233
    </variablelist>
231
234
  </refsect1>
232
 
  
 
235
 
233
236
  <refsect1 id="overview">
234
237
    <title>OVERVIEW</title>
235
238
    <xi:include href="overview.xml"/>
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
 
243
246
  <refsect1 id="protocol">
244
247
    <title>NETWORK PROTOCOL</title>
245
248
    <para>
297
300
      </row>
298
301
    </tbody></tgroup></table>
299
302
  </refsect1>
300
 
  
 
303
 
301
304
  <refsect1 id="checking">
302
305
    <title>CHECKING</title>
303
306
    <para>
311
314
      <manvolnum>5</manvolnum></citerefentry>.
312
315
    </para>
313
316
  </refsect1>
314
 
  
 
317
 
315
318
  <refsect1 id="logging">
316
319
    <title>LOGGING</title>
317
320
    <para>
321
324
      and also show them on the console.
322
325
    </para>
323
326
  </refsect1>
324
 
  
 
327
 
325
328
  <refsect1 id="exit_status">
326
329
    <title>EXIT STATUS</title>
327
330
    <para>
329
332
      critical error is encountered.
330
333
    </para>
331
334
  </refsect1>
332
 
  
 
335
 
333
336
  <refsect1 id="environment">
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
349
352
      </varlistentry>
350
353
    </variablelist>
351
354
  </refsect1>
352
 
  
 
355
 
353
356
  <refsect1 id="file">
354
357
    <title>FILES</title>
355
358
    <para>
379
382
        </listitem>
380
383
      </varlistentry>
381
384
      <varlistentry>
382
 
        <term><filename>/var/run/mandos.pid</filename></term>
 
385
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
383
386
        <listitem>
384
387
          <para>
385
388
            The file containing the process id of
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>
481
480
  </refsect1>
482
 
  
 
481
 
483
482
  <refsect1 id="security">
484
483
    <title>SECURITY</title>
485
484
    <refsect2 id="SERVER">
487
486
      <para>
488
487
        Running this <command>&COMMANDNAME;</command> server program
489
488
        should not in itself present any security risk to the host
490
 
        computer running it.  The program switches to a non-root user
491
 
        soon after startup.
 
489
        computer running it.  The program does not need any special
 
490
        privileges to run, and is designed to run as a non-root user.
492
491
      </para>
493
492
    </refsect2>
494
493
    <refsect2 id="CLIENTS">
504
503
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
505
504
        <manvolnum>5</manvolnum></citerefentry>)
506
505
        <emphasis>must</emphasis> be made non-readable by anyone
507
 
        except the user starting the server (usually root).
 
506
        except the user running the server.
508
507
      </para>
509
508
      <para>
510
509
        As detailed in <xref linkend="checking"/>, the status of all
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>
530
529
      <para>
531
530
        For more details on client-side security, see
532
 
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
531
        <citerefentry><refentrytitle>password-request</refentrytitle>
533
532
        <manvolnum>8mandos</manvolnum></citerefentry>.
534
533
      </para>
535
534
    </refsect2>
536
535
  </refsect1>
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>mandos-client</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: -->