/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: 2015-05-23 20:18:34 UTC
  • mto: (237.7.304 trunk)
  • mto: This revision was merged to the branch mainline in revision 325.
  • 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-31">
 
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>
70
52
      Generate key and password for Mandos client and server.
71
53
    </refpurpose>
72
54
  </refnamediv>
73
 
 
 
55
  
74
56
  <refsynopsisdiv>
75
57
    <cmdsynopsis>
76
58
      <command>&COMMANDNAME;</command>
137
119
        <replaceable>TIME</replaceable></option></arg>
138
120
      </group>
139
121
      <sbr/>
140
 
      <arg><option>--force</option></arg>
 
122
      <group>
 
123
        <arg choice="plain"><option>--force</option></arg>
 
124
        <arg choice="plain"><option>-f</option></arg>
 
125
      </group>
141
126
    </cmdsynopsis>
142
127
    <cmdsynopsis>
143
128
      <command>&COMMANDNAME;</command>
144
129
      <group choice="req">
145
130
        <arg choice="plain"><option>--password</option></arg>
146
131
        <arg choice="plain"><option>-p</option></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>
147
136
      </group>
148
137
      <sbr/>
149
138
      <group>
159
148
        <arg choice="plain"><option>-n
160
149
        <replaceable>NAME</replaceable></option></arg>
161
150
      </group>
 
151
      <group>
 
152
        <arg choice="plain"><option>--no-ssh</option></arg>
 
153
        <arg choice="plain"><option>-S</option></arg>
 
154
      </group>
162
155
    </cmdsynopsis>
163
156
    <cmdsynopsis>
164
157
      <command>&COMMANDNAME;</command>
181
174
    <para>
182
175
      <command>&COMMANDNAME;</command> is a program to generate the
183
176
      OpenPGP key used by
184
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
177
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
185
178
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
186
179
      normally written to /etc/mandos for later installation into the
187
180
      initrd image, but this, and most other things, can be changed
189
182
    </para>
190
183
    <para>
191
184
      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
 
185
      <option>--password</option> or <option>--passfile</option>
 
186
      options to generate a ready-made section for
 
187
      <filename>clients.conf</filename> (see
194
188
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
195
189
      <manvolnum>5</manvolnum></citerefentry>).
196
190
    </para>
219
213
          </para>
220
214
        </listitem>
221
215
      </varlistentry>
222
 
 
 
216
      
223
217
      <varlistentry>
224
218
        <term><option>--dir
225
219
        <replaceable>DIRECTORY</replaceable></option></term>
228
222
        <listitem>
229
223
          <para>
230
224
            Target directory for key files.  Default is
231
 
            <filename>/etc/mandos</filename>.
 
225
            <filename class="directory">/etc/mandos</filename>.
232
226
          </para>
233
227
        </listitem>
234
228
      </varlistentry>
235
 
 
 
229
      
236
230
      <varlistentry>
237
231
        <term><option>--type
238
232
        <replaceable>TYPE</replaceable></option></term>
240
234
        <replaceable>TYPE</replaceable></option></term>
241
235
        <listitem>
242
236
          <para>
243
 
            Key type.  Default is <quote>DSA</quote>.
 
237
            Key type.  Default is <quote>RSA</quote>.
244
238
          </para>
245
239
        </listitem>
246
240
      </varlistentry>
247
 
 
 
241
      
248
242
      <varlistentry>
249
243
        <term><option>--length
250
244
        <replaceable>BITS</replaceable></option></term>
252
246
        <replaceable>BITS</replaceable></option></term>
253
247
        <listitem>
254
248
          <para>
255
 
            Key length in bits.  Default is 2048.
 
249
            Key length in bits.  Default is 4096.
256
250
          </para>
257
251
        </listitem>
258
252
      </varlistentry>
259
 
 
 
253
      
260
254
      <varlistentry>
261
255
        <term><option>--subtype
262
256
        <replaceable>KEYTYPE</replaceable></option></term>
264
258
        <replaceable>KEYTYPE</replaceable></option></term>
265
259
        <listitem>
266
260
          <para>
267
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
 
261
            Subkey type.  Default is <quote>RSA</quote> (Elgamal
268
262
            encryption-only).
269
263
          </para>
270
264
        </listitem>
271
265
      </varlistentry>
272
 
 
 
266
      
273
267
      <varlistentry>
274
268
        <term><option>--sublength
275
269
        <replaceable>BITS</replaceable></option></term>
277
271
        <replaceable>BITS</replaceable></option></term>
278
272
        <listitem>
279
273
          <para>
280
 
            Subkey length in bits.  Default is 2048.
 
274
            Subkey length in bits.  Default is 4096.
281
275
          </para>
282
276
        </listitem>
283
277
      </varlistentry>
284
 
 
 
278
      
285
279
      <varlistentry>
286
280
        <term><option>--email
287
281
        <replaceable>ADDRESS</replaceable></option></term>
293
287
          </para>
294
288
        </listitem>
295
289
      </varlistentry>
296
 
 
 
290
      
297
291
      <varlistentry>
298
292
        <term><option>--comment
299
293
        <replaceable>TEXT</replaceable></option></term>
301
295
        <replaceable>TEXT</replaceable></option></term>
302
296
        <listitem>
303
297
          <para>
304
 
            Comment field for key.  The default value is
305
 
            <quote><literal>Mandos client key</literal></quote>.
 
298
            Comment field for key.  Default is empty.
306
299
          </para>
307
300
        </listitem>
308
301
      </varlistentry>
309
 
 
 
302
      
310
303
      <varlistentry>
311
304
        <term><option>--expire
312
305
        <replaceable>TIME</replaceable></option></term>
320
313
          </para>
321
314
        </listitem>
322
315
      </varlistentry>
323
 
 
 
316
      
324
317
      <varlistentry>
325
318
        <term><option>--force</option></term>
326
319
        <term><option>-f</option></term>
348
341
          </para>
349
342
        </listitem>
350
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.
 
369
          </para>
 
370
        </listitem>
 
371
      </varlistentry>
351
372
    </variablelist>
352
373
  </refsect1>
353
 
 
 
374
  
354
375
  <refsect1 id="overview">
355
376
    <title>OVERVIEW</title>
356
377
    <xi:include href="overview.xml"/>
360
381
      <filename>clients.conf</filename> on the server.
361
382
    </para>
362
383
  </refsect1>
363
 
 
 
384
  
364
385
  <refsect1 id="exit_status">
365
386
    <title>EXIT STATUS</title>
366
387
    <para>
386
407
    </variablelist>
387
408
  </refsect1>
388
409
  
389
 
  <refsect1 id="file">
 
410
  <refsect1 id="files">
390
411
    <title>FILES</title>
391
412
    <para>
392
413
      Use the <option>--dir</option> option to change where
413
434
        </listitem>
414
435
      </varlistentry>
415
436
      <varlistentry>
416
 
        <term><filename>/tmp</filename></term>
 
437
        <term><filename class="directory">/tmp</filename></term>
417
438
        <listitem>
418
439
          <para>
419
440
            Temporary files will be written here if
423
444
      </varlistentry>
424
445
    </variablelist>
425
446
  </refsect1>
426
 
 
427
 
  <refsect1 id="bugs">
428
 
    <title>BUGS</title>
429
 
    <para>
430
 
      None are known at this time.
431
 
    </para>
432
 
  </refsect1>
433
 
 
 
447
  
 
448
<!--   <refsect1 id="bugs"> -->
 
449
<!--     <title>BUGS</title> -->
 
450
<!--     <para> -->
 
451
<!--     </para> -->
 
452
<!--   </refsect1> -->
 
453
  
434
454
  <refsect1 id="example">
435
455
    <title>EXAMPLE</title>
436
456
    <informalexample>
455
475
    </informalexample>
456
476
    <informalexample>
457
477
      <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>.
 
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>.
461
481
      </para>
462
482
      <para>
463
483
        <userinput>&COMMANDNAME; --password</userinput>
477
497
      </para>
478
498
    </informalexample>
479
499
  </refsect1>
480
 
 
 
500
  
481
501
  <refsect1 id="security">
482
502
    <title>SECURITY</title>
483
503
    <para>
492
512
      <manvolnum>8</manvolnum></citerefentry>.
493
513
    </para>
494
514
  </refsect1>
495
 
 
 
515
  
496
516
  <refsect1 id="see_also">
497
517
    <title>SEE ALSO</title>
498
518
    <para>
 
519
      <citerefentry><refentrytitle>intro</refentrytitle>
 
520
      <manvolnum>8mandos</manvolnum></citerefentry>,
499
521
      <citerefentry><refentrytitle>gpg</refentrytitle>
500
522
      <manvolnum>1</manvolnum></citerefentry>,
501
523
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
502
524
      <manvolnum>5</manvolnum></citerefentry>,
503
525
      <citerefentry><refentrytitle>mandos</refentrytitle>
504
526
      <manvolnum>8</manvolnum></citerefentry>,
505
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
506
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
527
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
528
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
529
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
 
530
      <manvolnum>1</manvolnum></citerefentry>
507
531
    </para>
508
532
  </refsect1>
509
533