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