/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-21 12:04:02 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080921120402-mgd2jl8xo634jw18
* Makefile: Put the init script before avahi-daemon.

* debian/mandos.prerm: Bug fix: stop mandos, not ssh.

* debian/rules (install-indep): Put the init script before
                                avahi-daemon.

* init.d/mandos: Require "avahi-daemon".

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