-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html>
<head>
+<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
+
<title>User service daemon and client specification - Service-side configuration</title>
</head>
<body>
+<a name="ch-config"></a>
<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>]
+[ <a href="ch-envir.html">previous</a> ]
+[ <a href="index.html#contents">Contents</a> ]
+[ <a href="ch-intro.html">1</a> ]
+[ <a href="ch-client.html">2</a> ]
+[ <a href="ch-envir.html">3</a> ]
+[ 4 ]
+[ <a href="ch-ipass.html">5</a> ]
+[ <a href="ch-notes.html">6</a> ]
+[ <a href="ch-ipass.html">next</a> ]
<hr>
<h1>
-User service daemon and client specification - Chapter 4<br>
-Service-side configuration
+User service daemon and client specification
+<br>Chapter 4 - Service-side configuration
</h1>
+
<hr>
+
<p>
-Which services may be run by whom and under what conditions is
-controlled by configuration files.
-</p>
+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 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>
+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 <samp>/etc/userv/system.default</samp>. Then, by
<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>
+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>
+<a name="s4.1"></a>
+<h2>4.1 Configuration file syntax</h2>
<p>
-The configuration file is a series of directives, usually one per
-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
-required, a string in double quotes. Double-quoted strings may
-contain the following backslash escapes:
-
-<dl compact>
-<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
-
+The configuration file is a series of directives, usually one per 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 required, a string in double
+quotes. Double-quoted strings may contain the following backslash escapes:
+<dl>
+<dt><samp>\n</samp></dt>
+<dd>
+newline
+</dd>
+<dt><samp>\t</samp></dt>
+<dd>
+tab
+</dd>
+<dt><samp>\r</samp></dt>
+<dd>
+carriage return
+</dd>
+<dt><samp>\<var>OOO</var></samp></dt>
+<dd>
+character whose octal code is <var>OOO</var>
+</dd>
+<dt><samp>\x<var>XX</var></samp></dt>
+<dd>
+character whose hex code is <var>XX</var>
+</dd>
+<dt><samp>\<var>punctuation</var></samp></dt>
+<dd>
+literal punctuation character (eg <samp>\\</samp>, <samp>\"</samp>)
+</dd>
+<dt><samp>\<var>newline</var></samp> (ie, backslash at end of line)</dt>
+<dd>
+string continues on next line
+</dd>
</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 <samp>~/</samp> are taken to be
-relative to the service user's home directory.
-</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 <samp>~/</samp> 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>
+<a name="s-directives"></a>
+<h2>4.2 Configuration file directives</h2>
<hr>
-<h3>
-<a name="s-dirs-immediate">4.2.1 Immediate directives</a>
-</h3>
+<a name="s-dirs-immediate"></a>
+<h3>4.2.1 Immediate directives</h3>
<p>
The following directives take effect immediately:
-
<dl>
-<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.
-
-<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).
+<dt><samp>cd <var>pathname</var></samp></dt>
+<dd>
+Change directory in the service program. <code>cd</code> is cumulative. It is
+an error if the directory cannot be changed to.
-<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
+<p>
+<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).
+</dd>
+</dl>
+<dl>
+<dt><samp>eof</samp></dt>
+<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 <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 <code>include-ifexist</code>
-is used and the file does not exist, in which case the directive is
-silently ignored.
-
-<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 <samp>:default</samp> will be read, if it exists. If <var>parameter</var>'s
+finished. Parsing will continue in the file which caused the file containing
+the <code>eof</code> to be read.
+</dd>
+</dl>
+<dl>
+<dt><samp>quit</samp></dt>
+<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.
+</dd>
+</dl>
+<dl>
+<dt><samp>include <var>filename</var></samp></dt>
+<dt><samp>include-ifexist <var>filename</var></samp></dt>
+<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 <code>include-ifexist</code> is used and the
+file does not exist, in which case the directive is silently ignored.
+</dd>
+</dl>
+<dl>
+<dt><samp>include-lookup <var>parameter</var> <var>directory</var></samp></dt>
+<dt><samp>include-lookup-all <var>parameter</var> <var>directory</var></samp></dt>
+<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="ch-config.html#s-dirs-control">Control structure directives, Section
+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.
+
+<p>
+If none of the parameter's values had a corresponding file then the 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.
+<p>
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.
-
-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 <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
-<samp>:empty</samp> (note that this is different from a parameter not having
-any values).
-
-<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><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
-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><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.
-
-</dl>
-</p>
+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 <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 <samp>:empty</samp> (note that
+this is different from a parameter not having any values).
+</dd>
+</dl>
+<dl>
+<dt><samp>include-directory <var>directory</var></samp></dt>
+<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.
+</dd>
+</dl>
+<dl>
+<dt><samp>error <var>text ...</var></samp></dt>
+<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.
+</dd>
+</dl>
+<dl>
+<dt><samp>message <var>text ...</var></samp></dt>
+<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.
+</dd>
+</dl>
<hr>
-<h3>
-<a name="s-dirs-delayed">4.2.2 Directives with delayed effect</a>
-</h3>
+<a name="s-dirs-delayed"></a>
+<h3>4.2.2 Directives with delayed effect</h3>
<p>
-The following directives have no immediate effect, but are remembered
-and have an effect on later processing of the configuration files.
-
+The following directives have no immediate effect, but are remembered and have
+an effect on later processing of the configuration files.
<dl>
-<p><dt><samp>user-rcfile <var>filename</var></samp><dd>Specifies that the file <var>filename</var> should be read instead of the
+<dt><samp>user-rcfile <var>filename</var></samp></dt>
+<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
-<code>system.default</code> configuration file has been read. This
-directive has no effect in a user's configuration file or in the
-<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><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><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>.
-
+<code>system.default</code> configuration file has been read. This directive
+has no effect in a user's configuration file or in the
+<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.
+</dd>
+</dl>
+<dl>
+<dt><samp>errors-to-stderr</samp></dt>
+<dd>
+Causes error messages to be delivered to the client's stderr.
+</dd>
+</dl>
+<dl>
+<dt><samp>errors-to-file</samp> <var>filename</var></dt>
+<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.
+</dd>
+</dl>
+<dl>
+<dt><samp>errors-to-syslog</samp> [<var>facility</var> [<var>level</var>]]</dt>
+<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>.
+</dd>
</dl>
-</p>
<hr>
-<h3>
-<a name="s-dirs-control">4.2.3 Control structure directives</a>
-</h3>
+<a name="s-dirs-control"></a>
+<h3>4.2.3 Control structure directives</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.
-
+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>
-<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.
+<dt><samp>fi</samp></dt>
+<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>
The conditions are:
-
-<dl compact>
-<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><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
+<dl>
+<dt><samp>glob <var>parameter</var> <var>glob-pattern</var> ...</samp></dt>
+<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).
+</dd>
+<dt><samp>range <var>parameter</var> <var>min</var> <var>max</var></samp></dt>
+<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><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><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>
-...
-)
+</dd>
+<dt><samp>grep <var>parameter</var> <var>filename</var></samp></dt>
+<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.
+</dd>
+<dt><samp>! <var>condition</var></samp></dt>
+<dd>
+The <var>condition</var> is <em>not</em> true.
+</dd>
+<dt>Conjunctions: <samp>&</samp> and <samp>|</samp></dt>
+<dd>
+<pre>
+ ( <var>condition</var>
+ & <var>condition</var>
+ & <var>condition</var>
+ ...
+ )
</pre>
-
+<p>
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.
-
+condition from the next, as shown, and the parentheses are mandatory. These
+conjunctions do not do lazy evaluation.
+</dd>
</dl>
-</p>
<p>
The parameters are:
-
-<dl compact>
-<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><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><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><samp>service-group</samp><dd>Several strings: the primary and supplementary group names and gids
-(in decimal) of the service user.
-
-<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
+<dl>
+<dt><samp>service</samp></dt>
+<dd>
+The service name specified when the client was called.
+</dd>
+<dt><samp>calling-user</samp></dt>
+<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).
+</dd>
+<dt><samp>calling-group</samp></dt>
+<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.
+</dd>
+<dt><samp>calling-user-shell</samp></dt>
+<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).
+</dd>
+<dt><samp>service-user</samp></dt>
+<dd>
+Two strings: the name of the service user (as specified to the client) and
+their uid (represented in decimal).
+</dd>
+<dt><samp>service-group</samp></dt>
+<dd>
+Several strings: the primary and supplementary group names and gids (in
+decimal) of the service user.
+</dd>
+<dt><samp>service-user-shell</samp></dt>
+<dd>
+The service user's shell, as listed in their password entry.
+</dd>
+<dt><samp>u-<var>name</var></samp></dt>
+<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
+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
<samp>include-lookup</samp> on it will read the <samp>:none</samp> file, or
<samp>:default</samp> if <samp>:none</samp> is not found.
-
+</dd>
</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
+</dd>
+</dl>
+<dl>
+<dt><samp>errors-push</samp> <var>filename</var></dt>
+<dt><samp>srorre</samp></dt>
+<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><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
+</dd>
+</dl>
+<dl>
+<dt><samp>catch-quit</samp></dt>
+<dt><samp>hctac</samp></dt>
+<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 <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 <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.
+<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>.
+<p>
+If a lexical or syntax error is detected in the same configuration 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.
+</dd>
</dl>
-</p>
<hr>
-<h3>
-<a name="s-dirs-execution">4.2.4 Directives for changing execution settings</a>
-</h3>
+<a name="s-dirs-execution"></a>
+<h3>4.2.4 Directives for changing execution settings</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.
-
+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>
-<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
-<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><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.
-
-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).
+<dt><samp>reject</samp></dt>
+<dd>
+Reject the request. <code>execute</code>, <code>execute-from-directory</code>
+and <code>execute-from-path</code> will change this setting.
+</dd>
+</dl>
+<dl>
+<dt><samp>execute <var>program</var> [<var>argument</var> ...]</samp></dt>
+<dd>
+Execute the program <var>program</var>, with the arguments as specified,
+followed by any arguments given to the client if <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.
+</dd>
+</dl>
+<dl>
+<dt><samp>execute-from-directory <var>pathname</var> [<var>argument</var> ...]</samp></dt>
+<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.
-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>
+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><dt><samp>execute-from-path</samp><dd><var>service</var> is interpreted as a program on the default <code>PATH</code>
+<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).
+</dd>
+</dl>
+<dl>
+<dt><samp>execute-from-path</samp></dt>
+<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
-<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><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
-standard output (i.e., wherever file descriptor 1 is directed). The
-builtin services are:
-
-<dl compact>
-<dt><samp>execute</samp><dd>Displays the execution settings, defined variables,
-arguments, etc. with which the builtin service was invoked.
-
-<dt><samp>environment</samp><dd>Displays the environment variable settings with which the builtin
-service was invoked.
-
-<dt><samp>parameter <var>parameter</var></samp><dd>Displays the values of the service configuration language parameter
-specified.
-
-<dt><samp>version</samp><dd>Displays the version string and compilation details of the uservd
-server program.
-
-<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
+<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).
+</dd>
+</dl>
+<dl>
+<dt><samp>execute-builtin <var>service-name</var> <var>service-arguments</var></samp></dt>
+<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>
+<dt><samp>execute</samp></dt>
+<dd>
+Displays the execution settings, defined variables, arguments, etc. with which
+the builtin service was invoked.
+</dd>
+<dt><samp>environment</samp></dt>
+<dd>
+Displays the environment variable settings with which the builtin service was
+invoked.
+</dd>
+<dt><samp>parameter <var>parameter</var></samp></dt>
+<dd>
+Displays the values of the service configuration language parameter specified.
+</dd>
+<dt><samp>version</samp></dt>
+<dd>
+Displays the version string and compilation details of the uservd server
+program.
+</dd>
+<dt><samp>reset</samp></dt>
+<dd>
+Displays the default reset configuration (evaluated when <code>reset</code> is
+found in a configuration file, or when an error is caught by
<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><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><samp>help</samp><dd>Displays a list of the understood builtin service names and arguments.
-
+</dd>
+<dt><samp>toplevel</samp></dt>
+<dd>
+Displays the top-level default configuration (the configuration data, evaluated
+by the server, which calls all the other configuration files).
+</dd>
+<dt><samp>override</samp></dt>
+<dd>
+Displays the top-level override configuration (the configuration data,
+evaluated by the server, which causes all the other configuration data to be
+parsed).
+</dd>
+<dt><samp>help</samp></dt>
+<dd>
+Displays a list of the understood builtin service names and arguments.
+</dd>
</dl>
+<p>
+In the future other builtin services may be defined which do more than just
+print information.
+</dd>
+</dl>
+<dl>
+<dt><samp>set-environment</samp></dt>
+<dt><samp>no-set-environment</samp></dt>
+<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
-In the future other builtin services may be defined which do more than
-just print information.
-</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 ...
+ .../program arg arg arg ...
</pre>
+<p>
as
+
<pre>
-/bin/sh -c '. /etc/environment; exec "$@"' - .../program arg arg arg ...
+ /bin/sh -c '. /etc/environment; exec "$@"' - .../program arg arg arg ...
</pre>
+<p>
<code>no-set-environment</code> cancels the effect of
<code>set-environment</code>.
+</dd>
+</dl>
+<dl>
+<dt><samp>no-suppress-args</samp></dt>
+<dt><samp>suppress-args</samp></dt>
+<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>.
+</dd>
+</dl>
+<dl>
+<dt><samp>require-fd <var>fd-range</var> read|write</samp></dt>
+<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 <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.
-<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 <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
-<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.
-
-When the configuration has been parsed, and before the service is
-about to be executed, stderr (fd 2) must be required or allowed
-(<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
-<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 <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><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><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.
+<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 <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.
-<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.
+<p>
+When the configuration has been parsed, and before the service is about to be
+executed, stderr (fd 2) must be required or allowed (<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 <code>exec</code> the service
+program is not lost.
+</dd>
+</dl>
+<dl>
+<dt><samp>allow-fd <var>fd-range</var> [read|write]</samp></dt>
+<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
+<samp>/dev/null</samp> (for reading, writing, or both, depending on whether
+<samp>read</samp>, <samp>write</samp> or neither was specified).
+</dd>
+</dl>
+<dl>
+<dt><samp>null-fd <var>fd-range</var> [read|write]</samp></dt>
+<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.
+</dd>
+</dl>
+<dl>
+<dt><samp>reject-fd <var>fd-range</var></samp></dt>
+<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).
+</dd>
+</dl>
+<dl>
+<dt><samp>ignore-fd <var>fd-range</var></samp></dt>
+<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.
+</dd>
+</dl>
+<dl>
+<dt><samp>disconnect-hup</samp></dt>
+<dt><samp>no-disconnect-hup</samp></dt>
+<dd>
+Causes the service's process group to get a <code>SIGHUP</code> if the client
+disconnects before the main service process terminates.
<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 <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.
+<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
+<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.
+</dd>
+</dl>
+<dl>
+<dt><samp>reset</samp></dt>
+<dd>
+Resets the execution settings to the default. This is equivalent to:
-<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
+ cd ~/
+ reject
+ no-set-environment
+ suppress-args
+ allow-fd 0 read
+ allow-fd 1-2 write
+ reject-fd 3-
+ disconnect-hup
</pre>
-
+</dd>
</dl>
-
+<p>
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>
+<code>execute-from-directory</code> or <code>builtin</code> 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>
+<a name="s-configerrors"></a>
+<h2>4.3 Errors in the configuration file</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 <code>errors-</code> family
-of directives, above).
-</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 <code>errors-</code> 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 <code>catch-quit</code> construct.
-In this case the settings controlling the program's execution will be
-reset to the defaults as if a <code>reset</code> directive had been issued,
-and parsing continues after <code>hctac</code>.
-</p>
+The error will cause processing of the configuration files to cease at 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 <code>reset</code> directive had been issued, and parsing
+continues after <code>hctac</code>.
<hr>
-<h2>
-<a name="s-defaults">4.4 Defaults</a>
-</h2>
+<a name="s-defaults"></a>
+<h2>4.4 Defaults</h2>
<p>
-The default configuration processing is as if the daemon were parsing
-an overall configuration file whose contents were as follows:
+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
+ 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>
<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:
+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
+ reset
+ errors-to-stderr
+ include <var>file containing configuration data sent by client</var>
+ 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>]
+[ <a href="ch-envir.html">previous</a> ]
+[ <a href="index.html#contents">Contents</a> ]
+[ <a href="ch-intro.html">1</a> ]
+[ <a href="ch-client.html">2</a> ]
+[ <a href="ch-envir.html">3</a> ]
+[ 4 ]
+[ <a href="ch-ipass.html">5</a> ]
+[ <a href="ch-notes.html">6</a> ]
+[ <a href="ch-ipass.html">next</a> ]
<hr>
-User service daemon and client specification<br>
+<p>
+User service daemon and client specification
<address>
-0.95.0<br>
-Ian Jackson <a href="mailto:ian@davenant.greenend.org.uk">ian@davenant.greenend.org.uk</a>
+1.0.3<br>
+Ian Jackson <code><a href="mailto:ian@davenant.greenend.org.uk">ian@davenant.greenend.org.uk</a></code>
</address>
+<hr>
+
</body>
</html>
~ian / userv.git / blobdiff