/mandos/release

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/release
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">
111 by Teddy Hogeborn
* mandos-clients.conf.xml (ENTITY TIMESTAMP): New. Automatically
6
<!ENTITY TIMESTAMP "2008-08-29">
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
7
]>
8
91 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Include all DocBook-to-manpage-related
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
10
  <refentryinfo>
11
    <title>&COMMANDNAME;</title>
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
12
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
13
    <productname>&COMMANDNAME;</productname>
14
    <productnumber>&VERSION;</productnumber>
111 by Teddy Hogeborn
* mandos-clients.conf.xml (ENTITY TIMESTAMP): New. Automatically
15
    <date>&TIMESTAMP;</date>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
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>
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
34
      <holder>Teddy Hogeborn</holder>
35
      <holder>Björn Påhlsson</holder>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
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">
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
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">
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
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">
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
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">
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
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">
97 by Teddy Hogeborn
* mandos-keygen: Bug fix: Recognize new options --subtype and
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">
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
178
	<arg choice="plain"><option>-h</option></arg>
179
	<arg choice="plain"><option>--help</option></arg>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
180
      </group>
181
    </cmdsynopsis>
182
    <cmdsynopsis>
183
      <command>&COMMANDNAME;</command>
184
      <group choice="req">
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
185
	<arg choice="plain"><option>-v</option></arg>
186
	<arg choice="plain"><option>--version</option></arg>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
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>
97 by Teddy Hogeborn
* mandos-keygen: Bug fix: Recognize new options --subtype and
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>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
208
  </refsect1>
209
  
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
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
  
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
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>
97 by Teddy Hogeborn
* mandos-keygen: Bug fix: Recognize new options --subtype and
240
	    Target directory for key files.  Default is
241
	    <filename>/etc/mandos</filename>.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
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>
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
251
	    Key type.  Default is <quote>DSA</quote>.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
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>
104 by Teddy Hogeborn
* Makefile (maintainer-clean): Also remove "confdir".
261
	    Key length in bits.  Default is 2048.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
262
	  </para>
263
	</listitem>
264
      </varlistentry>
265
266
      <varlistentry>
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
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>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
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
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
303
	    <quote><literal>Mandos client key</literal></quote>.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
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>
97 by Teddy Hogeborn
* mandos-keygen: Bug fix: Recognize new options --subtype and
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>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
346
    </variablelist>
347
  </refsect1>
348
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
349
  <refsect1 id="overview">
350
    <title>OVERVIEW</title>
91 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Include all DocBook-to-manpage-related
351
    <xi:include href="overview.xml"/>
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
352
    <para>
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
353
      This program is a small utility to generate new OpenPGP keys for
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
354
      new Mandos clients.
355
    </para>
356
  </refsect1>
357
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
358
  <refsect1 id="exit_status">
359
    <title>EXIT STATUS</title>
360
    <para>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
361
      The exit status will be 0 if new keys were successfully created,
362
      otherwise not.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
363
    </para>
364
  </refsect1>
365
  
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
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
  
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
382
  <refsect1 id="file">
383
    <title>FILES</title>
384
    <para>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
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.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
388
    </para>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
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>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
418
  </refsect1>
419
420
  <refsect1 id="bugs">
421
    <title>BUGS</title>
422
    <para>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
423
      None are known at this time.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
424
    </para>
425
  </refsect1>
426
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
427
  <refsect1 id="example">
428
    <title>EXAMPLE</title>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
429
    <informalexample>
430
      <para>
431
	Normal invocation needs no options:
432
      </para>
433
      <para>
434
	<userinput>mandos-keygen</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>mandos-keygen --dir ~/keydir --type RSA --force</userinput>
446
447
      </para>
448
    </informalexample>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
449
  </refsect1>
450
451
  <refsect1 id="security">
452
    <title>SECURITY</title>
453
    <para>
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
454
      The <option>--type</option>, <option>--length</option>,
455
      <option>--subtype</option>, and <option>--sublength</option>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
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>.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
463
    </para>
464
  </refsect1>
465
466
  <refsect1 id="see_also">
467
    <title>SEE ALSO</title>
468
    <para>
469
      <citerefentry><refentrytitle>password-request</refentrytitle>
470
      <manvolnum>8mandos</manvolnum></citerefentry>,
471
      <citerefentry><refentrytitle>mandos</refentrytitle>
92 by Teddy Hogeborn
* mandos-keygen.xml (SEE ALSO): Remove "and".
472
      <manvolnum>8</manvolnum></citerefentry>,
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
473
      <citerefentry><refentrytitle>gpg</refentrytitle>
474
      <manvolnum>1</manvolnum></citerefentry>
475
    </para>
476
  </refsect1>
477
  
478
</refentry>
111 by Teddy Hogeborn
* mandos-clients.conf.xml (ENTITY TIMESTAMP): New. Automatically
479
<!-- Local Variables: -->
480
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
481
<!-- time-stamp-end: "[\"']>" -->
482
<!-- time-stamp-format: "%:y-%02m-%02d" -->
483
<!-- End: -->