Which services may be run by whom and under what conditions is controlled by configuration files.
The daemon will read these files in order. Certain directives in the files modify the daemon's execution settings for invoking the service, for example allowing certain file descriptors to be specified by the client or specifying which program to execute to provide the service.
The last instance of each such setting will take effect. The directives which specify which program to execute will not stop the configuration file from being read; they will be remembered and will only take effect if they are not overridden by a later directive.
The daemon will first read /etc/userv/system.default. Then, by default (this behaviour may be modified), it will read a per-user file ~/.userv/rc, if it exists and the service user's shell is in /etc/shells. Finally it will read /etc/userv/system.override.
When it has read all of these files it will act according to the currently values of of the execution settings.
The configuration file is a series of directives, usually one per line. The portion of a line following a hash character # is taken as a comment and ignored. Each directive consists of a series of tokens separated by linear whitespace (spaces and tabs); tokens may be words consisting of non-space characters, or, where a string is required, a string in double quotes. Double-quoted strings may contain the following backslash escapes:
Relative pathnames in directives are relative to the service program's current directory (usually the service user's home directory). Pathnames starting with the two characters ~/ are taken to be relative to the service user's home directory.
The following directives take effect immediately:
cdis cumulative. It is an error if the directory cannot be changed to.
cdshould not be used between
execute-from-directoryand the invocation of the service program, as the test for the availability of the service program would be done with the old current directory and the actual execution with the new (probably causing an error).
errors-push) which were started in that file will be considered finished. Parsing will continue in the file which caused the file containing the
eofto be read.
quitis subject to the
include-ifexistis used and the file does not exist, in which case the directive is silently ignored.
if, Control structure directives, subsection 4.2.3). If parameter has several values they will be tried in order; with
include-lookupthis search will stop when one is found, but with
include-lookup-allthe search will continue and any files appropriate to other values will be read too. If none of the parameter's values had a corresponding file then the file :default will be read, if it exists. If parameter's list of values was empty then the file :none will be tried first and read if it exists, otherwise :default will be tried. It is not an error for any of the files (including :default) not to exist, but it is an error if a file exists and cannot be read or if the directory cannot be accessed. A translation will be applied to values before they are used to construct a filename, so that the lookup cannot access dotfiles or files in other directories: values starting with full stops will have a colon prepended (making :.), colons will be doubled, and each slash will be replaced with a colon followed by a hyphen :-. A parameter value which is the empty string will be replaced with :empty (note that this is different from a parameter not having any values).
The following directives have no immediate effect, but are remembered and have an effect on later processing of the configuration files.
system.defaultconfiguration file has been read. This directive has no effect in a user's configuration file or in the
system.overridefile, as the user's configuration file has already been found and read by then and will not be re-read.
syslog. The default facility is user; the default level is error.
The following directives are used to create control structures. If the end of the file is encountered before the end of any control structure which was started inside it then that control structure is considered finished. This is not an error.
ifare interpreted only if the condition is true. Many conditions are properties of parameter values. Most parameters have a single string as a value; however, some may yield zero or several strings, in which case the condition is true if it is true of any of the strings individually. Parameters are described below.
The conditions are:
( condition & condition & condition ... )is true if all the listed conditions are true; where | is used it is true if any of them is true. Newlines must be used to separate one condition from the next, as shown, and the parentheses are mandatory. These conjunctions do not do lazy evaluation.
The parameters are:
USERV_USER, above) and the calling uid (represented in decimal).
--defvarcommand-line option to the client. If the variable was not defined then this parameter is an empty list of strings; in this case any condition which tests it will be false, and include-lookup on it will read the :none file, or :default if :none is not found.
catch-quitwill merely cause the parsing to continue at
hctacinstead. Any control constructs started since the
catch-quitwill be considered finished if a
quitis found. If an error occurs inside
catch-quitthe execution settings will be reset (as if by the
resetdirective) and parsing will likewise continue at
hctac. If a lexical or syntax error is detected in the same configuration file as the
catch-quit, while looking for the
hctacafter an error or
quit, that new error will not be caught.
The following directives modify the execution settings; the server will remember the fact that the directive was encountered and act on it only after all the configuration has been parsed. The last directive which modifies any particuar setting will take effect.
execute-from-pathwill change this setting.
no-suppress-argsis in effect. It is an error for the execution to fail when it is attempted (after all the configuration has been parsed). If program does not contain a slash it will be searched for on the service user's path.
PATH(or as a pathname of an executable, if it contains a /). This directive is very dangerous, and is only provided to make the
--overrideoptions effective. It should not normally be used. It is an error for the execution to fail when it is attempted (after all the configuration has been parsed).
Executes the builtin service service-name. These builtin services display information about the server and/or the request, and ignore any arguments passed from the service side except possibly to print them as part of their output. They write their results to their standard output (i.e., wherever file descriptor 1 is directed). The builtin services are:
resetis found in a configuration file, or when an error is caught by
.../program arg arg arg ...as
/bin/sh -c '. /etc/environment; exec "$@"' - .../program arg arg arg ...
no-set-environmentcancels the effect of
suppress-argsundoes the effect of
reject-fdwhich affected a particular file descriptor will take effect. fd-range may be a single number, two numbers separated by a hyphen, or one number followed by a hyphen (indicating all descriptors from that number onwards). It may also be one of the words stdin, stdout or stderr. Open-ended file descriptor rangers are allowed only with
ignore-fd, as otherwise the service program would find itself with a very large number of file descriptors open. When the configuration has been parsed, and before the service is about to be executed, stderr (fd 2) must be required or allowed (
allow-fd) for writing; this is so that the error message printed by the server's child process if it cannot
execthe service program is not lost.
/dev/nullfor reading resp. writing, or both if neither read nor write is specified. Any specification of these file descriptors by the client will be silently ignored; the client will see its ends of the descriptors being closed immediately.
SIGHUPif the client disconnects before the main service process terminates.
disconnect-hup. If one of the reading descriptors specified when the client is called gets a read error, or if the service is disconnected for some other reason, then the
SIGHUPwill be delivered before the writing end(s) of the service's reading pipe(s) are closed, so that the client can distinguish disconnection from reading EOF on a pipe.
cd ~/ reject no-set-environment suppress-args allow-fd 0 read allow-fd 1-2 write reject-fd 3- disconnect-hup
builtinis interpreted before all the files are read then the request is rejected.
If a syntax error or other problem occurs when processing a
configuration file then a diagnostic will be issued, to wherever the
error messages are currently being sent (see the
of directives, above).
The error will cause processing of the configuration files to cease at
that point, unless the error was inside a
In this case the settings controlling the program's execution will be
reset to the defaults as if a
reset directive had been issued,
and parsing continues after
The default configuration processing is as if the daemon were parsing an overall configuration file whose contents were as follows:
reset user-rcfile ~/.userv/rc errors-to-stderr include /etc/userv/system.default if grep service-user-shell /etc/shells errors-push catch-quit include-ifexist file specified by most recent user-rcfile directive hctac srorre fi include /etc/userv/system.override quit
If one of the
--override options to the client is used then it
will instead be as if the daemon were parsing an overall configuration
reset errors-to-stderr include file containing configuration data sent by client quit