/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-30 19:05:15 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080830190515-l7e6vu81yyw5kcku
* mandos.xml (SYNOPSIS): Use <option> and <replaceable> tags.  Unify
                         short and long options.

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-30">
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>
51
70
      Gives 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>
86
105
      <replaceable>DIRECTORY</replaceable></option></arg>
87
106
      <sbr/>
88
107
      <arg><option>--debug</option></arg>
89
 
      <sbr/>
90
 
      <arg><option>--debuglevel
91
 
      <replaceable>LEVEL</replaceable></option></arg>
92
 
      <sbr/>
93
 
      <arg><option>--no-dbus</option></arg>
94
 
      <sbr/>
95
 
      <arg><option>--no-ipv6</option></arg>
96
108
    </cmdsynopsis>
97
109
    <cmdsynopsis>
98
110
      <command>&COMMANDNAME;</command>
99
111
      <group choice="req">
 
112
        <arg choice="plain"><option>-h</option></arg>
100
113
        <arg choice="plain"><option>--help</option></arg>
101
 
        <arg choice="plain"><option>-h</option></arg>
102
114
      </group>
103
115
    </cmdsynopsis>
104
116
    <cmdsynopsis>
110
122
      <arg choice="plain"><option>--check</option></arg>
111
123
    </cmdsynopsis>
112
124
  </refsynopsisdiv>
113
 
  
 
125
 
114
126
  <refsect1 id="description">
115
127
    <title>DESCRIPTION</title>
116
128
    <para>
125
137
      Any authenticated client is then given the stored pre-encrypted
126
138
      password for that specific client.
127
139
    </para>
 
140
 
128
141
  </refsect1>
129
142
  
130
143
  <refsect1 id="purpose">
131
144
    <title>PURPOSE</title>
 
145
 
132
146
    <para>
133
147
      The purpose of this is to enable <emphasis>remote and unattended
134
148
      rebooting</emphasis> of client host computer with an
135
149
      <emphasis>encrypted root file system</emphasis>.  See <xref
136
150
      linkend="overview"/> for details.
137
151
    </para>
 
152
 
138
153
  </refsect1>
139
154
  
140
155
  <refsect1 id="options">
141
156
    <title>OPTIONS</title>
 
157
 
142
158
    <variablelist>
143
159
      <varlistentry>
 
160
        <term><option>-h</option></term>
144
161
        <term><option>--help</option></term>
145
 
        <term><option>-h</option></term>
146
162
        <listitem>
147
163
          <para>
148
164
            Show a help message and exit
149
165
          </para>
150
166
        </listitem>
151
167
      </varlistentry>
152
 
      
 
168
 
153
169
      <varlistentry>
 
170
        <term><option>-i</option>
 
171
        <replaceable>NAME</replaceable></term>
154
172
        <term><option>--interface</option>
155
173
        <replaceable>NAME</replaceable></term>
156
 
        <term><option>-i</option>
157
 
        <replaceable>NAME</replaceable></term>
158
174
        <listitem>
159
175
          <xi:include href="mandos-options.xml" xpointer="interface"/>
160
176
        </listitem>
161
177
      </varlistentry>
162
 
      
 
178
 
163
179
      <varlistentry>
164
 
        <term><option>--address
165
 
        <replaceable>ADDRESS</replaceable></option></term>
166
 
        <term><option>-a
167
 
        <replaceable>ADDRESS</replaceable></option></term>
 
180
        <term><literal>-a</literal>, <literal>--address <replaceable>
 
181
        ADDRESS</replaceable></literal></term>
168
182
        <listitem>
169
183
          <xi:include href="mandos-options.xml" xpointer="address"/>
170
184
        </listitem>
171
185
      </varlistentry>
172
 
      
 
186
 
173
187
      <varlistentry>
174
 
        <term><option>--port
175
 
        <replaceable>PORT</replaceable></option></term>
176
 
        <term><option>-p
177
 
        <replaceable>PORT</replaceable></option></term>
 
188
        <term><literal>-p</literal>, <literal>--port <replaceable>
 
189
        PORT</replaceable></literal></term>
178
190
        <listitem>
179
191
          <xi:include href="mandos-options.xml" xpointer="port"/>
180
192
        </listitem>
181
193
      </varlistentry>
182
 
      
 
194
 
183
195
      <varlistentry>
184
 
        <term><option>--check</option></term>
 
196
        <term><literal>--check</literal></term>
185
197
        <listitem>
186
198
          <para>
187
199
            Run the server’s self-tests.  This includes any unit
189
201
          </para>
190
202
        </listitem>
191
203
      </varlistentry>
192
 
      
 
204
 
193
205
      <varlistentry>
194
 
        <term><option>--debug</option></term>
 
206
        <term><literal>--debug</literal></term>
195
207
        <listitem>
196
208
          <xi:include href="mandos-options.xml" xpointer="debug"/>
197
209
        </listitem>
198
210
      </varlistentry>
199
 
      
200
 
      <varlistentry>
201
 
        <term><option>--debuglevel
202
 
        <replaceable>LEVEL</replaceable></option></term>
203
 
        <listitem>
204
 
          <para>
205
 
            Set the debugging log level.
206
 
            <replaceable>LEVEL</replaceable> is a string, one of
207
 
            <quote><literal>CRITICAL</literal></quote>,
208
 
            <quote><literal>ERROR</literal></quote>,
209
 
            <quote><literal>WARNING</literal></quote>,
210
 
            <quote><literal>INFO</literal></quote>, or
211
 
            <quote><literal>DEBUG</literal></quote>, in order of
212
 
            increasing verbosity.  The default level is
213
 
            <quote><literal>WARNING</literal></quote>.
214
 
          </para>
215
 
        </listitem>
216
 
      </varlistentry>
217
 
      
218
 
      <varlistentry>
219
 
        <term><option>--priority <replaceable>
220
 
        PRIORITY</replaceable></option></term>
 
211
 
 
212
      <varlistentry>
 
213
        <term><literal>--priority <replaceable>
 
214
        PRIORITY</replaceable></literal></term>
221
215
        <listitem>
222
216
          <xi:include href="mandos-options.xml" xpointer="priority"/>
223
217
        </listitem>
224
218
      </varlistentry>
225
 
      
 
219
 
226
220
      <varlistentry>
227
 
        <term><option>--servicename
228
 
        <replaceable>NAME</replaceable></option></term>
 
221
        <term><literal>--servicename <replaceable>NAME</replaceable>
 
222
        </literal></term>
229
223
        <listitem>
230
224
          <xi:include href="mandos-options.xml"
231
225
                      xpointer="servicename"/>
232
226
        </listitem>
233
227
      </varlistentry>
234
 
      
 
228
 
235
229
      <varlistentry>
236
 
        <term><option>--configdir
237
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
230
        <term><literal>--configdir <replaceable>DIR</replaceable>
 
231
        </literal></term>
238
232
        <listitem>
239
233
          <para>
240
234
            Directory to search for configuration files.  Default is
246
240
          </para>
247
241
        </listitem>
248
242
      </varlistentry>
249
 
      
 
243
 
250
244
      <varlistentry>
251
 
        <term><option>--version</option></term>
 
245
        <term><literal>--version</literal></term>
252
246
        <listitem>
253
247
          <para>
254
248
            Prints the program version and exit.
255
249
          </para>
256
250
        </listitem>
257
251
      </varlistentry>
258
 
      
259
 
      <varlistentry>
260
 
        <term><option>--no-dbus</option></term>
261
 
        <listitem>
262
 
          <xi:include href="mandos-options.xml" xpointer="dbus"/>
263
 
          <para>
264
 
            See also <xref linkend="dbus_interface"/>.
265
 
          </para>
266
 
        </listitem>
267
 
      </varlistentry>
268
 
      
269
 
      <varlistentry>
270
 
        <term><option>--no-ipv6</option></term>
271
 
        <listitem>
272
 
          <xi:include href="mandos-options.xml" xpointer="ipv6"/>
273
 
        </listitem>
274
 
      </varlistentry>
275
252
    </variablelist>
276
253
  </refsect1>
277
 
  
 
254
 
278
255
  <refsect1 id="overview">
279
256
    <title>OVERVIEW</title>
280
257
    <xi:include href="overview.xml"/>
281
258
    <para>
282
259
      This program is the server part.  It is a normal server program
283
260
      and will run in a normal system environment, not in an initial
284
 
      <acronym>RAM</acronym> disk environment.
 
261
      RAM disk environment.
285
262
    </para>
286
263
  </refsect1>
287
 
  
 
264
 
288
265
  <refsect1 id="protocol">
289
266
    <title>NETWORK PROTOCOL</title>
290
267
    <para>
342
319
      </row>
343
320
    </tbody></tgroup></table>
344
321
  </refsect1>
345
 
  
 
322
 
346
323
  <refsect1 id="checking">
347
324
    <title>CHECKING</title>
348
325
    <para>
349
326
      The server will, by default, continually check that the clients
350
327
      are still up.  If a client has not been confirmed as being up
351
328
      for some time, the client is assumed to be compromised and is no
352
 
      longer eligible to receive the encrypted password.  (Manual
353
 
      intervention is required to re-enable a client.)  The timeout,
 
329
      longer eligible to receive the encrypted password.  The timeout,
354
330
      checker program, and interval between checks can be configured
355
331
      both globally and per client; see <citerefentry>
356
332
      <refentrytitle>mandos-clients.conf</refentrytitle>
357
 
      <manvolnum>5</manvolnum></citerefentry>.  A client successfully
358
 
      receiving its password will also be treated as a successful
359
 
      checker run.
360
 
    </para>
361
 
  </refsect1>
362
 
  
363
 
  <refsect1 id="approval">
364
 
    <title>APPROVAL</title>
365
 
    <para>
366
 
      The server can be configured to require manual approval for a
367
 
      client before it is sent its secret.  The delay to wait for such
368
 
      approval and the default action (approve or deny) can be
369
 
      configured both globally and per client; see <citerefentry>
370
 
      <refentrytitle>mandos-clients.conf</refentrytitle>
371
 
      <manvolnum>5</manvolnum></citerefentry>.  By default all clients
372
 
      will be approved immediately without delay.
373
 
    </para>
374
 
    <para>
375
 
      This can be used to deny a client its secret if not manually
376
 
      approved within a specified time.  It can also be used to make
377
 
      the server delay before giving a client its secret, allowing
378
 
      optional manual denying of this specific client.
379
 
    </para>
380
 
    
381
 
  </refsect1>
382
 
  
 
333
      <manvolnum>5</manvolnum></citerefentry>.
 
334
    </para>
 
335
  </refsect1>
 
336
 
383
337
  <refsect1 id="logging">
384
338
    <title>LOGGING</title>
385
339
    <para>
389
343
      and also show them on the console.
390
344
    </para>
391
345
  </refsect1>
392
 
  
393
 
  <refsect1 id="dbus_interface">
394
 
    <title>D-BUS INTERFACE</title>
395
 
    <para>
396
 
      The server will by default provide a D-Bus system bus interface.
397
 
      This interface will only be accessible by the root user or a
398
 
      Mandos-specific user, if such a user exists.  For documentation
399
 
      of the D-Bus API, see the file <filename>DBUS-API</filename>.
400
 
    </para>
401
 
  </refsect1>
402
 
  
 
346
 
403
347
  <refsect1 id="exit_status">
404
348
    <title>EXIT STATUS</title>
405
349
    <para>
407
351
      critical error is encountered.
408
352
    </para>
409
353
  </refsect1>
410
 
  
 
354
 
411
355
  <refsect1 id="environment">
412
356
    <title>ENVIRONMENT</title>
413
357
    <variablelist>
427
371
      </varlistentry>
428
372
    </variablelist>
429
373
  </refsect1>
430
 
  
431
 
  <refsect1 id="files">
 
374
 
 
375
  <refsect1 id="file">
432
376
    <title>FILES</title>
433
377
    <para>
434
378
      Use the <option>--configdir</option> option to change where
457
401
        </listitem>
458
402
      </varlistentry>
459
403
      <varlistentry>
460
 
        <term><filename>/var/run/mandos.pid</filename></term>
 
404
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
461
405
        <listitem>
462
406
          <para>
463
 
            The file containing the process id of the
464
 
            <command>&COMMANDNAME;</command> process started last.
 
407
            The file containing the process id of
 
408
            <command>&COMMANDNAME;</command>.
465
409
          </para>
466
410
        </listitem>
467
411
      </varlistentry>
495
439
      backtrace.  This could be considered a feature.
496
440
    </para>
497
441
    <para>
498
 
      Currently, if a client is disabled due to having timed out, the
499
 
      server does not record this fact onto permanent storage.  This
500
 
      has some security implications, see <xref linkend="clients"/>.
 
442
      Currently, if a client is declared <quote>invalid</quote> due to
 
443
      having timed out, the server does not record this fact onto
 
444
      permanent storage.  This has some security implications, see
 
445
      <xref linkend="CLIENTS"/>.
 
446
    </para>
 
447
    <para>
 
448
      There is currently no way of querying the server of the current
 
449
      status of clients, other than analyzing its <systemitem
 
450
      class="service">syslog</systemitem> output.
501
451
    </para>
502
452
    <para>
503
453
      There is no fine-grained control over logging and debug output.
506
456
      Debug mode is conflated with running in the foreground.
507
457
    </para>
508
458
    <para>
509
 
      The console log messages do not show a time stamp.
510
 
    </para>
511
 
    <para>
512
 
      This server does not check the expire time of clients’ OpenPGP
513
 
      keys.
 
459
      The console log messages does not show a timestamp.
514
460
    </para>
515
461
  </refsect1>
516
462
  
551
497
      </para>
552
498
    </informalexample>
553
499
  </refsect1>
554
 
  
 
500
 
555
501
  <refsect1 id="security">
556
502
    <title>SECURITY</title>
557
 
    <refsect2 id="server">
 
503
    <refsect2 id="SERVER">
558
504
      <title>SERVER</title>
559
505
      <para>
560
506
        Running this <command>&COMMANDNAME;</command> server program
561
507
        should not in itself present any security risk to the host
562
 
        computer running it.  The program switches to a non-root user
563
 
        soon after startup.
 
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.
564
510
      </para>
565
511
    </refsect2>
566
 
    <refsect2 id="clients">
 
512
    <refsect2 id="CLIENTS">
567
513
      <title>CLIENTS</title>
568
514
      <para>
569
515
        The server only gives out its stored data to clients which
576
522
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
577
523
        <manvolnum>5</manvolnum></citerefentry>)
578
524
        <emphasis>must</emphasis> be made non-readable by anyone
579
 
        except the user starting the server (usually root).
 
525
        except the user running the server.
580
526
      </para>
581
527
      <para>
582
528
        As detailed in <xref linkend="checking"/>, the status of all
585
531
      </para>
586
532
      <para>
587
533
        If a client is compromised, its downtime should be duly noted
588
 
        by the server which would therefore disable the client.  But
589
 
        if the server was ever restarted, it would re-read its client
590
 
        list from its configuration file and again regard all clients
591
 
        therein as enabled, and hence eligible to receive their
592
 
        passwords.  Therefore, be careful when restarting servers if
593
 
        it is suspected that a client has, in fact, been compromised
594
 
        by parties who may now be running a fake Mandos client with
595
 
        the keys from the non-encrypted initial <acronym>RAM</acronym>
596
 
        image of the client host.  What should be done in that case
597
 
        (if restarting the server program really is necessary) is to
598
 
        stop the server program, edit the configuration file to omit
599
 
        any suspect clients, and restart the server program.
 
534
        by the server which would therefore declare the client
 
535
        invalid.  But if the server was ever restarted, it would
 
536
        re-read its client list from its configuration file and again
 
537
        regard all clients therein as valid, and hence eligible to
 
538
        receive their passwords.  Therefore, be careful when
 
539
        restarting servers if it is suspected that a client has, in
 
540
        fact, been compromised by parties who may now be running a
 
541
        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
 
545
        configuration file to omit any suspect clients, and restart
 
546
        the server program.
600
547
      </para>
601
548
      <para>
602
549
        For more details on client-side security, see
603
 
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
550
        <citerefentry><refentrytitle>password-request</refentrytitle>
604
551
        <manvolnum>8mandos</manvolnum></citerefentry>.
605
552
      </para>
606
553
    </refsect2>
607
554
  </refsect1>
608
 
  
 
555
 
609
556
  <refsect1 id="see_also">
610
557
    <title>SEE ALSO</title>
611
558
    <para>
614
561
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
615
562
        <refentrytitle>mandos.conf</refentrytitle>
616
563
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
617
 
        <refentrytitle>mandos-client</refentrytitle>
 
564
        <refentrytitle>password-request</refentrytitle>
618
565
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
619
566
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
620
567
      </citerefentry>