/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: Teddy Hogeborn
  • Date: 2008-10-05 17:38:31 UTC
  • Revision ID: teddy@fukt.bsnet.se-20081005173831-fysrfayl4yvhlo6x
* INSTALL: Add instructions on how to set the correct network
           interface on the cient, and also how to test the server and
           verify the password.

* TODO: Clean up old stuff.

* debian/mandos-client.README.Debian: Separate into sections with
                                      headlines.  Add instructions on
                                      how to test the server and
                                      verify the password.

* plugin-runner.conf: Add reminder to update initrd image.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos.xml
1
1
<?xml version="1.0" encoding="UTF-8"?>
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
 
<!ENTITY VERSION "1.0">
5
4
<!ENTITY COMMANDNAME "mandos">
 
5
<!ENTITY TIMESTAMP "2008-10-03">
 
6
<!ENTITY % common SYSTEM "common.ent">
 
7
%common;
6
8
]>
7
9
 
8
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
9
 
  <refentryinfo>
10
 
    <title>&COMMANDNAME;</title>
 
11
   <refentryinfo>
 
12
    <title>Mandos Manual</title>
11
13
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
12
 
    <productname>&COMMANDNAME;</productname>
13
 
    <productnumber>&VERSION;</productnumber>
 
14
    <productname>Mandos</productname>
 
15
    <productnumber>&version;</productnumber>
 
16
    <date>&TIMESTAMP;</date>
14
17
    <authorgroup>
15
18
      <author>
16
19
        <firstname>Björn</firstname>
32
35
      <holder>Teddy Hogeborn</holder>
33
36
      <holder>Björn Påhlsson</holder>
34
37
    </copyright>
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
    <xi:include href="legalnotice.xml"/>
58
39
  </refentryinfo>
59
 
 
 
40
  
60
41
  <refmeta>
61
42
    <refentrytitle>&COMMANDNAME;</refentrytitle>
62
43
    <manvolnum>8</manvolnum>
65
46
  <refnamediv>
66
47
    <refname><command>&COMMANDNAME;</command></refname>
67
48
    <refpurpose>
68
 
      Sends encrypted passwords to authenticated Mandos clients
 
49
      Gives encrypted passwords to authenticated Mandos clients
69
50
    </refpurpose>
70
51
  </refnamediv>
71
 
 
 
52
  
72
53
  <refsynopsisdiv>
73
54
    <cmdsynopsis>
74
55
      <command>&COMMANDNAME;</command>
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>
 
56
      <group>
 
57
        <arg choice="plain"><option>--interface
 
58
        <replaceable>NAME</replaceable></option></arg>
 
59
        <arg choice="plain"><option>-i
 
60
        <replaceable>NAME</replaceable></option></arg>
 
61
      </group>
 
62
      <sbr/>
 
63
      <group>
 
64
        <arg choice="plain"><option>--address
 
65
        <replaceable>ADDRESS</replaceable></option></arg>
 
66
        <arg choice="plain"><option>-a
 
67
        <replaceable>ADDRESS</replaceable></option></arg>
 
68
      </group>
 
69
      <sbr/>
 
70
      <group>
 
71
        <arg choice="plain"><option>--port
 
72
        <replaceable>PORT</replaceable></option></arg>
 
73
        <arg choice="plain"><option>-p
 
74
        <replaceable>PORT</replaceable></option></arg>
 
75
      </group>
 
76
      <sbr/>
 
77
      <arg><option>--priority
 
78
      <replaceable>PRIORITY</replaceable></option></arg>
 
79
      <sbr/>
 
80
      <arg><option>--servicename
 
81
      <replaceable>NAME</replaceable></option></arg>
 
82
      <sbr/>
 
83
      <arg><option>--configdir
 
84
      <replaceable>DIRECTORY</replaceable></option></arg>
 
85
      <sbr/>
 
86
      <arg><option>--debug</option></arg>
92
87
    </cmdsynopsis>
93
88
    <cmdsynopsis>
94
89
      <command>&COMMANDNAME;</command>
95
90
      <group choice="req">
96
 
        <arg choice="plain">-h</arg>
97
 
        <arg choice="plain">--help</arg>
 
91
        <arg choice="plain"><option>--help</option></arg>
 
92
        <arg choice="plain"><option>-h</option></arg>
98
93
      </group>
99
94
    </cmdsynopsis>
100
95
    <cmdsynopsis>
101
96
      <command>&COMMANDNAME;</command>
102
 
      <arg choice="plain">--version</arg>
 
97
      <arg choice="plain"><option>--version</option></arg>
103
98
    </cmdsynopsis>
104
99
    <cmdsynopsis>
105
100
      <command>&COMMANDNAME;</command>
106
 
      <arg choice="plain">--check</arg>
 
101
      <arg choice="plain"><option>--check</option></arg>
107
102
    </cmdsynopsis>
108
103
  </refsynopsisdiv>
109
 
 
 
104
  
110
105
  <refsect1 id="description">
111
106
    <title>DESCRIPTION</title>
112
107
    <para>
121
116
      Any authenticated client is then given the stored pre-encrypted
122
117
      password for that specific client.
123
118
    </para>
124
 
 
125
119
  </refsect1>
126
120
  
127
121
  <refsect1 id="purpose">
128
122
    <title>PURPOSE</title>
129
 
 
130
123
    <para>
131
124
      The purpose of this is to enable <emphasis>remote and unattended
132
125
      rebooting</emphasis> of client host computer with an
133
126
      <emphasis>encrypted root file system</emphasis>.  See <xref
134
127
      linkend="overview"/> for details.
135
128
    </para>
136
 
 
137
129
  </refsect1>
138
130
  
139
131
  <refsect1 id="options">
140
132
    <title>OPTIONS</title>
141
 
 
142
133
    <variablelist>
143
134
      <varlistentry>
144
 
        <term><literal>-h</literal>, <literal>--help</literal></term>
 
135
        <term><option>--help</option></term>
 
136
        <term><option>-h</option></term>
145
137
        <listitem>
146
138
          <para>
147
139
            Show a help message and exit
148
140
          </para>
149
141
        </listitem>
150
142
      </varlistentry>
151
 
 
 
143
      
152
144
      <varlistentry>
153
 
        <term><literal>-i</literal>, <literal>--interface <replaceable>
154
 
        IF</replaceable></literal></term>
 
145
        <term><option>--interface</option>
 
146
        <replaceable>NAME</replaceable></term>
 
147
        <term><option>-i</option>
 
148
        <replaceable>NAME</replaceable></term>
155
149
        <listitem>
156
150
          <xi:include href="mandos-options.xml" xpointer="interface"/>
157
151
        </listitem>
158
152
      </varlistentry>
159
 
 
 
153
      
160
154
      <varlistentry>
161
 
        <term><literal>-a</literal>, <literal>--address <replaceable>
162
 
        ADDRESS</replaceable></literal></term>
 
155
        <term><option>--address
 
156
        <replaceable>ADDRESS</replaceable></option></term>
 
157
        <term><option>-a
 
158
        <replaceable>ADDRESS</replaceable></option></term>
163
159
        <listitem>
164
160
          <xi:include href="mandos-options.xml" xpointer="address"/>
165
161
        </listitem>
166
162
      </varlistentry>
167
 
 
 
163
      
168
164
      <varlistentry>
169
 
        <term><literal>-p</literal>, <literal>--port <replaceable>
170
 
        PORT</replaceable></literal></term>
 
165
        <term><option>--port
 
166
        <replaceable>PORT</replaceable></option></term>
 
167
        <term><option>-p
 
168
        <replaceable>PORT</replaceable></option></term>
171
169
        <listitem>
172
170
          <xi:include href="mandos-options.xml" xpointer="port"/>
173
171
        </listitem>
174
172
      </varlistentry>
175
 
 
 
173
      
176
174
      <varlistentry>
177
 
        <term><literal>--check</literal></term>
 
175
        <term><option>--check</option></term>
178
176
        <listitem>
179
177
          <para>
180
178
            Run the server’s self-tests.  This includes any unit
182
180
          </para>
183
181
        </listitem>
184
182
      </varlistentry>
185
 
 
 
183
      
186
184
      <varlistentry>
187
 
        <term><literal>--debug</literal></term>
 
185
        <term><option>--debug</option></term>
188
186
        <listitem>
189
187
          <xi:include href="mandos-options.xml" xpointer="debug"/>
190
188
        </listitem>
191
189
      </varlistentry>
192
 
 
 
190
      
193
191
      <varlistentry>
194
 
        <term><literal>--priority <replaceable>
195
 
        PRIORITY</replaceable></literal></term>
 
192
        <term><option>--priority <replaceable>
 
193
        PRIORITY</replaceable></option></term>
196
194
        <listitem>
197
195
          <xi:include href="mandos-options.xml" xpointer="priority"/>
198
196
        </listitem>
199
197
      </varlistentry>
200
 
 
 
198
      
201
199
      <varlistentry>
202
 
        <term><literal>--servicename <replaceable>NAME</replaceable>
203
 
        </literal></term>
 
200
        <term><option>--servicename
 
201
        <replaceable>NAME</replaceable></option></term>
204
202
        <listitem>
205
203
          <xi:include href="mandos-options.xml"
206
204
                      xpointer="servicename"/>
207
205
        </listitem>
208
206
      </varlistentry>
209
 
 
 
207
      
210
208
      <varlistentry>
211
 
        <term><literal>--configdir <replaceable>DIR</replaceable>
212
 
        </literal></term>
 
209
        <term><option>--configdir
 
210
        <replaceable>DIRECTORY</replaceable></option></term>
213
211
        <listitem>
214
212
          <para>
215
213
            Directory to search for configuration files.  Default is
221
219
          </para>
222
220
        </listitem>
223
221
      </varlistentry>
224
 
 
 
222
      
225
223
      <varlistentry>
226
 
        <term><literal>--version</literal></term>
 
224
        <term><option>--version</option></term>
227
225
        <listitem>
228
226
          <para>
229
227
            Prints the program version and exit.
232
230
      </varlistentry>
233
231
    </variablelist>
234
232
  </refsect1>
235
 
 
 
233
  
236
234
  <refsect1 id="overview">
237
235
    <title>OVERVIEW</title>
238
236
    <xi:include href="overview.xml"/>
239
237
    <para>
240
238
      This program is the server part.  It is a normal server program
241
239
      and will run in a normal system environment, not in an initial
242
 
      RAM disk environment.
 
240
      <acronym>RAM</acronym> disk environment.
243
241
    </para>
244
242
  </refsect1>
245
 
 
 
243
  
246
244
  <refsect1 id="protocol">
247
245
    <title>NETWORK PROTOCOL</title>
248
246
    <para>
300
298
      </row>
301
299
    </tbody></tgroup></table>
302
300
  </refsect1>
303
 
 
 
301
  
304
302
  <refsect1 id="checking">
305
303
    <title>CHECKING</title>
306
304
    <para>
314
312
      <manvolnum>5</manvolnum></citerefentry>.
315
313
    </para>
316
314
  </refsect1>
317
 
 
 
315
  
318
316
  <refsect1 id="logging">
319
317
    <title>LOGGING</title>
320
318
    <para>
324
322
      and also show them on the console.
325
323
    </para>
326
324
  </refsect1>
327
 
 
 
325
  
328
326
  <refsect1 id="exit_status">
329
327
    <title>EXIT STATUS</title>
330
328
    <para>
332
330
      critical error is encountered.
333
331
    </para>
334
332
  </refsect1>
335
 
 
 
333
  
336
334
  <refsect1 id="environment">
337
335
    <title>ENVIRONMENT</title>
338
336
    <variablelist>
339
337
      <varlistentry>
340
 
        <term><varname>PATH</varname></term>
 
338
        <term><envar>PATH</envar></term>
341
339
        <listitem>
342
340
          <para>
343
341
            To start the configured checker (see <xref
352
350
      </varlistentry>
353
351
    </variablelist>
354
352
  </refsect1>
355
 
 
356
 
  <refsect1 id="file">
 
353
  
 
354
  <refsect1 id="files">
357
355
    <title>FILES</title>
358
356
    <para>
359
357
      Use the <option>--configdir</option> option to change where
382
380
        </listitem>
383
381
      </varlistentry>
384
382
      <varlistentry>
385
 
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
 
383
        <term><filename>/var/run/mandos.pid</filename></term>
386
384
        <listitem>
387
385
          <para>
388
386
            The file containing the process id of
423
421
      Currently, if a client is declared <quote>invalid</quote> due to
424
422
      having timed out, the server does not record this fact onto
425
423
      permanent storage.  This has some security implications, see
426
 
      <xref linkend="CLIENTS"/>.
 
424
      <xref linkend="clients"/>.
427
425
    </para>
428
426
    <para>
429
427
      There is currently no way of querying the server of the current
437
435
      Debug mode is conflated with running in the foreground.
438
436
    </para>
439
437
    <para>
440
 
      The console log messages does not show a timestamp.
 
438
      The console log messages does not show a time stamp.
 
439
    </para>
 
440
    <para>
 
441
      This server does not check the expire time of clients’ OpenPGP
 
442
      keys.
441
443
    </para>
442
444
  </refsect1>
443
445
  
448
450
        Normal invocation needs no options:
449
451
      </para>
450
452
      <para>
451
 
        <userinput>mandos</userinput>
 
453
        <userinput>&COMMANDNAME;</userinput>
452
454
      </para>
453
455
    </informalexample>
454
456
    <informalexample>
461
463
      <para>
462
464
 
463
465
<!-- do not wrap this line -->
464
 
<userinput>mandos --debug --configdir ~/mandos --servicename Test</userinput>
 
466
<userinput>&COMMANDNAME; --debug --configdir ~/mandos --servicename Test</userinput>
465
467
 
466
468
      </para>
467
469
    </informalexample>
473
475
      <para>
474
476
 
475
477
<!-- do not wrap this line -->
476
 
<userinput>mandos --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>
 
478
<userinput>&COMMANDNAME; --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>
477
479
 
478
480
      </para>
479
481
    </informalexample>
480
482
  </refsect1>
481
 
 
 
483
  
482
484
  <refsect1 id="security">
483
485
    <title>SECURITY</title>
484
 
    <refsect2 id="SERVER">
 
486
    <refsect2 id="server">
485
487
      <title>SERVER</title>
486
488
      <para>
487
489
        Running this <command>&COMMANDNAME;</command> server program
488
490
        should not in itself present any security risk to the host
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.
 
491
        computer running it.  The program switches to a non-root user
 
492
        soon after startup.
491
493
      </para>
492
494
    </refsect2>
493
 
    <refsect2 id="CLIENTS">
 
495
    <refsect2 id="clients">
494
496
      <title>CLIENTS</title>
495
497
      <para>
496
498
        The server only gives out its stored data to clients which
503
505
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
504
506
        <manvolnum>5</manvolnum></citerefentry>)
505
507
        <emphasis>must</emphasis> be made non-readable by anyone
506
 
        except the user running the server.
 
508
        except the user starting the server (usually root).
507
509
      </para>
508
510
      <para>
509
511
        As detailed in <xref linkend="checking"/>, the status of all
520
522
        restarting servers if it is suspected that a client has, in
521
523
        fact, been compromised by parties who may now be running a
522
524
        fake Mandos client with the keys from the non-encrypted
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
 
525
        initial <acronym>RAM</acronym> image of the client host.  What
 
526
        should be done in that case (if restarting the server program
 
527
        really is necessary) is to stop the server program, edit the
526
528
        configuration file to omit any suspect clients, and restart
527
529
        the server program.
528
530
      </para>
529
531
      <para>
530
532
        For more details on client-side security, see
531
 
        <citerefentry><refentrytitle>password-request</refentrytitle>
 
533
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
532
534
        <manvolnum>8mandos</manvolnum></citerefentry>.
533
535
      </para>
534
536
    </refsect2>
535
537
  </refsect1>
536
 
 
 
538
  
537
539
  <refsect1 id="see_also">
538
540
    <title>SEE ALSO</title>
539
541
    <para>
540
542
      <citerefentry>
 
543
        <refentrytitle>mandos-clients.conf</refentrytitle>
 
544
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
541
545
        <refentrytitle>mandos.conf</refentrytitle>
542
546
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
543
 
        <refentrytitle>mandos-clients.conf</refentrytitle>
544
 
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
545
 
        <refentrytitle>password-request</refentrytitle>
 
547
        <refentrytitle>mandos-client</refentrytitle>
546
548
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
547
549
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
548
550
      </citerefentry>
572
574
      </varlistentry>
573
575
      <varlistentry>
574
576
        <term>
575
 
          <ulink
576
 
              url="http://www.gnu.org/software/gnutls/">GnuTLS</ulink>
 
577
          <ulink url="http://www.gnu.org/software/gnutls/"
 
578
          >GnuTLS</ulink>
577
579
        </term>
578
580
      <listitem>
579
581
        <para>
585
587
      </varlistentry>
586
588
      <varlistentry>
587
589
        <term>
588
 
          <citation>RFC 4291: <citetitle>IP Version 6 Addressing
589
 
          Architecture</citetitle>, section 2.5.6, Link-Local IPv6
590
 
          Unicast Addresses</citation>
 
590
          RFC 4291: <citetitle>IP Version 6 Addressing
 
591
          Architecture</citetitle>
591
592
        </term>
592
593
        <listitem>
593
 
          <para>
594
 
            The clients use IPv6 link-local addresses, which are
595
 
            immediately usable since a link-local addresses is
596
 
            automatically assigned to a network interfaces when it is
597
 
            brought up.
598
 
          </para>
 
594
          <variablelist>
 
595
            <varlistentry>
 
596
              <term>Section 2.2: <citetitle>Text Representation of
 
597
              Addresses</citetitle></term>
 
598
              <listitem><para/></listitem>
 
599
            </varlistentry>
 
600
            <varlistentry>
 
601
              <term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6
 
602
              Address</citetitle></term>
 
603
              <listitem><para/></listitem>
 
604
            </varlistentry>
 
605
            <varlistentry>
 
606
            <term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast
 
607
            Addresses</citetitle></term>
 
608
            <listitem>
 
609
              <para>
 
610
                The clients use IPv6 link-local addresses, which are
 
611
                immediately usable since a link-local addresses is
 
612
                automatically assigned to a network interfaces when it
 
613
                is brought up.
 
614
              </para>
 
615
            </listitem>
 
616
            </varlistentry>
 
617
          </variablelist>
599
618
        </listitem>
600
619
      </varlistentry>
601
620
      <varlistentry>
602
621
        <term>
603
 
          <citation>RFC 4346: <citetitle>The Transport Layer Security
604
 
          (TLS) Protocol Version 1.1</citetitle></citation>
 
622
          RFC 4346: <citetitle>The Transport Layer Security (TLS)
 
623
          Protocol Version 1.1</citetitle>
605
624
        </term>
606
625
      <listitem>
607
626
        <para>
611
630
      </varlistentry>
612
631
      <varlistentry>
613
632
        <term>
614
 
          <citation>RFC 4880: <citetitle>OpenPGP Message
615
 
          Format</citetitle></citation>
 
633
          RFC 4880: <citetitle>OpenPGP Message Format</citetitle>
616
634
        </term>
617
635
      <listitem>
618
636
        <para>
622
640
      </varlistentry>
623
641
      <varlistentry>
624
642
        <term>
625
 
          <citation>RFC 5081: <citetitle>Using OpenPGP Keys for
626
 
          Transport Layer Security</citetitle></citation>
 
643
          RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer
 
644
          Security</citetitle>
627
645
        </term>
628
646
      <listitem>
629
647
        <para>
635
653
    </variablelist>
636
654
  </refsect1>
637
655
</refentry>
 
656
<!-- Local Variables: -->
 
657
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
 
658
<!-- time-stamp-end: "[\"']>" -->
 
659
<!-- time-stamp-format: "%:y-%02m-%02d" -->
 
660
<!-- End: -->