/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">
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">
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
161
	<arg choice="plain"><option>-h</option></arg>
162
	<arg choice="plain"><option>--help</option></arg>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
163
      </group>
164
    </cmdsynopsis>
165
    <cmdsynopsis>
166
      <command>&COMMANDNAME;</command>
167
      <group choice="req">
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
168
	<arg choice="plain"><option>-v</option></arg>
169
	<arg choice="plain"><option>--version</option></arg>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
170
      </group>
171
    </cmdsynopsis>
172
  </refsynopsisdiv>
173
174
  <refsect1 id="description">
175
    <title>DESCRIPTION</title>
176
    <para>
177
      <command>&COMMANDNAME;</command> is a program to generate the
178
      OpenPGP keys used by
179
      <citerefentry><refentrytitle>password-request</refentrytitle>
180
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
181
      normally written to /etc/mandos for later installation into the
182
      initrd image, but this, like most things, can be changed with
183
      command line options.
184
    </para>
185
  </refsect1>
186
  
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
187
  <refsect1 id="purpose">
188
    <title>PURPOSE</title>
189
190
    <para>
191
      The purpose of this is to enable <emphasis>remote and unattended
192
      rebooting</emphasis> of client host computer with an
193
      <emphasis>encrypted root file system</emphasis>.  See <xref
194
      linkend="overview"/> for details.
195
    </para>
196
197
  </refsect1>
198
  
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
199
  <refsect1 id="options">
200
    <title>OPTIONS</title>
201
202
    <variablelist>
203
      <varlistentry>
204
	<term><literal>-h</literal>, <literal>--help</literal></term>
205
	<listitem>
206
	  <para>
207
	    Show a help message and exit
208
	  </para>
209
	</listitem>
210
      </varlistentry>
211
212
      <varlistentry>
213
	<term><literal>-d</literal>, <literal>--dir
214
	<replaceable>directory</replaceable></literal></term>
215
	<listitem>
216
	  <para>
217
	    Target directory for key files.
218
	  </para>
219
	</listitem>
220
      </varlistentry>
221
222
      <varlistentry>
223
	<term><literal>-t</literal>, <literal>--type
224
	<replaceable>type</replaceable></literal></term>
225
	<listitem>
226
	  <para>
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
227
	    Key type.  Default is <quote>DSA</quote>.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
228
	  </para>
229
	</listitem>
230
      </varlistentry>
231
232
      <varlistentry>
233
	<term><literal>-l</literal>, <literal>--length
234
	<replaceable>bits</replaceable></literal></term>
235
	<listitem>
236
	  <para>
237
	    Key length in bits.  Default is 1024.
238
	  </para>
239
	</listitem>
240
      </varlistentry>
241
242
      <varlistentry>
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
243
	<term><literal>-s</literal>, <literal>--subtype
244
	<replaceable>type</replaceable></literal></term>
245
	<listitem>
246
	  <para>
247
	    Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
248
	    encryption-only).
249
	  </para>
250
	</listitem>
251
      </varlistentry>
252
253
      <varlistentry>
254
	<term><literal>-L</literal>, <literal>--sublength
255
	<replaceable>bits</replaceable></literal></term>
256
	<listitem>
257
	  <para>
258
	    Subkey length in bits.  Default is 2048.
259
	  </para>
260
	</listitem>
261
      </varlistentry>
262
263
      <varlistentry>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
264
	<term><literal>-e</literal>, <literal>--email</literal>
265
	<replaceable>address</replaceable></term>
266
	<listitem>
267
	  <para>
268
	    Email address of key.  Default is empty.
269
	  </para>
270
	</listitem>
271
      </varlistentry>
272
273
      <varlistentry>
274
	<term><literal>-c</literal>, <literal>--comment</literal>
275
	<replaceable>comment</replaceable></term>
276
	<listitem>
277
	  <para>
278
	    Comment field for key.  The default value is
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
279
	    <quote><literal>Mandos client key</literal></quote>.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
280
	  </para>
281
	</listitem>
282
      </varlistentry>
283
284
      <varlistentry>
285
	<term><literal>-x</literal>, <literal>--expire</literal>
286
	<replaceable>time</replaceable></term>
287
	<listitem>
288
	  <para>
289
	    Key expire time.  Default is no expiration.  See
290
	    <citerefentry><refentrytitle>gpg</refentrytitle>
291
	    <manvolnum>1</manvolnum></citerefentry> for syntax.
292
	  </para>
293
	</listitem>
294
      </varlistentry>
295
296
      <varlistentry>
297
	<term><literal>-f</literal>, <literal>--force</literal></term>
298
	<listitem>
299
	  <para>
300
	    Force overwriting old keys.
301
	  </para>
302
	</listitem>
303
      </varlistentry>
304
    </variablelist>
305
  </refsect1>
306
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
307
  <refsect1 id="overview">
308
    <title>OVERVIEW</title>
91 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Include all DocBook-to-manpage-related
309
    <xi:include href="overview.xml"/>
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
310
    <para>
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
311
      This program is a small utility to generate new OpenPGP keys for
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
312
      new Mandos clients.
313
    </para>
314
  </refsect1>
315
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
316
  <refsect1 id="exit_status">
317
    <title>EXIT STATUS</title>
318
    <para>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
319
      The exit status will be 0 if new keys were successfully created,
320
      otherwise not.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
321
    </para>
322
  </refsect1>
323
  
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
324
  <refsect1 id="environment">
325
    <title>ENVIRONMENT</title>
326
    <variablelist>
327
      <varlistentry>
328
	<term><varname>TMPDIR</varname></term>
329
	<listitem>
330
	  <para>
331
	    If set, temporary files will be created here. See
332
	    <citerefentry><refentrytitle>mktemp</refentrytitle>
333
	    <manvolnum>1</manvolnum></citerefentry>.
334
	  </para>
335
	</listitem>
336
      </varlistentry>
337
    </variablelist>
338
  </refsect1>
339
  
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
340
  <refsect1 id="file">
341
    <title>FILES</title>
342
    <para>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
343
      Use the <option>--dir</option> option to change where
344
      <command>&COMMANDNAME;</command> will write the key files.  The
345
      default file names are shown here.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
346
    </para>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
347
    <variablelist>
348
      <varlistentry>
349
	<term><filename>/etc/mandos/seckey.txt</filename></term>
350
	<listitem>
351
	  <para>
352
	    OpenPGP secret key file which will be created or
353
	    overwritten.
354
	  </para>
355
	</listitem>
356
      </varlistentry>
357
      <varlistentry>
358
	<term><filename>/etc/mandos/pubkey.txt</filename></term>
359
	<listitem>
360
	  <para>
361
	    OpenPGP public key file which will be created or
362
	    overwritten.
363
	  </para>
364
	</listitem>
365
      </varlistentry>
366
      <varlistentry>
367
	<term><filename>/tmp</filename></term>
368
	<listitem>
369
	  <para>
370
	    Temporary files will be written here if
371
	    <varname>TMPDIR</varname> is not set.
372
	  </para>
373
	</listitem>
374
      </varlistentry>
375
    </variablelist>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
376
  </refsect1>
377
378
  <refsect1 id="bugs">
379
    <title>BUGS</title>
380
    <para>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
381
      None are known at this time.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
382
    </para>
383
  </refsect1>
384
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
385
  <refsect1 id="example">
386
    <title>EXAMPLE</title>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
387
    <informalexample>
388
      <para>
389
	Normal invocation needs no options:
390
      </para>
391
      <para>
392
	<userinput>mandos-keygen</userinput>
393
      </para>
394
    </informalexample>
395
    <informalexample>
396
      <para>
397
	Create keys in another directory and of another type.  Force
398
	overwriting old key files:
399
      </para>
400
      <para>
401
402
<!-- do not wrap this line -->
403
<userinput>mandos-keygen --dir ~/keydir --type RSA --force</userinput>
404
405
      </para>
406
    </informalexample>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
407
  </refsect1>
408
409
  <refsect1 id="security">
410
    <title>SECURITY</title>
411
    <para>
96 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
412
      The <option>--type</option>, <option>--length</option>,
413
      <option>--subtype</option>, and <option>--sublength</option>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
414
      options can be used to create keys of insufficient security.  If
415
      in doubt, leave them to the default values.
416
    </para>
417
    <para>
418
      The key expire time is not guaranteed to be honored by
419
      <citerefentry><refentrytitle>mandos</refentrytitle>
420
      <manvolnum>8</manvolnum></citerefentry>.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
421
    </para>
422
  </refsect1>
423
424
  <refsect1 id="see_also">
425
    <title>SEE ALSO</title>
426
    <para>
427
      <citerefentry><refentrytitle>password-request</refentrytitle>
428
      <manvolnum>8mandos</manvolnum></citerefentry>,
429
      <citerefentry><refentrytitle>mandos</refentrytitle>
92 by Teddy Hogeborn
* mandos-keygen.xml (SEE ALSO): Remove "and".
430
      <manvolnum>8</manvolnum></citerefentry>,
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
431
      <citerefentry><refentrytitle>gpg</refentrytitle>
432
      <manvolnum>1</manvolnum></citerefentry>
433
    </para>
434
  </refsect1>
435
  
436
</refentry>