/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-31 08:47:38 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080831084738-uu70kayyt876982d
* mandos-keygen: Minor help text change.

* mandos-keygen.xml: Changed plural "keys" to singular "key"
                     throughout.
  (NAME): Improved wording.
  (DESCRIPTION): Improved wording.
  (OPTIONS): Split options in <term> tags into separate <term> tags.
             Use <option> tags.  Move long options before short
             options.  Uppercase replaceables.
  (OVERVIEW): Improved wording.
  (EXIT STATUS): Also cover --password option.
  (EXAMPLE): Add two examples using the --password option.
  (SECURITY): Improved wording.

* overview.xml: Improved wording.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos-keygen.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-keygen">
6
 
<!ENTITY TIMESTAMP "2008-08-30">
 
6
<!ENTITY TIMESTAMP "2008-08-31">
7
7
]>
8
8
 
9
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
67
67
  <refnamediv>
68
68
    <refname><command>&COMMANDNAME;</command></refname>
69
69
    <refpurpose>
70
 
      Generate keys for <citerefentry><refentrytitle>password-request
71
 
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
 
70
      Generate key and password for Mandos client and server.
72
71
    </refpurpose>
73
72
  </refnamediv>
74
73
 
143
142
    <cmdsynopsis>
144
143
      <command>&COMMANDNAME;</command>
145
144
      <group choice="req">
 
145
        <arg choice="plain"><option>--password</option></arg>
146
146
        <arg choice="plain"><option>-p</option></arg>
147
 
        <arg choice="plain"><option>--password</option></arg>
148
147
      </group>
149
148
      <sbr/>
150
149
      <group>
164
163
    <cmdsynopsis>
165
164
      <command>&COMMANDNAME;</command>
166
165
      <group choice="req">
 
166
        <arg choice="plain"><option>--help</option></arg>
167
167
        <arg choice="plain"><option>-h</option></arg>
168
 
        <arg choice="plain"><option>--help</option></arg>
169
168
      </group>
170
169
    </cmdsynopsis>
171
170
    <cmdsynopsis>
172
171
      <command>&COMMANDNAME;</command>
173
172
      <group choice="req">
 
173
        <arg choice="plain"><option>--version</option></arg>
174
174
        <arg choice="plain"><option>-v</option></arg>
175
 
        <arg choice="plain"><option>--version</option></arg>
176
175
      </group>
177
176
    </cmdsynopsis>
178
177
  </refsynopsisdiv>
179
 
 
 
178
  
180
179
  <refsect1 id="description">
181
180
    <title>DESCRIPTION</title>
182
181
    <para>
183
182
      <command>&COMMANDNAME;</command> is a program to generate the
184
 
      OpenPGP keys used by
 
183
      OpenPGP key used by
185
184
      <citerefentry><refentrytitle>password-request</refentrytitle>
186
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
 
185
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
187
186
      normally written to /etc/mandos for later installation into the
188
 
      initrd image, but this, like most things, can be changed with
189
 
      command line options.
 
187
      initrd image, but this, and most other things, can be changed
 
188
      with command line options.
190
189
    </para>
191
190
    <para>
192
 
      It can also be used to generate ready-made sections for
 
191
      This program can also be used with the
 
192
      <option>--password</option> option to generate a ready-made
 
193
      section for <filename>clients.conf</filename> (see
193
194
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
194
 
      <manvolnum>5</manvolnum></citerefentry> using the
195
 
      <option>--password</option> option.
 
195
      <manvolnum>5</manvolnum></citerefentry>).
196
196
    </para>
197
197
  </refsect1>
198
198
  
199
199
  <refsect1 id="purpose">
200
200
    <title>PURPOSE</title>
201
 
 
202
201
    <para>
203
202
      The purpose of this is to enable <emphasis>remote and unattended
204
203
      rebooting</emphasis> of client host computer with an
205
204
      <emphasis>encrypted root file system</emphasis>.  See <xref
206
205
      linkend="overview"/> for details.
207
206
    </para>
208
 
 
209
207
  </refsect1>
210
208
  
211
209
  <refsect1 id="options">
212
210
    <title>OPTIONS</title>
213
 
 
 
211
    
214
212
    <variablelist>
215
213
      <varlistentry>
216
 
        <term><literal>-h</literal>, <literal>--help</literal></term>
 
214
        <term><option>--help</option></term>
 
215
        <term><option>-h</option></term>
217
216
        <listitem>
218
217
          <para>
219
218
            Show a help message and exit
222
221
      </varlistentry>
223
222
 
224
223
      <varlistentry>
225
 
        <term><literal>-d</literal>, <literal>--dir
226
 
        <replaceable>directory</replaceable></literal></term>
 
224
        <term><option>--dir
 
225
        <replaceable>DIRECTORY</replaceable></option></term>
 
226
        <term><option>-d
 
227
        <replaceable>DIRECTORY</replaceable></option></term>
227
228
        <listitem>
228
229
          <para>
229
230
            Target directory for key files.  Default is
233
234
      </varlistentry>
234
235
 
235
236
      <varlistentry>
236
 
        <term><literal>-t</literal>, <literal>--type
237
 
        <replaceable>type</replaceable></literal></term>
 
237
        <term><option>--type
 
238
        <replaceable>TYPE</replaceable></option></term>
 
239
        <term><option>-t
 
240
        <replaceable>TYPE</replaceable></option></term>
238
241
        <listitem>
239
242
          <para>
240
243
            Key type.  Default is <quote>DSA</quote>.
243
246
      </varlistentry>
244
247
 
245
248
      <varlistentry>
246
 
        <term><literal>-l</literal>, <literal>--length
247
 
        <replaceable>bits</replaceable></literal></term>
 
249
        <term><option>--length
 
250
        <replaceable>BITS</replaceable></option></term>
 
251
        <term><option>-l
 
252
        <replaceable>BITS</replaceable></option></term>
248
253
        <listitem>
249
254
          <para>
250
255
            Key length in bits.  Default is 2048.
253
258
      </varlistentry>
254
259
 
255
260
      <varlistentry>
256
 
        <term><literal>-s</literal>, <literal>--subtype
257
 
        <replaceable>type</replaceable></literal></term>
 
261
        <term><option>--subtype
 
262
        <replaceable>KEYTYPE</replaceable></option></term>
 
263
        <term><option>-s
 
264
        <replaceable>KEYTYPE</replaceable></option></term>
258
265
        <listitem>
259
266
          <para>
260
267
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
264
271
      </varlistentry>
265
272
 
266
273
      <varlistentry>
267
 
        <term><literal>-L</literal>, <literal>--sublength
268
 
        <replaceable>bits</replaceable></literal></term>
 
274
        <term><option>--sublength
 
275
        <replaceable>BITS</replaceable></option></term>
 
276
        <term><option>-L
 
277
        <replaceable>BITS</replaceable></option></term>
269
278
        <listitem>
270
279
          <para>
271
280
            Subkey length in bits.  Default is 2048.
274
283
      </varlistentry>
275
284
 
276
285
      <varlistentry>
277
 
        <term><literal>-e</literal>, <literal>--email</literal>
278
 
        <replaceable>address</replaceable></term>
 
286
        <term><option>--email
 
287
        <replaceable>ADDRESS</replaceable></option></term>
 
288
        <term><option>-e
 
289
        <replaceable>ADDRESS</replaceable></option></term>
279
290
        <listitem>
280
291
          <para>
281
292
            Email address of key.  Default is empty.
284
295
      </varlistentry>
285
296
 
286
297
      <varlistentry>
287
 
        <term><literal>-c</literal>, <literal>--comment</literal>
288
 
        <replaceable>comment</replaceable></term>
 
298
        <term><option>--comment
 
299
        <replaceable>TEXT</replaceable></option></term>
 
300
        <term><option>-c
 
301
        <replaceable>TEXT</replaceable></option></term>
289
302
        <listitem>
290
303
          <para>
291
304
            Comment field for key.  The default value is
295
308
      </varlistentry>
296
309
 
297
310
      <varlistentry>
298
 
        <term><literal>-x</literal>, <literal>--expire</literal>
299
 
        <replaceable>time</replaceable></term>
 
311
        <term><option>--expire
 
312
        <replaceable>TIME</replaceable></option></term>
 
313
        <term><option>-x
 
314
        <replaceable>TIME</replaceable></option></term>
300
315
        <listitem>
301
316
          <para>
302
317
            Key expire time.  Default is no expiration.  See
307
322
      </varlistentry>
308
323
 
309
324
      <varlistentry>
310
 
        <term><literal>-f</literal>, <literal>--force</literal></term>
 
325
        <term><option>--force</option></term>
 
326
        <term><option>-f</option></term>
311
327
        <listitem>
312
328
          <para>
313
 
            Force overwriting old keys.
 
329
            Force overwriting old key.
314
330
          </para>
315
331
        </listitem>
316
332
      </varlistentry>
317
333
      <varlistentry>
318
 
        <term><literal>-p</literal>, <literal>--password</literal
319
 
        ></term>
 
334
        <term><option>--password</option></term>
 
335
        <term><option>-p</option></term>
320
336
        <listitem>
321
337
          <para>
322
338
            Prompt for a password and encrypt it with the key already
328
344
            >8</manvolnum></citerefentry>.  The host name or the name
329
345
            specified with the <option>--name</option> option is used
330
346
            for the section header.  All other options are ignored,
331
 
            and no keys are created.
 
347
            and no key is created.
332
348
          </para>
333
349
        </listitem>
334
350
      </varlistentry>
340
356
    <xi:include href="overview.xml"/>
341
357
    <para>
342
358
      This program is a small utility to generate new OpenPGP keys for
343
 
      new Mandos clients.
 
359
      new Mandos clients, and to generate sections for inclusion in
 
360
      <filename>clients.conf</filename> on the server.
344
361
    </para>
345
362
  </refsect1>
346
363
 
347
364
  <refsect1 id="exit_status">
348
365
    <title>EXIT STATUS</title>
349
366
    <para>
350
 
      The exit status will be 0 if new keys were successfully created,
351
 
      otherwise not.
 
367
      The exit status will be 0 if a new key (or password, if the
 
368
      <option>--password</option> option was used) was successfully
 
369
      created, otherwise not.
352
370
    </para>
353
371
  </refsect1>
354
372
  
425
443
    </informalexample>
426
444
    <informalexample>
427
445
      <para>
428
 
        Create keys in another directory and of another type.  Force
 
446
        Create key in another directory and of another type.  Force
429
447
        overwriting old key files:
430
448
      </para>
431
449
      <para>
435
453
 
436
454
      </para>
437
455
    </informalexample>
 
456
    <informalexample>
 
457
      <para>
 
458
        Prompt for a password, encrypt it with the key in
 
459
        <filename>/etc/mandos</filename> and output a section suitable
 
460
        for <filename>clients.conf</filename>.
 
461
      </para>
 
462
      <para>
 
463
        <userinput>&COMMANDNAME; --password</userinput>
 
464
      </para>
 
465
    </informalexample>
 
466
    <informalexample>
 
467
      <para>
 
468
        Prompt for a password, encrypt it with the key in the
 
469
        <filename>client-key</filename> directory and output a section
 
470
        suitable for <filename>clients.conf</filename>.
 
471
      </para>
 
472
      <para>
 
473
 
 
474
<!-- do not wrap this line -->
 
475
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
 
476
 
 
477
      </para>
 
478
    </informalexample>
438
479
  </refsect1>
439
480
 
440
481
  <refsect1 id="security">
442
483
    <para>
443
484
      The <option>--type</option>, <option>--length</option>,
444
485
      <option>--subtype</option>, and <option>--sublength</option>
445
 
      options can be used to create keys of insufficient security.  If
446
 
      in doubt, leave them to the default values.
 
486
      options can be used to create keys of low security.  If in
 
487
      doubt, leave them to the default values.
447
488
    </para>
448
489
    <para>
449
 
      The key expire time is not guaranteed to be honored by
450
 
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
490
      The key expire time is <emphasis>not</emphasis> guaranteed to be
 
491
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
451
492
      <manvolnum>8</manvolnum></citerefentry>.
452
493
    </para>
453
494
  </refsect1>
457
498
    <para>
458
499
      <citerefentry><refentrytitle>gpg</refentrytitle>
459
500
      <manvolnum>1</manvolnum></citerefentry>,
 
501
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
 
502
      <manvolnum>5</manvolnum></citerefentry>,
460
503
      <citerefentry><refentrytitle>mandos</refentrytitle>
461
504
      <manvolnum>8</manvolnum></citerefentry>,
462
505
      <citerefentry><refentrytitle>password-request</refentrytitle>