/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

  • Committer: Teddy Hogeborn
  • Date: 2008-08-18 23:55:28 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080818235528-dn628nlbrtzl7z4f
* Makefile: Bug fix: fixed creation of man pages for section 5 pages.

* mandos (main): Changed from requiring "[server]" in mandos.conf(5)
                 to requiring "[DEFAULT]".

* mandos.conf ([server]): Renamed to "[DEFAULT]".

* mandos.conf.xml: Removed <?xml-stylesheet>.  New entity "&OVERVIEW;"
                   referring to "overview.xml".
  (DESCRIPTION): Updated to specify the syntax more precisely.  Use
                 <varname> around the option names.

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>
232
237
        <listitem>
233
238
          <para>
234
239
            Zeroconf service name.  The default is
235
 
            <quote><literal>Mandos</literal></quote>.  You only need
236
 
            to change this if you for some reason want to run more
237
 
            than one server on the same <emphasis>host</emphasis>,
238
 
            which would not normally be useful.  If there are name
239
 
            collisions on the same <emphasis>network</emphasis>, the
240
 
            newer server will automatically rename itself to
241
 
            <quote><literal>Mandos #2</literal></quote>, and so on;
242
 
            therefore, this option is not needed in that case.
 
240
            <quote><literal>Mandos</literal></quote>.  This only needs
 
241
            to be changed this if it, for some reason, is necessary to
 
242
            run more than one server on the same
 
243
            <emphasis>host</emphasis>, which would not normally be
 
244
            useful.  If there are name collisions on the same
 
245
            <emphasis>network</emphasis>, the newer server will
 
246
            automatically rename itself to <quote><literal>Mandos
 
247
            #2</literal></quote>, and so on; therefore, this option is
 
248
            not needed in that case.
243
249
          </para>
244
250
        </listitem>
245
251
      </varlistentry>
372
378
    </para>
373
379
  </refsect1>
374
380
 
 
381
  <refsect1 id="environment">
 
382
    <title>ENVIRONMENT</title>
 
383
    <variablelist>
 
384
      <varlistentry>
 
385
        <term><varname>PATH</varname></term>
 
386
        <listitem>
 
387
          <para>
 
388
            To start the configured checker (see <xref
 
389
            linkend="checking"/>), the server uses
 
390
            <filename>/bin/sh</filename>, which in turn uses
 
391
            <varname>PATH</varname> to search for matching commands if
 
392
            an absolute path is not given.  See <citerefentry>
 
393
            <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
 
394
          </citerefentry>
 
395
          </para>
 
396
        </listitem>
 
397
      </varlistentry>
 
398
    </variablelist>
 
399
  </refsect1>
 
400
 
375
401
  <refsect1 id="file">
376
402
    <title>FILES</title>
377
403
    <para>
418
444
          </para>
419
445
        </listitem>
420
446
      </varlistentry>
 
447
      <varlistentry>
 
448
        <term><filename>/bin/sh</filename></term>
 
449
        <listitem>
 
450
          <para>
 
451
            This is used to start the configured checker command for
 
452
            each client.  See <citerefentry>
 
453
            <refentrytitle>mandos-clients.conf</refentrytitle>
 
454
            <manvolnum>5</manvolnum></citerefentry> for details.
 
455
          </para>
 
456
        </listitem>
 
457
      </varlistentry>
421
458
    </variablelist>
422
459
  </refsect1>
423
 
 
 
460
  
424
461
  <refsect1 id="bugs">
425
462
    <title>BUGS</title>
426
463
    <para>
427
464
      This server might, on especially fatal errors, emit a Python
428
465
      backtrace.  This could be considered a feature.
429
466
    </para>
 
467
    <para>
 
468
      Currently, if a client is declared <quote>invalid</quote> due to
 
469
      having timed out, the server does not record this fact onto
 
470
      permanent storage.  This has some security implications, see
 
471
      <xref linkend="CLIENTS"/>.
 
472
    </para>
 
473
    <para>
 
474
      There is currently no way of querying the server of the current
 
475
      status of clients, other than analyzing its <systemitem
 
476
      class="service">syslog</systemitem> output.
 
477
    </para>
 
478
    <para>
 
479
      There is no fine-grained control over logging and debug output.
 
480
    </para>
 
481
    <para>
 
482
      Debug mode is conflated with running in the foreground.
 
483
    </para>
 
484
    <para>
 
485
      The console log messages does not show a timestamp.
 
486
    </para>
430
487
  </refsect1>
431
 
 
432
 
  <refsect1 id="examples">
433
 
    <title>EXAMPLES</title>
 
488
  
 
489
  <refsect1 id="example">
 
490
    <title>EXAMPLE</title>
434
491
    <informalexample>
435
492
      <para>
436
493
        Normal invocation needs no options:
469
526
 
470
527
  <refsect1 id="security">
471
528
    <title>SECURITY</title>
472
 
    <refsect2>
 
529
    <refsect2 id="SERVER">
473
530
      <title>SERVER</title>
474
531
      <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.
 
532
        Running this <command>&COMMANDNAME;</command> server program
 
533
        should not in itself present any security risk to the host
 
534
        computer running it.  The program does not need any special
 
535
        privileges to run, and is designed to run as a non-root user.
479
536
      </para>
480
537
    </refsect2>
481
 
    <refsect2>
 
538
    <refsect2 id="CLIENTS">
482
539
      <title>CLIENTS</title>
483
540
      <para>
484
541
        The server only gives out its stored data to clients which
499
556
        compromised if they are gone for too long.
500
557
      </para>
501
558
      <para>
 
559
        If a client is compromised, its downtime should be duly noted
 
560
        by the server which would therefore declare the client
 
561
        invalid.  But if the server was ever restarted, it would
 
562
        re-read its client list from its configuration file and again
 
563
        regard all clients therein as valid, and hence eligible to
 
564
        receive their passwords.  Therefore, be careful when
 
565
        restarting servers if it is suspected that a client has, in
 
566
        fact, been compromised by parties who may now be running a
 
567
        fake Mandos client with the keys from the non-encrypted
 
568
        initial RAM image of the client host.  What should be done in
 
569
        that case (if restarting the server program really is
 
570
        necessary) is to stop the server program, edit the
 
571
        configuration file to omit any suspect clients, and restart
 
572
        the server program.
 
573
      </para>
 
574
      <para>
502
575
        For more details on client-side security, see
503
576
        <citerefentry><refentrytitle>password-request</refentrytitle>
504
577
        <manvolnum>8mandos</manvolnum></citerefentry>.