/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-09-23 18:46:17 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080923184617-r2rd8r7o2jvgz5ey
* Makefile (PLUGINS, uninstall-client,
            install-client-nokey): Added "plugins.d/splashy".

* plugin-runner.c: Change in comments.

* plugins.d/splashy: Removed; replaced by "splashy.c".
* plugins.d/splashy.c: New.

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-09-20">
7
7
]>
8
8
 
9
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
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>
63
41
    <refentrytitle>&COMMANDNAME;</refentrytitle>
64
42
    <manvolnum>8</manvolnum>
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>
145
122
      <group choice="req">
146
123
        <arg choice="plain"><option>--password</option></arg>
147
124
        <arg choice="plain"><option>-p</option></arg>
 
125
        <arg choice="plain"><option>--passfile
 
126
        <replaceable>FILE</replaceable></option></arg>
 
127
        <arg choice="plain"><option>-F</option>
 
128
        <replaceable>FILE</replaceable></arg>
148
129
      </group>
149
130
      <sbr/>
150
131
      <group>
176
157
      </group>
177
158
    </cmdsynopsis>
178
159
  </refsynopsisdiv>
179
 
 
 
160
  
180
161
  <refsect1 id="description">
181
162
    <title>DESCRIPTION</title>
182
163
    <para>
183
164
      <command>&COMMANDNAME;</command> is a program to generate the
184
 
      OpenPGP keys used by
185
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
186
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
 
165
      OpenPGP key used by
 
166
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
167
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
187
168
      normally written to /etc/mandos for later installation into the
188
 
      initrd image, but this, like most things, can be changed with
189
 
      command line options.
 
169
      initrd image, but this, and most other things, can be changed
 
170
      with command line options.
190
171
    </para>
191
172
    <para>
192
 
      It can also be used to generate ready-made sections for
 
173
      This program can also be used with the
 
174
      <option>--password</option> or <option>--passfile</option>
 
175
      options to generate a ready-made section for
 
176
      <filename>clients.conf</filename> (see
193
177
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
194
 
      <manvolnum>5</manvolnum></citerefentry> using the
195
 
      <option>--password</option> option.
 
178
      <manvolnum>5</manvolnum></citerefentry>).
196
179
    </para>
197
180
  </refsect1>
198
181
  
199
182
  <refsect1 id="purpose">
200
183
    <title>PURPOSE</title>
201
 
 
202
184
    <para>
203
185
      The purpose of this is to enable <emphasis>remote and unattended
204
186
      rebooting</emphasis> of client host computer with an
205
187
      <emphasis>encrypted root file system</emphasis>.  See <xref
206
188
      linkend="overview"/> for details.
207
189
    </para>
208
 
 
209
190
  </refsect1>
210
191
  
211
192
  <refsect1 id="options">
212
193
    <title>OPTIONS</title>
213
 
 
 
194
    
214
195
    <variablelist>
215
196
      <varlistentry>
216
 
        <term><literal>-h</literal>, <literal>--help</literal></term>
 
197
        <term><option>--help</option></term>
 
198
        <term><option>-h</option></term>
217
199
        <listitem>
218
200
          <para>
219
201
            Show a help message and exit
220
202
          </para>
221
203
        </listitem>
222
204
      </varlistentry>
223
 
 
 
205
      
224
206
      <varlistentry>
225
 
        <term><literal>-d</literal>, <literal>--dir
226
 
        <replaceable>directory</replaceable></literal></term>
 
207
        <term><option>--dir
 
208
        <replaceable>DIRECTORY</replaceable></option></term>
 
209
        <term><option>-d
 
210
        <replaceable>DIRECTORY</replaceable></option></term>
227
211
        <listitem>
228
212
          <para>
229
213
            Target directory for key files.  Default is
231
215
          </para>
232
216
        </listitem>
233
217
      </varlistentry>
234
 
 
 
218
      
235
219
      <varlistentry>
236
 
        <term><literal>-t</literal>, <literal>--type
237
 
        <replaceable>type</replaceable></literal></term>
 
220
        <term><option>--type
 
221
        <replaceable>TYPE</replaceable></option></term>
 
222
        <term><option>-t
 
223
        <replaceable>TYPE</replaceable></option></term>
238
224
        <listitem>
239
225
          <para>
240
226
            Key type.  Default is <quote>DSA</quote>.
241
227
          </para>
242
228
        </listitem>
243
229
      </varlistentry>
244
 
 
 
230
      
245
231
      <varlistentry>
246
 
        <term><literal>-l</literal>, <literal>--length
247
 
        <replaceable>bits</replaceable></literal></term>
 
232
        <term><option>--length
 
233
        <replaceable>BITS</replaceable></option></term>
 
234
        <term><option>-l
 
235
        <replaceable>BITS</replaceable></option></term>
248
236
        <listitem>
249
237
          <para>
250
238
            Key length in bits.  Default is 2048.
251
239
          </para>
252
240
        </listitem>
253
241
      </varlistentry>
254
 
 
 
242
      
255
243
      <varlistentry>
256
 
        <term><literal>-s</literal>, <literal>--subtype
257
 
        <replaceable>type</replaceable></literal></term>
 
244
        <term><option>--subtype
 
245
        <replaceable>KEYTYPE</replaceable></option></term>
 
246
        <term><option>-s
 
247
        <replaceable>KEYTYPE</replaceable></option></term>
258
248
        <listitem>
259
249
          <para>
260
250
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
262
252
          </para>
263
253
        </listitem>
264
254
      </varlistentry>
265
 
 
 
255
      
266
256
      <varlistentry>
267
 
        <term><literal>-L</literal>, <literal>--sublength
268
 
        <replaceable>bits</replaceable></literal></term>
 
257
        <term><option>--sublength
 
258
        <replaceable>BITS</replaceable></option></term>
 
259
        <term><option>-L
 
260
        <replaceable>BITS</replaceable></option></term>
269
261
        <listitem>
270
262
          <para>
271
263
            Subkey length in bits.  Default is 2048.
272
264
          </para>
273
265
        </listitem>
274
266
      </varlistentry>
275
 
 
 
267
      
276
268
      <varlistentry>
277
 
        <term><literal>-e</literal>, <literal>--email</literal>
278
 
        <replaceable>address</replaceable></term>
 
269
        <term><option>--email
 
270
        <replaceable>ADDRESS</replaceable></option></term>
 
271
        <term><option>-e
 
272
        <replaceable>ADDRESS</replaceable></option></term>
279
273
        <listitem>
280
274
          <para>
281
275
            Email address of key.  Default is empty.
282
276
          </para>
283
277
        </listitem>
284
278
      </varlistentry>
285
 
 
 
279
      
286
280
      <varlistentry>
287
 
        <term><literal>-c</literal>, <literal>--comment</literal>
288
 
        <replaceable>comment</replaceable></term>
 
281
        <term><option>--comment
 
282
        <replaceable>TEXT</replaceable></option></term>
 
283
        <term><option>-c
 
284
        <replaceable>TEXT</replaceable></option></term>
289
285
        <listitem>
290
286
          <para>
291
287
            Comment field for key.  The default value is
293
289
          </para>
294
290
        </listitem>
295
291
      </varlistentry>
296
 
 
 
292
      
297
293
      <varlistentry>
298
 
        <term><literal>-x</literal>, <literal>--expire</literal>
299
 
        <replaceable>time</replaceable></term>
 
294
        <term><option>--expire
 
295
        <replaceable>TIME</replaceable></option></term>
 
296
        <term><option>-x
 
297
        <replaceable>TIME</replaceable></option></term>
300
298
        <listitem>
301
299
          <para>
302
300
            Key expire time.  Default is no expiration.  See
305
303
          </para>
306
304
        </listitem>
307
305
      </varlistentry>
308
 
 
 
306
      
309
307
      <varlistentry>
310
 
        <term><literal>-f</literal>, <literal>--force</literal></term>
 
308
        <term><option>--force</option></term>
 
309
        <term><option>-f</option></term>
311
310
        <listitem>
312
311
          <para>
313
 
            Force overwriting old keys.
 
312
            Force overwriting old key.
314
313
          </para>
315
314
        </listitem>
316
315
      </varlistentry>
317
316
      <varlistentry>
318
 
        <term><literal>-p</literal>, <literal>--password</literal
319
 
        ></term>
 
317
        <term><option>--password</option></term>
 
318
        <term><option>-p</option></term>
320
319
        <listitem>
321
320
          <para>
322
321
            Prompt for a password and encrypt it with the key already
328
327
            >8</manvolnum></citerefentry>.  The host name or the name
329
328
            specified with the <option>--name</option> option is used
330
329
            for the section header.  All other options are ignored,
331
 
            and no keys are created.
 
330
            and no key is created.
 
331
          </para>
 
332
        </listitem>
 
333
      </varlistentry>
 
334
      <varlistentry>
 
335
        <term><option>--passfile
 
336
        <replaceable>FILE</replaceable></option></term>
 
337
        <term><option>-F
 
338
        <replaceable>FILE</replaceable></option></term>
 
339
        <listitem>
 
340
          <para>
 
341
            The same as <option>--password</option>, but read from
 
342
            <replaceable>FILE</replaceable>, not the terminal.
332
343
          </para>
333
344
        </listitem>
334
345
      </varlistentry>
335
346
    </variablelist>
336
347
  </refsect1>
337
 
 
 
348
  
338
349
  <refsect1 id="overview">
339
350
    <title>OVERVIEW</title>
340
351
    <xi:include href="overview.xml"/>
341
352
    <para>
342
353
      This program is a small utility to generate new OpenPGP keys for
343
 
      new Mandos clients.
 
354
      new Mandos clients, and to generate sections for inclusion in
 
355
      <filename>clients.conf</filename> on the server.
344
356
    </para>
345
357
  </refsect1>
346
 
 
 
358
  
347
359
  <refsect1 id="exit_status">
348
360
    <title>EXIT STATUS</title>
349
361
    <para>
350
 
      The exit status will be 0 if new keys were successfully created,
351
 
      otherwise not.
 
362
      The exit status will be 0 if a new key (or password, if the
 
363
      <option>--password</option> option was used) was successfully
 
364
      created, otherwise not.
352
365
    </para>
353
366
  </refsect1>
354
367
  
405
418
      </varlistentry>
406
419
    </variablelist>
407
420
  </refsect1>
408
 
 
409
 
  <refsect1 id="bugs">
410
 
    <title>BUGS</title>
411
 
    <para>
412
 
      None are known at this time.
413
 
    </para>
414
 
  </refsect1>
415
 
 
 
421
  
 
422
<!--   <refsect1 id="bugs"> -->
 
423
<!--     <title>BUGS</title> -->
 
424
<!--     <para> -->
 
425
<!--     </para> -->
 
426
<!--   </refsect1> -->
 
427
  
416
428
  <refsect1 id="example">
417
429
    <title>EXAMPLE</title>
418
430
    <informalexample>
425
437
    </informalexample>
426
438
    <informalexample>
427
439
      <para>
428
 
        Create keys in another directory and of another type.  Force
 
440
        Create key in another directory and of another type.  Force
429
441
        overwriting old key files:
430
442
      </para>
431
443
      <para>
435
447
 
436
448
      </para>
437
449
    </informalexample>
 
450
    <informalexample>
 
451
      <para>
 
452
        Prompt for a password, encrypt it with the key in
 
453
        <filename>/etc/mandos</filename> and output a section suitable
 
454
        for <filename>clients.conf</filename>.
 
455
      </para>
 
456
      <para>
 
457
        <userinput>&COMMANDNAME; --password</userinput>
 
458
      </para>
 
459
    </informalexample>
 
460
    <informalexample>
 
461
      <para>
 
462
        Prompt for a password, encrypt it with the key in the
 
463
        <filename>client-key</filename> directory and output a section
 
464
        suitable for <filename>clients.conf</filename>.
 
465
      </para>
 
466
      <para>
 
467
 
 
468
<!-- do not wrap this line -->
 
469
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
 
470
 
 
471
      </para>
 
472
    </informalexample>
438
473
  </refsect1>
439
 
 
 
474
  
440
475
  <refsect1 id="security">
441
476
    <title>SECURITY</title>
442
477
    <para>
443
478
      The <option>--type</option>, <option>--length</option>,
444
479
      <option>--subtype</option>, and <option>--sublength</option>
445
 
      options can be used to create keys of insufficient security.  If
446
 
      in doubt, leave them to the default values.
 
480
      options can be used to create keys of low security.  If in
 
481
      doubt, leave them to the default values.
447
482
    </para>
448
483
    <para>
449
 
      The key expire time is not guaranteed to be honored by
450
 
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
484
      The key expire time is <emphasis>not</emphasis> guaranteed to be
 
485
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
451
486
      <manvolnum>8</manvolnum></citerefentry>.
452
487
    </para>
453
488
  </refsect1>
454
 
 
 
489
  
455
490
  <refsect1 id="see_also">
456
491
    <title>SEE ALSO</title>
457
492
    <para>
458
493
      <citerefentry><refentrytitle>gpg</refentrytitle>
459
494
      <manvolnum>1</manvolnum></citerefentry>,
 
495
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
 
496
      <manvolnum>5</manvolnum></citerefentry>,
460
497
      <citerefentry><refentrytitle>mandos</refentrytitle>
461
498
      <manvolnum>8</manvolnum></citerefentry>,
462
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
499
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
463
500
      <manvolnum>8mandos</manvolnum></citerefentry>
464
501
    </para>
465
502
  </refsect1>