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 110
- compare with another revision
- download diff
- download tarball
- view history from revision 110
- Committer: Teddy Hogeborn
- Date: 2008-08-29 05:53:59 UTC
- Revision ID: teddy@fukt.bsnet.se-20080829055359-wkdasnyxtylmnxus
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
"&COMMANDNAME;".
* plugins.d/password-prompt.c (main): Improved some documentation
strings. Do perror() of
tcgetattr() fails. Add debug
output if interrupted by signal.
Loop over write() instead of
using fwrite() when outputting
password. Add debug output if
getline() returns 0, unless it
was caused by a signal. Add
exit status code to debug
output.
* plugins.d/password-prompt.xml: Changed all single quotes to double
quotes for consistency. Removed
<?xml-stylesheet>.
(ENTITY TIMESTAMP): New. Automatically updated by Emacs time-stamp
by using Emacs local variables.
(/refentry/refentryinfo/title): Changed to "Mandos Manual".
(/refentry/refentryinfo/productname): Changed to "Mandos".
(/refentry/refentryinfo/date): New; set to "&TIMESTAMP;".
(/refentry/refentryinfo/copyright): Split copyright holders.
(/refentry/refnamediv/refpurpose): Improved wording.
(SYNOPSIS): Fix to use correct markup. Add short options.
(DESCRIPTION, OPTIONS): Improved wording.
(OPTIONS): Improved wording. Use more correct markup. Document
short options.
(EXIT STATUS): Add text.
(ENVIRONMENT): Document use of "cryptsource" and "crypttarget".
(FILES): REMOVED.
(BUGS): Add text.
(EXAMPLE): Added some examples.
(SECURITY): Added text.
(SEE ALSO): Remove reference to mandos(8). Add reference to
crypttab(5).
"&COMMANDNAME;".
* plugins.d/password-prompt.c (main): Improved some documentation
strings. Do perror() of
tcgetattr() fails. Add debug
output if interrupted by signal.
Loop over write() instead of
using fwrite() when outputting
password. Add debug output if
getline() returns 0, unless it
was caused by a signal. Add
exit status code to debug
output.
* plugins.d/password-prompt.xml: Changed all single quotes to double
quotes for consistency. Removed
<?xml-stylesheet>.
(ENTITY TIMESTAMP): New. Automatically updated by Emacs time-stamp
by using Emacs local variables.
(/refentry/refentryinfo/title): Changed to "Mandos Manual".
(/refentry/refentryinfo/productname): Changed to "Mandos".
(/refentry/refentryinfo/date): New; set to "&TIMESTAMP;".
(/refentry/refentryinfo/copyright): Split copyright holders.
(/refentry/refnamediv/refpurpose): Improved wording.
(SYNOPSIS): Fix to use correct markup. Add short options.
(DESCRIPTION, OPTIONS): Improved wording.
(OPTIONS): Improved wording. Use more correct markup. Document
short options.
(EXIT STATUS): Add text.
(ENVIRONMENT): Document use of "cryptsource" and "crypttarget".
(FILES): REMOVED.
(BUGS): Add text.
(EXAMPLE): Added some examples.
(SECURITY): Added text.
(SEE ALSO): Remove reference to mandos(8). Add reference to
crypttab(5).
added
removed
mandos-keygen.xml
3
3
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
4
<!ENTITY VERSION "1.0">
5
5
<!ENTITY COMMANDNAME "mandos-keygen">
6
<!ENTITY TIMESTAMP "2008-09-03">
7
6
]>
8
7
9
8
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
10
9
<refentryinfo>
11
<title>Mandos Manual</title>
10
<title>&COMMANDNAME;</title>
12
11
<!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
<productname>Mandos</productname>
12
<productname>&COMMANDNAME;</productname>
14
13
<productnumber>&VERSION;</productnumber>
15
<date>&TIMESTAMP;</date>
16
14
<authorgroup>
17
15
<author>
18
16
<firstname>Björn</firstname>
34
32
<holder>Teddy Hogeborn</holder>
35
33
<holder>Björn Påhlsson</holder>
36
34
</copyright>
37
<xi:include href="legalnotice.xml"/>
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>
38
58
</refentryinfo>
39
59
40
60
<refmeta>
45
65
<refnamediv>
46
66
<refname><command>&COMMANDNAME;</command></refname>
47
67
<refpurpose>
48
Generate key and password for Mandos client and server.
68
Generate keys for <citerefentry><refentrytitle>password-request
69
</refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
49
70
</refpurpose>
50
71
</refnamediv>
51
72
52
73
<refsynopsisdiv>
53
74
<cmdsynopsis>
54
75
<command>&COMMANDNAME;</command>
55
<group>
56
<arg choice="plain"><option>--dir
57
<replaceable>DIRECTORY</replaceable></option></arg>
58
<arg choice="plain"><option>-d
59
<replaceable>DIRECTORY</replaceable></option></arg>
60
</group>
61
<sbr/>
62
<group>
63
<arg choice="plain"><option>--type
64
<replaceable>KEYTYPE</replaceable></option></arg>
65
<arg choice="plain"><option>-t
66
<replaceable>KEYTYPE</replaceable></option></arg>
67
</group>
68
<sbr/>
69
<group>
70
<arg choice="plain"><option>--length
71
<replaceable>BITS</replaceable></option></arg>
72
<arg choice="plain"><option>-l
73
<replaceable>BITS</replaceable></option></arg>
74
</group>
75
<sbr/>
76
<group>
77
<arg choice="plain"><option>--subtype
78
<replaceable>KEYTYPE</replaceable></option></arg>
79
<arg choice="plain"><option>-s
80
<replaceable>KEYTYPE</replaceable></option></arg>
81
</group>
82
<sbr/>
83
<group>
84
<arg choice="plain"><option>--sublength
85
<replaceable>BITS</replaceable></option></arg>
86
<arg choice="plain"><option>-L
87
<replaceable>BITS</replaceable></option></arg>
88
</group>
89
<sbr/>
90
<group>
91
<arg choice="plain"><option>--name
92
<replaceable>NAME</replaceable></option></arg>
93
<arg choice="plain"><option>-n
94
<replaceable>NAME</replaceable></option></arg>
95
</group>
96
<sbr/>
97
<group>
98
<arg choice="plain"><option>--email
99
<replaceable>ADDRESS</replaceable></option></arg>
100
<arg choice="plain"><option>-e
101
<replaceable>ADDRESS</replaceable></option></arg>
102
</group>
103
<sbr/>
104
<group>
105
<arg choice="plain"><option>--comment
106
<replaceable>TEXT</replaceable></option></arg>
107
<arg choice="plain"><option>-c
108
<replaceable>TEXT</replaceable></option></arg>
109
</group>
110
<sbr/>
111
<group>
112
<arg choice="plain"><option>--expire
113
<replaceable>TIME</replaceable></option></arg>
114
<arg choice="plain"><option>-x
115
<replaceable>TIME</replaceable></option></arg>
116
</group>
117
<sbr/>
118
<arg><option>--force</option></arg>
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">
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">
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">
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">
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>
119
157
</cmdsynopsis>
120
158
<cmdsynopsis>
121
159
<command>&COMMANDNAME;</command>
122
160
<group choice="req">
161
<arg choice="plain"><option>-p</option></arg>
123
162
<arg choice="plain"><option>--password</option></arg>
124
<arg choice="plain"><option>-p</option></arg>
125
</group>
126
<sbr/>
127
<group>
128
<arg choice="plain"><option>--dir
129
<replaceable>DIRECTORY</replaceable></option></arg>
130
<arg choice="plain"><option>-d
131
<replaceable>DIRECTORY</replaceable></option></arg>
132
</group>
133
<sbr/>
134
<group>
135
<arg choice="plain"><option>--name
136
<replaceable>NAME</replaceable></option></arg>
137
<arg choice="plain"><option>-n
138
<replaceable>NAME</replaceable></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>
139
171
</group>
140
172
</cmdsynopsis>
141
173
<cmdsynopsis>
142
174
<command>&COMMANDNAME;</command>
143
175
<group choice="req">
176
<arg choice="plain"><option>-h</option></arg>
144
177
<arg choice="plain"><option>--help</option></arg>
145
<arg choice="plain"><option>-h</option></arg>
146
178
</group>
147
179
</cmdsynopsis>
148
180
<cmdsynopsis>
149
181
<command>&COMMANDNAME;</command>
150
182
<group choice="req">
183
<arg choice="plain"><option>-v</option></arg>
151
184
<arg choice="plain"><option>--version</option></arg>
152
<arg choice="plain"><option>-v</option></arg>
153
185
</group>
154
186
</cmdsynopsis>
155
187
</refsynopsisdiv>
156
188
157
189
<refsect1 id="description">
158
190
<title>DESCRIPTION</title>
159
191
<para>
160
192
<command>&COMMANDNAME;</command> is a program to generate the
161
OpenPGP key used by
193
OpenPGP keys used by
162
194
<citerefentry><refentrytitle>password-request</refentrytitle>
163
<manvolnum>8mandos</manvolnum></citerefentry>. The key is
195
<manvolnum>8mandos</manvolnum></citerefentry>. The keys are
164
196
normally written to /etc/mandos for later installation into the
165
initrd image, but this, and most other things, can be changed
166
with command line options.
197
initrd image, but this, like most things, can be changed with
198
command line options.
167
199
</para>
168
200
<para>
169
This program can also be used with the
170
<option>--password</option> option to generate a ready-made
171
section for <filename>clients.conf</filename> (see
201
It can also be used to generate ready-made sections for
172
202
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
173
<manvolnum>5</manvolnum></citerefentry>).
203
<manvolnum>5</manvolnum></citerefentry> using the
204
<option>--password</option> option.
174
205
</para>
175
206
</refsect1>
176
207
177
208
<refsect1 id="purpose">
178
209
<title>PURPOSE</title>
210
179
211
<para>
180
212
The purpose of this is to enable <emphasis>remote and unattended
181
213
rebooting</emphasis> of client host computer with an
182
214
<emphasis>encrypted root file system</emphasis>. See <xref
183
215
linkend="overview"/> for details.
184
216
</para>
217
185
218
</refsect1>
186
219
187
220
<refsect1 id="options">
188
221
<title>OPTIONS</title>
189
222
190
223
<variablelist>
191
224
<varlistentry>
192
<term><option>--help</option></term>
193
<term><option>-h</option></term>
225
<term><literal>-h</literal>, <literal>--help</literal></term>
194
226
<listitem>
195
227
<para>
196
228
Show a help message and exit
199
231
</varlistentry>
200
232
201
233
<varlistentry>
202
<term><option>--dir
203
<replaceable>DIRECTORY</replaceable></option></term>
204
<term><option>-d
205
<replaceable>DIRECTORY</replaceable></option></term>
234
<term><literal>-d</literal>, <literal>--dir
235
<replaceable>directory</replaceable></literal></term>
206
236
<listitem>
207
237
<para>
208
238
Target directory for key files. Default is
212
242
</varlistentry>
213
243
214
244
<varlistentry>
215
<term><option>--type
216
<replaceable>TYPE</replaceable></option></term>
217
<term><option>-t
218
<replaceable>TYPE</replaceable></option></term>
245
<term><literal>-t</literal>, <literal>--type
246
<replaceable>type</replaceable></literal></term>
219
247
<listitem>
220
248
<para>
221
249
Key type. Default is <quote>DSA</quote>.
224
252
</varlistentry>
225
253
226
254
<varlistentry>
227
<term><option>--length
228
<replaceable>BITS</replaceable></option></term>
229
<term><option>-l
230
<replaceable>BITS</replaceable></option></term>
255
<term><literal>-l</literal>, <literal>--length
256
<replaceable>bits</replaceable></literal></term>
231
257
<listitem>
232
258
<para>
233
259
Key length in bits. Default is 2048.
236
262
</varlistentry>
237
263
238
264
<varlistentry>
239
<term><option>--subtype
240
<replaceable>KEYTYPE</replaceable></option></term>
241
<term><option>-s
242
<replaceable>KEYTYPE</replaceable></option></term>
265
<term><literal>-s</literal>, <literal>--subtype
266
<replaceable>type</replaceable></literal></term>
243
267
<listitem>
244
268
<para>
245
269
Subkey type. Default is <quote>ELG-E</quote> (Elgamal
249
273
</varlistentry>
250
274
251
275
<varlistentry>
252
<term><option>--sublength
253
<replaceable>BITS</replaceable></option></term>
254
<term><option>-L
255
<replaceable>BITS</replaceable></option></term>
276
<term><literal>-L</literal>, <literal>--sublength
277
<replaceable>bits</replaceable></literal></term>
256
278
<listitem>
257
279
<para>
258
280
Subkey length in bits. Default is 2048.
261
283
</varlistentry>
262
284
263
285
<varlistentry>
264
<term><option>--email
265
<replaceable>ADDRESS</replaceable></option></term>
266
<term><option>-e
267
<replaceable>ADDRESS</replaceable></option></term>
286
<term><literal>-e</literal>, <literal>--email</literal>
287
<replaceable>address</replaceable></term>
268
288
<listitem>
269
289
<para>
270
290
Email address of key. Default is empty.
273
293
</varlistentry>
274
294
275
295
<varlistentry>
276
<term><option>--comment
277
<replaceable>TEXT</replaceable></option></term>
278
<term><option>-c
279
<replaceable>TEXT</replaceable></option></term>
296
<term><literal>-c</literal>, <literal>--comment</literal>
297
<replaceable>comment</replaceable></term>
280
298
<listitem>
281
299
<para>
282
300
Comment field for key. The default value is
286
304
</varlistentry>
287
305
288
306
<varlistentry>
289
<term><option>--expire
290
<replaceable>TIME</replaceable></option></term>
291
<term><option>-x
292
<replaceable>TIME</replaceable></option></term>
307
<term><literal>-x</literal>, <literal>--expire</literal>
308
<replaceable>time</replaceable></term>
293
309
<listitem>
294
310
<para>
295
311
Key expire time. Default is no expiration. See
300
316
</varlistentry>
301
317
302
318
<varlistentry>
303
<term><option>--force</option></term>
304
<term><option>-f</option></term>
319
<term><literal>-f</literal>, <literal>--force</literal></term>
305
320
<listitem>
306
321
<para>
307
Force overwriting old key.
322
Force overwriting old keys.
308
323
</para>
309
324
</listitem>
310
325
</varlistentry>
311
326
<varlistentry>
312
<term><option>--password</option></term>
313
<term><option>-p</option></term>
327
<term><literal>-p</literal>, <literal>--password</literal
328
></term>
314
329
<listitem>
315
330
<para>
316
331
Prompt for a password and encrypt it with the key already
322
337
>8</manvolnum></citerefentry>. The host name or the name
323
338
specified with the <option>--name</option> option is used
324
339
for the section header. All other options are ignored,
325
and no key is created.
340
and no keys are created.
326
341
</para>
327
342
</listitem>
328
343
</varlistentry>
334
349
<xi:include href="overview.xml"/>
335
350
<para>
336
351
This program is a small utility to generate new OpenPGP keys for
337
new Mandos clients, and to generate sections for inclusion in
338
<filename>clients.conf</filename> on the server.
352
new Mandos clients.
339
353
</para>
340
354
</refsect1>
341
355
342
356
<refsect1 id="exit_status">
343
357
<title>EXIT STATUS</title>
344
358
<para>
345
The exit status will be 0 if a new key (or password, if the
346
<option>--password</option> option was used) was successfully
347
created, otherwise not.
359
The exit status will be 0 if new keys were successfully created,
360
otherwise not.
348
361
</para>
349
362
</refsect1>
350
363
352
365
<title>ENVIRONMENT</title>
353
366
<variablelist>
354
367
<varlistentry>
355
<term><envar>TMPDIR</envar></term>
368
<term><varname>TMPDIR</varname></term>
356
369
<listitem>
357
370
<para>
358
371
If set, temporary files will be created here. See
402
415
</variablelist>
403
416
</refsect1>
404
417
405
<!-- <refsect1 id="bugs"> -->
406
<!-- <title>BUGS</title> -->
407
<!-- <para> -->
408
<!-- </para> -->
409
<!-- </refsect1> -->
418
<refsect1 id="bugs">
419
<title>BUGS</title>
420
<para>
421
None are known at this time.
422
</para>
423
</refsect1>
410
424
411
425
<refsect1 id="example">
412
426
<title>EXAMPLE</title>
415
429
Normal invocation needs no options:
416
430
</para>
417
431
<para>
418
<userinput>&COMMANDNAME;</userinput>
432
<userinput>mandos-keygen</userinput>
419
433
</para>
420
434
</informalexample>
421
435
<informalexample>
422
436
<para>
423
Create key in another directory and of another type. Force
437
Create keys in another directory and of another type. Force
424
438
overwriting old key files:
425
439
</para>
426
440
<para>
427
441
428
442
<!-- do not wrap this line -->
429
<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>
430
431
</para>
432
</informalexample>
433
<informalexample>
434
<para>
435
Prompt for a password, encrypt it with the key in
436
<filename>/etc/mandos</filename> and output a section suitable
437
for <filename>clients.conf</filename>.
438
</para>
439
<para>
440
<userinput>&COMMANDNAME; --password</userinput>
441
</para>
442
</informalexample>
443
<informalexample>
444
<para>
445
Prompt for a password, encrypt it with the key in the
446
<filename>client-key</filename> directory and output a section
447
suitable for <filename>clients.conf</filename>.
448
</para>
449
<para>
450
451
<!-- do not wrap this line -->
452
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
443
<userinput>mandos-keygen --dir ~/keydir --type RSA --force</userinput>
453
444
454
445
</para>
455
446
</informalexample>
460
451
<para>
461
452
The <option>--type</option>, <option>--length</option>,
462
453
<option>--subtype</option>, and <option>--sublength</option>
463
options can be used to create keys of low security. If in
464
doubt, leave them to the default values.
454
options can be used to create keys of insufficient security. If
455
in doubt, leave them to the default values.
465
456
</para>
466
457
<para>
467
The key expire time is <emphasis>not</emphasis> guaranteed to be
468
honored by <citerefentry><refentrytitle>mandos</refentrytitle>
458
The key expire time is not guaranteed to be honored by
459
<citerefentry><refentrytitle>mandos</refentrytitle>
469
460
<manvolnum>8</manvolnum></citerefentry>.
470
461
</para>
471
462
</refsect1>
473
464
<refsect1 id="see_also">
474
465
<title>SEE ALSO</title>
475
466
<para>
467
<citerefentry><refentrytitle>password-request</refentrytitle>
468
<manvolnum>8mandos</manvolnum></citerefentry>,
469
<citerefentry><refentrytitle>mandos</refentrytitle>
470
<manvolnum>8</manvolnum></citerefentry>,
476
471
<citerefentry><refentrytitle>gpg</refentrytitle>
477
<manvolnum>1</manvolnum></citerefentry>,
478
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
479
<manvolnum>5</manvolnum></citerefentry>,
480
<citerefentry><refentrytitle>mandos</refentrytitle>
481
<manvolnum>8</manvolnum></citerefentry>,
482
<citerefentry><refentrytitle>password-request</refentrytitle>
483
<manvolnum>8mandos</manvolnum></citerefentry>
472
<manvolnum>1</manvolnum></citerefentry>
484
473
</para>
485
474
</refsect1>
486
475
487
476
</refentry>
488
<!-- Local Variables: -->
489
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
490
<!-- time-stamp-end: "[\"']>" -->
491
<!-- time-stamp-format: "%:y-%02m-%02d" -->
492
<!-- End: -->
Loggerhead is a web-based interface for Breezy
Version: 2.0.2.dev0