/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-06 17:24:58 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080906172458-2x5wlfkn7oqckt1y
* legalnotice.xml: Copy DocBook 4.4-formatted text from
                   <http://www.gnu.org/licenses/gpl-3.0.dbk>.

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-09-06">
6
7
]>
7
8
 
8
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
9
10
  <refentryinfo>
10
 
    <title>&COMMANDNAME;</title>
 
11
    <title>Mandos Manual</title>
11
12
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
12
 
    <productname>&COMMANDNAME;</productname>
 
13
    <productname>Mandos</productname>
13
14
    <productnumber>&VERSION;</productnumber>
 
15
    <date>&TIMESTAMP;</date>
14
16
    <authorgroup>
15
17
      <author>
16
18
        <firstname>Björn</firstname>
32
34
      <holder>Teddy Hogeborn</holder>
33
35
      <holder>Björn Påhlsson</holder>
34
36
    </copyright>
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>
 
37
    <xi:include href="legalnotice.xml"/>
58
38
  </refentryinfo>
59
39
 
60
40
  <refmeta>
65
45
  <refnamediv>
66
46
    <refname><command>&COMMANDNAME;</command></refname>
67
47
    <refpurpose>
68
 
      Generate keys for <citerefentry><refentrytitle>password-request
69
 
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
 
48
      Generate key and password for Mandos client and server.
70
49
    </refpurpose>
71
50
  </refnamediv>
72
51
 
73
52
  <refsynopsisdiv>
74
53
    <cmdsynopsis>
75
54
      <command>&COMMANDNAME;</command>
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">
 
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">
 
144
        <arg choice="plain"><option>--help</option></arg>
161
145
        <arg choice="plain"><option>-h</option></arg>
162
 
        <arg choice="plain"><option>--help</option></arg>
163
146
      </group>
164
147
    </cmdsynopsis>
165
148
    <cmdsynopsis>
166
149
      <command>&COMMANDNAME;</command>
167
150
      <group choice="req">
 
151
        <arg choice="plain"><option>--version</option></arg>
168
152
        <arg choice="plain"><option>-v</option></arg>
169
 
        <arg choice="plain"><option>--version</option></arg>
170
153
      </group>
171
154
    </cmdsynopsis>
172
155
  </refsynopsisdiv>
173
 
 
 
156
  
174
157
  <refsect1 id="description">
175
158
    <title>DESCRIPTION</title>
176
159
    <para>
177
160
      <command>&COMMANDNAME;</command> is a program to generate the
178
 
      OpenPGP keys used by
179
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
180
 
      <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
181
164
      normally written to /etc/mandos for later installation into the
182
 
      initrd image, but this, like most things, can be changed with
183
 
      command line options.
 
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>).
184
174
    </para>
185
175
  </refsect1>
186
176
  
187
177
  <refsect1 id="purpose">
188
178
    <title>PURPOSE</title>
189
 
 
190
179
    <para>
191
180
      The purpose of this is to enable <emphasis>remote and unattended
192
181
      rebooting</emphasis> of client host computer with an
193
182
      <emphasis>encrypted root file system</emphasis>.  See <xref
194
183
      linkend="overview"/> for details.
195
184
    </para>
196
 
 
197
185
  </refsect1>
198
186
  
199
187
  <refsect1 id="options">
200
188
    <title>OPTIONS</title>
201
 
 
 
189
    
202
190
    <variablelist>
203
191
      <varlistentry>
204
 
        <term><literal>-h</literal>, <literal>--help</literal></term>
 
192
        <term><option>--help</option></term>
 
193
        <term><option>-h</option></term>
205
194
        <listitem>
206
195
          <para>
207
196
            Show a help message and exit
210
199
      </varlistentry>
211
200
 
212
201
      <varlistentry>
213
 
        <term><literal>-d</literal>, <literal>--dir
214
 
        <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>
215
206
        <listitem>
216
207
          <para>
217
 
            Target directory for key files.
 
208
            Target directory for key files.  Default is
 
209
            <filename>/etc/mandos</filename>.
218
210
          </para>
219
211
        </listitem>
220
212
      </varlistentry>
221
213
 
222
214
      <varlistentry>
223
 
        <term><literal>-t</literal>, <literal>--type
224
 
        <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>
225
219
        <listitem>
226
220
          <para>
227
221
            Key type.  Default is <quote>DSA</quote>.
230
224
      </varlistentry>
231
225
 
232
226
      <varlistentry>
233
 
        <term><literal>-l</literal>, <literal>--length
234
 
        <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>
235
231
        <listitem>
236
232
          <para>
237
 
            Key length in bits.  Default is 1024.
 
233
            Key length in bits.  Default is 2048.
238
234
          </para>
239
235
        </listitem>
240
236
      </varlistentry>
241
237
 
242
238
      <varlistentry>
243
 
        <term><literal>-s</literal>, <literal>--subtype
244
 
        <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>
245
243
        <listitem>
246
244
          <para>
247
245
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
251
249
      </varlistentry>
252
250
 
253
251
      <varlistentry>
254
 
        <term><literal>-L</literal>, <literal>--sublength
255
 
        <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>
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><literal>-e</literal>, <literal>--email</literal>
265
 
        <replaceable>address</replaceable></term>
 
264
        <term><option>--email
 
265
        <replaceable>ADDRESS</replaceable></option></term>
 
266
        <term><option>-e
 
267
        <replaceable>ADDRESS</replaceable></option></term>
266
268
        <listitem>
267
269
          <para>
268
270
            Email address of key.  Default is empty.
271
273
      </varlistentry>
272
274
 
273
275
      <varlistentry>
274
 
        <term><literal>-c</literal>, <literal>--comment</literal>
275
 
        <replaceable>comment</replaceable></term>
 
276
        <term><option>--comment
 
277
        <replaceable>TEXT</replaceable></option></term>
 
278
        <term><option>-c
 
279
        <replaceable>TEXT</replaceable></option></term>
276
280
        <listitem>
277
281
          <para>
278
282
            Comment field for key.  The default value is
282
286
      </varlistentry>
283
287
 
284
288
      <varlistentry>
285
 
        <term><literal>-x</literal>, <literal>--expire</literal>
286
 
        <replaceable>time</replaceable></term>
 
289
        <term><option>--expire
 
290
        <replaceable>TIME</replaceable></option></term>
 
291
        <term><option>-x
 
292
        <replaceable>TIME</replaceable></option></term>
287
293
        <listitem>
288
294
          <para>
289
295
            Key expire time.  Default is no expiration.  See
294
300
      </varlistentry>
295
301
 
296
302
      <varlistentry>
297
 
        <term><literal>-f</literal>, <literal>--force</literal></term>
298
 
        <listitem>
299
 
          <para>
300
 
            Force overwriting old keys.
 
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.
301
326
          </para>
302
327
        </listitem>
303
328
      </varlistentry>
309
334
    <xi:include href="overview.xml"/>
310
335
    <para>
311
336
      This program is a small utility to generate new OpenPGP keys for
312
 
      new Mandos clients.
 
337
      new Mandos clients, and to generate sections for inclusion in
 
338
      <filename>clients.conf</filename> on the server.
313
339
    </para>
314
340
  </refsect1>
315
341
 
316
342
  <refsect1 id="exit_status">
317
343
    <title>EXIT STATUS</title>
318
344
    <para>
319
 
      The exit status will be 0 if new keys were successfully created,
320
 
      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.
321
348
    </para>
322
349
  </refsect1>
323
350
  
325
352
    <title>ENVIRONMENT</title>
326
353
    <variablelist>
327
354
      <varlistentry>
328
 
        <term><varname>TMPDIR</varname></term>
 
355
        <term><envar>TMPDIR</envar></term>
329
356
        <listitem>
330
357
          <para>
331
358
            If set, temporary files will be created here. See
375
402
    </variablelist>
376
403
  </refsect1>
377
404
 
378
 
  <refsect1 id="bugs">
379
 
    <title>BUGS</title>
380
 
    <para>
381
 
      None are known at this time.
382
 
    </para>
383
 
  </refsect1>
 
405
<!--   <refsect1 id="bugs"> -->
 
406
<!--     <title>BUGS</title> -->
 
407
<!--     <para> -->
 
408
<!--     </para> -->
 
409
<!--   </refsect1> -->
384
410
 
385
411
  <refsect1 id="example">
386
412
    <title>EXAMPLE</title>
389
415
        Normal invocation needs no options:
390
416
      </para>
391
417
      <para>
392
 
        <userinput>mandos-keygen</userinput>
 
418
        <userinput>&COMMANDNAME;</userinput>
393
419
      </para>
394
420
    </informalexample>
395
421
    <informalexample>
396
422
      <para>
397
 
        Create keys in another directory and of another type.  Force
 
423
        Create key in another directory and of another type.  Force
398
424
        overwriting old key files:
399
425
      </para>
400
426
      <para>
401
427
 
402
428
<!-- do not wrap this line -->
403
 
<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>
404
453
 
405
454
      </para>
406
455
    </informalexample>
411
460
    <para>
412
461
      The <option>--type</option>, <option>--length</option>,
413
462
      <option>--subtype</option>, and <option>--sublength</option>
414
 
      options can be used to create keys of insufficient security.  If
415
 
      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.
416
465
    </para>
417
466
    <para>
418
 
      The key expire time is not guaranteed to be honored by
419
 
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
467
      The key expire time is <emphasis>not</emphasis> guaranteed to be
 
468
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
420
469
      <manvolnum>8</manvolnum></citerefentry>.
421
470
    </para>
422
471
  </refsect1>
424
473
  <refsect1 id="see_also">
425
474
    <title>SEE ALSO</title>
426
475
    <para>
427
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
428
 
      <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>,
429
480
      <citerefentry><refentrytitle>mandos</refentrytitle>
430
481
      <manvolnum>8</manvolnum></citerefentry>,
431
 
      <citerefentry><refentrytitle>gpg</refentrytitle>
432
 
      <manvolnum>1</manvolnum></citerefentry>
 
482
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
483
      <manvolnum>8mandos</manvolnum></citerefentry>
433
484
    </para>
434
485
  </refsect1>
435
486
  
436
487
</refentry>
 
488
<!-- Local Variables: -->
 
489
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
 
490
<!-- time-stamp-end: "[\"']>" -->
 
491
<!-- time-stamp-format: "%:y-%02m-%02d" -->
 
492
<!-- End: -->