/mandos/trunk

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/trunk
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
1
<?xml version="1.0" encoding="UTF-8"?>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(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
]>
7
91 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Include all DocBook-to-manpage-related
8
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
9
  <refentryinfo>
10
    <title>&COMMANDNAME;</title>
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
11
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
12
    <productname>&COMMANDNAME;</productname>
13
    <productnumber>&VERSION;</productnumber>
14
    <authorgroup>
15
      <author>
16
	<firstname>Björn</firstname>
17
	<surname>Påhlsson</surname>
18
	<address>
19
	  <email>belorn@fukt.bsnet.se</email>
20
	</address>
21
      </author>
22
      <author>
23
	<firstname>Teddy</firstname>
24
	<surname>Hogeborn</surname>
25
	<address>
26
	  <email>teddy@fukt.bsnet.se</email>
27
	</address>
28
      </author>
29
    </authorgroup>
30
    <copyright>
31
      <year>2008</year>
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
32
      <holder>Teddy Hogeborn</holder>
33
      <holder>Björn Påhlsson</holder>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
34
    </copyright>
35
    <legalnotice>
36
      <para>
37
	This manual page is free software: you can redistribute it
38
	and/or modify it under the terms of the GNU General Public
39
	License as published by the Free Software Foundation,
40
	either version 3 of the License, or (at your option) any
41
	later version.
42
      </para>
43
44
      <para>
45
	This manual page is distributed in the hope that it will
46
	be useful, but WITHOUT ANY WARRANTY; without even the
47
	implied warranty of MERCHANTABILITY or FITNESS FOR A
48
	PARTICULAR PURPOSE.  See the GNU General Public License
49
	for more details.
50
      </para>
51
52
      <para>
53
	You should have received a copy of the GNU General Public
54
	License along with this program; If not, see
55
	<ulink url="http://www.gnu.org/licenses/"/>.
56
      </para>
57
    </legalnotice>
58
  </refentryinfo>
59
60
  <refmeta>
61
    <refentrytitle>&COMMANDNAME;</refentrytitle>
62
    <manvolnum>8</manvolnum>
63
  </refmeta>
64
  
65
  <refnamediv>
66
    <refname><command>&COMMANDNAME;</command></refname>
67
    <refpurpose>
68
      Generate keys for <citerefentry><refentrytitle>password-request
69
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
70
    </refpurpose>
71
  </refnamediv>
72
73
  <refsynopsisdiv>
74
    <cmdsynopsis>
75
      <command>&COMMANDNAME;</command>
76
      <group choice="opt">
77
	<arg choice="plain"><option>--dir</option>
78
	<replaceable>directory</replaceable></arg>
79
      </group>
80
      <group choice="opt">
81
	<arg choice="plain"><option>--type</option>
82
	<replaceable>type</replaceable></arg>
83
      </group>
84
      <group choice="opt">
85
	<arg choice="plain"><option>--length</option>
86
	<replaceable>bits</replaceable></arg>
87
      </group>
88
      <group choice="opt">
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
89
	<arg choice="plain"><option>--subtype</option>
90
	<replaceable>type</replaceable></arg>
91
      </group>
92
      <group choice="opt">
93
	<arg choice="plain"><option>--sublength</option>
94
	<replaceable>bits</replaceable></arg>
95
      </group>
96
      <group choice="opt">
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
97
	<arg choice="plain"><option>--name</option>
98
	<replaceable>NAME</replaceable></arg>
99
      </group>
100
      <group choice="opt">
101
	<arg choice="plain"><option>--email</option>
102
	<replaceable>EMAIL</replaceable></arg>
103
      </group>
104
      <group choice="opt">
105
	<arg choice="plain"><option>--comment</option>
106
	<replaceable>COMMENT</replaceable></arg>
107
      </group>
108
      <group choice="opt">
109
	<arg choice="plain"><option>--expire</option>
110
	<replaceable>TIME</replaceable></arg>
111
      </group>
112
      <group choice="opt">
113
	<arg choice="plain"><option>--force</option></arg>
114
      </group>
115
    </cmdsynopsis>
116
    <cmdsynopsis>
117
      <command>&COMMANDNAME;</command>
118
      <group choice="opt">
119
	<arg choice="plain"><option>-d</option>
120
	<replaceable>directory</replaceable></arg>
121
      </group>
122
      <group choice="opt">
123
	<arg choice="plain"><option>-t</option>
124
	<replaceable>type</replaceable></arg>
125
      </group>
126
      <group choice="opt">
127
	<arg choice="plain"><option>-l</option>
128
	<replaceable>bits</replaceable></arg>
129
      </group>
130
      <group choice="opt">
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
131
	<arg choice="plain"><option>-s</option>
132
	<replaceable>type</replaceable></arg>
133
      </group>
134
      <group choice="opt">
135
	<arg choice="plain"><option>-L</option>
136
	<replaceable>bits</replaceable></arg>
137
      </group>
138
      <group choice="opt">
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
139
	<arg choice="plain"><option>-n</option>
140
	<replaceable>NAME</replaceable></arg>
141
      </group>
142
      <group choice="opt">
143
	<arg choice="plain"><option>-e</option>
144
	<replaceable>EMAIL</replaceable></arg>
145
      </group>
146
      <group choice="opt">
147
	<arg choice="plain"><option>-c</option>
148
	<replaceable>COMMENT</replaceable></arg>
149
      </group>
150
      <group choice="opt">
151
	<arg choice="plain"><option>-x</option>
152
	<replaceable>TIME</replaceable></arg>
153
      </group>
154
      <group choice="opt">
155
	<arg choice="plain"><option>-f</option></arg>
156
      </group>
157
    </cmdsynopsis>
158
    <cmdsynopsis>
159
      <command>&COMMANDNAME;</command>
160
      <group choice="req">
97 by Teddy Hogeborn
* mandos-keygen: Bug fix: Recognize new options --subtype and
161
	<arg choice="plain"><option>-p</option></arg>
162
	<arg choice="plain"><option>--password</option></arg>
163
      </group>
164
      <group choice="opt">
165
	<arg choice="plain"><option>--dir</option>
166
	<replaceable>directory</replaceable></arg>
167
      </group>
168
      <group choice="opt">
169
	<arg choice="plain"><option>--name</option>
170
	<replaceable>NAME</replaceable></arg>
171
      </group>
172
    </cmdsynopsis>
173
    <cmdsynopsis>
174
      <command>&COMMANDNAME;</command>
175
      <group choice="req">
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
176
	<arg choice="plain"><option>-h</option></arg>
177
	<arg choice="plain"><option>--help</option></arg>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
178
      </group>
179
    </cmdsynopsis>
180
    <cmdsynopsis>
181
      <command>&COMMANDNAME;</command>
182
      <group choice="req">
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
183
	<arg choice="plain"><option>-v</option></arg>
184
	<arg choice="plain"><option>--version</option></arg>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
185
      </group>
186
    </cmdsynopsis>
187
  </refsynopsisdiv>
188
189
  <refsect1 id="description">
190
    <title>DESCRIPTION</title>
191
    <para>
192
      <command>&COMMANDNAME;</command> is a program to generate the
193
      OpenPGP keys used by
194
      <citerefentry><refentrytitle>password-request</refentrytitle>
195
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
196
      normally written to /etc/mandos for later installation into the
197
      initrd image, but this, like most things, can be changed with
198
      command line options.
199
    </para>
97 by Teddy Hogeborn
* mandos-keygen: Bug fix: Recognize new options --subtype and
200
    <para>
201
      It can also be used to generate ready-made sections for
202
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
203
      <manvolnum>5</manvolnum></citerefentry> using the
204
      <option>--password</option> option.
205
    </para>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
206
  </refsect1>
207
  
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
208
  <refsect1 id="purpose">
209
    <title>PURPOSE</title>
210
211
    <para>
212
      The purpose of this is to enable <emphasis>remote and unattended
213
      rebooting</emphasis> of client host computer with an
214
      <emphasis>encrypted root file system</emphasis>.  See <xref
215
      linkend="overview"/> for details.
216
    </para>
217
218
  </refsect1>
219
  
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
220
  <refsect1 id="options">
221
    <title>OPTIONS</title>
222
223
    <variablelist>
224
      <varlistentry>
225
	<term><literal>-h</literal>, <literal>--help</literal></term>
226
	<listitem>
227
	  <para>
228
	    Show a help message and exit
229
	  </para>
230
	</listitem>
231
      </varlistentry>
232
233
      <varlistentry>
234
	<term><literal>-d</literal>, <literal>--dir
235
	<replaceable>directory</replaceable></literal></term>
236
	<listitem>
237
	  <para>
97 by Teddy Hogeborn
* mandos-keygen: Bug fix: Recognize new options --subtype and
238
	    Target directory for key files.  Default is
239
	    <filename>/etc/mandos</filename>.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
240
	  </para>
241
	</listitem>
242
      </varlistentry>
243
244
      <varlistentry>
245
	<term><literal>-t</literal>, <literal>--type
246
	<replaceable>type</replaceable></literal></term>
247
	<listitem>
248
	  <para>
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
249
	    Key type.  Default is <quote>DSA</quote>.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
250
	  </para>
251
	</listitem>
252
      </varlistentry>
253
254
      <varlistentry>
255
	<term><literal>-l</literal>, <literal>--length
256
	<replaceable>bits</replaceable></literal></term>
257
	<listitem>
258
	  <para>
104 by Teddy Hogeborn
* Makefile (maintainer-clean): Also remove "confdir".
259
	    Key length in bits.  Default is 2048.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
260
	  </para>
261
	</listitem>
262
      </varlistentry>
263
264
      <varlistentry>
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
265
	<term><literal>-s</literal>, <literal>--subtype
266
	<replaceable>type</replaceable></literal></term>
267
	<listitem>
268
	  <para>
269
	    Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
270
	    encryption-only).
271
	  </para>
272
	</listitem>
273
      </varlistentry>
274
275
      <varlistentry>
276
	<term><literal>-L</literal>, <literal>--sublength
277
	<replaceable>bits</replaceable></literal></term>
278
	<listitem>
279
	  <para>
280
	    Subkey length in bits.  Default is 2048.
281
	  </para>
282
	</listitem>
283
      </varlistentry>
284
285
      <varlistentry>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
286
	<term><literal>-e</literal>, <literal>--email</literal>
287
	<replaceable>address</replaceable></term>
288
	<listitem>
289
	  <para>
290
	    Email address of key.  Default is empty.
291
	  </para>
292
	</listitem>
293
      </varlistentry>
294
295
      <varlistentry>
296
	<term><literal>-c</literal>, <literal>--comment</literal>
297
	<replaceable>comment</replaceable></term>
298
	<listitem>
299
	  <para>
300
	    Comment field for key.  The default value is
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
301
	    <quote><literal>Mandos client key</literal></quote>.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
302
	  </para>
303
	</listitem>
304
      </varlistentry>
305
306
      <varlistentry>
307
	<term><literal>-x</literal>, <literal>--expire</literal>
308
	<replaceable>time</replaceable></term>
309
	<listitem>
310
	  <para>
311
	    Key expire time.  Default is no expiration.  See
312
	    <citerefentry><refentrytitle>gpg</refentrytitle>
313
	    <manvolnum>1</manvolnum></citerefentry> for syntax.
314
	  </para>
315
	</listitem>
316
      </varlistentry>
317
318
      <varlistentry>
319
	<term><literal>-f</literal>, <literal>--force</literal></term>
320
	<listitem>
321
	  <para>
322
	    Force overwriting old keys.
323
	  </para>
324
	</listitem>
325
      </varlistentry>
97 by Teddy Hogeborn
* mandos-keygen: Bug fix: Recognize new options --subtype and
326
      <varlistentry>
327
	<term><literal>-p</literal>, <literal>--password</literal
328
	></term>
329
	<listitem>
330
	  <para>
331
	    Prompt for a password and encrypt it with the key already
332
	    present in either <filename>/etc/mandos</filename> or the
333
	    directory specified with the <option>--dir</option>
334
	    option.  Outputs, on standard output, a section suitable
335
	    for inclusion in <citerefentry><refentrytitle
336
	    >mandos-clients.conf</refentrytitle><manvolnum
337
	    >8</manvolnum></citerefentry>.  The host name or the name
338
	    specified with the <option>--name</option> option is used
339
	    for the section header.  All other options are ignored,
340
	    and no keys are created.
341
	  </para>
342
	</listitem>
343
      </varlistentry>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
344
    </variablelist>
345
  </refsect1>
346
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
347
  <refsect1 id="overview">
348
    <title>OVERVIEW</title>
91 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Include all DocBook-to-manpage-related
349
    <xi:include href="overview.xml"/>
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
350
    <para>
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
351
      This program is a small utility to generate new OpenPGP keys for
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
352
      new Mandos clients.
353
    </para>
354
  </refsect1>
355
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
356
  <refsect1 id="exit_status">
357
    <title>EXIT STATUS</title>
358
    <para>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
359
      The exit status will be 0 if new keys were successfully created,
360
      otherwise not.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
361
    </para>
362
  </refsect1>
363
  
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
364
  <refsect1 id="environment">
365
    <title>ENVIRONMENT</title>
366
    <variablelist>
367
      <varlistentry>
368
	<term><varname>TMPDIR</varname></term>
369
	<listitem>
370
	  <para>
371
	    If set, temporary files will be created here. See
372
	    <citerefentry><refentrytitle>mktemp</refentrytitle>
373
	    <manvolnum>1</manvolnum></citerefentry>.
374
	  </para>
375
	</listitem>
376
      </varlistentry>
377
    </variablelist>
378
  </refsect1>
379
  
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
380
  <refsect1 id="file">
381
    <title>FILES</title>
382
    <para>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
383
      Use the <option>--dir</option> option to change where
384
      <command>&COMMANDNAME;</command> will write the key files.  The
385
      default file names are shown here.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
386
    </para>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
387
    <variablelist>
388
      <varlistentry>
389
	<term><filename>/etc/mandos/seckey.txt</filename></term>
390
	<listitem>
391
	  <para>
392
	    OpenPGP secret key file which will be created or
393
	    overwritten.
394
	  </para>
395
	</listitem>
396
      </varlistentry>
397
      <varlistentry>
398
	<term><filename>/etc/mandos/pubkey.txt</filename></term>
399
	<listitem>
400
	  <para>
401
	    OpenPGP public key file which will be created or
402
	    overwritten.
403
	  </para>
404
	</listitem>
405
      </varlistentry>
406
      <varlistentry>
407
	<term><filename>/tmp</filename></term>
408
	<listitem>
409
	  <para>
410
	    Temporary files will be written here if
411
	    <varname>TMPDIR</varname> is not set.
412
	  </para>
413
	</listitem>
414
      </varlistentry>
415
    </variablelist>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
416
  </refsect1>
417
418
  <refsect1 id="bugs">
419
    <title>BUGS</title>
420
    <para>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
421
      None are known at this time.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
422
    </para>
423
  </refsect1>
424
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
425
  <refsect1 id="example">
426
    <title>EXAMPLE</title>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
427
    <informalexample>
428
      <para>
429
	Normal invocation needs no options:
430
      </para>
431
      <para>
432
	<userinput>mandos-keygen</userinput>
433
      </para>
434
    </informalexample>
435
    <informalexample>
436
      <para>
437
	Create keys in another directory and of another type.  Force
438
	overwriting old key files:
439
      </para>
440
      <para>
441
442
<!-- do not wrap this line -->
443
<userinput>mandos-keygen --dir ~/keydir --type RSA --force</userinput>
444
445
      </para>
446
    </informalexample>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
447
  </refsect1>
448
449
  <refsect1 id="security">
450
    <title>SECURITY</title>
451
    <para>
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
452
      The <option>--type</option>, <option>--length</option>,
453
      <option>--subtype</option>, and <option>--sublength</option>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
454
      options can be used to create keys of insufficient security.  If
455
      in doubt, leave them to the default values.
456
    </para>
457
    <para>
458
      The key expire time is not guaranteed to be honored by
459
      <citerefentry><refentrytitle>mandos</refentrytitle>
460
      <manvolnum>8</manvolnum></citerefentry>.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
461
    </para>
462
  </refsect1>
463
464
  <refsect1 id="see_also">
465
    <title>SEE ALSO</title>
466
    <para>
467
      <citerefentry><refentrytitle>password-request</refentrytitle>
468
      <manvolnum>8mandos</manvolnum></citerefentry>,
469
      <citerefentry><refentrytitle>mandos</refentrytitle>
92 by Teddy Hogeborn
* mandos-keygen.xml (SEE ALSO): Remove "and".
470
      <manvolnum>8</manvolnum></citerefentry>,
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
471
      <citerefentry><refentrytitle>gpg</refentrytitle>
472
      <manvolnum>1</manvolnum></citerefentry>
473
    </para>
474
  </refsect1>
475
  
476
</refentry>