/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:49:24 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080830194924-f4liqq8wxajlbshn
* plugin-runner.xml (NAME): Improved wording.
  (SYNOPSIS): Use <option> and <replaceable> tags.  Unify short and
              long options.  Add "--global-envs" and "--envs-for"
              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 "2017-02-23">
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
 
      <year>2017</year>
44
34
      <holder>Teddy Hogeborn</holder>
45
35
      <holder>Björn Påhlsson</holder>
46
36
    </copyright>
47
 
    <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>
48
60
  </refentryinfo>
49
 
  
 
61
 
50
62
  <refmeta>
51
63
    <refentrytitle>&COMMANDNAME;</refentrytitle>
52
64
    <manvolnum>8</manvolnum>
55
67
  <refnamediv>
56
68
    <refname><command>&COMMANDNAME;</command></refname>
57
69
    <refpurpose>
58
 
      Generate key and password for Mandos client and server.
 
70
      Generate keys for <citerefentry><refentrytitle>password-request
 
71
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
59
72
    </refpurpose>
60
73
  </refnamediv>
61
 
  
 
74
 
62
75
  <refsynopsisdiv>
63
76
    <cmdsynopsis>
64
77
      <command>&COMMANDNAME;</command>
125
138
        <replaceable>TIME</replaceable></option></arg>
126
139
      </group>
127
140
      <sbr/>
128
 
      <group>
129
 
        <arg choice="plain"><option>--force</option></arg>
130
 
        <arg choice="plain"><option>-f</option></arg>
131
 
      </group>
 
141
      <arg><option>--force</option></arg>
132
142
    </cmdsynopsis>
133
143
    <cmdsynopsis>
134
144
      <command>&COMMANDNAME;</command>
135
145
      <group choice="req">
 
146
        <arg choice="plain"><option>-p</option></arg>
136
147
        <arg choice="plain"><option>--password</option></arg>
137
 
        <arg choice="plain"><option>-p</option></arg>
138
 
        <arg choice="plain"><option>--passfile
139
 
        <replaceable>FILE</replaceable></option></arg>
140
 
        <arg choice="plain"><option>-F</option>
141
 
        <replaceable>FILE</replaceable></arg>
142
148
      </group>
143
149
      <sbr/>
144
150
      <group>
154
160
        <arg choice="plain"><option>-n
155
161
        <replaceable>NAME</replaceable></option></arg>
156
162
      </group>
157
 
      <group>
158
 
        <arg choice="plain"><option>--no-ssh</option></arg>
159
 
        <arg choice="plain"><option>-S</option></arg>
160
 
      </group>
161
163
    </cmdsynopsis>
162
164
    <cmdsynopsis>
163
165
      <command>&COMMANDNAME;</command>
164
166
      <group choice="req">
 
167
        <arg choice="plain"><option>-h</option></arg>
165
168
        <arg choice="plain"><option>--help</option></arg>
166
 
        <arg choice="plain"><option>-h</option></arg>
167
169
      </group>
168
170
    </cmdsynopsis>
169
171
    <cmdsynopsis>
170
172
      <command>&COMMANDNAME;</command>
171
173
      <group choice="req">
 
174
        <arg choice="plain"><option>-v</option></arg>
172
175
        <arg choice="plain"><option>--version</option></arg>
173
 
        <arg choice="plain"><option>-v</option></arg>
174
176
      </group>
175
177
    </cmdsynopsis>
176
178
  </refsynopsisdiv>
177
 
  
 
179
 
178
180
  <refsect1 id="description">
179
181
    <title>DESCRIPTION</title>
180
182
    <para>
181
183
      <command>&COMMANDNAME;</command> is a program to generate the
182
 
      OpenPGP key used by
183
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
184
 
      <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
185
187
      normally written to /etc/mandos for later installation into the
186
 
      initrd image, but this, and most other things, can be changed
187
 
      with command line options.
 
188
      initrd image, but this, like most things, can be changed with
 
189
      command line options.
188
190
    </para>
189
191
    <para>
190
 
      This program can also be used with the
191
 
      <option>--password</option> or <option>--passfile</option>
192
 
      options to generate a ready-made section for
193
 
      <filename>clients.conf</filename> (see
 
192
      It can also be used to generate ready-made sections for
194
193
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
195
 
      <manvolnum>5</manvolnum></citerefentry>).
 
194
      <manvolnum>5</manvolnum></citerefentry> using the
 
195
      <option>--password</option> option.
196
196
    </para>
197
197
  </refsect1>
198
198
  
199
199
  <refsect1 id="purpose">
200
200
    <title>PURPOSE</title>
 
201
 
201
202
    <para>
202
203
      The purpose of this is to enable <emphasis>remote and unattended
203
204
      rebooting</emphasis> of client host computer with an
204
205
      <emphasis>encrypted root file system</emphasis>.  See <xref
205
206
      linkend="overview"/> for details.
206
207
    </para>
 
208
 
207
209
  </refsect1>
208
210
  
209
211
  <refsect1 id="options">
210
212
    <title>OPTIONS</title>
211
 
    
 
213
 
212
214
    <variablelist>
213
215
      <varlistentry>
214
 
        <term><option>--help</option></term>
215
 
        <term><option>-h</option></term>
 
216
        <term><literal>-h</literal>, <literal>--help</literal></term>
216
217
        <listitem>
217
218
          <para>
218
219
            Show a help message and exit
219
220
          </para>
220
221
        </listitem>
221
222
      </varlistentry>
222
 
      
 
223
 
223
224
      <varlistentry>
224
 
        <term><option>--dir
225
 
        <replaceable>DIRECTORY</replaceable></option></term>
226
 
        <term><option>-d
227
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
225
        <term><literal>-d</literal>, <literal>--dir
 
226
        <replaceable>directory</replaceable></literal></term>
228
227
        <listitem>
229
228
          <para>
230
229
            Target directory for key files.  Default is
231
 
            <filename class="directory">/etc/mandos</filename>.
232
 
          </para>
233
 
        </listitem>
234
 
      </varlistentry>
235
 
      
236
 
      <varlistentry>
237
 
        <term><option>--type
238
 
        <replaceable>TYPE</replaceable></option></term>
239
 
        <term><option>-t
240
 
        <replaceable>TYPE</replaceable></option></term>
241
 
        <listitem>
242
 
          <para>
243
 
            Key type.  Default is <quote>RSA</quote>.
244
 
          </para>
245
 
        </listitem>
246
 
      </varlistentry>
247
 
      
248
 
      <varlistentry>
249
 
        <term><option>--length
250
 
        <replaceable>BITS</replaceable></option></term>
251
 
        <term><option>-l
252
 
        <replaceable>BITS</replaceable></option></term>
253
 
        <listitem>
254
 
          <para>
255
 
            Key length in bits.  Default is 4096.
256
 
          </para>
257
 
        </listitem>
258
 
      </varlistentry>
259
 
      
260
 
      <varlistentry>
261
 
        <term><option>--subtype
262
 
        <replaceable>KEYTYPE</replaceable></option></term>
263
 
        <term><option>-s
264
 
        <replaceable>KEYTYPE</replaceable></option></term>
265
 
        <listitem>
266
 
          <para>
267
 
            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
268
261
            encryption-only).
269
262
          </para>
270
263
        </listitem>
271
264
      </varlistentry>
272
 
      
 
265
 
273
266
      <varlistentry>
274
 
        <term><option>--sublength
275
 
        <replaceable>BITS</replaceable></option></term>
276
 
        <term><option>-L
277
 
        <replaceable>BITS</replaceable></option></term>
 
267
        <term><literal>-L</literal>, <literal>--sublength
 
268
        <replaceable>bits</replaceable></literal></term>
278
269
        <listitem>
279
270
          <para>
280
 
            Subkey length in bits.  Default is 4096.
 
271
            Subkey length in bits.  Default is 2048.
281
272
          </para>
282
273
        </listitem>
283
274
      </varlistentry>
284
 
      
 
275
 
285
276
      <varlistentry>
286
 
        <term><option>--email
287
 
        <replaceable>ADDRESS</replaceable></option></term>
288
 
        <term><option>-e
289
 
        <replaceable>ADDRESS</replaceable></option></term>
 
277
        <term><literal>-e</literal>, <literal>--email</literal>
 
278
        <replaceable>address</replaceable></term>
290
279
        <listitem>
291
280
          <para>
292
281
            Email address of key.  Default is empty.
293
282
          </para>
294
283
        </listitem>
295
284
      </varlistentry>
296
 
      
 
285
 
297
286
      <varlistentry>
298
 
        <term><option>--comment
299
 
        <replaceable>TEXT</replaceable></option></term>
300
 
        <term><option>-c
301
 
        <replaceable>TEXT</replaceable></option></term>
 
287
        <term><literal>-c</literal>, <literal>--comment</literal>
 
288
        <replaceable>comment</replaceable></term>
302
289
        <listitem>
303
290
          <para>
304
 
            Comment field for key.  Default is empty.
 
291
            Comment field for key.  The default value is
 
292
            <quote><literal>Mandos client key</literal></quote>.
305
293
          </para>
306
294
        </listitem>
307
295
      </varlistentry>
308
 
      
 
296
 
309
297
      <varlistentry>
310
 
        <term><option>--expire
311
 
        <replaceable>TIME</replaceable></option></term>
312
 
        <term><option>-x
313
 
        <replaceable>TIME</replaceable></option></term>
 
298
        <term><literal>-x</literal>, <literal>--expire</literal>
 
299
        <replaceable>time</replaceable></term>
314
300
        <listitem>
315
301
          <para>
316
302
            Key expire time.  Default is no expiration.  See
319
305
          </para>
320
306
        </listitem>
321
307
      </varlistentry>
322
 
      
 
308
 
323
309
      <varlistentry>
324
 
        <term><option>--force</option></term>
325
 
        <term><option>-f</option></term>
 
310
        <term><literal>-f</literal>, <literal>--force</literal></term>
326
311
        <listitem>
327
312
          <para>
328
 
            Force overwriting old key.
 
313
            Force overwriting old keys.
329
314
          </para>
330
315
        </listitem>
331
316
      </varlistentry>
332
317
      <varlistentry>
333
 
        <term><option>--password</option></term>
334
 
        <term><option>-p</option></term>
 
318
        <term><literal>-p</literal>, <literal>--password</literal
 
319
        ></term>
335
320
        <listitem>
336
321
          <para>
337
322
            Prompt for a password and encrypt it with the key already
343
328
            >8</manvolnum></citerefentry>.  The host name or the name
344
329
            specified with the <option>--name</option> option is used
345
330
            for the section header.  All other options are ignored,
346
 
            and no key is created.
347
 
          </para>
348
 
        </listitem>
349
 
      </varlistentry>
350
 
      <varlistentry>
351
 
        <term><option>--passfile
352
 
        <replaceable>FILE</replaceable></option></term>
353
 
        <term><option>-F
354
 
        <replaceable>FILE</replaceable></option></term>
355
 
        <listitem>
356
 
          <para>
357
 
            The same as <option>--password</option>, but read from
358
 
            <replaceable>FILE</replaceable>, not the terminal.
359
 
          </para>
360
 
        </listitem>
361
 
      </varlistentry>
362
 
      <varlistentry>
363
 
        <term><option>--no-ssh</option></term>
364
 
        <term><option>-S</option></term>
365
 
        <listitem>
366
 
          <para>
367
 
            When <option>--password</option> or
368
 
            <option>--passfile</option> is given, this option will
369
 
            prevent <command>&COMMANDNAME;</command> from calling
370
 
            <command>ssh-keyscan</command> to get an SSH fingerprint
371
 
            for this host and, if successful, output suitable config
372
 
            options to use this fingerprint as a
373
 
            <option>checker</option> option in the output.  This is
374
 
            otherwise the default behavior.
 
331
            and no keys are created.
375
332
          </para>
376
333
        </listitem>
377
334
      </varlistentry>
378
335
    </variablelist>
379
336
  </refsect1>
380
 
  
 
337
 
381
338
  <refsect1 id="overview">
382
339
    <title>OVERVIEW</title>
383
340
    <xi:include href="overview.xml"/>
384
341
    <para>
385
342
      This program is a small utility to generate new OpenPGP keys for
386
 
      new Mandos clients, and to generate sections for inclusion in
387
 
      <filename>clients.conf</filename> on the server.
 
343
      new Mandos clients.
388
344
    </para>
389
345
  </refsect1>
390
 
  
 
346
 
391
347
  <refsect1 id="exit_status">
392
348
    <title>EXIT STATUS</title>
393
349
    <para>
394
 
      The exit status will be 0 if a new key (or password, if the
395
 
      <option>--password</option> option was used) was successfully
396
 
      created, otherwise not.
 
350
      The exit status will be 0 if new keys were successfully created,
 
351
      otherwise not.
397
352
    </para>
398
353
  </refsect1>
399
354
  
413
368
    </variablelist>
414
369
  </refsect1>
415
370
  
416
 
  <refsect1 id="files">
 
371
  <refsect1 id="file">
417
372
    <title>FILES</title>
418
373
    <para>
419
374
      Use the <option>--dir</option> option to change where
440
395
        </listitem>
441
396
      </varlistentry>
442
397
      <varlistentry>
443
 
        <term><filename class="directory">/tmp</filename></term>
 
398
        <term><filename>/tmp</filename></term>
444
399
        <listitem>
445
400
          <para>
446
401
            Temporary files will be written here if
450
405
      </varlistentry>
451
406
    </variablelist>
452
407
  </refsect1>
453
 
  
 
408
 
454
409
  <refsect1 id="bugs">
455
410
    <title>BUGS</title>
456
 
    <xi:include href="bugs.xml"/>
 
411
    <para>
 
412
      None are known at this time.
 
413
    </para>
457
414
  </refsect1>
458
 
  
 
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