/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.conf.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
 
<?xml version='1.0' encoding='UTF-8'?>
 
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 CONFNAME "mandos.conf">
6
5
<!ENTITY CONFPATH "<filename>/etc/mandos/mandos.conf</filename>">
7
 
<!ENTITY OVERVIEW SYSTEM "overview.xml">
 
6
<!ENTITY TIMESTAMP "2015-04-02">
 
7
<!ENTITY % common SYSTEM "common.ent">
 
8
%common;
8
9
]>
9
10
 
10
 
<refentry>
 
11
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
12
  <refentryinfo>
12
 
    <title>&CONFNAME;</title>
 
13
    <title>Mandos Manual</title>
13
14
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
14
 
    <productname>&CONFNAME;</productname>
15
 
    <productnumber>&VERSION;</productnumber>
 
15
    <productname>Mandos</productname>
 
16
    <productnumber>&version;</productnumber>
 
17
    <date>&TIMESTAMP;</date>
16
18
    <authorgroup>
17
19
      <author>
18
20
        <firstname>Björn</firstname>
19
21
        <surname>Påhlsson</surname>
20
22
        <address>
21
 
          <email>belorn@fukt.bsnet.se</email>
 
23
          <email>belorn@recompile.se</email>
22
24
        </address>
23
25
      </author>
24
26
      <author>
25
27
        <firstname>Teddy</firstname>
26
28
        <surname>Hogeborn</surname>
27
29
        <address>
28
 
          <email>teddy@fukt.bsnet.se</email>
 
30
          <email>teddy@recompile.se</email>
29
31
        </address>
30
32
      </author>
31
33
    </authorgroup>
32
34
    <copyright>
33
35
      <year>2008</year>
 
36
      <year>2009</year>
 
37
      <year>2011</year>
 
38
      <year>2012</year>
 
39
      <year>2013</year>
34
40
      <holder>Teddy Hogeborn</holder>
35
41
      <holder>Björn Påhlsson</holder>
36
42
    </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>
 
43
    <xi:include href="legalnotice.xml"/>
60
44
  </refentryinfo>
61
 
 
 
45
  
62
46
  <refmeta>
63
47
    <refentrytitle>&CONFNAME;</refentrytitle>
64
48
    <manvolnum>5</manvolnum>
70
54
      Configuration file for the Mandos server
71
55
    </refpurpose>
72
56
  </refnamediv>
73
 
 
 
57
  
74
58
  <refsynopsisdiv>
75
 
    <synopsis>
76
 
      &CONFPATH;
77
 
    </synopsis>
 
59
    <synopsis>&CONFPATH;</synopsis>
78
60
  </refsynopsisdiv>
79
 
 
 
61
  
80
62
  <refsect1 id="description">
81
63
    <title>DESCRIPTION</title>
82
64
    <para>
83
65
      The file &CONFPATH; is a simple configuration file for
84
66
      <citerefentry><refentrytitle>mandos</refentrytitle>
85
67
      <manvolnum>8</manvolnum></citerefentry>, and is read by it at
86
 
      startup.  The configuration file starts with
87
 
      <quote><literal>[DEFAULT]</literal></quote> on a line by itself,
88
 
      followed by any number of
89
 
      <quote><varname><replaceable>option</replaceable></varname>=<replaceable>value</replaceable></quote>
90
 
      entries, with continuations in the style of RFC 822.
91
 
      <quote><varname><replaceable>option</replaceable></varname>:
92
 
      <replaceable>value</replaceable></quote> is also accepted.  Note
93
 
      that leading whitespace is removed from values.  Lines beginning
94
 
      with <quote>#</quote> or <quote>;</quote> are ignored and may be
95
 
      used to provide comments.
96
 
    </para>
97
 
 
98
 
    <para>
99
 
      The options are:
100
 
    </para>
101
 
 
 
68
      startup.  The configuration file starts with <quote><literal
 
69
      >[DEFAULT]</literal></quote> on a line by itself, followed by
 
70
      any number of <quote><varname><replaceable>option</replaceable
 
71
      ></varname>=<replaceable>value</replaceable></quote> entries,
 
72
      with continuations in the style of RFC 822.  <quote><varname
 
73
      ><replaceable>option</replaceable></varname>: <replaceable
 
74
      >value</replaceable></quote> is also accepted.  Note that
 
75
      leading whitespace is removed from values.  Lines beginning with
 
76
      <quote>#</quote> or <quote>;</quote> are ignored and may be used
 
77
      to provide comments.
 
78
    </para>
 
79
    
 
80
  </refsect1>
 
81
  <refsect1>
 
82
    <title>OPTIONS</title>
 
83
    
102
84
    <variablelist>
103
85
      <varlistentry>
104
 
        <term><literal><varname>interface</varname></literal></term>
105
 
        <listitem>
106
 
          <para>
107
 
            This option allows you to override the default network
108
 
            interfaces. By default mandos will not bind to any
109
 
            specific interface but instead use default avahi-server
110
 
            behaviour.
111
 
          </para>
112
 
        </listitem>
113
 
      </varlistentry>
114
 
 
115
 
      <varlistentry>
116
 
        <term><literal><varname>address</varname></literal></term>
117
 
        <listitem>
118
 
          <para>
119
 
            This option allows you to override the default network
120
 
            address. By default mandos will not bind to any
121
 
            specific address but instead use default avahi-server
122
 
            behaviour.
123
 
          </para>
124
 
        </listitem>
125
 
      </varlistentry>      
126
 
 
127
 
      <varlistentry>
128
 
        <term><literal><varname>port</varname></literal></term>
129
 
        <listitem>
130
 
          <para>
131
 
            This option allows you to override the default port to
132
 
            listen on. By default mandos will not specify any specific
133
 
            port and instead use a random port given by the OS from
134
 
            the use of INADDR_ANY.
135
 
          </para>
136
 
        </listitem>
137
 
      </varlistentry>
138
 
 
139
 
      <varlistentry>
140
 
        <term><literal><varname>debug</varname></literal></term>
141
 
        <listitem>
142
 
          <para>
143
 
            This option allows you to modify debug mode with a true/false
144
 
            boolean value. By default is debug set to <literal>false</literal>.
145
 
          </para>
146
 
        </listitem>
147
 
      </varlistentry>      
148
 
 
149
 
      <varlistentry>
150
 
        <term><literal><varname>priority</varname></literal></term>
151
 
        <listitem>
152
 
          <para>
153
 
            This option allows you to override the default gnutls
154
 
            priority that will be used in gnutls session. See
155
 
            <citerefentry><refentrytitle>gnutls_priority_init
156
 
            </refentrytitle><manvolnum>3</manvolnum></citerefentry>for
157
 
            more information on gnutls priority strings.
158
 
          </para>         
159
 
        </listitem>
160
 
      </varlistentry>
161
 
 
162
 
      <varlistentry>
163
 
        <term><literal><varname>servicename</varname></literal></term>
164
 
        <listitem>
165
 
          <para>
166
 
            This option allows you to override the default Zeroconf
167
 
            service name use to announce mandos as a avahi service. By
168
 
            default mandos will use "Mandos".
169
 
          </para>
 
86
        <term><option>interface<literal> = </literal><replaceable
 
87
        >NAME</replaceable></option></term>
 
88
        <listitem>
 
89
          <xi:include href="mandos-options.xml" xpointer="interface"/>
 
90
        </listitem>
 
91
      </varlistentry>
 
92
      
 
93
      <varlistentry>
 
94
        <term><option>address<literal> = </literal><replaceable
 
95
          >ADDRESS</replaceable></option></term>
 
96
        <listitem>
 
97
          <xi:include href="mandos-options.xml" xpointer="address"/>
 
98
        </listitem>
 
99
      </varlistentry>
 
100
      
 
101
      <varlistentry>
 
102
        <term><option>port<literal> = </literal><replaceable
 
103
        >NUMBER</replaceable></option></term>
 
104
        <listitem>
 
105
          <xi:include href="mandos-options.xml" xpointer="port"/>
 
106
        </listitem>
 
107
      </varlistentry>
 
108
      
 
109
      <varlistentry>
 
110
        <term><option>debug<literal> = </literal>{ <literal
 
111
          >1</literal> | <literal>yes</literal> | <literal
 
112
          >true</literal> | <literal>on</literal> | <literal
 
113
          >0</literal> | <literal>no</literal> | <literal
 
114
          >false</literal> | <literal>off</literal> }</option></term>
 
115
        <listitem>
 
116
          <xi:include href="mandos-options.xml" xpointer="debug"/>
 
117
        </listitem>
 
118
      </varlistentry>
 
119
      
 
120
      <varlistentry>
 
121
        <term><option>priority<literal> = </literal><replaceable
 
122
        >STRING</replaceable></option></term>
 
123
        <listitem>
 
124
          <xi:include href="mandos-options.xml"
 
125
                      xpointer="priority_compat"/>
 
126
        </listitem>
 
127
      </varlistentry>
 
128
      
 
129
      <varlistentry>
 
130
        <term><option>servicename<literal> = </literal
 
131
        ><replaceable>NAME</replaceable></option></term>
 
132
        <listitem>
 
133
          <xi:include href="mandos-options.xml"
 
134
                      xpointer="servicename"/>
 
135
        </listitem>
 
136
      </varlistentry>
 
137
      
 
138
      <varlistentry>
 
139
        <term><option>use_dbus<literal> = </literal>{ <literal
 
140
          >1</literal> | <literal>yes</literal> | <literal
 
141
          >true</literal> | <literal>on</literal> | <literal
 
142
          >0</literal> | <literal>no</literal> | <literal
 
143
          >false</literal> | <literal>off</literal> }</option></term>
 
144
        <listitem>
 
145
          <xi:include href="mandos-options.xml" xpointer="dbus"/>
 
146
        </listitem>
 
147
      </varlistentry>
 
148
      
 
149
      <varlistentry>
 
150
        <term><option>use_ipv6<literal> = </literal>{ <literal
 
151
          >1</literal> | <literal>yes</literal> | <literal
 
152
          >true</literal> | <literal>on</literal> | <literal
 
153
          >0</literal> | <literal>no</literal> | <literal
 
154
          >false</literal> | <literal>off</literal> }</option></term>
 
155
        <listitem>
 
156
          <xi:include href="mandos-options.xml" xpointer="ipv6"/>
 
157
        </listitem>
 
158
      </varlistentry>
 
159
      
 
160
      <varlistentry>
 
161
        <term><option>restore<literal> = </literal>{ <literal
 
162
          >1</literal> | <literal>yes</literal> | <literal
 
163
          >true</literal> | <literal>on</literal> | <literal
 
164
          >0</literal> | <literal>no</literal> | <literal
 
165
          >false</literal> | <literal>off</literal> }</option></term>
 
166
        <listitem>
 
167
          <xi:include href="mandos-options.xml" xpointer="restore"/>
 
168
        </listitem>
 
169
      </varlistentry>
 
170
      
 
171
      <varlistentry>
 
172
        <term><option>statedir<literal> = </literal><replaceable
 
173
        >DIRECTORY</replaceable></option></term>
 
174
        <listitem>
 
175
          <xi:include href="mandos-options.xml" xpointer="statedir"/>
 
176
        </listitem>
 
177
      </varlistentry>
 
178
      
 
179
      <varlistentry>
 
180
        <term><option>socket<literal> = </literal><replaceable
 
181
        >NUMBER</replaceable></option></term>
 
182
        <listitem>
 
183
          <xi:include href="mandos-options.xml" xpointer="socket"/>
170
184
        </listitem>
171
185
      </varlistentry>
172
186
      
173
187
    </variablelist>
174
188
  </refsect1>
175
 
 
176
 
  <refsect1 id="examples">
177
 
    <title>EXAMPLES</title>
178
 
    <informalexample>
179
 
      <programlisting>
180
 
        [server]
181
 
        # A configuration example
182
 
        interface = eth0 
183
 
        address = 2001:DB8:
184
 
        port = 1025 
185
 
        debug = true 
186
 
        priority = SECURE256:!CTYPE-X.509:+CTYPE-OPENPGP
187
 
        servicename = Mandos
188
 
      </programlisting>
189
 
    </informalexample>
190
 
  </refsect1>  
191
189
  
192
190
  <refsect1 id="files">
193
191
    <title>FILES</title>
195
193
      The file described here is &CONFPATH;
196
194
    </para>
197
195
  </refsect1>
 
196
  
 
197
  <refsect1 id="bugs">
 
198
    <title>BUGS</title>
 
199
    <para>
 
200
      The <literal>[DEFAULT]</literal> is necessary because the Python
 
201
      built-in module <systemitem class="library">ConfigParser</systemitem>
 
202
      requires it.
 
203
    </para>
 
204
  </refsect1>
 
205
  
 
206
  <refsect1 id="example">
 
207
    <title>EXAMPLE</title>
 
208
    <informalexample>
 
209
      <para>
 
210
        No options are actually required:
 
211
      </para>
 
212
      <programlisting>
 
213
[DEFAULT]
 
214
      </programlisting>
 
215
    </informalexample>
 
216
    <informalexample>
 
217
      <para>
 
218
        An example using all the options:
 
219
      </para>
 
220
      <programlisting>
 
221
[DEFAULT]
 
222
# A configuration example
 
223
interface = eth0
 
224
address = fe80::aede:48ff:fe71:f6f2
 
225
port = 1025
 
226
debug = True
 
227
priority = SECURE256:!CTYPE-X.509:+CTYPE-OPENPGP:!RSA
 
228
servicename = Daena
 
229
use_dbus = False
 
230
use_ipv6 = True
 
231
restore = True
 
232
statedir = /var/lib/mandos
 
233
      </programlisting>
 
234
    </informalexample>
 
235
  </refsect1>
 
236
  
 
237
  <refsect1 id="see_also">
 
238
    <title>SEE ALSO</title>
 
239
    <para>
 
240
      <citerefentry><refentrytitle>intro</refentrytitle>
 
241
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
242
      <citerefentry><refentrytitle>gnutls_priority_init</refentrytitle
 
243
      ><manvolnum>3</manvolnum></citerefentry>,
 
244
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
245
      <manvolnum>8</manvolnum></citerefentry>,
 
246
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
 
247
      <manvolnum>5</manvolnum></citerefentry>
 
248
    </para>
 
249
    
 
250
    <variablelist>
 
251
      <varlistentry>
 
252
        <term>
 
253
          RFC 4291: <citetitle>IP Version 6 Addressing
 
254
          Architecture</citetitle>
 
255
        </term>
 
256
        <listitem>
 
257
          <variablelist>
 
258
            <varlistentry>
 
259
              <term>Section 2.2: <citetitle>Text Representation of
 
260
              Addresses</citetitle></term>
 
261
              <listitem><para/></listitem>
 
262
            </varlistentry>
 
263
            <varlistentry>
 
264
              <term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6
 
265
              Address</citetitle></term>
 
266
              <listitem><para/></listitem>
 
267
            </varlistentry>
 
268
            <varlistentry>
 
269
            <term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast
 
270
            Addresses</citetitle></term>
 
271
            <listitem>
 
272
              <para>
 
273
                The clients use IPv6 link-local addresses, which are
 
274
                immediately usable since a link-local addresses is
 
275
                automatically assigned to a network interface when it
 
276
                is brought up.
 
277
              </para>
 
278
            </listitem>
 
279
            </varlistentry>
 
280
          </variablelist>
 
281
        </listitem>
 
282
      </varlistentry>
 
283
      <varlistentry>
 
284
        <term>
 
285
          <ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
 
286
        </term>
 
287
        <listitem>
 
288
          <para>
 
289
            Zeroconf is the network protocol standard used by clients
 
290
            for finding the Mandos server on the local network.
 
291
          </para>
 
292
        </listitem>
 
293
      </varlistentry>
 
294
    </variablelist>
 
295
  </refsect1>
198
296
</refentry>
 
297
<!-- Local Variables: -->
 
298
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
 
299
<!-- time-stamp-end: "[\"']>" -->
 
300
<!-- time-stamp-format: "%:y-%02m-%02d" -->
 
301
<!-- End: -->