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