--- /dev/null
+<html><head>
+<title>User service daemon and client specification - Service-side configuration</title>
+<link rev=made href="mailto:ian@davenant.greenend.org.uk">
+</head><body>
+<h1>
+User service daemon and client specification - chapter 4<br>
+Service-side configuration
+</h1>
+
+Which services may be run by whom and under what conditions is
+controlled by configuration files.<P>
+
+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.<P>
+
+The <em>last</em> 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.<P>
+
+The daemon will first read <code>/etc/userv/system.default</code>. Then, by
+default (this behaviour may be modified), it will read a per-user file
+<code>~/.userv/rc</code>, if it exists and the service user's shell is in
+<code>/etc/shells</code>. Finally it will read
+<code>/etc/userv/system.override</code>.<P>
+
+When it has read all of these files it will act according to the
+currently values of of the execution settings.
+<hr>
+<h2><A name="s4.1">
+4.1 Configuration file syntax
+</A></h2>
+
+The configuration file is a series of directives, usually one per
+line. The portion of a line following a hash character <code>#</code> 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:
+
+<dl compact>
+<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>
+<P>
+
+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 <code>~/</code> are taken to be
+relative to the service user's home directory.
+<hr>
+<h2><A name="s-directives">
+4.2 Configuration file directives
+</A></h2>
+<hr>
+<h3><A name="s-dirs-immediate">
+4.2.1 Immediate directives
+</A></h3>
+
+The following directives take effect immediately:
+
+<dl>
+<dt><code>cd </code><var>pathname</var><code></code><dd>Change directory in the service program. <kbd>cd</kbd> is cumulative. It
+is an error if the directory cannot be changed to.<P>
+
+<kbd>cd</kbd> should not be used between <kbd>execute-from-directory</kbd> 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).
+<p><dt><code>eof</code><dd>Stop reading the configuration file in question, as if end of file had
+been reached. Any control constructs (<kbd>if</kbd>, <kbd>catch-quit</kbd> or
+<kbd>errors-push</kbd>) which were started in that file will be considered
+finished. Parsing will continue in the file which caused the file
+containing the <kbd>eof</kbd> to be read.
+<p><dt><code>quit</code><dd>Stop reading configuration files and act immediately on the current
+settings. The behaviour of <kbd>quit</kbd> is subject to the
+<kbd>catch-quit</kbd> control construct.
+<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
+file and continue parsing it with the next directive. It is an error
+if the file cannot be opened and read, unless <kbd>include-ifexist</kbd>
+is used and the file does not exist, in which case the directive is
+silently ignored.
+<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
+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
+be tried in order; with <kbd>include-lookup</kbd> this search will stop
+when one is found, but with <kbd>include-lookup-all</kbd> the search will
+continue and any files appropriate to other values will be read too.<P>
+
+If none of the parameter's values had a corresponding file then the
+file <code>:default</code> will be read, if it exists. If <var>parameter</var>'s
+list of values was empty then the file <code>:none</code> will be tried first
+and read if it exists, otherwise <code>:default</code> will be tried.<P>
+
+It is not an error for any of the files (including <code>:default</code>) not
+to exist, but it is an error if a file exists and cannot be read or if
+the directory cannot be accessed.
+<P>
+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 <code>:.</code>), colons will be doubled, and each
+slash will be replaced with a colon followed by a hyphen <code>:-</code>. A
+parameter value which is the empty string will be replaced with
+<code>:empty</code> (note that this is different from a parameter not having
+any values).
+<p><dt><code>include-directory </code><var>directory</var><code></code><dd>Read configuration from all files in directory <var>directory</var> 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.
+<p><dt><code>error </code><var>text ...</var><code></code><dd>Causes an error whose message includes the descriptive string
+<var>text</var>. <var>text</var> 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.
+<p><dt><code>message </code><var>text ...</var><code></code><dd>Causes a message including the descriptive string <var>text</var> to be
+delivered as if it were an error message, but does not actually cause
+an error.<p></dl>
+
+<hr>
+<h3><A name="s-dirs-delayed">
+4.2.2 Directives with delayed effect
+</A></h3>
+
+The following directives have no immediate effect, but are remembered
+and have an effect on later processing of the configuration files.
+
+<dl>
+<dt><code>user-rcfile </code><var>filename</var><code></code><dd>Specifies that the file <var>filename</var> should be read instead of the
+user's <code>~/.userv/rc</code>. This does <em>not</em> happen immediately;
+instead, the setting is remembered and used after the
+<kbd>system.default</kbd> configuration file has been read. This
+directive has no effect in a user's configuration file or in the
+<kbd>system.override</kbd> file, as the user's configuration file has
+already been found and read by then and will not be re-read.
+<p><dt><code>errors-to-stderr</code><dd>Causes error messages to be delivered to the client's stderr.
+<p><dt><code>errors-to-file</code> <var>filename</var><dd>Error messages will be written to <var>filename</var>, which will be opened
+in the context of and with the privileges of the service user.
+<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
+<var>facility</var> is <code>user</code>; the default <var>level</var> is <code>error</code>.<p></dl>
+
+<hr>
+<h3><A name="s-dirs-control">
+4.2.3 Control structure directives
+</A></h3>
+
+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.
+
+<dl>
+<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
+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.<P>
+
+The conditions are:
+
+<dl compact>
+<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
+patterns (anchored at both ends; backslashes can be used to escape
+metacharacters).
+<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
+the range specified. <var>min</var> or <var>max</var> may be <code>$</code> to indicate
+no lower or upper limit, respectively.
+<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
+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.
+<dt><code>! </code><var>condition</var><code></code><dd>The <var>condition</var> is <em>not</em> true.
+<dt>Conjunctions: <code>&</code> and <code>|</code><dd><pre>( <var>condition</var>
+& <var>condition</var>
+& <var>condition</var>
+...
+)</pre>
+is true if all the listed conditions are true; where <code>|</code> 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.</dl>
+<P>
+
+The parameters are:
+
+<dl compact>
+<dt><code>service</code><dd>The service name specified when the client was called.
+<dt><code>calling-user</code><dd>Two strings: the login name of the calling user (determined as for
+<kbd>USERV_USER</kbd>, above) and the calling uid (represented in
+decimal).
+<dt><code>calling-group</code><dd>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.
+<dt><code>calling-user-shell</code><dd>The calling user's shell, as listed in the password entry for the
+calling login name (as determined for <kbd>USERV_USER</kbd>, above).
+<dt><code>service-user</code><dd>Two strings: the name of the service user (as specified to the client)
+and their uid (represented in decimal).
+<dt><code>service-group</code><dd>Several strings: the primary and supplementary group names and gids
+(in decimal) of the service user.
+<dt><code>service-user-shell</code><dd>The service user's shell, as listed in their password entry.
+<dt><code>u-</code><var>name</var><code></code><dd>The value of the user-defined variable <var>name</var> passed by the caller
+using the <kbd>--defvar</kbd> 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
+<code>include-lookup</code> on it will read the <code>:none</code> file, or
+<code>:default</code> if <code>:none</code> is not found.
+</dl>
+
+<dt><code>errors-push</code> <var>filename</var><dt><code>srorre</code><dd>Stacks the error handling behaviour currently in effect. Any changes
+to error handling will take effect only between <kbd>errors-push</kbd> and
+<kbd>srorre</kbd>.
+<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
+parsing to continue at <kbd>hctac</kbd> instead. Any control constructs
+started since the <kbd>catch-quit</kbd> will be considered finished if a
+<kbd>quit</kbd> is found.<P>
+
+If an error occurs inside <kbd>catch-quit</kbd> the execution settings
+will be reset (as if by the <kbd>reset</kbd> directive) and parsing will
+likewise continue at <kbd>hctac</kbd>.<P>
+
+If a lexical or syntax error is detected in the same configuration
+file as the <kbd>catch-quit</kbd>, while looking for the <kbd>hctac</kbd>
+after an error or <kbd>quit</kbd>, that new error will not be caught.
+</dl>
+
+<hr>
+<h3><A name="s-dirs-execution">
+4.2.4 Directives for changing execution settings
+</A></h3>
+
+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 <em>last</em>
+directive which modifies any particuar setting will take effect.
+
+<dl>
+<dt><code>reject</code><dd>Reject the request. <kbd>execute</kbd>, <kbd>execute-from-directory</kbd> and
+<kbd>execute-from-path</kbd> will change this setting.
+<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,
+followed by any arguments given to the client if
+<kbd>no-suppress-args</kbd> is in effect. It is an error for the
+execution to fail when it is attempted (after all the configuration
+has been parsed). If <var>program</var> does not contain a slash it will
+be searched for on the service user's path.
+<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
+specified when the client was called, and execute that program in the
+directory named by <var>pathname</var> as if it had been specified for
+<var>execute</var>. 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.<P>
+
+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).<P>
+
+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).
+<p><dt><code>execute-from-path</code><dd><var>service</var> is interpreted as a program on the default <kbd>PATH</kbd>
+(or as a pathname of an executable, if it contains a <code>/</code>). This
+directive is <em>very dangerous</em>, and is only provided to make the
+<kbd>--override</kbd> 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).
+<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
+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:
+
+<dl compact>
+<dt><code>execute</code><dd>Displays the execution settings, defined variables,
+arguments, etc. with which the builtin service was invoked.
+<dt><code>environment</code><dd>Displays the environment variable settings with which the builtin
+service was invoked.
+<dt><code>parameter </code><var>parameter</var><code></code><dd>Displays the values of the service configuration language parameter
+specified.
+<dt><code>version</code><dd>Displays the version string and compilation details of the uservd
+server program.
+<dt><code>reset</code><dd>Displays the default reset configuration (evaluated when <kbd>reset</kbd>
+is found in a configuration file, or when an error is caught by
+<kbd>catch-quit</kbd>).
+<dt><code>toplevel</code><dd>Displays the top-level default configuration (the configuration data,
+evaluated by the server, which calls all the other configuration
+files).
+<dt><code>override</code><dd>Displays the top-level override configuration (the configuration data,
+evaluated by the server, which causes all the other configuration data
+to be parsed).
+<dt><code>help</code><dd>Displays a list of the understood builtin service names and arguments.</dl>
+
+
+In the future other builtin services may be defined which do more than
+just print information.
+<dt><code>set-environment</code><dt><code>no-set-environment</code><dd>Runs <code>/etc/environment</code> 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
+<pre>.../program arg arg arg ...</pre>
+as
+<pre>/bin/sh -c '. /etc/environment; exec "$@"' - .../program arg arg arg ...</pre>
+<kbd>no-set-environment</kbd> cancels the effect of
+<kbd>set-environment</kbd>.
+<dt><code>no-suppress-args</code><dt><code>suppress-args</code><dd>Include any arguments given to the client as arguments to the program
+invoked as a result of an <kbd>execute</kbd>,
+<kbd>execute-from-directory</kbd> or <kbd>execute-from-path</kbd> directive.
+<kbd>suppress-args</kbd> undoes the effect of <kbd>no-suppress-args</kbd>.
+<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.
+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 <kbd>require-fd</kbd>,
+<kbd>allow-fd</kbd>, <kbd>ignore-fd</kbd>, <kbd>null-fd</kbd> or <kbd>reject-fd</kbd>
+which affected a particular file descriptor will take effect.<P>
+
+<var>fd-range</var> 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
+<code>stdin</code>, <code>stdout</code> or <code>stderr</code>. Open-ended file descriptor
+rangers are allowed only with <kbd>reject-fd</kbd> and <kbd>ignore-fd</kbd>,
+as otherwise the service program would find itself with a very large
+number of file descriptors open.<P>
+
+When the configuration has been parsed, and before the service is
+about to be executed, stderr (fd 2) must be required or allowed
+(<kbd>require-fd</kbd> or <kbd>allow-fd</kbd>) for writing; this is so that
+the error message printed by the server's child process if it cannot
+<kbd>exec</kbd> the service program is not lost.
+<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
+either if neither <code>read</code> nor <code>write</code> is specified. If a
+particular descriptor not specified by the client then it will be open
+onto <code>/dev/null</code> (for reading, writing, or both, depending on
+whether <code>read</code>, <code>write</code> or neither was specified).
+<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
+reading resp. writing, or both if neither <code>read</code> nor <code>write</code>
+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.
+<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
+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).
+<dt><code>ignore-fd </code><var>fd-range</var><code></code><dd>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.
+<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
+client disconnects before the main service process terminates.
+<kbd>no-disconnect-hup</kbd> cancels <kbd>disconnect-hup</kbd>.<P>
+
+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 <kbd>SIGHUP</kbd> will be delivered <em>before</em> 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.
+<dt><code>reset</code><dd>Resets the execution settings to the default. This is equivalent to:
+<pre>cd ~/
+reject
+no-set-environment
+suppress-args
+allow-fd 0 read
+allow-fd 1-2 write
+reject-fd 3-
+disconnect-hup</pre>
+</dl>
+
+
+If no <kbd>execute</kbd>, <kbd>execute-from-path</kbd>,
+<kbd>execute-from-directory</kbd> or <kbd>builtin</kbd> is interpreted before
+all the files are read then the request is rejected.
+
+<hr>
+<h2><A name="s-configerrors">
+4.3 Errors in the configuration file
+</A></h2>
+
+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 <kbd>errors-</kbd> family
+of directives, above).<P>
+
+The error will cause processing of the configuration files to cease at
+that point, unless the error was inside a <kbd>catch-quit</kbd> construct.
+In this case the settings controlling the program's execution will be
+reset to the defaults as if a <kbd>reset</kbd> directive had been issued,
+and parsing continues after <kbd>hctac</kbd>.
+
+<hr>
+<h2><A name="s-defaults">
+4.4 Defaults
+</A></h2>
+
+The default configuration processing is as if the daemon were parsing
+an overall configuration file whose contents were as follows:
+
+<pre>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 <var>file specified by most recent user-rcfile directive</var>
+ hctac
+ srorre
+fi
+include /etc/userv/system.override
+quit</pre><P>
+
+If one of the <kbd>--override</kbd> options to the client is used then it
+will instead be as if the daemon were parsing an overall configuration
+as follows:
+
+<pre>reset
+errors-to-stderr
+include <var>file containing configuration data sent by client</var>
+quit</pre>
+
+<hr>
+User service daemon and client specification
+- <A href="index.html#copyright"><kbd>userv</kbd> is Copyright 1996-1999 Ian Jackson.</A>
+<br>
+<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>.
+<br>
+<address>0.61.1<br>
+Ian Jackson <A href="mailto:ian@davenant.greenend.org.uk">ian@davenant.greenend.org.uk</A></address>
+</body></html>
~ian / userv.git / blobdiff