/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:50:28 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080818035028-su31apqs2pv2147v
* mandos-keygen.xml: Removed <?xml-stylesheet>.  New entity
                     "&OVERVIEW;" referring to "overview.xml".
  (PURPOSE, OVERVIEW): New sections, same as in mandos(8).
  (EXAMPLES): Renamed to "EXAMPLE", as per man-pages(7).

* mandos.xml (OPTIONS, CLIENTS): Slight wording change.

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-29">
 
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>
74
73
  <refsynopsisdiv>
75
74
    <cmdsynopsis>
76
75
      <command>&COMMANDNAME;</command>
77
 
      <arg>--interface<arg choice="plain">NAME</arg></arg>
 
76
      <arg>--interface<arg choice="plain">IF</arg></arg>
78
77
      <arg>--address<arg choice="plain">ADDRESS</arg></arg>
79
78
      <arg>--port<arg choice="plain">PORT</arg></arg>
80
79
      <arg>--priority<arg choice="plain">PRIORITY</arg></arg>
84
83
    </cmdsynopsis>
85
84
    <cmdsynopsis>
86
85
      <command>&COMMANDNAME;</command>
87
 
      <arg>-i<arg choice="plain">NAME</arg></arg>
 
86
      <arg>-i<arg choice="plain">IF</arg></arg>
88
87
      <arg>-a<arg choice="plain">ADDRESS</arg></arg>
89
88
      <arg>-p<arg choice="plain">PORT</arg></arg>
90
89
      <arg>--priority<arg choice="plain">PRIORITY</arg></arg>
143
142
 
144
143
    <variablelist>
145
144
      <varlistentry>
146
 
        <term><option>-h</option></term>
147
 
        <term><option>--help</option></term>
 
145
        <term><literal>-h</literal>, <literal>--help</literal></term>
148
146
        <listitem>
149
147
          <para>
150
148
            Show a help message and exit
153
151
      </varlistentry>
154
152
 
155
153
      <varlistentry>
156
 
        <term><option>-i</option>
157
 
        <replaceable>NAME</replaceable></term>
158
 
        <term><option>--interface</option>
159
 
        <replaceable>NAME</replaceable></term>
 
154
        <term><literal>-i</literal>, <literal>--interface <replaceable>
 
155
        IF</replaceable></literal></term>
160
156
        <listitem>
161
 
          <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>
162
164
        </listitem>
163
165
      </varlistentry>
164
166
 
166
168
        <term><literal>-a</literal>, <literal>--address <replaceable>
167
169
        ADDRESS</replaceable></literal></term>
168
170
        <listitem>
169
 
          <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>
170
181
        </listitem>
171
182
      </varlistentry>
172
183
 
174
185
        <term><literal>-p</literal>, <literal>--port <replaceable>
175
186
        PORT</replaceable></literal></term>
176
187
        <listitem>
177
 
          <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>
178
193
        </listitem>
179
194
      </varlistentry>
180
195
 
191
206
      <varlistentry>
192
207
        <term><literal>--debug</literal></term>
193
208
        <listitem>
194
 
          <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>
195
214
        </listitem>
196
215
      </varlistentry>
197
216
 
199
218
        <term><literal>--priority <replaceable>
200
219
        PRIORITY</replaceable></literal></term>
201
220
        <listitem>
202
 
          <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>
203
231
        </listitem>
204
232
      </varlistentry>
205
233
 
207
235
        <term><literal>--servicename <replaceable>NAME</replaceable>
208
236
        </literal></term>
209
237
        <listitem>
210
 
          <xi:include href="mandos-options.xml"
211
 
                      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>
212
250
        </listitem>
213
251
      </varlistentry>
214
252
 
240
278
 
241
279
  <refsect1 id="overview">
242
280
    <title>OVERVIEW</title>
243
 
    <xi:include href="overview.xml"/>
 
281
    &OVERVIEW;
244
282
    <para>
245
283
      This program is the server part.  It is a normal server program
246
284
      and will run in a normal system environment, not in an initial
279
317
        <entry>-><!-- &rarr; --></entry>
280
318
      </row>
281
319
      <row>
282
 
        <entry><quote><literal>1\r\n</literal></quote></entry>
 
320
        <entry><quote><literal>1\r\en</literal></quote></entry>
283
321
        <entry>-><!-- &rarr; --></entry>
284
322
      </row>
285
323
      <row>
315
353
      longer eligible to receive the encrypted password.  The timeout,
316
354
      checker program, and interval between checks can be configured
317
355
      both globally and per client; see <citerefentry>
 
356
      <refentrytitle>mandos.conf</refentrytitle>
 
357
      <manvolnum>5</manvolnum></citerefentry> and <citerefentry>
318
358
      <refentrytitle>mandos-clients.conf</refentrytitle>
319
359
      <manvolnum>5</manvolnum></citerefentry>.
320
360
    </para>
323
363
  <refsect1 id="logging">
324
364
    <title>LOGGING</title>
325
365
    <para>
326
 
      The server will send log message with various severity levels to
327
 
      <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
328
368
      <option>--debug</option> option, it will log even more messages,
329
369
      and also show them on the console.
330
370
    </para>
351
391
            <varname>PATH</varname> to search for matching commands if
352
392
            an absolute path is not given.  See <citerefentry>
353
393
            <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
354
 
            </citerefentry>.
 
394
          </citerefentry>
355
395
          </para>
356
396
        </listitem>
357
397
      </varlistentry>
453
493
        Normal invocation needs no options:
454
494
      </para>
455
495
      <para>
456
 
        <userinput>&COMMANDNAME;</userinput>
 
496
        <userinput>mandos</userinput>
457
497
      </para>
458
498
    </informalexample>
459
499
    <informalexample>
466
506
      <para>
467
507
 
468
508
<!-- do not wrap this line -->
469
 
<userinput>&COMMANDNAME; --debug --configdir ~/mandos --servicename Test</userinput>
 
509
<userinput>mandos --debug --configdir ~/mandos --servicename Test</userinput>
470
510
 
471
511
      </para>
472
512
    </informalexample>
478
518
      <para>
479
519
 
480
520
<!-- do not wrap this line -->
481
 
<userinput>&COMMANDNAME; --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>
 
521
<userinput>mandos --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>
482
522
 
483
523
      </para>
484
524
    </informalexample>
541
581
 
542
582
  <refsect1 id="see_also">
543
583
    <title>SEE ALSO</title>
544
 
    <para>
545
 
      <citerefentry>
546
 
        <refentrytitle>mandos-clients.conf</refentrytitle>
547
 
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
548
 
        <refentrytitle>mandos.conf</refentrytitle>
549
 
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
550
 
        <refentrytitle>password-request</refentrytitle>
551
 
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
552
 
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
553
 
      </citerefentry>
554
 
    </para>
555
584
    <variablelist>
556
585
      <varlistentry>
557
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>
558
603
          <ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
559
604
        </term>
560
605
        <listitem>
577
622
      </varlistentry>
578
623
      <varlistentry>
579
624
        <term>
580
 
          <ulink url="http://www.gnu.org/software/gnutls/"
581
 
          >GnuTLS</ulink>
 
625
          <ulink
 
626
              url="http://www.gnu.org/software/gnutls/">GnuTLS</ulink>
582
627
        </term>
583
628
      <listitem>
584
629
        <para>
590
635
      </varlistentry>
591
636
      <varlistentry>
592
637
        <term>
593
 
          RFC 4291: <citetitle>IP Version 6 Addressing
594
 
          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>
595
641
        </term>
596
642
        <listitem>
597
 
          <variablelist>
598
 
            <varlistentry>
599
 
              <term>Section 2.2: <citetitle>Text Representation of
600
 
              Addresses</citetitle></term>
601
 
              <listitem><para/></listitem>
602
 
            </varlistentry>
603
 
            <varlistentry>
604
 
              <term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6
605
 
              Address</citetitle></term>
606
 
              <listitem><para/></listitem>
607
 
            </varlistentry>
608
 
            <varlistentry>
609
 
            <term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast
610
 
            Addresses</citetitle></term>
611
 
            <listitem>
612
 
              <para>
613
 
                The clients use IPv6 link-local addresses, which are
614
 
                immediately usable since a link-local addresses is
615
 
                automatically assigned to a network interfaces when it
616
 
                is brought up.
617
 
              </para>
618
 
            </listitem>
619
 
            </varlistentry>
620
 
          </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>
621
649
        </listitem>
622
650
      </varlistentry>
623
651
      <varlistentry>
624
652
        <term>
625
 
          RFC 4346: <citetitle>The Transport Layer Security (TLS)
626
 
          Protocol Version 1.1</citetitle>
 
653
          <citation>RFC 4346: <citetitle>The Transport Layer Security
 
654
          (TLS) Protocol Version 1.1</citetitle></citation>
627
655
        </term>
628
656
      <listitem>
629
657
        <para>
633
661
      </varlistentry>
634
662
      <varlistentry>
635
663
        <term>
636
 
          RFC 4880: <citetitle>OpenPGP Message Format</citetitle>
 
664
          <citation>RFC 4880: <citetitle>OpenPGP Message
 
665
          Format</citetitle></citation>
637
666
        </term>
638
667
      <listitem>
639
668
        <para>
643
672
      </varlistentry>
644
673
      <varlistentry>
645
674
        <term>
646
 
          RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer
647
 
          Security</citetitle>
 
675
          <citation>RFC 5081: <citetitle>Using OpenPGP Keys for
 
676
          Transport Layer Security</citetitle></citation>
648
677
        </term>
649
678
      <listitem>
650
679
        <para>
656
685
    </variablelist>
657
686
  </refsect1>
658
687
</refentry>
659
 
<!-- Local Variables: -->
660
 
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
661
 
<!-- time-stamp-end: "[\"']>" -->
662
 
<!-- time-stamp-format: "%:y-%02m-%02d" -->
663
 
<!-- End: -->