/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
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-09-12">
 
6
<!ENTITY TIMESTAMP "2008-08-30">
7
7
]>
8
8
 
9
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
34
34
      <holder>Teddy Hogeborn</holder>
35
35
      <holder>Björn Påhlsson</holder>
36
36
    </copyright>
37
 
    <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>
38
60
  </refentryinfo>
39
 
  
 
61
 
40
62
  <refmeta>
41
63
    <refentrytitle>&COMMANDNAME;</refentrytitle>
42
64
    <manvolnum>8</manvolnum>
45
67
  <refnamediv>
46
68
    <refname><command>&COMMANDNAME;</command></refname>
47
69
    <refpurpose>
48
 
      Generate key and password for Mandos client and server.
 
70
      Generate keys for <citerefentry><refentrytitle>password-request
 
71
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
49
72
    </refpurpose>
50
73
  </refnamediv>
51
 
  
 
74
 
52
75
  <refsynopsisdiv>
53
76
    <cmdsynopsis>
54
77
      <command>&COMMANDNAME;</command>
120
143
    <cmdsynopsis>
121
144
      <command>&COMMANDNAME;</command>
122
145
      <group choice="req">
 
146
        <arg choice="plain"><option>-p</option></arg>
123
147
        <arg choice="plain"><option>--password</option></arg>
124
 
        <arg choice="plain"><option>-p</option></arg>
125
148
      </group>
126
149
      <sbr/>
127
150
      <group>
141
164
    <cmdsynopsis>
142
165
      <command>&COMMANDNAME;</command>
143
166
      <group choice="req">
 
167
        <arg choice="plain"><option>-h</option></arg>
144
168
        <arg choice="plain"><option>--help</option></arg>
145
 
        <arg choice="plain"><option>-h</option></arg>
146
169
      </group>
147
170
    </cmdsynopsis>
148
171
    <cmdsynopsis>
149
172
      <command>&COMMANDNAME;</command>
150
173
      <group choice="req">
 
174
        <arg choice="plain"><option>-v</option></arg>
151
175
        <arg choice="plain"><option>--version</option></arg>
152
 
        <arg choice="plain"><option>-v</option></arg>
153
176
      </group>
154
177
    </cmdsynopsis>
155
178
  </refsynopsisdiv>
156
 
  
 
179
 
157
180
  <refsect1 id="description">
158
181
    <title>DESCRIPTION</title>
159
182
    <para>
160
183
      <command>&COMMANDNAME;</command> is a program to generate the
161
 
      OpenPGP key used by
162
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
163
 
      <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
164
187
      normally written to /etc/mandos for later installation into the
165
 
      initrd image, but this, and most other things, can be changed
166
 
      with command line options.
 
188
      initrd image, but this, like most things, can be changed with
 
189
      command line options.
167
190
    </para>
168
191
    <para>
169
 
      This program can also be used with the
170
 
      <option>--password</option> option to generate a ready-made
171
 
      section for <filename>clients.conf</filename> (see
 
192
      It can also be used to generate ready-made sections for
172
193
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
173
 
      <manvolnum>5</manvolnum></citerefentry>).
 
194
      <manvolnum>5</manvolnum></citerefentry> using the
 
195
      <option>--password</option> option.
174
196
    </para>
175
197
  </refsect1>
176
198
  
177
199
  <refsect1 id="purpose">
178
200
    <title>PURPOSE</title>
 
201
 
179
202
    <para>
180
203
      The purpose of this is to enable <emphasis>remote and unattended
181
204
      rebooting</emphasis> of client host computer with an
182
205
      <emphasis>encrypted root file system</emphasis>.  See <xref
183
206
      linkend="overview"/> for details.
184
207
    </para>
 
208
 
185
209
  </refsect1>
186
210
  
187
211
  <refsect1 id="options">
188
212
    <title>OPTIONS</title>
189
 
    
 
213
 
190
214
    <variablelist>
191
215
      <varlistentry>
192
 
        <term><option>--help</option></term>
193
 
        <term><option>-h</option></term>
 
216
        <term><literal>-h</literal>, <literal>--help</literal></term>
194
217
        <listitem>
195
218
          <para>
196
219
            Show a help message and exit
197
220
          </para>
198
221
        </listitem>
199
222
      </varlistentry>
200
 
      
 
223
 
201
224
      <varlistentry>
202
 
        <term><option>--dir
203
 
        <replaceable>DIRECTORY</replaceable></option></term>
204
 
        <term><option>-d
205
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
225
        <term><literal>-d</literal>, <literal>--dir
 
226
        <replaceable>directory</replaceable></literal></term>
206
227
        <listitem>
207
228
          <para>
208
229
            Target directory for key files.  Default is
210
231
          </para>
211
232
        </listitem>
212
233
      </varlistentry>
213
 
      
 
234
 
214
235
      <varlistentry>
215
 
        <term><option>--type
216
 
        <replaceable>TYPE</replaceable></option></term>
217
 
        <term><option>-t
218
 
        <replaceable>TYPE</replaceable></option></term>
 
236
        <term><literal>-t</literal>, <literal>--type
 
237
        <replaceable>type</replaceable></literal></term>
219
238
        <listitem>
220
239
          <para>
221
240
            Key type.  Default is <quote>DSA</quote>.
222
241
          </para>
223
242
        </listitem>
224
243
      </varlistentry>
225
 
      
 
244
 
226
245
      <varlistentry>
227
 
        <term><option>--length
228
 
        <replaceable>BITS</replaceable></option></term>
229
 
        <term><option>-l
230
 
        <replaceable>BITS</replaceable></option></term>
 
246
        <term><literal>-l</literal>, <literal>--length
 
247
        <replaceable>bits</replaceable></literal></term>
231
248
        <listitem>
232
249
          <para>
233
250
            Key length in bits.  Default is 2048.
234
251
          </para>
235
252
        </listitem>
236
253
      </varlistentry>
237
 
      
 
254
 
238
255
      <varlistentry>
239
 
        <term><option>--subtype
240
 
        <replaceable>KEYTYPE</replaceable></option></term>
241
 
        <term><option>-s
242
 
        <replaceable>KEYTYPE</replaceable></option></term>
 
256
        <term><literal>-s</literal>, <literal>--subtype
 
257
        <replaceable>type</replaceable></literal></term>
243
258
        <listitem>
244
259
          <para>
245
260
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
247
262
          </para>
248
263
        </listitem>
249
264
      </varlistentry>
250
 
      
 
265
 
251
266
      <varlistentry>
252
 
        <term><option>--sublength
253
 
        <replaceable>BITS</replaceable></option></term>
254
 
        <term><option>-L
255
 
        <replaceable>BITS</replaceable></option></term>
 
267
        <term><literal>-L</literal>, <literal>--sublength
 
268
        <replaceable>bits</replaceable></literal></term>
256
269
        <listitem>
257
270
          <para>
258
271
            Subkey length in bits.  Default is 2048.
259
272
          </para>
260
273
        </listitem>
261
274
      </varlistentry>
262
 
      
 
275
 
263
276
      <varlistentry>
264
 
        <term><option>--email
265
 
        <replaceable>ADDRESS</replaceable></option></term>
266
 
        <term><option>-e
267
 
        <replaceable>ADDRESS</replaceable></option></term>
 
277
        <term><literal>-e</literal>, <literal>--email</literal>
 
278
        <replaceable>address</replaceable></term>
268
279
        <listitem>
269
280
          <para>
270
281
            Email address of key.  Default is empty.
271
282
          </para>
272
283
        </listitem>
273
284
      </varlistentry>
274
 
      
 
285
 
275
286
      <varlistentry>
276
 
        <term><option>--comment
277
 
        <replaceable>TEXT</replaceable></option></term>
278
 
        <term><option>-c
279
 
        <replaceable>TEXT</replaceable></option></term>
 
287
        <term><literal>-c</literal>, <literal>--comment</literal>
 
288
        <replaceable>comment</replaceable></term>
280
289
        <listitem>
281
290
          <para>
282
291
            Comment field for key.  The default value is
284
293
          </para>
285
294
        </listitem>
286
295
      </varlistentry>
287
 
      
 
296
 
288
297
      <varlistentry>
289
 
        <term><option>--expire
290
 
        <replaceable>TIME</replaceable></option></term>
291
 
        <term><option>-x
292
 
        <replaceable>TIME</replaceable></option></term>
 
298
        <term><literal>-x</literal>, <literal>--expire</literal>
 
299
        <replaceable>time</replaceable></term>
293
300
        <listitem>
294
301
          <para>
295
302
            Key expire time.  Default is no expiration.  See
298
305
          </para>
299
306
        </listitem>
300
307
      </varlistentry>
301
 
      
 
308
 
302
309
      <varlistentry>
303
 
        <term><option>--force</option></term>
304
 
        <term><option>-f</option></term>
 
310
        <term><literal>-f</literal>, <literal>--force</literal></term>
305
311
        <listitem>
306
312
          <para>
307
 
            Force overwriting old key.
 
313
            Force overwriting old keys.
308
314
          </para>
309
315
        </listitem>
310
316
      </varlistentry>
311
317
      <varlistentry>
312
 
        <term><option>--password</option></term>
313
 
        <term><option>-p</option></term>
 
318
        <term><literal>-p</literal>, <literal>--password</literal
 
319
        ></term>
314
320
        <listitem>
315
321
          <para>
316
322
            Prompt for a password and encrypt it with the key already
322
328
            >8</manvolnum></citerefentry>.  The host name or the name
323
329
            specified with the <option>--name</option> option is used
324
330
            for the section header.  All other options are ignored,
325
 
            and no key is created.
 
331
            and no keys are created.
326
332
          </para>
327
333
        </listitem>
328
334
      </varlistentry>
329
335
    </variablelist>
330
336
  </refsect1>
331
 
  
 
337
 
332
338
  <refsect1 id="overview">
333
339
    <title>OVERVIEW</title>
334
340
    <xi:include href="overview.xml"/>
335
341
    <para>
336
342
      This program is a small utility to generate new OpenPGP keys for
337
 
      new Mandos clients, and to generate sections for inclusion in
338
 
      <filename>clients.conf</filename> on the server.
 
343
      new Mandos clients.
339
344
    </para>
340
345
  </refsect1>
341
 
  
 
346
 
342
347
  <refsect1 id="exit_status">
343
348
    <title>EXIT STATUS</title>
344
349
    <para>
345
 
      The exit status will be 0 if a new key (or password, if the
346
 
      <option>--password</option> option was used) was successfully
347
 
      created, otherwise not.
 
350
      The exit status will be 0 if new keys were successfully created,
 
351
      otherwise not.
348
352
    </para>
349
353
  </refsect1>
350
354
  
401
405
      </varlistentry>
402
406
    </variablelist>
403
407
  </refsect1>
404
 
  
405
 
<!--   <refsect1 id="bugs"> -->
406
 
<!--     <title>BUGS</title> -->
407
 
<!--     <para> -->
408
 
<!--     </para> -->
409
 
<!--   </refsect1> -->
410
 
  
 
408
 
 
409
  <refsect1 id="bugs">
 
410
    <title>BUGS</title>
 
411
    <para>
 
412
      None are known at this time.
 
413
    </para>
 
414
  </refsect1>
 
415
 
411
416
  <refsect1 id="example">
412
417
    <title>EXAMPLE</title>
413
418
    <informalexample>
420
425
    </informalexample>
421
426
    <informalexample>
422
427
      <para>
423
 
        Create key in another directory and of another type.  Force
 
428
        Create keys in another directory and of another type.  Force
424
429
        overwriting old key files:
425
430
      </para>
426
431
      <para>
430
435
 
431
436
      </para>
432
437
    </informalexample>
433
 
    <informalexample>
434
 
      <para>
435
 
        Prompt for a password, encrypt it with the key in
436
 
        <filename>/etc/mandos</filename> and output a section suitable
437
 
        for <filename>clients.conf</filename>.
438
 
      </para>
439
 
      <para>
440
 
        <userinput>&COMMANDNAME; --password</userinput>
441
 
      </para>
442
 
    </informalexample>
443
 
    <informalexample>
444
 
      <para>
445
 
        Prompt for a password, encrypt it with the key in the
446
 
        <filename>client-key</filename> directory and output a section
447
 
        suitable for <filename>clients.conf</filename>.
448
 
      </para>
449
 
      <para>
450
 
 
451
 
<!-- do not wrap this line -->
452
 
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
453
 
 
454
 
      </para>
455
 
    </informalexample>
456
438
  </refsect1>
457
 
  
 
439
 
458
440
  <refsect1 id="security">
459
441
    <title>SECURITY</title>
460
442
    <para>
461
443
      The <option>--type</option>, <option>--length</option>,
462
444
      <option>--subtype</option>, and <option>--sublength</option>
463
 
      options can be used to create keys of low security.  If in
464
 
      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.
465
447
    </para>
466
448
    <para>
467
 
      The key expire time is <emphasis>not</emphasis> guaranteed to be
468
 
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
 
449
      The key expire time is not guaranteed to be honored by
 
450
      <citerefentry><refentrytitle>mandos</refentrytitle>
469
451
      <manvolnum>8</manvolnum></citerefentry>.
470
452
    </para>
471
453
  </refsect1>
472
 
  
 
454
 
473
455
  <refsect1 id="see_also">
474
456
    <title>SEE ALSO</title>
475
457
    <para>
476
458
      <citerefentry><refentrytitle>gpg</refentrytitle>
477
459
      <manvolnum>1</manvolnum></citerefentry>,
478
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
479
 
      <manvolnum>5</manvolnum></citerefentry>,
480
460
      <citerefentry><refentrytitle>mandos</refentrytitle>
481
461
      <manvolnum>8</manvolnum></citerefentry>,
482
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
462
      <citerefentry><refentrytitle>password-request</refentrytitle>
483
463
      <manvolnum>8mandos</manvolnum></citerefentry>
484
464
    </para>
485
465
  </refsect1>