/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-clients.conf.xml

* mandos (ClientDBus.__init__): Bug fix: Translate "-" in client names
                                to "_" in D-Bus object paths.
  (MandosServer.handle_ipc): Bug fix: Send only address string to
                             D-Bus signal, not whole tuple.

* mandos-ctl: New options "--approve-by-default", "--deny-by-default",
              "--approval-delay", and "--approval-duration".
* mandos-ctl.xml (SYNOPSIS, OPTIONS): Document new options.

* mandos-monitor (MandosClientWidget.update): Fix spelling.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos-clients.conf.xml
3
3
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
4
<!ENTITY CONFNAME "mandos-clients.conf">
5
5
<!ENTITY CONFPATH "<filename>/etc/mandos/clients.conf</filename>">
6
 
<!ENTITY TIMESTAMP "2009-09-17">
 
6
<!ENTITY TIMESTAMP "2010-09-25">
7
7
<!ENTITY % common SYSTEM "common.ent">
8
8
%common;
9
9
]>
63
63
      ><refentrytitle>mandos</refentrytitle>
64
64
      <manvolnum>8</manvolnum></citerefentry>, read by it at startup.
65
65
      The file needs to list all clients that should be able to use
66
 
      the service.  All clients listed will be regarded as valid, even
67
 
      if a client was declared invalid in a previous run of the
68
 
      server.
 
66
      the service.  All clients listed will be regarded as enabled,
 
67
      even if a client was disabled in a previous run of the server.
69
68
    </para>
70
69
    <para>
71
70
      The format starts with a <literal>[<replaceable>section
101
100
    <variablelist>
102
101
      
103
102
      <varlistentry>
104
 
        <term><option>timeout<literal> = </literal><replaceable
105
 
        >TIME</replaceable></option></term>
106
 
        <listitem>
107
 
          <para>
108
 
            This option is <emphasis>optional</emphasis>.
109
 
          </para>
110
 
          <para>
111
 
            The timeout is how long the server will wait (for either a
112
 
            successful checker run or a client receiving its secret)
113
 
            until a client is considered invalid - that is, ineligible
114
 
            to get the data this server holds.  By default Mandos will
115
 
            use 1 hour.
116
 
          </para>
117
 
          <para>
118
 
            The <replaceable>TIME</replaceable> is specified as a
119
 
            space-separated number of values, each of which is a
120
 
            number and a one-character suffix.  The suffix must be one
121
 
            of <quote>d</quote>, <quote>s</quote>, <quote>m</quote>,
122
 
            <quote>h</quote>, and <quote>w</quote> for days, seconds,
123
 
            minutes, hours, and weeks, respectively.  The values are
124
 
            added together to give the total time value, so all of
125
 
            <quote><literal>330s</literal></quote>,
126
 
            <quote><literal>110s 110s 110s</literal></quote>, and
127
 
            <quote><literal>5m 30s</literal></quote> will give a value
128
 
            of five minutes and thirty seconds.
129
 
          </para>
130
 
        </listitem>
131
 
      </varlistentry>
132
 
      
133
 
      <varlistentry>
134
 
        <term><option>interval<literal> = </literal><replaceable
135
 
        >TIME</replaceable></option></term>
136
 
        <listitem>
137
 
          <para>
138
 
            This option is <emphasis>optional</emphasis>.
139
 
          </para>
140
 
          <para>
141
 
            How often to run the checker to confirm that a client is
142
 
            still up.  <emphasis>Note:</emphasis> a new checker will
143
 
            not be started if an old one is still running.  The server
144
 
            will wait for a checker to complete until the above
145
 
            <quote><varname>timeout</varname></quote> occurs, at which
146
 
            time the client will be marked invalid, and any running
147
 
            checker killed.  The default interval is 5 minutes.
148
 
          </para>
149
 
          <para>
150
 
            The format of <replaceable>TIME</replaceable> is the same
151
 
            as for <varname>timeout</varname> above.
 
103
        <term><option>approval_delay<literal> = </literal><replaceable
 
104
        >TIME</replaceable></option></term>
 
105
        <listitem>
 
106
          <para>
 
107
            This option is <emphasis>optional</emphasis>.
 
108
          </para>
 
109
          <para>
 
110
            How long to wait for external approval before resorting to
 
111
            use the <option>approved_by_default</option> value.  The
 
112
            default is <quote>0s</quote>, i.e. not to wait.
 
113
          </para>
 
114
          <para>
 
115
            The format of <replaceable>TIME</replaceable> is the same
 
116
            as for <varname>timeout</varname> below.
 
117
          </para>
 
118
        </listitem>
 
119
      </varlistentry>
 
120
      
 
121
      <varlistentry>
 
122
        <term><option>approval_duration<literal> = </literal
 
123
        ><replaceable>TIME</replaceable></option></term>
 
124
        <listitem>
 
125
          <para>
 
126
            This option is <emphasis>optional</emphasis>.
 
127
          </para>
 
128
          <para>
 
129
            How long an external approval lasts.  The default is 1
 
130
            second.
 
131
          </para>
 
132
          <para>
 
133
            The format of <replaceable>TIME</replaceable> is the same
 
134
            as for <varname>timeout</varname> below.
 
135
          </para>
 
136
        </listitem>
 
137
      </varlistentry>
 
138
      
 
139
      <varlistentry>
 
140
        <term><option>approved_by_default<literal> = </literal
 
141
          >{ <literal >1</literal> | <literal>yes</literal> | <literal
 
142
          >true</literal> | <literal>on</literal> | <literal
 
143
          >0</literal> | <literal>no</literal> | <literal
 
144
          >false</literal> | <literal>off</literal> }</option></term>
 
145
        <listitem>
 
146
          <para>
 
147
            Whether to approve a client by default after
 
148
            the <option>approval_delay</option>.  The default
 
149
            is <quote>True</quote>.
152
150
          </para>
153
151
        </listitem>
154
152
      </varlistentry>
198
196
      </varlistentry>
199
197
      
200
198
      <varlistentry>
 
199
        <term><option><literal>host = </literal><replaceable
 
200
        >STRING</replaceable></option></term>
 
201
        <listitem>
 
202
          <para>
 
203
            This option is <emphasis>optional</emphasis>, but highly
 
204
            <emphasis>recommended</emphasis> unless the
 
205
            <option>checker</option> option is modified to a
 
206
            non-standard value without <quote>%%(host)s</quote> in it.
 
207
          </para>
 
208
          <para>
 
209
            Host name for this client.  This is not used by the server
 
210
            directly, but can be, and is by default, used by the
 
211
            checker.  See the <option>checker</option> option.
 
212
          </para>
 
213
        </listitem>
 
214
      </varlistentry>
 
215
      
 
216
      <varlistentry>
 
217
        <term><option>interval<literal> = </literal><replaceable
 
218
        >TIME</replaceable></option></term>
 
219
        <listitem>
 
220
          <para>
 
221
            This option is <emphasis>optional</emphasis>.
 
222
          </para>
 
223
          <para>
 
224
            How often to run the checker to confirm that a client is
 
225
            still up.  <emphasis>Note:</emphasis> a new checker will
 
226
            not be started if an old one is still running.  The server
 
227
            will wait for a checker to complete until the below
 
228
            <quote><varname>timeout</varname></quote> occurs, at which
 
229
            time the client will be disabled, and any running checker
 
230
            killed.  The default interval is 5 minutes.
 
231
          </para>
 
232
          <para>
 
233
            The format of <replaceable>TIME</replaceable> is the same
 
234
            as for <varname>timeout</varname> below.
 
235
          </para>
 
236
        </listitem>
 
237
      </varlistentry>
 
238
      
 
239
      <varlistentry>
 
240
        <term><option>secfile<literal> = </literal><replaceable
 
241
        >FILENAME</replaceable></option></term>
 
242
        <listitem>
 
243
          <para>
 
244
            This option is only used if <option>secret</option> is not
 
245
            specified, in which case this option is
 
246
            <emphasis>required</emphasis>.
 
247
          </para>
 
248
          <para>
 
249
            Similar to the <option>secret</option>, except the secret
 
250
            data is in an external file.  The contents of the file
 
251
            should <emphasis>not</emphasis> be base64-encoded, but
 
252
            will be sent to clients verbatim.
 
253
          </para>
 
254
          <para>
 
255
            File names of the form <filename>~user/foo/bar</filename>
 
256
            and <filename>$<envar>ENVVAR</envar>/foo/bar</filename>
 
257
            are supported.
 
258
          </para>
 
259
        </listitem>
 
260
      </varlistentry>
 
261
      
 
262
      <varlistentry>
201
263
        <term><option>secret<literal> = </literal><replaceable
202
264
        >BASE64_ENCODED_DATA</replaceable></option></term>
203
265
        <listitem>
228
290
      </varlistentry>
229
291
      
230
292
      <varlistentry>
231
 
        <term><option>secfile<literal> = </literal><replaceable
232
 
        >FILENAME</replaceable></option></term>
233
 
        <listitem>
234
 
          <para>
235
 
            This option is only used if <option>secret</option> is not
236
 
            specified, in which case this option is
237
 
            <emphasis>required</emphasis>.
238
 
          </para>
239
 
          <para>
240
 
            Similar to the <option>secret</option>, except the secret
241
 
            data is in an external file.  The contents of the file
242
 
            should <emphasis>not</emphasis> be base64-encoded, but
243
 
            will be sent to clients verbatim.
244
 
          </para>
245
 
          <para>
246
 
            File names of the form <filename>~user/foo/bar</filename>
247
 
            and <filename>$<envar>ENVVAR</envar>/foo/bar</filename>
248
 
            are supported.
249
 
          </para>
250
 
        </listitem>
251
 
      </varlistentry>
252
 
      
253
 
      <varlistentry>
254
 
        <term><option><literal>host = </literal><replaceable
255
 
        >STRING</replaceable></option></term>
256
 
        <listitem>
257
 
          <para>
258
 
            This option is <emphasis>optional</emphasis>, but highly
259
 
            <emphasis>recommended</emphasis> unless the
260
 
            <option>checker</option> option is modified to a
261
 
            non-standard value without <quote>%%(host)s</quote> in it.
262
 
          </para>
263
 
          <para>
264
 
            Host name for this client.  This is not used by the server
265
 
            directly, but can be, and is by default, used by the
266
 
            checker.  See the <option>checker</option> option.
 
293
        <term><option>timeout<literal> = </literal><replaceable
 
294
        >TIME</replaceable></option></term>
 
295
        <listitem>
 
296
          <para>
 
297
            This option is <emphasis>optional</emphasis>.
 
298
          </para>
 
299
          <para>
 
300
            The timeout is how long the server will wait (for either a
 
301
            successful checker run or a client receiving its secret)
 
302
            until a client is disabled and not allowed to get the data
 
303
            this server holds.  By default Mandos will use 1 hour.
 
304
          </para>
 
305
          <para>
 
306
            The <replaceable>TIME</replaceable> is specified as a
 
307
            space-separated number of values, each of which is a
 
308
            number and a one-character suffix.  The suffix must be one
 
309
            of <quote>d</quote>, <quote>s</quote>, <quote>m</quote>,
 
310
            <quote>h</quote>, and <quote>w</quote> for days, seconds,
 
311
            minutes, hours, and weeks, respectively.  The values are
 
312
            added together to give the total time value, so all of
 
313
            <quote><literal>330s</literal></quote>,
 
314
            <quote><literal>110s 110s 110s</literal></quote>, and
 
315
            <quote><literal>5m 30s</literal></quote> will give a value
 
316
            of five minutes and thirty seconds.
267
317
          </para>
268
318
        </listitem>
269
319
      </varlistentry>
381
431
fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27
382
432
secfile = /etc/mandos/bar-secret
383
433
timeout = 15m
 
434
approved_by_default = False
 
435
approval_delay = 30s
384
436
      </programlisting>
385
437
    </informalexample>
386
438
  </refsect1>