/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 "2014-06-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>
119
138
        <replaceable>TIME</replaceable></option></arg>
120
139
      </group>
121
140
      <sbr/>
122
 
      <group>
123
 
        <arg choice="plain"><option>--force</option></arg>
124
 
        <arg choice="plain"><option>-f</option></arg>
125
 
      </group>
 
141
      <arg><option>--force</option></arg>
126
142
    </cmdsynopsis>
127
143
    <cmdsynopsis>
128
144
      <command>&COMMANDNAME;</command>
129
145
      <group choice="req">
 
146
        <arg choice="plain"><option>-p</option></arg>
130
147
        <arg choice="plain"><option>--password</option></arg>
131
 
        <arg choice="plain"><option>-p</option></arg>
132
 
        <arg choice="plain"><option>--passfile
133
 
        <replaceable>FILE</replaceable></option></arg>
134
 
        <arg choice="plain"><option>-F</option>
135
 
        <replaceable>FILE</replaceable></arg>
136
148
      </group>
137
149
      <sbr/>
138
150
      <group>
148
160
        <arg choice="plain"><option>-n
149
161
        <replaceable>NAME</replaceable></option></arg>
150
162
      </group>
151
 
      <group>
152
 
        <arg choice="plain"><option>--no-ssh</option></arg>
153
 
        <arg choice="plain"><option>-S</option></arg>
154
 
      </group>
155
163
    </cmdsynopsis>
156
164
    <cmdsynopsis>
157
165
      <command>&COMMANDNAME;</command>
158
166
      <group choice="req">
 
167
        <arg choice="plain"><option>-h</option></arg>
159
168
        <arg choice="plain"><option>--help</option></arg>
160
 
        <arg choice="plain"><option>-h</option></arg>
161
169
      </group>
162
170
    </cmdsynopsis>
163
171
    <cmdsynopsis>
164
172
      <command>&COMMANDNAME;</command>
165
173
      <group choice="req">
 
174
        <arg choice="plain"><option>-v</option></arg>
166
175
        <arg choice="plain"><option>--version</option></arg>
167
 
        <arg choice="plain"><option>-v</option></arg>
168
176
      </group>
169
177
    </cmdsynopsis>
170
178
  </refsynopsisdiv>
171
 
  
 
179
 
172
180
  <refsect1 id="description">
173
181
    <title>DESCRIPTION</title>
174
182
    <para>
175
183
      <command>&COMMANDNAME;</command> is a program to generate the
176
 
      OpenPGP key used by
177
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
178
 
      <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
179
187
      normally written to /etc/mandos for later installation into the
180
 
      initrd image, but this, and most other things, can be changed
181
 
      with command line options.
 
188
      initrd image, but this, like most things, can be changed with
 
189
      command line options.
182
190
    </para>
183
191
    <para>
184
 
      This program can also be used with the
185
 
      <option>--password</option> or <option>--passfile</option>
186
 
      options to generate a ready-made section for
187
 
      <filename>clients.conf</filename> (see
 
192
      It can also be used to generate ready-made sections for
188
193
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
189
 
      <manvolnum>5</manvolnum></citerefentry>).
 
194
      <manvolnum>5</manvolnum></citerefentry> using the
 
195
      <option>--password</option> option.
190
196
    </para>
191
197
  </refsect1>
192
198
  
193
199
  <refsect1 id="purpose">
194
200
    <title>PURPOSE</title>
 
201
 
195
202
    <para>
196
203
      The purpose of this is to enable <emphasis>remote and unattended
197
204
      rebooting</emphasis> of client host computer with an
198
205
      <emphasis>encrypted root file system</emphasis>.  See <xref
199
206
      linkend="overview"/> for details.
200
207
    </para>
 
208
 
201
209
  </refsect1>
202
210
  
203
211
  <refsect1 id="options">
204
212
    <title>OPTIONS</title>
205
 
    
 
213
 
206
214
    <variablelist>
207
215
      <varlistentry>
208
 
        <term><option>--help</option></term>
209
 
        <term><option>-h</option></term>
 
216
        <term><literal>-h</literal>, <literal>--help</literal></term>
210
217
        <listitem>
211
218
          <para>
212
219
            Show a help message and exit
213
220
          </para>
214
221
        </listitem>
215
222
      </varlistentry>
216
 
      
 
223
 
217
224
      <varlistentry>
218
 
        <term><option>--dir
219
 
        <replaceable>DIRECTORY</replaceable></option></term>
220
 
        <term><option>-d
221
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
225
        <term><literal>-d</literal>, <literal>--dir
 
226
        <replaceable>directory</replaceable></literal></term>
222
227
        <listitem>
223
228
          <para>
224
229
            Target directory for key files.  Default is
225
 
            <filename class="directory">/etc/mandos</filename>.
226
 
          </para>
227
 
        </listitem>
228
 
      </varlistentry>
229
 
      
230
 
      <varlistentry>
231
 
        <term><option>--type
232
 
        <replaceable>TYPE</replaceable></option></term>
233
 
        <term><option>-t
234
 
        <replaceable>TYPE</replaceable></option></term>
235
 
        <listitem>
236
 
          <para>
237
 
            Key type.  Default is <quote>RSA</quote>.
238
 
          </para>
239
 
        </listitem>
240
 
      </varlistentry>
241
 
      
242
 
      <varlistentry>
243
 
        <term><option>--length
244
 
        <replaceable>BITS</replaceable></option></term>
245
 
        <term><option>-l
246
 
        <replaceable>BITS</replaceable></option></term>
247
 
        <listitem>
248
 
          <para>
249
 
            Key length in bits.  Default is 4096.
250
 
          </para>
251
 
        </listitem>
252
 
      </varlistentry>
253
 
      
254
 
      <varlistentry>
255
 
        <term><option>--subtype
256
 
        <replaceable>KEYTYPE</replaceable></option></term>
257
 
        <term><option>-s
258
 
        <replaceable>KEYTYPE</replaceable></option></term>
259
 
        <listitem>
260
 
          <para>
261
 
            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
262
261
            encryption-only).
263
262
          </para>
264
263
        </listitem>
265
264
      </varlistentry>
266
 
      
 
265
 
267
266
      <varlistentry>
268
 
        <term><option>--sublength
269
 
        <replaceable>BITS</replaceable></option></term>
270
 
        <term><option>-L
271
 
        <replaceable>BITS</replaceable></option></term>
 
267
        <term><literal>-L</literal>, <literal>--sublength
 
268
        <replaceable>bits</replaceable></literal></term>
272
269
        <listitem>
273
270
          <para>
274
 
            Subkey length in bits.  Default is 4096.
 
271
            Subkey length in bits.  Default is 2048.
275
272
          </para>
276
273
        </listitem>
277
274
      </varlistentry>
278
 
      
 
275
 
279
276
      <varlistentry>
280
 
        <term><option>--email
281
 
        <replaceable>ADDRESS</replaceable></option></term>
282
 
        <term><option>-e
283
 
        <replaceable>ADDRESS</replaceable></option></term>
 
277
        <term><literal>-e</literal>, <literal>--email</literal>
 
278
        <replaceable>address</replaceable></term>
284
279
        <listitem>
285
280
          <para>
286
281
            Email address of key.  Default is empty.
287
282
          </para>
288
283
        </listitem>
289
284
      </varlistentry>
290
 
      
 
285
 
291
286
      <varlistentry>
292
 
        <term><option>--comment
293
 
        <replaceable>TEXT</replaceable></option></term>
294
 
        <term><option>-c
295
 
        <replaceable>TEXT</replaceable></option></term>
 
287
        <term><literal>-c</literal>, <literal>--comment</literal>
 
288
        <replaceable>comment</replaceable></term>
296
289
        <listitem>
297
290
          <para>
298
 
            Comment field for key.  Default is empty.
 
291
            Comment field for key.  The default value is
 
292
            <quote><literal>Mandos client key</literal></quote>.
299
293
          </para>
300
294
        </listitem>
301
295
      </varlistentry>
302
 
      
 
296
 
303
297
      <varlistentry>
304
 
        <term><option>--expire
305
 
        <replaceable>TIME</replaceable></option></term>
306
 
        <term><option>-x
307
 
        <replaceable>TIME</replaceable></option></term>
 
298
        <term><literal>-x</literal>, <literal>--expire</literal>
 
299
        <replaceable>time</replaceable></term>
308
300
        <listitem>
309
301
          <para>
310
302
            Key expire time.  Default is no expiration.  See
313
305
          </para>
314
306
        </listitem>
315
307
      </varlistentry>
316
 
      
 
308
 
317
309
      <varlistentry>
318
 
        <term><option>--force</option></term>
319
 
        <term><option>-f</option></term>
 
310
        <term><literal>-f</literal>, <literal>--force</literal></term>
320
311
        <listitem>
321
312
          <para>
322
 
            Force overwriting old key.
 
313
            Force overwriting old keys.
323
314
          </para>
324
315
        </listitem>
325
316
      </varlistentry>
326
317
      <varlistentry>
327
 
        <term><option>--password</option></term>
328
 
        <term><option>-p</option></term>
 
318
        <term><literal>-p</literal>, <literal>--password</literal
 
319
        ></term>
329
320
        <listitem>
330
321
          <para>
331
322
            Prompt for a password and encrypt it with the key already
337
328
            >8</manvolnum></citerefentry>.  The host name or the name
338
329
            specified with the <option>--name</option> option is used
339
330
            for the section header.  All other options are ignored,
340
 
            and no key is created.
341
 
          </para>
342
 
        </listitem>
343
 
      </varlistentry>
344
 
      <varlistentry>
345
 
        <term><option>--passfile
346
 
        <replaceable>FILE</replaceable></option></term>
347
 
        <term><option>-F
348
 
        <replaceable>FILE</replaceable></option></term>
349
 
        <listitem>
350
 
          <para>
351
 
            The same as <option>--password</option>, but read from
352
 
            <replaceable>FILE</replaceable>, not the terminal.
353
 
          </para>
354
 
        </listitem>
355
 
      </varlistentry>
356
 
      <varlistentry>
357
 
        <term><option>--no-ssh</option></term>
358
 
        <term><option>-S</option></term>
359
 
        <listitem>
360
 
          <para>
361
 
            When <option>--password</option> or
362
 
            <option>--passfile</option> is given, this option will
363
 
            prevent <command>&COMMANDNAME;</command> from calling
364
 
            <command>ssh-keyscan</command> to get an SSH fingerprint
365
 
            for this host and, if successful, output suitable config
366
 
            options to use this fingerprint as a
367
 
            <option>checker</option> option in the output.  This is
368
 
            otherwise the default behavior.
 
331
            and no keys are created.
369
332
          </para>
370
333
        </listitem>
371
334
      </varlistentry>
372
335
    </variablelist>
373
336
  </refsect1>
374
 
  
 
337
 
375
338
  <refsect1 id="overview">
376
339
    <title>OVERVIEW</title>
377
340
    <xi:include href="overview.xml"/>
378
341
    <para>
379
342
      This program is a small utility to generate new OpenPGP keys for
380
 
      new Mandos clients, and to generate sections for inclusion in
381
 
      <filename>clients.conf</filename> on the server.
 
343
      new Mandos clients.
382
344
    </para>
383
345
  </refsect1>
384
 
  
 
346
 
385
347
  <refsect1 id="exit_status">
386
348
    <title>EXIT STATUS</title>
387
349
    <para>
388
 
      The exit status will be 0 if a new key (or password, if the
389
 
      <option>--password</option> option was used) was successfully
390
 
      created, otherwise not.
 
350
      The exit status will be 0 if new keys were successfully created,
 
351
      otherwise not.
391
352
    </para>
392
353
  </refsect1>
393
354
  
407
368
    </variablelist>
408
369
  </refsect1>
409
370
  
410
 
  <refsect1 id="files">
 
371
  <refsect1 id="file">
411
372
    <title>FILES</title>
412
373
    <para>
413
374
      Use the <option>--dir</option> option to change where
434
395
        </listitem>
435
396
      </varlistentry>
436
397
      <varlistentry>
437
 
        <term><filename class="directory">/tmp</filename></term>
 
398
        <term><filename>/tmp</filename></term>
438
399
        <listitem>
439
400
          <para>
440
401
            Temporary files will be written here if
444
405
      </varlistentry>
445
406
    </variablelist>
446
407
  </refsect1>
447
 
  
448
 
<!--   <refsect1 id="bugs"> -->
449
 
<!--     <title>BUGS</title> -->
450
 
<!--     <para> -->
451
 
<!--     </para> -->
452
 
<!--   </refsect1> -->
453
 
  
 
408
 
 
409
  <refsect1 id="bugs">
 
410
    <title>BUGS</title>
 
411
    <para>
 
412
      None are known at this time.
 
413
    </para>
 
414
  </refsect1>
 
415
 
454
416
  <refsect1 id="example">
455
417
    <title>EXAMPLE</title>
456
418
    <informalexample>
463
425
    </informalexample>
464
426
    <informalexample>
465
427
      <para>
466
 
        Create key in another directory and of another type.  Force
 
428
        Create keys in another directory and of another type.  Force
467
429
        overwriting old key files:
468
430
      </para>
469
431
      <para>
473
435
 
474
436
      </para>
475
437
    </informalexample>
476
 
    <informalexample>
477
 
      <para>
478
 
        Prompt for a password, encrypt it with the key in <filename
479
 
        class="directory">/etc/mandos</filename> and output a section
480
 
        suitable for <filename>clients.conf</filename>.
481
 
      </para>
482
 
      <para>
483
 
        <userinput>&COMMANDNAME; --password</userinput>
484
 
      </para>
485
 
    </informalexample>
486
 
    <informalexample>
487
 
      <para>
488
 
        Prompt for a password, encrypt it with the key in the
489
 
        <filename>client-key</filename> directory and output a section
490
 
        suitable for <filename>clients.conf</filename>.
491
 
      </para>
492
 
      <para>
493
 
 
494
 
<!-- do not wrap this line -->
495
 
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
496
 
 
497
 
      </para>
498
 
    </informalexample>
499
438
  </refsect1>
500
 
  
 
439
 
501
440
  <refsect1 id="security">
502
441
    <title>SECURITY</title>
503
442
    <para>
504
443
      The <option>--type</option>, <option>--length</option>,
505
444
      <option>--subtype</option>, and <option>--sublength</option>
506
 
      options can be used to create keys of low security.  If in
507
 
      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.
508
447
    </para>
509
448
    <para>
510
 
      The key expire time is <emphasis>not</emphasis> guaranteed to be
511
 
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
 
449
      The key expire time is not guaranteed to be honored by
 
450
      <citerefentry><refentrytitle>mandos</refentrytitle>
512
451
      <manvolnum>8</manvolnum></citerefentry>.
513
452
    </para>
514
453
  </refsect1>
515
 
  
 
454
 
516
455
  <refsect1 id="see_also">
517
456
    <title>SEE ALSO</title>
518
457
    <para>
519
 
      <citerefentry><refentrytitle>intro</refentrytitle>
520
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
521
458
      <citerefentry><refentrytitle>gpg</refentrytitle>
522
459
      <manvolnum>1</manvolnum></citerefentry>,
523
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
524
 
      <manvolnum>5</manvolnum></citerefentry>,
525
460
      <citerefentry><refentrytitle>mandos</refentrytitle>
526
461
      <manvolnum>8</manvolnum></citerefentry>,
527
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
528
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
529
 
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
530
 
      <manvolnum>1</manvolnum></citerefentry>
 
462
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
463
      <manvolnum>8mandos</manvolnum></citerefentry>
531
464
    </para>
532
465
  </refsect1>
533
466