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:
cd is cumulative. It
is an error if the directory cannot be changed to.
cd should not be used between execute-from-directory and
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).
if, catch-quit or
errors-push) which were started in that file will be considered
finished. Parsing will continue in the file which caused the file
containing the eof to be read.
quit is subject to the
catch-quit control construct.
include-ifexist
is 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-lookup this search will stop
when one is found, but with include-lookup-all the 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.default configuration file has been read. This
directive has no effect in a user's configuration file or in the
system.override file, 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.
if are 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).
USERV_USER, above).
--defvar command-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.
errors-push and
srorre.
quit inside catch-quit will merely cause the
parsing to continue at hctac instead. Any control constructs
started since the catch-quit will be considered finished if a
quit is found.
If an error occurs inside catch-quit the execution settings
will be reset (as if by the reset directive) 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 hctac
after 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, execute-from-directory and
execute-from-path will change this setting.
no-suppress-args is 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
--override options 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:
reset
is found in a configuration file, or when an error is caught by
catch-quit).
.../program arg arg arg ...as
/bin/sh -c '. /etc/environment; exec "$@"' - .../program arg arg arg ...
no-set-environment cancels the effect of
set-environment.
execute,
execute-from-directory or execute-from-path directive.
suppress-args undoes the effect of no-suppress-args.
require-fd,
allow-fd, ignore-fd, null-fd or reject-fd
which 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 reject-fd and 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
(require-fd or allow-fd) for writing; this is so that
the error message printed by the server's child process if it cannot
exec the service program is not lost.
/dev/null for
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.
SIGHUP if the
client disconnects before the main service process terminates.
no-disconnect-hup cancels 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 SIGHUP will 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
execute, execute-from-path,
execute-from-directory or builtin is 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 errors- family
of directives, above).
The error will cause processing of the configuration files to cease at
that point, unless the error was inside a catch-quit construct.
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 hctac.
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
as follows:
reset errors-to-stderr include file containing configuration data sent by client quit