/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

merge

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