/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-08-29 07:30:17 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080829073017-tvryowganbf75zp5
* mandos-clients.conf.xml (SEE ALSO): Alphabetized, as per
                                      man-pages(7).
* mandos-keygen.xml: - '' -
* mandos.conf.xml: - '' -
* mandos.xml: - '' -
* plugin-runner.xml: - '' -
* plugins.d/password-request.xml (SEE ALSO): Changed from an
                                             <itemizedlist> to a
                                             <para>, as per
                                             man-pages(7).  Also
                                             alphabetize.

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">
4
5
<!ENTITY COMMANDNAME "mandos">
5
 
<!ENTITY TIMESTAMP "2010-09-26">
6
 
<!ENTITY % common SYSTEM "common.ent">
7
 
%common;
 
6
<!ENTITY TIMESTAMP "2008-08-29">
8
7
]>
9
8
 
10
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
 
   <refentryinfo>
 
10
  <refentryinfo>
12
11
    <title>Mandos Manual</title>
13
12
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
14
13
    <productname>Mandos</productname>
15
 
    <productnumber>&version;</productnumber>
 
14
    <productnumber>&VERSION;</productnumber>
16
15
    <date>&TIMESTAMP;</date>
17
16
    <authorgroup>
18
17
      <author>
32
31
    </authorgroup>
33
32
    <copyright>
34
33
      <year>2008</year>
35
 
      <year>2009</year>
36
 
      <year>2010</year>
37
34
      <holder>Teddy Hogeborn</holder>
38
35
      <holder>Björn Påhlsson</holder>
39
36
    </copyright>
40
 
    <xi:include href="legalnotice.xml"/>
 
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>
41
60
  </refentryinfo>
42
 
  
 
61
 
43
62
  <refmeta>
44
63
    <refentrytitle>&COMMANDNAME;</refentrytitle>
45
64
    <manvolnum>8</manvolnum>
48
67
  <refnamediv>
49
68
    <refname><command>&COMMANDNAME;</command></refname>
50
69
    <refpurpose>
51
 
      Gives encrypted passwords to authenticated Mandos clients
 
70
      Sends encrypted passwords to authenticated Mandos clients
52
71
    </refpurpose>
53
72
  </refnamediv>
54
 
  
 
73
 
55
74
  <refsynopsisdiv>
56
75
    <cmdsynopsis>
57
76
      <command>&COMMANDNAME;</command>
58
 
      <group>
59
 
        <arg choice="plain"><option>--interface
60
 
        <replaceable>NAME</replaceable></option></arg>
61
 
        <arg choice="plain"><option>-i
62
 
        <replaceable>NAME</replaceable></option></arg>
63
 
      </group>
64
 
      <sbr/>
65
 
      <group>
66
 
        <arg choice="plain"><option>--address
67
 
        <replaceable>ADDRESS</replaceable></option></arg>
68
 
        <arg choice="plain"><option>-a
69
 
        <replaceable>ADDRESS</replaceable></option></arg>
70
 
      </group>
71
 
      <sbr/>
72
 
      <group>
73
 
        <arg choice="plain"><option>--port
74
 
        <replaceable>PORT</replaceable></option></arg>
75
 
        <arg choice="plain"><option>-p
76
 
        <replaceable>PORT</replaceable></option></arg>
77
 
      </group>
78
 
      <sbr/>
79
 
      <arg><option>--priority
80
 
      <replaceable>PRIORITY</replaceable></option></arg>
81
 
      <sbr/>
82
 
      <arg><option>--servicename
83
 
      <replaceable>NAME</replaceable></option></arg>
84
 
      <sbr/>
85
 
      <arg><option>--configdir
86
 
      <replaceable>DIRECTORY</replaceable></option></arg>
87
 
      <sbr/>
88
 
      <arg><option>--debug</option></arg>
89
 
      <sbr/>
90
 
      <arg><option>--no-dbus</option></arg>
91
 
      <sbr/>
92
 
      <arg><option>--no-ipv6</option></arg>
 
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>
93
94
    </cmdsynopsis>
94
95
    <cmdsynopsis>
95
96
      <command>&COMMANDNAME;</command>
96
97
      <group choice="req">
97
 
        <arg choice="plain"><option>--help</option></arg>
98
 
        <arg choice="plain"><option>-h</option></arg>
 
98
        <arg choice="plain">-h</arg>
 
99
        <arg choice="plain">--help</arg>
99
100
      </group>
100
101
    </cmdsynopsis>
101
102
    <cmdsynopsis>
102
103
      <command>&COMMANDNAME;</command>
103
 
      <arg choice="plain"><option>--version</option></arg>
 
104
      <arg choice="plain">--version</arg>
104
105
    </cmdsynopsis>
105
106
    <cmdsynopsis>
106
107
      <command>&COMMANDNAME;</command>
107
 
      <arg choice="plain"><option>--check</option></arg>
 
108
      <arg choice="plain">--check</arg>
108
109
    </cmdsynopsis>
109
110
  </refsynopsisdiv>
110
 
  
 
111
 
111
112
  <refsect1 id="description">
112
113
    <title>DESCRIPTION</title>
113
114
    <para>
122
123
      Any authenticated client is then given the stored pre-encrypted
123
124
      password for that specific client.
124
125
    </para>
 
126
 
125
127
  </refsect1>
126
128
  
127
129
  <refsect1 id="purpose">
128
130
    <title>PURPOSE</title>
 
131
 
129
132
    <para>
130
133
      The purpose of this is to enable <emphasis>remote and unattended
131
134
      rebooting</emphasis> of client host computer with an
132
135
      <emphasis>encrypted root file system</emphasis>.  See <xref
133
136
      linkend="overview"/> for details.
134
137
    </para>
 
138
 
135
139
  </refsect1>
136
140
  
137
141
  <refsect1 id="options">
138
142
    <title>OPTIONS</title>
 
143
 
139
144
    <variablelist>
140
145
      <varlistentry>
141
 
        <term><option>--help</option></term>
142
 
        <term><option>-h</option></term>
 
146
        <term><literal>-h</literal>, <literal>--help</literal></term>
143
147
        <listitem>
144
148
          <para>
145
149
            Show a help message and exit
146
150
          </para>
147
151
        </listitem>
148
152
      </varlistentry>
149
 
      
 
153
 
150
154
      <varlistentry>
151
 
        <term><option>--interface</option>
152
 
        <replaceable>NAME</replaceable></term>
153
 
        <term><option>-i</option>
154
 
        <replaceable>NAME</replaceable></term>
 
155
        <term><literal>-i</literal>, <literal>--interface <replaceable
 
156
        >NAME</replaceable></literal></term>
155
157
        <listitem>
156
158
          <xi:include href="mandos-options.xml" xpointer="interface"/>
157
159
        </listitem>
158
160
      </varlistentry>
159
 
      
 
161
 
160
162
      <varlistentry>
161
 
        <term><option>--address
162
 
        <replaceable>ADDRESS</replaceable></option></term>
163
 
        <term><option>-a
164
 
        <replaceable>ADDRESS</replaceable></option></term>
 
163
        <term><literal>-a</literal>, <literal>--address <replaceable>
 
164
        ADDRESS</replaceable></literal></term>
165
165
        <listitem>
166
166
          <xi:include href="mandos-options.xml" xpointer="address"/>
167
167
        </listitem>
168
168
      </varlistentry>
169
 
      
 
169
 
170
170
      <varlistentry>
171
 
        <term><option>--port
172
 
        <replaceable>PORT</replaceable></option></term>
173
 
        <term><option>-p
174
 
        <replaceable>PORT</replaceable></option></term>
 
171
        <term><literal>-p</literal>, <literal>--port <replaceable>
 
172
        PORT</replaceable></literal></term>
175
173
        <listitem>
176
174
          <xi:include href="mandos-options.xml" xpointer="port"/>
177
175
        </listitem>
178
176
      </varlistentry>
179
 
      
 
177
 
180
178
      <varlistentry>
181
 
        <term><option>--check</option></term>
 
179
        <term><literal>--check</literal></term>
182
180
        <listitem>
183
181
          <para>
184
182
            Run the server’s self-tests.  This includes any unit
186
184
          </para>
187
185
        </listitem>
188
186
      </varlistentry>
189
 
      
 
187
 
190
188
      <varlistentry>
191
 
        <term><option>--debug</option></term>
 
189
        <term><literal>--debug</literal></term>
192
190
        <listitem>
193
191
          <xi:include href="mandos-options.xml" xpointer="debug"/>
194
192
        </listitem>
195
193
      </varlistentry>
196
 
      
 
194
 
197
195
      <varlistentry>
198
 
        <term><option>--priority <replaceable>
199
 
        PRIORITY</replaceable></option></term>
 
196
        <term><literal>--priority <replaceable>
 
197
        PRIORITY</replaceable></literal></term>
200
198
        <listitem>
201
199
          <xi:include href="mandos-options.xml" xpointer="priority"/>
202
200
        </listitem>
203
201
      </varlistentry>
204
 
      
 
202
 
205
203
      <varlistentry>
206
 
        <term><option>--servicename
207
 
        <replaceable>NAME</replaceable></option></term>
 
204
        <term><literal>--servicename <replaceable>NAME</replaceable>
 
205
        </literal></term>
208
206
        <listitem>
209
207
          <xi:include href="mandos-options.xml"
210
208
                      xpointer="servicename"/>
211
209
        </listitem>
212
210
      </varlistentry>
213
 
      
 
211
 
214
212
      <varlistentry>
215
 
        <term><option>--configdir
216
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
213
        <term><literal>--configdir <replaceable>DIR</replaceable>
 
214
        </literal></term>
217
215
        <listitem>
218
216
          <para>
219
217
            Directory to search for configuration files.  Default is
225
223
          </para>
226
224
        </listitem>
227
225
      </varlistentry>
228
 
      
 
226
 
229
227
      <varlistentry>
230
 
        <term><option>--version</option></term>
 
228
        <term><literal>--version</literal></term>
231
229
        <listitem>
232
230
          <para>
233
231
            Prints the program version and exit.
234
232
          </para>
235
233
        </listitem>
236
234
      </varlistentry>
237
 
      
238
 
      <varlistentry>
239
 
        <term><option>--no-dbus</option></term>
240
 
        <listitem>
241
 
          <xi:include href="mandos-options.xml" xpointer="dbus"/>
242
 
          <para>
243
 
            See also <xref linkend="dbus_interface"/>.
244
 
          </para>
245
 
        </listitem>
246
 
      </varlistentry>
247
 
      
248
 
      <varlistentry>
249
 
        <term><option>--no-ipv6</option></term>
250
 
        <listitem>
251
 
          <xi:include href="mandos-options.xml" xpointer="ipv6"/>
252
 
        </listitem>
253
 
      </varlistentry>
254
235
    </variablelist>
255
236
  </refsect1>
256
 
  
 
237
 
257
238
  <refsect1 id="overview">
258
239
    <title>OVERVIEW</title>
259
240
    <xi:include href="overview.xml"/>
260
241
    <para>
261
242
      This program is the server part.  It is a normal server program
262
243
      and will run in a normal system environment, not in an initial
263
 
      <acronym>RAM</acronym> disk environment.
 
244
      RAM disk environment.
264
245
    </para>
265
246
  </refsect1>
266
 
  
 
247
 
267
248
  <refsect1 id="protocol">
268
249
    <title>NETWORK PROTOCOL</title>
269
250
    <para>
321
302
      </row>
322
303
    </tbody></tgroup></table>
323
304
  </refsect1>
324
 
  
 
305
 
325
306
  <refsect1 id="checking">
326
307
    <title>CHECKING</title>
327
308
    <para>
328
309
      The server will, by default, continually check that the clients
329
310
      are still up.  If a client has not been confirmed as being up
330
311
      for some time, the client is assumed to be compromised and is no
331
 
      longer eligible to receive the encrypted password.  (Manual
332
 
      intervention is required to re-enable a client.)  The timeout,
 
312
      longer eligible to receive the encrypted password.  The timeout,
333
313
      checker program, and interval between checks can be configured
334
314
      both globally and per client; see <citerefentry>
335
315
      <refentrytitle>mandos-clients.conf</refentrytitle>
336
 
      <manvolnum>5</manvolnum></citerefentry>.  A client successfully
337
 
      receiving its password will also be treated as a successful
338
 
      checker run.
339
 
    </para>
340
 
  </refsect1>
341
 
  
342
 
  <refsect1 id="approval">
343
 
    <title>APPROVAL</title>
344
 
    <para>
345
 
      The server can be configured to require manual approval for a
346
 
      client before it is sent its secret.  The delay to wait for such
347
 
      approval and the default action (approve or deny) can be
348
 
      configured both globally and per client; see <citerefentry>
349
 
      <refentrytitle>mandos-clients.conf</refentrytitle>
350
 
      <manvolnum>5</manvolnum></citerefentry>.  By default all clients
351
 
      will be approved immediately without delay.
352
 
    </para>
353
 
    <para>
354
 
      This can be used to deny a client its secret if not manually
355
 
      approved within a specified time.  It can also be used to make
356
 
      the server delay before giving a client its secret, allowing
357
 
      optional manual denying of this specific client.
358
 
    </para>
359
 
    
360
 
  </refsect1>
361
 
  
 
316
      <manvolnum>5</manvolnum></citerefentry>.
 
317
    </para>
 
318
  </refsect1>
 
319
 
362
320
  <refsect1 id="logging">
363
321
    <title>LOGGING</title>
364
322
    <para>
368
326
      and also show them on the console.
369
327
    </para>
370
328
  </refsect1>
371
 
  
372
 
  <refsect1 id="dbus_interface">
373
 
    <title>D-BUS INTERFACE</title>
374
 
    <para>
375
 
      The server will by default provide a D-Bus system bus interface.
376
 
      This interface will only be accessible by the root user or a
377
 
      Mandos-specific user, if such a user exists.  For documentation
378
 
      of the D-Bus API, see the file <filename>DBUS-API</filename>.
379
 
    </para>
380
 
  </refsect1>
381
 
  
 
329
 
382
330
  <refsect1 id="exit_status">
383
331
    <title>EXIT STATUS</title>
384
332
    <para>
386
334
      critical error is encountered.
387
335
    </para>
388
336
  </refsect1>
389
 
  
 
337
 
390
338
  <refsect1 id="environment">
391
339
    <title>ENVIRONMENT</title>
392
340
    <variablelist>
393
341
      <varlistentry>
394
 
        <term><envar>PATH</envar></term>
 
342
        <term><varname>PATH</varname></term>
395
343
        <listitem>
396
344
          <para>
397
345
            To start the configured checker (see <xref
406
354
      </varlistentry>
407
355
    </variablelist>
408
356
  </refsect1>
409
 
  
410
 
  <refsect1 id="files">
 
357
 
 
358
  <refsect1 id="file">
411
359
    <title>FILES</title>
412
360
    <para>
413
361
      Use the <option>--configdir</option> option to change where
436
384
        </listitem>
437
385
      </varlistentry>
438
386
      <varlistentry>
439
 
        <term><filename>/var/run/mandos.pid</filename></term>
 
387
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
440
388
        <listitem>
441
389
          <para>
442
 
            The file containing the process id of the
443
 
            <command>&COMMANDNAME;</command> process started last.
 
390
            The file containing the process id of
 
391
            <command>&COMMANDNAME;</command>.
444
392
          </para>
445
393
        </listitem>
446
394
      </varlistentry>
474
422
      backtrace.  This could be considered a feature.
475
423
    </para>
476
424
    <para>
477
 
      Currently, if a client is disabled due to having timed out, the
478
 
      server does not record this fact onto permanent storage.  This
479
 
      has some security implications, see <xref linkend="clients"/>.
 
425
      Currently, if a client is declared <quote>invalid</quote> due to
 
426
      having timed out, the server does not record this fact onto
 
427
      permanent storage.  This has some security implications, see
 
428
      <xref linkend="CLIENTS"/>.
 
429
    </para>
 
430
    <para>
 
431
      There is currently no way of querying the server of the current
 
432
      status of clients, other than analyzing its <systemitem
 
433
      class="service">syslog</systemitem> output.
480
434
    </para>
481
435
    <para>
482
436
      There is no fine-grained control over logging and debug output.
485
439
      Debug mode is conflated with running in the foreground.
486
440
    </para>
487
441
    <para>
488
 
      The console log messages do not show a time stamp.
489
 
    </para>
490
 
    <para>
491
 
      This server does not check the expire time of clients’ OpenPGP
492
 
      keys.
 
442
      The console log messages does not show a timestamp.
493
443
    </para>
494
444
  </refsect1>
495
445
  
530
480
      </para>
531
481
    </informalexample>
532
482
  </refsect1>
533
 
  
 
483
 
534
484
  <refsect1 id="security">
535
485
    <title>SECURITY</title>
536
 
    <refsect2 id="server">
 
486
    <refsect2 id="SERVER">
537
487
      <title>SERVER</title>
538
488
      <para>
539
489
        Running this <command>&COMMANDNAME;</command> server program
540
490
        should not in itself present any security risk to the host
541
 
        computer running it.  The program switches to a non-root user
542
 
        soon after startup.
 
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.
543
493
      </para>
544
494
    </refsect2>
545
 
    <refsect2 id="clients">
 
495
    <refsect2 id="CLIENTS">
546
496
      <title>CLIENTS</title>
547
497
      <para>
548
498
        The server only gives out its stored data to clients which
555
505
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
556
506
        <manvolnum>5</manvolnum></citerefentry>)
557
507
        <emphasis>must</emphasis> be made non-readable by anyone
558
 
        except the user starting the server (usually root).
 
508
        except the user running the server.
559
509
      </para>
560
510
      <para>
561
511
        As detailed in <xref linkend="checking"/>, the status of all
564
514
      </para>
565
515
      <para>
566
516
        If a client is compromised, its downtime should be duly noted
567
 
        by the server which would therefore disable the client.  But
568
 
        if the server was ever restarted, it would re-read its client
569
 
        list from its configuration file and again regard all clients
570
 
        therein as enabled, and hence eligible to receive their
571
 
        passwords.  Therefore, be careful when restarting servers if
572
 
        it is suspected that a client has, in fact, been compromised
573
 
        by parties who may now be running a fake Mandos client with
574
 
        the keys from the non-encrypted initial <acronym>RAM</acronym>
575
 
        image of the client host.  What should be done in that case
576
 
        (if restarting the server program really is necessary) is to
577
 
        stop the server program, edit the configuration file to omit
578
 
        any suspect clients, and restart the server program.
 
517
        by the server which would therefore declare the client
 
518
        invalid.  But if the server was ever restarted, it would
 
519
        re-read its client list from its configuration file and again
 
520
        regard all clients therein as valid, and hence eligible to
 
521
        receive their passwords.  Therefore, be careful when
 
522
        restarting servers if it is suspected that a client has, in
 
523
        fact, been compromised by parties who may now be running a
 
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
 
528
        configuration file to omit any suspect clients, and restart
 
529
        the server program.
579
530
      </para>
580
531
      <para>
581
532
        For more details on client-side security, see
582
 
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
533
        <citerefentry><refentrytitle>password-request</refentrytitle>
583
534
        <manvolnum>8mandos</manvolnum></citerefentry>.
584
535
      </para>
585
536
    </refsect2>
586
537
  </refsect1>
587
 
  
 
538
 
588
539
  <refsect1 id="see_also">
589
540
    <title>SEE ALSO</title>
590
541
    <para>
593
544
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
594
545
        <refentrytitle>mandos.conf</refentrytitle>
595
546
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
596
 
        <refentrytitle>mandos-client</refentrytitle>
 
547
        <refentrytitle>password-request</refentrytitle>
597
548
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
598
549
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
599
550
      </citerefentry>