/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>
146
 
        <term><literal>-h</literal>, <literal>--help</literal></term>
 
135
        <term><option>--help</option></term>
 
136
        <term><option>-h</option></term>
147
137
        <listitem>
148
138
          <para>
149
139
            Show a help message and exit
150
140
          </para>
151
141
        </listitem>
152
142
      </varlistentry>
153
 
 
 
143
      
154
144
      <varlistentry>
155
 
        <term><literal>-i</literal>, <literal>--interface <replaceable
156
 
        >NAME</replaceable></literal></term>
 
145
        <term><option>--interface</option>
 
146
        <replaceable>NAME</replaceable></term>
 
147
        <term><option>-i</option>
 
148
        <replaceable>NAME</replaceable></term>
157
149
        <listitem>
158
150
          <xi:include href="mandos-options.xml" xpointer="interface"/>
159
151
        </listitem>
160
152
      </varlistentry>
161
 
 
 
153
      
162
154
      <varlistentry>
163
 
        <term><literal>-a</literal>, <literal>--address <replaceable>
164
 
        ADDRESS</replaceable></literal></term>
 
155
        <term><option>--address
 
156
        <replaceable>ADDRESS</replaceable></option></term>
 
157
        <term><option>-a
 
158
        <replaceable>ADDRESS</replaceable></option></term>
165
159
        <listitem>
166
160
          <xi:include href="mandos-options.xml" xpointer="address"/>
167
161
        </listitem>
168
162
      </varlistentry>
169
 
 
 
163
      
170
164
      <varlistentry>
171
 
        <term><literal>-p</literal>, <literal>--port <replaceable>
172
 
        PORT</replaceable></literal></term>
 
165
        <term><option>--port
 
166
        <replaceable>PORT</replaceable></option></term>
 
167
        <term><option>-p
 
168
        <replaceable>PORT</replaceable></option></term>
173
169
        <listitem>
174
170
          <xi:include href="mandos-options.xml" xpointer="port"/>
175
171
        </listitem>
176
172
      </varlistentry>
177
 
 
 
173
      
178
174
      <varlistentry>
179
 
        <term><literal>--check</literal></term>
 
175
        <term><option>--check</option></term>
180
176
        <listitem>
181
177
          <para>
182
178
            Run the server’s self-tests.  This includes any unit
184
180
          </para>
185
181
        </listitem>
186
182
      </varlistentry>
187
 
 
 
183
      
188
184
      <varlistentry>
189
 
        <term><literal>--debug</literal></term>
 
185
        <term><option>--debug</option></term>
190
186
        <listitem>
191
187
          <xi:include href="mandos-options.xml" xpointer="debug"/>
192
188
        </listitem>
193
189
      </varlistentry>
194
 
 
 
190
      
195
191
      <varlistentry>
196
 
        <term><literal>--priority <replaceable>
197
 
        PRIORITY</replaceable></literal></term>
 
192
        <term><option>--priority <replaceable>
 
193
        PRIORITY</replaceable></option></term>
198
194
        <listitem>
199
195
          <xi:include href="mandos-options.xml" xpointer="priority"/>
200
196
        </listitem>
201
197
      </varlistentry>
202
 
 
 
198
      
203
199
      <varlistentry>
204
 
        <term><literal>--servicename <replaceable>NAME</replaceable>
205
 
        </literal></term>
 
200
        <term><option>--servicename
 
201
        <replaceable>NAME</replaceable></option></term>
206
202
        <listitem>
207
203
          <xi:include href="mandos-options.xml"
208
204
                      xpointer="servicename"/>
209
205
        </listitem>
210
206
      </varlistentry>
211
 
 
 
207
      
212
208
      <varlistentry>
213
 
        <term><literal>--configdir <replaceable>DIR</replaceable>
214
 
        </literal></term>
 
209
        <term><option>--configdir
 
210
        <replaceable>DIRECTORY</replaceable></option></term>
215
211
        <listitem>
216
212
          <para>
217
213
            Directory to search for configuration files.  Default is
223
219
          </para>
224
220
        </listitem>
225
221
      </varlistentry>
226
 
 
 
222
      
227
223
      <varlistentry>
228
 
        <term><literal>--version</literal></term>
 
224
        <term><option>--version</option></term>
229
225
        <listitem>
230
226
          <para>
231
227
            Prints the program version and exit.
234
230
      </varlistentry>
235
231
    </variablelist>
236
232
  </refsect1>
237
 
 
 
233
  
238
234
  <refsect1 id="overview">
239
235
    <title>OVERVIEW</title>
240
236
    <xi:include href="overview.xml"/>
241
237
    <para>
242
238
      This program is the server part.  It is a normal server program
243
239
      and will run in a normal system environment, not in an initial
244
 
      RAM disk environment.
 
240
      <acronym>RAM</acronym> disk environment.
245
241
    </para>
246
242
  </refsect1>
247
 
 
 
243
  
248
244
  <refsect1 id="protocol">
249
245
    <title>NETWORK PROTOCOL</title>
250
246
    <para>
302
298
      </row>
303
299
    </tbody></tgroup></table>
304
300
  </refsect1>
305
 
 
 
301
  
306
302
  <refsect1 id="checking">
307
303
    <title>CHECKING</title>
308
304
    <para>
316
312
      <manvolnum>5</manvolnum></citerefentry>.
317
313
    </para>
318
314
  </refsect1>
319
 
 
 
315
  
320
316
  <refsect1 id="logging">
321
317
    <title>LOGGING</title>
322
318
    <para>
326
322
      and also show them on the console.
327
323
    </para>
328
324
  </refsect1>
329
 
 
 
325
  
330
326
  <refsect1 id="exit_status">
331
327
    <title>EXIT STATUS</title>
332
328
    <para>
334
330
      critical error is encountered.
335
331
    </para>
336
332
  </refsect1>
337
 
 
 
333
  
338
334
  <refsect1 id="environment">
339
335
    <title>ENVIRONMENT</title>
340
336
    <variablelist>
341
337
      <varlistentry>
342
 
        <term><varname>PATH</varname></term>
 
338
        <term><envar>PATH</envar></term>
343
339
        <listitem>
344
340
          <para>
345
341
            To start the configured checker (see <xref
354
350
      </varlistentry>
355
351
    </variablelist>
356
352
  </refsect1>
357
 
 
358
 
  <refsect1 id="file">
 
353
  
 
354
  <refsect1 id="files">
359
355
    <title>FILES</title>
360
356
    <para>
361
357
      Use the <option>--configdir</option> option to change where
384
380
        </listitem>
385
381
      </varlistentry>
386
382
      <varlistentry>
387
 
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
 
383
        <term><filename>/var/run/mandos.pid</filename></term>
388
384
        <listitem>
389
385
          <para>
390
386
            The file containing the process id of
425
421
      Currently, if a client is declared <quote>invalid</quote> due to
426
422
      having timed out, the server does not record this fact onto
427
423
      permanent storage.  This has some security implications, see
428
 
      <xref linkend="CLIENTS"/>.
 
424
      <xref linkend="clients"/>.
429
425
    </para>
430
426
    <para>
431
427
      There is currently no way of querying the server of the current
439
435
      Debug mode is conflated with running in the foreground.
440
436
    </para>
441
437
    <para>
442
 
      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.
443
443
    </para>
444
444
  </refsect1>
445
445
  
480
480
      </para>
481
481
    </informalexample>
482
482
  </refsect1>
483
 
 
 
483
  
484
484
  <refsect1 id="security">
485
485
    <title>SECURITY</title>
486
 
    <refsect2 id="SERVER">
 
486
    <refsect2 id="server">
487
487
      <title>SERVER</title>
488
488
      <para>
489
489
        Running this <command>&COMMANDNAME;</command> server program
490
490
        should not in itself present any security risk to the host
491
 
        computer running it.  The program does not need any special
492
 
        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.
493
493
      </para>
494
494
    </refsect2>
495
 
    <refsect2 id="CLIENTS">
 
495
    <refsect2 id="clients">
496
496
      <title>CLIENTS</title>
497
497
      <para>
498
498
        The server only gives out its stored data to clients which
505
505
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
506
506
        <manvolnum>5</manvolnum></citerefentry>)
507
507
        <emphasis>must</emphasis> be made non-readable by anyone
508
 
        except the user running the server.
 
508
        except the user starting the server (usually root).
509
509
      </para>
510
510
      <para>
511
511
        As detailed in <xref linkend="checking"/>, the status of all
522
522
        restarting servers if it is suspected that a client has, in
523
523
        fact, been compromised by parties who may now be running a
524
524
        fake Mandos client with the keys from the non-encrypted
525
 
        initial RAM image of the client host.  What should be done in
526
 
        that case (if restarting the server program really is
527
 
        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
528
528
        configuration file to omit any suspect clients, and restart
529
529
        the server program.
530
530
      </para>
531
531
      <para>
532
532
        For more details on client-side security, see
533
 
        <citerefentry><refentrytitle>password-request</refentrytitle>
 
533
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
534
534
        <manvolnum>8mandos</manvolnum></citerefentry>.
535
535
      </para>
536
536
    </refsect2>
537
537
  </refsect1>
538
 
 
 
538
  
539
539
  <refsect1 id="see_also">
540
540
    <title>SEE ALSO</title>
541
541
    <para>
544
544
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
545
545
        <refentrytitle>mandos.conf</refentrytitle>
546
546
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
547
 
        <refentrytitle>password-request</refentrytitle>
 
547
        <refentrytitle>mandos-client</refentrytitle>
548
548
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
549
549
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
550
550
      </citerefentry>