/mandos/release

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/release

« 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 "2016-03-05">
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
 
  
 
408
 
453
409
  <refsect1 id="bugs">
454
410
    <title>BUGS</title>
455
 
    <xi:include href="bugs.xml"/>
 
411
    <para>
 
412
      None are known at this time.
 
413
    </para>
456
414
  </refsect1>
457
 
  
 
415
 
458
416
  <refsect1 id="example">
459
417
    <title>EXAMPLE</title>
460
418
    <informalexample>
467
425
    </informalexample>
468
426
    <informalexample>
469
427
      <para>
470
 
        Create key in another directory and of another type.  Force
 
428
        Create keys in another directory and of another type.  Force
471
429
        overwriting old key files:
472
430
      </para>
473
431
      <para>
477
435
 
478
436
      </para>
479
437
    </informalexample>
480
 
    <informalexample>
481
 
      <para>
482
 
        Prompt for a password, encrypt it with the key in <filename
483
 
        class="directory">/etc/mandos</filename> and output a section
484
 
        suitable for <filename>clients.conf</filename>.
485
 
      </para>
486
 
      <para>
487
 
        <userinput>&COMMANDNAME; --password</userinput>
488
 
      </para>
489
 
    </informalexample>
490
 
    <informalexample>
491
 
      <para>
492
 
        Prompt for a password, encrypt it with the key in the
493
 
        <filename>client-key</filename> directory and output a section
494
 
        suitable for <filename>clients.conf</filename>.
495
 
      </para>
496
 
      <para>
497
 
 
498
 
<!-- do not wrap this line -->
499
 
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
500
 
 
501
 
      </para>
502
 
    </informalexample>
503
438
  </refsect1>
504
 
  
 
439
 
505
440
  <refsect1 id="security">
506
441
    <title>SECURITY</title>
507
442
    <para>
508
443
      The <option>--type</option>, <option>--length</option>,
509
444
      <option>--subtype</option>, and <option>--sublength</option>
510
 
      options can be used to create keys of low security.  If in
511
 
      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.
512
447
    </para>
513
448
    <para>
514
 
      The key expire time is <emphasis>not</emphasis> guaranteed to be
515
 
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
 
449
      The key expire time is not guaranteed to be honored by
 
450
      <citerefentry><refentrytitle>mandos</refentrytitle>
516
451
      <manvolnum>8</manvolnum></citerefentry>.
517
452
    </para>
518
453
  </refsect1>
519
 
  
 
454
 
520
455
  <refsect1 id="see_also">
521
456
    <title>SEE ALSO</title>
522
457
    <para>
523
 
      <citerefentry><refentrytitle>intro</refentrytitle>
524
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
525
458
      <citerefentry><refentrytitle>gpg</refentrytitle>
526
459
      <manvolnum>1</manvolnum></citerefentry>,
527
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
528
 
      <manvolnum>5</manvolnum></citerefentry>,
529
460
      <citerefentry><refentrytitle>mandos</refentrytitle>
530
461
      <manvolnum>8</manvolnum></citerefentry>,
531
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
532
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
533
 
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
534
 
      <manvolnum>1</manvolnum></citerefentry>
 
462
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
463
      <manvolnum>8mandos</manvolnum></citerefentry>
535
464
    </para>
536
465
  </refsect1>
537
466