/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-29 06:38:27 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080829063827-hbjl6t92tyjl5305
* mandos-clients.conf.xml (ENTITY TIMESTAMP): New.  Automatically
                                              updated by Emacs
                                              time-stamp by using
                                              Emacs local variables.
  (/refentry/refentryinfo/date): New; set to "&TIMESTAMP;".
* mandos-keygen.xml: - '' -
* mandos.conf.xml: - '' -
* mandos.xml: - '' -
* plugin-runner.xml: - '' -
* plugins.d/password-request.xml: - '' -

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">
 
6
<!ENTITY TIMESTAMP "2008-08-29">
7
7
]>
8
8
 
9
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
10
10
  <refentryinfo>
11
 
    <title>Mandos Manual</title>
 
11
    <title>&COMMANDNAME;</title>
12
12
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
 
    <productname>Mandos</productname>
 
13
    <productname>&COMMANDNAME;</productname>
14
14
    <productnumber>&VERSION;</productnumber>
15
15
    <date>&TIMESTAMP;</date>
16
16
    <authorgroup>
67
67
  <refnamediv>
68
68
    <refname><command>&COMMANDNAME;</command></refname>
69
69
    <refpurpose>
70
 
      Generate key and password for Mandos client and server.
 
70
      Generate keys for <citerefentry><refentrytitle>password-request
 
71
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
71
72
    </refpurpose>
72
73
  </refnamediv>
73
74
 
74
75
  <refsynopsisdiv>
75
76
    <cmdsynopsis>
76
77
      <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>
 
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>
141
159
    </cmdsynopsis>
142
160
    <cmdsynopsis>
143
161
      <command>&COMMANDNAME;</command>
144
162
      <group choice="req">
 
163
        <arg choice="plain"><option>-p</option></arg>
145
164
        <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>
 
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>
161
173
      </group>
162
174
    </cmdsynopsis>
163
175
    <cmdsynopsis>
164
176
      <command>&COMMANDNAME;</command>
165
177
      <group choice="req">
 
178
        <arg choice="plain"><option>-h</option></arg>
166
179
        <arg choice="plain"><option>--help</option></arg>
167
 
        <arg choice="plain"><option>-h</option></arg>
168
180
      </group>
169
181
    </cmdsynopsis>
170
182
    <cmdsynopsis>
171
183
      <command>&COMMANDNAME;</command>
172
184
      <group choice="req">
 
185
        <arg choice="plain"><option>-v</option></arg>
173
186
        <arg choice="plain"><option>--version</option></arg>
174
 
        <arg choice="plain"><option>-v</option></arg>
175
187
      </group>
176
188
    </cmdsynopsis>
177
189
  </refsynopsisdiv>
178
 
  
 
190
 
179
191
  <refsect1 id="description">
180
192
    <title>DESCRIPTION</title>
181
193
    <para>
182
194
      <command>&COMMANDNAME;</command> is a program to generate the
183
 
      OpenPGP key used by
 
195
      OpenPGP keys used by
184
196
      <citerefentry><refentrytitle>password-request</refentrytitle>
185
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
 
197
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
186
198
      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.
 
199
      initrd image, but this, like most things, can be changed with
 
200
      command line options.
189
201
    </para>
190
202
    <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
 
203
      It can also be used to generate ready-made sections for
194
204
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
195
 
      <manvolnum>5</manvolnum></citerefentry>).
 
205
      <manvolnum>5</manvolnum></citerefentry> using the
 
206
      <option>--password</option> option.
196
207
    </para>
197
208
  </refsect1>
198
209
  
199
210
  <refsect1 id="purpose">
200
211
    <title>PURPOSE</title>
 
212
 
201
213
    <para>
202
214
      The purpose of this is to enable <emphasis>remote and unattended
203
215
      rebooting</emphasis> of client host computer with an
204
216
      <emphasis>encrypted root file system</emphasis>.  See <xref
205
217
      linkend="overview"/> for details.
206
218
    </para>
 
219
 
207
220
  </refsect1>
208
221
  
209
222
  <refsect1 id="options">
210
223
    <title>OPTIONS</title>
211
 
    
 
224
 
212
225
    <variablelist>
213
226
      <varlistentry>
214
 
        <term><option>--help</option></term>
215
 
        <term><option>-h</option></term>
 
227
        <term><literal>-h</literal>, <literal>--help</literal></term>
216
228
        <listitem>
217
229
          <para>
218
230
            Show a help message and exit
221
233
      </varlistentry>
222
234
 
223
235
      <varlistentry>
224
 
        <term><option>--dir
225
 
        <replaceable>DIRECTORY</replaceable></option></term>
226
 
        <term><option>-d
227
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
236
        <term><literal>-d</literal>, <literal>--dir
 
237
        <replaceable>directory</replaceable></literal></term>
228
238
        <listitem>
229
239
          <para>
230
240
            Target directory for key files.  Default is
234
244
      </varlistentry>
235
245
 
236
246
      <varlistentry>
237
 
        <term><option>--type
238
 
        <replaceable>TYPE</replaceable></option></term>
239
 
        <term><option>-t
240
 
        <replaceable>TYPE</replaceable></option></term>
 
247
        <term><literal>-t</literal>, <literal>--type
 
248
        <replaceable>type</replaceable></literal></term>
241
249
        <listitem>
242
250
          <para>
243
251
            Key type.  Default is <quote>DSA</quote>.
246
254
      </varlistentry>
247
255
 
248
256
      <varlistentry>
249
 
        <term><option>--length
250
 
        <replaceable>BITS</replaceable></option></term>
251
 
        <term><option>-l
252
 
        <replaceable>BITS</replaceable></option></term>
 
257
        <term><literal>-l</literal>, <literal>--length
 
258
        <replaceable>bits</replaceable></literal></term>
253
259
        <listitem>
254
260
          <para>
255
261
            Key length in bits.  Default is 2048.
258
264
      </varlistentry>
259
265
 
260
266
      <varlistentry>
261
 
        <term><option>--subtype
262
 
        <replaceable>KEYTYPE</replaceable></option></term>
263
 
        <term><option>-s
264
 
        <replaceable>KEYTYPE</replaceable></option></term>
 
267
        <term><literal>-s</literal>, <literal>--subtype
 
268
        <replaceable>type</replaceable></literal></term>
265
269
        <listitem>
266
270
          <para>
267
271
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
271
275
      </varlistentry>
272
276
 
273
277
      <varlistentry>
274
 
        <term><option>--sublength
275
 
        <replaceable>BITS</replaceable></option></term>
276
 
        <term><option>-L
277
 
        <replaceable>BITS</replaceable></option></term>
 
278
        <term><literal>-L</literal>, <literal>--sublength
 
279
        <replaceable>bits</replaceable></literal></term>
278
280
        <listitem>
279
281
          <para>
280
282
            Subkey length in bits.  Default is 2048.
283
285
      </varlistentry>
284
286
 
285
287
      <varlistentry>
286
 
        <term><option>--email
287
 
        <replaceable>ADDRESS</replaceable></option></term>
288
 
        <term><option>-e
289
 
        <replaceable>ADDRESS</replaceable></option></term>
 
288
        <term><literal>-e</literal>, <literal>--email</literal>
 
289
        <replaceable>address</replaceable></term>
290
290
        <listitem>
291
291
          <para>
292
292
            Email address of key.  Default is empty.
295
295
      </varlistentry>
296
296
 
297
297
      <varlistentry>
298
 
        <term><option>--comment
299
 
        <replaceable>TEXT</replaceable></option></term>
300
 
        <term><option>-c
301
 
        <replaceable>TEXT</replaceable></option></term>
 
298
        <term><literal>-c</literal>, <literal>--comment</literal>
 
299
        <replaceable>comment</replaceable></term>
302
300
        <listitem>
303
301
          <para>
304
302
            Comment field for key.  The default value is
308
306
      </varlistentry>
309
307
 
310
308
      <varlistentry>
311
 
        <term><option>--expire
312
 
        <replaceable>TIME</replaceable></option></term>
313
 
        <term><option>-x
314
 
        <replaceable>TIME</replaceable></option></term>
 
309
        <term><literal>-x</literal>, <literal>--expire</literal>
 
310
        <replaceable>time</replaceable></term>
315
311
        <listitem>
316
312
          <para>
317
313
            Key expire time.  Default is no expiration.  See
322
318
      </varlistentry>
323
319
 
324
320
      <varlistentry>
325
 
        <term><option>--force</option></term>
326
 
        <term><option>-f</option></term>
 
321
        <term><literal>-f</literal>, <literal>--force</literal></term>
327
322
        <listitem>
328
323
          <para>
329
 
            Force overwriting old key.
 
324
            Force overwriting old keys.
330
325
          </para>
331
326
        </listitem>
332
327
      </varlistentry>
333
328
      <varlistentry>
334
 
        <term><option>--password</option></term>
335
 
        <term><option>-p</option></term>
 
329
        <term><literal>-p</literal>, <literal>--password</literal
 
330
        ></term>
336
331
        <listitem>
337
332
          <para>
338
333
            Prompt for a password and encrypt it with the key already
344
339
            >8</manvolnum></citerefentry>.  The host name or the name
345
340
            specified with the <option>--name</option> option is used
346
341
            for the section header.  All other options are ignored,
347
 
            and no key is created.
 
342
            and no keys are created.
348
343
          </para>
349
344
        </listitem>
350
345
      </varlistentry>
356
351
    <xi:include href="overview.xml"/>
357
352
    <para>
358
353
      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.
 
354
      new Mandos clients.
361
355
    </para>
362
356
  </refsect1>
363
357
 
364
358
  <refsect1 id="exit_status">
365
359
    <title>EXIT STATUS</title>
366
360
    <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.
 
361
      The exit status will be 0 if new keys were successfully created,
 
362
      otherwise not.
370
363
    </para>
371
364
  </refsect1>
372
365
  
374
367
    <title>ENVIRONMENT</title>
375
368
    <variablelist>
376
369
      <varlistentry>
377
 
        <term><envar>TMPDIR</envar></term>
 
370
        <term><varname>TMPDIR</varname></term>
378
371
        <listitem>
379
372
          <para>
380
373
            If set, temporary files will be created here. See
438
431
        Normal invocation needs no options:
439
432
      </para>
440
433
      <para>
441
 
        <userinput>&COMMANDNAME;</userinput>
 
434
        <userinput>mandos-keygen</userinput>
442
435
      </para>
443
436
    </informalexample>
444
437
    <informalexample>
445
438
      <para>
446
 
        Create key in another directory and of another type.  Force
 
439
        Create keys in another directory and of another type.  Force
447
440
        overwriting old key files:
448
441
      </para>
449
442
      <para>
450
443
 
451
444
<!-- 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>
 
445
<userinput>mandos-keygen --dir ~/keydir --type RSA --force</userinput>
476
446
 
477
447
      </para>
478
448
    </informalexample>
483
453
    <para>
484
454
      The <option>--type</option>, <option>--length</option>,
485
455
      <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.
 
456
      options can be used to create keys of insufficient security.  If
 
457
      in doubt, leave them to the default values.
488
458
    </para>
489
459
    <para>
490
 
      The key expire time is <emphasis>not</emphasis> guaranteed to be
491
 
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
 
460
      The key expire time is not guaranteed to be honored by
 
461
      <citerefentry><refentrytitle>mandos</refentrytitle>
492
462
      <manvolnum>8</manvolnum></citerefentry>.
493
463
    </para>
494
464
  </refsect1>
496
466
  <refsect1 id="see_also">
497
467
    <title>SEE ALSO</title>
498
468
    <para>
 
469
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
470
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
471
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
472
      <manvolnum>8</manvolnum></citerefentry>,
499
473
      <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>
 
474
      <manvolnum>1</manvolnum></citerefentry>
507
475
    </para>
508
476
  </refsect1>
509
477