/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-ctl.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-ctl">
5
 
<!ENTITY TIMESTAMP "2010-09-21">
 
5
<!ENTITY TIMESTAMP "2012-06-22">
6
6
<!ENTITY % common SYSTEM "common.ent">
7
7
%common;
8
8
]>
19
19
        <firstname>Björn</firstname>
20
20
        <surname>Påhlsson</surname>
21
21
        <address>
22
 
          <email>belorn@fukt.bsnet.se</email>
 
22
          <email>belorn@recompile.se</email>
23
23
        </address>
24
24
      </author>
25
25
      <author>
26
26
        <firstname>Teddy</firstname>
27
27
        <surname>Hogeborn</surname>
28
28
        <address>
29
 
          <email>teddy@fukt.bsnet.se</email>
 
29
          <email>teddy@recompile.se</email>
30
30
        </address>
31
31
      </author>
32
32
    </authorgroup>
33
33
    <copyright>
34
34
      <year>2010</year>
 
35
      <year>2011</year>
 
36
      <year>2012</year>
35
37
      <holder>Teddy Hogeborn</holder>
36
38
      <holder>Björn Påhlsson</holder>
37
39
    </copyright>
94
96
      </group>
95
97
      <sbr/>
96
98
      <group>
 
99
        <arg choice="plain"><option>--extended-timeout
 
100
        <replaceable>TIME</replaceable></option></arg>
 
101
      </group>
 
102
      <sbr/>
 
103
      <group>
 
104
        <arg choice="plain"><option>--interval
 
105
        <replaceable>TIME</replaceable></option></arg>
 
106
        <arg choice="plain"><option>-i
 
107
        <replaceable>TIME</replaceable></option></arg>
 
108
      </group>
 
109
      <sbr/>
 
110
      <group>
 
111
        <arg choice="plain"><option>--approve-by-default</option
 
112
        ></arg>
 
113
        <sbr/>
 
114
        <arg choice="plain"><option>--deny-by-default</option></arg>
 
115
      </group>
 
116
      <sbr/>
 
117
      <group>
 
118
        <arg choice="plain"><option>--approval-delay
 
119
        <replaceable>TIME</replaceable></option></arg>
 
120
      </group>
 
121
      <sbr/>
 
122
      <group>
 
123
        <arg choice="plain"><option>--approval-duration
 
124
        <replaceable>TIME</replaceable></option></arg>
 
125
      </group>
 
126
      <sbr/>
 
127
      <group>
97
128
        <arg choice="plain"><option>--interval
98
129
        <replaceable>TIME</replaceable></option></arg>
99
130
        <arg choice="plain"><option>-i
164
195
        <arg choice="plain"><option>-v</option></arg>
165
196
      </group>
166
197
    </cmdsynopsis>
 
198
    <cmdsynopsis>
 
199
      <command>&COMMANDNAME;</command>
 
200
      <arg choice="plain"><option>--check</option></arg>
 
201
    </cmdsynopsis>
167
202
  </refsynopsisdiv>
168
203
  
169
204
  <refsect1 id="description">
273
308
          <para>
274
309
            Set the <varname>checker</varname> option of the specified
275
310
            client(s); see <citerefentry><refentrytitle
276
 
            >mandos-client.conf</refentrytitle><manvolnum>5</manvolnum
277
 
            ></citerefentry>.
 
311
            >mandos-clients.conf</refentrytitle><manvolnum
 
312
            >5</manvolnum></citerefentry>.
278
313
          </para>
279
314
        </listitem>
280
315
      </varlistentry>
288
323
          <para>
289
324
            Set the <varname>timeout</varname> option of the specified
290
325
            client(s); see <citerefentry><refentrytitle
291
 
            >mandos-client.conf</refentrytitle><manvolnum>5</manvolnum
292
 
            ></citerefentry>.
 
326
            >mandos-clients.conf</refentrytitle><manvolnum
 
327
            >5</manvolnum></citerefentry>.
 
328
          </para>
 
329
        </listitem>
 
330
      </varlistentry>
 
331
 
 
332
      <varlistentry>
 
333
        <term><option>--extended-timeout
 
334
        <replaceable>TIME</replaceable></option></term>
 
335
        <listitem>
 
336
          <para>
 
337
            Set the <varname>extended_timeout</varname> option of the
 
338
            specified client(s); see <citerefentry><refentrytitle
 
339
            >mandos-clients.conf</refentrytitle><manvolnum
 
340
            >5</manvolnum></citerefentry>.
293
341
          </para>
294
342
        </listitem>
295
343
      </varlistentry>
301
349
        <replaceable>TIME</replaceable></option></term>
302
350
        <listitem>
303
351
          <para>
304
 
            Set the <varname>interval</varname> option of the specified
305
 
            client(s); see <citerefentry><refentrytitle
306
 
            >mandos-client.conf</refentrytitle><manvolnum>5</manvolnum
307
 
            ></citerefentry>.
 
352
            Set the <varname>interval</varname> option of the
 
353
            specified client(s); see <citerefentry><refentrytitle
 
354
            >mandos-clients.conf</refentrytitle><manvolnum
 
355
            >5</manvolnum></citerefentry>.
 
356
          </para>
 
357
        </listitem>
 
358
      </varlistentry>
 
359
      
 
360
      <varlistentry>
 
361
        <term><option>--approve-by-default</option></term>
 
362
        <term><option>--deny-by-default</option></term>
 
363
        <listitem>
 
364
          <para>
 
365
            Set the <varname>approved_by_default</varname> option of
 
366
            the specified client(s) to <literal>True</literal> or
 
367
            <literal>False</literal>, respectively; see
 
368
            <citerefentry><refentrytitle
 
369
            >mandos-clients.conf</refentrytitle><manvolnum
 
370
            >5</manvolnum></citerefentry>.
 
371
          </para>
 
372
        </listitem>
 
373
      </varlistentry>
 
374
      
 
375
      <varlistentry>
 
376
        <term><option>--approval-delay
 
377
        <replaceable>TIME</replaceable></option></term>
 
378
        <listitem>
 
379
          <para>
 
380
            Set the <varname>approval_delay</varname> option of the
 
381
            specified client(s); see <citerefentry><refentrytitle
 
382
            >mandos-clients.conf</refentrytitle><manvolnum
 
383
            >5</manvolnum></citerefentry>.
 
384
          </para>
 
385
        </listitem>
 
386
      </varlistentry>
 
387
      
 
388
      <varlistentry>
 
389
        <term><option>--approval-duration
 
390
        <replaceable>TIME</replaceable></option></term>
 
391
        <listitem>
 
392
          <para>
 
393
            Set the <varname>approval_duration</varname> option of the
 
394
            specified client(s); see <citerefentry><refentrytitle
 
395
            >mandos-clients.conf</refentrytitle><manvolnum
 
396
            >5</manvolnum></citerefentry>.
308
397
          </para>
309
398
        </listitem>
310
399
      </varlistentry>
318
407
          <para>
319
408
            Set the <varname>host</varname> option of the specified
320
409
            client(s); see <citerefentry><refentrytitle
321
 
            >mandos-client.conf</refentrytitle><manvolnum>5</manvolnum
322
 
            ></citerefentry>.
 
410
            >mandos-clients.conf</refentrytitle><manvolnum
 
411
            >5</manvolnum></citerefentry>.
323
412
          </para>
324
413
        </listitem>
325
414
      </varlistentry>
333
422
          <para>
334
423
            Set the <varname>secfile</varname> option of the specified
335
424
            client(s); see <citerefentry><refentrytitle
336
 
            >mandos-client.conf</refentrytitle><manvolnum>5</manvolnum
337
 
            ></citerefentry>.
 
425
            >mandos-clients.conf</refentrytitle><manvolnum
 
426
            >5</manvolnum></citerefentry>.
338
427
          </para>
339
428
        </listitem>
340
429
      </varlistentry>
391
480
        </listitem>
392
481
      </varlistentry>
393
482
      
 
483
      <varlistentry>
 
484
        <term><option>--check</option></term>
 
485
        <listitem>
 
486
          <para>
 
487
            Run self-tests.  This includes any unit tests, etc.
 
488
          </para>
 
489
        </listitem>
 
490
      </varlistentry>
 
491
      
394
492
    </variablelist>
395
493
  </refsect1>
396
494
  
422
520
    <title>EXAMPLE</title>
423
521
    <informalexample>
424
522
      <para>
425
 
        List all clients with some of their settings:
 
523
        To list all clients:
426
524
      </para>
427
525
      <para>
428
526
        <userinput>&COMMANDNAME;</userinput>
429
527
      </para>
430
528
    </informalexample>
431
 
    <informalexample>
432
 
      <para>
433
 
        Show all settings for the clients named <quote>foo</quote> and
434
 
        <quote>bar</quote>:
435
 
      </para>
436
 
      <para>
437
 
 
438
 
<!-- do not wrap this line -->
439
 
<userinput>&COMMANDNAME; --verbose foo bar</userinput>
440
 
 
 
529
    
 
530
    <informalexample>
 
531
      <para>
 
532
        To list <emphasis>all</emphasis> settings for the clients
 
533
        named <quote>foo1.example.org</quote> and <quote
 
534
        >foo2.example.org</quote>:
 
535
      </para>
 
536
      <para>
 
537
 
 
538
<!-- do not wrap this line -->
 
539
<userinput>&COMMANDNAME; --verbose foo1.example.org foo2.example.org</userinput>
 
540
 
 
541
      </para>
 
542
    </informalexample>
 
543
    
 
544
    <informalexample>
 
545
      <para>
 
546
        To enable all clients:
 
547
      </para>
 
548
      <para>
 
549
        <userinput>&COMMANDNAME; --enable --all</userinput>
 
550
      </para>
 
551
    </informalexample>
 
552
    
 
553
    <informalexample>
 
554
      <para>
 
555
        To change timeout and interval value for the clients
 
556
        named <quote>foo1.example.org</quote> and <quote
 
557
        >foo2.example.org</quote>:
 
558
      </para>
 
559
      <para>
 
560
 
 
561
<!-- do not wrap this line -->
 
562
<userinput>&COMMANDNAME; --timeout="5m" --interval="1m" foo1.example.org foo2.example.org</userinput>
 
563
 
 
564
      </para>
 
565
    </informalexample>
 
566
    
 
567
    <informalexample>
 
568
      <para>
 
569
        To approve all clients currently waiting for it:
 
570
      </para>
 
571
      <para>
 
572
        <userinput>&COMMANDNAME; --approve --all</userinput>
441
573
      </para>
442
574
    </informalexample>
443
575
  </refsect1>
454
586
  <refsect1 id="see_also">
455
587
    <title>SEE ALSO</title>
456
588
    <para>
 
589
      <citerefentry><refentrytitle>intro</refentrytitle>
 
590
      <manvolnum>8mandos</manvolnum></citerefentry>,
457
591
      <citerefentry><refentrytitle>mandos</refentrytitle>
458
592
      <manvolnum>8</manvolnum></citerefentry>,
459
593
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>