/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 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
3
3
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
4
<!ENTITY VERSION "1.0">
5
5
<!ENTITY COMMANDNAME "mandos">
6
 
<!ENTITY TIMESTAMP "2008-08-31">
 
6
<!ENTITY OVERVIEW SYSTEM "overview.xml">
7
7
]>
8
8
 
9
 
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
 
9
<refentry>
10
10
  <refentryinfo>
11
 
    <title>Mandos Manual</title>
 
11
    <title>&COMMANDNAME;</title>
12
12
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
 
    <productname>Mandos</productname>
 
13
    <productname>&COMMANDNAME;</productname>
14
14
    <productnumber>&VERSION;</productnumber>
15
 
    <date>&TIMESTAMP;</date>
16
15
    <authorgroup>
17
16
      <author>
18
17
        <firstname>Björn</firstname>
67
66
  <refnamediv>
68
67
    <refname><command>&COMMANDNAME;</command></refname>
69
68
    <refpurpose>
70
 
      Gives encrypted passwords to authenticated Mandos clients
 
69
      Sends encrypted passwords to authenticated Mandos clients
71
70
    </refpurpose>
72
71
  </refnamediv>
73
72
 
74
73
  <refsynopsisdiv>
75
74
    <cmdsynopsis>
76
75
      <command>&COMMANDNAME;</command>
77
 
      <group>
78
 
        <arg choice="plain"><option>--interface
79
 
        <replaceable>NAME</replaceable></option></arg>
80
 
        <arg choice="plain"><option>-i
81
 
        <replaceable>NAME</replaceable></option></arg>
82
 
      </group>
83
 
      <sbr/>
84
 
      <group>
85
 
        <arg choice="plain"><option>--address
86
 
        <replaceable>ADDRESS</replaceable></option></arg>
87
 
        <arg choice="plain"><option>-a
88
 
        <replaceable>ADDRESS</replaceable></option></arg>
89
 
      </group>
90
 
      <sbr/>
91
 
      <group>
92
 
        <arg choice="plain"><option>--port
93
 
        <replaceable>PORT</replaceable></option></arg>
94
 
        <arg choice="plain"><option>-p
95
 
        <replaceable>PORT</replaceable></option></arg>
96
 
      </group>
97
 
      <sbr/>
98
 
      <arg><option>--priority
99
 
      <replaceable>PRIORITY</replaceable></option></arg>
100
 
      <sbr/>
101
 
      <arg><option>--servicename
102
 
      <replaceable>NAME</replaceable></option></arg>
103
 
      <sbr/>
104
 
      <arg><option>--configdir
105
 
      <replaceable>DIRECTORY</replaceable></option></arg>
106
 
      <sbr/>
107
 
      <arg><option>--debug</option></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>
108
93
    </cmdsynopsis>
109
94
    <cmdsynopsis>
110
95
      <command>&COMMANDNAME;</command>
111
96
      <group choice="req">
112
 
        <arg choice="plain"><option>--help</option></arg>
113
 
        <arg choice="plain"><option>-h</option></arg>
 
97
        <arg choice="plain">-h</arg>
 
98
        <arg choice="plain">--help</arg>
114
99
      </group>
115
100
    </cmdsynopsis>
116
101
    <cmdsynopsis>
117
102
      <command>&COMMANDNAME;</command>
118
 
      <arg choice="plain"><option>--version</option></arg>
 
103
      <arg choice="plain">--version</arg>
119
104
    </cmdsynopsis>
120
105
    <cmdsynopsis>
121
106
      <command>&COMMANDNAME;</command>
122
 
      <arg choice="plain"><option>--check</option></arg>
 
107
      <arg choice="plain">--check</arg>
123
108
    </cmdsynopsis>
124
109
  </refsynopsisdiv>
125
110
 
157
142
 
158
143
    <variablelist>
159
144
      <varlistentry>
160
 
        <term><option>-h</option></term>
161
 
        <term><option>--help</option></term>
 
145
        <term><literal>-h</literal>, <literal>--help</literal></term>
162
146
        <listitem>
163
147
          <para>
164
148
            Show a help message and exit
167
151
      </varlistentry>
168
152
 
169
153
      <varlistentry>
170
 
        <term><option>-i</option>
171
 
        <replaceable>NAME</replaceable></term>
172
 
        <term><option>--interface</option>
173
 
        <replaceable>NAME</replaceable></term>
 
154
        <term><literal>-i</literal>, <literal>--interface <replaceable>
 
155
        IF</replaceable></literal></term>
174
156
        <listitem>
175
 
          <xi:include href="mandos-options.xml" xpointer="interface"/>
 
157
          <para>
 
158
            Only announce the server and listen to requests on network
 
159
            interface <replaceable>IF</replaceable>.  Default is to
 
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.
 
163
          </para>
176
164
        </listitem>
177
165
      </varlistentry>
178
166
 
180
168
        <term><literal>-a</literal>, <literal>--address <replaceable>
181
169
        ADDRESS</replaceable></literal></term>
182
170
        <listitem>
183
 
          <xi:include href="mandos-options.xml" xpointer="address"/>
 
171
          <para>
 
172
            If this option is used, the server will only listen to a
 
173
            specific address.  This must currently be an IPv6 address;
 
174
            an IPv4 address can be specified using the
 
175
            <quote><literal>::FFFF:192.0.2.3</literal></quote> syntax.
 
176
            Also, if a link-local address is specified, an interface
 
177
            should be set, since a link-local address is only valid on
 
178
            a single interface.  By default, the server will listen to
 
179
            all available addresses.
 
180
          </para>
184
181
        </listitem>
185
182
      </varlistentry>
186
183
 
188
185
        <term><literal>-p</literal>, <literal>--port <replaceable>
189
186
        PORT</replaceable></literal></term>
190
187
        <listitem>
191
 
          <xi:include href="mandos-options.xml" xpointer="port"/>
 
188
          <para>
 
189
            If this option is used, the server to bind to that
 
190
            port. By default, the server will listen to an arbitrary
 
191
            port given by the operating system.
 
192
          </para>
192
193
        </listitem>
193
194
      </varlistentry>
194
195
 
205
206
      <varlistentry>
206
207
        <term><literal>--debug</literal></term>
207
208
        <listitem>
208
 
          <xi:include href="mandos-options.xml" xpointer="debug"/>
 
209
          <para>
 
210
            If the server is run in debug mode, it will run in the
 
211
            foreground and print a lot of debugging information.  The
 
212
            default is <emphasis>not</emphasis> to run in debug mode.
 
213
          </para>
209
214
        </listitem>
210
215
      </varlistentry>
211
216
 
213
218
        <term><literal>--priority <replaceable>
214
219
        PRIORITY</replaceable></literal></term>
215
220
        <listitem>
216
 
          <xi:include href="mandos-options.xml" xpointer="priority"/>
 
221
          <para>
 
222
            GnuTLS priority string for the TLS handshake with the
 
223
            clients.  The default is
 
224
            <quote><literal>SECURE256:!CTYPE-X.509:+CTYPE-OPENPGP</literal></quote>.
 
225
            See <citerefentry><refentrytitle>gnutls_priority_init
 
226
            </refentrytitle><manvolnum>3</manvolnum></citerefentry>
 
227
            for the syntax.  <emphasis>Warning</emphasis>: changing
 
228
            this may make the TLS handshake fail, making communication
 
229
            with clients impossible.
 
230
          </para>
217
231
        </listitem>
218
232
      </varlistentry>
219
233
 
221
235
        <term><literal>--servicename <replaceable>NAME</replaceable>
222
236
        </literal></term>
223
237
        <listitem>
224
 
          <xi:include href="mandos-options.xml"
225
 
                      xpointer="servicename"/>
 
238
          <para>
 
239
            Zeroconf service name.  The default is
 
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.
 
249
          </para>
226
250
        </listitem>
227
251
      </varlistentry>
228
252
 
254
278
 
255
279
  <refsect1 id="overview">
256
280
    <title>OVERVIEW</title>
257
 
    <xi:include href="overview.xml"/>
 
281
    &OVERVIEW;
258
282
    <para>
259
283
      This program is the server part.  It is a normal server program
260
284
      and will run in a normal system environment, not in an initial
293
317
        <entry>-><!-- &rarr; --></entry>
294
318
      </row>
295
319
      <row>
296
 
        <entry><quote><literal>1\r\n</literal></quote></entry>
 
320
        <entry><quote><literal>1\r\en</literal></quote></entry>
297
321
        <entry>-><!-- &rarr; --></entry>
298
322
      </row>
299
323
      <row>
329
353
      longer eligible to receive the encrypted password.  The timeout,
330
354
      checker program, and interval between checks can be configured
331
355
      both globally and per client; see <citerefentry>
 
356
      <refentrytitle>mandos.conf</refentrytitle>
 
357
      <manvolnum>5</manvolnum></citerefentry> and <citerefentry>
332
358
      <refentrytitle>mandos-clients.conf</refentrytitle>
333
359
      <manvolnum>5</manvolnum></citerefentry>.
334
360
    </para>
337
363
  <refsect1 id="logging">
338
364
    <title>LOGGING</title>
339
365
    <para>
340
 
      The server will send log message with various severity levels to
341
 
      <filename>/dev/log</filename>.  With the
 
366
      The server will send log messaged with various severity levels
 
367
      to <filename>/dev/log</filename>.  With the
342
368
      <option>--debug</option> option, it will log even more messages,
343
369
      and also show them on the console.
344
370
    </para>
356
382
    <title>ENVIRONMENT</title>
357
383
    <variablelist>
358
384
      <varlistentry>
359
 
        <term><envar>PATH</envar></term>
 
385
        <term><varname>PATH</varname></term>
360
386
        <listitem>
361
387
          <para>
362
388
            To start the configured checker (see <xref
365
391
            <varname>PATH</varname> to search for matching commands if
366
392
            an absolute path is not given.  See <citerefentry>
367
393
            <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
368
 
            </citerefentry>.
 
394
          </citerefentry>
369
395
          </para>
370
396
        </listitem>
371
397
      </varlistentry>
467
493
        Normal invocation needs no options:
468
494
      </para>
469
495
      <para>
470
 
        <userinput>&COMMANDNAME;</userinput>
 
496
        <userinput>mandos</userinput>
471
497
      </para>
472
498
    </informalexample>
473
499
    <informalexample>
480
506
      <para>
481
507
 
482
508
<!-- do not wrap this line -->
483
 
<userinput>&COMMANDNAME; --debug --configdir ~/mandos --servicename Test</userinput>
 
509
<userinput>mandos --debug --configdir ~/mandos --servicename Test</userinput>
484
510
 
485
511
      </para>
486
512
    </informalexample>
492
518
      <para>
493
519
 
494
520
<!-- do not wrap this line -->
495
 
<userinput>&COMMANDNAME; --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>
 
521
<userinput>mandos --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>
496
522
 
497
523
      </para>
498
524
    </informalexample>
555
581
 
556
582
  <refsect1 id="see_also">
557
583
    <title>SEE ALSO</title>
558
 
    <para>
559
 
      <citerefentry>
560
 
        <refentrytitle>mandos-clients.conf</refentrytitle>
561
 
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
562
 
        <refentrytitle>mandos.conf</refentrytitle>
563
 
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
564
 
        <refentrytitle>password-request</refentrytitle>
565
 
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
566
 
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
567
 
      </citerefentry>
568
 
    </para>
569
584
    <variablelist>
570
585
      <varlistentry>
571
586
        <term>
 
587
          <citerefentry>
 
588
            <refentrytitle>password-request</refentrytitle>
 
589
            <manvolnum>8mandos</manvolnum>
 
590
          </citerefentry>
 
591
        </term>
 
592
        <listitem>
 
593
          <para>
 
594
            This is the actual program which talks to this server.
 
595
            Note that it is normally not invoked directly, and is only
 
596
            run in the initial RAM disk environment, and not on a
 
597
            fully started system.
 
598
          </para>
 
599
        </listitem>
 
600
      </varlistentry>
 
601
      <varlistentry>
 
602
        <term>
572
603
          <ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
573
604
        </term>
574
605
        <listitem>
591
622
      </varlistentry>
592
623
      <varlistentry>
593
624
        <term>
594
 
          <ulink url="http://www.gnu.org/software/gnutls/"
595
 
          >GnuTLS</ulink>
 
625
          <ulink
 
626
              url="http://www.gnu.org/software/gnutls/">GnuTLS</ulink>
596
627
        </term>
597
628
      <listitem>
598
629
        <para>
604
635
      </varlistentry>
605
636
      <varlistentry>
606
637
        <term>
607
 
          RFC 4291: <citetitle>IP Version 6 Addressing
608
 
          Architecture</citetitle>
 
638
          <citation>RFC 4291: <citetitle>IP Version 6 Addressing
 
639
          Architecture</citetitle>, section 2.5.6, Link-Local IPv6
 
640
          Unicast Addresses</citation>
609
641
        </term>
610
642
        <listitem>
611
 
          <variablelist>
612
 
            <varlistentry>
613
 
              <term>Section 2.2: <citetitle>Text Representation of
614
 
              Addresses</citetitle></term>
615
 
              <listitem><para/></listitem>
616
 
            </varlistentry>
617
 
            <varlistentry>
618
 
              <term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6
619
 
              Address</citetitle></term>
620
 
              <listitem><para/></listitem>
621
 
            </varlistentry>
622
 
            <varlistentry>
623
 
            <term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast
624
 
            Addresses</citetitle></term>
625
 
            <listitem>
626
 
              <para>
627
 
                The clients use IPv6 link-local addresses, which are
628
 
                immediately usable since a link-local addresses is
629
 
                automatically assigned to a network interfaces when it
630
 
                is brought up.
631
 
              </para>
632
 
            </listitem>
633
 
            </varlistentry>
634
 
          </variablelist>
 
643
          <para>
 
644
            The clients use IPv6 link-local addresses, which are
 
645
            immediately usable since a link-local addresses is
 
646
            automatically assigned to a network interfaces when it is
 
647
            brought up.
 
648
          </para>
635
649
        </listitem>
636
650
      </varlistentry>
637
651
      <varlistentry>
638
652
        <term>
639
 
          RFC 4346: <citetitle>The Transport Layer Security (TLS)
640
 
          Protocol Version 1.1</citetitle>
 
653
          <citation>RFC 4346: <citetitle>The Transport Layer Security
 
654
          (TLS) Protocol Version 1.1</citetitle></citation>
641
655
        </term>
642
656
      <listitem>
643
657
        <para>
647
661
      </varlistentry>
648
662
      <varlistentry>
649
663
        <term>
650
 
          RFC 4880: <citetitle>OpenPGP Message Format</citetitle>
 
664
          <citation>RFC 4880: <citetitle>OpenPGP Message
 
665
          Format</citetitle></citation>
651
666
        </term>
652
667
      <listitem>
653
668
        <para>
657
672
      </varlistentry>
658
673
      <varlistentry>
659
674
        <term>
660
 
          RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer
661
 
          Security</citetitle>
 
675
          <citation>RFC 5081: <citetitle>Using OpenPGP Keys for
 
676
          Transport Layer Security</citetitle></citation>
662
677
        </term>
663
678
      <listitem>
664
679
        <para>
670
685
    </variablelist>
671
686
  </refsect1>
672
687
</refentry>
673
 
<!-- Local Variables: -->
674
 
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
675
 
<!-- time-stamp-end: "[\"']>" -->
676
 
<!-- time-stamp-format: "%:y-%02m-%02d" -->
677
 
<!-- End: -->