/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: 2009-10-24 19:17:52 UTC
  • Revision ID: teddy@fukt.bsnet.se-20091024191752-7g6xlf6wpp2pdexb
Convert some programs to use the exit codes from <sysexits.h>.  Change
all programs using the "argp" parsing functions to use them correctly;
checking return value, using argp_error() to report parse errors etc.

* plugin-runner.c: Use <sysexits.h> exit codes.  Always use fallback,
                   even on option errors, except for "--help", etc.
  (getplugin): Make sure "errno" is set correctly on return.
  (main): Declare our own "--help", "--usage", and "--version"
          options which do not cause the fallback to be invoked.
          In all other options, use fallback on any error.
  (parse_opt, parse_opt_config_file): Reset errno at start and return
                                      errno.  No need to check "arg"
                                      for NULL.  New "--help",
                                      "--usage", and "--version"
                                      options.
  (parse_opt): Accept empty string as global option.  Do not print
               errors which will be detected and reported later.  Do
               "argp_error()" on parse error or empty plugin names.
* plugins.d/mandos-client.c: Use <sysexits.h> exit codes.  Do not
                             return successful exit code on "--help",
                             etc. since this would give the wrong
                             message to "plugin-runner".
  (main): Declare our own "--help", "--usage", and "--version"
          options which do not return a successful exit code.
  (parse_opt): Reset errno at start and return errno.  Do
               "argp_error()" on parse errors.  New "--help",
               "--usage", and "--version" options.
* plugins.d/password-prompt.c: Use exit codes from <sysexits.h>.  Do
                               not return successful exit code on
                               "--help", etc. since this would give
                               the wrong message to "plugin-runner".
  (main): Declare our own "--help", "--usage", and "--version" options
          which do not return a successful exit code.  Do
          close(STDOUT_FILENO) after writing to check its return code.
  (parse_opt): Reset errno at start and return errno.

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-clients.conf">
6
5
<!ENTITY CONFPATH "<filename>/etc/mandos/clients.conf</filename>">
7
 
<!ENTITY TIMESTAMP "2008-08-30">
 
6
<!ENTITY TIMESTAMP "2009-09-17">
 
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
13
    <title>Mandos Manual</title>
13
14
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
14
15
    <productname>Mandos</productname>
15
 
    <productnumber>&VERSION;</productnumber>
 
16
    <productnumber>&version;</productnumber>
16
17
    <date>&TIMESTAMP;</date>
17
18
    <authorgroup>
18
19
      <author>
32
33
    </authorgroup>
33
34
    <copyright>
34
35
      <year>2008</year>
 
36
      <year>2009</year>
35
37
      <holder>Teddy Hogeborn</holder>
36
38
      <holder>Björn Påhlsson</holder>
37
39
    </copyright>
38
 
    <legalnotice>
39
 
      <para>
40
 
        This manual page is free software: you can redistribute it
41
 
        and/or modify it under the terms of the GNU General Public
42
 
        License as published by the Free Software Foundation,
43
 
        either version 3 of the License, or (at your option) any
44
 
        later version.
45
 
      </para>
46
 
 
47
 
      <para>
48
 
        This manual page is distributed in the hope that it will
49
 
        be useful, but WITHOUT ANY WARRANTY; without even the
50
 
        implied warranty of MERCHANTABILITY or FITNESS FOR A
51
 
        PARTICULAR PURPOSE.  See the GNU General Public License
52
 
        for more details.
53
 
      </para>
54
 
 
55
 
      <para>
56
 
        You should have received a copy of the GNU General Public
57
 
        License along with this program; If not, see
58
 
        <ulink url="http://www.gnu.org/licenses/"/>.
59
 
      </para>
60
 
    </legalnotice>
 
40
    <xi:include href="legalnotice.xml"/>
61
41
  </refentryinfo>
62
 
 
 
42
  
63
43
  <refmeta>
64
44
    <refentrytitle>&CONFNAME;</refentrytitle>
65
45
    <manvolnum>5</manvolnum>
71
51
      Configuration file for the Mandos server
72
52
    </refpurpose>
73
53
  </refnamediv>
74
 
 
 
54
  
75
55
  <refsynopsisdiv>
76
56
    <synopsis>&CONFPATH;</synopsis>
77
57
  </refsynopsisdiv>
78
 
 
 
58
  
79
59
  <refsect1 id="description">
80
60
    <title>DESCRIPTION</title>
81
61
    <para>
115
95
      start time expansion, see <xref linkend="expansion"/>.
116
96
    </para>
117
97
    <para>
118
 
      Uknown options are ignored.  The used options are as follows:
 
98
      Unknown options are ignored.  The used options are as follows:
119
99
    </para>
120
 
 
 
100
    
121
101
    <variablelist>
122
 
 
 
102
      
123
103
      <varlistentry>
124
104
        <term><option>timeout<literal> = </literal><replaceable
125
105
        >TIME</replaceable></option></term>
126
106
        <listitem>
127
107
          <para>
128
 
            The timeout is how long the server will wait for a
129
 
            successful checker run until a client is considered
130
 
            invalid - that is, ineligible to get the data this server
131
 
            holds.  By default Mandos will use 1 hour.
 
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.
132
116
          </para>
133
117
          <para>
134
118
            The <replaceable>TIME</replaceable> is specified as a
145
129
          </para>
146
130
        </listitem>
147
131
      </varlistentry>
148
 
 
 
132
      
149
133
      <varlistentry>
150
134
        <term><option>interval<literal> = </literal><replaceable
151
135
        >TIME</replaceable></option></term>
152
136
        <listitem>
153
137
          <para>
 
138
            This option is <emphasis>optional</emphasis>.
 
139
          </para>
 
140
          <para>
154
141
            How often to run the checker to confirm that a client is
155
142
            still up.  <emphasis>Note:</emphasis> a new checker will
156
143
            not be started if an old one is still running.  The server
165
152
          </para>
166
153
        </listitem>
167
154
      </varlistentry>
168
 
 
 
155
      
169
156
      <varlistentry>
170
157
        <term><option>checker<literal> = </literal><replaceable
171
158
        >COMMAND</replaceable></option></term>
172
159
        <listitem>
173
160
          <para>
 
161
            This option is <emphasis>optional</emphasis>.
 
162
          </para>
 
163
          <para>
174
164
            This option allows you to override the default shell
175
165
            command that the server will use to check if the client is
176
166
            still up.  Any output of the command will be ignored, only
181
171
            <varname>PATH</varname> will be searched.  The default
182
172
            value for the checker command is <quote><literal
183
173
            ><command>fping</command> <option>-q</option> <option
184
 
            >--</option> %(host)s</literal></quote>.
 
174
            >--</option> %%(host)s</literal></quote>.
185
175
          </para>
186
176
          <para>
187
177
            In addition to normal start time expansion, this option
196
186
        ><replaceable>HEXSTRING</replaceable></option></term>
197
187
        <listitem>
198
188
          <para>
 
189
            This option is <emphasis>required</emphasis>.
 
190
          </para>
 
191
          <para>
199
192
            This option sets the OpenPGP fingerprint that identifies
200
193
            the public key that clients authenticate themselves with
201
194
            through TLS.  The string needs to be in hexidecimal form,
209
202
        >BASE64_ENCODED_DATA</replaceable></option></term>
210
203
        <listitem>
211
204
          <para>
 
205
            If this option is not specified, the <option
 
206
            >secfile</option> option is <emphasis>required</emphasis>
 
207
            to be present.
 
208
          </para>
 
209
          <para>
212
210
            If present, this option must be set to a string of
213
211
            base64-encoded binary data.  It will be decoded and sent
214
212
            to the client matching the above
226
224
            lines is that a line beginning with white space adds to
227
225
            the value of the previous line, RFC 822-style.
228
226
          </para>
229
 
          <para>
230
 
            If this option is not specified, the <option
231
 
            >secfile</option> option is used instead, but one of them
232
 
            <emphasis>must</emphasis> be present.
233
 
          </para>
234
227
        </listitem>
235
228
      </varlistentry>
236
 
 
 
229
      
237
230
      <varlistentry>
238
231
        <term><option>secfile<literal> = </literal><replaceable
239
232
        >FILENAME</replaceable></option></term>
240
233
        <listitem>
241
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>
242
240
            Similar to the <option>secret</option>, except the secret
243
241
            data is in an external file.  The contents of the file
244
242
            should <emphasis>not</emphasis> be base64-encoded, but
245
243
            will be sent to clients verbatim.
246
244
          </para>
247
245
          <para>
248
 
            This option is only used, and <emphasis>must</emphasis> be
249
 
            present, if <option>secret</option> is not specified.
 
246
            File names of the form <filename>~user/foo/bar</filename>
 
247
            and <filename>$<envar>ENVVAR</envar>/foo/bar</filename>
 
248
            are supported.
250
249
          </para>
251
250
        </listitem>
252
251
      </varlistentry>
253
 
 
 
252
      
254
253
      <varlistentry>
255
254
        <term><option><literal>host = </literal><replaceable
256
255
        >STRING</replaceable></option></term>
257
256
        <listitem>
258
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>
259
264
            Host name for this client.  This is not used by the server
260
265
            directly, but can be, and is by default, used by the
261
266
            checker.  See the <option>checker</option> option.
316
321
        mode is needed to expose an error of this kind.
317
322
      </para>
318
323
    </refsect2>
319
 
 
 
324
    
320
325
  </refsect1>
321
326
  
322
327
  <refsect1 id="files">
347
352
[DEFAULT]
348
353
timeout = 1h
349
354
interval = 5m
350
 
checker = fping -q -- %(host)s
 
355
checker = fping -q -- %%(host)s
351
356
 
352
357
# Client "foo"
353
358
[foo]
376
381
fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27
377
382
secfile = /etc/mandos/bar-secret
378
383
timeout = 15m
379
 
 
380
384
      </programlisting>
381
385
    </informalexample>
382
386
  </refsect1>