/mandos/release

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/release

« 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-31">
6
7
]>
7
8
 
8
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
9
10
  <refentryinfo>
10
 
    <title>&COMMANDNAME;</title>
 
11
    <title>Mandos Manual</title>
11
12
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
12
 
    <productname>&COMMANDNAME;</productname>
 
13
    <productname>Mandos</productname>
13
14
    <productnumber>&VERSION;</productnumber>
 
15
    <date>&TIMESTAMP;</date>
14
16
    <authorgroup>
15
17
      <author>
16
18
        <firstname>Björn</firstname>
65
67
  <refnamediv>
66
68
    <refname><command>&COMMANDNAME;</command></refname>
67
69
    <refpurpose>
68
 
      Generate keys for <citerefentry><refentrytitle>password-request
69
 
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
 
70
      Generate key and password for Mandos client and server.
70
71
    </refpurpose>
71
72
  </refnamediv>
72
73
 
73
74
  <refsynopsisdiv>
74
75
    <cmdsynopsis>
75
76
      <command>&COMMANDNAME;</command>
76
 
      <group choice="opt">
77
 
        <arg choice="plain"><option>--dir</option>
78
 
        <replaceable>directory</replaceable></arg>
79
 
      </group>
80
 
      <group choice="opt">
81
 
        <arg choice="plain"><option>--type</option>
82
 
        <replaceable>type</replaceable></arg>
83
 
      </group>
84
 
      <group choice="opt">
85
 
        <arg choice="plain"><option>--length</option>
86
 
        <replaceable>bits</replaceable></arg>
87
 
      </group>
88
 
      <group choice="opt">
89
 
        <arg choice="plain"><option>--subtype</option>
90
 
        <replaceable>type</replaceable></arg>
91
 
      </group>
92
 
      <group choice="opt">
93
 
        <arg choice="plain"><option>--sublength</option>
94
 
        <replaceable>bits</replaceable></arg>
95
 
      </group>
96
 
      <group choice="opt">
97
 
        <arg choice="plain"><option>--name</option>
98
 
        <replaceable>NAME</replaceable></arg>
99
 
      </group>
100
 
      <group choice="opt">
101
 
        <arg choice="plain"><option>--email</option>
102
 
        <replaceable>EMAIL</replaceable></arg>
103
 
      </group>
104
 
      <group choice="opt">
105
 
        <arg choice="plain"><option>--comment</option>
106
 
        <replaceable>COMMENT</replaceable></arg>
107
 
      </group>
108
 
      <group choice="opt">
109
 
        <arg choice="plain"><option>--expire</option>
110
 
        <replaceable>TIME</replaceable></arg>
111
 
      </group>
112
 
      <group choice="opt">
113
 
        <arg choice="plain"><option>--force</option></arg>
114
 
      </group>
115
 
    </cmdsynopsis>
116
 
    <cmdsynopsis>
117
 
      <command>&COMMANDNAME;</command>
118
 
      <group choice="opt">
119
 
        <arg choice="plain"><option>-d</option>
120
 
        <replaceable>directory</replaceable></arg>
121
 
      </group>
122
 
      <group choice="opt">
123
 
        <arg choice="plain"><option>-t</option>
124
 
        <replaceable>type</replaceable></arg>
125
 
      </group>
126
 
      <group choice="opt">
127
 
        <arg choice="plain"><option>-l</option>
128
 
        <replaceable>bits</replaceable></arg>
129
 
      </group>
130
 
      <group choice="opt">
131
 
        <arg choice="plain"><option>-s</option>
132
 
        <replaceable>type</replaceable></arg>
133
 
      </group>
134
 
      <group choice="opt">
135
 
        <arg choice="plain"><option>-L</option>
136
 
        <replaceable>bits</replaceable></arg>
137
 
      </group>
138
 
      <group choice="opt">
139
 
        <arg choice="plain"><option>-n</option>
140
 
        <replaceable>NAME</replaceable></arg>
141
 
      </group>
142
 
      <group choice="opt">
143
 
        <arg choice="plain"><option>-e</option>
144
 
        <replaceable>EMAIL</replaceable></arg>
145
 
      </group>
146
 
      <group choice="opt">
147
 
        <arg choice="plain"><option>-c</option>
148
 
        <replaceable>COMMENT</replaceable></arg>
149
 
      </group>
150
 
      <group choice="opt">
151
 
        <arg choice="plain"><option>-x</option>
152
 
        <replaceable>TIME</replaceable></arg>
153
 
      </group>
154
 
      <group choice="opt">
155
 
        <arg choice="plain"><option>-f</option></arg>
156
 
      </group>
 
77
      <group>
 
78
        <arg choice="plain"><option>--dir
 
79
        <replaceable>DIRECTORY</replaceable></option></arg>
 
80
        <arg choice="plain"><option>-d
 
81
        <replaceable>DIRECTORY</replaceable></option></arg>
 
82
      </group>
 
83
      <sbr/>
 
84
      <group>
 
85
        <arg choice="plain"><option>--type
 
86
        <replaceable>KEYTYPE</replaceable></option></arg>
 
87
        <arg choice="plain"><option>-t
 
88
        <replaceable>KEYTYPE</replaceable></option></arg>
 
89
      </group>
 
90
      <sbr/>
 
91
      <group>
 
92
        <arg choice="plain"><option>--length
 
93
        <replaceable>BITS</replaceable></option></arg>
 
94
        <arg choice="plain"><option>-l
 
95
        <replaceable>BITS</replaceable></option></arg>
 
96
      </group>
 
97
      <sbr/>
 
98
      <group>
 
99
        <arg choice="plain"><option>--subtype
 
100
        <replaceable>KEYTYPE</replaceable></option></arg>
 
101
        <arg choice="plain"><option>-s
 
102
        <replaceable>KEYTYPE</replaceable></option></arg>
 
103
      </group>
 
104
      <sbr/>
 
105
      <group>
 
106
        <arg choice="plain"><option>--sublength
 
107
        <replaceable>BITS</replaceable></option></arg>
 
108
        <arg choice="plain"><option>-L
 
109
        <replaceable>BITS</replaceable></option></arg>
 
110
      </group>
 
111
      <sbr/>
 
112
      <group>
 
113
        <arg choice="plain"><option>--name
 
114
        <replaceable>NAME</replaceable></option></arg>
 
115
        <arg choice="plain"><option>-n
 
116
        <replaceable>NAME</replaceable></option></arg>
 
117
      </group>
 
118
      <sbr/>
 
119
      <group>
 
120
        <arg choice="plain"><option>--email
 
121
        <replaceable>ADDRESS</replaceable></option></arg>
 
122
        <arg choice="plain"><option>-e
 
123
        <replaceable>ADDRESS</replaceable></option></arg>
 
124
      </group>
 
125
      <sbr/>
 
126
      <group>
 
127
        <arg choice="plain"><option>--comment
 
128
        <replaceable>TEXT</replaceable></option></arg>
 
129
        <arg choice="plain"><option>-c
 
130
        <replaceable>TEXT</replaceable></option></arg>
 
131
      </group>
 
132
      <sbr/>
 
133
      <group>
 
134
        <arg choice="plain"><option>--expire
 
135
        <replaceable>TIME</replaceable></option></arg>
 
136
        <arg choice="plain"><option>-x
 
137
        <replaceable>TIME</replaceable></option></arg>
 
138
      </group>
 
139
      <sbr/>
 
140
      <arg><option>--force</option></arg>
157
141
    </cmdsynopsis>
158
142
    <cmdsynopsis>
159
143
      <command>&COMMANDNAME;</command>
160
144
      <group choice="req">
 
145
        <arg choice="plain"><option>--password</option></arg>
161
146
        <arg choice="plain"><option>-p</option></arg>
162
 
        <arg choice="plain"><option>--password</option></arg>
163
 
      </group>
164
 
      <group choice="opt">
165
 
        <arg choice="plain"><option>--dir</option>
166
 
        <replaceable>directory</replaceable></arg>
167
 
      </group>
168
 
      <group choice="opt">
169
 
        <arg choice="plain"><option>--name</option>
170
 
        <replaceable>NAME</replaceable></arg>
 
147
      </group>
 
148
      <sbr/>
 
149
      <group>
 
150
        <arg choice="plain"><option>--dir
 
151
        <replaceable>DIRECTORY</replaceable></option></arg>
 
152
        <arg choice="plain"><option>-d
 
153
        <replaceable>DIRECTORY</replaceable></option></arg>
 
154
      </group>
 
155
      <sbr/>
 
156
      <group>
 
157
        <arg choice="plain"><option>--name
 
158
        <replaceable>NAME</replaceable></option></arg>
 
159
        <arg choice="plain"><option>-n
 
160
        <replaceable>NAME</replaceable></option></arg>
171
161
      </group>
172
162
    </cmdsynopsis>
173
163
    <cmdsynopsis>
174
164
      <command>&COMMANDNAME;</command>
175
165
      <group choice="req">
 
166
        <arg choice="plain"><option>--help</option></arg>
176
167
        <arg choice="plain"><option>-h</option></arg>
177
 
        <arg choice="plain"><option>--help</option></arg>
178
168
      </group>
179
169
    </cmdsynopsis>
180
170
    <cmdsynopsis>
181
171
      <command>&COMMANDNAME;</command>
182
172
      <group choice="req">
 
173
        <arg choice="plain"><option>--version</option></arg>
183
174
        <arg choice="plain"><option>-v</option></arg>
184
 
        <arg choice="plain"><option>--version</option></arg>
185
175
      </group>
186
176
    </cmdsynopsis>
187
177
  </refsynopsisdiv>
188
 
 
 
178
  
189
179
  <refsect1 id="description">
190
180
    <title>DESCRIPTION</title>
191
181
    <para>
192
182
      <command>&COMMANDNAME;</command> is a program to generate the
193
 
      OpenPGP keys used by
 
183
      OpenPGP key used by
194
184
      <citerefentry><refentrytitle>password-request</refentrytitle>
195
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
 
185
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
196
186
      normally written to /etc/mandos for later installation into the
197
 
      initrd image, but this, like most things, can be changed with
198
 
      command line options.
 
187
      initrd image, but this, and most other things, can be changed
 
188
      with command line options.
199
189
    </para>
200
190
    <para>
201
 
      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
202
194
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
203
 
      <manvolnum>5</manvolnum></citerefentry> using the
204
 
      <option>--password</option> option.
 
195
      <manvolnum>5</manvolnum></citerefentry>).
205
196
    </para>
206
197
  </refsect1>
207
198
  
208
199
  <refsect1 id="purpose">
209
200
    <title>PURPOSE</title>
210
 
 
211
201
    <para>
212
202
      The purpose of this is to enable <emphasis>remote and unattended
213
203
      rebooting</emphasis> of client host computer with an
214
204
      <emphasis>encrypted root file system</emphasis>.  See <xref
215
205
      linkend="overview"/> for details.
216
206
    </para>
217
 
 
218
207
  </refsect1>
219
208
  
220
209
  <refsect1 id="options">
221
210
    <title>OPTIONS</title>
222
 
 
 
211
    
223
212
    <variablelist>
224
213
      <varlistentry>
225
 
        <term><literal>-h</literal>, <literal>--help</literal></term>
 
214
        <term><option>--help</option></term>
 
215
        <term><option>-h</option></term>
226
216
        <listitem>
227
217
          <para>
228
218
            Show a help message and exit
231
221
      </varlistentry>
232
222
 
233
223
      <varlistentry>
234
 
        <term><literal>-d</literal>, <literal>--dir
235
 
        <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>
236
228
        <listitem>
237
229
          <para>
238
230
            Target directory for key files.  Default is
242
234
      </varlistentry>
243
235
 
244
236
      <varlistentry>
245
 
        <term><literal>-t</literal>, <literal>--type
246
 
        <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>
247
241
        <listitem>
248
242
          <para>
249
243
            Key type.  Default is <quote>DSA</quote>.
252
246
      </varlistentry>
253
247
 
254
248
      <varlistentry>
255
 
        <term><literal>-l</literal>, <literal>--length
256
 
        <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>
257
253
        <listitem>
258
254
          <para>
259
255
            Key length in bits.  Default is 2048.
262
258
      </varlistentry>
263
259
 
264
260
      <varlistentry>
265
 
        <term><literal>-s</literal>, <literal>--subtype
266
 
        <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>
267
265
        <listitem>
268
266
          <para>
269
267
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
273
271
      </varlistentry>
274
272
 
275
273
      <varlistentry>
276
 
        <term><literal>-L</literal>, <literal>--sublength
277
 
        <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>
278
278
        <listitem>
279
279
          <para>
280
280
            Subkey length in bits.  Default is 2048.
283
283
      </varlistentry>
284
284
 
285
285
      <varlistentry>
286
 
        <term><literal>-e</literal>, <literal>--email</literal>
287
 
        <replaceable>address</replaceable></term>
 
286
        <term><option>--email
 
287
        <replaceable>ADDRESS</replaceable></option></term>
 
288
        <term><option>-e
 
289
        <replaceable>ADDRESS</replaceable></option></term>
288
290
        <listitem>
289
291
          <para>
290
292
            Email address of key.  Default is empty.
293
295
      </varlistentry>
294
296
 
295
297
      <varlistentry>
296
 
        <term><literal>-c</literal>, <literal>--comment</literal>
297
 
        <replaceable>comment</replaceable></term>
 
298
        <term><option>--comment
 
299
        <replaceable>TEXT</replaceable></option></term>
 
300
        <term><option>-c
 
301
        <replaceable>TEXT</replaceable></option></term>
298
302
        <listitem>
299
303
          <para>
300
304
            Comment field for key.  The default value is
304
308
      </varlistentry>
305
309
 
306
310
      <varlistentry>
307
 
        <term><literal>-x</literal>, <literal>--expire</literal>
308
 
        <replaceable>time</replaceable></term>
 
311
        <term><option>--expire
 
312
        <replaceable>TIME</replaceable></option></term>
 
313
        <term><option>-x
 
314
        <replaceable>TIME</replaceable></option></term>
309
315
        <listitem>
310
316
          <para>
311
317
            Key expire time.  Default is no expiration.  See
316
322
      </varlistentry>
317
323
 
318
324
      <varlistentry>
319
 
        <term><literal>-f</literal>, <literal>--force</literal></term>
 
325
        <term><option>--force</option></term>
 
326
        <term><option>-f</option></term>
320
327
        <listitem>
321
328
          <para>
322
 
            Force overwriting old keys.
 
329
            Force overwriting old key.
323
330
          </para>
324
331
        </listitem>
325
332
      </varlistentry>
326
333
      <varlistentry>
327
 
        <term><literal>-p</literal>, <literal>--password</literal
328
 
        ></term>
 
334
        <term><option>--password</option></term>
 
335
        <term><option>-p</option></term>
329
336
        <listitem>
330
337
          <para>
331
338
            Prompt for a password and encrypt it with the key already
337
344
            >8</manvolnum></citerefentry>.  The host name or the name
338
345
            specified with the <option>--name</option> option is used
339
346
            for the section header.  All other options are ignored,
340
 
            and no keys are created.
 
347
            and no key is created.
341
348
          </para>
342
349
        </listitem>
343
350
      </varlistentry>
349
356
    <xi:include href="overview.xml"/>
350
357
    <para>
351
358
      This program is a small utility to generate new OpenPGP keys for
352
 
      new Mandos clients.
 
359
      new Mandos clients, and to generate sections for inclusion in
 
360
      <filename>clients.conf</filename> on the server.
353
361
    </para>
354
362
  </refsect1>
355
363
 
356
364
  <refsect1 id="exit_status">
357
365
    <title>EXIT STATUS</title>
358
366
    <para>
359
 
      The exit status will be 0 if new keys were successfully created,
360
 
      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.
361
370
    </para>
362
371
  </refsect1>
363
372
  
365
374
    <title>ENVIRONMENT</title>
366
375
    <variablelist>
367
376
      <varlistentry>
368
 
        <term><varname>TMPDIR</varname></term>
 
377
        <term><envar>TMPDIR</envar></term>
369
378
        <listitem>
370
379
          <para>
371
380
            If set, temporary files will be created here. See
429
438
        Normal invocation needs no options:
430
439
      </para>
431
440
      <para>
432
 
        <userinput>mandos-keygen</userinput>
 
441
        <userinput>&COMMANDNAME;</userinput>
433
442
      </para>
434
443
    </informalexample>
435
444
    <informalexample>
436
445
      <para>
437
 
        Create keys in another directory and of another type.  Force
 
446
        Create key in another directory and of another type.  Force
438
447
        overwriting old key files:
439
448
      </para>
440
449
      <para>
441
450
 
442
451
<!-- do not wrap this line -->
443
 
<userinput>mandos-keygen --dir ~/keydir --type RSA --force</userinput>
 
452
<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>
 
453
 
 
454
      </para>
 
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>
444
476
 
445
477
      </para>
446
478
    </informalexample>
451
483
    <para>
452
484
      The <option>--type</option>, <option>--length</option>,
453
485
      <option>--subtype</option>, and <option>--sublength</option>
454
 
      options can be used to create keys of insufficient security.  If
455
 
      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.
456
488
    </para>
457
489
    <para>
458
 
      The key expire time is not guaranteed to be honored by
459
 
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
490
      The key expire time is <emphasis>not</emphasis> guaranteed to be
 
491
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
460
492
      <manvolnum>8</manvolnum></citerefentry>.
461
493
    </para>
462
494
  </refsect1>
464
496
  <refsect1 id="see_also">
465
497
    <title>SEE ALSO</title>
466
498
    <para>
467
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
468
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
499
      <citerefentry><refentrytitle>gpg</refentrytitle>
 
500
      <manvolnum>1</manvolnum></citerefentry>,
 
501
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
 
502
      <manvolnum>5</manvolnum></citerefentry>,
469
503
      <citerefentry><refentrytitle>mandos</refentrytitle>
470
504
      <manvolnum>8</manvolnum></citerefentry>,
471
 
      <citerefentry><refentrytitle>gpg</refentrytitle>
472
 
      <manvolnum>1</manvolnum></citerefentry>
 
505
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
506
      <manvolnum>8mandos</manvolnum></citerefentry>
473
507
    </para>
474
508
  </refsect1>
475
509
  
476
510
</refentry>
 
511
<!-- Local Variables: -->
 
512
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
 
513
<!-- time-stamp-end: "[\"']>" -->
 
514
<!-- time-stamp-format: "%:y-%02m-%02d" -->
 
515
<!-- End: -->