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