/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.12-1
* Makefile (version): Changed to "1.0.12".
* NEWS (Version 1.0.12): New entry.
* debian/changelog (1.0.12-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">
6
 
<!ENTITY TIMESTAMP "2008-08-30">
 
5
<!ENTITY TIMESTAMP "2009-09-17">
 
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>
326
315
      The server will, by default, continually check that the clients
327
316
      are still up.  If a client has not been confirmed as being up
328
317
      for some time, the client is assumed to be compromised and is no
329
 
      longer eligible to receive the encrypted password.  The timeout,
 
318
      longer eligible to receive the encrypted password.  (Manual
 
319
      intervention is required to re-enable a client.)  The timeout,
330
320
      checker program, and interval between checks can be configured
331
321
      both globally and per client; see <citerefentry>
332
322
      <refentrytitle>mandos-clients.conf</refentrytitle>
333
 
      <manvolnum>5</manvolnum></citerefentry>.
 
323
      <manvolnum>5</manvolnum></citerefentry>.  A client successfully
 
324
      receiving its password will also be treated as a successful
 
325
      checker run.
334
326
    </para>
335
327
  </refsect1>
336
 
 
 
328
  
337
329
  <refsect1 id="logging">
338
330
    <title>LOGGING</title>
339
331
    <para>
343
335
      and also show them on the console.
344
336
    </para>
345
337
  </refsect1>
346
 
 
 
338
  
347
339
  <refsect1 id="exit_status">
348
340
    <title>EXIT STATUS</title>
349
341
    <para>
351
343
      critical error is encountered.
352
344
    </para>
353
345
  </refsect1>
354
 
 
 
346
  
355
347
  <refsect1 id="environment">
356
348
    <title>ENVIRONMENT</title>
357
349
    <variablelist>
371
363
      </varlistentry>
372
364
    </variablelist>
373
365
  </refsect1>
374
 
 
375
 
  <refsect1 id="file">
 
366
  
 
367
  <refsect1 id="files">
376
368
    <title>FILES</title>
377
369
    <para>
378
370
      Use the <option>--configdir</option> option to change where
401
393
        </listitem>
402
394
      </varlistentry>
403
395
      <varlistentry>
404
 
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
 
396
        <term><filename>/var/run/mandos.pid</filename></term>
405
397
        <listitem>
406
398
          <para>
407
399
            The file containing the process id of
442
434
      Currently, if a client is declared <quote>invalid</quote> due to
443
435
      having timed out, the server does not record this fact onto
444
436
      permanent storage.  This has some security implications, see
445
 
      <xref linkend="CLIENTS"/>.
 
437
      <xref linkend="clients"/>.
446
438
    </para>
447
439
    <para>
448
440
      There is currently no way of querying the server of the current
456
448
      Debug mode is conflated with running in the foreground.
457
449
    </para>
458
450
    <para>
459
 
      The console log messages does not show a timestamp.
 
451
      The console log messages do not show a time stamp.
 
452
    </para>
 
453
    <para>
 
454
      This server does not check the expire time of clients’ OpenPGP
 
455
      keys.
460
456
    </para>
461
457
  </refsect1>
462
458
  
497
493
      </para>
498
494
    </informalexample>
499
495
  </refsect1>
500
 
 
 
496
  
501
497
  <refsect1 id="security">
502
498
    <title>SECURITY</title>
503
 
    <refsect2 id="SERVER">
 
499
    <refsect2 id="server">
504
500
      <title>SERVER</title>
505
501
      <para>
506
502
        Running this <command>&COMMANDNAME;</command> server program
507
503
        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.
 
504
        computer running it.  The program switches to a non-root user
 
505
        soon after startup.
510
506
      </para>
511
507
    </refsect2>
512
 
    <refsect2 id="CLIENTS">
 
508
    <refsect2 id="clients">
513
509
      <title>CLIENTS</title>
514
510
      <para>
515
511
        The server only gives out its stored data to clients which
522
518
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
523
519
        <manvolnum>5</manvolnum></citerefentry>)
524
520
        <emphasis>must</emphasis> be made non-readable by anyone
525
 
        except the user running the server.
 
521
        except the user starting the server (usually root).
526
522
      </para>
527
523
      <para>
528
524
        As detailed in <xref linkend="checking"/>, the status of all
539
535
        restarting servers if it is suspected that a client has, in
540
536
        fact, been compromised by parties who may now be running a
541
537
        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
 
538
        initial <acronym>RAM</acronym> image of the client host.  What
 
539
        should be done in that case (if restarting the server program
 
540
        really is necessary) is to stop the server program, edit the
545
541
        configuration file to omit any suspect clients, and restart
546
542
        the server program.
547
543
      </para>
548
544
      <para>
549
545
        For more details on client-side security, see
550
 
        <citerefentry><refentrytitle>password-request</refentrytitle>
 
546
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
551
547
        <manvolnum>8mandos</manvolnum></citerefentry>.
552
548
      </para>
553
549
    </refsect2>
554
550
  </refsect1>
555
 
 
 
551
  
556
552
  <refsect1 id="see_also">
557
553
    <title>SEE ALSO</title>
558
554
    <para>
561
557
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
562
558
        <refentrytitle>mandos.conf</refentrytitle>
563
559
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
564
 
        <refentrytitle>password-request</refentrytitle>
 
560
        <refentrytitle>mandos-client</refentrytitle>
565
561
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
566
562
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
567
563
      </citerefentry>