/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-31 12:23:33 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080831122333-qgppahxb4d4b0coc
* plugins.d/password-request.xml (OPTIONS): Make replaceables match
                                            the ones in the SYNOPSIS.
                                            Split <term> tags into one
                                            for each option.  Use
                                            <option> tags instead of
                                            <literal>.  Moved long
                                            options before short.

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-31">
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>
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>
144
160
        <term><option>--help</option></term>
196
212
          <xi:include href="mandos-options.xml" xpointer="debug"/>
197
213
        </listitem>
198
214
      </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
 
      
 
215
 
218
216
      <varlistentry>
219
217
        <term><option>--priority <replaceable>
220
218
        PRIORITY</replaceable></option></term>
222
220
          <xi:include href="mandos-options.xml" xpointer="priority"/>
223
221
        </listitem>
224
222
      </varlistentry>
225
 
      
 
223
 
226
224
      <varlistentry>
227
225
        <term><option>--servicename
228
226
        <replaceable>NAME</replaceable></option></term>
231
229
                      xpointer="servicename"/>
232
230
        </listitem>
233
231
      </varlistentry>
234
 
      
 
232
 
235
233
      <varlistentry>
236
234
        <term><option>--configdir
237
235
        <replaceable>DIRECTORY</replaceable></option></term>
246
244
          </para>
247
245
        </listitem>
248
246
      </varlistentry>
249
 
      
 
247
 
250
248
      <varlistentry>
251
249
        <term><option>--version</option></term>
252
250
        <listitem>
255
253
          </para>
256
254
        </listitem>
257
255
      </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
256
    </variablelist>
276
257
  </refsect1>
277
 
  
 
258
 
278
259
  <refsect1 id="overview">
279
260
    <title>OVERVIEW</title>
280
261
    <xi:include href="overview.xml"/>
281
262
    <para>
282
263
      This program is the server part.  It is a normal server program
283
264
      and will run in a normal system environment, not in an initial
284
 
      <acronym>RAM</acronym> disk environment.
 
265
      RAM disk environment.
285
266
    </para>
286
267
  </refsect1>
287
 
  
 
268
 
288
269
  <refsect1 id="protocol">
289
270
    <title>NETWORK PROTOCOL</title>
290
271
    <para>
342
323
      </row>
343
324
    </tbody></tgroup></table>
344
325
  </refsect1>
345
 
  
 
326
 
346
327
  <refsect1 id="checking">
347
328
    <title>CHECKING</title>
348
329
    <para>
349
330
      The server will, by default, continually check that the clients
350
331
      are still up.  If a client has not been confirmed as being up
351
332
      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,
 
333
      longer eligible to receive the encrypted password.  The timeout,
354
334
      checker program, and interval between checks can be configured
355
335
      both globally and per client; see <citerefentry>
356
336
      <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
 
  
 
337
      <manvolnum>5</manvolnum></citerefentry>.
 
338
    </para>
 
339
  </refsect1>
 
340
 
383
341
  <refsect1 id="logging">
384
342
    <title>LOGGING</title>
385
343
    <para>
389
347
      and also show them on the console.
390
348
    </para>
391
349
  </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
 
  
 
350
 
403
351
  <refsect1 id="exit_status">
404
352
    <title>EXIT STATUS</title>
405
353
    <para>
407
355
      critical error is encountered.
408
356
    </para>
409
357
  </refsect1>
410
 
  
 
358
 
411
359
  <refsect1 id="environment">
412
360
    <title>ENVIRONMENT</title>
413
361
    <variablelist>
427
375
      </varlistentry>
428
376
    </variablelist>
429
377
  </refsect1>
430
 
  
431
 
  <refsect1 id="files">
 
378
 
 
379
  <refsect1 id="file">
432
380
    <title>FILES</title>
433
381
    <para>
434
382
      Use the <option>--configdir</option> option to change where
457
405
        </listitem>
458
406
      </varlistentry>
459
407
      <varlistentry>
460
 
        <term><filename>/var/run/mandos.pid</filename></term>
 
408
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
461
409
        <listitem>
462
410
          <para>
463
 
            The file containing the process id of the
464
 
            <command>&COMMANDNAME;</command> process started last.
 
411
            The file containing the process id of
 
412
            <command>&COMMANDNAME;</command>.
465
413
          </para>
466
414
        </listitem>
467
415
      </varlistentry>
495
443
      backtrace.  This could be considered a feature.
496
444
    </para>
497
445
    <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"/>.
 
446
      Currently, if a client is declared <quote>invalid</quote> due to
 
447
      having timed out, the server does not record this fact onto
 
448
      permanent storage.  This has some security implications, see
 
449
      <xref linkend="CLIENTS"/>.
 
450
    </para>
 
451
    <para>
 
452
      There is currently no way of querying the server of the current
 
453
      status of clients, other than analyzing its <systemitem
 
454
      class="service">syslog</systemitem> output.
501
455
    </para>
502
456
    <para>
503
457
      There is no fine-grained control over logging and debug output.
506
460
      Debug mode is conflated with running in the foreground.
507
461
    </para>
508
462
    <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.
 
463
      The console log messages does not show a timestamp.
514
464
    </para>
515
465
  </refsect1>
516
466
  
551
501
      </para>
552
502
    </informalexample>
553
503
  </refsect1>
554
 
  
 
504
 
555
505
  <refsect1 id="security">
556
506
    <title>SECURITY</title>
557
 
    <refsect2 id="server">
 
507
    <refsect2 id="SERVER">
558
508
      <title>SERVER</title>
559
509
      <para>
560
510
        Running this <command>&COMMANDNAME;</command> server program
561
511
        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.
 
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.
564
514
      </para>
565
515
    </refsect2>
566
 
    <refsect2 id="clients">
 
516
    <refsect2 id="CLIENTS">
567
517
      <title>CLIENTS</title>
568
518
      <para>
569
519
        The server only gives out its stored data to clients which
576
526
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
577
527
        <manvolnum>5</manvolnum></citerefentry>)
578
528
        <emphasis>must</emphasis> be made non-readable by anyone
579
 
        except the user starting the server (usually root).
 
529
        except the user running the server.
580
530
      </para>
581
531
      <para>
582
532
        As detailed in <xref linkend="checking"/>, the status of all
585
535
      </para>
586
536
      <para>
587
537
        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.
 
538
        by the server which would therefore declare the client
 
539
        invalid.  But if the server was ever restarted, it would
 
540
        re-read its client list from its configuration file and again
 
541
        regard all clients therein as valid, and hence eligible to
 
542
        receive their passwords.  Therefore, be careful when
 
543
        restarting servers if it is suspected that a client has, in
 
544
        fact, been compromised by parties who may now be running a
 
545
        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
 
549
        configuration file to omit any suspect clients, and restart
 
550
        the server program.
600
551
      </para>
601
552
      <para>
602
553
        For more details on client-side security, see
603
 
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
554
        <citerefentry><refentrytitle>password-request</refentrytitle>
604
555
        <manvolnum>8mandos</manvolnum></citerefentry>.
605
556
      </para>
606
557
    </refsect2>
607
558
  </refsect1>
608
 
  
 
559
 
609
560
  <refsect1 id="see_also">
610
561
    <title>SEE ALSO</title>
611
562
    <para>
614
565
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
615
566
        <refentrytitle>mandos.conf</refentrytitle>
616
567
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
617
 
        <refentrytitle>mandos-client</refentrytitle>
 
568
        <refentrytitle>password-request</refentrytitle>
618
569
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
619
570
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
620
571
      </citerefentry>