/mandos/trunk

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/trunk
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
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
]>
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>
11
    <!-- NWalsh's docbook scripts use this to generate the footer: -->
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>
32
      <holder>Teddy Hogeborn &amp; Björn Påhlsson</holder>
33
    </copyright>
34
    <legalnotice>
35
      <para>
36
	This manual page is free software: you can redistribute it
37
	and/or modify it under the terms of the GNU General Public
38
	License as published by the Free Software Foundation,
39
	either version 3 of the License, or (at your option) any
40
	later version.
41
      </para>
42
43
      <para>
44
	This manual page is distributed in the hope that it will
45
	be useful, but WITHOUT ANY WARRANTY; without even the
46
	implied warranty of MERCHANTABILITY or FITNESS FOR A
47
	PARTICULAR PURPOSE.  See the GNU General Public License
48
	for more details.
49
      </para>
50
51
      <para>
52
	You should have received a copy of the GNU General Public
53
	License along with this program; If not, see
54
	<ulink url="http://www.gnu.org/licenses/"/>.
55
      </para>
56
    </legalnotice>
57
  </refentryinfo>
58
59
  <refmeta>
60
    <refentrytitle>&COMMANDNAME;</refentrytitle>
61
    <manvolnum>8</manvolnum>
62
  </refmeta>
63
  
64
  <refnamediv>
65
    <refname><command>&COMMANDNAME;</command></refname>
66
    <refpurpose>
67
      Generate keys for <citerefentry><refentrytitle>password-request
68
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
69
    </refpurpose>
70
  </refnamediv>
71
72
  <refsynopsisdiv>
73
    <cmdsynopsis>
74
      <command>&COMMANDNAME;</command>
75
      <group choice="opt">
76
	<arg choice="plain"><option>--dir</option>
77
	<replaceable>directory</replaceable></arg>
78
      </group>
79
      <group choice="opt">
80
	<arg choice="plain"><option>--type</option>
81
	<replaceable>type</replaceable></arg>
82
      </group>
83
      <group choice="opt">
84
	<arg choice="plain"><option>--length</option>
85
	<replaceable>bits</replaceable></arg>
86
      </group>
87
      <group choice="opt">
88
	<arg choice="plain"><option>--name</option>
89
	<replaceable>NAME</replaceable></arg>
90
      </group>
91
      <group choice="opt">
92
	<arg choice="plain"><option>--email</option>
93
	<replaceable>EMAIL</replaceable></arg>
94
      </group>
95
      <group choice="opt">
96
	<arg choice="plain"><option>--comment</option>
97
	<replaceable>COMMENT</replaceable></arg>
98
      </group>
99
      <group choice="opt">
100
	<arg choice="plain"><option>--expire</option>
101
	<replaceable>TIME</replaceable></arg>
102
      </group>
103
      <group choice="opt">
104
	<arg choice="plain"><option>--force</option></arg>
105
      </group>
106
    </cmdsynopsis>
107
    <cmdsynopsis>
108
      <command>&COMMANDNAME;</command>
109
      <group choice="opt">
110
	<arg choice="plain"><option>-d</option>
111
	<replaceable>directory</replaceable></arg>
112
      </group>
113
      <group choice="opt">
114
	<arg choice="plain"><option>-t</option>
115
	<replaceable>type</replaceable></arg>
116
      </group>
117
      <group choice="opt">
118
	<arg choice="plain"><option>-l</option>
119
	<replaceable>bits</replaceable></arg>
120
      </group>
121
      <group choice="opt">
122
	<arg choice="plain"><option>-n</option>
123
	<replaceable>NAME</replaceable></arg>
124
      </group>
125
      <group choice="opt">
126
	<arg choice="plain"><option>-e</option>
127
	<replaceable>EMAIL</replaceable></arg>
128
      </group>
129
      <group choice="opt">
130
	<arg choice="plain"><option>-c</option>
131
	<replaceable>COMMENT</replaceable></arg>
132
      </group>
133
      <group choice="opt">
134
	<arg choice="plain"><option>-x</option>
135
	<replaceable>TIME</replaceable></arg>
136
      </group>
137
      <group choice="opt">
138
	<arg choice="plain"><option>-f</option></arg>
139
      </group>
140
    </cmdsynopsis>
141
    <cmdsynopsis>
142
      <command>&COMMANDNAME;</command>
143
      <group choice="req">
144
	<arg choice='plain'><option>-h</option></arg>
145
	<arg choice='plain'><option>--help</option></arg>
146
      </group>
147
    </cmdsynopsis>
148
    <cmdsynopsis>
149
      <command>&COMMANDNAME;</command>
150
      <group choice="req">
151
	<arg choice='plain'><option>-v</option></arg>
152
	<arg choice='plain'><option>--version</option></arg>
153
      </group>
154
    </cmdsynopsis>
155
  </refsynopsisdiv>
156
157
  <refsect1 id="description">
158
    <title>DESCRIPTION</title>
159
    <para>
160
      <command>&COMMANDNAME;</command> is a program to generate the
161
      OpenPGP keys used by
162
      <citerefentry><refentrytitle>password-request</refentrytitle>
163
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
164
      normally written to /etc/mandos for later installation into the
165
      initrd image, but this, like most things, can be changed with
166
      command line options.
167
    </para>
168
  </refsect1>
169
  
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
170
  <refsect1 id="purpose">
171
    <title>PURPOSE</title>
172
173
    <para>
174
      The purpose of this is to enable <emphasis>remote and unattended
175
      rebooting</emphasis> of client host computer with an
176
      <emphasis>encrypted root file system</emphasis>.  See <xref
177
      linkend="overview"/> for details.
178
    </para>
179
180
  </refsect1>
181
  
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
182
  <refsect1 id="options">
183
    <title>OPTIONS</title>
184
185
    <variablelist>
186
      <varlistentry>
187
	<term><literal>-h</literal>, <literal>--help</literal></term>
188
	<listitem>
189
	  <para>
190
	    Show a help message and exit
191
	  </para>
192
	</listitem>
193
      </varlistentry>
194
195
      <varlistentry>
196
	<term><literal>-d</literal>, <literal>--dir
197
	<replaceable>directory</replaceable></literal></term>
198
	<listitem>
199
	  <para>
200
	    Target directory for key files.
201
	  </para>
202
	</listitem>
203
      </varlistentry>
204
205
      <varlistentry>
206
	<term><literal>-t</literal>, <literal>--type
207
	<replaceable>type</replaceable></literal></term>
208
	<listitem>
209
	  <para>
210
	    Key type.  Default is DSA.
211
	  </para>
212
	</listitem>
213
      </varlistentry>
214
215
      <varlistentry>
216
	<term><literal>-l</literal>, <literal>--length
217
	<replaceable>bits</replaceable></literal></term>
218
	<listitem>
219
	  <para>
220
	    Key length in bits.  Default is 1024.
221
	  </para>
222
	</listitem>
223
      </varlistentry>
224
225
      <varlistentry>
226
	<term><literal>-e</literal>, <literal>--email</literal>
227
	<replaceable>address</replaceable></term>
228
	<listitem>
229
	  <para>
230
	    Email address of key.  Default is empty.
231
	  </para>
232
	</listitem>
233
      </varlistentry>
234
235
      <varlistentry>
236
	<term><literal>-c</literal>, <literal>--comment</literal>
237
	<replaceable>comment</replaceable></term>
238
	<listitem>
239
	  <para>
240
	    Comment field for key.  The default value is
241
	    "<literal>Mandos client key</literal>".
242
	  </para>
243
	</listitem>
244
      </varlistentry>
245
246
      <varlistentry>
247
	<term><literal>-x</literal>, <literal>--expire</literal>
248
	<replaceable>time</replaceable></term>
249
	<listitem>
250
	  <para>
251
	    Key expire time.  Default is no expiration.  See
252
	    <citerefentry><refentrytitle>gpg</refentrytitle>
253
	    <manvolnum>1</manvolnum></citerefentry> for syntax.
254
	  </para>
255
	</listitem>
256
      </varlistentry>
257
258
      <varlistentry>
259
	<term><literal>-f</literal>, <literal>--force</literal></term>
260
	<listitem>
261
	  <para>
262
	    Force overwriting old keys.
263
	  </para>
264
	</listitem>
265
      </varlistentry>
266
    </variablelist>
267
  </refsect1>
268
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
269
  <refsect1 id="overview">
270
    <title>OVERVIEW</title>
91 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Include all DocBook-to-manpage-related
271
    <xi:include href="overview.xml"/>
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
272
    <para>
273
      This program is a small program to generate new OpenPGP keys for
274
      new Mandos clients.
275
    </para>
276
  </refsect1>
277
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
278
  <refsect1 id="exit_status">
279
    <title>EXIT STATUS</title>
280
    <para>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
281
      The exit status will be 0 if new keys were successfully created,
282
      otherwise not.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
283
    </para>
284
  </refsect1>
285
  
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
286
  <refsect1 id="environment">
287
    <title>ENVIRONMENT</title>
288
    <variablelist>
289
      <varlistentry>
290
	<term><varname>TMPDIR</varname></term>
291
	<listitem>
292
	  <para>
293
	    If set, temporary files will be created here. See
294
	    <citerefentry><refentrytitle>mktemp</refentrytitle>
295
	    <manvolnum>1</manvolnum></citerefentry>.
296
	  </para>
297
	</listitem>
298
      </varlistentry>
299
    </variablelist>
300
  </refsect1>
301
  
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
302
  <refsect1 id="file">
303
    <title>FILES</title>
304
    <para>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
305
      Use the <option>--dir</option> option to change where
306
      <command>&COMMANDNAME;</command> will write the key files.  The
307
      default file names are shown here.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
308
    </para>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
309
    <variablelist>
310
      <varlistentry>
311
	<term><filename>/etc/mandos/seckey.txt</filename></term>
312
	<listitem>
313
	  <para>
314
	    OpenPGP secret key file which will be created or
315
	    overwritten.
316
	  </para>
317
	</listitem>
318
      </varlistentry>
319
      <varlistentry>
320
	<term><filename>/etc/mandos/pubkey.txt</filename></term>
321
	<listitem>
322
	  <para>
323
	    OpenPGP public key file which will be created or
324
	    overwritten.
325
	  </para>
326
	</listitem>
327
      </varlistentry>
328
      <varlistentry>
329
	<term><filename>/tmp</filename></term>
330
	<listitem>
331
	  <para>
332
	    Temporary files will be written here if
333
	    <varname>TMPDIR</varname> is not set.
334
	  </para>
335
	</listitem>
336
      </varlistentry>
337
    </variablelist>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
338
  </refsect1>
339
340
  <refsect1 id="bugs">
341
    <title>BUGS</title>
342
    <para>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
343
      None are known at this time.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
344
    </para>
345
  </refsect1>
346
86 by Teddy Hogeborn
* mandos-keygen.xml: Removed <?xml-stylesheet>. New entity
347
  <refsect1 id="example">
348
    <title>EXAMPLE</title>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
349
    <informalexample>
350
      <para>
351
	Normal invocation needs no options:
352
      </para>
353
      <para>
354
	<userinput>mandos-keygen</userinput>
355
      </para>
356
    </informalexample>
357
    <informalexample>
358
      <para>
359
	Create keys in another directory and of another type.  Force
360
	overwriting old key files:
361
      </para>
362
      <para>
363
364
<!-- do not wrap this line -->
365
<userinput>mandos-keygen --dir ~/keydir --type RSA --force</userinput>
366
367
      </para>
368
    </informalexample>
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
369
  </refsect1>
370
371
  <refsect1 id="security">
372
    <title>SECURITY</title>
373
    <para>
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
374
      The <option>--type</option> and <option>--length</option>
375
      options can be used to create keys of insufficient security.  If
376
      in doubt, leave them to the default values.
377
    </para>
378
    <para>
379
      The key expire time is not guaranteed to be honored by
380
      <citerefentry><refentrytitle>mandos</refentrytitle>
381
      <manvolnum>8</manvolnum></citerefentry>.
80 by Teddy Hogeborn
* mandos-keygen.xml: New man page for mandos-keygen(8).
382
    </para>
383
  </refsect1>
384
385
  <refsect1 id="see_also">
386
    <title>SEE ALSO</title>
387
    <para>
388
      <citerefentry><refentrytitle>password-request</refentrytitle>
389
      <manvolnum>8mandos</manvolnum></citerefentry>,
390
      <citerefentry><refentrytitle>mandos</refentrytitle>
391
      <manvolnum>8</manvolnum></citerefentry>, and
392
      <citerefentry><refentrytitle>gpg</refentrytitle>
393
      <manvolnum>1</manvolnum></citerefentry>
394
    </para>
395
  </refsect1>
396
  
397
</refentry>