/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 at bsnet
  • Date: 2011-07-31 13:05:34 UTC
  • Revision ID: teddy@fukt.bsnet.se-20110731130534-v4d9hsvek80ms9uo
* plugins.d/mandos-client.c (avahi_loop_with_timeout): Fix warning.
  (main): Disallow "--retry" arguments < 0.  Allow brackets [] around
          IPv6 addresses, as recommended by RFC 5952.  Bug fix: When
          using --connect, really use retry_interval, not 1 second.
* plugins.d/mandos-client.xml (DESCRIPTION): Add retry info.
  (--retry): Remove repeated word.

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 "2011-02-27">
 
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>
 
36
      <year>2010</year>
 
37
      <year>2011</year>
34
38
      <holder>Teddy Hogeborn</holder>
35
39
      <holder>Björn Påhlsson</holder>
36
40
    </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>
 
41
    <xi:include href="legalnotice.xml"/>
60
42
  </refentryinfo>
61
 
 
 
43
  
62
44
  <refmeta>
63
45
    <refentrytitle>&COMMANDNAME;</refentrytitle>
64
46
    <manvolnum>8</manvolnum>
70
52
      Gives encrypted passwords to authenticated Mandos clients
71
53
    </refpurpose>
72
54
  </refnamediv>
73
 
 
 
55
  
74
56
  <refsynopsisdiv>
75
57
    <cmdsynopsis>
76
58
      <command>&COMMANDNAME;</command>
105
87
      <replaceable>DIRECTORY</replaceable></option></arg>
106
88
      <sbr/>
107
89
      <arg><option>--debug</option></arg>
 
90
      <sbr/>
 
91
      <arg><option>--debuglevel
 
92
      <replaceable>LEVEL</replaceable></option></arg>
 
93
      <sbr/>
 
94
      <arg><option>--no-dbus</option></arg>
 
95
      <sbr/>
 
96
      <arg><option>--no-ipv6</option></arg>
108
97
    </cmdsynopsis>
109
98
    <cmdsynopsis>
110
99
      <command>&COMMANDNAME;</command>
122
111
      <arg choice="plain"><option>--check</option></arg>
123
112
    </cmdsynopsis>
124
113
  </refsynopsisdiv>
125
 
 
 
114
  
126
115
  <refsect1 id="description">
127
116
    <title>DESCRIPTION</title>
128
117
    <para>
137
126
      Any authenticated client is then given the stored pre-encrypted
138
127
      password for that specific client.
139
128
    </para>
140
 
 
141
129
  </refsect1>
142
130
  
143
131
  <refsect1 id="purpose">
144
132
    <title>PURPOSE</title>
145
 
 
146
133
    <para>
147
134
      The purpose of this is to enable <emphasis>remote and unattended
148
135
      rebooting</emphasis> of client host computer with an
149
136
      <emphasis>encrypted root file system</emphasis>.  See <xref
150
137
      linkend="overview"/> for details.
151
138
    </para>
152
 
    
153
139
  </refsect1>
154
140
  
155
141
  <refsect1 id="options">
156
142
    <title>OPTIONS</title>
157
 
    
158
143
    <variablelist>
159
144
      <varlistentry>
160
145
        <term><option>--help</option></term>
212
197
          <xi:include href="mandos-options.xml" xpointer="debug"/>
213
198
        </listitem>
214
199
      </varlistentry>
215
 
 
 
200
      
 
201
      <varlistentry>
 
202
        <term><option>--debuglevel
 
203
        <replaceable>LEVEL</replaceable></option></term>
 
204
        <listitem>
 
205
          <para>
 
206
            Set the debugging log level.
 
207
            <replaceable>LEVEL</replaceable> is a string, one of
 
208
            <quote><literal>CRITICAL</literal></quote>,
 
209
            <quote><literal>ERROR</literal></quote>,
 
210
            <quote><literal>WARNING</literal></quote>,
 
211
            <quote><literal>INFO</literal></quote>, or
 
212
            <quote><literal>DEBUG</literal></quote>, in order of
 
213
            increasing verbosity.  The default level is
 
214
            <quote><literal>WARNING</literal></quote>.
 
215
          </para>
 
216
        </listitem>
 
217
      </varlistentry>
 
218
      
216
219
      <varlistentry>
217
220
        <term><option>--priority <replaceable>
218
221
        PRIORITY</replaceable></option></term>
220
223
          <xi:include href="mandos-options.xml" xpointer="priority"/>
221
224
        </listitem>
222
225
      </varlistentry>
223
 
 
 
226
      
224
227
      <varlistentry>
225
228
        <term><option>--servicename
226
229
        <replaceable>NAME</replaceable></option></term>
229
232
                      xpointer="servicename"/>
230
233
        </listitem>
231
234
      </varlistentry>
232
 
 
 
235
      
233
236
      <varlistentry>
234
237
        <term><option>--configdir
235
238
        <replaceable>DIRECTORY</replaceable></option></term>
244
247
          </para>
245
248
        </listitem>
246
249
      </varlistentry>
247
 
 
 
250
      
248
251
      <varlistentry>
249
252
        <term><option>--version</option></term>
250
253
        <listitem>
253
256
          </para>
254
257
        </listitem>
255
258
      </varlistentry>
 
259
      
 
260
      <varlistentry>
 
261
        <term><option>--no-dbus</option></term>
 
262
        <listitem>
 
263
          <xi:include href="mandos-options.xml" xpointer="dbus"/>
 
264
          <para>
 
265
            See also <xref linkend="dbus_interface"/>.
 
266
          </para>
 
267
        </listitem>
 
268
      </varlistentry>
 
269
      
 
270
      <varlistentry>
 
271
        <term><option>--no-ipv6</option></term>
 
272
        <listitem>
 
273
          <xi:include href="mandos-options.xml" xpointer="ipv6"/>
 
274
        </listitem>
 
275
      </varlistentry>
256
276
    </variablelist>
257
277
  </refsect1>
258
 
 
 
278
  
259
279
  <refsect1 id="overview">
260
280
    <title>OVERVIEW</title>
261
281
    <xi:include href="overview.xml"/>
262
282
    <para>
263
283
      This program is the server part.  It is a normal server program
264
284
      and will run in a normal system environment, not in an initial
265
 
      RAM disk environment.
 
285
      <acronym>RAM</acronym> disk environment.
266
286
    </para>
267
287
  </refsect1>
268
 
 
 
288
  
269
289
  <refsect1 id="protocol">
270
290
    <title>NETWORK PROTOCOL</title>
271
291
    <para>
323
343
      </row>
324
344
    </tbody></tgroup></table>
325
345
  </refsect1>
326
 
 
 
346
  
327
347
  <refsect1 id="checking">
328
348
    <title>CHECKING</title>
329
349
    <para>
330
350
      The server will, by default, continually check that the clients
331
351
      are still up.  If a client has not been confirmed as being up
332
352
      for some time, the client is assumed to be compromised and is no
333
 
      longer eligible to receive the encrypted password.  The timeout,
 
353
      longer eligible to receive the encrypted password.  (Manual
 
354
      intervention is required to re-enable a client.)  The timeout,
334
355
      checker program, and interval between checks can be configured
335
356
      both globally and per client; see <citerefentry>
336
357
      <refentrytitle>mandos-clients.conf</refentrytitle>
337
 
      <manvolnum>5</manvolnum></citerefentry>.
338
 
    </para>
339
 
  </refsect1>
340
 
 
 
358
      <manvolnum>5</manvolnum></citerefentry>.  A client successfully
 
359
      receiving its password will also be treated as a successful
 
360
      checker run.
 
361
    </para>
 
362
  </refsect1>
 
363
  
 
364
  <refsect1 id="approval">
 
365
    <title>APPROVAL</title>
 
366
    <para>
 
367
      The server can be configured to require manual approval for a
 
368
      client before it is sent its secret.  The delay to wait for such
 
369
      approval and the default action (approve or deny) can be
 
370
      configured both globally and per client; see <citerefentry>
 
371
      <refentrytitle>mandos-clients.conf</refentrytitle>
 
372
      <manvolnum>5</manvolnum></citerefentry>.  By default all clients
 
373
      will be approved immediately without delay.
 
374
    </para>
 
375
    <para>
 
376
      This can be used to deny a client its secret if not manually
 
377
      approved within a specified time.  It can also be used to make
 
378
      the server delay before giving a client its secret, allowing
 
379
      optional manual denying of this specific client.
 
380
    </para>
 
381
    
 
382
  </refsect1>
 
383
  
341
384
  <refsect1 id="logging">
342
385
    <title>LOGGING</title>
343
386
    <para>
347
390
      and also show them on the console.
348
391
    </para>
349
392
  </refsect1>
350
 
 
 
393
  
 
394
  <refsect1 id="dbus_interface">
 
395
    <title>D-BUS INTERFACE</title>
 
396
    <para>
 
397
      The server will by default provide a D-Bus system bus interface.
 
398
      This interface will only be accessible by the root user or a
 
399
      Mandos-specific user, if such a user exists.  For documentation
 
400
      of the D-Bus API, see the file <filename>DBUS-API</filename>.
 
401
    </para>
 
402
  </refsect1>
 
403
  
351
404
  <refsect1 id="exit_status">
352
405
    <title>EXIT STATUS</title>
353
406
    <para>
355
408
      critical error is encountered.
356
409
    </para>
357
410
  </refsect1>
358
 
 
 
411
  
359
412
  <refsect1 id="environment">
360
413
    <title>ENVIRONMENT</title>
361
414
    <variablelist>
375
428
      </varlistentry>
376
429
    </variablelist>
377
430
  </refsect1>
378
 
 
379
 
  <refsect1 id="file">
 
431
  
 
432
  <refsect1 id="files">
380
433
    <title>FILES</title>
381
434
    <para>
382
435
      Use the <option>--configdir</option> option to change where
405
458
        </listitem>
406
459
      </varlistentry>
407
460
      <varlistentry>
408
 
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
 
461
        <term><filename>/var/run/mandos.pid</filename></term>
409
462
        <listitem>
410
463
          <para>
411
 
            The file containing the process id of
412
 
            <command>&COMMANDNAME;</command>.
 
464
            The file containing the process id of the
 
465
            <command>&COMMANDNAME;</command> process started last.
413
466
          </para>
414
467
        </listitem>
415
468
      </varlistentry>
443
496
      backtrace.  This could be considered a feature.
444
497
    </para>
445
498
    <para>
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.
 
499
      Currently, if a client is disabled due to having timed out, the
 
500
      server does not record this fact onto permanent storage.  This
 
501
      has some security implications, see <xref linkend="clients"/>.
455
502
    </para>
456
503
    <para>
457
504
      There is no fine-grained control over logging and debug output.
460
507
      Debug mode is conflated with running in the foreground.
461
508
    </para>
462
509
    <para>
463
 
      The console log messages does not show a timestamp.
 
510
      The console log messages do not show a time stamp.
 
511
    </para>
 
512
    <para>
 
513
      This server does not check the expire time of clients’ OpenPGP
 
514
      keys.
464
515
    </para>
465
516
  </refsect1>
466
517
  
501
552
      </para>
502
553
    </informalexample>
503
554
  </refsect1>
504
 
 
 
555
  
505
556
  <refsect1 id="security">
506
557
    <title>SECURITY</title>
507
 
    <refsect2 id="SERVER">
 
558
    <refsect2 id="server">
508
559
      <title>SERVER</title>
509
560
      <para>
510
561
        Running this <command>&COMMANDNAME;</command> server program
511
562
        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.
 
563
        computer running it.  The program switches to a non-root user
 
564
        soon after startup.
514
565
      </para>
515
566
    </refsect2>
516
 
    <refsect2 id="CLIENTS">
 
567
    <refsect2 id="clients">
517
568
      <title>CLIENTS</title>
518
569
      <para>
519
570
        The server only gives out its stored data to clients which
526
577
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
527
578
        <manvolnum>5</manvolnum></citerefentry>)
528
579
        <emphasis>must</emphasis> be made non-readable by anyone
529
 
        except the user running the server.
 
580
        except the user starting the server (usually root).
530
581
      </para>
531
582
      <para>
532
583
        As detailed in <xref linkend="checking"/>, the status of all
535
586
      </para>
536
587
      <para>
537
588
        If a client is compromised, its downtime should be duly noted
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.
 
589
        by the server which would therefore disable the client.  But
 
590
        if the server was ever restarted, it would re-read its client
 
591
        list from its configuration file and again regard all clients
 
592
        therein as enabled, and hence eligible to receive their
 
593
        passwords.  Therefore, be careful when restarting servers if
 
594
        it is suspected that a client has, in fact, been compromised
 
595
        by parties who may now be running a fake Mandos client with
 
596
        the keys from the non-encrypted initial <acronym>RAM</acronym>
 
597
        image of the client host.  What should be done in that case
 
598
        (if restarting the server program really is necessary) is to
 
599
        stop the server program, edit the configuration file to omit
 
600
        any suspect clients, and restart the server program.
551
601
      </para>
552
602
      <para>
553
603
        For more details on client-side security, see
554
 
        <citerefentry><refentrytitle>password-request</refentrytitle>
 
604
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
555
605
        <manvolnum>8mandos</manvolnum></citerefentry>.
556
606
      </para>
557
607
    </refsect2>
558
608
  </refsect1>
559
 
 
 
609
  
560
610
  <refsect1 id="see_also">
561
611
    <title>SEE ALSO</title>
562
612
    <para>
565
615
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
566
616
        <refentrytitle>mandos.conf</refentrytitle>
567
617
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
568
 
        <refentrytitle>password-request</refentrytitle>
 
618
        <refentrytitle>mandos-client</refentrytitle>
569
619
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
570
620
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
571
621
      </citerefentry>