/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:49:24 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080830194924-f4liqq8wxajlbshn
* plugin-runner.xml (NAME): Improved wording.
  (SYNOPSIS): Use <option> and <replaceable> tags.  Unify short and
              long options.  Add "--global-envs" and "--envs-for"
              options.

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