/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-08-29 07:30:17 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080829073017-tvryowganbf75zp5
* mandos-clients.conf.xml (SEE ALSO): Alphabetized, as per
                                      man-pages(7).
* mandos-keygen.xml: - '' -
* mandos.conf.xml: - '' -
* mandos.xml: - '' -
* plugin-runner.xml: - '' -
* plugins.d/password-request.xml (SEE ALSO): Changed from an
                                             <itemizedlist> to a
                                             <para>, as per
                                             man-pages(7).  Also
                                             alphabetize.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos-keygen.xml
 
1
<?xml version="1.0" encoding="UTF-8"?>
 
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
 
3
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
 
4
<!ENTITY VERSION "1.0">
 
5
<!ENTITY COMMANDNAME "mandos-keygen">
 
6
<!ENTITY TIMESTAMP "2008-08-29">
 
7
]>
 
8
 
 
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
 
10
  <refentryinfo>
 
11
    <title>Mandos Manual</title>
 
12
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
 
13
    <productname>Mandos</productname>
 
14
    <productnumber>&VERSION;</productnumber>
 
15
    <date>&TIMESTAMP;</date>
 
16
    <authorgroup>
 
17
      <author>
 
18
        <firstname>Björn</firstname>
 
19
        <surname>Påhlsson</surname>
 
20
        <address>
 
21
          <email>belorn@fukt.bsnet.se</email>
 
22
        </address>
 
23
      </author>
 
24
      <author>
 
25
        <firstname>Teddy</firstname>
 
26
        <surname>Hogeborn</surname>
 
27
        <address>
 
28
          <email>teddy@fukt.bsnet.se</email>
 
29
        </address>
 
30
      </author>
 
31
    </authorgroup>
 
32
    <copyright>
 
33
      <year>2008</year>
 
34
      <holder>Teddy Hogeborn</holder>
 
35
      <holder>Björn Påhlsson</holder>
 
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>
 
60
  </refentryinfo>
 
61
 
 
62
  <refmeta>
 
63
    <refentrytitle>&COMMANDNAME;</refentrytitle>
 
64
    <manvolnum>8</manvolnum>
 
65
  </refmeta>
 
66
  
 
67
  <refnamediv>
 
68
    <refname><command>&COMMANDNAME;</command></refname>
 
69
    <refpurpose>
 
70
      Generate keys for <citerefentry><refentrytitle>password-request
 
71
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
 
72
    </refpurpose>
 
73
  </refnamediv>
 
74
 
 
75
  <refsynopsisdiv>
 
76
    <cmdsynopsis>
 
77
      <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>
 
159
    </cmdsynopsis>
 
160
    <cmdsynopsis>
 
161
      <command>&COMMANDNAME;</command>
 
162
      <group choice="req">
 
163
        <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>
 
173
      </group>
 
174
    </cmdsynopsis>
 
175
    <cmdsynopsis>
 
176
      <command>&COMMANDNAME;</command>
 
177
      <group choice="req">
 
178
        <arg choice="plain"><option>-h</option></arg>
 
179
        <arg choice="plain"><option>--help</option></arg>
 
180
      </group>
 
181
    </cmdsynopsis>
 
182
    <cmdsynopsis>
 
183
      <command>&COMMANDNAME;</command>
 
184
      <group choice="req">
 
185
        <arg choice="plain"><option>-v</option></arg>
 
186
        <arg choice="plain"><option>--version</option></arg>
 
187
      </group>
 
188
    </cmdsynopsis>
 
189
  </refsynopsisdiv>
 
190
 
 
191
  <refsect1 id="description">
 
192
    <title>DESCRIPTION</title>
 
193
    <para>
 
194
      <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
 
198
      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.
 
201
    </para>
 
202
    <para>
 
203
      It can also be used to generate ready-made sections for
 
204
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
 
205
      <manvolnum>5</manvolnum></citerefentry> using the
 
206
      <option>--password</option> option.
 
207
    </para>
 
208
  </refsect1>
 
209
  
 
210
  <refsect1 id="purpose">
 
211
    <title>PURPOSE</title>
 
212
 
 
213
    <para>
 
214
      The purpose of this is to enable <emphasis>remote and unattended
 
215
      rebooting</emphasis> of client host computer with an
 
216
      <emphasis>encrypted root file system</emphasis>.  See <xref
 
217
      linkend="overview"/> for details.
 
218
    </para>
 
219
 
 
220
  </refsect1>
 
221
  
 
222
  <refsect1 id="options">
 
223
    <title>OPTIONS</title>
 
224
 
 
225
    <variablelist>
 
226
      <varlistentry>
 
227
        <term><literal>-h</literal>, <literal>--help</literal></term>
 
228
        <listitem>
 
229
          <para>
 
230
            Show a help message and exit
 
231
          </para>
 
232
        </listitem>
 
233
      </varlistentry>
 
234
 
 
235
      <varlistentry>
 
236
        <term><literal>-d</literal>, <literal>--dir
 
237
        <replaceable>directory</replaceable></literal></term>
 
238
        <listitem>
 
239
          <para>
 
240
            Target directory for key files.  Default is
 
241
            <filename>/etc/mandos</filename>.
 
242
          </para>
 
243
        </listitem>
 
244
      </varlistentry>
 
245
 
 
246
      <varlistentry>
 
247
        <term><literal>-t</literal>, <literal>--type
 
248
        <replaceable>type</replaceable></literal></term>
 
249
        <listitem>
 
250
          <para>
 
251
            Key type.  Default is <quote>DSA</quote>.
 
252
          </para>
 
253
        </listitem>
 
254
      </varlistentry>
 
255
 
 
256
      <varlistentry>
 
257
        <term><literal>-l</literal>, <literal>--length
 
258
        <replaceable>bits</replaceable></literal></term>
 
259
        <listitem>
 
260
          <para>
 
261
            Key length in bits.  Default is 2048.
 
262
          </para>
 
263
        </listitem>
 
264
      </varlistentry>
 
265
 
 
266
      <varlistentry>
 
267
        <term><literal>-s</literal>, <literal>--subtype
 
268
        <replaceable>type</replaceable></literal></term>
 
269
        <listitem>
 
270
          <para>
 
271
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
 
272
            encryption-only).
 
273
          </para>
 
274
        </listitem>
 
275
      </varlistentry>
 
276
 
 
277
      <varlistentry>
 
278
        <term><literal>-L</literal>, <literal>--sublength
 
279
        <replaceable>bits</replaceable></literal></term>
 
280
        <listitem>
 
281
          <para>
 
282
            Subkey length in bits.  Default is 2048.
 
283
          </para>
 
284
        </listitem>
 
285
      </varlistentry>
 
286
 
 
287
      <varlistentry>
 
288
        <term><literal>-e</literal>, <literal>--email</literal>
 
289
        <replaceable>address</replaceable></term>
 
290
        <listitem>
 
291
          <para>
 
292
            Email address of key.  Default is empty.
 
293
          </para>
 
294
        </listitem>
 
295
      </varlistentry>
 
296
 
 
297
      <varlistentry>
 
298
        <term><literal>-c</literal>, <literal>--comment</literal>
 
299
        <replaceable>comment</replaceable></term>
 
300
        <listitem>
 
301
          <para>
 
302
            Comment field for key.  The default value is
 
303
            <quote><literal>Mandos client key</literal></quote>.
 
304
          </para>
 
305
        </listitem>
 
306
      </varlistentry>
 
307
 
 
308
      <varlistentry>
 
309
        <term><literal>-x</literal>, <literal>--expire</literal>
 
310
        <replaceable>time</replaceable></term>
 
311
        <listitem>
 
312
          <para>
 
313
            Key expire time.  Default is no expiration.  See
 
314
            <citerefentry><refentrytitle>gpg</refentrytitle>
 
315
            <manvolnum>1</manvolnum></citerefentry> for syntax.
 
316
          </para>
 
317
        </listitem>
 
318
      </varlistentry>
 
319
 
 
320
      <varlistentry>
 
321
        <term><literal>-f</literal>, <literal>--force</literal></term>
 
322
        <listitem>
 
323
          <para>
 
324
            Force overwriting old keys.
 
325
          </para>
 
326
        </listitem>
 
327
      </varlistentry>
 
328
      <varlistentry>
 
329
        <term><literal>-p</literal>, <literal>--password</literal
 
330
        ></term>
 
331
        <listitem>
 
332
          <para>
 
333
            Prompt for a password and encrypt it with the key already
 
334
            present in either <filename>/etc/mandos</filename> or the
 
335
            directory specified with the <option>--dir</option>
 
336
            option.  Outputs, on standard output, a section suitable
 
337
            for inclusion in <citerefentry><refentrytitle
 
338
            >mandos-clients.conf</refentrytitle><manvolnum
 
339
            >8</manvolnum></citerefentry>.  The host name or the name
 
340
            specified with the <option>--name</option> option is used
 
341
            for the section header.  All other options are ignored,
 
342
            and no keys are created.
 
343
          </para>
 
344
        </listitem>
 
345
      </varlistentry>
 
346
    </variablelist>
 
347
  </refsect1>
 
348
 
 
349
  <refsect1 id="overview">
 
350
    <title>OVERVIEW</title>
 
351
    <xi:include href="overview.xml"/>
 
352
    <para>
 
353
      This program is a small utility to generate new OpenPGP keys for
 
354
      new Mandos clients.
 
355
    </para>
 
356
  </refsect1>
 
357
 
 
358
  <refsect1 id="exit_status">
 
359
    <title>EXIT STATUS</title>
 
360
    <para>
 
361
      The exit status will be 0 if new keys were successfully created,
 
362
      otherwise not.
 
363
    </para>
 
364
  </refsect1>
 
365
  
 
366
  <refsect1 id="environment">
 
367
    <title>ENVIRONMENT</title>
 
368
    <variablelist>
 
369
      <varlistentry>
 
370
        <term><varname>TMPDIR</varname></term>
 
371
        <listitem>
 
372
          <para>
 
373
            If set, temporary files will be created here. See
 
374
            <citerefentry><refentrytitle>mktemp</refentrytitle>
 
375
            <manvolnum>1</manvolnum></citerefentry>.
 
376
          </para>
 
377
        </listitem>
 
378
      </varlistentry>
 
379
    </variablelist>
 
380
  </refsect1>
 
381
  
 
382
  <refsect1 id="file">
 
383
    <title>FILES</title>
 
384
    <para>
 
385
      Use the <option>--dir</option> option to change where
 
386
      <command>&COMMANDNAME;</command> will write the key files.  The
 
387
      default file names are shown here.
 
388
    </para>
 
389
    <variablelist>
 
390
      <varlistentry>
 
391
        <term><filename>/etc/mandos/seckey.txt</filename></term>
 
392
        <listitem>
 
393
          <para>
 
394
            OpenPGP secret key file which will be created or
 
395
            overwritten.
 
396
          </para>
 
397
        </listitem>
 
398
      </varlistentry>
 
399
      <varlistentry>
 
400
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
 
401
        <listitem>
 
402
          <para>
 
403
            OpenPGP public key file which will be created or
 
404
            overwritten.
 
405
          </para>
 
406
        </listitem>
 
407
      </varlistentry>
 
408
      <varlistentry>
 
409
        <term><filename>/tmp</filename></term>
 
410
        <listitem>
 
411
          <para>
 
412
            Temporary files will be written here if
 
413
            <varname>TMPDIR</varname> is not set.
 
414
          </para>
 
415
        </listitem>
 
416
      </varlistentry>
 
417
    </variablelist>
 
418
  </refsect1>
 
419
 
 
420
  <refsect1 id="bugs">
 
421
    <title>BUGS</title>
 
422
    <para>
 
423
      None are known at this time.
 
424
    </para>
 
425
  </refsect1>
 
426
 
 
427
  <refsect1 id="example">
 
428
    <title>EXAMPLE</title>
 
429
    <informalexample>
 
430
      <para>
 
431
        Normal invocation needs no options:
 
432
      </para>
 
433
      <para>
 
434
        <userinput>&COMMANDNAME;</userinput>
 
435
      </para>
 
436
    </informalexample>
 
437
    <informalexample>
 
438
      <para>
 
439
        Create keys in another directory and of another type.  Force
 
440
        overwriting old key files:
 
441
      </para>
 
442
      <para>
 
443
 
 
444
<!-- do not wrap this line -->
 
445
<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>
 
446
 
 
447
      </para>
 
448
    </informalexample>
 
449
  </refsect1>
 
450
 
 
451
  <refsect1 id="security">
 
452
    <title>SECURITY</title>
 
453
    <para>
 
454
      The <option>--type</option>, <option>--length</option>,
 
455
      <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.
 
458
    </para>
 
459
    <para>
 
460
      The key expire time is not guaranteed to be honored by
 
461
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
462
      <manvolnum>8</manvolnum></citerefentry>.
 
463
    </para>
 
464
  </refsect1>
 
465
 
 
466
  <refsect1 id="see_also">
 
467
    <title>SEE ALSO</title>
 
468
    <para>
 
469
      <citerefentry><refentrytitle>gpg</refentrytitle>
 
470
      <manvolnum>1</manvolnum></citerefentry>,
 
471
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
472
      <manvolnum>8</manvolnum></citerefentry>,
 
473
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
474
      <manvolnum>8mandos</manvolnum></citerefentry>
 
475
    </para>
 
476
  </refsect1>
 
477
  
 
478
</refentry>
 
479
<!-- Local Variables: -->
 
480
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
 
481
<!-- time-stamp-end: "[\"']>" -->
 
482
<!-- time-stamp-format: "%:y-%02m-%02d" -->
 
483
<!-- End: -->