/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.  Lots of bug fixes, including Debian bug #546928.

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-31">
 
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>
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>
160
138
        <term><option>--help</option></term>
212
190
          <xi:include href="mandos-options.xml" xpointer="debug"/>
213
191
        </listitem>
214
192
      </varlistentry>
215
 
 
 
193
      
216
194
      <varlistentry>
217
195
        <term><option>--priority <replaceable>
218
196
        PRIORITY</replaceable></option></term>
220
198
          <xi:include href="mandos-options.xml" xpointer="priority"/>
221
199
        </listitem>
222
200
      </varlistentry>
223
 
 
 
201
      
224
202
      <varlistentry>
225
203
        <term><option>--servicename
226
204
        <replaceable>NAME</replaceable></option></term>
229
207
                      xpointer="servicename"/>
230
208
        </listitem>
231
209
      </varlistentry>
232
 
 
 
210
      
233
211
      <varlistentry>
234
212
        <term><option>--configdir
235
213
        <replaceable>DIRECTORY</replaceable></option></term>
244
222
          </para>
245
223
        </listitem>
246
224
      </varlistentry>
247
 
 
 
225
      
248
226
      <varlistentry>
249
227
        <term><option>--version</option></term>
250
228
        <listitem>
253
231
          </para>
254
232
        </listitem>
255
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>
256
241
    </variablelist>
257
242
  </refsect1>
258
 
 
 
243
  
259
244
  <refsect1 id="overview">
260
245
    <title>OVERVIEW</title>
261
246
    <xi:include href="overview.xml"/>
262
247
    <para>
263
248
      This program is the server part.  It is a normal server program
264
249
      and will run in a normal system environment, not in an initial
265
 
      RAM disk environment.
 
250
      <acronym>RAM</acronym> disk environment.
266
251
    </para>
267
252
  </refsect1>
268
 
 
 
253
  
269
254
  <refsect1 id="protocol">
270
255
    <title>NETWORK PROTOCOL</title>
271
256
    <para>
323
308
      </row>
324
309
    </tbody></tgroup></table>
325
310
  </refsect1>
326
 
 
 
311
  
327
312
  <refsect1 id="checking">
328
313
    <title>CHECKING</title>
329
314
    <para>
330
315
      The server will, by default, continually check that the clients
331
316
      are still up.  If a client has not been confirmed as being up
332
317
      for some time, the client is assumed to be compromised and is no
333
 
      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,
334
320
      checker program, and interval between checks can be configured
335
321
      both globally and per client; see <citerefentry>
336
322
      <refentrytitle>mandos-clients.conf</refentrytitle>
337
 
      <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.
338
326
    </para>
339
327
  </refsect1>
340
 
 
 
328
  
341
329
  <refsect1 id="logging">
342
330
    <title>LOGGING</title>
343
331
    <para>
347
335
      and also show them on the console.
348
336
    </para>
349
337
  </refsect1>
350
 
 
 
338
  
351
339
  <refsect1 id="exit_status">
352
340
    <title>EXIT STATUS</title>
353
341
    <para>
355
343
      critical error is encountered.
356
344
    </para>
357
345
  </refsect1>
358
 
 
 
346
  
359
347
  <refsect1 id="environment">
360
348
    <title>ENVIRONMENT</title>
361
349
    <variablelist>
375
363
      </varlistentry>
376
364
    </variablelist>
377
365
  </refsect1>
378
 
 
379
 
  <refsect1 id="file">
 
366
  
 
367
  <refsect1 id="files">
380
368
    <title>FILES</title>
381
369
    <para>
382
370
      Use the <option>--configdir</option> option to change where
405
393
        </listitem>
406
394
      </varlistentry>
407
395
      <varlistentry>
408
 
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
 
396
        <term><filename>/var/run/mandos.pid</filename></term>
409
397
        <listitem>
410
398
          <para>
411
399
            The file containing the process id of
446
434
      Currently, if a client is declared <quote>invalid</quote> due to
447
435
      having timed out, the server does not record this fact onto
448
436
      permanent storage.  This has some security implications, see
449
 
      <xref linkend="CLIENTS"/>.
 
437
      <xref linkend="clients"/>.
450
438
    </para>
451
439
    <para>
452
440
      There is currently no way of querying the server of the current
460
448
      Debug mode is conflated with running in the foreground.
461
449
    </para>
462
450
    <para>
463
 
      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.
464
456
    </para>
465
457
  </refsect1>
466
458
  
501
493
      </para>
502
494
    </informalexample>
503
495
  </refsect1>
504
 
 
 
496
  
505
497
  <refsect1 id="security">
506
498
    <title>SECURITY</title>
507
 
    <refsect2 id="SERVER">
 
499
    <refsect2 id="server">
508
500
      <title>SERVER</title>
509
501
      <para>
510
502
        Running this <command>&COMMANDNAME;</command> server program
511
503
        should not in itself present any security risk to the host
512
 
        computer running it.  The program does not need any special
513
 
        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.
514
506
      </para>
515
507
    </refsect2>
516
 
    <refsect2 id="CLIENTS">
 
508
    <refsect2 id="clients">
517
509
      <title>CLIENTS</title>
518
510
      <para>
519
511
        The server only gives out its stored data to clients which
526
518
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
527
519
        <manvolnum>5</manvolnum></citerefentry>)
528
520
        <emphasis>must</emphasis> be made non-readable by anyone
529
 
        except the user running the server.
 
521
        except the user starting the server (usually root).
530
522
      </para>
531
523
      <para>
532
524
        As detailed in <xref linkend="checking"/>, the status of all
543
535
        restarting servers if it is suspected that a client has, in
544
536
        fact, been compromised by parties who may now be running a
545
537
        fake Mandos client with the keys from the non-encrypted
546
 
        initial RAM image of the client host.  What should be done in
547
 
        that case (if restarting the server program really is
548
 
        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
549
541
        configuration file to omit any suspect clients, and restart
550
542
        the server program.
551
543
      </para>
552
544
      <para>
553
545
        For more details on client-side security, see
554
 
        <citerefentry><refentrytitle>password-request</refentrytitle>
 
546
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
555
547
        <manvolnum>8mandos</manvolnum></citerefentry>.
556
548
      </para>
557
549
    </refsect2>
558
550
  </refsect1>
559
 
 
 
551
  
560
552
  <refsect1 id="see_also">
561
553
    <title>SEE ALSO</title>
562
554
    <para>
565
557
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
566
558
        <refentrytitle>mandos.conf</refentrytitle>
567
559
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
568
 
        <refentrytitle>password-request</refentrytitle>
 
560
        <refentrytitle>mandos-client</refentrytitle>
569
561
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
570
562
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
571
563
      </citerefentry>