/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-19 13:25:14 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080819132514-wawrvgmfjovg9poj
* Makefile (DOCBOOKTOMAN): Added "--xinclude".

* mandos-options.xml: New file; moved mandos(8) option descriptions
                      here.

* mandos.conf.xml: Add XInclude namespace.
  (OPTIONS): New separate section with options from old "DESCRIPTION"
             section.  Changed all options to include a synopsis and
             include its paragraph from "mandos-options.xml".
  (FILES): Moved to before "EXAMPLES".
  (BUGS): New section.
  (EXAMPLES): Renamed to "EXAMPLE", as per man-pages(7).  Unindented
              example text.

* mandos.xml: Removed OVERVIEW entity.  Add XInclude namespace.
  (OPTIONS): Moved all descriptive paragraphs to "mandos-options.xml"
             and just <xi:include/> them from here.
  (OVERVIEW): Changed to do <xi:include/>.

* overview.xml: Added DOCTYPE; reportedly needed for XInclude to work.

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">
7
6
]>
8
7
 
9
8
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
10
9
  <refentryinfo>
11
 
    <title>Mandos Manual</title>
 
10
    <title>&COMMANDNAME;</title>
12
11
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
 
    <productname>Mandos</productname>
 
12
    <productname>&COMMANDNAME;</productname>
14
13
    <productnumber>&VERSION;</productnumber>
15
 
    <date>&TIMESTAMP;</date>
16
14
    <authorgroup>
17
15
      <author>
18
16
        <firstname>Björn</firstname>
67
65
  <refnamediv>
68
66
    <refname><command>&COMMANDNAME;</command></refname>
69
67
    <refpurpose>
70
 
      Gives encrypted passwords to authenticated Mandos clients
 
68
      Sends encrypted passwords to authenticated Mandos clients
71
69
    </refpurpose>
72
70
  </refnamediv>
73
71
 
74
72
  <refsynopsisdiv>
75
73
    <cmdsynopsis>
76
74
      <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>
 
75
      <arg>--interface<arg choice="plain">IF</arg></arg>
 
76
      <arg>--address<arg choice="plain">ADDRESS</arg></arg>
 
77
      <arg>--port<arg choice="plain">PORT</arg></arg>
 
78
      <arg>--priority<arg choice="plain">PRIORITY</arg></arg>
 
79
      <arg>--servicename<arg choice="plain">NAME</arg></arg>
 
80
      <arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>
 
81
      <arg>--debug</arg>
 
82
    </cmdsynopsis>
 
83
    <cmdsynopsis>
 
84
      <command>&COMMANDNAME;</command>
 
85
      <arg>-i<arg choice="plain">IF</arg></arg>
 
86
      <arg>-a<arg choice="plain">ADDRESS</arg></arg>
 
87
      <arg>-p<arg choice="plain">PORT</arg></arg>
 
88
      <arg>--priority<arg choice="plain">PRIORITY</arg></arg>
 
89
      <arg>--servicename<arg choice="plain">NAME</arg></arg>
 
90
      <arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>
 
91
      <arg>--debug</arg>
108
92
    </cmdsynopsis>
109
93
    <cmdsynopsis>
110
94
      <command>&COMMANDNAME;</command>
111
95
      <group choice="req">
112
 
        <arg choice="plain"><option>--help</option></arg>
113
 
        <arg choice="plain"><option>-h</option></arg>
 
96
        <arg choice="plain">-h</arg>
 
97
        <arg choice="plain">--help</arg>
114
98
      </group>
115
99
    </cmdsynopsis>
116
100
    <cmdsynopsis>
117
101
      <command>&COMMANDNAME;</command>
118
 
      <arg choice="plain"><option>--version</option></arg>
 
102
      <arg choice="plain">--version</arg>
119
103
    </cmdsynopsis>
120
104
    <cmdsynopsis>
121
105
      <command>&COMMANDNAME;</command>
122
 
      <arg choice="plain"><option>--check</option></arg>
 
106
      <arg choice="plain">--check</arg>
123
107
    </cmdsynopsis>
124
108
  </refsynopsisdiv>
125
109
 
149
133
      <emphasis>encrypted root file system</emphasis>.  See <xref
150
134
      linkend="overview"/> for details.
151
135
    </para>
152
 
    
 
136
 
153
137
  </refsect1>
154
138
  
155
139
  <refsect1 id="options">
156
140
    <title>OPTIONS</title>
157
 
    
 
141
 
158
142
    <variablelist>
159
143
      <varlistentry>
160
 
        <term><option>--help</option></term>
161
 
        <term><option>-h</option></term>
 
144
        <term><literal>-h</literal>, <literal>--help</literal></term>
162
145
        <listitem>
163
146
          <para>
164
147
            Show a help message and exit
165
148
          </para>
166
149
        </listitem>
167
150
      </varlistentry>
168
 
      
 
151
 
169
152
      <varlistentry>
170
 
        <term><option>--interface</option>
171
 
        <replaceable>NAME</replaceable></term>
172
 
        <term><option>-i</option>
173
 
        <replaceable>NAME</replaceable></term>
 
153
        <term><literal>-i</literal>, <literal>--interface <replaceable>
 
154
        IF</replaceable></literal></term>
174
155
        <listitem>
175
156
          <xi:include href="mandos-options.xml" xpointer="interface"/>
176
157
        </listitem>
177
158
      </varlistentry>
178
 
      
 
159
 
179
160
      <varlistentry>
180
 
        <term><option>--address
181
 
        <replaceable>ADDRESS</replaceable></option></term>
182
 
        <term><option>-a
183
 
        <replaceable>ADDRESS</replaceable></option></term>
 
161
        <term><literal>-a</literal>, <literal>--address <replaceable>
 
162
        ADDRESS</replaceable></literal></term>
184
163
        <listitem>
185
164
          <xi:include href="mandos-options.xml" xpointer="address"/>
186
165
        </listitem>
187
166
      </varlistentry>
188
 
      
 
167
 
189
168
      <varlistentry>
190
 
        <term><option>--port
191
 
        <replaceable>PORT</replaceable></option></term>
192
 
        <term><option>-p
193
 
        <replaceable>PORT</replaceable></option></term>
 
169
        <term><literal>-p</literal>, <literal>--port <replaceable>
 
170
        PORT</replaceable></literal></term>
194
171
        <listitem>
195
172
          <xi:include href="mandos-options.xml" xpointer="port"/>
196
173
        </listitem>
197
174
      </varlistentry>
198
 
      
 
175
 
199
176
      <varlistentry>
200
 
        <term><option>--check</option></term>
 
177
        <term><literal>--check</literal></term>
201
178
        <listitem>
202
179
          <para>
203
180
            Run the server’s self-tests.  This includes any unit
205
182
          </para>
206
183
        </listitem>
207
184
      </varlistentry>
208
 
      
 
185
 
209
186
      <varlistentry>
210
 
        <term><option>--debug</option></term>
 
187
        <term><literal>--debug</literal></term>
211
188
        <listitem>
212
189
          <xi:include href="mandos-options.xml" xpointer="debug"/>
213
190
        </listitem>
214
191
      </varlistentry>
215
192
 
216
193
      <varlistentry>
217
 
        <term><option>--priority <replaceable>
218
 
        PRIORITY</replaceable></option></term>
 
194
        <term><literal>--priority <replaceable>
 
195
        PRIORITY</replaceable></literal></term>
219
196
        <listitem>
220
197
          <xi:include href="mandos-options.xml" xpointer="priority"/>
221
198
        </listitem>
222
199
      </varlistentry>
223
200
 
224
201
      <varlistentry>
225
 
        <term><option>--servicename
226
 
        <replaceable>NAME</replaceable></option></term>
 
202
        <term><literal>--servicename <replaceable>NAME</replaceable>
 
203
        </literal></term>
227
204
        <listitem>
228
205
          <xi:include href="mandos-options.xml"
229
206
                      xpointer="servicename"/>
231
208
      </varlistentry>
232
209
 
233
210
      <varlistentry>
234
 
        <term><option>--configdir
235
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
211
        <term><literal>--configdir <replaceable>DIR</replaceable>
 
212
        </literal></term>
236
213
        <listitem>
237
214
          <para>
238
215
            Directory to search for configuration files.  Default is
246
223
      </varlistentry>
247
224
 
248
225
      <varlistentry>
249
 
        <term><option>--version</option></term>
 
226
        <term><literal>--version</literal></term>
250
227
        <listitem>
251
228
          <para>
252
229
            Prints the program version and exit.
297
274
        <entry>-><!-- &rarr; --></entry>
298
275
      </row>
299
276
      <row>
300
 
        <entry><quote><literal>1\r\n</literal></quote></entry>
 
277
        <entry><quote><literal>1\r\en</literal></quote></entry>
301
278
        <entry>-><!-- &rarr; --></entry>
302
279
      </row>
303
280
      <row>
333
310
      longer eligible to receive the encrypted password.  The timeout,
334
311
      checker program, and interval between checks can be configured
335
312
      both globally and per client; see <citerefentry>
 
313
      <refentrytitle>mandos.conf</refentrytitle>
 
314
      <manvolnum>5</manvolnum></citerefentry> and <citerefentry>
336
315
      <refentrytitle>mandos-clients.conf</refentrytitle>
337
316
      <manvolnum>5</manvolnum></citerefentry>.
338
317
    </para>
341
320
  <refsect1 id="logging">
342
321
    <title>LOGGING</title>
343
322
    <para>
344
 
      The server will send log message with various severity levels to
345
 
      <filename>/dev/log</filename>.  With the
 
323
      The server will send log messaged with various severity levels
 
324
      to <filename>/dev/log</filename>.  With the
346
325
      <option>--debug</option> option, it will log even more messages,
347
326
      and also show them on the console.
348
327
    </para>
360
339
    <title>ENVIRONMENT</title>
361
340
    <variablelist>
362
341
      <varlistentry>
363
 
        <term><envar>PATH</envar></term>
 
342
        <term><varname>PATH</varname></term>
364
343
        <listitem>
365
344
          <para>
366
345
            To start the configured checker (see <xref
369
348
            <varname>PATH</varname> to search for matching commands if
370
349
            an absolute path is not given.  See <citerefentry>
371
350
            <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
372
 
            </citerefentry>.
 
351
          </citerefentry>
373
352
          </para>
374
353
        </listitem>
375
354
      </varlistentry>
471
450
        Normal invocation needs no options:
472
451
      </para>
473
452
      <para>
474
 
        <userinput>&COMMANDNAME;</userinput>
 
453
        <userinput>mandos</userinput>
475
454
      </para>
476
455
    </informalexample>
477
456
    <informalexample>
484
463
      <para>
485
464
 
486
465
<!-- do not wrap this line -->
487
 
<userinput>&COMMANDNAME; --debug --configdir ~/mandos --servicename Test</userinput>
 
466
<userinput>mandos --debug --configdir ~/mandos --servicename Test</userinput>
488
467
 
489
468
      </para>
490
469
    </informalexample>
496
475
      <para>
497
476
 
498
477
<!-- do not wrap this line -->
499
 
<userinput>&COMMANDNAME; --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>
 
478
<userinput>mandos --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>
500
479
 
501
480
      </para>
502
481
    </informalexample>
559
538
 
560
539
  <refsect1 id="see_also">
561
540
    <title>SEE ALSO</title>
562
 
    <para>
563
 
      <citerefentry>
564
 
        <refentrytitle>mandos-clients.conf</refentrytitle>
565
 
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
566
 
        <refentrytitle>mandos.conf</refentrytitle>
567
 
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
568
 
        <refentrytitle>password-request</refentrytitle>
569
 
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
570
 
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
571
 
      </citerefentry>
572
 
    </para>
573
541
    <variablelist>
574
542
      <varlistentry>
575
543
        <term>
 
544
          <citerefentry>
 
545
            <refentrytitle>password-request</refentrytitle>
 
546
            <manvolnum>8mandos</manvolnum>
 
547
          </citerefentry>
 
548
        </term>
 
549
        <listitem>
 
550
          <para>
 
551
            This is the actual program which talks to this server.
 
552
            Note that it is normally not invoked directly, and is only
 
553
            run in the initial RAM disk environment, and not on a
 
554
            fully started system.
 
555
          </para>
 
556
        </listitem>
 
557
      </varlistentry>
 
558
      <varlistentry>
 
559
        <term>
576
560
          <ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
577
561
        </term>
578
562
        <listitem>
595
579
      </varlistentry>
596
580
      <varlistentry>
597
581
        <term>
598
 
          <ulink url="http://www.gnu.org/software/gnutls/"
599
 
          >GnuTLS</ulink>
 
582
          <ulink
 
583
              url="http://www.gnu.org/software/gnutls/">GnuTLS</ulink>
600
584
        </term>
601
585
      <listitem>
602
586
        <para>
608
592
      </varlistentry>
609
593
      <varlistentry>
610
594
        <term>
611
 
          RFC 4291: <citetitle>IP Version 6 Addressing
612
 
          Architecture</citetitle>
 
595
          <citation>RFC 4291: <citetitle>IP Version 6 Addressing
 
596
          Architecture</citetitle>, section 2.5.6, Link-Local IPv6
 
597
          Unicast Addresses</citation>
613
598
        </term>
614
599
        <listitem>
615
 
          <variablelist>
616
 
            <varlistentry>
617
 
              <term>Section 2.2: <citetitle>Text Representation of
618
 
              Addresses</citetitle></term>
619
 
              <listitem><para/></listitem>
620
 
            </varlistentry>
621
 
            <varlistentry>
622
 
              <term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6
623
 
              Address</citetitle></term>
624
 
              <listitem><para/></listitem>
625
 
            </varlistentry>
626
 
            <varlistentry>
627
 
            <term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast
628
 
            Addresses</citetitle></term>
629
 
            <listitem>
630
 
              <para>
631
 
                The clients use IPv6 link-local addresses, which are
632
 
                immediately usable since a link-local addresses is
633
 
                automatically assigned to a network interfaces when it
634
 
                is brought up.
635
 
              </para>
636
 
            </listitem>
637
 
            </varlistentry>
638
 
          </variablelist>
 
600
          <para>
 
601
            The clients use IPv6 link-local addresses, which are
 
602
            immediately usable since a link-local addresses is
 
603
            automatically assigned to a network interfaces when it is
 
604
            brought up.
 
605
          </para>
639
606
        </listitem>
640
607
      </varlistentry>
641
608
      <varlistentry>
642
609
        <term>
643
 
          RFC 4346: <citetitle>The Transport Layer Security (TLS)
644
 
          Protocol Version 1.1</citetitle>
 
610
          <citation>RFC 4346: <citetitle>The Transport Layer Security
 
611
          (TLS) Protocol Version 1.1</citetitle></citation>
645
612
        </term>
646
613
      <listitem>
647
614
        <para>
651
618
      </varlistentry>
652
619
      <varlistentry>
653
620
        <term>
654
 
          RFC 4880: <citetitle>OpenPGP Message Format</citetitle>
 
621
          <citation>RFC 4880: <citetitle>OpenPGP Message
 
622
          Format</citetitle></citation>
655
623
        </term>
656
624
      <listitem>
657
625
        <para>
661
629
      </varlistentry>
662
630
      <varlistentry>
663
631
        <term>
664
 
          RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer
665
 
          Security</citetitle>
 
632
          <citation>RFC 5081: <citetitle>Using OpenPGP Keys for
 
633
          Transport Layer Security</citetitle></citation>
666
634
        </term>
667
635
      <listitem>
668
636
        <para>
674
642
    </variablelist>
675
643
  </refsect1>
676
644
</refentry>
677
 
<!-- Local Variables: -->
678
 
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
679
 
<!-- time-stamp-end: "[\"']>" -->
680
 
<!-- time-stamp-format: "%:y-%02m-%02d" -->
681
 
<!-- End: -->