/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-18 03:25:01 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080818032501-2cl874fi3uvsqn1b
* mandos.xml (SYNOPSIS): Removed unnecessary 'choice="opt"' from <arg>
                         tags.  Also show the "-h" option.
  (OPTIONS): Note that failure to obey the "--interface" option is not
             considered critical.
  (ENVIRONMENT): New section to document the use of PATH by /bin/sh.
  (FILES): Added "/bin/sh".
  (BUGS): Add five bugs from the TODO file.
  (EXAMPLES): Renamed to "EXAMPLE", as per man-pages(7).
  (SERVER, CLIENTS): Added "id" attribute.
  (CLIENT): Document the security implications of one of the five
            bugs added to the BUGS section.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos.xml
73
73
  <refsynopsisdiv>
74
74
    <cmdsynopsis>
75
75
      <command>&COMMANDNAME;</command>
76
 
      <arg choice="opt">--interface<arg choice="plain">IF</arg></arg>
77
 
      <arg choice="opt">--address<arg choice="plain">ADDRESS</arg></arg>
78
 
      <arg choice="opt">--port<arg choice="plain">PORT</arg></arg>
79
 
      <arg choice="opt">--priority<arg choice="plain">PRIORITY</arg></arg>
80
 
      <arg choice="opt">--servicename<arg choice="plain">NAME</arg></arg>
81
 
      <arg choice="opt">--configdir<arg choice="plain">DIRECTORY</arg></arg>
82
 
      <arg choice="opt">--debug</arg>
83
 
    </cmdsynopsis>
84
 
    <cmdsynopsis>
85
 
      <command>&COMMANDNAME;</command>
86
 
      <arg choice="opt">-i<arg choice="plain">IF</arg></arg>
87
 
      <arg choice="opt">-a<arg choice="plain">ADDRESS</arg></arg>
88
 
      <arg choice="opt">-p<arg choice="plain">PORT</arg></arg>
89
 
      <arg choice="opt">--priority<arg choice="plain">PRIORITY</arg></arg>
90
 
      <arg choice="opt">--servicename<arg choice="plain">NAME</arg></arg>
91
 
      <arg choice="opt">--configdir<arg choice="plain">DIRECTORY</arg></arg>
92
 
      <arg choice="opt">--debug</arg>
93
 
    </cmdsynopsis>
94
 
    <cmdsynopsis>
95
 
      <command>&COMMANDNAME;</command>
96
 
      <arg choice="plain">--help</arg>
 
76
      <arg>--interface<arg choice="plain">IF</arg></arg>
 
77
      <arg>--address<arg choice="plain">ADDRESS</arg></arg>
 
78
      <arg>--port<arg choice="plain">PORT</arg></arg>
 
79
      <arg>--priority<arg choice="plain">PRIORITY</arg></arg>
 
80
      <arg>--servicename<arg choice="plain">NAME</arg></arg>
 
81
      <arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>
 
82
      <arg>--debug</arg>
 
83
    </cmdsynopsis>
 
84
    <cmdsynopsis>
 
85
      <command>&COMMANDNAME;</command>
 
86
      <arg>-i<arg choice="plain">IF</arg></arg>
 
87
      <arg>-a<arg choice="plain">ADDRESS</arg></arg>
 
88
      <arg>-p<arg choice="plain">PORT</arg></arg>
 
89
      <arg>--priority<arg choice="plain">PRIORITY</arg></arg>
 
90
      <arg>--servicename<arg choice="plain">NAME</arg></arg>
 
91
      <arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>
 
92
      <arg>--debug</arg>
 
93
    </cmdsynopsis>
 
94
    <cmdsynopsis>
 
95
      <command>&COMMANDNAME;</command>
 
96
      <group choice="req">
 
97
        <arg choice="plain">-h</arg>
 
98
        <arg choice="plain">--help</arg>
 
99
      </group>
97
100
    </cmdsynopsis>
98
101
    <cmdsynopsis>
99
102
      <command>&COMMANDNAME;</command>
154
157
          <para>
155
158
            Only announce the server and listen to requests on network
156
159
            interface <replaceable>IF</replaceable>.  Default is to
157
 
            use all available interfaces.
 
160
            use all available interfaces.  <emphasis>Note:</emphasis>
 
161
            a failure to bind to the specified interface is not
 
162
            considered critical, and the server does not exit.
158
163
          </para>
159
164
        </listitem>
160
165
      </varlistentry>
372
377
    </para>
373
378
  </refsect1>
374
379
 
 
380
  <refsect1 id="environment">
 
381
    <title>ENVIRONMENT</title>
 
382
    <variablelist>
 
383
      <varlistentry>
 
384
        <term><varname>PATH</varname></term>
 
385
        <listitem>
 
386
          <para>
 
387
            To start the configured checker (see <xref
 
388
            linkend="checking"/>), the server uses
 
389
            <filename>/bin/sh</filename>, which in turn uses
 
390
            <varname>PATH</varname> to search for matching commands if
 
391
            an absolute path is not given.  See <citerefentry>
 
392
            <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
 
393
          </citerefentry>
 
394
          </para>
 
395
        </listitem>
 
396
      </varlistentry>
 
397
    </variablelist>
 
398
  </refsect1>
 
399
 
375
400
  <refsect1 id="file">
376
401
    <title>FILES</title>
377
402
    <para>
418
443
          </para>
419
444
        </listitem>
420
445
      </varlistentry>
 
446
      <varlistentry>
 
447
        <term><filename>/bin/sh</filename></term>
 
448
        <listitem>
 
449
          <para>
 
450
            This is used to start the configured checker command for
 
451
            each client.  See <citerefentry>
 
452
            <refentrytitle>mandos-clients.conf</refentrytitle>
 
453
            <manvolnum>5</manvolnum></citerefentry> for details.
 
454
          </para>
 
455
        </listitem>
 
456
      </varlistentry>
421
457
    </variablelist>
422
458
  </refsect1>
423
 
 
 
459
  
424
460
  <refsect1 id="bugs">
425
461
    <title>BUGS</title>
426
462
    <para>
427
463
      This server might, on especially fatal errors, emit a Python
428
464
      backtrace.  This could be considered a feature.
429
465
    </para>
 
466
    <para>
 
467
      Currently, if a client is declared <quote>invalid</quote> due to
 
468
      having timed out, the server does not record this fact onto
 
469
      permanent storage.  This has some security implications, see
 
470
      <xref linkend="CLIENTS"/>.
 
471
    </para>
 
472
    <para>
 
473
      There is currently no way of querying the server of the current
 
474
      status of clients, other than analyzing its <systemitem
 
475
      class="service">syslog</systemitem> output.
 
476
    </para>
 
477
    <para>
 
478
      There is no fine-grained control over logging and debug output.
 
479
    </para>
 
480
    <para>
 
481
      Debug mode is conflated with running in the foreground.
 
482
    </para>
 
483
    <para>
 
484
      The console log messages does not show a timestamp.
 
485
    </para>
430
486
  </refsect1>
431
 
 
432
 
  <refsect1 id="examples">
433
 
    <title>EXAMPLES</title>
 
487
  
 
488
  <refsect1 id="example">
 
489
    <title>EXAMPLE</title>
434
490
    <informalexample>
435
491
      <para>
436
492
        Normal invocation needs no options:
469
525
 
470
526
  <refsect1 id="security">
471
527
    <title>SECURITY</title>
472
 
    <refsect2>
 
528
    <refsect2 id="SERVER">
473
529
      <title>SERVER</title>
474
530
      <para>
475
 
        Running this &COMMANDNAME; server program should not in itself
476
 
        present any security risk to the host computer running it.
477
 
        The program does not need any special privileges to run, and
478
 
        is designed to run as a non-root user.
 
531
        Running this <command>&COMMANDNAME;</command> server program
 
532
        should not in itself present any security risk to the host
 
533
        computer running it.  The program does not need any special
 
534
        privileges to run, and is designed to run as a non-root user.
479
535
      </para>
480
536
    </refsect2>
481
 
    <refsect2>
 
537
    <refsect2 id="CLIENTS">
482
538
      <title>CLIENTS</title>
483
539
      <para>
484
540
        The server only gives out its stored data to clients which
499
555
        compromised if they are gone for too long.
500
556
      </para>
501
557
      <para>
 
558
        If a client is compromised, its downtime should be duly noted
 
559
        by the server which would therefore declare the client
 
560
        invalid.  But if the server was ever restarted, it would
 
561
        re-read its client list from its configuration file and again
 
562
        regard all clients therein as valid, and hence eligible to
 
563
        receive their passwords.  Therefore, be careful when
 
564
        restarting servers if you suspect that a client has, in fact,
 
565
        been compromised by parties who may now be running a fake
 
566
        Mandos client with the keys from the non-encrypted initial RAM
 
567
        image of the client host.  What should be done in that case
 
568
        (if restarting the server program really is necessary) is to
 
569
        stop the server program, edit the configuration file to omit
 
570
        any suspect clients, and restart the server program.
 
571
      </para>
 
572
      <para>
502
573
        For more details on client-side security, see
503
574
        <citerefentry><refentrytitle>password-request</refentrytitle>
504
575
        <manvolnum>8mandos</manvolnum></citerefentry>.