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