/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 12:23:33 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080831122333-qgppahxb4d4b0coc
* plugins.d/password-request.xml (OPTIONS): Make replaceables match
                                            the ones in the SYNOPSIS.
                                            Split <term> tags into one
                                            for each option.  Use
                                            <option> tags instead of
                                            <literal>.  Moved long
                                            options before short.

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