/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: 2015-06-28 16:35:27 UTC
  • mto: This revision was merged to the branch mainline in revision 759.
  • Revision ID: teddy@recompile.se-20150628163527-cky0ec59zew7teua
Add a plugin helper directory, available to all plugins.

* Makefile (PLUGIN_HELPERS): New; list of plugin helpers.
  (CPROGS): Appended "$(PLUGIN_HELPERS)".
* initramfs-tools-hook: Create new plugin helper directory, and copy
                        plugin helpers provided by the system and/or
                        by the local administrator.
  (PLUGINHELPERDIR): New.
* plugin-runner.c: Take new --plugin-helper-dir option and provide
                   environment variable to all plugins.
  (PHDIR): New; set to "/lib/mandos/plugin-helpers".
  (main/pluginhelperdir): New.
  (main/options): New option "--plugin-helper-dir".
  (main/parse_opt, main/parse_opt_config_file): Accept new option.
  (main): Use new option to set MANDOSPLUGINHELPERDIR environment
          variable as if using --global-env MANDOSPLUGINHELPERDIR=...
* plugin-runner.xml: Document new --plugin-helper-dir option.
  (SYNOPSIS, OPTIONS): Add "--plugin-helper-dir" option.
  (PLUGINS/WRITING PLUGINS): Document new environment variable
                             available to plugins.
  (ENVIRONMENT): Document new environment variable
                 "MANDOSPLUGINHELPERDIR" affected by the new
                 --plugin-helper-dir option.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos-keygen.xml
1
1
<?xml version="1.0" encoding="UTF-8"?>
2
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
3
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
 
<!ENTITY VERSION "1.0">
5
4
<!ENTITY COMMANDNAME "mandos-keygen">
6
 
<!ENTITY TIMESTAMP "2008-08-30">
 
5
<!ENTITY TIMESTAMP "2014-06-22">
 
6
<!ENTITY % common SYSTEM "common.ent">
 
7
%common;
7
8
]>
8
9
 
9
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
12
    <title>Mandos Manual</title>
12
13
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
14
    <productname>Mandos</productname>
14
 
    <productnumber>&VERSION;</productnumber>
 
15
    <productnumber>&version;</productnumber>
15
16
    <date>&TIMESTAMP;</date>
16
17
    <authorgroup>
17
18
      <author>
18
19
        <firstname>Björn</firstname>
19
20
        <surname>Påhlsson</surname>
20
21
        <address>
21
 
          <email>belorn@fukt.bsnet.se</email>
 
22
          <email>belorn@recompile.se</email>
22
23
        </address>
23
24
      </author>
24
25
      <author>
25
26
        <firstname>Teddy</firstname>
26
27
        <surname>Hogeborn</surname>
27
28
        <address>
28
 
          <email>teddy@fukt.bsnet.se</email>
 
29
          <email>teddy@recompile.se</email>
29
30
        </address>
30
31
      </author>
31
32
    </authorgroup>
32
33
    <copyright>
33
34
      <year>2008</year>
 
35
      <year>2009</year>
 
36
      <year>2011</year>
 
37
      <year>2012</year>
34
38
      <holder>Teddy Hogeborn</holder>
35
39
      <holder>Björn Påhlsson</holder>
36
40
    </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>
 
41
    <xi:include href="legalnotice.xml"/>
60
42
  </refentryinfo>
61
 
 
 
43
  
62
44
  <refmeta>
63
45
    <refentrytitle>&COMMANDNAME;</refentrytitle>
64
46
    <manvolnum>8</manvolnum>
67
49
  <refnamediv>
68
50
    <refname><command>&COMMANDNAME;</command></refname>
69
51
    <refpurpose>
70
 
      Generate keys for <citerefentry><refentrytitle>password-request
71
 
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
 
52
      Generate key and password for Mandos client and server.
72
53
    </refpurpose>
73
54
  </refnamediv>
74
 
 
 
55
  
75
56
  <refsynopsisdiv>
76
57
    <cmdsynopsis>
77
58
      <command>&COMMANDNAME;</command>
138
119
        <replaceable>TIME</replaceable></option></arg>
139
120
      </group>
140
121
      <sbr/>
141
 
      <arg><option>--force</option></arg>
 
122
      <group>
 
123
        <arg choice="plain"><option>--force</option></arg>
 
124
        <arg choice="plain"><option>-f</option></arg>
 
125
      </group>
142
126
    </cmdsynopsis>
143
127
    <cmdsynopsis>
144
128
      <command>&COMMANDNAME;</command>
145
129
      <group choice="req">
 
130
        <arg choice="plain"><option>--password</option></arg>
146
131
        <arg choice="plain"><option>-p</option></arg>
147
 
        <arg choice="plain"><option>--password</option></arg>
 
132
        <arg choice="plain"><option>--passfile
 
133
        <replaceable>FILE</replaceable></option></arg>
 
134
        <arg choice="plain"><option>-F</option>
 
135
        <replaceable>FILE</replaceable></arg>
148
136
      </group>
149
137
      <sbr/>
150
138
      <group>
160
148
        <arg choice="plain"><option>-n
161
149
        <replaceable>NAME</replaceable></option></arg>
162
150
      </group>
 
151
      <group>
 
152
        <arg choice="plain"><option>--no-ssh</option></arg>
 
153
        <arg choice="plain"><option>-S</option></arg>
 
154
      </group>
163
155
    </cmdsynopsis>
164
156
    <cmdsynopsis>
165
157
      <command>&COMMANDNAME;</command>
166
158
      <group choice="req">
 
159
        <arg choice="plain"><option>--help</option></arg>
167
160
        <arg choice="plain"><option>-h</option></arg>
168
 
        <arg choice="plain"><option>--help</option></arg>
169
161
      </group>
170
162
    </cmdsynopsis>
171
163
    <cmdsynopsis>
172
164
      <command>&COMMANDNAME;</command>
173
165
      <group choice="req">
 
166
        <arg choice="plain"><option>--version</option></arg>
174
167
        <arg choice="plain"><option>-v</option></arg>
175
 
        <arg choice="plain"><option>--version</option></arg>
176
168
      </group>
177
169
    </cmdsynopsis>
178
170
  </refsynopsisdiv>
179
 
 
 
171
  
180
172
  <refsect1 id="description">
181
173
    <title>DESCRIPTION</title>
182
174
    <para>
183
175
      <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
 
176
      OpenPGP key used by
 
177
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
178
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
187
179
      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.
 
180
      initrd image, but this, and most other things, can be changed
 
181
      with command line options.
190
182
    </para>
191
183
    <para>
192
 
      It can also be used to generate ready-made sections for
 
184
      This program can also be used with the
 
185
      <option>--password</option> or <option>--passfile</option>
 
186
      options to generate a ready-made section for
 
187
      <filename>clients.conf</filename> (see
193
188
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
194
 
      <manvolnum>5</manvolnum></citerefentry> using the
195
 
      <option>--password</option> option.
 
189
      <manvolnum>5</manvolnum></citerefentry>).
196
190
    </para>
197
191
  </refsect1>
198
192
  
199
193
  <refsect1 id="purpose">
200
194
    <title>PURPOSE</title>
201
 
 
202
195
    <para>
203
196
      The purpose of this is to enable <emphasis>remote and unattended
204
197
      rebooting</emphasis> of client host computer with an
205
198
      <emphasis>encrypted root file system</emphasis>.  See <xref
206
199
      linkend="overview"/> for details.
207
200
    </para>
208
 
 
209
201
  </refsect1>
210
202
  
211
203
  <refsect1 id="options">
212
204
    <title>OPTIONS</title>
213
 
 
 
205
    
214
206
    <variablelist>
215
207
      <varlistentry>
216
 
        <term><literal>-h</literal>, <literal>--help</literal></term>
 
208
        <term><option>--help</option></term>
 
209
        <term><option>-h</option></term>
217
210
        <listitem>
218
211
          <para>
219
212
            Show a help message and exit
220
213
          </para>
221
214
        </listitem>
222
215
      </varlistentry>
223
 
 
 
216
      
224
217
      <varlistentry>
225
 
        <term><literal>-d</literal>, <literal>--dir
226
 
        <replaceable>directory</replaceable></literal></term>
 
218
        <term><option>--dir
 
219
        <replaceable>DIRECTORY</replaceable></option></term>
 
220
        <term><option>-d
 
221
        <replaceable>DIRECTORY</replaceable></option></term>
227
222
        <listitem>
228
223
          <para>
229
224
            Target directory for key files.  Default is
230
 
            <filename>/etc/mandos</filename>.
231
 
          </para>
232
 
        </listitem>
233
 
      </varlistentry>
234
 
 
235
 
      <varlistentry>
236
 
        <term><literal>-t</literal>, <literal>--type
237
 
        <replaceable>type</replaceable></literal></term>
238
 
        <listitem>
239
 
          <para>
240
 
            Key type.  Default is <quote>DSA</quote>.
241
 
          </para>
242
 
        </listitem>
243
 
      </varlistentry>
244
 
 
245
 
      <varlistentry>
246
 
        <term><literal>-l</literal>, <literal>--length
247
 
        <replaceable>bits</replaceable></literal></term>
248
 
        <listitem>
249
 
          <para>
250
 
            Key length in bits.  Default is 2048.
251
 
          </para>
252
 
        </listitem>
253
 
      </varlistentry>
254
 
 
255
 
      <varlistentry>
256
 
        <term><literal>-s</literal>, <literal>--subtype
257
 
        <replaceable>type</replaceable></literal></term>
258
 
        <listitem>
259
 
          <para>
260
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
 
225
            <filename class="directory">/etc/mandos</filename>.
 
226
          </para>
 
227
        </listitem>
 
228
      </varlistentry>
 
229
      
 
230
      <varlistentry>
 
231
        <term><option>--type
 
232
        <replaceable>TYPE</replaceable></option></term>
 
233
        <term><option>-t
 
234
        <replaceable>TYPE</replaceable></option></term>
 
235
        <listitem>
 
236
          <para>
 
237
            Key type.  Default is <quote>RSA</quote>.
 
238
          </para>
 
239
        </listitem>
 
240
      </varlistentry>
 
241
      
 
242
      <varlistentry>
 
243
        <term><option>--length
 
244
        <replaceable>BITS</replaceable></option></term>
 
245
        <term><option>-l
 
246
        <replaceable>BITS</replaceable></option></term>
 
247
        <listitem>
 
248
          <para>
 
249
            Key length in bits.  Default is 4096.
 
250
          </para>
 
251
        </listitem>
 
252
      </varlistentry>
 
253
      
 
254
      <varlistentry>
 
255
        <term><option>--subtype
 
256
        <replaceable>KEYTYPE</replaceable></option></term>
 
257
        <term><option>-s
 
258
        <replaceable>KEYTYPE</replaceable></option></term>
 
259
        <listitem>
 
260
          <para>
 
261
            Subkey type.  Default is <quote>RSA</quote> (Elgamal
261
262
            encryption-only).
262
263
          </para>
263
264
        </listitem>
264
265
      </varlistentry>
265
 
 
 
266
      
266
267
      <varlistentry>
267
 
        <term><literal>-L</literal>, <literal>--sublength
268
 
        <replaceable>bits</replaceable></literal></term>
 
268
        <term><option>--sublength
 
269
        <replaceable>BITS</replaceable></option></term>
 
270
        <term><option>-L
 
271
        <replaceable>BITS</replaceable></option></term>
269
272
        <listitem>
270
273
          <para>
271
 
            Subkey length in bits.  Default is 2048.
 
274
            Subkey length in bits.  Default is 4096.
272
275
          </para>
273
276
        </listitem>
274
277
      </varlistentry>
275
 
 
 
278
      
276
279
      <varlistentry>
277
 
        <term><literal>-e</literal>, <literal>--email</literal>
278
 
        <replaceable>address</replaceable></term>
 
280
        <term><option>--email
 
281
        <replaceable>ADDRESS</replaceable></option></term>
 
282
        <term><option>-e
 
283
        <replaceable>ADDRESS</replaceable></option></term>
279
284
        <listitem>
280
285
          <para>
281
286
            Email address of key.  Default is empty.
282
287
          </para>
283
288
        </listitem>
284
289
      </varlistentry>
285
 
 
 
290
      
286
291
      <varlistentry>
287
 
        <term><literal>-c</literal>, <literal>--comment</literal>
288
 
        <replaceable>comment</replaceable></term>
 
292
        <term><option>--comment
 
293
        <replaceable>TEXT</replaceable></option></term>
 
294
        <term><option>-c
 
295
        <replaceable>TEXT</replaceable></option></term>
289
296
        <listitem>
290
297
          <para>
291
 
            Comment field for key.  The default value is
292
 
            <quote><literal>Mandos client key</literal></quote>.
 
298
            Comment field for key.  Default is empty.
293
299
          </para>
294
300
        </listitem>
295
301
      </varlistentry>
296
 
 
 
302
      
297
303
      <varlistentry>
298
 
        <term><literal>-x</literal>, <literal>--expire</literal>
299
 
        <replaceable>time</replaceable></term>
 
304
        <term><option>--expire
 
305
        <replaceable>TIME</replaceable></option></term>
 
306
        <term><option>-x
 
307
        <replaceable>TIME</replaceable></option></term>
300
308
        <listitem>
301
309
          <para>
302
310
            Key expire time.  Default is no expiration.  See
305
313
          </para>
306
314
        </listitem>
307
315
      </varlistentry>
308
 
 
 
316
      
309
317
      <varlistentry>
310
 
        <term><literal>-f</literal>, <literal>--force</literal></term>
 
318
        <term><option>--force</option></term>
 
319
        <term><option>-f</option></term>
311
320
        <listitem>
312
321
          <para>
313
 
            Force overwriting old keys.
 
322
            Force overwriting old key.
314
323
          </para>
315
324
        </listitem>
316
325
      </varlistentry>
317
326
      <varlistentry>
318
 
        <term><literal>-p</literal>, <literal>--password</literal
319
 
        ></term>
 
327
        <term><option>--password</option></term>
 
328
        <term><option>-p</option></term>
320
329
        <listitem>
321
330
          <para>
322
331
            Prompt for a password and encrypt it with the key already
328
337
            >8</manvolnum></citerefentry>.  The host name or the name
329
338
            specified with the <option>--name</option> option is used
330
339
            for the section header.  All other options are ignored,
331
 
            and no keys are created.
 
340
            and no key is created.
 
341
          </para>
 
342
        </listitem>
 
343
      </varlistentry>
 
344
      <varlistentry>
 
345
        <term><option>--passfile
 
346
        <replaceable>FILE</replaceable></option></term>
 
347
        <term><option>-F
 
348
        <replaceable>FILE</replaceable></option></term>
 
349
        <listitem>
 
350
          <para>
 
351
            The same as <option>--password</option>, but read from
 
352
            <replaceable>FILE</replaceable>, not the terminal.
 
353
          </para>
 
354
        </listitem>
 
355
      </varlistentry>
 
356
      <varlistentry>
 
357
        <term><option>--no-ssh</option></term>
 
358
        <term><option>-S</option></term>
 
359
        <listitem>
 
360
          <para>
 
361
            When <option>--password</option> or
 
362
            <option>--passfile</option> is given, this option will
 
363
            prevent <command>&COMMANDNAME;</command> from calling
 
364
            <command>ssh-keyscan</command> to get an SSH fingerprint
 
365
            for this host and, if successful, output suitable config
 
366
            options to use this fingerprint as a
 
367
            <option>checker</option> option in the output.  This is
 
368
            otherwise the default behavior.
332
369
          </para>
333
370
        </listitem>
334
371
      </varlistentry>
335
372
    </variablelist>
336
373
  </refsect1>
337
 
 
 
374
  
338
375
  <refsect1 id="overview">
339
376
    <title>OVERVIEW</title>
340
377
    <xi:include href="overview.xml"/>
341
378
    <para>
342
379
      This program is a small utility to generate new OpenPGP keys for
343
 
      new Mandos clients.
 
380
      new Mandos clients, and to generate sections for inclusion in
 
381
      <filename>clients.conf</filename> on the server.
344
382
    </para>
345
383
  </refsect1>
346
 
 
 
384
  
347
385
  <refsect1 id="exit_status">
348
386
    <title>EXIT STATUS</title>
349
387
    <para>
350
 
      The exit status will be 0 if new keys were successfully created,
351
 
      otherwise not.
 
388
      The exit status will be 0 if a new key (or password, if the
 
389
      <option>--password</option> option was used) was successfully
 
390
      created, otherwise not.
352
391
    </para>
353
392
  </refsect1>
354
393
  
368
407
    </variablelist>
369
408
  </refsect1>
370
409
  
371
 
  <refsect1 id="file">
 
410
  <refsect1 id="files">
372
411
    <title>FILES</title>
373
412
    <para>
374
413
      Use the <option>--dir</option> option to change where
395
434
        </listitem>
396
435
      </varlistentry>
397
436
      <varlistentry>
398
 
        <term><filename>/tmp</filename></term>
 
437
        <term><filename class="directory">/tmp</filename></term>
399
438
        <listitem>
400
439
          <para>
401
440
            Temporary files will be written here if
405
444
      </varlistentry>
406
445
    </variablelist>
407
446
  </refsect1>
408
 
 
409
 
  <refsect1 id="bugs">
410
 
    <title>BUGS</title>
411
 
    <para>
412
 
      None are known at this time.
413
 
    </para>
414
 
  </refsect1>
415
 
 
 
447
  
 
448
<!--   <refsect1 id="bugs"> -->
 
449
<!--     <title>BUGS</title> -->
 
450
<!--     <para> -->
 
451
<!--     </para> -->
 
452
<!--   </refsect1> -->
 
453
  
416
454
  <refsect1 id="example">
417
455
    <title>EXAMPLE</title>
418
456
    <informalexample>
425
463
    </informalexample>
426
464
    <informalexample>
427
465
      <para>
428
 
        Create keys in another directory and of another type.  Force
 
466
        Create key in another directory and of another type.  Force
429
467
        overwriting old key files:
430
468
      </para>
431
469
      <para>
435
473
 
436
474
      </para>
437
475
    </informalexample>
 
476
    <informalexample>
 
477
      <para>
 
478
        Prompt for a password, encrypt it with the key in <filename
 
479
        class="directory">/etc/mandos</filename> and output a section
 
480
        suitable for <filename>clients.conf</filename>.
 
481
      </para>
 
482
      <para>
 
483
        <userinput>&COMMANDNAME; --password</userinput>
 
484
      </para>
 
485
    </informalexample>
 
486
    <informalexample>
 
487
      <para>
 
488
        Prompt for a password, encrypt it with the key in the
 
489
        <filename>client-key</filename> directory and output a section
 
490
        suitable for <filename>clients.conf</filename>.
 
491
      </para>
 
492
      <para>
 
493
 
 
494
<!-- do not wrap this line -->
 
495
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
 
496
 
 
497
      </para>
 
498
    </informalexample>
438
499
  </refsect1>
439
 
 
 
500
  
440
501
  <refsect1 id="security">
441
502
    <title>SECURITY</title>
442
503
    <para>
443
504
      The <option>--type</option>, <option>--length</option>,
444
505
      <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.
 
506
      options can be used to create keys of low security.  If in
 
507
      doubt, leave them to the default values.
447
508
    </para>
448
509
    <para>
449
 
      The key expire time is not guaranteed to be honored by
450
 
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
510
      The key expire time is <emphasis>not</emphasis> guaranteed to be
 
511
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
451
512
      <manvolnum>8</manvolnum></citerefentry>.
452
513
    </para>
453
514
  </refsect1>
454
 
 
 
515
  
455
516
  <refsect1 id="see_also">
456
517
    <title>SEE ALSO</title>
457
518
    <para>
 
519
      <citerefentry><refentrytitle>intro</refentrytitle>
 
520
      <manvolnum>8mandos</manvolnum></citerefentry>,
458
521
      <citerefentry><refentrytitle>gpg</refentrytitle>
459
522
      <manvolnum>1</manvolnum></citerefentry>,
 
523
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
 
524
      <manvolnum>5</manvolnum></citerefentry>,
460
525
      <citerefentry><refentrytitle>mandos</refentrytitle>
461
526
      <manvolnum>8</manvolnum></citerefentry>,
462
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
463
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
527
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
528
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
529
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
 
530
      <manvolnum>1</manvolnum></citerefentry>
464
531
    </para>
465
532
  </refsect1>
466
533