/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">
117 by Teddy Hogeborn
* mandos-keygen.xml (ENVIRONMENT): Replaced <varname> with <envar>.
6
<!ENTITY TIMESTAMP "2008-08-30">
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>
112 by Teddy Hogeborn
* mandos-clients.conf.xml (/refentry/refentryinfo/title): Changed to
11
    <title>Mandos Manual</title>
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
12
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
112 by Teddy Hogeborn
* mandos-clients.conf.xml (/refentry/refentryinfo/title): Changed to
13
    <productname>Mandos</productname>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
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>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
78
      <group>
79
	<arg choice="plain"><option>--dir
80
	<replaceable>DIRECTORY</replaceable></option></arg>
81
	<arg choice="plain"><option>-d
82
	<replaceable>DIRECTORY</replaceable></option></arg>
83
      </group>
84
      <sbr/>
85
      <group>
86
	<arg choice="plain"><option>--type
87
	<replaceable>KEYTYPE</replaceable></option></arg>
88
	<arg choice="plain"><option>-t
89
	<replaceable>KEYTYPE</replaceable></option></arg>
90
      </group>
91
      <sbr/>
92
      <group>
93
	<arg choice="plain"><option>--length
94
	<replaceable>BITS</replaceable></option></arg>
95
	<arg choice="plain"><option>-l
96
	<replaceable>BITS</replaceable></option></arg>
97
      </group>
98
      <sbr/>
99
      <group>
100
	<arg choice="plain"><option>--subtype
101
	<replaceable>KEYTYPE</replaceable></option></arg>
102
	<arg choice="plain"><option>-s
103
	<replaceable>KEYTYPE</replaceable></option></arg>
104
      </group>
105
      <sbr/>
106
      <group>
107
	<arg choice="plain"><option>--sublength
108
	<replaceable>BITS</replaceable></option></arg>
109
	<arg choice="plain"><option>-L
110
	<replaceable>BITS</replaceable></option></arg>
111
      </group>
112
      <sbr/>
113
      <group>
114
	<arg choice="plain"><option>--name
115
	<replaceable>NAME</replaceable></option></arg>
116
	<arg choice="plain"><option>-n
117
	<replaceable>NAME</replaceable></option></arg>
118
      </group>
119
      <sbr/>
120
      <group>
121
	<arg choice="plain"><option>--email
122
	<replaceable>ADDRESS</replaceable></option></arg>
123
	<arg choice="plain"><option>-e
124
	<replaceable>ADDRESS</replaceable></option></arg>
125
      </group>
126
      <sbr/>
127
      <group>
128
	<arg choice="plain"><option>--comment
129
	<replaceable>TEXT</replaceable></option></arg>
130
	<arg choice="plain"><option>-c
131
	<replaceable>TEXT</replaceable></option></arg>
132
      </group>
133
      <sbr/>
134
      <group>
135
	<arg choice="plain"><option>--expire
136
	<replaceable>TIME</replaceable></option></arg>
137
	<arg choice="plain"><option>-x
138
	<replaceable>TIME</replaceable></option></arg>
139
      </group>
140
      <sbr/>
141
      <arg><option>--force</option></arg>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
142
    </cmdsynopsis>
143
    <cmdsynopsis>
144
      <command>&COMMANDNAME;</command>
145
      <group choice="req">
97 by Teddy Hogeborn
* mandos-keygen: Bug fix: Recognize new options --subtype and
146
	<arg choice="plain"><option>-p</option></arg>
147
	<arg choice="plain"><option>--password</option></arg>
148
      </group>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
149
      <sbr/>
150
      <group>
151
	<arg choice="plain"><option>--dir
152
	<replaceable>DIRECTORY</replaceable></option></arg>
153
	<arg choice="plain"><option>-d
154
	<replaceable>DIRECTORY</replaceable></option></arg>
97 by Teddy Hogeborn
* mandos-keygen: Bug fix: Recognize new options --subtype and
155
      </group>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
156
      <sbr/>
157
      <group>
158
	<arg choice="plain"><option>--name
159
	<replaceable>NAME</replaceable></option></arg>
160
	<arg choice="plain"><option>-n
161
	<replaceable>NAME</replaceable></option></arg>
97 by Teddy Hogeborn
* mandos-keygen: Bug fix: Recognize new options --subtype and
162
      </group>
163
    </cmdsynopsis>
164
    <cmdsynopsis>
165
      <command>&COMMANDNAME;</command>
166
      <group choice="req">
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
167
	<arg choice="plain"><option>-h</option></arg>
168
	<arg choice="plain"><option>--help</option></arg>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
169
      </group>
170
    </cmdsynopsis>
171
    <cmdsynopsis>
172
      <command>&COMMANDNAME;</command>
173
      <group choice="req">
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
174
	<arg choice="plain"><option>-v</option></arg>
175
	<arg choice="plain"><option>--version</option></arg>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
176
      </group>
177
    </cmdsynopsis>
178
  </refsynopsisdiv>
179
180
  <refsect1 id="description">
181
    <title>DESCRIPTION</title>
182
    <para>
183
      <command>&COMMANDNAME;</command> is a program to generate the
184
      OpenPGP keys used by
185
      <citerefentry><refentrytitle>password-request</refentrytitle>
186
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
187
      normally written to /etc/mandos for later installation into the
188
      initrd image, but this, like most things, can be changed with
189
      command line options.
190
    </para>
97 by Teddy Hogeborn
* mandos-keygen: Bug fix: Recognize new options --subtype and
191
    <para>
192
      It can also be used to generate ready-made sections for
193
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
194
      <manvolnum>5</manvolnum></citerefentry> using the
195
      <option>--password</option> option.
196
    </para>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
197
  </refsect1>
198
  
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
199
  <refsect1 id="purpose">
200
    <title>PURPOSE</title>
201
202
    <para>
203
      The purpose of this is to enable <emphasis>remote and unattended
204
      rebooting</emphasis> of client host computer with an
205
      <emphasis>encrypted root file system</emphasis>.  See <xref
206
      linkend="overview"/> for details.
207
    </para>
208
209
  </refsect1>
210
  
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
211
  <refsect1 id="options">
212
    <title>OPTIONS</title>
213
214
    <variablelist>
215
      <varlistentry>
216
	<term><literal>-h</literal>, <literal>--help</literal></term>
217
	<listitem>
218
	  <para>
219
	    Show a help message and exit
220
	  </para>
221
	</listitem>
222
      </varlistentry>
223
224
      <varlistentry>
225
	<term><literal>-d</literal>, <literal>--dir
226
	<replaceable>directory</replaceable></literal></term>
227
	<listitem>
228
	  <para>
97 by Teddy Hogeborn
* mandos-keygen: Bug fix: Recognize new options --subtype and
229
	    Target directory for key files.  Default is
230
	    <filename>/etc/mandos</filename>.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
231
	  </para>
232
	</listitem>
233
      </varlistentry>
234
235
      <varlistentry>
236
	<term><literal>-t</literal>, <literal>--type
237
	<replaceable>type</replaceable></literal></term>
238
	<listitem>
239
	  <para>
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
240
	    Key type.  Default is <quote>DSA</quote>.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
241
	  </para>
242
	</listitem>
243
      </varlistentry>
244
245
      <varlistentry>
246
	<term><literal>-l</literal>, <literal>--length
247
	<replaceable>bits</replaceable></literal></term>
248
	<listitem>
249
	  <para>
104 by Teddy Hogeborn
* Makefile (maintainer-clean): Also remove "confdir".
250
	    Key length in bits.  Default is 2048.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
251
	  </para>
252
	</listitem>
253
      </varlistentry>
254
255
      <varlistentry>
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
256
	<term><literal>-s</literal>, <literal>--subtype
257
	<replaceable>type</replaceable></literal></term>
258
	<listitem>
259
	  <para>
260
	    Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
261
	    encryption-only).
262
	  </para>
263
	</listitem>
264
      </varlistentry>
265
266
      <varlistentry>
267
	<term><literal>-L</literal>, <literal>--sublength
268
	<replaceable>bits</replaceable></literal></term>
269
	<listitem>
270
	  <para>
271
	    Subkey length in bits.  Default is 2048.
272
	  </para>
273
	</listitem>
274
      </varlistentry>
275
276
      <varlistentry>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
277
	<term><literal>-e</literal>, <literal>--email</literal>
278
	<replaceable>address</replaceable></term>
279
	<listitem>
280
	  <para>
281
	    Email address of key.  Default is empty.
282
	  </para>
283
	</listitem>
284
      </varlistentry>
285
286
      <varlistentry>
287
	<term><literal>-c</literal>, <literal>--comment</literal>
288
	<replaceable>comment</replaceable></term>
289
	<listitem>
290
	  <para>
291
	    Comment field for key.  The default value is
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
292
	    <quote><literal>Mandos client key</literal></quote>.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
293
	  </para>
294
	</listitem>
295
      </varlistentry>
296
297
      <varlistentry>
298
	<term><literal>-x</literal>, <literal>--expire</literal>
299
	<replaceable>time</replaceable></term>
300
	<listitem>
301
	  <para>
302
	    Key expire time.  Default is no expiration.  See
303
	    <citerefentry><refentrytitle>gpg</refentrytitle>
304
	    <manvolnum>1</manvolnum></citerefentry> for syntax.
305
	  </para>
306
	</listitem>
307
      </varlistentry>
308
309
      <varlistentry>
310
	<term><literal>-f</literal>, <literal>--force</literal></term>
311
	<listitem>
312
	  <para>
313
	    Force overwriting old keys.
314
	  </para>
315
	</listitem>
316
      </varlistentry>
97 by Teddy Hogeborn
* mandos-keygen: Bug fix: Recognize new options --subtype and
317
      <varlistentry>
318
	<term><literal>-p</literal>, <literal>--password</literal
319
	></term>
320
	<listitem>
321
	  <para>
322
	    Prompt for a password and encrypt it with the key already
323
	    present in either <filename>/etc/mandos</filename> or the
324
	    directory specified with the <option>--dir</option>
325
	    option.  Outputs, on standard output, a section suitable
326
	    for inclusion in <citerefentry><refentrytitle
327
	    >mandos-clients.conf</refentrytitle><manvolnum
328
	    >8</manvolnum></citerefentry>.  The host name or the name
329
	    specified with the <option>--name</option> option is used
330
	    for the section header.  All other options are ignored,
331
	    and no keys are created.
332
	  </para>
333
	</listitem>
334
      </varlistentry>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
335
    </variablelist>
336
  </refsect1>
337
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
338
  <refsect1 id="overview">
339
    <title>OVERVIEW</title>
91 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Include all DocBook-to-manpage-related
340
    <xi:include href="overview.xml"/>
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
341
    <para>
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
342
      This program is a small utility to generate new OpenPGP keys for
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
343
      new Mandos clients.
344
    </para>
345
  </refsect1>
346
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
347
  <refsect1 id="exit_status">
348
    <title>EXIT STATUS</title>
349
    <para>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
350
      The exit status will be 0 if new keys were successfully created,
351
      otherwise not.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
352
    </para>
353
  </refsect1>
354
  
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
355
  <refsect1 id="environment">
356
    <title>ENVIRONMENT</title>
357
    <variablelist>
358
      <varlistentry>
117 by Teddy Hogeborn
* mandos-keygen.xml (ENVIRONMENT): Replaced <varname> with <envar>.
359
	<term><envar>TMPDIR</envar></term>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
360
	<listitem>
361
	  <para>
362
	    If set, temporary files will be created here. See
363
	    <citerefentry><refentrytitle>mktemp</refentrytitle>
364
	    <manvolnum>1</manvolnum></citerefentry>.
365
	  </para>
366
	</listitem>
367
      </varlistentry>
368
    </variablelist>
369
  </refsect1>
370
  
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
371
  <refsect1 id="file">
372
    <title>FILES</title>
373
    <para>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
374
      Use the <option>--dir</option> option to change where
375
      <command>&COMMANDNAME;</command> will write the key files.  The
376
      default file names are shown here.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
377
    </para>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
378
    <variablelist>
379
      <varlistentry>
380
	<term><filename>/etc/mandos/seckey.txt</filename></term>
381
	<listitem>
382
	  <para>
383
	    OpenPGP secret key file which will be created or
384
	    overwritten.
385
	  </para>
386
	</listitem>
387
      </varlistentry>
388
      <varlistentry>
389
	<term><filename>/etc/mandos/pubkey.txt</filename></term>
390
	<listitem>
391
	  <para>
392
	    OpenPGP public key file which will be created or
393
	    overwritten.
394
	  </para>
395
	</listitem>
396
      </varlistentry>
397
      <varlistentry>
398
	<term><filename>/tmp</filename></term>
399
	<listitem>
400
	  <para>
401
	    Temporary files will be written here if
402
	    <varname>TMPDIR</varname> is not set.
403
	  </para>
404
	</listitem>
405
      </varlistentry>
406
    </variablelist>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
407
  </refsect1>
408
409
  <refsect1 id="bugs">
410
    <title>BUGS</title>
411
    <para>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
412
      None are known at this time.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
413
    </para>
414
  </refsect1>
415
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
416
  <refsect1 id="example">
417
    <title>EXAMPLE</title>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
418
    <informalexample>
419
      <para>
420
	Normal invocation needs no options:
421
      </para>
422
      <para>
113 by Teddy Hogeborn
* mandos-keygen.xml (EXAMPLE): Replaced all occurrences of command
423
	<userinput>&COMMANDNAME;</userinput>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
424
      </para>
425
    </informalexample>
426
    <informalexample>
427
      <para>
428
	Create keys in another directory and of another type.  Force
429
	overwriting old key files:
430
      </para>
431
      <para>
432
433
<!-- do not wrap this line -->
113 by Teddy Hogeborn
* mandos-keygen.xml (EXAMPLE): Replaced all occurrences of command
434
<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
435
436
      </para>
437
    </informalexample>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
438
  </refsect1>
439
440
  <refsect1 id="security">
441
    <title>SECURITY</title>
442
    <para>
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
443
      The <option>--type</option>, <option>--length</option>,
444
      <option>--subtype</option>, and <option>--sublength</option>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
445
      options can be used to create keys of insufficient security.  If
446
      in doubt, leave them to the default values.
447
    </para>
448
    <para>
449
      The key expire time is not guaranteed to be honored by
450
      <citerefentry><refentrytitle>mandos</refentrytitle>
451
      <manvolnum>8</manvolnum></citerefentry>.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
452
    </para>
453
  </refsect1>
454
455
  <refsect1 id="see_also">
456
    <title>SEE ALSO</title>
457
    <para>
114 by Teddy Hogeborn
* mandos-clients.conf.xml (SEE ALSO): Alphabetized, as per
458
      <citerefentry><refentrytitle>gpg</refentrytitle>
459
      <manvolnum>1</manvolnum></citerefentry>,
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
460
      <citerefentry><refentrytitle>mandos</refentrytitle>
92 by Teddy Hogeborn
* mandos-keygen.xml (SEE ALSO): Remove "and".
461
      <manvolnum>8</manvolnum></citerefentry>,
114 by Teddy Hogeborn
* mandos-clients.conf.xml (SEE ALSO): Alphabetized, as per
462
      <citerefentry><refentrytitle>password-request</refentrytitle>
463
      <manvolnum>8mandos</manvolnum></citerefentry>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
464
    </para>
465
  </refsect1>
466
  
467
</refentry>
111 by Teddy Hogeborn
* mandos-clients.conf.xml (ENTITY TIMESTAMP): New. Automatically
468
<!-- Local Variables: -->
469
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
470
<!-- time-stamp-end: "[\"']>" -->
471
<!-- time-stamp-format: "%:y-%02m-%02d" -->
472
<!-- End: -->