/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:
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
4
<!ENTITY COMMANDNAME "mandos-keygen">
5
 
<!ENTITY TIMESTAMP "2019-07-18">
 
5
<!ENTITY TIMESTAMP "2014-06-22">
6
6
<!ENTITY % common SYSTEM "common.ent">
7
7
%common;
8
8
]>
33
33
    <copyright>
34
34
      <year>2008</year>
35
35
      <year>2009</year>
36
 
      <year>2010</year>
37
36
      <year>2011</year>
38
37
      <year>2012</year>
39
 
      <year>2013</year>
40
 
      <year>2014</year>
41
 
      <year>2015</year>
42
 
      <year>2016</year>
43
 
      <year>2017</year>
44
 
      <year>2018</year>
45
 
      <year>2019</year>
46
38
      <holder>Teddy Hogeborn</holder>
47
39
      <holder>Björn Påhlsson</holder>
48
40
    </copyright>
128
120
      </group>
129
121
      <sbr/>
130
122
      <group>
131
 
        <arg choice="plain"><option>--tls-keytype
132
 
        <replaceable>KEYTYPE</replaceable></option></arg>
133
 
        <arg choice="plain"><option>-T
134
 
        <replaceable>KEYTYPE</replaceable></option></arg>
135
 
      </group>
136
 
      <sbr/>
137
 
      <group>
138
123
        <arg choice="plain"><option>--force</option></arg>
139
124
        <arg choice="plain"><option>-f</option></arg>
140
125
      </group>
188
173
    <title>DESCRIPTION</title>
189
174
    <para>
190
175
      <command>&COMMANDNAME;</command> is a program to generate the
191
 
      TLS and OpenPGP keys used by
 
176
      OpenPGP key used by
192
177
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
193
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
194
 
      normally written to /etc/keys/mandos for later installation into
195
 
      the initrd image, but this, and most other things, can be
196
 
      changed with command line options.
 
178
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
 
179
      normally written to /etc/mandos for later installation into the
 
180
      initrd image, but this, and most other things, can be changed
 
181
      with command line options.
197
182
    </para>
198
183
    <para>
199
184
      This program can also be used with the
236
221
        <replaceable>DIRECTORY</replaceable></option></term>
237
222
        <listitem>
238
223
          <para>
239
 
            Target directory for key files.  Default is <filename
240
 
            class="directory">/etc/keys/mandos</filename>.
 
224
            Target directory for key files.  Default is
 
225
            <filename class="directory">/etc/mandos</filename>.
241
226
          </para>
242
227
        </listitem>
243
228
      </varlistentry>
249
234
        <replaceable>TYPE</replaceable></option></term>
250
235
        <listitem>
251
236
          <para>
252
 
            OpenPGP key type.  Default is <quote>RSA</quote>.
 
237
            Key type.  Default is <quote>RSA</quote>.
253
238
          </para>
254
239
        </listitem>
255
240
      </varlistentry>
261
246
        <replaceable>BITS</replaceable></option></term>
262
247
        <listitem>
263
248
          <para>
264
 
            OpenPGP key length in bits.  Default is 4096.
 
249
            Key length in bits.  Default is 4096.
265
250
          </para>
266
251
        </listitem>
267
252
      </varlistentry>
273
258
        <replaceable>KEYTYPE</replaceable></option></term>
274
259
        <listitem>
275
260
          <para>
276
 
            OpenPGP subkey type.  Default is <quote>RSA</quote>
 
261
            Subkey type.  Default is <quote>RSA</quote> (Elgamal
 
262
            encryption-only).
277
263
          </para>
278
264
        </listitem>
279
265
      </varlistentry>
285
271
        <replaceable>BITS</replaceable></option></term>
286
272
        <listitem>
287
273
          <para>
288
 
            OpenPGP subkey length in bits.  Default is 4096.
 
274
            Subkey length in bits.  Default is 4096.
289
275
          </para>
290
276
        </listitem>
291
277
      </varlistentry>
329
315
      </varlistentry>
330
316
      
331
317
      <varlistentry>
332
 
        <term><option>--tls-keytype
333
 
        <replaceable>KEYTYPE</replaceable></option></term>
334
 
        <term><option>-T
335
 
        <replaceable>KEYTYPE</replaceable></option></term>
336
 
        <listitem>
337
 
          <para>
338
 
            TLS key type.  Default is <quote>ed25519</quote>
339
 
          </para>
340
 
        </listitem>
341
 
      </varlistentry>
342
 
      
343
 
      <varlistentry>
344
318
        <term><option>--force</option></term>
345
319
        <term><option>-f</option></term>
346
320
        <listitem>
355
329
        <listitem>
356
330
          <para>
357
331
            Prompt for a password and encrypt it with the key already
358
 
            present in either <filename>/etc/keys/mandos</filename> or
359
 
            the directory specified with the <option>--dir</option>
 
332
            present in either <filename>/etc/mandos</filename> or the
 
333
            directory specified with the <option>--dir</option>
360
334
            option.  Outputs, on standard output, a section suitable
361
335
            for inclusion in <citerefentry><refentrytitle
362
336
            >mandos-clients.conf</refentrytitle><manvolnum
363
337
            >8</manvolnum></citerefentry>.  The host name or the name
364
338
            specified with the <option>--name</option> option is used
365
339
            for the section header.  All other options are ignored,
366
 
            and no key is created.  Note: white space is stripped from
367
 
            the beginning and from the end of the password; See <xref
368
 
            linkend="bugs"/>.
 
340
            and no key is created.
369
341
          </para>
370
342
        </listitem>
371
343
      </varlistentry>
377
349
        <listitem>
378
350
          <para>
379
351
            The same as <option>--password</option>, but read from
380
 
            <replaceable>FILE</replaceable>, not the terminal, and
381
 
            white space is not stripped from the password in any way.
 
352
            <replaceable>FILE</replaceable>, not the terminal.
382
353
          </para>
383
354
        </listitem>
384
355
      </varlistentry>
405
376
    <title>OVERVIEW</title>
406
377
    <xi:include href="overview.xml"/>
407
378
    <para>
408
 
      This program is a small utility to generate new TLS and OpenPGP
409
 
      keys for new Mandos clients, and to generate sections for
410
 
      inclusion in <filename>clients.conf</filename> on the server.
 
379
      This program is a small utility to generate new OpenPGP keys for
 
380
      new Mandos clients, and to generate sections for inclusion in
 
381
      <filename>clients.conf</filename> on the server.
411
382
    </para>
412
383
  </refsect1>
413
384
  
445
416
    </para>
446
417
    <variablelist>
447
418
      <varlistentry>
448
 
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
 
419
        <term><filename>/etc/mandos/seckey.txt</filename></term>
449
420
        <listitem>
450
421
          <para>
451
422
            OpenPGP secret key file which will be created or
454
425
        </listitem>
455
426
      </varlistentry>
456
427
      <varlistentry>
457
 
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
 
428
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
458
429
        <listitem>
459
430
          <para>
460
431
            OpenPGP public key file which will be created or
463
434
        </listitem>
464
435
      </varlistentry>
465
436
      <varlistentry>
466
 
        <term><filename>/etc/keys/mandos/tls-privkey.pem</filename></term>
467
 
        <listitem>
468
 
          <para>
469
 
            Private key file which will be created or overwritten.
470
 
          </para>
471
 
        </listitem>
472
 
      </varlistentry>
473
 
      <varlistentry>
474
 
        <term><filename>/etc/keys/mandos/tls-pubkey.pem</filename></term>
475
 
        <listitem>
476
 
          <para>
477
 
            Public key file which will be created or overwritten.
478
 
          </para>
479
 
        </listitem>
480
 
      </varlistentry>
481
 
      <varlistentry>
482
437
        <term><filename class="directory">/tmp</filename></term>
483
438
        <listitem>
484
439
          <para>
490
445
    </variablelist>
491
446
  </refsect1>
492
447
  
493
 
  <refsect1 id="bugs">
494
 
    <title>BUGS</title>
495
 
    <para>
496
 
      The <option>--password</option>/<option>-p</option> option
497
 
      strips white space from the start and from the end of the
498
 
      password before using it.  If this is a problem, use the
499
 
      <option>--passfile</option> option instead, which does not do
500
 
      this.
501
 
    </para>
502
 
    <xi:include href="bugs.xml"/>
503
 
  </refsect1>
 
448
<!--   <refsect1 id="bugs"> -->
 
449
<!--     <title>BUGS</title> -->
 
450
<!--     <para> -->
 
451
<!--     </para> -->
 
452
<!--   </refsect1> -->
504
453
  
505
454
  <refsect1 id="example">
506
455
    <title>EXAMPLE</title>
526
475
    </informalexample>
527
476
    <informalexample>
528
477
      <para>
529
 
        Prompt for a password, encrypt it with the keys in <filename
530
 
        class="directory">/etc/keys/mandos</filename> and output a
531
 
        section suitable 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>.
532
481
      </para>
533
482
      <para>
534
483
        <userinput>&COMMANDNAME; --password</userinput>
536
485
    </informalexample>
537
486
    <informalexample>
538
487
      <para>
539
 
        Prompt for a password, encrypt it with the keys in the
 
488
        Prompt for a password, encrypt it with the key in the
540
489
        <filename>client-key</filename> directory and output a section
541
490
        suitable for <filename>clients.conf</filename>.
542
491
      </para>