/mandos/release

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/release

« back to all changes in this revision

Viewing changes to mandos-keygen.xml

  • Committer: Teddy Hogeborn
  • Date: 2008-08-19 23:44:17 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080819234417-8dz5prw19ihrklx6
* Makefile (DOCBOOKTOMAN): Include all DocBook-to-manpage-related
                           commands here, and use it everywhere.
  (mandos.8, mandos.conf.5): New; also depend on "mandos-options.xml".

* mandos-keygen.xml: Removed OVERVIEW entity.  Add XInclude namespace.
  (OVERVIEW): Changed to do <xi:include/>.

* mandos-options.xml (<simplesect>): Changed to a <section>.
  ([@id="address"]): Reordered sentences.

* mandos.conf.xml (OPTIONS): Removed illegal <arg> tags.
  (EXAMPLE): Added empty example.

* mandos.xml (NETWORK PROTOCOL): Bug fix: Changed "1\r\en" back to
                                 "1\r\n".
  (CHECKING): Do not refer to the non-relevant mandos.conf(5) manual.

Show diffs side-by-side

added added

removed removed

Lines of Context:
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
]>
 
7
 
 
8
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
 
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
  
 
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
  
 
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
 
 
269
  <refsect1 id="overview">
 
270
    <title>OVERVIEW</title>
 
271
    <xi:include href="overview.xml"/>
 
272
    <para>
 
273
      This program is a small program to generate new OpenPGP keys for
 
274
      new Mandos clients.
 
275
    </para>
 
276
  </refsect1>
 
277
 
 
278
  <refsect1 id="exit_status">
 
279
    <title>EXIT STATUS</title>
 
280
    <para>
 
281
      The exit status will be 0 if new keys were successfully created,
 
282
      otherwise not.
 
283
    </para>
 
284
  </refsect1>
 
285
  
 
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
  
 
302
  <refsect1 id="file">
 
303
    <title>FILES</title>
 
304
    <para>
 
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.
 
308
    </para>
 
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>
 
338
  </refsect1>
 
339
 
 
340
  <refsect1 id="bugs">
 
341
    <title>BUGS</title>
 
342
    <para>
 
343
      None are known at this time.
 
344
    </para>
 
345
  </refsect1>
 
346
 
 
347
  <refsect1 id="example">
 
348
    <title>EXAMPLE</title>
 
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>
 
369
  </refsect1>
 
370
 
 
371
  <refsect1 id="security">
 
372
    <title>SECURITY</title>
 
373
    <para>
 
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>.
 
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>