+userv (1.0.7) unstable; urgency=low
+
+ * Remove spec.html from revision control.
+
+ --
+
userv (1.0.6) unstable; urgency=low
Packaging fix:
+++ /dev/null
-<!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 - Client program usage</title>
-
-</head>
-
-<body>
-
-<a name="ch-client"></a>
-<hr>
-
-[ <a href="ch-intro.html">previous</a> ]
-[ <a href="index.html#contents">Contents</a> ]
-[ <a href="ch-intro.html">1</a> ]
-[ 2 ]
-[ <a href="ch-envir.html">3</a> ]
-[ <a href="ch-config.html">4</a> ]
-[ <a href="ch-ipass.html">5</a> ]
-[ <a href="ch-notes.html">6</a> ]
-[ <a href="ch-envir.html">next</a> ]
-
-<hr>
-
-<h1>
-User service daemon and client specification
-<br>Chapter 2 - Client program usage
-</h1>
-
-
-<pre>
- userv <var>options</var> [--] <var>service-user</var> <var>service-name</var> [<var>argument</var> ...]
- userv <var>options</var> -B|--builtin [--] <var>builtin-service</var> [<var>info-argument</var> ...]
-</pre>
-
-<hr>
-
-
-<p>
-<var>service-user</var> specifies which user is to provide the service. The
-user may be a login name or a numeric uid, or <samp>-</samp> to indicate that
-the service user is to be the same as the calling user.
-
-<p>
-The service name is interpreted by the userv[<a href="footnotes.html#f1"
-name="fr1">1</a>] daemon on behalf of the service user. It will often be the
-name of a program.
-
-<hr>
-
-<a name="s2.1"></a>
-<h2>2.1 Options</h2>
-
-<p>
-Single-letter options may be combined as is usual with Unix programs, and the
-value for such an option may appear in the same argument or in the next.
-<dl>
-<dt><samp>-B</samp></dt>
-<dt><samp>--builtin</samp></dt>
-<dd>
-Requests that a builtin service be provided. This is equivalent to using the
-<code>--override</code> option to specify a string consisting of
-<code>execute-builtin</code> followed by the <var>builtin-service</var>
-requested, and requesting a service user of <samp>-</samp> (indicating the
-calling user).
-
-<p>
-If the builtin service being requested requires a <var>service-argument</var>
-then this must be supplied to the client in the same argument as the
-<var>builtin-service</var>. See <a
-href="ch-config.html#s-dirs-execution">Directives for changing execution
-settings, Section 4.2.4</a> for details of the builtin services available, and
-<a href="ch-client.html#s-optoverride">Security-overriding options, Section
-2.2</a> for details of the <code>--override</code> options.
-
-<p>
-The actual service name passed will be the <var>builtin-service</var>; note
-that this actual service name (as opposed to the override data) and the
-<var>info-argument</var>s supplied will be ignored by most builtin services;
-the override mechanism and <code>execute-builtin</code> will be used to ensure
-that the right builtin service is called with the right
-<var>service-argument</var>s.
-</dd>
-</dl>
-<dl>
-<dt><samp>--file <var>fd</var>[<var>modifiers</var>]=<var>filename</var></samp></dt>
-<dd>
-Requests that data be copied in and out of the service using pipes. For each
-file or descriptor this will be done by creating a pipe, one end of which is
-passed to the service program and the other end of which is passed to a copy of
-<code>cat</code> invoked by the client; the other file descriptor passed to
-<code>cat</code> will be one inherited by the client program from the caller or
-one opened by the client program on behalf of the caller.
-
-<p>
-The descriptor in the service program that should be connected must be
-specified as <var>fd</var>, either as a decimal number or as one of the strings
-<samp>stdin</samp>, <samp>stdout</samp> or <samp>stderr</samp>. The next
-argument is a filename which will be opened by the client with the privileges
-of the calling user.
-
-<p>
-<var>modifiers</var> is used to specify whether the file or descriptor is to be
-read from or written to. It consists of a series of words separated by commas.
-A comma may separate the <var>modifiers</var> from the <var>fd</var> and is
-required if <var>fd</var> is not numeric.
-
-<p>
-The modifier words are:
-<dl>
-<dt><samp>read</samp></dt>
-<dd>
-<samp>O_RDONLY</samp>: Allow reading and not writing. May not be used with
-<samp>write</samp> or things that imply it.
-</dd>
-<dt><samp>write</samp></dt>
-<dd>
-<samp>O_WRONLY</samp>: Allow writing and not reading. <em>Doesn't truncate or
-create</em> without <samp>truncate</samp> or <samp>create</samp>.
-<samp>write</samp> or things that imply it may not be used with
-<samp>read</samp>.
-</dd>
-<dt><samp>overwrite</samp></dt>
-<dd>
-Equivalent to <samp>write,create,truncate</samp>.
-</dd>
-<dt><samp>create</samp></dt>
-<dt><samp>creat</samp></dt>
-<dd>
-<samp>O_CREAT</samp>: Creates the file if necessary. Implies
-<samp>write</samp>.
-</dd>
-<dt><samp>exclusive</samp></dt>
-<dt><samp>excl</samp></dt>
-<dd>
-<samp>O_EXCL</samp>: Fails if the file already exists. Implies
-<samp>write</samp> and <samp>create</samp>. May not be used with
-<samp>truncate</samp>.
-</dd>
-<dt><samp>truncate</samp></dt>
-<dt><samp>trunc</samp></dt>
-<dd>
-<samp>O_TRUNC</samp>: Truncate any existing file. Implies <samp>write</samp>.
-May not be used with <samp>exclusive</samp>.
-</dd>
-<dt><samp>append</samp></dt>
-<dd>
-<samp>O_APPEND</samp>: All writes will append to the file. Implies
-<samp>write</samp> (but not <samp>create</samp>).
-</dd>
-<dt><samp>sync</samp></dt>
-<dd>
-<samp>O_SYNC</samp>: Do writes synchronously. Implies <samp>write</samp>.
-</dd>
-<dt><samp>wait</samp></dt>
-<dt><samp>nowait</samp></dt>
-<dt><samp>close</samp></dt>
-<dd>
-These modifiers control the behaviour of the client, with respect to the pipes
-carrying data to and from the service, when the service terminates. See below.
-</dd>
-<dt><samp>fd</samp></dt>
-<dd>
-The <var>filename</var> is not a filename but a numeric file descriptor. One
-or both of <samp>read</samp> and <samp>write</samp> must be specified, and no
-other words are allowed. The <var>filename</var> may also be
-<samp>stdin</samp>, <samp>stdout</samp> or <samp>stderr</samp> for file
-descriptor 0, 1 or 2 respectively.
-</dd>
-</dl>
-
-<p>
-If no <var>modifiers</var> which imply <samp>read</samp> or <samp>write</samp>
-are used it is as if <samp>write</samp> had been specified, except that if the
-filedescriptor 0 of the service is being opened (either specified numerically
-or with <samp>stdin</samp>) it is as if <samp>overwrite</samp> had been
-specified (or <samp>write</samp> if only <samp>fd</samp> was specified).
-
-<p>
-The client will also use <samp>O_NOCTTY</samp> when opening files specified by
-the caller, to avoid changing its controlling terminal.
-
-<p>
-By default stdin, stdout and stderr of the service will be connected to the
-corresponding descriptors on the client. Diagnostics from the client and
-daemon will also appear on stderr.
-
-<p>
-If <samp>wait</samp> is specified, the client will wait for the pipe to be
-closed, and only exit after this has happened. This means that either the
-receiving end of the pipe connection was closed while data was still available
-at the sending end, or that the end of file was reached on the reading file
-descriptor. Errors encountered reading or writing in the client at this stage
-will be considered a system error and cause the client to exit with status 255,
-but will not cause disconnection at the service side since the service has
-already exited.
-
-<p>
-If <samp>close</samp> is specified the client will immediately close the pipe
-connection by killing the relevant copy of <code>cat</code>. If the service
-uses the descriptor it will get <code>SIGPIPE</code> (or <code>EPIPE</code>)
-for a writing descriptor or end of file for a reading one; the descriptor
-opened by or passed to the client will also be closed.
-
-<p>
-If <samp>nowait</samp> is specified then the client will not wait and the
-connection will remain open after the client terminates. Data may continue to
-be passed between the inheritors of the relevant descriptor on the service side
-and the corresponding file or descriptor on the client side until either side
-closes their descriptor. This should not usually be specified for stderr (or
-stdout if <samp>--signals stdout</samp> is used) since diagnostics from the
-service side may arrive after the client has exited and be confused with
-expected output.
-
-<p>
-The default is <samp>wait</samp> for writing file descriptors and
-<samp>close</samp> for reading ones.
-</dd>
-</dl>
-<dl>
-<dt><samp>-w<var>fd</var>=<var>action</var></samp></dt>
-<dt><samp>--fdwait<var>fd</var>=<var>action</var></samp></dt>
-<dd>
-Sets the action on termination of the service for the specified file
-descriptor; <var>action</var> must be <samp>wait</samp>, <samp>nowait</samp> or
-<samp>close</samp> as described above. The file descriptor must be specified
-as open when this option is encountered; this option is overridden by any later
-<code>--file</code> or <code>--fdwait</code> option - even by a
-<code>--file</code> which does not specify an action on termination (in this
-case the default will be used, as described above).
-</dd>
-</dl>
-<dl>
-<dt><samp>-D<var>name</var>=<var>value</var></samp></dt>
-<dt><samp>--defvar <var>name</var>=<var>value</var></samp></dt>
-<dd>
-Set a user-defined variable <var>name</var> to <var>value</var>. These
-user-defined variables are made available in the configuration language as the
-parameters <samp>u-<var>name</var></samp> and are passed to the service in
-environment variables <samp>USERV_U_<var>name</var></samp>. <var>name</var>
-may contain only alphanumerics and underscores, and must start with a letter.
-If several definitions are given for the same <var>name</var> then only the
-last is effective.
-</dd>
-</dl>
-<dl>
-<dt><samp>-t <var>seconds</var></samp></dt>
-<dt><samp>--timeout <var>seconds</var></samp></dt>
-<dd>
-Time out the service if it takes longer than <var>seconds</var> seconds (a
-positive integer, in decimal). Timeout will produce a diagnostic on stderr and
-an exit status of 255. If <var>seconds</var> is zero then no timeout will be
-implemented (this is the default).
-</dd>
-</dl>
-<dl>
-<dt><samp>--signals</samp> <var>method</var></dt>
-<dd>
-Affects the handling of the exit status when the service terminates due to a
-signal. (The client will always finish by calling <code>_exit</code>, so that
-only numbers from 0 to 255 can be returned and not the full range of numbers
-and signal indications which can be returned by the <code>wait</code> family of
-system calls.)
-
-<p>
-The <var>method</var> may be one of the following:
-<dl>
-<dt><var>status</var></dt>
-<dd>
-The client's exit status will be <var>status</var>. This will not be
-distinguishable from the service really having exited with code
-<var>status</var>. This method is the default, with a <var>status</var> of
-254.
-</dd>
-<dt><samp>number</samp></dt>
-<dt><samp>number-nocore</samp></dt>
-<dd>
-The client's exit status will be the number of the signal which caused the
-termination of the service. If <samp>number</samp> is used rather than
-<samp>number-nocore</samp> then 128 will be added if the service dumped core.
-<samp>number</samp> is very like the exit code mangling done by the Bourne
-shell.
-</dd>
-<dt><samp>highbit</samp></dt>
-<dd>
-The client's exit status will be the number of the signal with 128 added. If
-the service exits normally with an exit code of greater than 127 then 127 will
-be returned.
-</dd>
-<dt><samp>stdout</samp></dt>
-<dd>
-The service's numeric wait status as two decimal numbers (high byte first) and
-a textual description of its meaning will be printed to the client's standard
-output. It will be preceded by a newline and followed by an extra newline, and
-the numbers are separated from each other and from the textual description by
-single spaces. The exit status of the client will be zero, unless a system
-error occurs in which case no exit status and description will be printed to
-stdout, and an error message will be printed to stderr as usual.
-</dd>
-</dl>
-
-<p>
-Problems such as client usage errors, the service not being found or permission
-being denied or failure of a system call are system errors. An error message
-describing the problem will be printed on the client's stderr, and the client's
-exit status will be 255. If the client dies due to a signal this should be
-treated as a serious system error.
-</dd>
-</dl>
-<dl>
-<dt><samp>-H</samp></dt>
-<dt><samp>--hidecwd</samp></dt>
-<dd>
-Prevents the calling process's current directory name from being passed to the
-service; the null string will be passed instead.
-</dd>
-</dl>
-<dl>
-<dt><samp>-P</samp></dt>
-<dt><samp>--sigpipe</samp></dt>
-<dd>
-If the service program is terminated due to a <code>SIGPIPE</code> the exit
-status of the client will be zero, even if it would have been something else
-according to the exit status method specified. This option has no effect on
-the code and description printed if the exit status method <samp>stdout</samp>
-is in use.
-</dd>
-</dl>
-<dl>
-<dt><samp>-h</samp></dt>
-<dt><samp>--help</samp></dt>
-<dt><samp>--copyright</samp></dt>
-<dd>
-<samp>-h</samp> or <samp>--help</samp> prints the client's usage message;
-<samp>--copyright</samp> prints the copyright and lack of warranty notice.
-</dd>
-</dl>
-
-<hr>
-
-<a name="s-optoverride"></a>
-<h2>2.2 Security-overriding options</h2>
-
-<p>
-There are also some options which are available for debugging and to allow the
-system administrator to override a user's policy. These options are available
-only if the client is called by root or if the calling user is the same as the
-service user.
-<dl>
-<dt><samp>--override <var>configuration-data</var></samp></dt>
-<dt><samp>--override-file <var>filename</var></samp></dt>
-<dd>
-Do not read the usual configuration files. Instead, the client sends
-<var>configuration-data</var> (followed by a newline) or the contents of
-<var>filename</var> (which is opened in the context of the client) to the
-daemon and the daemon uses that data instead. The
-<var>configuration-data</var> must all be in one argument. It will have a
-single newline appended so that a single directive can easily be given, but if
-more than one directive is required it will have to contain one or more real
-newlines.
-</dd>
-</dl>
-<dl>
-<dt><samp>--spoof-user <var>user</var></samp></dt>
-<dd>
-Pretend to the service that it is being called by <var>user</var> (which may be
-a username or a uid). This will also affect the group and supplementary groups
-supplied to the service; they will be the standard group and supplementary
-groups for <var>user</var>. The <samp>--spoof-user</samp> option will
-<em>not</em> affect which user is chosen if the service user is specified as
-just <samp>-</samp>; in this case the service user will be the real calling
-user.
-</dd>
-</dl>
-
-<hr>
-
-[ <a href="ch-intro.html">previous</a> ]
-[ <a href="index.html#contents">Contents</a> ]
-[ <a href="ch-intro.html">1</a> ]
-[ 2 ]
-[ <a href="ch-envir.html">3</a> ]
-[ <a href="ch-config.html">4</a> ]
-[ <a href="ch-ipass.html">5</a> ]
-[ <a href="ch-notes.html">6</a> ]
-[ <a href="ch-envir.html">next</a> ]
-
-<hr>
-
-<p>
-User service daemon and client specification
-
-<address>
-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>
-
+++ /dev/null
-<!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">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
-<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>
-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 <samp>/etc/userv/system.default</samp>. Then, by
-default (this behaviour may be modified), it will read a per-user file
-<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>
-When it has read all of these files it will act according to the currently
-values of of the execution settings.
-
-<hr>
-
-<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>
-<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>
-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>
-
-<a name="s-directives"></a>
-<h2>4.2 Configuration file directives</h2>
-
-<hr>
-
-<a name="s-dirs-immediate"></a>
-<h3>4.2.1 Immediate directives</h3>
-
-<p>
-The following directives take effect immediately:
-<dl>
-<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>
-<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.
-</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.
-
-<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>
-
-<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.
-<dl>
-<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.
-</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>
-
-<hr>
-
-<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.
-<dl>
-<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>
-<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.
-</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.
-</dd>
-</dl>
-
-<p>
-The parameters are:
-<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
-<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>
-</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>.
-</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.
-
-<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>
-
-<hr>
-
-<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.
-<dl>
-<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.
-
-<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).
-</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).
-</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>).
-</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
-
-<pre>
- .../program arg arg arg ...
-</pre>
-
-<p>
-as
-
-<pre>
- /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.
-
-<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.
-
-<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>.
-
-<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:
-
-<pre>
- 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.
-
-<hr>
-
-<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>
-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>
-
-<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:
-
-<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 <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
- errors-to-stderr
- include <var>file containing configuration data sent by client</var>
- quit
-</pre>
-
-<hr>
-
-[ <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>
-
-<p>
-User service daemon and client specification
-
-<address>
-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>
-
+++ /dev/null
-<!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 - Execution environment of the service program</title>
-
-</head>
-
-<body>
-
-<a name="ch-envir"></a>
-<hr>
-
-[ <a href="ch-client.html">previous</a> ]
-[ <a href="index.html#contents">Contents</a> ]
-[ <a href="ch-intro.html">1</a> ]
-[ <a href="ch-client.html">2</a> ]
-[ 3 ]
-[ <a href="ch-config.html">4</a> ]
-[ <a href="ch-ipass.html">5</a> ]
-[ <a href="ch-notes.html">6</a> ]
-[ <a href="ch-config.html">next</a> ]
-
-<hr>
-
-<h1>
-User service daemon and client specification
-<br>Chapter 3 - Execution environment of the service program
-</h1>
-
-
-<hr>
-
-
-<p>
-The daemon which is handling the service user side of things will read
-configuration files to decide what to do. If it decides to allow the service
-to be provided it will fork a subprocess to execute the service.
-
-<p>
-The service will have no controlling terminal, but it will be a process group
-leader.
-
-<p>
-If the client is killed or times out or a file or descriptor being read or
-written by the client process gets an error then the service will be
-disconnected from the client. The client will return an exit status of 255 and
-some the service's pipes may be closed at the other end. The service will
-become a child of <code>init</code>. The service may well not notice the
-disconnection, though writing to a pipe after this may produce a
-<code>SIGPIPE</code> and the facility exists to have a <code>SIGHUP</code> sent
-to the service on disconnection.
-
-<hr>
-
-<a name="s3.1"></a>
-<h2>3.1 File descriptors</h2>
-
-<p>
-The service program's standard filedescriptors, and possibly other file
-descriptors, will be connected to pipes or to <code>/dev/null</code>. The
-<code>userv</code> client/daemon pair will arrange that data is copied between
-the files or file descriptors specified to to the client by the caller and
-these these pipes.
-
-<p>
-Pipes which may be written to will be closed if a write error occurs on the
-corresponding client-side file or descriptor, which may result in a
-<code>SIGPIPE</code> in the service program; pipes open for reading will get
-<code>EOF</code> if the client-side file descriptor gets <code>EOF</code> or an
-error.
-
-<p>
-If the service closes one of its reading file descriptors the writing end of
-the corresponding pipe will generate a <code>SIGPIPE</code> when attempts are
-made by the client/daemon pair to write to it. This will not be considered an
-error; rather, the relevant pipe will be discarded and the corresponding file
-or file descriptor held by the client will be closed.
-
-<p>
-Likewise, if one of the file descriptors held by the client for writing by the
-service is a pipe whose other end is closed by the caller then the
-client/daemon pair will see an error when trying to copy data provided by the
-service. This too will not be considered an error; rather, the pipe
-correspondong to that descriptor will be closed and any further writes will
-cause the service to get a <code>SIGPIPE</code>.
-
-<p>
-Note that not all write errors or broken pipes on file descriptors may be
-visible to the service, since buffered data may be discarded by the operating
-system and there will be a finite interval between the error happening and the
-service being disconnected from the client or the next write causing a
-<code>SIGPIPE</code>.
-
-<p>
-Read errors on file descriptors (and disconnection) will only be visible to the
-service and distinguishable from normal end of file if
-<code>disconnect-hup</code> is in effect.
-
-<p>
-Read and write errors (other than broken pipes, as described above) will always
-be visible to the caller; they are system errors, and will therefore cause the
-client to print an error message to stderr and return with an exit status of
-255.
-
-<p>
-If the main service program process exits while it still has running children
-any file descriptors held by those children can remain open, depending on the
-use of <samp>wait</samp>, <samp>nowait</samp> or <samp>close</samp> for the
-relevant file descriptor in the client's arguments. By default writing
-filedescriptors remain open and the client will wait for them to be closed at
-the service end, and reading file descriptors are closed immediately. These
-leftover child processes will not get a any <code>SIGHUP</code> even if a read
-or write error occurs or the client disconnects before then.
-
-<hr>
-
-<a name="s3.2"></a>
-<h2>3.2 Environment</h2>
-
-<p>
-The service will have some information in environment variables:
-<dl>
-<dt><samp>USERV_USER</samp></dt>
-<dd>
-The login name of the calling user. If the <code>LOGNAME</code> variable is
-set (or, if that is unset, if the <code>USER</code> variable is set) in the
-environment passed to the client by the caller then the password entry for that
-login name will be looked up; if that password entry's uid is the same as that
-of the calling process then that login name will be used, otherwise (or if
-neither <code>LOGNAME</code> nor <code>USER</code> is set) the calling
-process's uid will be looked up to determine their login name (and if this
-lookup fails then the service will not be invoked).
-</dd>
-<dt><samp>USERV_UID</samp></dt>
-<dd>
-The uid of the calling process.
-</dd>
-<dt><samp>USERV_GID</samp></dt>
-<dd>
-The gid and supplementary group list of the calling process: first the group in
-gid and then those in the supplementary group list, in decimal, separated by
-spaces.
-</dd>
-<dt><samp>USERV_GROUP</samp></dt>
-<dd>
-The group names of the calling process, listed in the same way as the ids are
-in <code>USERV_GID</code>. If no name can be found for any of the calling
-process's group(s) then the service will not be invoked.
-</dd>
-<dt><samp>USERV_CWD</samp></dt>
-<dd>
-The client's current working directory name (this directory may not be
-accessible to the service). If it could not be determined or the
-<code>--hidecwd</code> flag was used then this variable will be set to an empty
-string (this is not considered an error).
-</dd>
-<dt><samp>USERV_SERVICE</samp></dt>
-<dd>
-The service name requested by the caller.
-</dd>
-<dt><samp>USERV_U_<var>name</var></samp></dt>
-<dd>
-The value supplied to the client by the caller using -D<var>name</var>.
-</dd>
-</dl>
-
-<p>
-<code>HOME</code>, <code>PATH</code>, <code>SHELL</code>, <code>LOGNAME</code>
-and <code>USER</code> will be set appropriately (according to the details of
-the service user).
-
-<hr>
-
-[ <a href="ch-client.html">previous</a> ]
-[ <a href="index.html#contents">Contents</a> ]
-[ <a href="ch-intro.html">1</a> ]
-[ <a href="ch-client.html">2</a> ]
-[ 3 ]
-[ <a href="ch-config.html">4</a> ]
-[ <a href="ch-ipass.html">5</a> ]
-[ <a href="ch-notes.html">6</a> ]
-[ <a href="ch-config.html">next</a> ]
-
-<hr>
-
-<p>
-User service daemon and client specification
-
-<address>
-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>
-
+++ /dev/null
-<!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 - Introduction</title>
-
-</head>
-
-<body>
-
-<a name="ch-intro"></a>
-<hr>
-
-[ <a href="index.html">previous</a> ]
-[ <a href="index.html#contents">Contents</a> ]
-[ 1 ]
-[ <a href="ch-client.html">2</a> ]
-[ <a href="ch-envir.html">3</a> ]
-[ <a href="ch-config.html">4</a> ]
-[ <a href="ch-ipass.html">5</a> ]
-[ <a href="ch-notes.html">6</a> ]
-[ <a href="ch-client.html">next</a> ]
-
-<hr>
-
-<h1>
-User service daemon and client specification
-<br>Chapter 1 - Introduction
-</h1>
-
-
-<hr>
-
-
-<p>
-There is a daemon which invokes user service programs (henceforth `services')
-in response to requests by callers of a companion client program (henceforth
-the `client') and according to rules set forth in system-wide and user-specific
-configuration files. The companion client program is setuid root, and
-negotiates with the daemon through an <code>AF_UNIX</code> socket and
-associated objects in a system-wide private directory set aside for the
-purpose. The user who wishes the service to be performed and calls the client
-is called the `calling user'; the process which calls the client is called the
-`calling process'.
-
-<p>
-The daemon and the client are responsible for ensuring that information is
-safely carried across the security boundary between the two users, and that the
-processes on either side cannot interact with each other in any unexpected
-ways.
-
-<hr>
-
-[ <a href="index.html">previous</a> ]
-[ <a href="index.html#contents">Contents</a> ]
-[ 1 ]
-[ <a href="ch-client.html">2</a> ]
-[ <a href="ch-envir.html">3</a> ]
-[ <a href="ch-config.html">4</a> ]
-[ <a href="ch-ipass.html">5</a> ]
-[ <a href="ch-notes.html">6</a> ]
-[ <a href="ch-client.html">next</a> ]
-
-<hr>
-
-<p>
-User service daemon and client specification
-
-<address>
-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>
-
+++ /dev/null
-<!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 - Information passed through the client/daemon combination</title>
-
-</head>
-
-<body>
-
-<a name="ch-ipass"></a>
-<hr>
-
-[ <a href="ch-config.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> ]
-[ <a href="ch-config.html">4</a> ]
-[ 5 ]
-[ <a href="ch-notes.html">6</a> ]
-[ <a href="ch-notes.html">next</a> ]
-
-<hr>
-
-<h1>
-User service daemon and client specification
-<br>Chapter 5 - Information passed through the client/daemon combination
-</h1>
-
-
-<hr>
-
-
-<p>
-The information described below is the only information which passes between
-the caller and the service.
-<ul>
-<li>
-The service name supplied by the caller is available in the configuration
-language for deciding whether and which service program to invoke, in the
-<code>service</code> parameter, and is used by the
-<code>execute-from-directory</code> and <code>execute-from-path</code>
-configuration directives. It is usually used to select which service program
-to invoke. It is also passed to the service program in the
-<code>USERV_SERVICE</code> environment variable.
-</li>
-</ul>
-<ul>
-<li>
-File descriptors specified by the client and allowed according to the
-configuration language will be connected. Each file descriptor is opened for
-reading or writing. Communication is via pipes, one end of each pipe being
-open on the appropriate file descriptor in the service program (when it is
-invoked) and the other end being held by the client process, which will read
-and write files it opens on behalf of its caller or file descriptors it is
-passed by its caller.
-
-<p>
-Data may be passed into the service through reading pipes and out of it through
-writing pipes. These pipes can remain open only until the service and client
-have terminated, or can be made to stay open after the client has terminated
-and (if the service program forks) the main service process has exited; the
-behaviour is controlled by options passed to the client by its caller.
-
-<p>
-The caller can arrange that a writing pipe be connected to a pipe or similar
-object and cause attempts to write to that descriptor by the service to
-generate a <code>SIGPIPE</code> (or <code>EPIPE</code> if <code>SIGPIPE</code>
-is caught or ignored) in the service.
-
-<p>
-Likewise, the service can close filedescriptors specified for reading, which
-will cause the corresponding filedescriptors passed by the caller to be closed,
-so that if these are pipes processes which write to them will receive
-<code>SIGPIPE</code> or <code>EPIPE</code>.
-</li>
-</ul>
-<ul>
-<li>
-If <code>no-suppress-args</code> is set then arguments passed to the client by
-its caller will be passed on, verbatim, to the service.
-</li>
-</ul>
-<ul>
-<li>
-Fatal signals and system call failures experienced by the client will result in
-the disconnection of the service from the client and possibly some of the
-communication file descriptors described above; if <code>disconnect-hup</code>
-is set then the service will also be sent a <code>SIGHUP</code>.
-</li>
-</ul>
-<ul>
-<li>
-The value of the <code>LOGNAME</code> (or <code>USER</code>) environment
-variable as passed to the client will be used as the login name of the calling
-user if the uid of the calling process matches the uid corresponding to that
-login name. Otherwise the calling uid's password entry will be used to
-determine the calling user's login name.
-
-<p>
-This login name and the calling uid are available in the configuration language
-in the <code>calling-user</code> parameter and are passed to the service
-program in environment variables <code>USERV_USER</code> and
-<code>USERV_UID</code>.
-
-<p>
-The shell corresponding to that login name (according to the password entry) is
-available as in the configuration language's <code>calling-user-shell</code>
-parameter.
-
-<p>
-If no relevant password entry can be found then no service will be invoked.
-</li>
-</ul>
-<ul>
-<li>
-The numeric values and textual names for calling gid and supplementary group
-list are available in the configuration language in the
-<code>calling-group</code> parameter and are passed to the service in
-environment variables.
-
-<p>
-If no name can be found for a numeric group to which the calling process
-belongs then no service will be invoked.
-</li>
-</ul>
-<ul>
-<li>
-The name of the current working directory in which the client was invoked is
-passed, if available and not hidden using <code>--hidecwd</code>, to the
-service program in the <code>USERV_CWD</code> variable. This grants no special
-access to that directory unless it is a subdirectory of a directory which is
-executable (searchable) but not readable by the service user.
-</li>
-</ul>
-<ul>
-<li>
-Settings specified by the caller using the <samp>--defvar
-<var>name</var>=<var>value</var></samp> option to the client are available in
-the configuration language as the corresponding <samp>u-<var>name</var></samp>
-parameters and are passed to the service program in environment variables
-<samp>USERV_U_<var>name</var></samp>.
-</li>
-</ul>
-<ul>
-<li>
-If the calling user is root or the same as the service user then options may be
-given to the client which bypass the usual security features; in this case
-other information may pass between the caller and the service.
-</li>
-</ul>
-
-<hr>
-
-[ <a href="ch-config.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> ]
-[ <a href="ch-config.html">4</a> ]
-[ 5 ]
-[ <a href="ch-notes.html">6</a> ]
-[ <a href="ch-notes.html">next</a> ]
-
-<hr>
-
-<p>
-User service daemon and client specification
-
-<address>
-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>
-
+++ /dev/null
-<!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 - Applications and notes on use</title>
-
-</head>
-
-<body>
-
-<a name="ch-notes"></a>
-<hr>
-
-[ <a href="ch-ipass.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> ]
-[ <a href="ch-config.html">4</a> ]
-[ <a href="ch-ipass.html">5</a> ]
-[ 6 ]
-[ <a href="index.html">next</a> ]
-
-<hr>
-
-<h1>
-User service daemon and client specification
-<br>Chapter 6 - Applications and notes on use
-</h1>
-
-
-<hr>
-
-<a name="s-examples"></a>
-<h2>6.1 Examples</h2>
-
-<p>
-The companion package, <code>userv-utils</code>, contains a selection of
-example services, some of which are useful tools in their own right. See the
-<code>README</code> in its top-level directory for details.
-
-<hr>
-
-<a name="s-standards"></a>
-<h2>6.2 Standard services and directory management</h2>
-
-<p>
-In later versions of this specification standard service names and interfaces
-for common services such as mail delivery and WWW CGI scripts may be specified.
-
-<p>
-<code>userv</code>-using applications and system services which hide
-<code>userv</code> behind wrapper scripts may need to store information in the
-user's filespace to preserve the correct placement of the security perimiters.
-Such applications should usually do so in a directory (created by them)
-<samp>~/.userv/<var>service</var></samp>, where <var>service</var> is the
-service name or application in question.
-
-<p>
-If desired, a dot-directory inside <samp>~/.userv</samp> may be used to avoid
-the user becoming confused by finding parts of a semi-privileged application's
-internal state in their filespace, and/or discourage them from fiddling with
-and thus corrupting it.
-
-<p>
-However, <code>userv</code> applications should of course not rely for their
-global integrity and security on the integrity of the data on the user's side
-of the security boundary.
-
-<hr>
-
-<a name="s-reducepriv"></a>
-<h2>6.3 Reducing the number of absolutely privileged subsystems</h2>
-
-<p>
-Currently most Unix systems have many components which need to run as root,
-even though most of their activity does not strictly require it. This gives
-rise to a large and complex body of code which must be trusted with the
-security of the system.
-
-<p>
-If they were to use <code>userv</code>, many of these subsystems would no
-longer need any unusual privilege.
-
-<p>
-<code>cron</code> and <code>at</code>, <code>lpr</code> and the system's mail
-transfer agent (<code>sendmail</code>, <code>smail</code>, <code>exim</code> or
-the like) all fall into this category, though <code>userv</code>-based versions
-of these programs are not currently available.
-
-<hr>
-
-<a name="s-noexcess"></a>
-<h2>6.4 Do not give away excessive privilege to <code>userv</code>-using facilities</h2>
-
-<p>
-There is a danger that people reimplementing the facilities I mention above
-using <code>userv</code> will discard much of the security benefit by using a
-naive implementation technique. This will become clearer with an example:
-
-<p>
-Consider the <code>lpr</code> program. In current systems this needs to have
-an absolutely privileged component in order to support delayed printing without
-copying: when the user queues a file to be printed the filename is stored in
-the print queue, rather than a copy of it, and the printer daemon accesses the
-file directly when it is ready to print the job. In order that the user can
-print files which are not world-readable the daemon is given root privilege so
-that it can open the file in the context of the user, rather than its own.
-
-<p>
-A simple-minded approach to converting this scheme to use <code>userv</code>
-might involve giving the printer daemon (the <code>lp</code> user) the ability
-to read the file by allowing them to run <code>cat</code> (or a special-purpose
-file-reading program) as any user. The <code>lpr</code> program would use a
-<code>userv</code> service to store the filename in the printer daemon's
-queues, and the daemon would read the file later when it felt like it.
-
-<p>
-However, this would allow the printer daemon to read any file on the system,
-whether or not someone had asked for it to be printed. Since many files will
-contain passwords and other security-critical information this is nearly as bad
-as giving the daemon root access in the first place. Any security holes in the
-print server which allow a user to execute commands as the <code>lp</code> user
-will give the user the ability to read any file on the system.
-
-<p>
-Instead, it is necessary to keep a record of which files the daemon has been
-asked to print <em>outside</em> the control of the print daemon. This record
-could be kept by a new root-privileged component, but this is not necessary:
-the record of which files a user has asked to be printed can be kept under the
-control of the user in question. The submission program <code>lpr</code> will
-make a record in an area under the user's control before communicating with the
-print server, and the print server would be given the ability to run a special
-file-reading program which would only allow files to be read which were listed
-in the user's file of things they'd asked to print.
-
-<p>
-Now security holes in most of the printing system do not critically affect the
-security of the entire system: they only allow the attacker to read and
-interfere with print jobs. Bugs in the programs run by the print server to
-read users' files (and to remove entries from the list of files when it has
-done with them) will still be serious, but this program can be quite simple.
-
-<p>
-Similar considerations apply to many <code>userv</code>-based versions of
-facilities which currently run as root.
-
-<p>
-It is debatable whether the user-controlled state should be kept in the user's
-filespace (in dotfiles, say) or kept in a separate area set aside for the
-purpose; however, using the user's home directory (and possibly creating a
-separate subdirectory of it as a dotfile to contain subsystem state) has fewer
-implications for the rest of the system and makes it entirely clear where the
-security boundaries lie.
-
-<hr>
-
-<a name="s-notreally"></a>
-<h2>6.5 <code>userv</code> can often replace <code>sudo</code>, but not <code>really</code></h2>
-
-<p>
-<code>userv</code> is not intended as a general-purpose system administration
-tool with which system administrators can execute arbitrary programs like text
-editors as root (or other system users) when they need to. It is unsuitable
-for this purpose precisely because it enforces a strong separation between the
-calling and the called program, which is undesirable in this context.
-
-<p>
-However, its use when restricted to running particular programs in particular
-ways is very similar to many common uses of <code>sudo</code>[<a
-href="footnotes.html#f2" name="fr2">2</a>]. <code>userv</code> is generally
-much better than restricted <code>sudo</code>, because it protects the called
-program much more strongly from bad environmental conditions set up by the
-caller. Most programs that one might want to run via restricted
-<code>sudo</code>, have not been designed to run in a partially hostile
-environment. <code>userv</code> allows these programs to be run in a safer
-environment and should be used instead.
-
-<hr>
-
-<a name="s-stdinerr"></a>
-<h2>6.6 Error handling and input streams (eg stdin)</h2>
-
-<p>
-When the service program is reading from a file descriptor connected to the
-calling side, the fd that the service program refers to a pipe set up by
-<code>userv</code> and not to the same object as was presented by the caller.
-
-<p>
-Therefore if there is some kind of error it is possible for the service-side fd
-to give premature end of file. If it is important to tell whether all of the
-intended data has been received by the service program, the datastream must
-contain an explicit end-of-file indication of some kind.
-
-<p>
-For example, consider a <code>userv</code> service for submitting a mail
-message, where message is supplied on the service's stdin. However, if the
-calling process is interrupted before it has written all of the message, the
-service program will get EOF on the message data. In a naive arrangement this
-would cause a half-complete message to be sent. To prevent this, it is
-necessary to adopt some kind of explicit end indication; for example, the end
-of the message could be signalled by a dot on a line by itself, and dots
-doubled, as in SMTP. Then the service program would know when the entire
-message had been received, and could avoid queueing incomplete messages.
-
-<hr>
-
-<a name="s-nogeneral"></a>
-<h2>6.7 Don't give access to general-purpose utilities</h2>
-
-<p>
-Do not specify general purpose programs like <code>mv</code> or
-<code>cat</code> in <code>execute-</code> directives without careful thought
-about their arguments, and certainly not if <code>no-suppress-args</code> is
-specified. If you do so it will give the caller much more privilige than you
-probably intend.
-
-<p>
-It is a shame that I have to say this here, but inexperienced administrators
-have made similar mistakes with programs like <code>sudo</code>.
-
-<hr>
-
-[ <a href="ch-ipass.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> ]
-[ <a href="ch-config.html">4</a> ]
-[ <a href="ch-ipass.html">5</a> ]
-[ 6 ]
-[ <a href="index.html">next</a> ]
-
-<hr>
-
-<p>
-User service daemon and client specification
-
-<address>
-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>
-
+++ /dev/null
-<!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 - Footnotes</title>
-
-</head>
-
-<body>
-
-<hr>
-
-<h1>
-User service daemon and client specification
-<br>Footnotes
-</h1>
-
-
-<h2><a href="ch-client.html#fr1" name="f1">1</a></h2>
-
-<p>
-<code>userv</code> is short for `user services', and is pronounced `you-serve'.
-
-<h2><a href="ch-notes.html#fr2" name="f2">2</a></h2>
-
-<p>
-<code>sudo</code> is a program which allows users to execute certain programs
-as root, according to configuration files specified by the system
-administrator.
-
-<hr>
-
-<p>
-User service daemon and client specification
-
-<address>
-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>
-
+++ /dev/null
-<!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</title>
-
-</head>
-
-<body>
-
-<a name="index"></a>
-<hr>
-
-[ <a href="ch-notes.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> ]
-[ <a href="ch-config.html">4</a> ]
-[ <a href="ch-ipass.html">5</a> ]
-[ <a href="ch-notes.html">6</a> ]
-[ <a href="ch-intro.html">next</a> ]
-
-<hr>
-
-<h1>
-User service daemon and client specification
-</h1>
-
-
-<hr>
-
-<a name="abstract"></a>
-<h2>Abstract</h2>
-
-<p>
-This is a specification for a Unix system facility to allow one program to
-invoke another when only limited trust exists between them.
-
-<hr>
-
-<a name="copyright"></a>
-<h2>Copyright Notice</h2>
-
-<p>
-<code>userv</code> is Copyright 1996-2003 Ian Jackson.
-
-<p>
-<code>userv</code> is free software; you can redistribute it and/or modify it
-under the terms of the GNU General Public License as published by the Free
-Software Foundation; either version 2 of the License, or (at your option) any
-later version.
-
-<p>
-This program is distributed in the hope that it will be useful, but <em>without
-any warranty</em>; without even the implied warranty of
-<em>merchantability</em> or <em>fitness for a particular purpose</em>. See the
-GNU General Public License for more details.
-
-<p>
-You should have received a copy of the GNU General Public License along with
-<code>userv</code>; if not, write to the Free Software Foundation, 59 Temple
-Place - Suite 330, Boston, MA 02111-1307, USA.
-
-<hr>
-
-<a name="contents"></a>
-<h2>Contents</h2>
-
-<ul>
-<li><a href="ch-intro.html">1 Introduction</a></li>
-<li><a href="ch-client.html">2 Client program usage</a></li>
-<ul>
-<li><a href="ch-client.html#s2.1">2.1 Options</a></li>
-<li><a href="ch-client.html#s-optoverride">2.2 Security-overriding options</a></li>
-</ul>
-<li><a href="ch-envir.html">3 Execution environment of the service program</a></li>
-<ul>
-<li><a href="ch-envir.html#s3.1">3.1 File descriptors</a></li>
-<li><a href="ch-envir.html#s3.2">3.2 Environment</a></li>
-</ul>
-<li><a href="ch-config.html">4 Service-side configuration</a></li>
-<ul>
-<li><a href="ch-config.html#s4.1">4.1 Configuration file syntax</a></li>
-<li><a href="ch-config.html#s-directives">4.2 Configuration file directives</a></li>
-<li><a href="ch-config.html#s-configerrors">4.3 Errors in the configuration file</a></li>
-<li><a href="ch-config.html#s-defaults">4.4 Defaults</a></li>
-</ul>
-<li><a href="ch-ipass.html">5 Information passed through the client/daemon combination</a></li>
-<li><a href="ch-notes.html">6 Applications and notes on use</a></li>
-<ul>
-<li><a href="ch-notes.html#s-examples">6.1 Examples</a></li>
-<li><a href="ch-notes.html#s-standards">6.2 Standard services and directory management</a></li>
-<li><a href="ch-notes.html#s-reducepriv">6.3 Reducing the number of absolutely privileged subsystems</a></li>
-<li><a href="ch-notes.html#s-noexcess">6.4 Do not give away excessive privilege to <code>userv</code>-using facilities</a></li>
-<li><a href="ch-notes.html#s-notreally">6.5 <code>userv</code> can often replace <code>sudo</code>, but not <code>really</code></a></li>
-<li><a href="ch-notes.html#s-stdinerr">6.6 Error handling and input streams (eg stdin)</a></li>
-<li><a href="ch-notes.html#s-nogeneral">6.7 Don't give access to general-purpose utilities</a></li>
-</ul>
-</ul>
-
-<hr>
-
-[ <a href="ch-notes.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> ]
-[ <a href="ch-config.html">4</a> ]
-[ <a href="ch-ipass.html">5</a> ]
-[ <a href="ch-notes.html">6</a> ]
-[ <a href="ch-intro.html">next</a> ]
-
-<hr>
-
-<p>
-User service daemon and client specification
-
-<address>
-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 / commitdiff