/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

merge + fallback bugg

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-08-31">
7
6
]>
8
7
 
9
8
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
10
9
  <refentryinfo>
11
 
    <title>Mandos Manual</title>
 
10
    <title>&COMMANDNAME;</title>
12
11
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
 
    <productname>Mandos</productname>
 
12
    <productname>&COMMANDNAME;</productname>
14
13
    <productnumber>&VERSION;</productnumber>
15
 
    <date>&TIMESTAMP;</date>
16
14
    <authorgroup>
17
15
      <author>
18
16
        <firstname>Björn</firstname>
34
32
      <holder>Teddy Hogeborn</holder>
35
33
      <holder>Björn Påhlsson</holder>
36
34
    </copyright>
37
 
    <xi:include href="legalnotice.xml"/>
 
35
    <legalnotice>
 
36
      <para>
 
37
        This manual page is free software: you can redistribute it
 
38
        and/or modify it under the terms of the GNU General Public
 
39
        License as published by the Free Software Foundation,
 
40
        either version 3 of the License, or (at your option) any
 
41
        later version.
 
42
      </para>
 
43
 
 
44
      <para>
 
45
        This manual page is distributed in the hope that it will
 
46
        be useful, but WITHOUT ANY WARRANTY; without even the
 
47
        implied warranty of MERCHANTABILITY or FITNESS FOR A
 
48
        PARTICULAR PURPOSE.  See the GNU General Public License
 
49
        for more details.
 
50
      </para>
 
51
 
 
52
      <para>
 
53
        You should have received a copy of the GNU General Public
 
54
        License along with this program; If not, see
 
55
        <ulink url="http://www.gnu.org/licenses/"/>.
 
56
      </para>
 
57
    </legalnotice>
38
58
  </refentryinfo>
39
59
 
40
60
  <refmeta>
45
65
  <refnamediv>
46
66
    <refname><command>&COMMANDNAME;</command></refname>
47
67
    <refpurpose>
48
 
      Generate key and password for Mandos client and server.
 
68
      Generate keys for <citerefentry><refentrytitle>password-request
 
69
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
49
70
    </refpurpose>
50
71
  </refnamediv>
51
72
 
52
73
  <refsynopsisdiv>
53
74
    <cmdsynopsis>
54
75
      <command>&COMMANDNAME;</command>
55
 
      <group>
56
 
        <arg choice="plain"><option>--dir
57
 
        <replaceable>DIRECTORY</replaceable></option></arg>
58
 
        <arg choice="plain"><option>-d
59
 
        <replaceable>DIRECTORY</replaceable></option></arg>
60
 
      </group>
61
 
      <sbr/>
62
 
      <group>
63
 
        <arg choice="plain"><option>--type
64
 
        <replaceable>KEYTYPE</replaceable></option></arg>
65
 
        <arg choice="plain"><option>-t
66
 
        <replaceable>KEYTYPE</replaceable></option></arg>
67
 
      </group>
68
 
      <sbr/>
69
 
      <group>
70
 
        <arg choice="plain"><option>--length
71
 
        <replaceable>BITS</replaceable></option></arg>
72
 
        <arg choice="plain"><option>-l
73
 
        <replaceable>BITS</replaceable></option></arg>
74
 
      </group>
75
 
      <sbr/>
76
 
      <group>
77
 
        <arg choice="plain"><option>--subtype
78
 
        <replaceable>KEYTYPE</replaceable></option></arg>
79
 
        <arg choice="plain"><option>-s
80
 
        <replaceable>KEYTYPE</replaceable></option></arg>
81
 
      </group>
82
 
      <sbr/>
83
 
      <group>
84
 
        <arg choice="plain"><option>--sublength
85
 
        <replaceable>BITS</replaceable></option></arg>
86
 
        <arg choice="plain"><option>-L
87
 
        <replaceable>BITS</replaceable></option></arg>
88
 
      </group>
89
 
      <sbr/>
90
 
      <group>
91
 
        <arg choice="plain"><option>--name
92
 
        <replaceable>NAME</replaceable></option></arg>
93
 
        <arg choice="plain"><option>-n
94
 
        <replaceable>NAME</replaceable></option></arg>
95
 
      </group>
96
 
      <sbr/>
97
 
      <group>
98
 
        <arg choice="plain"><option>--email
99
 
        <replaceable>ADDRESS</replaceable></option></arg>
100
 
        <arg choice="plain"><option>-e
101
 
        <replaceable>ADDRESS</replaceable></option></arg>
102
 
      </group>
103
 
      <sbr/>
104
 
      <group>
105
 
        <arg choice="plain"><option>--comment
106
 
        <replaceable>TEXT</replaceable></option></arg>
107
 
        <arg choice="plain"><option>-c
108
 
        <replaceable>TEXT</replaceable></option></arg>
109
 
      </group>
110
 
      <sbr/>
111
 
      <group>
112
 
        <arg choice="plain"><option>--expire
113
 
        <replaceable>TIME</replaceable></option></arg>
114
 
        <arg choice="plain"><option>-x
115
 
        <replaceable>TIME</replaceable></option></arg>
116
 
      </group>
117
 
      <sbr/>
118
 
      <arg><option>--force</option></arg>
 
76
      <group choice="opt">
 
77
        <arg choice="plain"><option>--dir</option>
 
78
        <replaceable>directory</replaceable></arg>
 
79
      </group>
 
80
      <group choice="opt">
 
81
        <arg choice="plain"><option>--type</option>
 
82
        <replaceable>type</replaceable></arg>
 
83
      </group>
 
84
      <group choice="opt">
 
85
        <arg choice="plain"><option>--length</option>
 
86
        <replaceable>bits</replaceable></arg>
 
87
      </group>
 
88
      <group choice="opt">
 
89
        <arg choice="plain"><option>--subtype</option>
 
90
        <replaceable>type</replaceable></arg>
 
91
      </group>
 
92
      <group choice="opt">
 
93
        <arg choice="plain"><option>--sublength</option>
 
94
        <replaceable>bits</replaceable></arg>
 
95
      </group>
 
96
      <group choice="opt">
 
97
        <arg choice="plain"><option>--name</option>
 
98
        <replaceable>NAME</replaceable></arg>
 
99
      </group>
 
100
      <group choice="opt">
 
101
        <arg choice="plain"><option>--email</option>
 
102
        <replaceable>EMAIL</replaceable></arg>
 
103
      </group>
 
104
      <group choice="opt">
 
105
        <arg choice="plain"><option>--comment</option>
 
106
        <replaceable>COMMENT</replaceable></arg>
 
107
      </group>
 
108
      <group choice="opt">
 
109
        <arg choice="plain"><option>--expire</option>
 
110
        <replaceable>TIME</replaceable></arg>
 
111
      </group>
 
112
      <group choice="opt">
 
113
        <arg choice="plain"><option>--force</option></arg>
 
114
      </group>
 
115
    </cmdsynopsis>
 
116
    <cmdsynopsis>
 
117
      <command>&COMMANDNAME;</command>
 
118
      <group choice="opt">
 
119
        <arg choice="plain"><option>-d</option>
 
120
        <replaceable>directory</replaceable></arg>
 
121
      </group>
 
122
      <group choice="opt">
 
123
        <arg choice="plain"><option>-t</option>
 
124
        <replaceable>type</replaceable></arg>
 
125
      </group>
 
126
      <group choice="opt">
 
127
        <arg choice="plain"><option>-l</option>
 
128
        <replaceable>bits</replaceable></arg>
 
129
      </group>
 
130
      <group choice="opt">
 
131
        <arg choice="plain"><option>-s</option>
 
132
        <replaceable>type</replaceable></arg>
 
133
      </group>
 
134
      <group choice="opt">
 
135
        <arg choice="plain"><option>-L</option>
 
136
        <replaceable>bits</replaceable></arg>
 
137
      </group>
 
138
      <group choice="opt">
 
139
        <arg choice="plain"><option>-n</option>
 
140
        <replaceable>NAME</replaceable></arg>
 
141
      </group>
 
142
      <group choice="opt">
 
143
        <arg choice="plain"><option>-e</option>
 
144
        <replaceable>EMAIL</replaceable></arg>
 
145
      </group>
 
146
      <group choice="opt">
 
147
        <arg choice="plain"><option>-c</option>
 
148
        <replaceable>COMMENT</replaceable></arg>
 
149
      </group>
 
150
      <group choice="opt">
 
151
        <arg choice="plain"><option>-x</option>
 
152
        <replaceable>TIME</replaceable></arg>
 
153
      </group>
 
154
      <group choice="opt">
 
155
        <arg choice="plain"><option>-f</option></arg>
 
156
      </group>
119
157
    </cmdsynopsis>
120
158
    <cmdsynopsis>
121
159
      <command>&COMMANDNAME;</command>
122
160
      <group choice="req">
 
161
        <arg choice="plain"><option>-p</option></arg>
123
162
        <arg choice="plain"><option>--password</option></arg>
124
 
        <arg choice="plain"><option>-p</option></arg>
125
 
      </group>
126
 
      <sbr/>
127
 
      <group>
128
 
        <arg choice="plain"><option>--dir
129
 
        <replaceable>DIRECTORY</replaceable></option></arg>
130
 
        <arg choice="plain"><option>-d
131
 
        <replaceable>DIRECTORY</replaceable></option></arg>
132
 
      </group>
133
 
      <sbr/>
134
 
      <group>
135
 
        <arg choice="plain"><option>--name
136
 
        <replaceable>NAME</replaceable></option></arg>
137
 
        <arg choice="plain"><option>-n
138
 
        <replaceable>NAME</replaceable></option></arg>
 
163
      </group>
 
164
      <group choice="opt">
 
165
        <arg choice="plain"><option>--dir</option>
 
166
        <replaceable>directory</replaceable></arg>
 
167
      </group>
 
168
      <group choice="opt">
 
169
        <arg choice="plain"><option>--name</option>
 
170
        <replaceable>NAME</replaceable></arg>
139
171
      </group>
140
172
    </cmdsynopsis>
141
173
    <cmdsynopsis>
142
174
      <command>&COMMANDNAME;</command>
143
175
      <group choice="req">
 
176
        <arg choice="plain"><option>-h</option></arg>
144
177
        <arg choice="plain"><option>--help</option></arg>
145
 
        <arg choice="plain"><option>-h</option></arg>
146
178
      </group>
147
179
    </cmdsynopsis>
148
180
    <cmdsynopsis>
149
181
      <command>&COMMANDNAME;</command>
150
182
      <group choice="req">
 
183
        <arg choice="plain"><option>-v</option></arg>
151
184
        <arg choice="plain"><option>--version</option></arg>
152
 
        <arg choice="plain"><option>-v</option></arg>
153
185
      </group>
154
186
    </cmdsynopsis>
155
187
  </refsynopsisdiv>
156
 
  
 
188
 
157
189
  <refsect1 id="description">
158
190
    <title>DESCRIPTION</title>
159
191
    <para>
160
192
      <command>&COMMANDNAME;</command> is a program to generate the
161
 
      OpenPGP key used by
 
193
      OpenPGP keys used by
162
194
      <citerefentry><refentrytitle>password-request</refentrytitle>
163
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
 
195
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
164
196
      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.
 
197
      initrd image, but this, like most things, can be changed with
 
198
      command line options.
167
199
    </para>
168
200
    <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
 
201
      It can also be used to generate ready-made sections for
172
202
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
173
 
      <manvolnum>5</manvolnum></citerefentry>).
 
203
      <manvolnum>5</manvolnum></citerefentry> using the
 
204
      <option>--password</option> option.
174
205
    </para>
175
206
  </refsect1>
176
207
  
177
208
  <refsect1 id="purpose">
178
209
    <title>PURPOSE</title>
 
210
 
179
211
    <para>
180
212
      The purpose of this is to enable <emphasis>remote and unattended
181
213
      rebooting</emphasis> of client host computer with an
182
214
      <emphasis>encrypted root file system</emphasis>.  See <xref
183
215
      linkend="overview"/> for details.
184
216
    </para>
 
217
 
185
218
  </refsect1>
186
219
  
187
220
  <refsect1 id="options">
188
221
    <title>OPTIONS</title>
189
 
    
 
222
 
190
223
    <variablelist>
191
224
      <varlistentry>
192
 
        <term><option>--help</option></term>
193
 
        <term><option>-h</option></term>
 
225
        <term><literal>-h</literal>, <literal>--help</literal></term>
194
226
        <listitem>
195
227
          <para>
196
228
            Show a help message and exit
199
231
      </varlistentry>
200
232
 
201
233
      <varlistentry>
202
 
        <term><option>--dir
203
 
        <replaceable>DIRECTORY</replaceable></option></term>
204
 
        <term><option>-d
205
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
234
        <term><literal>-d</literal>, <literal>--dir
 
235
        <replaceable>directory</replaceable></literal></term>
206
236
        <listitem>
207
237
          <para>
208
238
            Target directory for key files.  Default is
212
242
      </varlistentry>
213
243
 
214
244
      <varlistentry>
215
 
        <term><option>--type
216
 
        <replaceable>TYPE</replaceable></option></term>
217
 
        <term><option>-t
218
 
        <replaceable>TYPE</replaceable></option></term>
 
245
        <term><literal>-t</literal>, <literal>--type
 
246
        <replaceable>type</replaceable></literal></term>
219
247
        <listitem>
220
248
          <para>
221
249
            Key type.  Default is <quote>DSA</quote>.
224
252
      </varlistentry>
225
253
 
226
254
      <varlistentry>
227
 
        <term><option>--length
228
 
        <replaceable>BITS</replaceable></option></term>
229
 
        <term><option>-l
230
 
        <replaceable>BITS</replaceable></option></term>
 
255
        <term><literal>-l</literal>, <literal>--length
 
256
        <replaceable>bits</replaceable></literal></term>
231
257
        <listitem>
232
258
          <para>
233
 
            Key length in bits.  Default is 2048.
 
259
            Key length in bits.  Default is 1024.
234
260
          </para>
235
261
        </listitem>
236
262
      </varlistentry>
237
263
 
238
264
      <varlistentry>
239
 
        <term><option>--subtype
240
 
        <replaceable>KEYTYPE</replaceable></option></term>
241
 
        <term><option>-s
242
 
        <replaceable>KEYTYPE</replaceable></option></term>
 
265
        <term><literal>-s</literal>, <literal>--subtype
 
266
        <replaceable>type</replaceable></literal></term>
243
267
        <listitem>
244
268
          <para>
245
269
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
249
273
      </varlistentry>
250
274
 
251
275
      <varlistentry>
252
 
        <term><option>--sublength
253
 
        <replaceable>BITS</replaceable></option></term>
254
 
        <term><option>-L
255
 
        <replaceable>BITS</replaceable></option></term>
 
276
        <term><literal>-L</literal>, <literal>--sublength
 
277
        <replaceable>bits</replaceable></literal></term>
256
278
        <listitem>
257
279
          <para>
258
280
            Subkey length in bits.  Default is 2048.
261
283
      </varlistentry>
262
284
 
263
285
      <varlistentry>
264
 
        <term><option>--email
265
 
        <replaceable>ADDRESS</replaceable></option></term>
266
 
        <term><option>-e
267
 
        <replaceable>ADDRESS</replaceable></option></term>
 
286
        <term><literal>-e</literal>, <literal>--email</literal>
 
287
        <replaceable>address</replaceable></term>
268
288
        <listitem>
269
289
          <para>
270
290
            Email address of key.  Default is empty.
273
293
      </varlistentry>
274
294
 
275
295
      <varlistentry>
276
 
        <term><option>--comment
277
 
        <replaceable>TEXT</replaceable></option></term>
278
 
        <term><option>-c
279
 
        <replaceable>TEXT</replaceable></option></term>
 
296
        <term><literal>-c</literal>, <literal>--comment</literal>
 
297
        <replaceable>comment</replaceable></term>
280
298
        <listitem>
281
299
          <para>
282
300
            Comment field for key.  The default value is
286
304
      </varlistentry>
287
305
 
288
306
      <varlistentry>
289
 
        <term><option>--expire
290
 
        <replaceable>TIME</replaceable></option></term>
291
 
        <term><option>-x
292
 
        <replaceable>TIME</replaceable></option></term>
 
307
        <term><literal>-x</literal>, <literal>--expire</literal>
 
308
        <replaceable>time</replaceable></term>
293
309
        <listitem>
294
310
          <para>
295
311
            Key expire time.  Default is no expiration.  See
300
316
      </varlistentry>
301
317
 
302
318
      <varlistentry>
303
 
        <term><option>--force</option></term>
304
 
        <term><option>-f</option></term>
 
319
        <term><literal>-f</literal>, <literal>--force</literal></term>
305
320
        <listitem>
306
321
          <para>
307
 
            Force overwriting old key.
 
322
            Force overwriting old keys.
308
323
          </para>
309
324
        </listitem>
310
325
      </varlistentry>
311
326
      <varlistentry>
312
 
        <term><option>--password</option></term>
313
 
        <term><option>-p</option></term>
 
327
        <term><literal>-p</literal>, <literal>--password</literal
 
328
        ></term>
314
329
        <listitem>
315
330
          <para>
316
331
            Prompt for a password and encrypt it with the key already
322
337
            >8</manvolnum></citerefentry>.  The host name or the name
323
338
            specified with the <option>--name</option> option is used
324
339
            for the section header.  All other options are ignored,
325
 
            and no key is created.
 
340
            and no keys are created.
326
341
          </para>
327
342
        </listitem>
328
343
      </varlistentry>
334
349
    <xi:include href="overview.xml"/>
335
350
    <para>
336
351
      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.
 
352
      new Mandos clients.
339
353
    </para>
340
354
  </refsect1>
341
355
 
342
356
  <refsect1 id="exit_status">
343
357
    <title>EXIT STATUS</title>
344
358
    <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.
 
359
      The exit status will be 0 if new keys were successfully created,
 
360
      otherwise not.
348
361
    </para>
349
362
  </refsect1>
350
363
  
352
365
    <title>ENVIRONMENT</title>
353
366
    <variablelist>
354
367
      <varlistentry>
355
 
        <term><envar>TMPDIR</envar></term>
 
368
        <term><varname>TMPDIR</varname></term>
356
369
        <listitem>
357
370
          <para>
358
371
            If set, temporary files will be created here. See
416
429
        Normal invocation needs no options:
417
430
      </para>
418
431
      <para>
419
 
        <userinput>&COMMANDNAME;</userinput>
 
432
        <userinput>mandos-keygen</userinput>
420
433
      </para>
421
434
    </informalexample>
422
435
    <informalexample>
423
436
      <para>
424
 
        Create key in another directory and of another type.  Force
 
437
        Create keys in another directory and of another type.  Force
425
438
        overwriting old key files:
426
439
      </para>
427
440
      <para>
428
441
 
429
442
<!-- do not wrap this line -->
430
 
<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>
431
 
 
432
 
      </para>
433
 
    </informalexample>
434
 
    <informalexample>
435
 
      <para>
436
 
        Prompt for a password, encrypt it with the key in
437
 
        <filename>/etc/mandos</filename> and output a section suitable
438
 
        for <filename>clients.conf</filename>.
439
 
      </para>
440
 
      <para>
441
 
        <userinput>&COMMANDNAME; --password</userinput>
442
 
      </para>
443
 
    </informalexample>
444
 
    <informalexample>
445
 
      <para>
446
 
        Prompt for a password, encrypt it with the key in the
447
 
        <filename>client-key</filename> directory and output a section
448
 
        suitable for <filename>clients.conf</filename>.
449
 
      </para>
450
 
      <para>
451
 
 
452
 
<!-- do not wrap this line -->
453
 
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
 
443
<userinput>mandos-keygen --dir ~/keydir --type RSA --force</userinput>
454
444
 
455
445
      </para>
456
446
    </informalexample>
461
451
    <para>
462
452
      The <option>--type</option>, <option>--length</option>,
463
453
      <option>--subtype</option>, and <option>--sublength</option>
464
 
      options can be used to create keys of low security.  If in
465
 
      doubt, leave them to the default values.
 
454
      options can be used to create keys of insufficient security.  If
 
455
      in doubt, leave them to the default values.
466
456
    </para>
467
457
    <para>
468
 
      The key expire time is <emphasis>not</emphasis> guaranteed to be
469
 
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
 
458
      The key expire time is not guaranteed to be honored by
 
459
      <citerefentry><refentrytitle>mandos</refentrytitle>
470
460
      <manvolnum>8</manvolnum></citerefentry>.
471
461
    </para>
472
462
  </refsect1>
474
464
  <refsect1 id="see_also">
475
465
    <title>SEE ALSO</title>
476
466
    <para>
 
467
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
468
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
469
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
470
      <manvolnum>8</manvolnum></citerefentry>,
477
471
      <citerefentry><refentrytitle>gpg</refentrytitle>
478
 
      <manvolnum>1</manvolnum></citerefentry>,
479
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
480
 
      <manvolnum>5</manvolnum></citerefentry>,
481
 
      <citerefentry><refentrytitle>mandos</refentrytitle>
482
 
      <manvolnum>8</manvolnum></citerefentry>,
483
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
484
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
472
      <manvolnum>1</manvolnum></citerefentry>
485
473
    </para>
486
474
  </refsect1>
487
475
  
488
476
</refentry>
489
 
<!-- Local Variables: -->
490
 
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
491
 
<!-- time-stamp-end: "[\"']>" -->
492
 
<!-- time-stamp-format: "%:y-%02m-%02d" -->
493
 
<!-- End: -->