User service daemon and client specification - chapter 4
Service-side configuration

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.

4.1 Configuration file syntax

\n

newline

\t

tab

\r

carriage return

\OOO

character whose octal code is OOO

\xXX

character whose hex code is XX

\punctuation

literal punctuation character (eg \\, \")

\newline (ie, backslash at end of line)

string continues on next line

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.

4.2 Configuration file directives

4.2.1 Immediate directives

cd pathname

Change directory in the service program. 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).

eof

Stop reading the configuration file in question, as if end of file had been reached. Any control constructs (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

Stop reading configuration files and act immediately on the current settings. The behaviour of quit is subject to the catch-quit control construct.

include filename

include-ifexist filename

Read the configuration file filename, and then return to this file and continue parsing it with the next directive. It is an error if the file cannot be opened and read, unless include-ifexist is used and the file does not exist, in which case the directive is silently ignored.

include-lookup parameter directory

include-lookup-all parameter directory

Read the configuration file in directory whose name is the value of parameter (see the description of if, above). 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).

include-directory directory

Read configuration from all files in directory directory which are plain files whose names consist only of alphanumerics and hyphens and start with an alphanumeric. They will be read in lexical order. It is an error for the directory not to exist or for it or any of the files found not to be read successfully, or for anything with an appropriate name not to be a plain file or a symbolic link to a plain file.

error text ...

Causes an error whose message includes the descriptive string text. text may consist of several tokens with intervening whitespace. The whitespace will be included in the message as found in the configuration file: all the characters until the end of the line will be included verbatim, unless they are part of a double-quoted string, in which case the usual meaning of the string (i.e., after backslash escape processing) will be used. Comments and linear whitespace at the end of the line (or just before the comment) will still be ignored.

message text ...

Causes a message including the descriptive string text to be delivered as if it were an error message, but does not actually cause an error.

4.2.2 Directives with delayed effect

user-rcfile filename

Specifies that the file filename should be read instead of the user's ~/.userv/rc. This does not happen immediately; instead, the setting is remembered and used after the 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.

errors-to-stderr

Causes error messages to be delivered to the client's stderr.

errors-to-file filename

Error messages will be written to filename, which will be opened in the context of and with the privileges of the service user.

errors-to-syslog [facility [level]]

Error messages will be delivered using syslog. The default facility is daemon; the default level is error.

4.2.3 Control structure directives

if condition

elif condition

else

fi

Lines following 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:

glob parameter glob-pattern ...

The value of the parameter whose name is given matches one of the glob patterns (anchored at both ends; backslashes can be used to escape metacharacters).

range parameter min max

The value of the parameter is a nonnegative integer and lies within the range specified. min or max may be $ to indicate no lower or upper limit, respectively.

grep parameter filename

The filename refers to a file one of whose lines is the value of the parameter (leading or trailing whitespace on each line and empty lines in the file are ignored). It is an error for the file not to be opened and read.

! condition

The condition is not true.

Conjunctions: & and |

( 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:

service

The service name specified when the client was called.

calling-user

Two strings: the login name of the calling user (determined as for USERV_USER, above) and the calling uid (represented in decimal).

calling-group

Several strings: the primary and supplementary group names and gids (in decimal) of the calling process. All the group names come first, and then the gids. If the first supplementary group is the same as the primary group then it is elided.

calling-user-shell

The calling user's shell, as listed in the password entry for the calling login name (as determined for USERV_USER, above).

service-user

Two strings: the name of the service user (as specified to the client) and their uid (represented in decimal).

service-group

Several strings: the primary and supplementary group names and gids (in decimal) of the service user.

service-user-shell

The service user's shell, as listed in their password entry.

u-name

The value of the user-defined variable name passed by the caller using the -D 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 filename

srorre

Stacks the error handling behaviour currently in effect. Any changes to error handling will take effect only between errors-push and srorre.

catch-quit

hctac

Any use of 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 serious lexical or syntax error is detected in the same configuration file as the catch-quit, while looking for the hctac, that error will not be caught.

4.2.4 Directives for changing execution settings

reject

Reject the request. execute, execute-from-directory and execute-from-path will change this setting.

execute pathname [argument ...]

Execute the program pathname, with the arguments as specified, followed by any arguments given to the client if 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).

execute-from-directory pathname [argument ...]

Take all the characters after the last slash of the service name specified when the client was called, and execute that program in the directory named by pathname as if it had been specified for execute. The part of the service name used may contain only alphanumerics and hyphens and must start with an alphanumeric (and it must be non-empty), otherwise it is an error.

This directive is ignored if the relevant program does not exist in the directory specified; in this case the program to execute is left at its previous setting (or unset, if it was not set before).

It is an error for the test for the existence of the program to fail other than with a `no such file or directory' indication. It is also an error for the execution to fail if and when it is attempted (after all the configuration has been parsed).

execute-from-path

service is interpreted as a program on the default 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).

set-environment

no-set-environment

Runs /etc/environment to set the service user's environment. This adds the overhead of invoking a shell, but doesn't cause any shell (de)mangling of the service's arguments. This is achieved by invoking

.../program arg arg arg ...

as

/bin/sh -c '. /etc/environment; exec "$@"' - .../program arg arg arg ...

no-set-environment cancels the effect of set-environment.

no-suppress-args

suppress-args

Include any arguments given to the client as arguments to the program invoked as a result of an execute or execute-from-directory directive. suppress-args undoes the effect of no-suppress-args.

require-fd fd-range read|write

Insist that the filedescriptor(s) be opened for reading resp. writing. It is an error if any descriptor marked as required when the service is about to be invoked (after the configuration has been parsed) was not specified when the client was invoked. Each file descriptor has a separate setting, and the last one of 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.

allow-fd fd-range [read|write]

Allow the descriptor(s) to be opened for reading resp. writing, or either if neither read nor write is specified. If a particular descriptor not specified by the client then it will be open onto /dev/null (for reading, writing, or both, depending on whether read, write or neither was specified).

null-fd fd-range [read|write]

Specify that the descriptor(s) be opened onto /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.

reject-fd fd-range

Do not allow the descriptor(s) to be specified by the client. It is an error if any descriptor(s) marked for rejection are specified when the service is about to be invoked (after the configuration has been parsed).

ignore-fd fd-range

Silently ignore any specification by the client of those descriptor(s). The pipes corresponding to these descriptors will be closed just before the service is invoked.

disconnect-hup

no-disconnect-hup

Causes the service's process group to get a 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.

reset

Resets the execution settings to the default. This is equivalent to:

cd ~/
reject
no-set-environment
suppress-args
allow-fd 0 read
allow-fd 1-2 write
reject-fd 3-
disconnect-hup

4.3 Errors in the configuration file

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.

4.4 Defaults

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 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