2 <title>User service daemon and client specification - Service-side configuration</title>
3 <link rev=made href="mailto:ian@davenant.greenend.org.uk">
6 User service daemon and client specification - chapter 4<br>
7 Service-side configuration
10 Which services may be run by whom and under what conditions is
11 controlled by configuration files.<P>
13 The daemon will read these files in order. Certain directives in the
14 files modify the daemon's execution settings for invoking the service,
15 for example allowing certain file descriptors to be specified by the
16 client or specifying which program to execute to provide the service.<P>
18 The <em>last</em> instance of each such setting will take effect. The
19 directives which specify which program to execute will not stop the
20 configuration file from being read; they will be remembered and will
21 only take effect if they are not overridden by a later directive.<P>
23 The daemon will first read <code>/etc/userv/system.default</code>. Then, by
24 default (this behaviour may be modified), it will read a per-user file
25 <code>~/.userv/rc</code>, if it exists and the service user's shell is in
26 <code>/etc/shells</code>. Finally it will read
27 <code>/etc/userv/system.override</code>.<P>
29 When it has read all of these files it will act according to the
30 currently values of of the execution settings.
33 4.1 Configuration file syntax
36 The configuration file is a series of directives, usually one per
37 line. The portion of a line following a hash character <code>#</code> is
38 taken as a comment and ignored. Each directive consists of a series
39 of tokens separated by linear whitespace (spaces and tabs); tokens may
40 be words consisting of non-space characters, or, where a string is
41 required, a string in double quotes. Double-quoted strings may
42 contain the following backslash escapes:
45 <dt><code>\n</code><dd>newline<dt><code>\t</code><dd>tab<dt><code>\r</code><dd>carriage return<dt><code>\</code><var>OOO</var><code></code><dd>character whose octal code is <var>OOO</var><dt><code>\x</code><var>XX</var><code></code><dd>character whose hex code is <var>XX</var><dt><code>\</code><var>punctuation</var><code></code><dd>literal punctuation character (eg <code>\\</code>, <code>\"</code>)<dt><code>\</code><var>newline</var><code></code> (ie, backslash at end of line)<dd>string continues on next line</dl>
48 Relative pathnames in directives are relative to the service program's
49 current directory (usually the service user's home directory).
50 Pathnames starting with the two characters <code>~/</code> are taken to be
51 relative to the service user's home directory.
53 <h2><A name="s-directives">
54 4.2 Configuration file directives
57 <h3><A name="s-dirs-immediate">
58 4.2.1 Immediate directives
61 The following directives take effect immediately:
64 <dt><code>cd </code><var>pathname</var><code></code><dd>Change directory in the service program. <kbd>cd</kbd> is cumulative. It
65 is an error if the directory cannot be changed to.<P>
67 <kbd>cd</kbd> should not be used between <kbd>execute-from-directory</kbd> and
68 the invocation of the service program, as the test for the
69 availability of the service program would be done with the old current
70 directory and the actual execution with the new (probably causing an
72 <p><dt><code>eof</code><dd>Stop reading the configuration file in question, as if end of file had
73 been reached. Any control constructs (<kbd>if</kbd>, <kbd>catch-quit</kbd> or
74 <kbd>errors-push</kbd>) which were started in that file will be considered
75 finished. Parsing will continue in the file which caused the file
76 containing the <kbd>eof</kbd> to be read.
77 <p><dt><code>quit</code><dd>Stop reading configuration files and act immediately on the current
78 settings. The behaviour of <kbd>quit</kbd> is subject to the
79 <kbd>catch-quit</kbd> control construct.
80 <p><dt><code>include </code><var>filename</var><code></code><dt><code>include-ifexist </code><var>filename</var><code></code><dd>Read the configuration file <var>filename</var>, and then return to this
81 file and continue parsing it with the next directive. It is an error
82 if the file cannot be opened and read, unless <kbd>include-ifexist</kbd>
83 is used and the file does not exist, in which case the directive is
85 <p><dt><code>include-lookup </code><var>parameter</var><code> </code><var>directory</var><code></code><dt><code>include-lookup-all </code><var>parameter</var><code> </code><var>directory</var><code></code><dd>Read the configuration file in <var>directory</var> whose name is the value
86 of <var>parameter</var> (see the description of <kbd>if</kbd>, <A href="#s-dirs-control">Control structure directives, subsection 4.2.3</A>). If <var>parameter</var> has several values they will
87 be tried in order; with <kbd>include-lookup</kbd> this search will stop
88 when one is found, but with <kbd>include-lookup-all</kbd> the search will
89 continue and any files appropriate to other values will be read too.<P>
91 If none of the parameter's values had a corresponding file then the
92 file <code>:default</code> will be read, if it exists. If <var>parameter</var>'s
93 list of values was empty then the file <code>:none</code> will be tried first
94 and read if it exists, otherwise <code>:default</code> will be tried.<P>
96 It is not an error for any of the files (including <code>:default</code>) not
97 to exist, but it is an error if a file exists and cannot be read or if
98 the directory cannot be accessed.
100 A translation will be applied to values before they are used to
101 construct a filename, so that the lookup cannot access dotfiles or
102 files in other directories: values starting with full stops will have
103 a colon prepended (making <code>:.</code>), colons will be doubled, and each
104 slash will be replaced with a colon followed by a hyphen <code>:-</code>. A
105 parameter value which is the empty string will be replaced with
106 <code>:empty</code> (note that this is different from a parameter not having
108 <p><dt><code>include-directory </code><var>directory</var><code></code><dd>Read configuration from all files in directory <var>directory</var> which
109 are plain files whose names consist only of alphanumerics and hyphens
110 and start with an alphanumeric. They will be read in lexical order.
111 It is an error for the directory not to exist or for it or any of the
112 files found not to be read successfully, or for anything with an
113 appropriate name not to be a plain file or a symbolic link to a plain
115 <p><dt><code>error </code><var>text ...</var><code></code><dd>Causes an error whose message includes the descriptive string
116 <var>text</var>. <var>text</var> may consist of several tokens with intervening
117 whitespace. The whitespace will be included in the message as found
118 in the configuration file: all the characters until the end of the
119 line will be included verbatim, unless they are part of a
120 double-quoted string, in which case the usual meaning of the string
121 (i.e., after backslash escape processing) will be used. Comments and
122 linear whitespace at the end of the line (or just before the comment)
123 will still be ignored.
124 <p><dt><code>message </code><var>text ...</var><code></code><dd>Causes a message including the descriptive string <var>text</var> to be
125 delivered as if it were an error message, but does not actually cause
129 <h3><A name="s-dirs-delayed">
130 4.2.2 Directives with delayed effect
133 The following directives have no immediate effect, but are remembered
134 and have an effect on later processing of the configuration files.
137 <dt><code>user-rcfile </code><var>filename</var><code></code><dd>Specifies that the file <var>filename</var> should be read instead of the
138 user's <code>~/.userv/rc</code>. This does <em>not</em> happen immediately;
139 instead, the setting is remembered and used after the
140 <kbd>system.default</kbd> configuration file has been read. This
141 directive has no effect in a user's configuration file or in the
142 <kbd>system.override</kbd> file, as the user's configuration file has
143 already been found and read by then and will not be re-read.
144 <p><dt><code>errors-to-stderr</code><dd>Causes error messages to be delivered to the client's stderr.
145 <p><dt><code>errors-to-file</code> <var>filename</var><dd>Error messages will be written to <var>filename</var>, which will be opened
146 in the context of and with the privileges of the service user.
147 <p><dt><code>errors-to-syslog</code> [<var>facility</var> [<var>level</var>]]<dd>Error messages will be delivered using <kbd>syslog</kbd>. The default
148 <var>facility</var> is <code>user</code>; the default <var>level</var> is <code>error</code>.<p></dl>
151 <h3><A name="s-dirs-control">
152 4.2.3 Control structure directives
155 The following directives are used to create control structures. If
156 the end of the file is encountered before the end of any control
157 structure which was started inside it then that control structure is
158 considered finished. This is not an error.
161 <dt><code>if </code><var>condition</var><code></code><dt><code>elif </code><var>condition</var><code></code><dt><code>else</code><dt><code>fi</code><dd>Lines following <kbd>if</kbd> are interpreted only if the condition is
162 true. Many conditions are properties of parameter values. Most
163 parameters have a single string as a value; however, some may yield
164 zero or several strings, in which case the condition is true if it is
165 true of any of the strings individually. Parameters are described
171 <dt><code>glob </code><var>parameter</var><code> </code><var>glob-pattern</var><code> ...</code><dd>The value of the parameter whose name is given matches one of the glob
172 patterns (anchored at both ends; backslashes can be used to escape
174 <dt><code>range </code><var>parameter</var><code> </code><var>min</var><code> </code><var>max</var><code></code><dd>The value of the parameter is a nonnegative integer and lies within
175 the range specified. <var>min</var> or <var>max</var> may be <code>$</code> to indicate
176 no lower or upper limit, respectively.
177 <dt><code>grep </code><var>parameter</var><code> </code><var>filename</var><code></code><dd>The <var>filename</var> refers to a file one of whose lines is the value of
178 the parameter (leading or trailing whitespace on each line and empty
179 lines in the file are ignored). It is an error for the file not to be
181 <dt><code>! </code><var>condition</var><code></code><dd>The <var>condition</var> is <em>not</em> true.
182 <dt>Conjunctions: <code>&</code> and <code>|</code><dd><pre>( <var>condition</var>
183 & <var>condition</var>
184 & <var>condition</var>
187 is true if all the listed conditions are true; where <code>|</code> is used it
188 is true if any of them is true. Newlines must be used to separate one
189 condition from the next, as shown, and the parentheses are mandatory.
190 These conjunctions do not do lazy evaluation.</dl>
196 <dt><code>service</code><dd>The service name specified when the client was called.
197 <dt><code>calling-user</code><dd>Two strings: the login name of the calling user (determined as for
198 <kbd>USERV_USER</kbd>, above) and the calling uid (represented in
200 <dt><code>calling-group</code><dd>Several strings: the primary and supplementary group names and gids
201 (in decimal) of the calling process. All the group names come first,
202 and then the gids. If the first supplementary group is the same as
203 the primary group then it is elided.
204 <dt><code>calling-user-shell</code><dd>The calling user's shell, as listed in the password entry for the
205 calling login name (as determined for <kbd>USERV_USER</kbd>, above).
206 <dt><code>service-user</code><dd>Two strings: the name of the service user (as specified to the client)
207 and their uid (represented in decimal).
208 <dt><code>service-group</code><dd>Several strings: the primary and supplementary group names and gids
209 (in decimal) of the service user.
210 <dt><code>service-user-shell</code><dd>The service user's shell, as listed in their password entry.
211 <dt><code>u-</code><var>name</var><code></code><dd>The value of the user-defined variable <var>name</var> passed by the caller
212 using the <kbd>--defvar</kbd> command-line option to the client. If the
213 variable was not defined then this parameter is an empty list of
214 strings; in this case any condition which tests it will be false, and
215 <code>include-lookup</code> on it will read the <code>:none</code> file, or
216 <code>:default</code> if <code>:none</code> is not found.
219 <dt><code>errors-push</code> <var>filename</var><dt><code>srorre</code><dd>Stacks the error handling behaviour currently in effect. Any changes
220 to error handling will take effect only between <kbd>errors-push</kbd> and
222 <dt><code>catch-quit</code><dt><code>hctac</code><dd>Any use of <kbd>quit</kbd> inside <kbd>catch-quit</kbd> will merely cause the
223 parsing to continue at <kbd>hctac</kbd> instead. Any control constructs
224 started since the <kbd>catch-quit</kbd> will be considered finished if a
225 <kbd>quit</kbd> is found.<P>
227 If an error occurs inside <kbd>catch-quit</kbd> the execution settings
228 will be reset (as if by the <kbd>reset</kbd> directive) and parsing will
229 likewise continue at <kbd>hctac</kbd>.<P>
231 If a lexical or syntax error is detected in the same configuration
232 file as the <kbd>catch-quit</kbd>, while looking for the <kbd>hctac</kbd>
233 after an error or <kbd>quit</kbd>, that new error will not be caught.
237 <h3><A name="s-dirs-execution">
238 4.2.4 Directives for changing execution settings
241 The following directives modify the execution settings; the server
242 will remember the fact that the directive was encountered and act on
243 it only after all the configuration has been parsed. The <em>last</em>
244 directive which modifies any particuar setting will take effect.
247 <dt><code>reject</code><dd>Reject the request. <kbd>execute</kbd>, <kbd>execute-from-directory</kbd> and
248 <kbd>execute-from-path</kbd> will change this setting.
249 <p><dt><code>execute </code><var>program</var><code> [</code><var>argument</var><code> ...]</code><dd>Execute the program <var>program</var>, with the arguments as specified,
250 followed by any arguments given to the client if
251 <kbd>no-suppress-args</kbd> is in effect. It is an error for the
252 execution to fail when it is attempted (after all the configuration
253 has been parsed). If <var>program</var> does not contain a slash it will
254 be searched for on the service user's path.
255 <p><dt><code>execute-from-directory </code><var>pathname</var><code> [</code><var>argument</var><code> ...]</code><dd>Take all the characters after the last slash of the service name
256 specified when the client was called, and execute that program in the
257 directory named by <var>pathname</var> as if it had been specified for
258 <var>execute</var>. The part of the service name used may contain only
259 alphanumerics and hyphens and must start with an alphanumeric (and it
260 must be non-empty), otherwise it is an error.<P>
262 This directive is ignored if the relevant program does not exist in
263 the directory specified; in this case the program to execute is left
264 at its previous setting (or unset, if it was not set before).<P>
266 It is an error for the test for the existence of the program to fail
267 other than with a `no such file or directory' indication. It is also
268 an error for the execution to fail if and when it is attempted (after
269 all the configuration has been parsed).
270 <p><dt><code>execute-from-path</code><dd><var>service</var> is interpreted as a program on the default <kbd>PATH</kbd>
271 (or as a pathname of an executable, if it contains a <code>/</code>). This
272 directive is <em>very dangerous</em>, and is only provided to make the
273 <kbd>--override</kbd> options effective. It should not normally be used.
274 It is an error for the execution to fail when it is attempted (after
275 all the configuration has been parsed).
276 <p><dt><code>execute-builtin </code><var>service-name</var><code> </code><var>service-arguments</var><code></code><dd>Executes the builtin service <var>service-name</var>. These builtin
277 services display information about the server and/or the request, and
278 ignore any arguments passed from the service side except possibly to
279 print them as part of their output. They write their results to their
280 standard output (i.e., wherever file descriptor 1 is directed). The
281 builtin services are:
284 <dt><code>execute</code><dd>Displays the execution settings, defined variables,
285 arguments, etc. with which the builtin service was invoked.
286 <dt><code>environment</code><dd>Displays the environment variable settings with which the builtin
288 <dt><code>parameter </code><var>parameter</var><code></code><dd>Displays the values of the service configuration language parameter
290 <dt><code>version</code><dd>Displays the version string and compilation details of the uservd
292 <dt><code>reset</code><dd>Displays the default reset configuration (evaluated when <kbd>reset</kbd>
293 is found in a configuration file, or when an error is caught by
294 <kbd>catch-quit</kbd>).
295 <dt><code>toplevel</code><dd>Displays the top-level default configuration (the configuration data,
296 evaluated by the server, which calls all the other configuration
298 <dt><code>override</code><dd>Displays the top-level override configuration (the configuration data,
299 evaluated by the server, which causes all the other configuration data
301 <dt><code>help</code><dd>Displays a list of the understood builtin service names and arguments.</dl>
304 In the future other builtin services may be defined which do more than
305 just print information.
306 <dt><code>set-environment</code><dt><code>no-set-environment</code><dd>Runs <code>/etc/environment</code> to set the service user's environment.
307 This adds the overhead of invoking a shell, but doesn't cause any
308 shell (de)mangling of the service's arguments. This is achieved by
310 <pre>.../program arg arg arg ...</pre>
312 <pre>/bin/sh -c '. /etc/environment; exec "$@"' - .../program arg arg arg ...</pre>
313 <kbd>no-set-environment</kbd> cancels the effect of
314 <kbd>set-environment</kbd>.
315 <dt><code>no-suppress-args</code><dt><code>suppress-args</code><dd>Include any arguments given to the client as arguments to the program
316 invoked as a result of an <kbd>execute</kbd>,
317 <kbd>execute-from-directory</kbd> or <kbd>execute-from-path</kbd> directive.
318 <kbd>suppress-args</kbd> undoes the effect of <kbd>no-suppress-args</kbd>.
319 <dt><code>require-fd </code><var>fd-range</var><code> read|write</code><dd>Insist that the filedescriptor(s) be opened for reading resp. writing.
320 It is an error if any descriptor marked as required when the service
321 is about to be invoked (after the configuration has been parsed) was
322 not specified when the client was invoked. Each file descriptor has a
323 separate setting, and the last one of <kbd>require-fd</kbd>,
324 <kbd>allow-fd</kbd>, <kbd>ignore-fd</kbd>, <kbd>null-fd</kbd> or <kbd>reject-fd</kbd>
325 which affected a particular file descriptor will take effect.<P>
327 <var>fd-range</var> may be a single number, two numbers separated by a
328 hyphen, or one number followed by a hyphen (indicating all descriptors
329 from that number onwards). It may also be one of the words
330 <code>stdin</code>, <code>stdout</code> or <code>stderr</code>. Open-ended file descriptor
331 rangers are allowed only with <kbd>reject-fd</kbd> and <kbd>ignore-fd</kbd>,
332 as otherwise the service program would find itself with a very large
333 number of file descriptors open.<P>
335 When the configuration has been parsed, and before the service is
336 about to be executed, stderr (fd 2) must be required or allowed
337 (<kbd>require-fd</kbd> or <kbd>allow-fd</kbd>) for writing; this is so that
338 the error message printed by the server's child process if it cannot
339 <kbd>exec</kbd> the service program is not lost.
340 <dt><code>allow-fd </code><var>fd-range</var><code> [read|write]</code><dd>Allow the descriptor(s) to be opened for reading resp. writing, or
341 either if neither <code>read</code> nor <code>write</code> is specified. If a
342 particular descriptor not specified by the client then it will be open
343 onto <code>/dev/null</code> (for reading, writing, or both, depending on
344 whether <code>read</code>, <code>write</code> or neither was specified).
345 <dt><code>null-fd </code><var>fd-range</var><code> [read|write]</code><dd>Specify that the descriptor(s) be opened onto <kbd>/dev/null</kbd> for
346 reading resp. writing, or both if neither <code>read</code> nor <code>write</code>
347 is specified. Any specification of these file descriptors by the
348 client will be silently ignored; the client will see its ends of the
349 descriptors being closed immediately.
350 <dt><code>reject-fd </code><var>fd-range</var><code></code><dd>Do not allow the descriptor(s) to be specified by the client. It is
351 an error if any descriptor(s) marked for rejection are specified when
352 the service is about to be invoked (after the configuration has been
354 <dt><code>ignore-fd </code><var>fd-range</var><code></code><dd>Silently ignore any specification by the client of those
355 descriptor(s). The pipes corresponding to these descriptors will be
356 closed just before the service is invoked.
357 <dt><code>disconnect-hup</code><dt><code>no-disconnect-hup</code><dd>Causes the service's process group to get a <kbd>SIGHUP</kbd> if the
358 client disconnects before the main service process terminates.
359 <kbd>no-disconnect-hup</kbd> cancels <kbd>disconnect-hup</kbd>.<P>
361 If one of the reading descriptors specified when the client is called
362 gets a read error, or if the service is disconnected for some other
363 reason, then the <kbd>SIGHUP</kbd> will be delivered <em>before</em> the
364 writing end(s) of the service's reading pipe(s) are closed, so that
365 the client can distinguish disconnection from reading EOF on a pipe.
366 <dt><code>reset</code><dd>Resets the execution settings to the default. This is equivalent to:
378 If no <kbd>execute</kbd>, <kbd>execute-from-path</kbd>,
379 <kbd>execute-from-directory</kbd> or <kbd>builtin</kbd> is interpreted before
380 all the files are read then the request is rejected.
383 <h2><A name="s-configerrors">
384 4.3 Errors in the configuration file
387 If a syntax error or other problem occurs when processing a
388 configuration file then a diagnostic will be issued, to wherever the
389 error messages are currently being sent (see the <kbd>errors-</kbd> family
390 of directives, above).<P>
392 The error will cause processing of the configuration files to cease at
393 that point, unless the error was inside a <kbd>catch-quit</kbd> construct.
394 In this case the settings controlling the program's execution will be
395 reset to the defaults as if a <kbd>reset</kbd> directive had been issued,
396 and parsing continues after <kbd>hctac</kbd>.
399 <h2><A name="s-defaults">
403 The default configuration processing is as if the daemon were parsing
404 an overall configuration file whose contents were as follows:
407 user-rcfile ~/.userv/rc
409 include /etc/userv/system.default
410 if grep service-user-shell /etc/shells
413 include-ifexist <var>file specified by most recent user-rcfile directive</var>
417 include /etc/userv/system.override
420 If one of the <kbd>--override</kbd> options to the client is used then it
421 will instead be as if the daemon were parsing an overall configuration
426 include <var>file containing configuration data sent by client</var>
430 User service daemon and client specification
431 - <A href="index.html#copyright"><kbd>userv</kbd> is Copyright 1996-1999 Ian Jackson.</A>
433 <A href="index.html#toc">Contents</A>; <A href="index.html#abstract">abstract</A>; <A href="ch-ipass.html">next</A>; <A href="ch-envir.html">back</A>.
436 Ian Jackson <A href="mailto:ian@davenant.greenend.org.uk">ian@davenant.greenend.org.uk</A></address>
~ian / userv.git / blob