/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-08-30 19:49:24 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080830194924-f4liqq8wxajlbshn
* plugin-runner.xml (NAME): Improved wording.
  (SYNOPSIS): Use <option> and <replaceable> tags.  Unify short and
              long options.  Add "--global-envs" and "--envs-for"
              options.

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-08-30">
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
 
    <xi:include href="legalnotice.xml"/>
 
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>
38
60
  </refentryinfo>
39
61
 
40
62
  <refmeta>
45
67
  <refnamediv>
46
68
    <refname><command>&COMMANDNAME;</command></refname>
47
69
    <refpurpose>
48
 
      Generate key and password for Mandos client and server.
 
70
      Generate keys for <citerefentry><refentrytitle>password-request
 
71
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
49
72
    </refpurpose>
50
73
  </refnamediv>
51
74
 
120
143
    <cmdsynopsis>
121
144
      <command>&COMMANDNAME;</command>
122
145
      <group choice="req">
 
146
        <arg choice="plain"><option>-p</option></arg>
123
147
        <arg choice="plain"><option>--password</option></arg>
124
 
        <arg choice="plain"><option>-p</option></arg>
125
148
      </group>
126
149
      <sbr/>
127
150
      <group>
141
164
    <cmdsynopsis>
142
165
      <command>&COMMANDNAME;</command>
143
166
      <group choice="req">
 
167
        <arg choice="plain"><option>-h</option></arg>
144
168
        <arg choice="plain"><option>--help</option></arg>
145
 
        <arg choice="plain"><option>-h</option></arg>
146
169
      </group>
147
170
    </cmdsynopsis>
148
171
    <cmdsynopsis>
149
172
      <command>&COMMANDNAME;</command>
150
173
      <group choice="req">
 
174
        <arg choice="plain"><option>-v</option></arg>
151
175
        <arg choice="plain"><option>--version</option></arg>
152
 
        <arg choice="plain"><option>-v</option></arg>
153
176
      </group>
154
177
    </cmdsynopsis>
155
178
  </refsynopsisdiv>
156
 
  
 
179
 
157
180
  <refsect1 id="description">
158
181
    <title>DESCRIPTION</title>
159
182
    <para>
160
183
      <command>&COMMANDNAME;</command> is a program to generate the
161
 
      OpenPGP key used by
 
184
      OpenPGP keys used by
162
185
      <citerefentry><refentrytitle>password-request</refentrytitle>
163
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
 
186
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
164
187
      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.
 
188
      initrd image, but this, like most things, can be changed with
 
189
      command line options.
167
190
    </para>
168
191
    <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
 
192
      It can also be used to generate ready-made sections for
172
193
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
173
 
      <manvolnum>5</manvolnum></citerefentry>).
 
194
      <manvolnum>5</manvolnum></citerefentry> using the
 
195
      <option>--password</option> option.
174
196
    </para>
175
197
  </refsect1>
176
198
  
177
199
  <refsect1 id="purpose">
178
200
    <title>PURPOSE</title>
 
201
 
179
202
    <para>
180
203
      The purpose of this is to enable <emphasis>remote and unattended
181
204
      rebooting</emphasis> of client host computer with an
182
205
      <emphasis>encrypted root file system</emphasis>.  See <xref
183
206
      linkend="overview"/> for details.
184
207
    </para>
 
208
 
185
209
  </refsect1>
186
210
  
187
211
  <refsect1 id="options">
188
212
    <title>OPTIONS</title>
189
 
    
 
213
 
190
214
    <variablelist>
191
215
      <varlistentry>
192
 
        <term><option>--help</option></term>
193
 
        <term><option>-h</option></term>
 
216
        <term><literal>-h</literal>, <literal>--help</literal></term>
194
217
        <listitem>
195
218
          <para>
196
219
            Show a help message and exit
199
222
      </varlistentry>
200
223
 
201
224
      <varlistentry>
202
 
        <term><option>--dir
203
 
        <replaceable>DIRECTORY</replaceable></option></term>
204
 
        <term><option>-d
205
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
225
        <term><literal>-d</literal>, <literal>--dir
 
226
        <replaceable>directory</replaceable></literal></term>
206
227
        <listitem>
207
228
          <para>
208
229
            Target directory for key files.  Default is
212
233
      </varlistentry>
213
234
 
214
235
      <varlistentry>
215
 
        <term><option>--type
216
 
        <replaceable>TYPE</replaceable></option></term>
217
 
        <term><option>-t
218
 
        <replaceable>TYPE</replaceable></option></term>
 
236
        <term><literal>-t</literal>, <literal>--type
 
237
        <replaceable>type</replaceable></literal></term>
219
238
        <listitem>
220
239
          <para>
221
240
            Key type.  Default is <quote>DSA</quote>.
224
243
      </varlistentry>
225
244
 
226
245
      <varlistentry>
227
 
        <term><option>--length
228
 
        <replaceable>BITS</replaceable></option></term>
229
 
        <term><option>-l
230
 
        <replaceable>BITS</replaceable></option></term>
 
246
        <term><literal>-l</literal>, <literal>--length
 
247
        <replaceable>bits</replaceable></literal></term>
231
248
        <listitem>
232
249
          <para>
233
250
            Key length in bits.  Default is 2048.
236
253
      </varlistentry>
237
254
 
238
255
      <varlistentry>
239
 
        <term><option>--subtype
240
 
        <replaceable>KEYTYPE</replaceable></option></term>
241
 
        <term><option>-s
242
 
        <replaceable>KEYTYPE</replaceable></option></term>
 
256
        <term><literal>-s</literal>, <literal>--subtype
 
257
        <replaceable>type</replaceable></literal></term>
243
258
        <listitem>
244
259
          <para>
245
260
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
249
264
      </varlistentry>
250
265
 
251
266
      <varlistentry>
252
 
        <term><option>--sublength
253
 
        <replaceable>BITS</replaceable></option></term>
254
 
        <term><option>-L
255
 
        <replaceable>BITS</replaceable></option></term>
 
267
        <term><literal>-L</literal>, <literal>--sublength
 
268
        <replaceable>bits</replaceable></literal></term>
256
269
        <listitem>
257
270
          <para>
258
271
            Subkey length in bits.  Default is 2048.
261
274
      </varlistentry>
262
275
 
263
276
      <varlistentry>
264
 
        <term><option>--email
265
 
        <replaceable>ADDRESS</replaceable></option></term>
266
 
        <term><option>-e
267
 
        <replaceable>ADDRESS</replaceable></option></term>
 
277
        <term><literal>-e</literal>, <literal>--email</literal>
 
278
        <replaceable>address</replaceable></term>
268
279
        <listitem>
269
280
          <para>
270
281
            Email address of key.  Default is empty.
273
284
      </varlistentry>
274
285
 
275
286
      <varlistentry>
276
 
        <term><option>--comment
277
 
        <replaceable>TEXT</replaceable></option></term>
278
 
        <term><option>-c
279
 
        <replaceable>TEXT</replaceable></option></term>
 
287
        <term><literal>-c</literal>, <literal>--comment</literal>
 
288
        <replaceable>comment</replaceable></term>
280
289
        <listitem>
281
290
          <para>
282
291
            Comment field for key.  The default value is
286
295
      </varlistentry>
287
296
 
288
297
      <varlistentry>
289
 
        <term><option>--expire
290
 
        <replaceable>TIME</replaceable></option></term>
291
 
        <term><option>-x
292
 
        <replaceable>TIME</replaceable></option></term>
 
298
        <term><literal>-x</literal>, <literal>--expire</literal>
 
299
        <replaceable>time</replaceable></term>
293
300
        <listitem>
294
301
          <para>
295
302
            Key expire time.  Default is no expiration.  See
300
307
      </varlistentry>
301
308
 
302
309
      <varlistentry>
303
 
        <term><option>--force</option></term>
304
 
        <term><option>-f</option></term>
 
310
        <term><literal>-f</literal>, <literal>--force</literal></term>
305
311
        <listitem>
306
312
          <para>
307
 
            Force overwriting old key.
 
313
            Force overwriting old keys.
308
314
          </para>
309
315
        </listitem>
310
316
      </varlistentry>
311
317
      <varlistentry>
312
 
        <term><option>--password</option></term>
313
 
        <term><option>-p</option></term>
 
318
        <term><literal>-p</literal>, <literal>--password</literal
 
319
        ></term>
314
320
        <listitem>
315
321
          <para>
316
322
            Prompt for a password and encrypt it with the key already
322
328
            >8</manvolnum></citerefentry>.  The host name or the name
323
329
            specified with the <option>--name</option> option is used
324
330
            for the section header.  All other options are ignored,
325
 
            and no key is created.
 
331
            and no keys are created.
326
332
          </para>
327
333
        </listitem>
328
334
      </varlistentry>
334
340
    <xi:include href="overview.xml"/>
335
341
    <para>
336
342
      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.
 
343
      new Mandos clients.
339
344
    </para>
340
345
  </refsect1>
341
346
 
342
347
  <refsect1 id="exit_status">
343
348
    <title>EXIT STATUS</title>
344
349
    <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.
 
350
      The exit status will be 0 if new keys were successfully created,
 
351
      otherwise not.
348
352
    </para>
349
353
  </refsect1>
350
354
  
421
425
    </informalexample>
422
426
    <informalexample>
423
427
      <para>
424
 
        Create key in another directory and of another type.  Force
 
428
        Create keys in another directory and of another type.  Force
425
429
        overwriting old key files:
426
430
      </para>
427
431
      <para>
431
435
 
432
436
      </para>
433
437
    </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>
454
 
 
455
 
      </para>
456
 
    </informalexample>
457
438
  </refsect1>
458
439
 
459
440
  <refsect1 id="security">
461
442
    <para>
462
443
      The <option>--type</option>, <option>--length</option>,
463
444
      <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.
 
445
      options can be used to create keys of insufficient security.  If
 
446
      in doubt, leave them to the default values.
466
447
    </para>
467
448
    <para>
468
 
      The key expire time is <emphasis>not</emphasis> guaranteed to be
469
 
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
 
449
      The key expire time is not guaranteed to be honored by
 
450
      <citerefentry><refentrytitle>mandos</refentrytitle>
470
451
      <manvolnum>8</manvolnum></citerefentry>.
471
452
    </para>
472
453
  </refsect1>
476
457
    <para>
477
458
      <citerefentry><refentrytitle>gpg</refentrytitle>
478
459
      <manvolnum>1</manvolnum></citerefentry>,
479
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
480
 
      <manvolnum>5</manvolnum></citerefentry>,
481
460
      <citerefentry><refentrytitle>mandos</refentrytitle>
482
461
      <manvolnum>8</manvolnum></citerefentry>,
483
462
      <citerefentry><refentrytitle>password-request</refentrytitle>