-<html><head>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+
+<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>
+
+</head>
+
+<body>
+
+<hr>
+
+[<a href="ch-envir.html">back</a>]
+ [<a href="index.html#abstract">Abstract</a>]
+ [<a href="index.html#copyright">Copyright Notice</a>]
+ [<a href="index.html#contents">Contents</a>]
+ [<a href="ch-ipass.html">next</a>]
+
+<hr>
+
<h1>
-User service daemon and client specification - chapter 4<br>
+User service daemon and client specification - Chapter 4<br>
Service-side configuration
</h1>
+<hr>
+
+<p>
Which services may be run by whom and under what conditions is
-controlled by configuration files.<P>
+controlled by configuration files.
+</p>
+<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>
+client or specifying which program to execute to provide the service.
+</p>
+<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>
+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
+<p>
+The daemon will first read <samp>/etc/userv/system.default</samp>. 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>
+<samp>~/.userv/rc</samp>, if it exists and the service user's shell is in
+<samp>/etc/shells</samp>. Finally it will read
+<samp>/etc/userv/system.override</samp>.
+</p>
+<p>
When it has read all of these files it will act according to the
currently values of of the execution settings.
+</p>
+
<hr>
-<h2><A name="s4.1">
-4.1 Configuration file syntax
-</A></h2>
+<h2>
+<a name="s4.1">4.1 Configuration file syntax</a>
+</h2>
+
+<p>
The configuration file is a series of directives, usually one per
-line. The portion of a line following a hash character <code>#</code> is
+line. The portion of a line following a hash character <samp>#</samp> 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
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>
+<dt><samp>\n</samp><dd>newline
+
+<dt><samp>\t</samp><dd>tab
+
+<dt><samp>\r</samp><dd>carriage return
+
+<dt><samp>\<var>OOO</var></samp><dd>character whose octal code is <var>OOO</var>
+<dt><samp>\x<var>XX</var></samp><dd>character whose hex code is <var>XX</var>
+
+<dt><samp>\<var>punctuation</var></samp><dd>literal punctuation character (eg <samp>\\</samp>, <samp>\"</samp>)
+
+<dt><samp>\<var>newline</var></samp> (ie, backslash at end of line)<dd>string continues on next line
+
+</dl>
+</p>
+
+<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
+Pathnames starting with the two characters <samp>~/</samp> are taken to be
relative to the service user's home directory.
+</p>
+
<hr>
-<h2><A name="s-directives">
-4.2 Configuration file directives
-</A></h2>
+
+<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>
+<h3>
+<a name="s-dirs-immediate">4.2.1 Immediate directives</a>
+</h3>
+
+<p>
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>
+<p><dt><samp>cd <var>pathname</var></samp><dd>Change directory in the service program. <code>cd</code> is cumulative. It
+is an error if the directory cannot be changed to.
-<kbd>cd</kbd> should not be used between <kbd>execute-from-directory</kbd> and
+<code>cd</code> should not be used between <code>execute-from-directory</code> 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
+
+<p><dt><samp>eof</samp><dd>Stop reading the configuration file in question, as if end of file had
+been reached. Any control constructs (<code>if</code>, <code>catch-quit</code> or
+<code>errors-push</code>) 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
+containing the <code>eof</code> to be read.
+
+<p><dt><samp>quit</samp><dd>Stop reading configuration files and act immediately on the current
+settings. The behaviour of <code>quit</code> is subject to the
+<code>catch-quit</code> control construct.
+
+<p><dt><samp>include <var>filename</var></samp><p><dt><samp>include-ifexist <var>filename</var></samp><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>
+if the file cannot be opened and read, unless <code>include-ifexist</code>
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>
+
+<p><dt><samp>include-lookup <var>parameter</var> <var>directory</var></samp><p><dt><samp>include-lookup-all <var>parameter</var> <var>directory</var></samp><dd>Read the configuration file in <var>directory</var> whose name is the value
+of <var>parameter</var> (see the description of <code>if</code>, <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 <code>include-lookup</code> this search will stop
+when one is found, but with <code>include-lookup-all</code> 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 <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>
+file <samp>:default</samp> will be read, if it exists. If <var>parameter</var>'s
+list of values was empty then the file <samp>:none</samp> will be tried first
+and read if it exists, otherwise <samp>:default</samp> will be tried.
-It is not an error for any of the files (including <code>:default</code>) not
+It is not an error for any of the files (including <samp>:default</samp>) 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
+a colon prepended (making <samp>:.</samp>), colons will be doubled, and each
+slash will be replaced with a colon followed by a hyphen <samp>:-</samp>. 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
+<samp>:empty</samp> (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
+
+<p><dt><samp>include-directory <var>directory</var></samp><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
+
+<p><dt><samp>error <var>text ...</var></samp><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
(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
+
+<p><dt><samp>message <var>text ...</var></samp><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>
+an error.
+
+</dl>
+</p>
<hr>
-<h3><A name="s-dirs-delayed">
-4.2.2 Directives with delayed effect
-</A></h3>
+<h3>
+<a name="s-dirs-delayed">4.2.2 Directives with delayed effect</a>
+</h3>
+
+<p>
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;
+<p><dt><samp>user-rcfile <var>filename</var></samp><dd>Specifies that the file <var>filename</var> should be read instead of the
+user's <samp>~/.userv/rc</samp>. 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
+<code>system.default</code> 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
+<code>system.override</code> 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
+
+<p><dt><samp>errors-to-stderr</samp><dd>Causes error messages to be delivered to the client's stderr.
+
+<p><dt><samp>errors-to-file</samp> <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>
+
+<p><dt><samp>errors-to-syslog</samp> [<var>facility</var> [<var>level</var>]]<dd>Error messages will be delivered using <code>syslog</code>. The default
+<var>facility</var> is <samp>user</samp>; the default <var>level</var> is <samp>error</samp>.
+
+</dl>
+</p>
<hr>
-<h3><A name="s-dirs-control">
-4.2.3 Control structure directives
-</A></h3>
+<h3>
+<a name="s-dirs-control">4.2.3 Control structure directives</a>
+</h3>
+
+<p>
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
+<p><dt><samp>if <var>condition</var></samp><p><dt><samp>elif <var>condition</var></samp><p><dt><samp>else</samp><p><dt><samp>fi</samp><dd>Lines following <code>if</code> 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>
+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
+<dt><samp>glob <var>parameter</var> <var>glob-pattern</var> ...</samp><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
+
+<dt><samp>range <var>parameter</var> <var>min</var> <var>max</var></samp><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 <samp>$</samp> 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
+
+<dt><samp>grep <var>parameter</var> <var>filename</var></samp><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>
+
+<dt><samp>! <var>condition</var></samp><dd>The <var>condition</var> is <em>not</em> true.
+
+<dt>Conjunctions: <samp>&</samp> and <samp>|</samp><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
+)
+</pre>
+
+is true if all the listed conditions are true; where <samp>|</samp> 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>
+These conjunctions do not do lazy evaluation.
+
+</dl>
+</p>
+<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
+<dt><samp>service</samp><dd>The service name specified when the client was called.
+
+<dt><samp>calling-user</samp><dd>Two strings: the login name of the calling user (determined as for
+<code>USERV_USER</code>, above) and the calling uid (represented in
decimal).
-<dt><code>calling-group</code><dd>Several strings: the primary and supplementary group names and gids
+
+<dt><samp>calling-group</samp><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)
+
+<dt><samp>calling-user-shell</samp><dd>The calling user's shell, as listed in the password entry for the
+calling login name (as determined for <code>USERV_USER</code>, above).
+
+<dt><samp>service-user</samp><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
+
+<dt><samp>service-group</samp><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
+
+<dt><samp>service-user-shell</samp><dd>The service user's shell, as listed in their password entry.
+
+<dt><samp>u-<var>name</var></samp><dd>The value of the user-defined variable <var>name</var> passed by the caller
+using the <code>--defvar</code> 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.
+<samp>include-lookup</samp> on it will read the <samp>:none</samp> file, or
+<samp>:default</samp> if <samp>:none</samp> is not found.
+
</dl>
+</p>
+
+<dt><samp>errors-push</samp> <var>filename</var><dt><samp>srorre</samp><dd>Stacks the error handling behaviour currently in effect. Any changes
+to error handling will take effect only between <code>errors-push</code> and
+<code>srorre</code>.
-<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>
+<dt><samp>catch-quit</samp><dt><samp>hctac</samp><dd>Any use of <code>quit</code> inside <code>catch-quit</code> will merely cause the
+parsing to continue at <code>hctac</code> instead. Any control constructs
+started since the <code>catch-quit</code> will be considered finished if a
+<code>quit</code> is found.
-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 an error occurs inside <code>catch-quit</code> the execution settings
+will be reset (as if by the <code>reset</code> directive) and parsing will
+likewise continue at <code>hctac</code>.
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.
+file as the <code>catch-quit</code>, while looking for the <code>hctac</code>
+after an error or <code>quit</code>, that new error will not be caught.
+
</dl>
+</p>
<hr>
-<h3><A name="s-dirs-execution">
-4.2.4 Directives for changing execution settings
-</A></h3>
+<h3>
+<a name="s-dirs-execution">4.2.4 Directives for changing execution settings</a>
+</h3>
+
+<p>
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,
+<p><dt><samp>reject</samp><dd>Reject the request. <code>execute</code>, <code>execute-from-directory</code> and
+<code>execute-from-path</code> will change this setting.
+
+<p><dt><samp>execute <var>program</var> [<var>argument</var> ...]</samp><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
+<code>no-suppress-args</code> 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
+
+<p><dt><samp>execute-from-directory <var>pathname</var> [<var>argument</var> ...]</samp><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>
+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).<P>
+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).
-<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
+
+<p><dt><samp>execute-from-path</samp><dd><var>service</var> is interpreted as a program on the default <code>PATH</code>
+(or as a pathname of an executable, if it contains a <samp>/</samp>). 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.
+<code>--override</code> 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
+
+<p><dt><samp>execute-builtin <var>service-name</var> <var>service-arguments</var></samp><dd><p>
+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
builtin services are:
<dl compact>
-<dt><code>execute</code><dd>Displays the execution settings, defined variables,
+<dt><samp>execute</samp><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
+
+<dt><samp>environment</samp><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
+
+<dt><samp>parameter <var>parameter</var></samp><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
+
+<dt><samp>version</samp><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>
+
+<dt><samp>reset</samp><dd>Displays the default reset configuration (evaluated when <code>reset</code>
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,
+<code>catch-quit</code>).
+
+<dt><samp>toplevel</samp><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,
+
+<dt><samp>override</samp><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>
+<dt><samp>help</samp><dd>Displays a list of the understood builtin service names and arguments.
-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.
+<dt><samp>shutdown</samp><dd>Arranges for the <code>uservd</code> to shut down. Available only when the
+service user is root. This only affects new requests; it doesn't
+terminate any currently-running requests
+
+</dl>
+</p>
+
+<dt><samp>set-environment</samp><dt><samp>no-set-environment</samp><dd>Runs <samp>/etc/environment</samp> 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>
+<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.
+<pre>
+/bin/sh -c '. /etc/environment; exec "$@"' - .../program arg arg arg ...
+</pre>
+
+<code>no-set-environment</code> cancels the effect of
+<code>set-environment</code>.
+
+<dt><samp>no-suppress-args</samp><dt><samp>suppress-args</samp><dd>Include any arguments given to the client as arguments to the program
+invoked as a result of an <code>execute</code>,
+<code>execute-from-directory</code> or <code>execute-from-path</code> directive.
+<code>suppress-args</code> undoes the effect of <code>no-suppress-args</code>.
+
+<dt><samp>require-fd <var>fd-range</var> read|write</samp><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>
+separate setting, and the last one of <code>require-fd</code>,
+<code>allow-fd</code>, <code>ignore-fd</code>, <code>null-fd</code> or <code>reject-fd</code>
+which affected a particular file descriptor will take effect.
<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>,
+<samp>stdin</samp>, <samp>stdout</samp> or <samp>stderr</samp>. Open-ended file descriptor
+rangers are allowed only with <code>reject-fd</code> and <code>ignore-fd</code>,
as otherwise the service program would find itself with a very large
-number of file descriptors open.<P>
+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
-(<kbd>require-fd</kbd> or <kbd>allow-fd</kbd>) for writing; this is so that
+(<code>require-fd</code> or <code>allow-fd</code>) 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
+<code>exec</code> the service program is not lost.
+
+<dt><samp>allow-fd <var>fd-range</var> [read|write]</samp><dd>Allow the descriptor(s) to be opened for reading resp. writing, or
+either if neither <samp>read</samp> nor <samp>write</samp> 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>
+onto <samp>/dev/null</samp> (for reading, writing, or both, depending on
+whether <samp>read</samp>, <samp>write</samp> or neither was specified).
+
+<dt><samp>null-fd <var>fd-range</var> [read|write]</samp><dd>Specify that the descriptor(s) be opened onto <code>/dev/null</code> for
+reading resp. writing, or both if neither <samp>read</samp> nor <samp>write</samp>
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
+
+<dt><samp>reject-fd <var>fd-range</var></samp><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
+
+<dt><samp>ignore-fd <var>fd-range</var></samp><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
+
+<dt><samp>disconnect-hup</samp><dt><samp>no-disconnect-hup</samp><dd>Causes the service's process group to get a <code>SIGHUP</code> if the
client disconnects before the main service process terminates.
-<kbd>no-disconnect-hup</kbd> cancels <kbd>disconnect-hup</kbd>.<P>
+<code>no-disconnect-hup</code> cancels <code>disconnect-hup</code>.
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
+reason, then the <code>SIGHUP</code> 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 ~/
+
+<dt><samp>reset</samp><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>
+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
+If no <code>execute</code>, <code>execute-from-path</code>,
+<code>execute-from-directory</code> or <code>builtin</code> is interpreted before
all the files are read then the request is rejected.
+</p>
<hr>
-<h2><A name="s-configerrors">
-4.3 Errors in the configuration file
-</A></h2>
+<h2>
+<a name="s-configerrors">4.3 Errors in the configuration file</a>
+</h2>
+
+<p>
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>
+error messages are currently being sent (see the <code>errors-</code> family
+of directives, above).
+</p>
+<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.
+that point, unless the error was inside a <code>catch-quit</code> 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>.
+reset to the defaults as if a <code>reset</code> directive had been issued,
+and parsing continues after <code>hctac</code>.
+</p>
<hr>
-<h2><A name="s-defaults">
-4.4 Defaults
-</A></h2>
+<h2>
+<a name="s-defaults">4.4 Defaults</a>
+</h2>
+
+<p>
The default configuration processing is as if the daemon were parsing
an overall configuration file whose contents were as follows:
-<pre>reset
+<pre>
+reset
user-rcfile ~/.userv/rc
errors-to-stderr
include /etc/userv/system.default
srorre
fi
include /etc/userv/system.override
-quit</pre><P>
+quit
+</pre>
+</p>
-If one of the <kbd>--override</kbd> options to the client is used then it
+<p>
+If one of the <code>--override</code> options to the client is used then it
will instead be as if the daemon were parsing an overall configuration
as follows:
-<pre>reset
+<pre>
+reset
errors-to-stderr
include <var>file containing configuration data sent by client</var>
-quit</pre>
+quit
+</pre>
+</p>
+
+<hr>
+
+[<a href="ch-envir.html">back</a>]
+ [<a href="index.html#abstract">Abstract</a>]
+ [<a href="index.html#copyright">Copyright Notice</a>]
+ [<a href="index.html#contents">Contents</a>]
+ [<a href="ch-ipass.html">next</a>]
<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>
+
+User service daemon and client specification<br>
+
+<address>
+0.62<br>
+Ian Jackson <a href="mailto:ian@davenant.greenend.org.uk">ian@davenant.greenend.org.uk</a>
+</address>
+
+</body>
+
+</html>
+
~ian / userv.git / blobdiff