/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

Tags: version-1.0.5-1
* Makefile (version): Changed to "1.0.5".
* NEWS (1.0.5): New entry.
* debian/changelog (1.0.5-1): - '' -

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