/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:05:15 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080830190515-l7e6vu81yyw5kcku
* mandos.xml (SYNOPSIS): Use <option> and <replaceable> tags.  Unify
                         short and long 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 "2013-10-22">
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>.
219
 
          </para>
220
 
        </listitem>
221
 
      </varlistentry>
222
 
      
223
 
      <varlistentry>
224
 
        <term><option>--type
225
 
        <replaceable>TYPE</replaceable></option></term>
226
 
        <term><option>-t
227
 
        <replaceable>TYPE</replaceable></option></term>
228
 
        <listitem>
229
 
          <para>
230
 
            Key type.  Default is <quote>RSA</quote>.
231
 
          </para>
232
 
        </listitem>
233
 
      </varlistentry>
234
 
      
235
 
      <varlistentry>
236
 
        <term><option>--length
237
 
        <replaceable>BITS</replaceable></option></term>
238
 
        <term><option>-l
239
 
        <replaceable>BITS</replaceable></option></term>
240
 
        <listitem>
241
 
          <para>
242
 
            Key length in bits.  Default is 4096.
243
 
          </para>
244
 
        </listitem>
245
 
      </varlistentry>
246
 
      
247
 
      <varlistentry>
248
 
        <term><option>--subtype
249
 
        <replaceable>KEYTYPE</replaceable></option></term>
250
 
        <term><option>-s
251
 
        <replaceable>KEYTYPE</replaceable></option></term>
252
 
        <listitem>
253
 
          <para>
254
 
            Subkey type.  Default is <quote>RSA</quote> (Elgamal
 
230
            <filename>/etc/mandos</filename>.
 
231
          </para>
 
232
        </listitem>
 
233
      </varlistentry>
 
234
 
 
235
      <varlistentry>
 
236
        <term><literal>-t</literal>, <literal>--type
 
237
        <replaceable>type</replaceable></literal></term>
 
238
        <listitem>
 
239
          <para>
 
240
            Key type.  Default is <quote>DSA</quote>.
 
241
          </para>
 
242
        </listitem>
 
243
      </varlistentry>
 
244
 
 
245
      <varlistentry>
 
246
        <term><literal>-l</literal>, <literal>--length
 
247
        <replaceable>bits</replaceable></literal></term>
 
248
        <listitem>
 
249
          <para>
 
250
            Key length in bits.  Default is 2048.
 
251
          </para>
 
252
        </listitem>
 
253
      </varlistentry>
 
254
 
 
255
      <varlistentry>
 
256
        <term><literal>-s</literal>, <literal>--subtype
 
257
        <replaceable>type</replaceable></literal></term>
 
258
        <listitem>
 
259
          <para>
 
260
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
255
261
            encryption-only).
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
 
            Subkey length in bits.  Default is 4096.
 
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
 
            Comment field for key.  Default is empty.
 
291
            Comment field for key.  The default value is
 
292
            <quote><literal>Mandos client key</literal></quote>.
292
293
          </para>
293
294
        </listitem>
294
295
      </varlistentry>
295
 
      
 
296
 
296
297
      <varlistentry>
297
 
        <term><option>--expire
298
 
        <replaceable>TIME</replaceable></option></term>
299
 
        <term><option>-x
300
 
        <replaceable>TIME</replaceable></option></term>
 
298
        <term><literal>-x</literal>, <literal>--expire</literal>
 
299
        <replaceable>time</replaceable></term>
301
300
        <listitem>
302
301
          <para>
303
302
            Key expire time.  Default is no expiration.  See
306
305
          </para>
307
306
        </listitem>
308
307
      </varlistentry>
309
 
      
 
308
 
310
309
      <varlistentry>
311
 
        <term><option>--force</option></term>
312
 
        <term><option>-f</option></term>
 
310
        <term><literal>-f</literal>, <literal>--force</literal></term>
313
311
        <listitem>
314
312
          <para>
315
 
            Force overwriting old key.
 
313
            Force overwriting old keys.
316
314
          </para>
317
315
        </listitem>
318
316
      </varlistentry>
319
317
      <varlistentry>
320
 
        <term><option>--password</option></term>
321
 
        <term><option>-p</option></term>
 
318
        <term><literal>-p</literal>, <literal>--password</literal
 
319
        ></term>
322
320
        <listitem>
323
321
          <para>
324
322
            Prompt for a password and encrypt it with the key already
330
328
            >8</manvolnum></citerefentry>.  The host name or the name
331
329
            specified with the <option>--name</option> option is used
332
330
            for the section header.  All other options are ignored,
333
 
            and no key is created.
334
 
          </para>
335
 
        </listitem>
336
 
      </varlistentry>
337
 
      <varlistentry>
338
 
        <term><option>--passfile
339
 
        <replaceable>FILE</replaceable></option></term>
340
 
        <term><option>-F
341
 
        <replaceable>FILE</replaceable></option></term>
342
 
        <listitem>
343
 
          <para>
344
 
            The same as <option>--password</option>, but read from
345
 
            <replaceable>FILE</replaceable>, not the terminal.
 
331
            and no keys are created.
346
332
          </para>
347
333
        </listitem>
348
334
      </varlistentry>
349
335
    </variablelist>
350
336
  </refsect1>
351
 
  
 
337
 
352
338
  <refsect1 id="overview">
353
339
    <title>OVERVIEW</title>
354
340
    <xi:include href="overview.xml"/>
355
341
    <para>
356
342
      This program is a small utility to generate new OpenPGP keys for
357
 
      new Mandos clients, and to generate sections for inclusion in
358
 
      <filename>clients.conf</filename> on the server.
 
343
      new Mandos clients.
359
344
    </para>
360
345
  </refsect1>
361
 
  
 
346
 
362
347
  <refsect1 id="exit_status">
363
348
    <title>EXIT STATUS</title>
364
349
    <para>
365
 
      The exit status will be 0 if a new key (or password, if the
366
 
      <option>--password</option> option was used) was successfully
367
 
      created, otherwise not.
 
350
      The exit status will be 0 if new keys were successfully created,
 
351
      otherwise not.
368
352
    </para>
369
353
  </refsect1>
370
354
  
384
368
    </variablelist>
385
369
  </refsect1>
386
370
  
387
 
  <refsect1 id="files">
 
371
  <refsect1 id="file">
388
372
    <title>FILES</title>
389
373
    <para>
390
374
      Use the <option>--dir</option> option to change where
411
395
        </listitem>
412
396
      </varlistentry>
413
397
      <varlistentry>
414
 
        <term><filename class="directory">/tmp</filename></term>
 
398
        <term><filename>/tmp</filename></term>
415
399
        <listitem>
416
400
          <para>
417
401
            Temporary files will be written here if
421
405
      </varlistentry>
422
406
    </variablelist>
423
407
  </refsect1>
424
 
  
425
 
<!--   <refsect1 id="bugs"> -->
426
 
<!--     <title>BUGS</title> -->
427
 
<!--     <para> -->
428
 
<!--     </para> -->
429
 
<!--   </refsect1> -->
430
 
  
 
408
 
 
409
  <refsect1 id="bugs">
 
410
    <title>BUGS</title>
 
411
    <para>
 
412
      None are known at this time.
 
413
    </para>
 
414
  </refsect1>
 
415
 
431
416
  <refsect1 id="example">
432
417
    <title>EXAMPLE</title>
433
418
    <informalexample>
440
425
    </informalexample>
441
426
    <informalexample>
442
427
      <para>
443
 
        Create key in another directory and of another type.  Force
 
428
        Create keys in another directory and of another type.  Force
444
429
        overwriting old key files:
445
430
      </para>
446
431
      <para>
450
435
 
451
436
      </para>
452
437
    </informalexample>
453
 
    <informalexample>
454
 
      <para>
455
 
        Prompt for a password, encrypt it with the key in <filename
456
 
        class="directory">/etc/mandos</filename> and output a section
457
 
        suitable for <filename>clients.conf</filename>.
458
 
      </para>
459
 
      <para>
460
 
        <userinput>&COMMANDNAME; --password</userinput>
461
 
      </para>
462
 
    </informalexample>
463
 
    <informalexample>
464
 
      <para>
465
 
        Prompt for a password, encrypt it with the key in the
466
 
        <filename>client-key</filename> directory and output a section
467
 
        suitable for <filename>clients.conf</filename>.
468
 
      </para>
469
 
      <para>
470
 
 
471
 
<!-- do not wrap this line -->
472
 
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
473
 
 
474
 
      </para>
475
 
    </informalexample>
476
438
  </refsect1>
477
 
  
 
439
 
478
440
  <refsect1 id="security">
479
441
    <title>SECURITY</title>
480
442
    <para>
481
443
      The <option>--type</option>, <option>--length</option>,
482
444
      <option>--subtype</option>, and <option>--sublength</option>
483
 
      options can be used to create keys of low security.  If in
484
 
      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.
485
447
    </para>
486
448
    <para>
487
 
      The key expire time is <emphasis>not</emphasis> guaranteed to be
488
 
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
 
449
      The key expire time is not guaranteed to be honored by
 
450
      <citerefentry><refentrytitle>mandos</refentrytitle>
489
451
      <manvolnum>8</manvolnum></citerefentry>.
490
452
    </para>
491
453
  </refsect1>
492
 
  
 
454
 
493
455
  <refsect1 id="see_also">
494
456
    <title>SEE ALSO</title>
495
457
    <para>
496
 
      <citerefentry><refentrytitle>intro</refentrytitle>
497
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
498
458
      <citerefentry><refentrytitle>gpg</refentrytitle>
499
459
      <manvolnum>1</manvolnum></citerefentry>,
500
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
501
 
      <manvolnum>5</manvolnum></citerefentry>,
502
460
      <citerefentry><refentrytitle>mandos</refentrytitle>
503
461
      <manvolnum>8</manvolnum></citerefentry>,
504
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
462
      <citerefentry><refentrytitle>password-request</refentrytitle>
505
463
      <manvolnum>8mandos</manvolnum></citerefentry>
506
464
    </para>
507
465
  </refsect1>