/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-09-08 18:54:47 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080908185447-dm2ertwxa20qbckf
* INSTALL: Even better text.

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