/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-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">
6
 
<!ENTITY TIMESTAMP "2008-08-29">
 
5
<!ENTITY TIMESTAMP "2008-10-03">
 
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>
34
35
      <holder>Teddy Hogeborn</holder>
35
36
      <holder>Björn Påhlsson</holder>
36
37
    </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>
 
38
    <xi:include href="legalnotice.xml"/>
60
39
  </refentryinfo>
61
 
 
 
40
  
62
41
  <refmeta>
63
42
    <refentrytitle>&COMMANDNAME;</refentrytitle>
64
43
    <manvolnum>8</manvolnum>
67
46
  <refnamediv>
68
47
    <refname><command>&COMMANDNAME;</command></refname>
69
48
    <refpurpose>
70
 
      Sends encrypted passwords to authenticated Mandos clients
 
49
      Gives encrypted passwords to authenticated Mandos clients
71
50
    </refpurpose>
72
51
  </refnamediv>
73
 
 
 
52
  
74
53
  <refsynopsisdiv>
75
54
    <cmdsynopsis>
76
55
      <command>&COMMANDNAME;</command>
77
 
      <arg>--interface<arg choice="plain">NAME</arg></arg>
78
 
      <arg>--address<arg choice="plain">ADDRESS</arg></arg>
79
 
      <arg>--port<arg choice="plain">PORT</arg></arg>
80
 
      <arg>--priority<arg choice="plain">PRIORITY</arg></arg>
81
 
      <arg>--servicename<arg choice="plain">NAME</arg></arg>
82
 
      <arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>
83
 
      <arg>--debug</arg>
84
 
    </cmdsynopsis>
85
 
    <cmdsynopsis>
86
 
      <command>&COMMANDNAME;</command>
87
 
      <arg>-i<arg choice="plain">NAME</arg></arg>
88
 
      <arg>-a<arg choice="plain">ADDRESS</arg></arg>
89
 
      <arg>-p<arg choice="plain">PORT</arg></arg>
90
 
      <arg>--priority<arg choice="plain">PRIORITY</arg></arg>
91
 
      <arg>--servicename<arg choice="plain">NAME</arg></arg>
92
 
      <arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>
93
 
      <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>
94
87
    </cmdsynopsis>
95
88
    <cmdsynopsis>
96
89
      <command>&COMMANDNAME;</command>
97
90
      <group choice="req">
98
 
        <arg choice="plain">-h</arg>
99
 
        <arg choice="plain">--help</arg>
 
91
        <arg choice="plain"><option>--help</option></arg>
 
92
        <arg choice="plain"><option>-h</option></arg>
100
93
      </group>
101
94
    </cmdsynopsis>
102
95
    <cmdsynopsis>
103
96
      <command>&COMMANDNAME;</command>
104
 
      <arg choice="plain">--version</arg>
 
97
      <arg choice="plain"><option>--version</option></arg>
105
98
    </cmdsynopsis>
106
99
    <cmdsynopsis>
107
100
      <command>&COMMANDNAME;</command>
108
 
      <arg choice="plain">--check</arg>
 
101
      <arg choice="plain"><option>--check</option></arg>
109
102
    </cmdsynopsis>
110
103
  </refsynopsisdiv>
111
 
 
 
104
  
112
105
  <refsect1 id="description">
113
106
    <title>DESCRIPTION</title>
114
107
    <para>
123
116
      Any authenticated client is then given the stored pre-encrypted
124
117
      password for that specific client.
125
118
    </para>
126
 
 
127
119
  </refsect1>
128
120
  
129
121
  <refsect1 id="purpose">
130
122
    <title>PURPOSE</title>
131
 
 
132
123
    <para>
133
124
      The purpose of this is to enable <emphasis>remote and unattended
134
125
      rebooting</emphasis> of client host computer with an
135
126
      <emphasis>encrypted root file system</emphasis>.  See <xref
136
127
      linkend="overview"/> for details.
137
128
    </para>
138
 
 
139
129
  </refsect1>
140
130
  
141
131
  <refsect1 id="options">
142
132
    <title>OPTIONS</title>
143
 
 
144
133
    <variablelist>
145
134
      <varlistentry>
 
135
        <term><option>--help</option></term>
146
136
        <term><option>-h</option></term>
147
 
        <term><option>--help</option></term>
148
137
        <listitem>
149
138
          <para>
150
139
            Show a help message and exit
151
140
          </para>
152
141
        </listitem>
153
142
      </varlistentry>
154
 
 
 
143
      
155
144
      <varlistentry>
 
145
        <term><option>--interface</option>
 
146
        <replaceable>NAME</replaceable></term>
156
147
        <term><option>-i</option>
157
148
        <replaceable>NAME</replaceable></term>
158
 
        <term><option>--interface</option>
159
 
        <replaceable>NAME</replaceable></term>
160
149
        <listitem>
161
150
          <xi:include href="mandos-options.xml" xpointer="interface"/>
162
151
        </listitem>
163
152
      </varlistentry>
164
 
 
 
153
      
165
154
      <varlistentry>
166
 
        <term><literal>-a</literal>, <literal>--address <replaceable>
167
 
        ADDRESS</replaceable></literal></term>
 
155
        <term><option>--address
 
156
        <replaceable>ADDRESS</replaceable></option></term>
 
157
        <term><option>-a
 
158
        <replaceable>ADDRESS</replaceable></option></term>
168
159
        <listitem>
169
160
          <xi:include href="mandos-options.xml" xpointer="address"/>
170
161
        </listitem>
171
162
      </varlistentry>
172
 
 
 
163
      
173
164
      <varlistentry>
174
 
        <term><literal>-p</literal>, <literal>--port <replaceable>
175
 
        PORT</replaceable></literal></term>
 
165
        <term><option>--port
 
166
        <replaceable>PORT</replaceable></option></term>
 
167
        <term><option>-p
 
168
        <replaceable>PORT</replaceable></option></term>
176
169
        <listitem>
177
170
          <xi:include href="mandos-options.xml" xpointer="port"/>
178
171
        </listitem>
179
172
      </varlistentry>
180
 
 
 
173
      
181
174
      <varlistentry>
182
 
        <term><literal>--check</literal></term>
 
175
        <term><option>--check</option></term>
183
176
        <listitem>
184
177
          <para>
185
178
            Run the server’s self-tests.  This includes any unit
187
180
          </para>
188
181
        </listitem>
189
182
      </varlistentry>
190
 
 
 
183
      
191
184
      <varlistentry>
192
 
        <term><literal>--debug</literal></term>
 
185
        <term><option>--debug</option></term>
193
186
        <listitem>
194
187
          <xi:include href="mandos-options.xml" xpointer="debug"/>
195
188
        </listitem>
196
189
      </varlistentry>
197
 
 
 
190
      
198
191
      <varlistentry>
199
 
        <term><literal>--priority <replaceable>
200
 
        PRIORITY</replaceable></literal></term>
 
192
        <term><option>--priority <replaceable>
 
193
        PRIORITY</replaceable></option></term>
201
194
        <listitem>
202
195
          <xi:include href="mandos-options.xml" xpointer="priority"/>
203
196
        </listitem>
204
197
      </varlistentry>
205
 
 
 
198
      
206
199
      <varlistentry>
207
 
        <term><literal>--servicename <replaceable>NAME</replaceable>
208
 
        </literal></term>
 
200
        <term><option>--servicename
 
201
        <replaceable>NAME</replaceable></option></term>
209
202
        <listitem>
210
203
          <xi:include href="mandos-options.xml"
211
204
                      xpointer="servicename"/>
212
205
        </listitem>
213
206
      </varlistentry>
214
 
 
 
207
      
215
208
      <varlistentry>
216
 
        <term><literal>--configdir <replaceable>DIR</replaceable>
217
 
        </literal></term>
 
209
        <term><option>--configdir
 
210
        <replaceable>DIRECTORY</replaceable></option></term>
218
211
        <listitem>
219
212
          <para>
220
213
            Directory to search for configuration files.  Default is
226
219
          </para>
227
220
        </listitem>
228
221
      </varlistentry>
229
 
 
 
222
      
230
223
      <varlistentry>
231
 
        <term><literal>--version</literal></term>
 
224
        <term><option>--version</option></term>
232
225
        <listitem>
233
226
          <para>
234
227
            Prints the program version and exit.
237
230
      </varlistentry>
238
231
    </variablelist>
239
232
  </refsect1>
240
 
 
 
233
  
241
234
  <refsect1 id="overview">
242
235
    <title>OVERVIEW</title>
243
236
    <xi:include href="overview.xml"/>
244
237
    <para>
245
238
      This program is the server part.  It is a normal server program
246
239
      and will run in a normal system environment, not in an initial
247
 
      RAM disk environment.
 
240
      <acronym>RAM</acronym> disk environment.
248
241
    </para>
249
242
  </refsect1>
250
 
 
 
243
  
251
244
  <refsect1 id="protocol">
252
245
    <title>NETWORK PROTOCOL</title>
253
246
    <para>
305
298
      </row>
306
299
    </tbody></tgroup></table>
307
300
  </refsect1>
308
 
 
 
301
  
309
302
  <refsect1 id="checking">
310
303
    <title>CHECKING</title>
311
304
    <para>
319
312
      <manvolnum>5</manvolnum></citerefentry>.
320
313
    </para>
321
314
  </refsect1>
322
 
 
 
315
  
323
316
  <refsect1 id="logging">
324
317
    <title>LOGGING</title>
325
318
    <para>
329
322
      and also show them on the console.
330
323
    </para>
331
324
  </refsect1>
332
 
 
 
325
  
333
326
  <refsect1 id="exit_status">
334
327
    <title>EXIT STATUS</title>
335
328
    <para>
337
330
      critical error is encountered.
338
331
    </para>
339
332
  </refsect1>
340
 
 
 
333
  
341
334
  <refsect1 id="environment">
342
335
    <title>ENVIRONMENT</title>
343
336
    <variablelist>
344
337
      <varlistentry>
345
 
        <term><varname>PATH</varname></term>
 
338
        <term><envar>PATH</envar></term>
346
339
        <listitem>
347
340
          <para>
348
341
            To start the configured checker (see <xref
357
350
      </varlistentry>
358
351
    </variablelist>
359
352
  </refsect1>
360
 
 
361
 
  <refsect1 id="file">
 
353
  
 
354
  <refsect1 id="files">
362
355
    <title>FILES</title>
363
356
    <para>
364
357
      Use the <option>--configdir</option> option to change where
387
380
        </listitem>
388
381
      </varlistentry>
389
382
      <varlistentry>
390
 
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
 
383
        <term><filename>/var/run/mandos.pid</filename></term>
391
384
        <listitem>
392
385
          <para>
393
386
            The file containing the process id of
428
421
      Currently, if a client is declared <quote>invalid</quote> due to
429
422
      having timed out, the server does not record this fact onto
430
423
      permanent storage.  This has some security implications, see
431
 
      <xref linkend="CLIENTS"/>.
 
424
      <xref linkend="clients"/>.
432
425
    </para>
433
426
    <para>
434
427
      There is currently no way of querying the server of the current
442
435
      Debug mode is conflated with running in the foreground.
443
436
    </para>
444
437
    <para>
445
 
      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.
446
443
    </para>
447
444
  </refsect1>
448
445
  
483
480
      </para>
484
481
    </informalexample>
485
482
  </refsect1>
486
 
 
 
483
  
487
484
  <refsect1 id="security">
488
485
    <title>SECURITY</title>
489
 
    <refsect2 id="SERVER">
 
486
    <refsect2 id="server">
490
487
      <title>SERVER</title>
491
488
      <para>
492
489
        Running this <command>&COMMANDNAME;</command> server program
493
490
        should not in itself present any security risk to the host
494
 
        computer running it.  The program does not need any special
495
 
        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.
496
493
      </para>
497
494
    </refsect2>
498
 
    <refsect2 id="CLIENTS">
 
495
    <refsect2 id="clients">
499
496
      <title>CLIENTS</title>
500
497
      <para>
501
498
        The server only gives out its stored data to clients which
508
505
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
509
506
        <manvolnum>5</manvolnum></citerefentry>)
510
507
        <emphasis>must</emphasis> be made non-readable by anyone
511
 
        except the user running the server.
 
508
        except the user starting the server (usually root).
512
509
      </para>
513
510
      <para>
514
511
        As detailed in <xref linkend="checking"/>, the status of all
525
522
        restarting servers if it is suspected that a client has, in
526
523
        fact, been compromised by parties who may now be running a
527
524
        fake Mandos client with the keys from the non-encrypted
528
 
        initial RAM image of the client host.  What should be done in
529
 
        that case (if restarting the server program really is
530
 
        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
531
528
        configuration file to omit any suspect clients, and restart
532
529
        the server program.
533
530
      </para>
534
531
      <para>
535
532
        For more details on client-side security, see
536
 
        <citerefentry><refentrytitle>password-request</refentrytitle>
 
533
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
537
534
        <manvolnum>8mandos</manvolnum></citerefentry>.
538
535
      </para>
539
536
    </refsect2>
540
537
  </refsect1>
541
 
 
 
538
  
542
539
  <refsect1 id="see_also">
543
540
    <title>SEE ALSO</title>
544
541
    <para>
547
544
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
548
545
        <refentrytitle>mandos.conf</refentrytitle>
549
546
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
550
 
        <refentrytitle>password-request</refentrytitle>
 
547
        <refentrytitle>mandos-client</refentrytitle>
551
548
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
552
549
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
553
550
      </citerefentry>