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

  • Committer: Teddy Hogeborn
  • Date: 2010-09-25 19:55:17 UTC
  • Revision ID: teddy@fukt.bsnet.se-20100925195517-u0qfi01huxl72f75
* mandos (Client.runtime_expansions): New attribute containing the
                                      allowed runtime expansions.

* mandos-clients.conf.xml (OPTIONS): Reordered alphabetically.

* mandos-ctl: Bug fix: print timeout and interval values pretty again.

* mandos-ctl.xml (EXAMPLE): Added more examples.

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 "2008-10-07">
 
6
<!ENTITY TIMESTAMP "2010-09-25">
7
7
<!ENTITY % common SYSTEM "common.ent">
8
8
%common;
9
9
]>
33
33
    </authorgroup>
34
34
    <copyright>
35
35
      <year>2008</year>
 
36
      <year>2009</year>
36
37
      <holder>Teddy Hogeborn</holder>
37
38
      <holder>Björn Påhlsson</holder>
38
39
    </copyright>
62
63
      ><refentrytitle>mandos</refentrytitle>
63
64
      <manvolnum>8</manvolnum></citerefentry>, read by it at startup.
64
65
      The file needs to list all clients that should be able to use
65
 
      the service.  All clients listed will be regarded as valid, even
66
 
      if a client was declared invalid in a previous run of the
67
 
      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.
68
68
    </para>
69
69
    <para>
70
70
      The format starts with a <literal>[<replaceable>section
100
100
    <variablelist>
101
101
      
102
102
      <varlistentry>
103
 
        <term><option>timeout<literal> = </literal><replaceable
104
 
        >TIME</replaceable></option></term>
105
 
        <listitem>
106
 
          <para>
107
 
            This option is <emphasis>optional</emphasis>.
108
 
          </para>
109
 
          <para>
110
 
            The timeout is how long the server will wait for a
111
 
            successful checker run until a client is considered
112
 
            invalid - that is, ineligible to get the data this server
113
 
            holds.  By default Mandos will use 1 hour.
114
 
          </para>
115
 
          <para>
116
 
            The <replaceable>TIME</replaceable> is specified as a
117
 
            space-separated number of values, each of which is a
118
 
            number and a one-character suffix.  The suffix must be one
119
 
            of <quote>d</quote>, <quote>s</quote>, <quote>m</quote>,
120
 
            <quote>h</quote>, and <quote>w</quote> for days, seconds,
121
 
            minutes, hours, and weeks, respectively.  The values are
122
 
            added together to give the total time value, so all of
123
 
            <quote><literal>330s</literal></quote>,
124
 
            <quote><literal>110s 110s 110s</literal></quote>, and
125
 
            <quote><literal>5m 30s</literal></quote> will give a value
126
 
            of five minutes and thirty seconds.
127
 
          </para>
128
 
        </listitem>
129
 
      </varlistentry>
130
 
      
131
 
      <varlistentry>
132
 
        <term><option>interval<literal> = </literal><replaceable
133
 
        >TIME</replaceable></option></term>
134
 
        <listitem>
135
 
          <para>
136
 
            This option is <emphasis>optional</emphasis>.
137
 
          </para>
138
 
          <para>
139
 
            How often to run the checker to confirm that a client is
140
 
            still up.  <emphasis>Note:</emphasis> a new checker will
141
 
            not be started if an old one is still running.  The server
142
 
            will wait for a checker to complete until the above
143
 
            <quote><varname>timeout</varname></quote> occurs, at which
144
 
            time the client will be marked invalid, and any running
145
 
            checker killed.  The default interval is 5 minutes.
146
 
          </para>
147
 
          <para>
148
 
            The format of <replaceable>TIME</replaceable> is the same
149
 
            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>.
150
150
          </para>
151
151
        </listitem>
152
152
      </varlistentry>
169
169
            <varname>PATH</varname> will be searched.  The default
170
170
            value for the checker command is <quote><literal
171
171
            ><command>fping</command> <option>-q</option> <option
172
 
            >--</option> %(host)s</literal></quote>.
 
172
            >--</option> %%(host)s</literal></quote>.
173
173
          </para>
174
174
          <para>
175
175
            In addition to normal start time expansion, this option
196
196
      </varlistentry>
197
197
      
198
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>
199
263
        <term><option>secret<literal> = </literal><replaceable
200
264
        >BASE64_ENCODED_DATA</replaceable></option></term>
201
265
        <listitem>
226
290
      </varlistentry>
227
291
      
228
292
      <varlistentry>
229
 
        <term><option>secfile<literal> = </literal><replaceable
230
 
        >FILENAME</replaceable></option></term>
231
 
        <listitem>
232
 
          <para>
233
 
            This option is only used if <option>secret</option> is not
234
 
            specified, in which case this option is
235
 
            <emphasis>required</emphasis>.
236
 
          </para>
237
 
          <para>
238
 
            Similar to the <option>secret</option>, except the secret
239
 
            data is in an external file.  The contents of the file
240
 
            should <emphasis>not</emphasis> be base64-encoded, but
241
 
            will be sent to clients verbatim.
242
 
          </para>
243
 
          <para>
244
 
            File names of the form <filename>~user/foo/bar</filename>
245
 
            and <filename>$<envar>ENVVAR</envar>/foo/bar</filename>
246
 
            are supported.
247
 
          </para>
248
 
        </listitem>
249
 
      </varlistentry>
250
 
      
251
 
      <varlistentry>
252
 
        <term><option><literal>host = </literal><replaceable
253
 
        >STRING</replaceable></option></term>
254
 
        <listitem>
255
 
          <para>
256
 
            This option is <emphasis>optional</emphasis>, but highly
257
 
            <emphasis>recommended</emphasis> unless the
258
 
            <option>checker</option> option is modified to a
259
 
            non-standard value without <quote>%(host)s</quote> in it.
260
 
          </para>
261
 
          <para>
262
 
            Host name for this client.  This is not used by the server
263
 
            directly, but can be, and is by default, used by the
264
 
            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.
265
317
          </para>
266
318
        </listitem>
267
319
      </varlistentry>
350
402
[DEFAULT]
351
403
timeout = 1h
352
404
interval = 5m
353
 
checker = fping -q -- %(host)s
 
405
checker = fping -q -- %%(host)s
354
406
 
355
407
# Client "foo"
356
408
[foo]
379
431
fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27
380
432
secfile = /etc/mandos/bar-secret
381
433
timeout = 15m
 
434
approved_by_default = False
 
435
approval_delay = 30s
382
436
      </programlisting>
383
437
    </informalexample>
384
438
  </refsect1>