/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-keygen.xml

  • Committer: Teddy Hogeborn
  • Date: 2008-08-30 19:05:15 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080830190515-l7e6vu81yyw5kcku
* mandos.xml (SYNOPSIS): Use <option> and <replaceable> tags.  Unify
                         short and long options.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos-keygen.xml
1
1
<?xml version="1.0" encoding="UTF-8"?>
2
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
3
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
 
4
<!ENTITY VERSION "1.0">
4
5
<!ENTITY COMMANDNAME "mandos-keygen">
5
 
<!ENTITY TIMESTAMP "2008-10-03">
6
 
<!ENTITY % common SYSTEM "common.ent">
7
 
%common;
 
6
<!ENTITY TIMESTAMP "2008-08-30">
8
7
]>
9
8
 
10
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
12
11
    <title>Mandos Manual</title>
13
12
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
14
13
    <productname>Mandos</productname>
15
 
    <productnumber>&version;</productnumber>
 
14
    <productnumber>&VERSION;</productnumber>
16
15
    <date>&TIMESTAMP;</date>
17
16
    <authorgroup>
18
17
      <author>
35
34
      <holder>Teddy Hogeborn</holder>
36
35
      <holder>Björn Påhlsson</holder>
37
36
    </copyright>
38
 
    <xi:include href="legalnotice.xml"/>
 
37
    <legalnotice>
 
38
      <para>
 
39
        This manual page is free software: you can redistribute it
 
40
        and/or modify it under the terms of the GNU General Public
 
41
        License as published by the Free Software Foundation,
 
42
        either version 3 of the License, or (at your option) any
 
43
        later version.
 
44
      </para>
 
45
 
 
46
      <para>
 
47
        This manual page is distributed in the hope that it will
 
48
        be useful, but WITHOUT ANY WARRANTY; without even the
 
49
        implied warranty of MERCHANTABILITY or FITNESS FOR A
 
50
        PARTICULAR PURPOSE.  See the GNU General Public License
 
51
        for more details.
 
52
      </para>
 
53
 
 
54
      <para>
 
55
        You should have received a copy of the GNU General Public
 
56
        License along with this program; If not, see
 
57
        <ulink url="http://www.gnu.org/licenses/"/>.
 
58
      </para>
 
59
    </legalnotice>
39
60
  </refentryinfo>
40
 
  
 
61
 
41
62
  <refmeta>
42
63
    <refentrytitle>&COMMANDNAME;</refentrytitle>
43
64
    <manvolnum>8</manvolnum>
46
67
  <refnamediv>
47
68
    <refname><command>&COMMANDNAME;</command></refname>
48
69
    <refpurpose>
49
 
      Generate key and password for Mandos client and server.
 
70
      Generate keys for <citerefentry><refentrytitle>password-request
 
71
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
50
72
    </refpurpose>
51
73
  </refnamediv>
52
 
  
 
74
 
53
75
  <refsynopsisdiv>
54
76
    <cmdsynopsis>
55
77
      <command>&COMMANDNAME;</command>
121
143
    <cmdsynopsis>
122
144
      <command>&COMMANDNAME;</command>
123
145
      <group choice="req">
 
146
        <arg choice="plain"><option>-p</option></arg>
124
147
        <arg choice="plain"><option>--password</option></arg>
125
 
        <arg choice="plain"><option>-p</option></arg>
126
 
        <arg choice="plain"><option>--passfile
127
 
        <replaceable>FILE</replaceable></option></arg>
128
 
        <arg choice="plain"><option>-F</option>
129
 
        <replaceable>FILE</replaceable></arg>
130
148
      </group>
131
149
      <sbr/>
132
150
      <group>
146
164
    <cmdsynopsis>
147
165
      <command>&COMMANDNAME;</command>
148
166
      <group choice="req">
 
167
        <arg choice="plain"><option>-h</option></arg>
149
168
        <arg choice="plain"><option>--help</option></arg>
150
 
        <arg choice="plain"><option>-h</option></arg>
151
169
      </group>
152
170
    </cmdsynopsis>
153
171
    <cmdsynopsis>
154
172
      <command>&COMMANDNAME;</command>
155
173
      <group choice="req">
 
174
        <arg choice="plain"><option>-v</option></arg>
156
175
        <arg choice="plain"><option>--version</option></arg>
157
 
        <arg choice="plain"><option>-v</option></arg>
158
176
      </group>
159
177
    </cmdsynopsis>
160
178
  </refsynopsisdiv>
161
 
  
 
179
 
162
180
  <refsect1 id="description">
163
181
    <title>DESCRIPTION</title>
164
182
    <para>
165
183
      <command>&COMMANDNAME;</command> is a program to generate the
166
 
      OpenPGP key used by
167
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
168
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
 
184
      OpenPGP keys used by
 
185
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
186
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
169
187
      normally written to /etc/mandos for later installation into the
170
 
      initrd image, but this, and most other things, can be changed
171
 
      with command line options.
 
188
      initrd image, but this, like most things, can be changed with
 
189
      command line options.
172
190
    </para>
173
191
    <para>
174
 
      This program can also be used with the
175
 
      <option>--password</option> or <option>--passfile</option>
176
 
      options to generate a ready-made section for
177
 
      <filename>clients.conf</filename> (see
 
192
      It can also be used to generate ready-made sections for
178
193
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
179
 
      <manvolnum>5</manvolnum></citerefentry>).
 
194
      <manvolnum>5</manvolnum></citerefentry> using the
 
195
      <option>--password</option> option.
180
196
    </para>
181
197
  </refsect1>
182
198
  
183
199
  <refsect1 id="purpose">
184
200
    <title>PURPOSE</title>
 
201
 
185
202
    <para>
186
203
      The purpose of this is to enable <emphasis>remote and unattended
187
204
      rebooting</emphasis> of client host computer with an
188
205
      <emphasis>encrypted root file system</emphasis>.  See <xref
189
206
      linkend="overview"/> for details.
190
207
    </para>
 
208
 
191
209
  </refsect1>
192
210
  
193
211
  <refsect1 id="options">
194
212
    <title>OPTIONS</title>
195
 
    
 
213
 
196
214
    <variablelist>
197
215
      <varlistentry>
198
 
        <term><option>--help</option></term>
199
 
        <term><option>-h</option></term>
 
216
        <term><literal>-h</literal>, <literal>--help</literal></term>
200
217
        <listitem>
201
218
          <para>
202
219
            Show a help message and exit
203
220
          </para>
204
221
        </listitem>
205
222
      </varlistentry>
206
 
      
 
223
 
207
224
      <varlistentry>
208
 
        <term><option>--dir
209
 
        <replaceable>DIRECTORY</replaceable></option></term>
210
 
        <term><option>-d
211
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
225
        <term><literal>-d</literal>, <literal>--dir
 
226
        <replaceable>directory</replaceable></literal></term>
212
227
        <listitem>
213
228
          <para>
214
229
            Target directory for key files.  Default is
216
231
          </para>
217
232
        </listitem>
218
233
      </varlistentry>
219
 
      
 
234
 
220
235
      <varlistentry>
221
 
        <term><option>--type
222
 
        <replaceable>TYPE</replaceable></option></term>
223
 
        <term><option>-t
224
 
        <replaceable>TYPE</replaceable></option></term>
 
236
        <term><literal>-t</literal>, <literal>--type
 
237
        <replaceable>type</replaceable></literal></term>
225
238
        <listitem>
226
239
          <para>
227
240
            Key type.  Default is <quote>DSA</quote>.
228
241
          </para>
229
242
        </listitem>
230
243
      </varlistentry>
231
 
      
 
244
 
232
245
      <varlistentry>
233
 
        <term><option>--length
234
 
        <replaceable>BITS</replaceable></option></term>
235
 
        <term><option>-l
236
 
        <replaceable>BITS</replaceable></option></term>
 
246
        <term><literal>-l</literal>, <literal>--length
 
247
        <replaceable>bits</replaceable></literal></term>
237
248
        <listitem>
238
249
          <para>
239
250
            Key length in bits.  Default is 2048.
240
251
          </para>
241
252
        </listitem>
242
253
      </varlistentry>
243
 
      
 
254
 
244
255
      <varlistentry>
245
 
        <term><option>--subtype
246
 
        <replaceable>KEYTYPE</replaceable></option></term>
247
 
        <term><option>-s
248
 
        <replaceable>KEYTYPE</replaceable></option></term>
 
256
        <term><literal>-s</literal>, <literal>--subtype
 
257
        <replaceable>type</replaceable></literal></term>
249
258
        <listitem>
250
259
          <para>
251
260
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
253
262
          </para>
254
263
        </listitem>
255
264
      </varlistentry>
256
 
      
 
265
 
257
266
      <varlistentry>
258
 
        <term><option>--sublength
259
 
        <replaceable>BITS</replaceable></option></term>
260
 
        <term><option>-L
261
 
        <replaceable>BITS</replaceable></option></term>
 
267
        <term><literal>-L</literal>, <literal>--sublength
 
268
        <replaceable>bits</replaceable></literal></term>
262
269
        <listitem>
263
270
          <para>
264
271
            Subkey length in bits.  Default is 2048.
265
272
          </para>
266
273
        </listitem>
267
274
      </varlistentry>
268
 
      
 
275
 
269
276
      <varlistentry>
270
 
        <term><option>--email
271
 
        <replaceable>ADDRESS</replaceable></option></term>
272
 
        <term><option>-e
273
 
        <replaceable>ADDRESS</replaceable></option></term>
 
277
        <term><literal>-e</literal>, <literal>--email</literal>
 
278
        <replaceable>address</replaceable></term>
274
279
        <listitem>
275
280
          <para>
276
281
            Email address of key.  Default is empty.
277
282
          </para>
278
283
        </listitem>
279
284
      </varlistentry>
280
 
      
 
285
 
281
286
      <varlistentry>
282
 
        <term><option>--comment
283
 
        <replaceable>TEXT</replaceable></option></term>
284
 
        <term><option>-c
285
 
        <replaceable>TEXT</replaceable></option></term>
 
287
        <term><literal>-c</literal>, <literal>--comment</literal>
 
288
        <replaceable>comment</replaceable></term>
286
289
        <listitem>
287
290
          <para>
288
291
            Comment field for key.  The default value is
290
293
          </para>
291
294
        </listitem>
292
295
      </varlistentry>
293
 
      
 
296
 
294
297
      <varlistentry>
295
 
        <term><option>--expire
296
 
        <replaceable>TIME</replaceable></option></term>
297
 
        <term><option>-x
298
 
        <replaceable>TIME</replaceable></option></term>
 
298
        <term><literal>-x</literal>, <literal>--expire</literal>
 
299
        <replaceable>time</replaceable></term>
299
300
        <listitem>
300
301
          <para>
301
302
            Key expire time.  Default is no expiration.  See
304
305
          </para>
305
306
        </listitem>
306
307
      </varlistentry>
307
 
      
 
308
 
308
309
      <varlistentry>
309
 
        <term><option>--force</option></term>
310
 
        <term><option>-f</option></term>
 
310
        <term><literal>-f</literal>, <literal>--force</literal></term>
311
311
        <listitem>
312
312
          <para>
313
 
            Force overwriting old key.
 
313
            Force overwriting old keys.
314
314
          </para>
315
315
        </listitem>
316
316
      </varlistentry>
317
317
      <varlistentry>
318
 
        <term><option>--password</option></term>
319
 
        <term><option>-p</option></term>
 
318
        <term><literal>-p</literal>, <literal>--password</literal
 
319
        ></term>
320
320
        <listitem>
321
321
          <para>
322
322
            Prompt for a password and encrypt it with the key already
328
328
            >8</manvolnum></citerefentry>.  The host name or the name
329
329
            specified with the <option>--name</option> option is used
330
330
            for the section header.  All other options are ignored,
331
 
            and no key is created.
332
 
          </para>
333
 
        </listitem>
334
 
      </varlistentry>
335
 
      <varlistentry>
336
 
        <term><option>--passfile
337
 
        <replaceable>FILE</replaceable></option></term>
338
 
        <term><option>-F
339
 
        <replaceable>FILE</replaceable></option></term>
340
 
        <listitem>
341
 
          <para>
342
 
            The same as <option>--password</option>, but read from
343
 
            <replaceable>FILE</replaceable>, not the terminal.
 
331
            and no keys are created.
344
332
          </para>
345
333
        </listitem>
346
334
      </varlistentry>
347
335
    </variablelist>
348
336
  </refsect1>
349
 
  
 
337
 
350
338
  <refsect1 id="overview">
351
339
    <title>OVERVIEW</title>
352
340
    <xi:include href="overview.xml"/>
353
341
    <para>
354
342
      This program is a small utility to generate new OpenPGP keys for
355
 
      new Mandos clients, and to generate sections for inclusion in
356
 
      <filename>clients.conf</filename> on the server.
 
343
      new Mandos clients.
357
344
    </para>
358
345
  </refsect1>
359
 
  
 
346
 
360
347
  <refsect1 id="exit_status">
361
348
    <title>EXIT STATUS</title>
362
349
    <para>
363
 
      The exit status will be 0 if a new key (or password, if the
364
 
      <option>--password</option> option was used) was successfully
365
 
      created, otherwise not.
 
350
      The exit status will be 0 if new keys were successfully created,
 
351
      otherwise not.
366
352
    </para>
367
353
  </refsect1>
368
354
  
382
368
    </variablelist>
383
369
  </refsect1>
384
370
  
385
 
  <refsect1 id="files">
 
371
  <refsect1 id="file">
386
372
    <title>FILES</title>
387
373
    <para>
388
374
      Use the <option>--dir</option> option to change where
419
405
      </varlistentry>
420
406
    </variablelist>
421
407
  </refsect1>
422
 
  
423
 
<!--   <refsect1 id="bugs"> -->
424
 
<!--     <title>BUGS</title> -->
425
 
<!--     <para> -->
426
 
<!--     </para> -->
427
 
<!--   </refsect1> -->
428
 
  
 
408
 
 
409
  <refsect1 id="bugs">
 
410
    <title>BUGS</title>
 
411
    <para>
 
412
      None are known at this time.
 
413
    </para>
 
414
  </refsect1>
 
415
 
429
416
  <refsect1 id="example">
430
417
    <title>EXAMPLE</title>
431
418
    <informalexample>
438
425
    </informalexample>
439
426
    <informalexample>
440
427
      <para>
441
 
        Create key in another directory and of another type.  Force
 
428
        Create keys in another directory and of another type.  Force
442
429
        overwriting old key files:
443
430
      </para>
444
431
      <para>
448
435
 
449
436
      </para>
450
437
    </informalexample>
451
 
    <informalexample>
452
 
      <para>
453
 
        Prompt for a password, encrypt it with the key in
454
 
        <filename>/etc/mandos</filename> and output a section suitable
455
 
        for <filename>clients.conf</filename>.
456
 
      </para>
457
 
      <para>
458
 
        <userinput>&COMMANDNAME; --password</userinput>
459
 
      </para>
460
 
    </informalexample>
461
 
    <informalexample>
462
 
      <para>
463
 
        Prompt for a password, encrypt it with the key in the
464
 
        <filename>client-key</filename> directory and output a section
465
 
        suitable for <filename>clients.conf</filename>.
466
 
      </para>
467
 
      <para>
468
 
 
469
 
<!-- do not wrap this line -->
470
 
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
471
 
 
472
 
      </para>
473
 
    </informalexample>
474
438
  </refsect1>
475
 
  
 
439
 
476
440
  <refsect1 id="security">
477
441
    <title>SECURITY</title>
478
442
    <para>
479
443
      The <option>--type</option>, <option>--length</option>,
480
444
      <option>--subtype</option>, and <option>--sublength</option>
481
 
      options can be used to create keys of low security.  If in
482
 
      doubt, leave them to the default values.
 
445
      options can be used to create keys of insufficient security.  If
 
446
      in doubt, leave them to the default values.
483
447
    </para>
484
448
    <para>
485
 
      The key expire time is <emphasis>not</emphasis> guaranteed to be
486
 
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
 
449
      The key expire time is not guaranteed to be honored by
 
450
      <citerefentry><refentrytitle>mandos</refentrytitle>
487
451
      <manvolnum>8</manvolnum></citerefentry>.
488
452
    </para>
489
453
  </refsect1>
490
 
  
 
454
 
491
455
  <refsect1 id="see_also">
492
456
    <title>SEE ALSO</title>
493
457
    <para>
494
458
      <citerefentry><refentrytitle>gpg</refentrytitle>
495
459
      <manvolnum>1</manvolnum></citerefentry>,
496
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
497
 
      <manvolnum>5</manvolnum></citerefentry>,
498
460
      <citerefentry><refentrytitle>mandos</refentrytitle>
499
461
      <manvolnum>8</manvolnum></citerefentry>,
500
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
462
      <citerefentry><refentrytitle>password-request</refentrytitle>
501
463
      <manvolnum>8mandos</manvolnum></citerefentry>
502
464
    </para>
503
465
  </refsect1>