/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

merge

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>
67
65
  <refnamediv>
68
66
    <refname><command>&COMMANDNAME;</command></refname>
69
67
    <refpurpose>
70
 
      Generate key and password for Mandos client and server.
 
68
      Generate keys for <citerefentry><refentrytitle>password-request
 
69
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
71
70
    </refpurpose>
72
71
  </refnamediv>
73
72
 
74
73
  <refsynopsisdiv>
75
74
    <cmdsynopsis>
76
75
      <command>&COMMANDNAME;</command>
77
 
      <group>
78
 
        <arg choice="plain"><option>--dir
79
 
        <replaceable>DIRECTORY</replaceable></option></arg>
80
 
        <arg choice="plain"><option>-d
81
 
        <replaceable>DIRECTORY</replaceable></option></arg>
82
 
      </group>
83
 
      <sbr/>
84
 
      <group>
85
 
        <arg choice="plain"><option>--type
86
 
        <replaceable>KEYTYPE</replaceable></option></arg>
87
 
        <arg choice="plain"><option>-t
88
 
        <replaceable>KEYTYPE</replaceable></option></arg>
89
 
      </group>
90
 
      <sbr/>
91
 
      <group>
92
 
        <arg choice="plain"><option>--length
93
 
        <replaceable>BITS</replaceable></option></arg>
94
 
        <arg choice="plain"><option>-l
95
 
        <replaceable>BITS</replaceable></option></arg>
96
 
      </group>
97
 
      <sbr/>
98
 
      <group>
99
 
        <arg choice="plain"><option>--subtype
100
 
        <replaceable>KEYTYPE</replaceable></option></arg>
101
 
        <arg choice="plain"><option>-s
102
 
        <replaceable>KEYTYPE</replaceable></option></arg>
103
 
      </group>
104
 
      <sbr/>
105
 
      <group>
106
 
        <arg choice="plain"><option>--sublength
107
 
        <replaceable>BITS</replaceable></option></arg>
108
 
        <arg choice="plain"><option>-L
109
 
        <replaceable>BITS</replaceable></option></arg>
110
 
      </group>
111
 
      <sbr/>
112
 
      <group>
113
 
        <arg choice="plain"><option>--name
114
 
        <replaceable>NAME</replaceable></option></arg>
115
 
        <arg choice="plain"><option>-n
116
 
        <replaceable>NAME</replaceable></option></arg>
117
 
      </group>
118
 
      <sbr/>
119
 
      <group>
120
 
        <arg choice="plain"><option>--email
121
 
        <replaceable>ADDRESS</replaceable></option></arg>
122
 
        <arg choice="plain"><option>-e
123
 
        <replaceable>ADDRESS</replaceable></option></arg>
124
 
      </group>
125
 
      <sbr/>
126
 
      <group>
127
 
        <arg choice="plain"><option>--comment
128
 
        <replaceable>TEXT</replaceable></option></arg>
129
 
        <arg choice="plain"><option>-c
130
 
        <replaceable>TEXT</replaceable></option></arg>
131
 
      </group>
132
 
      <sbr/>
133
 
      <group>
134
 
        <arg choice="plain"><option>--expire
135
 
        <replaceable>TIME</replaceable></option></arg>
136
 
        <arg choice="plain"><option>-x
137
 
        <replaceable>TIME</replaceable></option></arg>
138
 
      </group>
139
 
      <sbr/>
140
 
      <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>
141
157
    </cmdsynopsis>
142
158
    <cmdsynopsis>
143
159
      <command>&COMMANDNAME;</command>
144
160
      <group choice="req">
 
161
        <arg choice="plain"><option>-p</option></arg>
145
162
        <arg choice="plain"><option>--password</option></arg>
146
 
        <arg choice="plain"><option>-p</option></arg>
147
 
      </group>
148
 
      <sbr/>
149
 
      <group>
150
 
        <arg choice="plain"><option>--dir
151
 
        <replaceable>DIRECTORY</replaceable></option></arg>
152
 
        <arg choice="plain"><option>-d
153
 
        <replaceable>DIRECTORY</replaceable></option></arg>
154
 
      </group>
155
 
      <sbr/>
156
 
      <group>
157
 
        <arg choice="plain"><option>--name
158
 
        <replaceable>NAME</replaceable></option></arg>
159
 
        <arg choice="plain"><option>-n
160
 
        <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>
161
171
      </group>
162
172
    </cmdsynopsis>
163
173
    <cmdsynopsis>
164
174
      <command>&COMMANDNAME;</command>
165
175
      <group choice="req">
 
176
        <arg choice="plain"><option>-h</option></arg>
166
177
        <arg choice="plain"><option>--help</option></arg>
167
 
        <arg choice="plain"><option>-h</option></arg>
168
178
      </group>
169
179
    </cmdsynopsis>
170
180
    <cmdsynopsis>
171
181
      <command>&COMMANDNAME;</command>
172
182
      <group choice="req">
 
183
        <arg choice="plain"><option>-v</option></arg>
173
184
        <arg choice="plain"><option>--version</option></arg>
174
 
        <arg choice="plain"><option>-v</option></arg>
175
185
      </group>
176
186
    </cmdsynopsis>
177
187
  </refsynopsisdiv>
178
 
  
 
188
 
179
189
  <refsect1 id="description">
180
190
    <title>DESCRIPTION</title>
181
191
    <para>
182
192
      <command>&COMMANDNAME;</command> is a program to generate the
183
 
      OpenPGP key used by
 
193
      OpenPGP keys used by
184
194
      <citerefentry><refentrytitle>password-request</refentrytitle>
185
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
 
195
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
186
196
      normally written to /etc/mandos for later installation into the
187
 
      initrd image, but this, and most other things, can be changed
188
 
      with command line options.
 
197
      initrd image, but this, like most things, can be changed with
 
198
      command line options.
189
199
    </para>
190
200
    <para>
191
 
      This program can also be used with the
192
 
      <option>--password</option> option to generate a ready-made
193
 
      section for <filename>clients.conf</filename> (see
 
201
      It can also be used to generate ready-made sections for
194
202
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
195
 
      <manvolnum>5</manvolnum></citerefentry>).
 
203
      <manvolnum>5</manvolnum></citerefentry> using the
 
204
      <option>--password</option> option.
196
205
    </para>
197
206
  </refsect1>
198
207
  
199
208
  <refsect1 id="purpose">
200
209
    <title>PURPOSE</title>
 
210
 
201
211
    <para>
202
212
      The purpose of this is to enable <emphasis>remote and unattended
203
213
      rebooting</emphasis> of client host computer with an
204
214
      <emphasis>encrypted root file system</emphasis>.  See <xref
205
215
      linkend="overview"/> for details.
206
216
    </para>
 
217
 
207
218
  </refsect1>
208
219
  
209
220
  <refsect1 id="options">
210
221
    <title>OPTIONS</title>
211
 
    
 
222
 
212
223
    <variablelist>
213
224
      <varlistentry>
214
 
        <term><option>--help</option></term>
215
 
        <term><option>-h</option></term>
 
225
        <term><literal>-h</literal>, <literal>--help</literal></term>
216
226
        <listitem>
217
227
          <para>
218
228
            Show a help message and exit
221
231
      </varlistentry>
222
232
 
223
233
      <varlistentry>
224
 
        <term><option>--dir
225
 
        <replaceable>DIRECTORY</replaceable></option></term>
226
 
        <term><option>-d
227
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
234
        <term><literal>-d</literal>, <literal>--dir
 
235
        <replaceable>directory</replaceable></literal></term>
228
236
        <listitem>
229
237
          <para>
230
238
            Target directory for key files.  Default is
234
242
      </varlistentry>
235
243
 
236
244
      <varlistentry>
237
 
        <term><option>--type
238
 
        <replaceable>TYPE</replaceable></option></term>
239
 
        <term><option>-t
240
 
        <replaceable>TYPE</replaceable></option></term>
 
245
        <term><literal>-t</literal>, <literal>--type
 
246
        <replaceable>type</replaceable></literal></term>
241
247
        <listitem>
242
248
          <para>
243
249
            Key type.  Default is <quote>DSA</quote>.
246
252
      </varlistentry>
247
253
 
248
254
      <varlistentry>
249
 
        <term><option>--length
250
 
        <replaceable>BITS</replaceable></option></term>
251
 
        <term><option>-l
252
 
        <replaceable>BITS</replaceable></option></term>
 
255
        <term><literal>-l</literal>, <literal>--length
 
256
        <replaceable>bits</replaceable></literal></term>
253
257
        <listitem>
254
258
          <para>
255
259
            Key length in bits.  Default is 2048.
258
262
      </varlistentry>
259
263
 
260
264
      <varlistentry>
261
 
        <term><option>--subtype
262
 
        <replaceable>KEYTYPE</replaceable></option></term>
263
 
        <term><option>-s
264
 
        <replaceable>KEYTYPE</replaceable></option></term>
 
265
        <term><literal>-s</literal>, <literal>--subtype
 
266
        <replaceable>type</replaceable></literal></term>
265
267
        <listitem>
266
268
          <para>
267
269
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
271
273
      </varlistentry>
272
274
 
273
275
      <varlistentry>
274
 
        <term><option>--sublength
275
 
        <replaceable>BITS</replaceable></option></term>
276
 
        <term><option>-L
277
 
        <replaceable>BITS</replaceable></option></term>
 
276
        <term><literal>-L</literal>, <literal>--sublength
 
277
        <replaceable>bits</replaceable></literal></term>
278
278
        <listitem>
279
279
          <para>
280
280
            Subkey length in bits.  Default is 2048.
283
283
      </varlistentry>
284
284
 
285
285
      <varlistentry>
286
 
        <term><option>--email
287
 
        <replaceable>ADDRESS</replaceable></option></term>
288
 
        <term><option>-e
289
 
        <replaceable>ADDRESS</replaceable></option></term>
 
286
        <term><literal>-e</literal>, <literal>--email</literal>
 
287
        <replaceable>address</replaceable></term>
290
288
        <listitem>
291
289
          <para>
292
290
            Email address of key.  Default is empty.
295
293
      </varlistentry>
296
294
 
297
295
      <varlistentry>
298
 
        <term><option>--comment
299
 
        <replaceable>TEXT</replaceable></option></term>
300
 
        <term><option>-c
301
 
        <replaceable>TEXT</replaceable></option></term>
 
296
        <term><literal>-c</literal>, <literal>--comment</literal>
 
297
        <replaceable>comment</replaceable></term>
302
298
        <listitem>
303
299
          <para>
304
300
            Comment field for key.  The default value is
308
304
      </varlistentry>
309
305
 
310
306
      <varlistentry>
311
 
        <term><option>--expire
312
 
        <replaceable>TIME</replaceable></option></term>
313
 
        <term><option>-x
314
 
        <replaceable>TIME</replaceable></option></term>
 
307
        <term><literal>-x</literal>, <literal>--expire</literal>
 
308
        <replaceable>time</replaceable></term>
315
309
        <listitem>
316
310
          <para>
317
311
            Key expire time.  Default is no expiration.  See
322
316
      </varlistentry>
323
317
 
324
318
      <varlistentry>
325
 
        <term><option>--force</option></term>
326
 
        <term><option>-f</option></term>
 
319
        <term><literal>-f</literal>, <literal>--force</literal></term>
327
320
        <listitem>
328
321
          <para>
329
 
            Force overwriting old key.
 
322
            Force overwriting old keys.
330
323
          </para>
331
324
        </listitem>
332
325
      </varlistentry>
333
326
      <varlistentry>
334
 
        <term><option>--password</option></term>
335
 
        <term><option>-p</option></term>
 
327
        <term><literal>-p</literal>, <literal>--password</literal
 
328
        ></term>
336
329
        <listitem>
337
330
          <para>
338
331
            Prompt for a password and encrypt it with the key already
344
337
            >8</manvolnum></citerefentry>.  The host name or the name
345
338
            specified with the <option>--name</option> option is used
346
339
            for the section header.  All other options are ignored,
347
 
            and no key is created.
 
340
            and no keys are created.
348
341
          </para>
349
342
        </listitem>
350
343
      </varlistentry>
356
349
    <xi:include href="overview.xml"/>
357
350
    <para>
358
351
      This program is a small utility to generate new OpenPGP keys for
359
 
      new Mandos clients, and to generate sections for inclusion in
360
 
      <filename>clients.conf</filename> on the server.
 
352
      new Mandos clients.
361
353
    </para>
362
354
  </refsect1>
363
355
 
364
356
  <refsect1 id="exit_status">
365
357
    <title>EXIT STATUS</title>
366
358
    <para>
367
 
      The exit status will be 0 if a new key (or password, if the
368
 
      <option>--password</option> option was used) was successfully
369
 
      created, otherwise not.
 
359
      The exit status will be 0 if new keys were successfully created,
 
360
      otherwise not.
370
361
    </para>
371
362
  </refsect1>
372
363
  
374
365
    <title>ENVIRONMENT</title>
375
366
    <variablelist>
376
367
      <varlistentry>
377
 
        <term><envar>TMPDIR</envar></term>
 
368
        <term><varname>TMPDIR</varname></term>
378
369
        <listitem>
379
370
          <para>
380
371
            If set, temporary files will be created here. See
438
429
        Normal invocation needs no options:
439
430
      </para>
440
431
      <para>
441
 
        <userinput>&COMMANDNAME;</userinput>
 
432
        <userinput>mandos-keygen</userinput>
442
433
      </para>
443
434
    </informalexample>
444
435
    <informalexample>
445
436
      <para>
446
 
        Create key in another directory and of another type.  Force
 
437
        Create keys in another directory and of another type.  Force
447
438
        overwriting old key files:
448
439
      </para>
449
440
      <para>
450
441
 
451
442
<!-- do not wrap this line -->
452
 
<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>
453
 
 
454
 
      </para>
455
 
    </informalexample>
456
 
    <informalexample>
457
 
      <para>
458
 
        Prompt for a password, encrypt it with the key in
459
 
        <filename>/etc/mandos</filename> and output a section suitable
460
 
        for <filename>clients.conf</filename>.
461
 
      </para>
462
 
      <para>
463
 
        <userinput>&COMMANDNAME; --password</userinput>
464
 
      </para>
465
 
    </informalexample>
466
 
    <informalexample>
467
 
      <para>
468
 
        Prompt for a password, encrypt it with the key in the
469
 
        <filename>client-key</filename> directory and output a section
470
 
        suitable for <filename>clients.conf</filename>.
471
 
      </para>
472
 
      <para>
473
 
 
474
 
<!-- do not wrap this line -->
475
 
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
 
443
<userinput>mandos-keygen --dir ~/keydir --type RSA --force</userinput>
476
444
 
477
445
      </para>
478
446
    </informalexample>
483
451
    <para>
484
452
      The <option>--type</option>, <option>--length</option>,
485
453
      <option>--subtype</option>, and <option>--sublength</option>
486
 
      options can be used to create keys of low security.  If in
487
 
      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.
488
456
    </para>
489
457
    <para>
490
 
      The key expire time is <emphasis>not</emphasis> guaranteed to be
491
 
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
 
458
      The key expire time is not guaranteed to be honored by
 
459
      <citerefentry><refentrytitle>mandos</refentrytitle>
492
460
      <manvolnum>8</manvolnum></citerefentry>.
493
461
    </para>
494
462
  </refsect1>
496
464
  <refsect1 id="see_also">
497
465
    <title>SEE ALSO</title>
498
466
    <para>
 
467
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
468
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
469
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
470
      <manvolnum>8</manvolnum></citerefentry>,
499
471
      <citerefentry><refentrytitle>gpg</refentrytitle>
500
 
      <manvolnum>1</manvolnum></citerefentry>,
501
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
502
 
      <manvolnum>5</manvolnum></citerefentry>,
503
 
      <citerefentry><refentrytitle>mandos</refentrytitle>
504
 
      <manvolnum>8</manvolnum></citerefentry>,
505
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
506
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
472
      <manvolnum>1</manvolnum></citerefentry>
507
473
    </para>
508
474
  </refsect1>
509
475
  
510
476
</refentry>
511
 
<!-- Local Variables: -->
512
 
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
513
 
<!-- time-stamp-end: "[\"']>" -->
514
 
<!-- time-stamp-format: "%:y-%02m-%02d" -->
515
 
<!-- End: -->