/mandos/release

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/release

« back to all changes in this revision

Viewing changes to mandos.xml

* mandos-keygen: Loop until passwords match when run interactively.

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-09-02">
 
5
<!ENTITY TIMESTAMP "2011-08-08">
 
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
41
    <xi:include href="legalnotice.xml"/>
38
42
  </refentryinfo>
39
 
 
 
43
  
40
44
  <refmeta>
41
45
    <refentrytitle>&COMMANDNAME;</refentrytitle>
42
46
    <manvolnum>8</manvolnum>
48
52
      Gives encrypted passwords to authenticated Mandos clients
49
53
    </refpurpose>
50
54
  </refnamediv>
51
 
 
 
55
  
52
56
  <refsynopsisdiv>
53
57
    <cmdsynopsis>
54
58
      <command>&COMMANDNAME;</command>
83
87
      <replaceable>DIRECTORY</replaceable></option></arg>
84
88
      <sbr/>
85
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>
86
97
    </cmdsynopsis>
87
98
    <cmdsynopsis>
88
99
      <command>&COMMANDNAME;</command>
100
111
      <arg choice="plain"><option>--check</option></arg>
101
112
    </cmdsynopsis>
102
113
  </refsynopsisdiv>
103
 
 
 
114
  
104
115
  <refsect1 id="description">
105
116
    <title>DESCRIPTION</title>
106
117
    <para>
186
197
          <xi:include href="mandos-options.xml" xpointer="debug"/>
187
198
        </listitem>
188
199
      </varlistentry>
189
 
 
 
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
      
190
219
      <varlistentry>
191
220
        <term><option>--priority <replaceable>
192
221
        PRIORITY</replaceable></option></term>
194
223
          <xi:include href="mandos-options.xml" xpointer="priority"/>
195
224
        </listitem>
196
225
      </varlistentry>
197
 
 
 
226
      
198
227
      <varlistentry>
199
228
        <term><option>--servicename
200
229
        <replaceable>NAME</replaceable></option></term>
203
232
                      xpointer="servicename"/>
204
233
        </listitem>
205
234
      </varlistentry>
206
 
 
 
235
      
207
236
      <varlistentry>
208
237
        <term><option>--configdir
209
238
        <replaceable>DIRECTORY</replaceable></option></term>
218
247
          </para>
219
248
        </listitem>
220
249
      </varlistentry>
221
 
 
 
250
      
222
251
      <varlistentry>
223
252
        <term><option>--version</option></term>
224
253
        <listitem>
227
256
          </para>
228
257
        </listitem>
229
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>
230
276
    </variablelist>
231
277
  </refsect1>
232
 
 
 
278
  
233
279
  <refsect1 id="overview">
234
280
    <title>OVERVIEW</title>
235
281
    <xi:include href="overview.xml"/>
239
285
      <acronym>RAM</acronym> disk environment.
240
286
    </para>
241
287
  </refsect1>
242
 
 
 
288
  
243
289
  <refsect1 id="protocol">
244
290
    <title>NETWORK PROTOCOL</title>
245
291
    <para>
297
343
      </row>
298
344
    </tbody></tgroup></table>
299
345
  </refsect1>
300
 
 
 
346
  
301
347
  <refsect1 id="checking">
302
348
    <title>CHECKING</title>
303
349
    <para>
304
350
      The server will, by default, continually check that the clients
305
351
      are still up.  If a client has not been confirmed as being up
306
352
      for some time, the client is assumed to be compromised and is no
307
 
      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,
308
355
      checker program, and interval between checks can be configured
309
356
      both globally and per client; see <citerefentry>
310
357
      <refentrytitle>mandos-clients.conf</refentrytitle>
311
 
      <manvolnum>5</manvolnum></citerefentry>.
312
 
    </para>
313
 
  </refsect1>
314
 
 
 
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
  
315
384
  <refsect1 id="logging">
316
385
    <title>LOGGING</title>
317
386
    <para>
321
390
      and also show them on the console.
322
391
    </para>
323
392
  </refsect1>
324
 
 
 
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
  
325
404
  <refsect1 id="exit_status">
326
405
    <title>EXIT STATUS</title>
327
406
    <para>
329
408
      critical error is encountered.
330
409
    </para>
331
410
  </refsect1>
332
 
 
 
411
  
333
412
  <refsect1 id="environment">
334
413
    <title>ENVIRONMENT</title>
335
414
    <variablelist>
349
428
      </varlistentry>
350
429
    </variablelist>
351
430
  </refsect1>
352
 
 
353
 
  <refsect1 id="file">
 
431
  
 
432
  <refsect1 id="files">
354
433
    <title>FILES</title>
355
434
    <para>
356
435
      Use the <option>--configdir</option> option to change where
379
458
        </listitem>
380
459
      </varlistentry>
381
460
      <varlistentry>
382
 
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
 
461
        <term><filename>/var/run/mandos.pid</filename></term>
383
462
        <listitem>
384
463
          <para>
385
 
            The file containing the process id of
386
 
            <command>&COMMANDNAME;</command>.
 
464
            The file containing the process id of the
 
465
            <command>&COMMANDNAME;</command> process started last.
387
466
          </para>
388
467
        </listitem>
389
468
      </varlistentry>
417
496
      backtrace.  This could be considered a feature.
418
497
    </para>
419
498
    <para>
420
 
      Currently, if a client is declared <quote>invalid</quote> due to
421
 
      having timed out, the server does not record this fact onto
422
 
      permanent storage.  This has some security implications, see
423
 
      <xref linkend="CLIENTS"/>.
424
 
    </para>
425
 
    <para>
426
 
      There is currently no way of querying the server of the current
427
 
      status of clients, other than analyzing its <systemitem
428
 
      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"/>.
429
502
    </para>
430
503
    <para>
431
504
      There is no fine-grained control over logging and debug output.
434
507
      Debug mode is conflated with running in the foreground.
435
508
    </para>
436
509
    <para>
437
 
      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.
438
515
    </para>
439
516
  </refsect1>
440
517
  
475
552
      </para>
476
553
    </informalexample>
477
554
  </refsect1>
478
 
 
 
555
  
479
556
  <refsect1 id="security">
480
557
    <title>SECURITY</title>
481
 
    <refsect2 id="SERVER">
 
558
    <refsect2 id="server">
482
559
      <title>SERVER</title>
483
560
      <para>
484
561
        Running this <command>&COMMANDNAME;</command> server program
485
562
        should not in itself present any security risk to the host
486
 
        computer running it.  The program does not need any special
487
 
        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.
488
565
      </para>
489
566
    </refsect2>
490
 
    <refsect2 id="CLIENTS">
 
567
    <refsect2 id="clients">
491
568
      <title>CLIENTS</title>
492
569
      <para>
493
570
        The server only gives out its stored data to clients which
500
577
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
501
578
        <manvolnum>5</manvolnum></citerefentry>)
502
579
        <emphasis>must</emphasis> be made non-readable by anyone
503
 
        except the user running the server.
 
580
        except the user starting the server (usually root).
504
581
      </para>
505
582
      <para>
506
583
        As detailed in <xref linkend="checking"/>, the status of all
509
586
      </para>
510
587
      <para>
511
588
        If a client is compromised, its downtime should be duly noted
512
 
        by the server which would therefore declare the client
513
 
        invalid.  But if the server was ever restarted, it would
514
 
        re-read its client list from its configuration file and again
515
 
        regard all clients therein as valid, and hence eligible to
516
 
        receive their passwords.  Therefore, be careful when
517
 
        restarting servers if it is suspected that a client has, in
518
 
        fact, been compromised by parties who may now be running a
519
 
        fake Mandos client with the keys from the non-encrypted
520
 
        initial <acronym>RAM</acronym> image of the client host.  What
521
 
        should be done in that case (if restarting the server program
522
 
        really is necessary) is to stop the server program, edit the
523
 
        configuration file to omit any suspect clients, and restart
524
 
        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.
525
601
      </para>
526
602
      <para>
527
603
        For more details on client-side security, see
528
 
        <citerefentry><refentrytitle>password-request</refentrytitle>
 
604
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
529
605
        <manvolnum>8mandos</manvolnum></citerefentry>.
530
606
      </para>
531
607
    </refsect2>
532
608
  </refsect1>
533
 
 
 
609
  
534
610
  <refsect1 id="see_also">
535
611
    <title>SEE ALSO</title>
536
612
    <para>
537
 
      <citerefentry>
538
 
        <refentrytitle>mandos-clients.conf</refentrytitle>
539
 
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
540
 
        <refentrytitle>mandos.conf</refentrytitle>
541
 
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
542
 
        <refentrytitle>password-request</refentrytitle>
543
 
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
544
 
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
545
 
      </citerefentry>
 
613
      <citerefentry><refentrytitle>intro</refentrytitle>
 
614
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
615
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
 
616
      <manvolnum>5</manvolnum></citerefentry>,
 
617
      <citerefentry><refentrytitle>mandos.conf</refentrytitle>
 
618
      <manvolnum>5</manvolnum></citerefentry>,
 
619
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
620
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
621
      <citerefentry><refentrytitle>sh</refentrytitle>
 
622
      <manvolnum>1</manvolnum></citerefentry>
546
623
    </para>
547
624
    <variablelist>
548
625
      <varlistentry>