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