/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 "2011-10-03">
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
34
      <holder>Teddy Hogeborn</holder>
38
35
      <holder>Björn Påhlsson</holder>
39
36
    </copyright>
40
 
    <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>
41
60
  </refentryinfo>
42
 
  
 
61
 
43
62
  <refmeta>
44
63
    <refentrytitle>&COMMANDNAME;</refentrytitle>
45
64
    <manvolnum>8</manvolnum>
48
67
  <refnamediv>
49
68
    <refname><command>&COMMANDNAME;</command></refname>
50
69
    <refpurpose>
51
 
      Generate key and password for Mandos client and server.
 
70
      Generate keys for <citerefentry><refentrytitle>password-request
 
71
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
52
72
    </refpurpose>
53
73
  </refnamediv>
54
 
  
 
74
 
55
75
  <refsynopsisdiv>
56
76
    <cmdsynopsis>
57
77
      <command>&COMMANDNAME;</command>
123
143
    <cmdsynopsis>
124
144
      <command>&COMMANDNAME;</command>
125
145
      <group choice="req">
 
146
        <arg choice="plain"><option>-p</option></arg>
126
147
        <arg choice="plain"><option>--password</option></arg>
127
 
        <arg choice="plain"><option>-p</option></arg>
128
 
        <arg choice="plain"><option>--passfile
129
 
        <replaceable>FILE</replaceable></option></arg>
130
 
        <arg choice="plain"><option>-F</option>
131
 
        <replaceable>FILE</replaceable></arg>
132
148
      </group>
133
149
      <sbr/>
134
150
      <group>
148
164
    <cmdsynopsis>
149
165
      <command>&COMMANDNAME;</command>
150
166
      <group choice="req">
 
167
        <arg choice="plain"><option>-h</option></arg>
151
168
        <arg choice="plain"><option>--help</option></arg>
152
 
        <arg choice="plain"><option>-h</option></arg>
153
169
      </group>
154
170
    </cmdsynopsis>
155
171
    <cmdsynopsis>
156
172
      <command>&COMMANDNAME;</command>
157
173
      <group choice="req">
 
174
        <arg choice="plain"><option>-v</option></arg>
158
175
        <arg choice="plain"><option>--version</option></arg>
159
 
        <arg choice="plain"><option>-v</option></arg>
160
176
      </group>
161
177
    </cmdsynopsis>
162
178
  </refsynopsisdiv>
163
 
  
 
179
 
164
180
  <refsect1 id="description">
165
181
    <title>DESCRIPTION</title>
166
182
    <para>
167
183
      <command>&COMMANDNAME;</command> is a program to generate the
168
 
      OpenPGP key used by
169
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
170
 
      <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
171
187
      normally written to /etc/mandos for later installation into the
172
 
      initrd image, but this, and most other things, can be changed
173
 
      with command line options.
 
188
      initrd image, but this, like most things, can be changed with
 
189
      command line options.
174
190
    </para>
175
191
    <para>
176
 
      This program can also be used with the
177
 
      <option>--password</option> or <option>--passfile</option>
178
 
      options to generate a ready-made section for
179
 
      <filename>clients.conf</filename> (see
 
192
      It can also be used to generate ready-made sections for
180
193
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
181
 
      <manvolnum>5</manvolnum></citerefentry>).
 
194
      <manvolnum>5</manvolnum></citerefentry> using the
 
195
      <option>--password</option> option.
182
196
    </para>
183
197
  </refsect1>
184
198
  
185
199
  <refsect1 id="purpose">
186
200
    <title>PURPOSE</title>
 
201
 
187
202
    <para>
188
203
      The purpose of this is to enable <emphasis>remote and unattended
189
204
      rebooting</emphasis> of client host computer with an
190
205
      <emphasis>encrypted root file system</emphasis>.  See <xref
191
206
      linkend="overview"/> for details.
192
207
    </para>
 
208
 
193
209
  </refsect1>
194
210
  
195
211
  <refsect1 id="options">
196
212
    <title>OPTIONS</title>
197
 
    
 
213
 
198
214
    <variablelist>
199
215
      <varlistentry>
200
 
        <term><option>--help</option></term>
201
 
        <term><option>-h</option></term>
 
216
        <term><literal>-h</literal>, <literal>--help</literal></term>
202
217
        <listitem>
203
218
          <para>
204
219
            Show a help message and exit
205
220
          </para>
206
221
        </listitem>
207
222
      </varlistentry>
208
 
      
 
223
 
209
224
      <varlistentry>
210
 
        <term><option>--dir
211
 
        <replaceable>DIRECTORY</replaceable></option></term>
212
 
        <term><option>-d
213
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
225
        <term><literal>-d</literal>, <literal>--dir
 
226
        <replaceable>directory</replaceable></literal></term>
214
227
        <listitem>
215
228
          <para>
216
229
            Target directory for key files.  Default is
218
231
          </para>
219
232
        </listitem>
220
233
      </varlistentry>
221
 
      
 
234
 
222
235
      <varlistentry>
223
 
        <term><option>--type
224
 
        <replaceable>TYPE</replaceable></option></term>
225
 
        <term><option>-t
226
 
        <replaceable>TYPE</replaceable></option></term>
 
236
        <term><literal>-t</literal>, <literal>--type
 
237
        <replaceable>type</replaceable></literal></term>
227
238
        <listitem>
228
239
          <para>
229
240
            Key type.  Default is <quote>DSA</quote>.
230
241
          </para>
231
242
        </listitem>
232
243
      </varlistentry>
233
 
      
 
244
 
234
245
      <varlistentry>
235
 
        <term><option>--length
236
 
        <replaceable>BITS</replaceable></option></term>
237
 
        <term><option>-l
238
 
        <replaceable>BITS</replaceable></option></term>
 
246
        <term><literal>-l</literal>, <literal>--length
 
247
        <replaceable>bits</replaceable></literal></term>
239
248
        <listitem>
240
249
          <para>
241
250
            Key length in bits.  Default is 2048.
242
251
          </para>
243
252
        </listitem>
244
253
      </varlistentry>
245
 
      
 
254
 
246
255
      <varlistentry>
247
 
        <term><option>--subtype
248
 
        <replaceable>KEYTYPE</replaceable></option></term>
249
 
        <term><option>-s
250
 
        <replaceable>KEYTYPE</replaceable></option></term>
 
256
        <term><literal>-s</literal>, <literal>--subtype
 
257
        <replaceable>type</replaceable></literal></term>
251
258
        <listitem>
252
259
          <para>
253
260
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
255
262
          </para>
256
263
        </listitem>
257
264
      </varlistentry>
258
 
      
 
265
 
259
266
      <varlistentry>
260
 
        <term><option>--sublength
261
 
        <replaceable>BITS</replaceable></option></term>
262
 
        <term><option>-L
263
 
        <replaceable>BITS</replaceable></option></term>
 
267
        <term><literal>-L</literal>, <literal>--sublength
 
268
        <replaceable>bits</replaceable></literal></term>
264
269
        <listitem>
265
270
          <para>
266
271
            Subkey length in bits.  Default is 2048.
267
272
          </para>
268
273
        </listitem>
269
274
      </varlistentry>
270
 
      
 
275
 
271
276
      <varlistentry>
272
 
        <term><option>--email
273
 
        <replaceable>ADDRESS</replaceable></option></term>
274
 
        <term><option>-e
275
 
        <replaceable>ADDRESS</replaceable></option></term>
 
277
        <term><literal>-e</literal>, <literal>--email</literal>
 
278
        <replaceable>address</replaceable></term>
276
279
        <listitem>
277
280
          <para>
278
281
            Email address of key.  Default is empty.
279
282
          </para>
280
283
        </listitem>
281
284
      </varlistentry>
282
 
      
 
285
 
283
286
      <varlistentry>
284
 
        <term><option>--comment
285
 
        <replaceable>TEXT</replaceable></option></term>
286
 
        <term><option>-c
287
 
        <replaceable>TEXT</replaceable></option></term>
 
287
        <term><literal>-c</literal>, <literal>--comment</literal>
 
288
        <replaceable>comment</replaceable></term>
288
289
        <listitem>
289
290
          <para>
290
291
            Comment field for key.  The default value is
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
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
456
 
        <filename>/etc/mandos</filename> and output a section suitable
457
 
        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>