/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

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>
119
 
    </cmdsynopsis>
120
 
    <cmdsynopsis>
121
 
      <command>&COMMANDNAME;</command>
122
 
      <group choice="req">
123
 
        <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>
139
 
      </group>
140
 
    </cmdsynopsis>
141
 
    <cmdsynopsis>
142
 
      <command>&COMMANDNAME;</command>
143
 
      <group choice="req">
 
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>
 
157
    </cmdsynopsis>
 
158
    <cmdsynopsis>
 
159
      <command>&COMMANDNAME;</command>
 
160
      <group choice="req">
 
161
        <arg choice="plain"><option>-h</option></arg>
144
162
        <arg choice="plain"><option>--help</option></arg>
145
 
        <arg choice="plain"><option>-h</option></arg>
146
163
      </group>
147
164
    </cmdsynopsis>
148
165
    <cmdsynopsis>
149
166
      <command>&COMMANDNAME;</command>
150
167
      <group choice="req">
 
168
        <arg choice="plain"><option>-v</option></arg>
151
169
        <arg choice="plain"><option>--version</option></arg>
152
 
        <arg choice="plain"><option>-v</option></arg>
153
170
      </group>
154
171
    </cmdsynopsis>
155
172
  </refsynopsisdiv>
156
 
  
 
173
 
157
174
  <refsect1 id="description">
158
175
    <title>DESCRIPTION</title>
159
176
    <para>
160
177
      <command>&COMMANDNAME;</command> is a program to generate the
161
 
      OpenPGP key used by
 
178
      OpenPGP keys used by
162
179
      <citerefentry><refentrytitle>password-request</refentrytitle>
163
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
 
180
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
164
181
      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.
167
 
    </para>
168
 
    <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
172
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
173
 
      <manvolnum>5</manvolnum></citerefentry>).
 
182
      initrd image, but this, like most things, can be changed with
 
183
      command line options.
174
184
    </para>
175
185
  </refsect1>
176
186
  
177
187
  <refsect1 id="purpose">
178
188
    <title>PURPOSE</title>
 
189
 
179
190
    <para>
180
191
      The purpose of this is to enable <emphasis>remote and unattended
181
192
      rebooting</emphasis> of client host computer with an
182
193
      <emphasis>encrypted root file system</emphasis>.  See <xref
183
194
      linkend="overview"/> for details.
184
195
    </para>
 
196
 
185
197
  </refsect1>
186
198
  
187
199
  <refsect1 id="options">
188
200
    <title>OPTIONS</title>
189
 
    
 
201
 
190
202
    <variablelist>
191
203
      <varlistentry>
192
 
        <term><option>--help</option></term>
193
 
        <term><option>-h</option></term>
 
204
        <term><literal>-h</literal>, <literal>--help</literal></term>
194
205
        <listitem>
195
206
          <para>
196
207
            Show a help message and exit
199
210
      </varlistentry>
200
211
 
201
212
      <varlistentry>
202
 
        <term><option>--dir
203
 
        <replaceable>DIRECTORY</replaceable></option></term>
204
 
        <term><option>-d
205
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
213
        <term><literal>-d</literal>, <literal>--dir
 
214
        <replaceable>directory</replaceable></literal></term>
206
215
        <listitem>
207
216
          <para>
208
 
            Target directory for key files.  Default is
209
 
            <filename>/etc/mandos</filename>.
 
217
            Target directory for key files.
210
218
          </para>
211
219
        </listitem>
212
220
      </varlistentry>
213
221
 
214
222
      <varlistentry>
215
 
        <term><option>--type
216
 
        <replaceable>TYPE</replaceable></option></term>
217
 
        <term><option>-t
218
 
        <replaceable>TYPE</replaceable></option></term>
 
223
        <term><literal>-t</literal>, <literal>--type
 
224
        <replaceable>type</replaceable></literal></term>
219
225
        <listitem>
220
226
          <para>
221
227
            Key type.  Default is <quote>DSA</quote>.
224
230
      </varlistentry>
225
231
 
226
232
      <varlistentry>
227
 
        <term><option>--length
228
 
        <replaceable>BITS</replaceable></option></term>
229
 
        <term><option>-l
230
 
        <replaceable>BITS</replaceable></option></term>
 
233
        <term><literal>-l</literal>, <literal>--length
 
234
        <replaceable>bits</replaceable></literal></term>
231
235
        <listitem>
232
236
          <para>
233
 
            Key length in bits.  Default is 2048.
 
237
            Key length in bits.  Default is 1024.
234
238
          </para>
235
239
        </listitem>
236
240
      </varlistentry>
237
241
 
238
242
      <varlistentry>
239
 
        <term><option>--subtype
240
 
        <replaceable>KEYTYPE</replaceable></option></term>
241
 
        <term><option>-s
242
 
        <replaceable>KEYTYPE</replaceable></option></term>
 
243
        <term><literal>-s</literal>, <literal>--subtype
 
244
        <replaceable>type</replaceable></literal></term>
243
245
        <listitem>
244
246
          <para>
245
247
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
249
251
      </varlistentry>
250
252
 
251
253
      <varlistentry>
252
 
        <term><option>--sublength
253
 
        <replaceable>BITS</replaceable></option></term>
254
 
        <term><option>-L
255
 
        <replaceable>BITS</replaceable></option></term>
 
254
        <term><literal>-L</literal>, <literal>--sublength
 
255
        <replaceable>bits</replaceable></literal></term>
256
256
        <listitem>
257
257
          <para>
258
258
            Subkey length in bits.  Default is 2048.
261
261
      </varlistentry>
262
262
 
263
263
      <varlistentry>
264
 
        <term><option>--email
265
 
        <replaceable>ADDRESS</replaceable></option></term>
266
 
        <term><option>-e
267
 
        <replaceable>ADDRESS</replaceable></option></term>
 
264
        <term><literal>-e</literal>, <literal>--email</literal>
 
265
        <replaceable>address</replaceable></term>
268
266
        <listitem>
269
267
          <para>
270
268
            Email address of key.  Default is empty.
273
271
      </varlistentry>
274
272
 
275
273
      <varlistentry>
276
 
        <term><option>--comment
277
 
        <replaceable>TEXT</replaceable></option></term>
278
 
        <term><option>-c
279
 
        <replaceable>TEXT</replaceable></option></term>
 
274
        <term><literal>-c</literal>, <literal>--comment</literal>
 
275
        <replaceable>comment</replaceable></term>
280
276
        <listitem>
281
277
          <para>
282
278
            Comment field for key.  The default value is
286
282
      </varlistentry>
287
283
 
288
284
      <varlistentry>
289
 
        <term><option>--expire
290
 
        <replaceable>TIME</replaceable></option></term>
291
 
        <term><option>-x
292
 
        <replaceable>TIME</replaceable></option></term>
 
285
        <term><literal>-x</literal>, <literal>--expire</literal>
 
286
        <replaceable>time</replaceable></term>
293
287
        <listitem>
294
288
          <para>
295
289
            Key expire time.  Default is no expiration.  See
300
294
      </varlistentry>
301
295
 
302
296
      <varlistentry>
303
 
        <term><option>--force</option></term>
304
 
        <term><option>-f</option></term>
305
 
        <listitem>
306
 
          <para>
307
 
            Force overwriting old key.
308
 
          </para>
309
 
        </listitem>
310
 
      </varlistentry>
311
 
      <varlistentry>
312
 
        <term><option>--password</option></term>
313
 
        <term><option>-p</option></term>
314
 
        <listitem>
315
 
          <para>
316
 
            Prompt for a password and encrypt it with the key already
317
 
            present in either <filename>/etc/mandos</filename> or the
318
 
            directory specified with the <option>--dir</option>
319
 
            option.  Outputs, on standard output, a section suitable
320
 
            for inclusion in <citerefentry><refentrytitle
321
 
            >mandos-clients.conf</refentrytitle><manvolnum
322
 
            >8</manvolnum></citerefentry>.  The host name or the name
323
 
            specified with the <option>--name</option> option is used
324
 
            for the section header.  All other options are ignored,
325
 
            and no key is created.
 
297
        <term><literal>-f</literal>, <literal>--force</literal></term>
 
298
        <listitem>
 
299
          <para>
 
300
            Force overwriting old keys.
326
301
          </para>
327
302
        </listitem>
328
303
      </varlistentry>
334
309
    <xi:include href="overview.xml"/>
335
310
    <para>
336
311
      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.
 
312
      new Mandos clients.
339
313
    </para>
340
314
  </refsect1>
341
315
 
342
316
  <refsect1 id="exit_status">
343
317
    <title>EXIT STATUS</title>
344
318
    <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.
 
319
      The exit status will be 0 if new keys were successfully created,
 
320
      otherwise not.
348
321
    </para>
349
322
  </refsect1>
350
323
  
352
325
    <title>ENVIRONMENT</title>
353
326
    <variablelist>
354
327
      <varlistentry>
355
 
        <term><envar>TMPDIR</envar></term>
 
328
        <term><varname>TMPDIR</varname></term>
356
329
        <listitem>
357
330
          <para>
358
331
            If set, temporary files will be created here. See
416
389
        Normal invocation needs no options:
417
390
      </para>
418
391
      <para>
419
 
        <userinput>&COMMANDNAME;</userinput>
 
392
        <userinput>mandos-keygen</userinput>
420
393
      </para>
421
394
    </informalexample>
422
395
    <informalexample>
423
396
      <para>
424
 
        Create key in another directory and of another type.  Force
 
397
        Create keys in another directory and of another type.  Force
425
398
        overwriting old key files:
426
399
      </para>
427
400
      <para>
428
401
 
429
402
<!-- 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>
 
403
<userinput>mandos-keygen --dir ~/keydir --type RSA --force</userinput>
454
404
 
455
405
      </para>
456
406
    </informalexample>
461
411
    <para>
462
412
      The <option>--type</option>, <option>--length</option>,
463
413
      <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.
 
414
      options can be used to create keys of insufficient security.  If
 
415
      in doubt, leave them to the default values.
466
416
    </para>
467
417
    <para>
468
 
      The key expire time is <emphasis>not</emphasis> guaranteed to be
469
 
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
 
418
      The key expire time is not guaranteed to be honored by
 
419
      <citerefentry><refentrytitle>mandos</refentrytitle>
470
420
      <manvolnum>8</manvolnum></citerefentry>.
471
421
    </para>
472
422
  </refsect1>
474
424
  <refsect1 id="see_also">
475
425
    <title>SEE ALSO</title>
476
426
    <para>
 
427
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
428
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
429
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
430
      <manvolnum>8</manvolnum></citerefentry>,
477
431
      <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>
 
432
      <manvolnum>1</manvolnum></citerefentry>
485
433
    </para>
486
434
  </refsect1>
487
435
  
488
436
</refentry>
489
 
<!-- Local Variables: -->
490
 
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
491
 
<!-- time-stamp-end: "[\"']>" -->
492
 
<!-- time-stamp-format: "%:y-%02m-%02d" -->
493
 
<!-- End: -->