/mandos/trunk

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

  • Committer: Teddy Hogeborn
  • Date: 2015-05-23 20:18:34 UTC
  • mto: This revision was merged to the branch mainline in revision 756.
  • Revision ID: teddy@recompile.se-20150523201834-e89ex4ito93yni8x
mandos: Use multiprocessing module to run checkers.

For a long time, the Mandos server has occasionally logged the message
"ERROR: Child process vanished".  This was never a fatal error, but it
has been annoying and slightly worrying, since a definite cause was
not found.  One potential cause could be the "multiprocessing" and
"subprocess" modules conflicting w.r.t. SIGCHLD.  To avoid this,
change the running of checkers from using subprocess.Popen
asynchronously to instead first create a multiprocessing.Process()
(which is asynchronous) calling a function, and have that function
then call subprocess.call() (which is synchronous).  In this way, the
only thing using any asynchronous subprocesses is the multiprocessing
module.

This makes it necessary to change one small thing in the D-Bus API,
since the subprocesses.call() function does not expose the raw wait(2)
status value.

DBUS-API (CheckerCompleted): Change the second value provided by this
                             D-Bus signal from the raw wait(2) status
                             to the actual terminating signal number.
mandos (subprocess_call_pipe): New function to be called by
                               multiprocessing.Process (starting a
                               separate process).
(Client.last_checker signal): New attribute for signal which
                              terminated last checker.  Like
                              last_checker_status, only not accessible
                              via D-Bus.
(Client.checker_callback): Take new "connection" argument and use it
                           to get returncode; set last_checker_signal.
                           Return False so gobject does not call this
                           callback again.
(Client.start_checker): Start checker using a multiprocessing.Process
                        instead of a subprocess.Popen.
(ClientDBus.checker_callback): Take new "connection" argument.        Call
                               Client.checker_callback early to have
                               it set last_checker_status and
                               last_checker_signal; use those.  Change
                               second value provided to D-Bus signal
                               CheckerCompleted to use
                               last_checker_signal if checker was
                               terminated by signal.
mandos-monitor: Update to reflect DBus API change.
(MandosClientWidget.checker_completed): Take "signal" instead of
                                        "condition" argument.  Use it
                                        accordingly.  Remove dead code
                                        (os.WCOREDUMP case).

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
1
<?xml version="1.0" encoding="UTF-8"?>
2
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
3
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
 
<!ENTITY VERSION "1.0">
5
4
<!ENTITY COMMANDNAME "mandos-keygen">
6
 
<!ENTITY TIMESTAMP "2008-08-29">
 
5
<!ENTITY TIMESTAMP "2014-06-22">
 
6
<!ENTITY % common SYSTEM "common.ent">
 
7
%common;
7
8
]>
8
9
 
9
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
12
    <title>Mandos Manual</title>
12
13
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
14
    <productname>Mandos</productname>
14
 
    <productnumber>&VERSION;</productnumber>
 
15
    <productnumber>&version;</productnumber>
15
16
    <date>&TIMESTAMP;</date>
16
17
    <authorgroup>
17
18
      <author>
18
19
        <firstname>Björn</firstname>
19
20
        <surname>Påhlsson</surname>
20
21
        <address>
21
 
          <email>belorn@fukt.bsnet.se</email>
 
22
          <email>belorn@recompile.se</email>
22
23
        </address>
23
24
      </author>
24
25
      <author>
25
26
        <firstname>Teddy</firstname>
26
27
        <surname>Hogeborn</surname>
27
28
        <address>
28
 
          <email>teddy@fukt.bsnet.se</email>
 
29
          <email>teddy@recompile.se</email>
29
30
        </address>
30
31
      </author>
31
32
    </authorgroup>
32
33
    <copyright>
33
34
      <year>2008</year>
 
35
      <year>2009</year>
 
36
      <year>2011</year>
 
37
      <year>2012</year>
34
38
      <holder>Teddy Hogeborn</holder>
35
39
      <holder>Björn Påhlsson</holder>
36
40
    </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>
 
41
    <xi:include href="legalnotice.xml"/>
60
42
  </refentryinfo>
61
 
 
 
43
  
62
44
  <refmeta>
63
45
    <refentrytitle>&COMMANDNAME;</refentrytitle>
64
46
    <manvolnum>8</manvolnum>
67
49
  <refnamediv>
68
50
    <refname><command>&COMMANDNAME;</command></refname>
69
51
    <refpurpose>
70
 
      Generate keys for <citerefentry><refentrytitle>password-request
71
 
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
 
52
      Generate key and password for Mandos client and server.
72
53
    </refpurpose>
73
54
  </refnamediv>
74
 
 
 
55
  
75
56
  <refsynopsisdiv>
76
57
    <cmdsynopsis>
77
58
      <command>&COMMANDNAME;</command>
78
 
      <group choice="opt">
79
 
        <arg choice="plain"><option>--dir</option>
80
 
        <replaceable>directory</replaceable></arg>
81
 
      </group>
82
 
      <group choice="opt">
83
 
        <arg choice="plain"><option>--type</option>
84
 
        <replaceable>type</replaceable></arg>
85
 
      </group>
86
 
      <group choice="opt">
87
 
        <arg choice="plain"><option>--length</option>
88
 
        <replaceable>bits</replaceable></arg>
89
 
      </group>
90
 
      <group choice="opt">
91
 
        <arg choice="plain"><option>--subtype</option>
92
 
        <replaceable>type</replaceable></arg>
93
 
      </group>
94
 
      <group choice="opt">
95
 
        <arg choice="plain"><option>--sublength</option>
96
 
        <replaceable>bits</replaceable></arg>
97
 
      </group>
98
 
      <group choice="opt">
99
 
        <arg choice="plain"><option>--name</option>
100
 
        <replaceable>NAME</replaceable></arg>
101
 
      </group>
102
 
      <group choice="opt">
103
 
        <arg choice="plain"><option>--email</option>
104
 
        <replaceable>EMAIL</replaceable></arg>
105
 
      </group>
106
 
      <group choice="opt">
107
 
        <arg choice="plain"><option>--comment</option>
108
 
        <replaceable>COMMENT</replaceable></arg>
109
 
      </group>
110
 
      <group choice="opt">
111
 
        <arg choice="plain"><option>--expire</option>
112
 
        <replaceable>TIME</replaceable></arg>
113
 
      </group>
114
 
      <group choice="opt">
 
59
      <group>
 
60
        <arg choice="plain"><option>--dir
 
61
        <replaceable>DIRECTORY</replaceable></option></arg>
 
62
        <arg choice="plain"><option>-d
 
63
        <replaceable>DIRECTORY</replaceable></option></arg>
 
64
      </group>
 
65
      <sbr/>
 
66
      <group>
 
67
        <arg choice="plain"><option>--type
 
68
        <replaceable>KEYTYPE</replaceable></option></arg>
 
69
        <arg choice="plain"><option>-t
 
70
        <replaceable>KEYTYPE</replaceable></option></arg>
 
71
      </group>
 
72
      <sbr/>
 
73
      <group>
 
74
        <arg choice="plain"><option>--length
 
75
        <replaceable>BITS</replaceable></option></arg>
 
76
        <arg choice="plain"><option>-l
 
77
        <replaceable>BITS</replaceable></option></arg>
 
78
      </group>
 
79
      <sbr/>
 
80
      <group>
 
81
        <arg choice="plain"><option>--subtype
 
82
        <replaceable>KEYTYPE</replaceable></option></arg>
 
83
        <arg choice="plain"><option>-s
 
84
        <replaceable>KEYTYPE</replaceable></option></arg>
 
85
      </group>
 
86
      <sbr/>
 
87
      <group>
 
88
        <arg choice="plain"><option>--sublength
 
89
        <replaceable>BITS</replaceable></option></arg>
 
90
        <arg choice="plain"><option>-L
 
91
        <replaceable>BITS</replaceable></option></arg>
 
92
      </group>
 
93
      <sbr/>
 
94
      <group>
 
95
        <arg choice="plain"><option>--name
 
96
        <replaceable>NAME</replaceable></option></arg>
 
97
        <arg choice="plain"><option>-n
 
98
        <replaceable>NAME</replaceable></option></arg>
 
99
      </group>
 
100
      <sbr/>
 
101
      <group>
 
102
        <arg choice="plain"><option>--email
 
103
        <replaceable>ADDRESS</replaceable></option></arg>
 
104
        <arg choice="plain"><option>-e
 
105
        <replaceable>ADDRESS</replaceable></option></arg>
 
106
      </group>
 
107
      <sbr/>
 
108
      <group>
 
109
        <arg choice="plain"><option>--comment
 
110
        <replaceable>TEXT</replaceable></option></arg>
 
111
        <arg choice="plain"><option>-c
 
112
        <replaceable>TEXT</replaceable></option></arg>
 
113
      </group>
 
114
      <sbr/>
 
115
      <group>
 
116
        <arg choice="plain"><option>--expire
 
117
        <replaceable>TIME</replaceable></option></arg>
 
118
        <arg choice="plain"><option>-x
 
119
        <replaceable>TIME</replaceable></option></arg>
 
120
      </group>
 
121
      <sbr/>
 
122
      <group>
115
123
        <arg choice="plain"><option>--force</option></arg>
116
 
      </group>
117
 
    </cmdsynopsis>
118
 
    <cmdsynopsis>
119
 
      <command>&COMMANDNAME;</command>
120
 
      <group choice="opt">
121
 
        <arg choice="plain"><option>-d</option>
122
 
        <replaceable>directory</replaceable></arg>
123
 
      </group>
124
 
      <group choice="opt">
125
 
        <arg choice="plain"><option>-t</option>
126
 
        <replaceable>type</replaceable></arg>
127
 
      </group>
128
 
      <group choice="opt">
129
 
        <arg choice="plain"><option>-l</option>
130
 
        <replaceable>bits</replaceable></arg>
131
 
      </group>
132
 
      <group choice="opt">
133
 
        <arg choice="plain"><option>-s</option>
134
 
        <replaceable>type</replaceable></arg>
135
 
      </group>
136
 
      <group choice="opt">
137
 
        <arg choice="plain"><option>-L</option>
138
 
        <replaceable>bits</replaceable></arg>
139
 
      </group>
140
 
      <group choice="opt">
141
 
        <arg choice="plain"><option>-n</option>
142
 
        <replaceable>NAME</replaceable></arg>
143
 
      </group>
144
 
      <group choice="opt">
145
 
        <arg choice="plain"><option>-e</option>
146
 
        <replaceable>EMAIL</replaceable></arg>
147
 
      </group>
148
 
      <group choice="opt">
149
 
        <arg choice="plain"><option>-c</option>
150
 
        <replaceable>COMMENT</replaceable></arg>
151
 
      </group>
152
 
      <group choice="opt">
153
 
        <arg choice="plain"><option>-x</option>
154
 
        <replaceable>TIME</replaceable></arg>
155
 
      </group>
156
 
      <group choice="opt">
157
124
        <arg choice="plain"><option>-f</option></arg>
158
125
      </group>
159
126
    </cmdsynopsis>
160
127
    <cmdsynopsis>
161
128
      <command>&COMMANDNAME;</command>
162
129
      <group choice="req">
 
130
        <arg choice="plain"><option>--password</option></arg>
163
131
        <arg choice="plain"><option>-p</option></arg>
164
 
        <arg choice="plain"><option>--password</option></arg>
165
 
      </group>
166
 
      <group choice="opt">
167
 
        <arg choice="plain"><option>--dir</option>
168
 
        <replaceable>directory</replaceable></arg>
169
 
      </group>
170
 
      <group choice="opt">
171
 
        <arg choice="plain"><option>--name</option>
172
 
        <replaceable>NAME</replaceable></arg>
 
132
        <arg choice="plain"><option>--passfile
 
133
        <replaceable>FILE</replaceable></option></arg>
 
134
        <arg choice="plain"><option>-F</option>
 
135
        <replaceable>FILE</replaceable></arg>
 
136
      </group>
 
137
      <sbr/>
 
138
      <group>
 
139
        <arg choice="plain"><option>--dir
 
140
        <replaceable>DIRECTORY</replaceable></option></arg>
 
141
        <arg choice="plain"><option>-d
 
142
        <replaceable>DIRECTORY</replaceable></option></arg>
 
143
      </group>
 
144
      <sbr/>
 
145
      <group>
 
146
        <arg choice="plain"><option>--name
 
147
        <replaceable>NAME</replaceable></option></arg>
 
148
        <arg choice="plain"><option>-n
 
149
        <replaceable>NAME</replaceable></option></arg>
 
150
      </group>
 
151
      <group>
 
152
        <arg choice="plain"><option>--no-ssh</option></arg>
 
153
        <arg choice="plain"><option>-S</option></arg>
173
154
      </group>
174
155
    </cmdsynopsis>
175
156
    <cmdsynopsis>
176
157
      <command>&COMMANDNAME;</command>
177
158
      <group choice="req">
 
159
        <arg choice="plain"><option>--help</option></arg>
178
160
        <arg choice="plain"><option>-h</option></arg>
179
 
        <arg choice="plain"><option>--help</option></arg>
180
161
      </group>
181
162
    </cmdsynopsis>
182
163
    <cmdsynopsis>
183
164
      <command>&COMMANDNAME;</command>
184
165
      <group choice="req">
 
166
        <arg choice="plain"><option>--version</option></arg>
185
167
        <arg choice="plain"><option>-v</option></arg>
186
 
        <arg choice="plain"><option>--version</option></arg>
187
168
      </group>
188
169
    </cmdsynopsis>
189
170
  </refsynopsisdiv>
190
 
 
 
171
  
191
172
  <refsect1 id="description">
192
173
    <title>DESCRIPTION</title>
193
174
    <para>
194
175
      <command>&COMMANDNAME;</command> is a program to generate the
195
 
      OpenPGP keys used by
196
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
197
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
 
176
      OpenPGP key used by
 
177
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
178
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
198
179
      normally written to /etc/mandos for later installation into the
199
 
      initrd image, but this, like most things, can be changed with
200
 
      command line options.
 
180
      initrd image, but this, and most other things, can be changed
 
181
      with command line options.
201
182
    </para>
202
183
    <para>
203
 
      It can also be used to generate ready-made sections for
 
184
      This program can also be used with the
 
185
      <option>--password</option> or <option>--passfile</option>
 
186
      options to generate a ready-made section for
 
187
      <filename>clients.conf</filename> (see
204
188
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
205
 
      <manvolnum>5</manvolnum></citerefentry> using the
206
 
      <option>--password</option> option.
 
189
      <manvolnum>5</manvolnum></citerefentry>).
207
190
    </para>
208
191
  </refsect1>
209
192
  
210
193
  <refsect1 id="purpose">
211
194
    <title>PURPOSE</title>
212
 
 
213
195
    <para>
214
196
      The purpose of this is to enable <emphasis>remote and unattended
215
197
      rebooting</emphasis> of client host computer with an
216
198
      <emphasis>encrypted root file system</emphasis>.  See <xref
217
199
      linkend="overview"/> for details.
218
200
    </para>
219
 
 
220
201
  </refsect1>
221
202
  
222
203
  <refsect1 id="options">
223
204
    <title>OPTIONS</title>
224
 
 
 
205
    
225
206
    <variablelist>
226
207
      <varlistentry>
227
 
        <term><literal>-h</literal>, <literal>--help</literal></term>
 
208
        <term><option>--help</option></term>
 
209
        <term><option>-h</option></term>
228
210
        <listitem>
229
211
          <para>
230
212
            Show a help message and exit
231
213
          </para>
232
214
        </listitem>
233
215
      </varlistentry>
234
 
 
 
216
      
235
217
      <varlistentry>
236
 
        <term><literal>-d</literal>, <literal>--dir
237
 
        <replaceable>directory</replaceable></literal></term>
 
218
        <term><option>--dir
 
219
        <replaceable>DIRECTORY</replaceable></option></term>
 
220
        <term><option>-d
 
221
        <replaceable>DIRECTORY</replaceable></option></term>
238
222
        <listitem>
239
223
          <para>
240
224
            Target directory for key files.  Default is
241
 
            <filename>/etc/mandos</filename>.
242
 
          </para>
243
 
        </listitem>
244
 
      </varlistentry>
245
 
 
246
 
      <varlistentry>
247
 
        <term><literal>-t</literal>, <literal>--type
248
 
        <replaceable>type</replaceable></literal></term>
249
 
        <listitem>
250
 
          <para>
251
 
            Key type.  Default is <quote>DSA</quote>.
252
 
          </para>
253
 
        </listitem>
254
 
      </varlistentry>
255
 
 
256
 
      <varlistentry>
257
 
        <term><literal>-l</literal>, <literal>--length
258
 
        <replaceable>bits</replaceable></literal></term>
259
 
        <listitem>
260
 
          <para>
261
 
            Key length in bits.  Default is 2048.
262
 
          </para>
263
 
        </listitem>
264
 
      </varlistentry>
265
 
 
266
 
      <varlistentry>
267
 
        <term><literal>-s</literal>, <literal>--subtype
268
 
        <replaceable>type</replaceable></literal></term>
269
 
        <listitem>
270
 
          <para>
271
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
 
225
            <filename class="directory">/etc/mandos</filename>.
 
226
          </para>
 
227
        </listitem>
 
228
      </varlistentry>
 
229
      
 
230
      <varlistentry>
 
231
        <term><option>--type
 
232
        <replaceable>TYPE</replaceable></option></term>
 
233
        <term><option>-t
 
234
        <replaceable>TYPE</replaceable></option></term>
 
235
        <listitem>
 
236
          <para>
 
237
            Key type.  Default is <quote>RSA</quote>.
 
238
          </para>
 
239
        </listitem>
 
240
      </varlistentry>
 
241
      
 
242
      <varlistentry>
 
243
        <term><option>--length
 
244
        <replaceable>BITS</replaceable></option></term>
 
245
        <term><option>-l
 
246
        <replaceable>BITS</replaceable></option></term>
 
247
        <listitem>
 
248
          <para>
 
249
            Key length in bits.  Default is 4096.
 
250
          </para>
 
251
        </listitem>
 
252
      </varlistentry>
 
253
      
 
254
      <varlistentry>
 
255
        <term><option>--subtype
 
256
        <replaceable>KEYTYPE</replaceable></option></term>
 
257
        <term><option>-s
 
258
        <replaceable>KEYTYPE</replaceable></option></term>
 
259
        <listitem>
 
260
          <para>
 
261
            Subkey type.  Default is <quote>RSA</quote> (Elgamal
272
262
            encryption-only).
273
263
          </para>
274
264
        </listitem>
275
265
      </varlistentry>
276
 
 
 
266
      
277
267
      <varlistentry>
278
 
        <term><literal>-L</literal>, <literal>--sublength
279
 
        <replaceable>bits</replaceable></literal></term>
 
268
        <term><option>--sublength
 
269
        <replaceable>BITS</replaceable></option></term>
 
270
        <term><option>-L
 
271
        <replaceable>BITS</replaceable></option></term>
280
272
        <listitem>
281
273
          <para>
282
 
            Subkey length in bits.  Default is 2048.
 
274
            Subkey length in bits.  Default is 4096.
283
275
          </para>
284
276
        </listitem>
285
277
      </varlistentry>
286
 
 
 
278
      
287
279
      <varlistentry>
288
 
        <term><literal>-e</literal>, <literal>--email</literal>
289
 
        <replaceable>address</replaceable></term>
 
280
        <term><option>--email
 
281
        <replaceable>ADDRESS</replaceable></option></term>
 
282
        <term><option>-e
 
283
        <replaceable>ADDRESS</replaceable></option></term>
290
284
        <listitem>
291
285
          <para>
292
286
            Email address of key.  Default is empty.
293
287
          </para>
294
288
        </listitem>
295
289
      </varlistentry>
296
 
 
 
290
      
297
291
      <varlistentry>
298
 
        <term><literal>-c</literal>, <literal>--comment</literal>
299
 
        <replaceable>comment</replaceable></term>
 
292
        <term><option>--comment
 
293
        <replaceable>TEXT</replaceable></option></term>
 
294
        <term><option>-c
 
295
        <replaceable>TEXT</replaceable></option></term>
300
296
        <listitem>
301
297
          <para>
302
 
            Comment field for key.  The default value is
303
 
            <quote><literal>Mandos client key</literal></quote>.
 
298
            Comment field for key.  Default is empty.
304
299
          </para>
305
300
        </listitem>
306
301
      </varlistentry>
307
 
 
 
302
      
308
303
      <varlistentry>
309
 
        <term><literal>-x</literal>, <literal>--expire</literal>
310
 
        <replaceable>time</replaceable></term>
 
304
        <term><option>--expire
 
305
        <replaceable>TIME</replaceable></option></term>
 
306
        <term><option>-x
 
307
        <replaceable>TIME</replaceable></option></term>
311
308
        <listitem>
312
309
          <para>
313
310
            Key expire time.  Default is no expiration.  See
316
313
          </para>
317
314
        </listitem>
318
315
      </varlistentry>
319
 
 
 
316
      
320
317
      <varlistentry>
321
 
        <term><literal>-f</literal>, <literal>--force</literal></term>
 
318
        <term><option>--force</option></term>
 
319
        <term><option>-f</option></term>
322
320
        <listitem>
323
321
          <para>
324
 
            Force overwriting old keys.
 
322
            Force overwriting old key.
325
323
          </para>
326
324
        </listitem>
327
325
      </varlistentry>
328
326
      <varlistentry>
329
 
        <term><literal>-p</literal>, <literal>--password</literal
330
 
        ></term>
 
327
        <term><option>--password</option></term>
 
328
        <term><option>-p</option></term>
331
329
        <listitem>
332
330
          <para>
333
331
            Prompt for a password and encrypt it with the key already
339
337
            >8</manvolnum></citerefentry>.  The host name or the name
340
338
            specified with the <option>--name</option> option is used
341
339
            for the section header.  All other options are ignored,
342
 
            and no keys are created.
 
340
            and no key is created.
 
341
          </para>
 
342
        </listitem>
 
343
      </varlistentry>
 
344
      <varlistentry>
 
345
        <term><option>--passfile
 
346
        <replaceable>FILE</replaceable></option></term>
 
347
        <term><option>-F
 
348
        <replaceable>FILE</replaceable></option></term>
 
349
        <listitem>
 
350
          <para>
 
351
            The same as <option>--password</option>, but read from
 
352
            <replaceable>FILE</replaceable>, not the terminal.
 
353
          </para>
 
354
        </listitem>
 
355
      </varlistentry>
 
356
      <varlistentry>
 
357
        <term><option>--no-ssh</option></term>
 
358
        <term><option>-S</option></term>
 
359
        <listitem>
 
360
          <para>
 
361
            When <option>--password</option> or
 
362
            <option>--passfile</option> is given, this option will
 
363
            prevent <command>&COMMANDNAME;</command> from calling
 
364
            <command>ssh-keyscan</command> to get an SSH fingerprint
 
365
            for this host and, if successful, output suitable config
 
366
            options to use this fingerprint as a
 
367
            <option>checker</option> option in the output.  This is
 
368
            otherwise the default behavior.
343
369
          </para>
344
370
        </listitem>
345
371
      </varlistentry>
346
372
    </variablelist>
347
373
  </refsect1>
348
 
 
 
374
  
349
375
  <refsect1 id="overview">
350
376
    <title>OVERVIEW</title>
351
377
    <xi:include href="overview.xml"/>
352
378
    <para>
353
379
      This program is a small utility to generate new OpenPGP keys for
354
 
      new Mandos clients.
 
380
      new Mandos clients, and to generate sections for inclusion in
 
381
      <filename>clients.conf</filename> on the server.
355
382
    </para>
356
383
  </refsect1>
357
 
 
 
384
  
358
385
  <refsect1 id="exit_status">
359
386
    <title>EXIT STATUS</title>
360
387
    <para>
361
 
      The exit status will be 0 if new keys were successfully created,
362
 
      otherwise not.
 
388
      The exit status will be 0 if a new key (or password, if the
 
389
      <option>--password</option> option was used) was successfully
 
390
      created, otherwise not.
363
391
    </para>
364
392
  </refsect1>
365
393
  
367
395
    <title>ENVIRONMENT</title>
368
396
    <variablelist>
369
397
      <varlistentry>
370
 
        <term><varname>TMPDIR</varname></term>
 
398
        <term><envar>TMPDIR</envar></term>
371
399
        <listitem>
372
400
          <para>
373
401
            If set, temporary files will be created here. See
379
407
    </variablelist>
380
408
  </refsect1>
381
409
  
382
 
  <refsect1 id="file">
 
410
  <refsect1 id="files">
383
411
    <title>FILES</title>
384
412
    <para>
385
413
      Use the <option>--dir</option> option to change where
406
434
        </listitem>
407
435
      </varlistentry>
408
436
      <varlistentry>
409
 
        <term><filename>/tmp</filename></term>
 
437
        <term><filename class="directory">/tmp</filename></term>
410
438
        <listitem>
411
439
          <para>
412
440
            Temporary files will be written here if
416
444
      </varlistentry>
417
445
    </variablelist>
418
446
  </refsect1>
419
 
 
420
 
  <refsect1 id="bugs">
421
 
    <title>BUGS</title>
422
 
    <para>
423
 
      None are known at this time.
424
 
    </para>
425
 
  </refsect1>
426
 
 
 
447
  
 
448
<!--   <refsect1 id="bugs"> -->
 
449
<!--     <title>BUGS</title> -->
 
450
<!--     <para> -->
 
451
<!--     </para> -->
 
452
<!--   </refsect1> -->
 
453
  
427
454
  <refsect1 id="example">
428
455
    <title>EXAMPLE</title>
429
456
    <informalexample>
431
458
        Normal invocation needs no options:
432
459
      </para>
433
460
      <para>
434
 
        <userinput>mandos-keygen</userinput>
 
461
        <userinput>&COMMANDNAME;</userinput>
435
462
      </para>
436
463
    </informalexample>
437
464
    <informalexample>
438
465
      <para>
439
 
        Create keys in another directory and of another type.  Force
 
466
        Create key in another directory and of another type.  Force
440
467
        overwriting old key files:
441
468
      </para>
442
469
      <para>
443
470
 
444
471
<!-- do not wrap this line -->
445
 
<userinput>mandos-keygen --dir ~/keydir --type RSA --force</userinput>
 
472
<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>
 
473
 
 
474
      </para>
 
475
    </informalexample>
 
476
    <informalexample>
 
477
      <para>
 
478
        Prompt for a password, encrypt it with the key in <filename
 
479
        class="directory">/etc/mandos</filename> and output a section
 
480
        suitable for <filename>clients.conf</filename>.
 
481
      </para>
 
482
      <para>
 
483
        <userinput>&COMMANDNAME; --password</userinput>
 
484
      </para>
 
485
    </informalexample>
 
486
    <informalexample>
 
487
      <para>
 
488
        Prompt for a password, encrypt it with the key in the
 
489
        <filename>client-key</filename> directory and output a section
 
490
        suitable for <filename>clients.conf</filename>.
 
491
      </para>
 
492
      <para>
 
493
 
 
494
<!-- do not wrap this line -->
 
495
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
446
496
 
447
497
      </para>
448
498
    </informalexample>
449
499
  </refsect1>
450
 
 
 
500
  
451
501
  <refsect1 id="security">
452
502
    <title>SECURITY</title>
453
503
    <para>
454
504
      The <option>--type</option>, <option>--length</option>,
455
505
      <option>--subtype</option>, and <option>--sublength</option>
456
 
      options can be used to create keys of insufficient security.  If
457
 
      in doubt, leave them to the default values.
 
506
      options can be used to create keys of low security.  If in
 
507
      doubt, leave them to the default values.
458
508
    </para>
459
509
    <para>
460
 
      The key expire time is not guaranteed to be honored by
461
 
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
510
      The key expire time is <emphasis>not</emphasis> guaranteed to be
 
511
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
462
512
      <manvolnum>8</manvolnum></citerefentry>.
463
513
    </para>
464
514
  </refsect1>
465
 
 
 
515
  
466
516
  <refsect1 id="see_also">
467
517
    <title>SEE ALSO</title>
468
518
    <para>
469
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
519
      <citerefentry><refentrytitle>intro</refentrytitle>
470
520
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
521
      <citerefentry><refentrytitle>gpg</refentrytitle>
 
522
      <manvolnum>1</manvolnum></citerefentry>,
 
523
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
 
524
      <manvolnum>5</manvolnum></citerefentry>,
471
525
      <citerefentry><refentrytitle>mandos</refentrytitle>
472
526
      <manvolnum>8</manvolnum></citerefentry>,
473
 
      <citerefentry><refentrytitle>gpg</refentrytitle>
 
527
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
528
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
529
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
474
530
      <manvolnum>1</manvolnum></citerefentry>
475
531
    </para>
476
532
  </refsect1>