1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
7 <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
9 <title>User service daemon and client specification - Service-side configuration</title>
15 <a name="ch-config"></a>
18 [ <a href="ch-envir.html">previous</a> ]
19 [ <a href="index.html#contents">Contents</a> ]
20 [ <a href="ch-intro.html">1</a> ]
21 [ <a href="ch-client.html">2</a> ]
22 [ <a href="ch-envir.html">3</a> ]
24 [ <a href="ch-ipass.html">5</a> ]
25 [ <a href="ch-notes.html">6</a> ]
26 [ <a href="ch-ipass.html">next</a> ]
31 User service daemon and client specification
32 <br>Chapter 4 - Service-side configuration
40 Which services may be run by whom and under what conditions is controlled by
44 The daemon will read these files in order. Certain directives in the files
45 modify the daemon's execution settings for invoking the service, for example
46 allowing certain file descriptors to be specified by the client or specifying
47 which program to execute to provide the service.
50 The <em>last</em> instance of each such setting will take effect. The
51 directives which specify which program to execute will not stop the
52 configuration file from being read; they will be remembered and will only take
53 effect if they are not overridden by a later directive.
56 The daemon will first read <samp>/etc/userv/system.default</samp>. Then, by
57 default (this behaviour may be modified), it will read a per-user file
58 <samp>~/.userv/rc</samp>, if it exists and the service user's shell is in
59 <samp>/etc/shells</samp>. Finally it will read
60 <samp>/etc/userv/system.override</samp>.
63 When it has read all of these files it will act according to the currently
64 values of of the execution settings.
69 <h2>4.1 Configuration file syntax</h2>
72 The configuration file is a series of directives, usually one per line. The
73 portion of a line following a hash character <samp>#</samp> is taken as a
74 comment and ignored. Each directive consists of a series of tokens separated
75 by linear whitespace (spaces and tabs); tokens may be words consisting of
76 non-space characters, or, where a string is required, a string in double
77 quotes. Double-quoted strings may contain the following backslash escapes:
79 <dt><samp>\n</samp></dt>
83 <dt><samp>\t</samp></dt>
87 <dt><samp>\r</samp></dt>
91 <dt><samp>\<var>OOO</var></samp></dt>
93 character whose octal code is <var>OOO</var>
95 <dt><samp>\x<var>XX</var></samp></dt>
97 character whose hex code is <var>XX</var>
99 <dt><samp>\<var>punctuation</var></samp></dt>
101 literal punctuation character (eg <samp>\\</samp>, <samp>\"</samp>)
103 <dt><samp>\<var>newline</var></samp> (ie, backslash at end of line)</dt>
105 string continues on next line
110 Relative pathnames in directives are relative to the service program's current
111 directory (usually the service user's home directory). Pathnames starting with
112 the two characters <samp>~/</samp> are taken to be relative to the service
113 user's home directory.
117 <a name="s-directives"></a>
118 <h2>4.2 Configuration file directives</h2>
122 <a name="s-dirs-immediate"></a>
123 <h3>4.2.1 Immediate directives</h3>
126 The following directives take effect immediately:
128 <dt><samp>cd <var>pathname</var></samp></dt>
130 Change directory in the service program. <code>cd</code> is cumulative. It is
131 an error if the directory cannot be changed to.
134 <code>cd</code> should not be used between <code>execute-from-directory</code>
135 and the invocation of the service program, as the test for the availability of
136 the service program would be done with the old current directory and the actual
137 execution with the new (probably causing an error).
141 <dt><samp>eof</samp></dt>
143 Stop reading the configuration file in question, as if end of file had been
144 reached. Any control constructs (<code>if</code>, <code>catch-quit</code> or
145 <code>errors-push</code>) which were started in that file will be considered
146 finished. Parsing will continue in the file which caused the file containing
147 the <code>eof</code> to be read.
151 <dt><samp>quit</samp></dt>
153 Stop reading configuration files and act immediately on the current settings.
154 The behaviour of <code>quit</code> is subject to the <code>catch-quit</code>
159 <dt><samp>include <var>filename</var></samp></dt>
160 <dt><samp>include-ifexist <var>filename</var></samp></dt>
162 Read the configuration file <var>filename</var>, and then return to this file
163 and continue parsing it with the next directive. It is an error if the file
164 cannot be opened and read, unless <code>include-ifexist</code> is used and the
165 file does not exist, in which case the directive is silently ignored.
169 <dt><samp>include-lookup <var>parameter</var> <var>directory</var></samp></dt>
170 <dt><samp>include-lookup-all <var>parameter</var> <var>directory</var></samp></dt>
172 Read the configuration file in <var>directory</var> whose name is the value of
173 <var>parameter</var> (see the description of <code>if</code>, <a
174 href="ch-config.html#s-dirs-control">Control structure directives, Section
175 4.2.3</a>). If <var>parameter</var> has several values they will be tried in
176 order; with <code>include-lookup</code> this search will stop when one is
177 found, but with <code>include-lookup-all</code> the search will continue and
178 any files appropriate to other values will be read too.
181 If none of the parameter's values had a corresponding file then the file
182 <samp>:default</samp> will be read, if it exists. If <var>parameter</var>'s
183 list of values was empty then the file <samp>:none</samp> will be tried first
184 and read if it exists, otherwise <samp>:default</samp> will be tried.
187 It is not an error for any of the files (including <samp>:default</samp>) not
188 to exist, but it is an error if a file exists and cannot be read or if the
189 directory cannot be accessed.
192 A translation will be applied to values before they are used to construct a
193 filename, so that the lookup cannot access dotfiles or files in other
194 directories: values starting with full stops will have a colon prepended
195 (making <samp>:.</samp>), colons will be doubled, and each slash will be
196 replaced with a colon followed by a hyphen <samp>:-</samp>. A parameter value
197 which is the empty string will be replaced with <samp>:empty</samp> (note that
198 this is different from a parameter not having any values).
202 <dt><samp>include-directory <var>directory</var></samp></dt>
204 Read configuration from all files in directory <var>directory</var> which are
205 plain files whose names consist only of alphanumerics and hyphens and start
206 with an alphanumeric. They will be read in lexical order. It is an error for
207 the directory not to exist or for it or any of the files found not to be read
208 successfully, or for anything with an appropriate name not to be a plain file
209 or a symbolic link to a plain file.
213 <dt><samp>error <var>text ...</var></samp></dt>
215 Causes an error whose message includes the descriptive string <var>text</var>.
216 <var>text</var> may consist of several tokens with intervening whitespace. The
217 whitespace will be included in the message as found in the configuration file:
218 all the characters until the end of the line will be included verbatim, unless
219 they are part of a double-quoted string, in which case the usual meaning of the
220 string (i.e., after backslash escape processing) will be used. Comments and
221 linear whitespace at the end of the line (or just before the comment) will
226 <dt><samp>message <var>text ...</var></samp></dt>
228 Causes a message including the descriptive string <var>text</var> to be
229 delivered as if it were an error message, but does not actually cause an error.
235 <a name="s-dirs-delayed"></a>
236 <h3>4.2.2 Directives with delayed effect</h3>
239 The following directives have no immediate effect, but are remembered and have
240 an effect on later processing of the configuration files.
242 <dt><samp>user-rcfile <var>filename</var></samp></dt>
244 Specifies that the file <var>filename</var> should be read instead of the
245 user's <samp>~/.userv/rc</samp>. This does <em>not</em> happen immediately;
246 instead, the setting is remembered and used after the
247 <code>system.default</code> configuration file has been read. This directive
248 has no effect in a user's configuration file or in the
249 <code>system.override</code> file, as the user's configuration file has already
250 been found and read by then and will not be re-read.
254 <dt><samp>errors-to-stderr</samp></dt>
256 Causes error messages to be delivered to the client's stderr.
260 <dt><samp>errors-to-file</samp> <var>filename</var></dt>
262 Error messages will be written to <var>filename</var>, which will be opened in
263 the context of and with the privileges of the service user.
267 <dt><samp>errors-to-syslog</samp> [<var>facility</var> [<var>level</var>]]</dt>
269 Error messages will be delivered using <code>syslog</code>. The default
270 <var>facility</var> is <samp>user</samp>; the default <var>level</var> is
277 <a name="s-dirs-control"></a>
278 <h3>4.2.3 Control structure directives</h3>
281 The following directives are used to create control structures. If the end of
282 the file is encountered before the end of any control structure which was
283 started inside it then that control structure is considered finished. This is
286 <dt><samp>fi</samp></dt>
288 Lines following <code>if</code> are interpreted only if the condition is true.
289 Many conditions are properties of parameter values. Most parameters have a
290 single string as a value; however, some may yield zero or several strings, in
291 which case the condition is true if it is true of any of the strings
292 individually. Parameters are described below.
297 <dt><samp>glob <var>parameter</var> <var>glob-pattern</var> ...</samp></dt>
299 The value of the parameter whose name is given matches one of the glob patterns
300 (anchored at both ends; backslashes can be used to escape metacharacters).
302 <dt><samp>range <var>parameter</var> <var>min</var> <var>max</var></samp></dt>
304 The value of the parameter is a nonnegative integer and lies within the range
305 specified. <var>min</var> or <var>max</var> may be <samp>$</samp> to indicate
306 no lower or upper limit, respectively.
308 <dt><samp>grep <var>parameter</var> <var>filename</var></samp></dt>
310 The <var>filename</var> refers to a file one of whose lines is the value of the
311 parameter (leading or trailing whitespace on each line and empty lines in the
312 file are ignored). It is an error for the file not to be opened and read.
314 <dt><samp>! <var>condition</var></samp></dt>
316 The <var>condition</var> is <em>not</em> true.
318 <dt>Conjunctions: <samp>&</samp> and <samp>|</samp></dt>
321 ( <var>condition</var>
322 & <var>condition</var>
323 & <var>condition</var>
328 is true if all the listed conditions are true; where <samp>|</samp> is used it
329 is true if any of them is true. Newlines must be used to separate one
330 condition from the next, as shown, and the parentheses are mandatory. These
331 conjunctions do not do lazy evaluation.
338 <dt><samp>service</samp></dt>
340 The service name specified when the client was called.
342 <dt><samp>calling-user</samp></dt>
344 Two strings: the login name of the calling user (determined as for
345 <code>USERV_USER</code>, above) and the calling uid (represented in decimal).
347 <dt><samp>calling-group</samp></dt>
349 Several strings: the primary and supplementary group names and gids (in
350 decimal) of the calling process. All the group names come first, and then the
351 gids. If the first supplementary group is the same as the primary group then
354 <dt><samp>calling-user-shell</samp></dt>
356 The calling user's shell, as listed in the password entry for the calling login
357 name (as determined for <code>USERV_USER</code>, above).
359 <dt><samp>service-user</samp></dt>
361 Two strings: the name of the service user (as specified to the client) and
362 their uid (represented in decimal).
364 <dt><samp>service-group</samp></dt>
366 Several strings: the primary and supplementary group names and gids (in
367 decimal) of the service user.
369 <dt><samp>service-user-shell</samp></dt>
371 The service user's shell, as listed in their password entry.
373 <dt><samp>u-<var>name</var></samp></dt>
375 The value of the user-defined variable <var>name</var> passed by the caller
376 using the <code>--defvar</code> command-line option to the client. If the
377 variable was not defined then this parameter is an empty list of strings; in
378 this case any condition which tests it will be false, and
379 <samp>include-lookup</samp> on it will read the <samp>:none</samp> file, or
380 <samp>:default</samp> if <samp>:none</samp> is not found.
386 <dt><samp>errors-push</samp> <var>filename</var></dt>
387 <dt><samp>srorre</samp></dt>
389 Stacks the error handling behaviour currently in effect. Any changes to error
390 handling will take effect only between <code>errors-push</code> and
395 <dt><samp>catch-quit</samp></dt>
396 <dt><samp>hctac</samp></dt>
398 Any use of <code>quit</code> inside <code>catch-quit</code> will merely cause
399 the parsing to continue at <code>hctac</code> instead. Any control constructs
400 started since the <code>catch-quit</code> will be considered finished if a
401 <code>quit</code> is found.
404 If an error occurs inside <code>catch-quit</code> the execution settings will
405 be reset (as if by the <code>reset</code> directive) and parsing will likewise
406 continue at <code>hctac</code>.
409 If a lexical or syntax error is detected in the same configuration file as the
410 <code>catch-quit</code>, while looking for the <code>hctac</code> after an
411 error or <code>quit</code>, that new error will not be caught.
417 <a name="s-dirs-execution"></a>
418 <h3>4.2.4 Directives for changing execution settings</h3>
421 The following directives modify the execution settings; the server will
422 remember the fact that the directive was encountered and act on it only after
423 all the configuration has been parsed. The <em>last</em> directive which
424 modifies any particuar setting will take effect.
426 <dt><samp>reject</samp></dt>
428 Reject the request. <code>execute</code>, <code>execute-from-directory</code>
429 and <code>execute-from-path</code> will change this setting.
433 <dt><samp>execute <var>program</var> [<var>argument</var> ...]</samp></dt>
435 Execute the program <var>program</var>, with the arguments as specified,
436 followed by any arguments given to the client if <code>no-suppress-args</code>
437 is in effect. It is an error for the execution to fail when it is attempted
438 (after all the configuration has been parsed). If <var>program</var> does not
439 contain a slash it will be searched for on the service user's path.
443 <dt><samp>execute-from-directory <var>pathname</var> [<var>argument</var> ...]</samp></dt>
445 Take all the characters after the last slash of the service name specified when
446 the client was called, and execute that program in the directory named by
447 <var>pathname</var> as if it had been specified for <var>execute</var>. The
448 part of the service name used may contain only alphanumerics and hyphens and
449 must start with an alphanumeric (and it must be non-empty), otherwise it is an
453 This directive is ignored if the relevant program does not exist in the
454 directory specified; in this case the program to execute is left at its
455 previous setting (or unset, if it was not set before).
458 It is an error for the test for the existence of the program to fail other than
459 with a `no such file or directory' indication. It is also an error for the
460 execution to fail if and when it is attempted (after all the configuration has
465 <dt><samp>execute-from-path</samp></dt>
467 <var>service</var> is interpreted as a program on the default <code>PATH</code>
468 (or as a pathname of an executable, if it contains a <samp>/</samp>). This
469 directive is <em>very dangerous</em>, and is only provided to make the
470 <code>--override</code> options effective. It should not normally be used. It
471 is an error for the execution to fail when it is attempted (after all the
472 configuration has been parsed).
476 <dt><samp>execute-builtin <var>service-name</var> <var>service-arguments</var></samp></dt>
478 Executes the builtin service <var>service-name</var>. These builtin services
479 display information about the server and/or the request, and ignore any
480 arguments passed from the service side except possibly to print them as part of
481 their output. They write their results to their standard output (i.e.,
482 wherever file descriptor 1 is directed). The builtin services are:
484 <dt><samp>execute</samp></dt>
486 Displays the execution settings, defined variables, arguments, etc. with which
487 the builtin service was invoked.
489 <dt><samp>environment</samp></dt>
491 Displays the environment variable settings with which the builtin service was
494 <dt><samp>parameter <var>parameter</var></samp></dt>
496 Displays the values of the service configuration language parameter specified.
498 <dt><samp>version</samp></dt>
500 Displays the version string and compilation details of the uservd server
503 <dt><samp>reset</samp></dt>
505 Displays the default reset configuration (evaluated when <code>reset</code> is
506 found in a configuration file, or when an error is caught by
507 <code>catch-quit</code>).
509 <dt><samp>toplevel</samp></dt>
511 Displays the top-level default configuration (the configuration data, evaluated
512 by the server, which calls all the other configuration files).
514 <dt><samp>override</samp></dt>
516 Displays the top-level override configuration (the configuration data,
517 evaluated by the server, which causes all the other configuration data to be
520 <dt><samp>help</samp></dt>
522 Displays a list of the understood builtin service names and arguments.
527 In the future other builtin services may be defined which do more than just
532 <dt><samp>set-environment</samp></dt>
533 <dt><samp>no-set-environment</samp></dt>
535 Runs <samp>/etc/environment</samp> to set the service user's environment. This
536 adds the overhead of invoking a shell, but doesn't cause any shell (de)mangling
537 of the service's arguments. This is achieved by invoking
540 .../program arg arg arg ...
547 /bin/sh -c '. /etc/environment; exec "$@"' - .../program arg arg arg ...
551 <code>no-set-environment</code> cancels the effect of
552 <code>set-environment</code>.
556 <dt><samp>no-suppress-args</samp></dt>
557 <dt><samp>suppress-args</samp></dt>
559 Include any arguments given to the client as arguments to the program invoked
560 as a result of an <code>execute</code>, <code>execute-from-directory</code> or
561 <code>execute-from-path</code> directive. <code>suppress-args</code> undoes
562 the effect of <code>no-suppress-args</code>.
566 <dt><samp>require-fd <var>fd-range</var> read|write</samp></dt>
568 Insist that the filedescriptor(s) be opened for reading resp. writing. It is
569 an error if any descriptor marked as required when the service is about to be
570 invoked (after the configuration has been parsed) was not specified when the
571 client was invoked. Each file descriptor has a separate setting, and the last
572 one of <code>require-fd</code>, <code>allow-fd</code>, <code>ignore-fd</code>,
573 <code>null-fd</code> or <code>reject-fd</code> which affected a particular file
574 descriptor will take effect.
577 <var>fd-range</var> may be a single number, two numbers separated by a hyphen,
578 or one number followed by a hyphen (indicating all descriptors from that number
579 onwards). It may also be one of the words <samp>stdin</samp>,
580 <samp>stdout</samp> or <samp>stderr</samp>. Open-ended file descriptor rangers
581 are allowed only with <code>reject-fd</code> and <code>ignore-fd</code>, as
582 otherwise the service program would find itself with a very large number of
583 file descriptors open.
586 When the configuration has been parsed, and before the service is about to be
587 executed, stderr (fd 2) must be required or allowed (<code>require-fd</code> or
588 <code>allow-fd</code>) for writing; this is so that the error message printed
589 by the server's child process if it cannot <code>exec</code> the service
594 <dt><samp>allow-fd <var>fd-range</var> [read|write]</samp></dt>
596 Allow the descriptor(s) to be opened for reading resp. writing, or either if
597 neither <samp>read</samp> nor <samp>write</samp> is specified. If a particular
598 descriptor not specified by the client then it will be open onto
599 <samp>/dev/null</samp> (for reading, writing, or both, depending on whether
600 <samp>read</samp>, <samp>write</samp> or neither was specified).
604 <dt><samp>null-fd <var>fd-range</var> [read|write]</samp></dt>
606 Specify that the descriptor(s) be opened onto <code>/dev/null</code> for
607 reading resp. writing, or both if neither <samp>read</samp> nor
608 <samp>write</samp> is specified. Any specification of these file descriptors
609 by the client will be silently ignored; the client will see its ends of the
610 descriptors being closed immediately.
614 <dt><samp>reject-fd <var>fd-range</var></samp></dt>
616 Do not allow the descriptor(s) to be specified by the client. It is an error
617 if any descriptor(s) marked for rejection are specified when the service is
618 about to be invoked (after the configuration has been parsed).
622 <dt><samp>ignore-fd <var>fd-range</var></samp></dt>
624 Silently ignore any specification by the client of those descriptor(s). The
625 pipes corresponding to these descriptors will be closed just before the service
630 <dt><samp>disconnect-hup</samp></dt>
631 <dt><samp>no-disconnect-hup</samp></dt>
633 Causes the service's process group to get a <code>SIGHUP</code> if the client
634 disconnects before the main service process terminates.
635 <code>no-disconnect-hup</code> cancels <code>disconnect-hup</code>.
638 If one of the reading descriptors specified when the client is called gets a
639 read error, or if the service is disconnected for some other reason, then the
640 <code>SIGHUP</code> will be delivered <em>before</em> the writing end(s) of the
641 service's reading pipe(s) are closed, so that the client can distinguish
642 disconnection from reading EOF on a pipe.
646 <dt><samp>reset</samp></dt>
648 Resets the execution settings to the default. This is equivalent to:
664 If no <code>execute</code>, <code>execute-from-path</code>,
665 <code>execute-from-directory</code> or <code>builtin</code> is interpreted
666 before all the files are read then the request is rejected.
670 <a name="s-configerrors"></a>
671 <h2>4.3 Errors in the configuration file</h2>
674 If a syntax error or other problem occurs when processing a configuration file
675 then a diagnostic will be issued, to wherever the error messages are currently
676 being sent (see the <code>errors-</code> family of directives, above).
679 The error will cause processing of the configuration files to cease at that
680 point, unless the error was inside a <code>catch-quit</code> construct. In
681 this case the settings controlling the program's execution will be reset to the
682 defaults as if a <code>reset</code> directive had been issued, and parsing
683 continues after <code>hctac</code>.
687 <a name="s-defaults"></a>
688 <h2>4.4 Defaults</h2>
691 The default configuration processing is as if the daemon were parsing an
692 overall configuration file whose contents were as follows:
696 user-rcfile ~/.userv/rc
698 include /etc/userv/system.default
699 if grep service-user-shell /etc/shells
702 include-ifexist <var>file specified by most recent user-rcfile directive</var>
706 include /etc/userv/system.override
711 If one of the <code>--override</code> options to the client is used then it
712 will instead be as if the daemon were parsing an overall configuration as
718 include <var>file containing configuration data sent by client</var>
724 [ <a href="ch-envir.html">previous</a> ]
725 [ <a href="index.html#contents">Contents</a> ]
726 [ <a href="ch-intro.html">1</a> ]
727 [ <a href="ch-client.html">2</a> ]
728 [ <a href="ch-envir.html">3</a> ]
730 [ <a href="ch-ipass.html">5</a> ]
731 [ <a href="ch-notes.html">6</a> ]
732 [ <a href="ch-ipass.html">next</a> ]
737 User service daemon and client specification
741 Ian Jackson <code><a href="mailto:ian@davenant.greenend.org.uk">ian@davenant.greenend.org.uk</a></code>
~ian / userv.git / blob