/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

Merge from trunk.  Bug fix for initramfs-tools-hook.

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">
6
 
<!ENTITY TIMESTAMP "2008-08-30">
 
5
<!ENTITY TIMESTAMP "2009-02-24">
 
6
<!ENTITY % common SYSTEM "common.ent">
 
7
%common;
7
8
]>
8
9
 
9
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
10
 
  <refentryinfo>
 
11
   <refentryinfo>
11
12
    <title>Mandos Manual</title>
12
13
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
14
    <productname>Mandos</productname>
14
 
    <productnumber>&VERSION;</productnumber>
 
15
    <productnumber>&version;</productnumber>
15
16
    <date>&TIMESTAMP;</date>
16
17
    <authorgroup>
17
18
      <author>
31
32
    </authorgroup>
32
33
    <copyright>
33
34
      <year>2008</year>
 
35
      <year>2009</year>
34
36
      <holder>Teddy Hogeborn</holder>
35
37
      <holder>Björn Påhlsson</holder>
36
38
    </copyright>
37
 
    <legalnotice>
38
 
      <para>
39
 
        This manual page is free software: you can redistribute it
40
 
        and/or modify it under the terms of the GNU General Public
41
 
        License as published by the Free Software Foundation,
42
 
        either version 3 of the License, or (at your option) any
43
 
        later version.
44
 
      </para>
45
 
 
46
 
      <para>
47
 
        This manual page is distributed in the hope that it will
48
 
        be useful, but WITHOUT ANY WARRANTY; without even the
49
 
        implied warranty of MERCHANTABILITY or FITNESS FOR A
50
 
        PARTICULAR PURPOSE.  See the GNU General Public License
51
 
        for more details.
52
 
      </para>
53
 
 
54
 
      <para>
55
 
        You should have received a copy of the GNU General Public
56
 
        License along with this program; If not, see
57
 
        <ulink url="http://www.gnu.org/licenses/"/>.
58
 
      </para>
59
 
    </legalnotice>
 
39
    <xi:include href="legalnotice.xml"/>
60
40
  </refentryinfo>
61
 
 
 
41
  
62
42
  <refmeta>
63
43
    <refentrytitle>&COMMANDNAME;</refentrytitle>
64
44
    <manvolnum>8</manvolnum>
70
50
      Gives encrypted passwords to authenticated Mandos clients
71
51
    </refpurpose>
72
52
  </refnamediv>
73
 
 
 
53
  
74
54
  <refsynopsisdiv>
75
55
    <cmdsynopsis>
76
56
      <command>&COMMANDNAME;</command>
105
85
      <replaceable>DIRECTORY</replaceable></option></arg>
106
86
      <sbr/>
107
87
      <arg><option>--debug</option></arg>
 
88
      <sbr/>
 
89
      <arg><option>--no-ipv6</option></arg>
108
90
    </cmdsynopsis>
109
91
    <cmdsynopsis>
110
92
      <command>&COMMANDNAME;</command>
111
93
      <group choice="req">
 
94
        <arg choice="plain"><option>--help</option></arg>
112
95
        <arg choice="plain"><option>-h</option></arg>
113
 
        <arg choice="plain"><option>--help</option></arg>
114
96
      </group>
115
97
    </cmdsynopsis>
116
98
    <cmdsynopsis>
122
104
      <arg choice="plain"><option>--check</option></arg>
123
105
    </cmdsynopsis>
124
106
  </refsynopsisdiv>
125
 
 
 
107
  
126
108
  <refsect1 id="description">
127
109
    <title>DESCRIPTION</title>
128
110
    <para>
137
119
      Any authenticated client is then given the stored pre-encrypted
138
120
      password for that specific client.
139
121
    </para>
140
 
 
141
122
  </refsect1>
142
123
  
143
124
  <refsect1 id="purpose">
144
125
    <title>PURPOSE</title>
145
 
 
146
126
    <para>
147
127
      The purpose of this is to enable <emphasis>remote and unattended
148
128
      rebooting</emphasis> of client host computer with an
149
129
      <emphasis>encrypted root file system</emphasis>.  See <xref
150
130
      linkend="overview"/> for details.
151
131
    </para>
152
 
 
153
132
  </refsect1>
154
133
  
155
134
  <refsect1 id="options">
156
135
    <title>OPTIONS</title>
157
 
 
158
136
    <variablelist>
159
137
      <varlistentry>
 
138
        <term><option>--help</option></term>
160
139
        <term><option>-h</option></term>
161
 
        <term><option>--help</option></term>
162
140
        <listitem>
163
141
          <para>
164
142
            Show a help message and exit
165
143
          </para>
166
144
        </listitem>
167
145
      </varlistentry>
168
 
 
 
146
      
169
147
      <varlistentry>
 
148
        <term><option>--interface</option>
 
149
        <replaceable>NAME</replaceable></term>
170
150
        <term><option>-i</option>
171
151
        <replaceable>NAME</replaceable></term>
172
 
        <term><option>--interface</option>
173
 
        <replaceable>NAME</replaceable></term>
174
152
        <listitem>
175
153
          <xi:include href="mandos-options.xml" xpointer="interface"/>
176
154
        </listitem>
177
155
      </varlistentry>
178
 
 
 
156
      
179
157
      <varlistentry>
180
 
        <term><literal>-a</literal>, <literal>--address <replaceable>
181
 
        ADDRESS</replaceable></literal></term>
 
158
        <term><option>--address
 
159
        <replaceable>ADDRESS</replaceable></option></term>
 
160
        <term><option>-a
 
161
        <replaceable>ADDRESS</replaceable></option></term>
182
162
        <listitem>
183
163
          <xi:include href="mandos-options.xml" xpointer="address"/>
184
164
        </listitem>
185
165
      </varlistentry>
186
 
 
 
166
      
187
167
      <varlistentry>
188
 
        <term><literal>-p</literal>, <literal>--port <replaceable>
189
 
        PORT</replaceable></literal></term>
 
168
        <term><option>--port
 
169
        <replaceable>PORT</replaceable></option></term>
 
170
        <term><option>-p
 
171
        <replaceable>PORT</replaceable></option></term>
190
172
        <listitem>
191
173
          <xi:include href="mandos-options.xml" xpointer="port"/>
192
174
        </listitem>
193
175
      </varlistentry>
194
 
 
 
176
      
195
177
      <varlistentry>
196
 
        <term><literal>--check</literal></term>
 
178
        <term><option>--check</option></term>
197
179
        <listitem>
198
180
          <para>
199
181
            Run the server’s self-tests.  This includes any unit
201
183
          </para>
202
184
        </listitem>
203
185
      </varlistentry>
204
 
 
 
186
      
205
187
      <varlistentry>
206
 
        <term><literal>--debug</literal></term>
 
188
        <term><option>--debug</option></term>
207
189
        <listitem>
208
190
          <xi:include href="mandos-options.xml" xpointer="debug"/>
209
191
        </listitem>
210
192
      </varlistentry>
211
 
 
 
193
      
212
194
      <varlistentry>
213
 
        <term><literal>--priority <replaceable>
214
 
        PRIORITY</replaceable></literal></term>
 
195
        <term><option>--priority <replaceable>
 
196
        PRIORITY</replaceable></option></term>
215
197
        <listitem>
216
198
          <xi:include href="mandos-options.xml" xpointer="priority"/>
217
199
        </listitem>
218
200
      </varlistentry>
219
 
 
 
201
      
220
202
      <varlistentry>
221
 
        <term><literal>--servicename <replaceable>NAME</replaceable>
222
 
        </literal></term>
 
203
        <term><option>--servicename
 
204
        <replaceable>NAME</replaceable></option></term>
223
205
        <listitem>
224
206
          <xi:include href="mandos-options.xml"
225
207
                      xpointer="servicename"/>
226
208
        </listitem>
227
209
      </varlistentry>
228
 
 
 
210
      
229
211
      <varlistentry>
230
 
        <term><literal>--configdir <replaceable>DIR</replaceable>
231
 
        </literal></term>
 
212
        <term><option>--configdir
 
213
        <replaceable>DIRECTORY</replaceable></option></term>
232
214
        <listitem>
233
215
          <para>
234
216
            Directory to search for configuration files.  Default is
240
222
          </para>
241
223
        </listitem>
242
224
      </varlistentry>
243
 
 
 
225
      
244
226
      <varlistentry>
245
 
        <term><literal>--version</literal></term>
 
227
        <term><option>--version</option></term>
246
228
        <listitem>
247
229
          <para>
248
230
            Prints the program version and exit.
249
231
          </para>
250
232
        </listitem>
251
233
      </varlistentry>
 
234
      
 
235
      <varlistentry>
 
236
        <term><option>--no-ipv6</option></term>
 
237
        <listitem>
 
238
          <xi:include href="mandos-options.xml" xpointer="ipv6"/>
 
239
        </listitem>
 
240
      </varlistentry>
252
241
    </variablelist>
253
242
  </refsect1>
254
 
 
 
243
  
255
244
  <refsect1 id="overview">
256
245
    <title>OVERVIEW</title>
257
246
    <xi:include href="overview.xml"/>
258
247
    <para>
259
248
      This program is the server part.  It is a normal server program
260
249
      and will run in a normal system environment, not in an initial
261
 
      RAM disk environment.
 
250
      <acronym>RAM</acronym> disk environment.
262
251
    </para>
263
252
  </refsect1>
264
 
 
 
253
  
265
254
  <refsect1 id="protocol">
266
255
    <title>NETWORK PROTOCOL</title>
267
256
    <para>
319
308
      </row>
320
309
    </tbody></tgroup></table>
321
310
  </refsect1>
322
 
 
 
311
  
323
312
  <refsect1 id="checking">
324
313
    <title>CHECKING</title>
325
314
    <para>
333
322
      <manvolnum>5</manvolnum></citerefentry>.
334
323
    </para>
335
324
  </refsect1>
336
 
 
 
325
  
337
326
  <refsect1 id="logging">
338
327
    <title>LOGGING</title>
339
328
    <para>
343
332
      and also show them on the console.
344
333
    </para>
345
334
  </refsect1>
346
 
 
 
335
  
347
336
  <refsect1 id="exit_status">
348
337
    <title>EXIT STATUS</title>
349
338
    <para>
351
340
      critical error is encountered.
352
341
    </para>
353
342
  </refsect1>
354
 
 
 
343
  
355
344
  <refsect1 id="environment">
356
345
    <title>ENVIRONMENT</title>
357
346
    <variablelist>
371
360
      </varlistentry>
372
361
    </variablelist>
373
362
  </refsect1>
374
 
 
375
 
  <refsect1 id="file">
 
363
  
 
364
  <refsect1 id="files">
376
365
    <title>FILES</title>
377
366
    <para>
378
367
      Use the <option>--configdir</option> option to change where
401
390
        </listitem>
402
391
      </varlistentry>
403
392
      <varlistentry>
404
 
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
 
393
        <term><filename>/var/run/mandos.pid</filename></term>
405
394
        <listitem>
406
395
          <para>
407
396
            The file containing the process id of
442
431
      Currently, if a client is declared <quote>invalid</quote> due to
443
432
      having timed out, the server does not record this fact onto
444
433
      permanent storage.  This has some security implications, see
445
 
      <xref linkend="CLIENTS"/>.
 
434
      <xref linkend="clients"/>.
446
435
    </para>
447
436
    <para>
448
437
      There is currently no way of querying the server of the current
456
445
      Debug mode is conflated with running in the foreground.
457
446
    </para>
458
447
    <para>
459
 
      The console log messages does not show a timestamp.
 
448
      The console log messages do not show a time stamp.
 
449
    </para>
 
450
    <para>
 
451
      This server does not check the expire time of clients’ OpenPGP
 
452
      keys.
460
453
    </para>
461
454
  </refsect1>
462
455
  
497
490
      </para>
498
491
    </informalexample>
499
492
  </refsect1>
500
 
 
 
493
  
501
494
  <refsect1 id="security">
502
495
    <title>SECURITY</title>
503
 
    <refsect2 id="SERVER">
 
496
    <refsect2 id="server">
504
497
      <title>SERVER</title>
505
498
      <para>
506
499
        Running this <command>&COMMANDNAME;</command> server program
507
500
        should not in itself present any security risk to the host
508
 
        computer running it.  The program does not need any special
509
 
        privileges to run, and is designed to run as a non-root user.
 
501
        computer running it.  The program switches to a non-root user
 
502
        soon after startup.
510
503
      </para>
511
504
    </refsect2>
512
 
    <refsect2 id="CLIENTS">
 
505
    <refsect2 id="clients">
513
506
      <title>CLIENTS</title>
514
507
      <para>
515
508
        The server only gives out its stored data to clients which
522
515
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
523
516
        <manvolnum>5</manvolnum></citerefentry>)
524
517
        <emphasis>must</emphasis> be made non-readable by anyone
525
 
        except the user running the server.
 
518
        except the user starting the server (usually root).
526
519
      </para>
527
520
      <para>
528
521
        As detailed in <xref linkend="checking"/>, the status of all
539
532
        restarting servers if it is suspected that a client has, in
540
533
        fact, been compromised by parties who may now be running a
541
534
        fake Mandos client with the keys from the non-encrypted
542
 
        initial RAM image of the client host.  What should be done in
543
 
        that case (if restarting the server program really is
544
 
        necessary) is to stop the server program, edit the
 
535
        initial <acronym>RAM</acronym> image of the client host.  What
 
536
        should be done in that case (if restarting the server program
 
537
        really is necessary) is to stop the server program, edit the
545
538
        configuration file to omit any suspect clients, and restart
546
539
        the server program.
547
540
      </para>
548
541
      <para>
549
542
        For more details on client-side security, see
550
 
        <citerefentry><refentrytitle>password-request</refentrytitle>
 
543
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
551
544
        <manvolnum>8mandos</manvolnum></citerefentry>.
552
545
      </para>
553
546
    </refsect2>
554
547
  </refsect1>
555
 
 
 
548
  
556
549
  <refsect1 id="see_also">
557
550
    <title>SEE ALSO</title>
558
551
    <para>
561
554
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
562
555
        <refentrytitle>mandos.conf</refentrytitle>
563
556
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
564
 
        <refentrytitle>password-request</refentrytitle>
 
557
        <refentrytitle>mandos-client</refentrytitle>
565
558
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
566
559
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
567
560
      </citerefentry>