chiark / gitweb /
version 1.0.3; updated and reformatted docs using Debian woody debian_version_1_0_3
authorian <ian>
Sat, 1 Nov 2003 01:12:21 +0000 (01:12 +0000)
committerian <ian>
Sat, 1 Nov 2003 01:12:21 +0000 (01:12 +0000)
debian/changelog
spec.html/ch-client.html
spec.html/ch-config.html
spec.html/ch-envir.html
spec.html/ch-intro.html
spec.html/ch-ipass.html
spec.html/ch-notes.html
spec.html/footnotes.html
spec.html/index.html
spec.ps
spec.sgml

index 3b5d5f2..33f676a 100644 (file)
@@ -1,52 +1,15 @@
-userv (1.0.1.99.4) unstable; urgency=low
-
-  * Update copyright dates everywhere.
-
- --
-
-userv (1.0.1.99.3) unstable; urgency=low
-
-  * Actually apply _all_ of PJB's fd patch!
-
- -- Ian Jackson <ian@davenant.greenend.org.uk>  Sat,  1 Nov 2003 00:44:44 +0000
-
-userv (1.0.1.99.2) unstable; urgency=low
-
-  * Actually ship uservd(8) !
-  * Fix fd modifier, signal, and exit status parsing to be rigourous in
-    their use of strtoul.  (Thanks to report from Peter Benie.)
-  * Close unwanted pipes in client-side cat subprocesses, to avoid
-    wedging at termination.  (Thanks to patchlet from Peter Benie.)
-
- -- Ian Jackson <ian@davenant.greenend.org.uk>  Sat,  1 Nov 2003 00:19:01 +0000
-
-userv (1.0.1.99.1) unstable; urgency=low
-
-  Debian packaging improvements:
-  * Standards-Version 3.6.1.
-  * /etc/init.d/userv nicer output: colons, . printed after done.
-  * Maintainer scripts use invoke-rc.d if it's available.
-  * Maintainer scripts discard stdout from update-rc.d.
-  * No more messing with /usr/doc, must have /usr/share/doc.
-  * Support unstripped binaries in the .deb, with DEB_BUILD_OPTIONS.
-  * Fixed typo in debian/copyright.
-  * When doing /etc/init.d/userv restart, don't mind if not already
-    running.
-  * debian/rules clean removes whole spec.html subdirectory.
-  * Ship spec.ps (Closes: #210859)
-  * added lintian override for suid binary userv (Closes: #211055)
-  (Thanks to Martin Pitt's NMU for inspirations and one-liners.)
-  
- -- Ian Jackson <ian@davenant.greenend.org.uk>  Fri, 31 Oct 2003 22:55:37 +0000
-
-userv (1.0.1.99.0) unstable; urgency=low
+userv (1.0.3) unstable; urgency=medium
 
   Bugfixes:
   * Make require-fd work with reading fds !
     (Thanks to Ben Harris for the bug report).
+  * Close unwanted pipes in client-side cat subprocesses, to avoid
+    wedging at termination.  (Thanks to patchlet from Peter Benie.)
   * gid_t may be >int, so cast to long when putting in USERV_GIDS
     (Might conceivably make USERV_GIDS be wrong on some platforms.)
   * Do not pass char to ctype macros; they can't cope with -ve !
+  * Fix fd modifier, signal, and exit status parsing to be rigourous in
+    their use of strtoul.  (Thanks to report from Peter Benie.)
 
   Portability fixes:
   * #include <fcntl.h>, not <sys/fcntl.h> (fixes some implicit decls).
@@ -63,22 +26,29 @@ userv (1.0.1.99.0) unstable; urgency=low
   * We do ship m4 and flex output now, so say so.
   * Some groff warnings in userv(1), and source version fixed.
   * New userv(8) manpage.  (Debian: Closes: #33777.)
+  * Update copyright dates everywhere.
 
-  Debian:
+  Debian packaging improvements:
   * Priority changed to optional as per override file.
-  * Added Build-Depends: debiandoc-sgml, tetex-bin.  Closes #190615.
+  * Build-Depends: debiandoc-sgml, tetex-bin, tetex-extra.  Closes #190615.
   * init.d reload is noop, restart now called restart.  Closes #70783.
-
- -- Ian Jackson <ian@davenant.greenend.org.uk>  Sun, 29 Jun 2003 22:23:43 +0100
-
-userv (1.0.1.1potatp.1) unstable; urgency=low
-
-  NMU:
-  * FHS transition (closes #91578)
-  * Corrected location of common licenses
-  * Added -isp to dpkg-gencontrol
-
- -- Bas Zoetekouw <bas@debian.org>  Wed,  8 Aug 2001 17:42:37 +0200
+  * /etc/init.d/userv nicer output: colons, `.' printed after done.
+  * Maintainer scripts use invoke-rc.d if it's available.
+  * Maintainer scripts discard stdout from update-rc.d.
+  * No more messing with /usr/doc, use only /usr/share/doc.  Closes #91578.
+  * Support unstripped binaries in the .deb, with DEB_BUILD_OPTIONS.
+  * Fixed typo in debian/copyright.
+  * /etc/init.d/userv restart doesn't mind if not already running.
+  * debian/rules clean removes whole spec.html subdirectory.
+  * Ship spec.ps (Closes: #210859)
+  * Lintian override for suid /usr/bin/userv (Closes: #211055)
+  * Standards-Version 3.6.1.
+  * Corrected location of common licenses.
+  * Added -isp to dpkg-gencontrol.
+  (Thanks to Martin Pitt and Bas Zoetekouw's NMUs
+   for many inspirations and one-liners.)
+  
+ -- Ian Jackson <ian@davenant.greenend.org.uk>  Sat,  1 Nov 2003 01:11:59 +0000
 
 userv (1.0.1) stable frozen unstable; urgency=high
 
index fe1b980..32c080b 100644 (file)
-<!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 - Client program usage</title>
 
 </head>
 
 <body>
 
+<a name="ch-client"></a>
 <hr>
 
-[<a href="ch-intro.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-envir.html">next</a>]
+[ <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 - Chapter 2<br>
-Client program usage
+User service daemon and client specification
+<br>Chapter 2 - Client program usage
 </h1>
 
-<hr>
 
-<p>
 <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> ...]
+     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>
-</p>
+
+<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>
+<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#1" name="fr1">[1]</a>
-daemon on behalf of the service user.  It will often be the name of a
-program.
-</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>
 
-<h2>
-<a name="s2.1">2.1 Options</a>
-</h2>
+<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.
-
+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>
-<p><dt><samp>-B</samp><p><dt><samp>--builtin</samp><dd>Requests that a builtin service be provided.  This is equivalent to
-using the <code>--override</code> option to specify a string consisting of
+<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).
 
-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, subsection 4.2.4</a> for details of the builtin services available,
-and <a href="#s-optoverride">Security-overriding options, section 2.2</a> for details of the <code>--override</code>
-options.
+<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
+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><dt><samp>-f<var>fd</var>[<var>modifiers</var>]=<var>filename</var></samp><p><dt><samp>--file <var>fd</var>[<var>modifiers</var>]=<var>filename</var></samp><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.
+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.
 
-<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>
+<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 compact>
-<dt><samp>read</samp><dd><samp>O_RDONLY</samp>: Allow reading and not writing.  May not be used with
+<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.
-
-<dt><samp>write</samp><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>.
-
-<dt><samp>overwrite</samp><dd>Equivalent to <samp>write,create,truncate</samp>.
-
-<dt><samp>create</samp><dt><samp>creat</samp><dd><samp>O_CREAT</samp>: Creates the file if necessary.  Implies <samp>write</samp>.
-
-<dt><samp>exclusive</samp><dt><samp>excl</samp><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>.
-
-<dt><samp>truncate</samp><dt><samp>trunc</samp><dd><samp>O_TRUNC</samp>: Truncate any existing file.  Implies <samp>write</samp>.
+</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>.
-
-<dt><samp>append</samp><dd><samp>O_APPEND</samp>: All writes will append to the file.  Implies <samp>write</samp>
-(but not <samp>create</samp>).
-
-<dt><samp>sync</samp><dd><samp>O_SYNC</samp>: Do writes synchronously.  Implies <samp>write</samp>.
-
-<dt><samp>wait</samp><dt><samp>nowait</samp><dt><samp>close</samp><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.
-
-<dt><samp>fd</samp><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>
+<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>
 
 <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
+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>
 
 <p>
 The client will also use <samp>O_NOCTTY</samp> when opening files specified by
 the caller, to avoid changing its controlling terminal.
-</p>
 
 <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>
+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>
+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
+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>
 
 <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>
+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.
-</p>
-
-<dt><samp>-w<var>fd</var>=<var>action</var></samp><dt><samp>--fdwait<var>fd</var>=<var>action</var></samp><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
+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).
-
-<dt><samp>-D<var>name</var>=<var>value</var></samp><dt><samp>--defvar <var>name</var>=<var>value</var></samp><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.
-
-<dt><samp>-t <var>seconds</var></samp><dt><samp>--timeout <var>seconds</var></samp><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).
-
-<dt><samp>-S</samp> <var>method</var><dt><samp>--signals</samp> <var>method</var><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.)
+</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 compact>
-<dt><var>status</var><dd>The client's exit status will be <var>status</var>.  This will not be
+<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.
-
-<dt><samp>number</samp><dt><samp>number-nocore</samp><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
+<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.
-
-<dt><samp>highbit</samp><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.
-
-<dt><samp>stdout</samp><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>
+<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>
 
 <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.
-</p>
-
-<dt><samp>-H</samp><dt><samp>--hidecwd</samp><dd>Prevents the calling process's current directory name from being
-passed to the service; the null string will be passed instead.
-
-<dt><samp>-P</samp><dt><samp>--sigpipe</samp><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.
-
-<dt><samp>-h</samp><dt><samp>--help</samp><dt><samp>--copyright</samp><dd><samp>-h</samp> or <samp>--help</samp> prints the client's usage message;
+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>
-</p>
 
 <hr>
 
-<h2>
-<a name="s-optoverride">2.2 Security-overriding options</a>
-</h2>
+<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.
-
+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>
-<p><dt><samp>--override <var>configuration-data</var></samp><p><dt><samp>--override-file <var>filename</var></samp><dd>Do not read the usual configuration files.  Instead, the client sends
+<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.
-
-<p><dt><samp>--spoof-user <var>user</var></samp><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.
-
+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>
-</p>
 
 <hr>
 
-[<a href="ch-intro.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-envir.html">next</a>]
+[ <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>
 
-User service daemon and client specification<br>
+<p>
+User service daemon and client specification
 
 <address>
-1.0.1<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>
index cad4884..6fe14f2 100644 (file)
@@ -1,50 +1,56 @@
-<!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
@@ -52,544 +58,691 @@ 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>
 
 <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>\&quot;</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>\&quot;</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>&amp;</samp> and <samp>|</samp><dd><pre>
-( <var>condition</var>
-&amp; <var>condition</var>
-&amp; <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>&amp;</samp> and <samp>|</samp></dt>
+<dd>
+<pre>
+     ( <var>condition</var>
+     &amp; <var>condition</var>
+     &amp; <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 &quot;$@&quot;' - .../program arg arg arg ...
+     /bin/sh -c '. /etc/environment; exec &quot;$@&quot;' - .../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>
-1.0.1<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>
index 54d4063..362999c 100644 (file)
-<!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 - Execution environment of the service program</title>
 
 </head>
 
 <body>
 
+<a name="ch-envir"></a>
 <hr>
 
-[<a href="ch-client.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-config.html">next</a>]
+[ <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 - Chapter 3<br>
-Execution environment of the service program
+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>
+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>
+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.
-</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>
 
-<h2>
-<a name="s3.1">3.1 File descriptors</a>
-</h2>
+<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>
+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>
+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>
+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>
+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>
+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
+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>
 
 <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>
+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.
-</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>
 
-<h2>
-<a name="s3.2">3.2 Environment</a>
-</h2>
+<a name="s3.2"></a>
+<h2>3.2 Environment</h2>
 
 <p>
 The service will have some information in environment variables:
-<dl compact>
-<dt><samp>USERV_USER</samp><dd>The login name of the calling user.  If the <code>LOGNAME</code> variable is
+<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).
-
-<dt><samp>USERV_UID</samp><dd>The uid of the calling process.
-
-<dt><samp>USERV_GID</samp><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.
-
-<dt><samp>USERV_GROUP</samp><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.
-
-<dt><samp>USERV_CWD</samp><dd>The client's current working directory name (this directory may not be
+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).
-
-<dt><samp>USERV_SERVICE</samp><dd>The service name requested by the caller.
-
-<dt><samp>USERV_U_<var>name</var></samp><dd>The value supplied to the client by the caller using -D<var>name</var>.
-
+<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>
 
-
-<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).
-</p>
+<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">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-config.html">next</a>]
+[ <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>
 
-User service daemon and client specification<br>
+<p>
+User service daemon and client specification
 
 <address>
-1.0.1<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>
index 220d640..2a4df1a 100644 (file)
@@ -1,67 +1,82 @@
-<!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 - Introduction</title>
 
 </head>
 
 <body>
 
+<a name="ch-intro"></a>
 <hr>
 
- [<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-client.html">next</a>]
+[ <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 - Chapter 1<br>
-Introduction
+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>
+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.
-</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#abstract">Abstract</a>]
- [<a href="index.html#copyright">Copyright Notice</a>]
- [<a href="index.html#contents">Contents</a>]
- [<a href="ch-client.html">next</a>]
+[ <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>
 
-User service daemon and client specification<br>
+<p>
+User service daemon and client specification
 
 <address>
-1.0.1<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>
index 84fcf2b..a3a1160 100644 (file)
-<!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 - Information passed through the client/daemon combination</title>
 
 </head>
 
 <body>
 
+<a name="ch-ipass"></a>
 <hr>
 
-[<a href="ch-config.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-notes.html">next</a>]
+[ <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 - Chapter 5<br>
-Information passed through the client/daemon combination
+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.
 
+<p>
+The information described below is the only information which passes between
+the caller and the service.
 <ul>
-<p><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
+<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
+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><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.
-
-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.
-
-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.
-
-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>.
-
-<p><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.
-
-<p><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>.
-
-<p><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.
-
-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>.
-
-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.
-
-If no relevant password entry can be found then no service will be
-invoked.
+<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><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>
+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.
 
-If no name can be found for a numeric group to which the calling
-process belongs then no service will be invoked.
+<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><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.
+<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><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>.
+<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><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.
+<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>
-</p>
 
 <hr>
 
-[<a href="ch-config.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-notes.html">next</a>]
+[ <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>
 
-User service daemon and client specification<br>
+<p>
+User service daemon and client specification
 
 <address>
-1.0.1<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>
index 4ab167a..a2b0c72 100644 (file)
-<!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 - Applications and notes on use</title>
 
 </head>
 
 <body>
 
+<a name="ch-notes"></a>
 <hr>
 
-[<a href="ch-ipass.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">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 - Chapter 6<br>
-Applications and notes on use
+User service daemon and client specification
+<br>Chapter 6 - Applications and notes on use
 </h1>
 
+
 <hr>
 
-<h2>
-<a name="s-examples">6.1 Examples</a>
-</h2>
+<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.
-</p>
+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>
 
-<h2>
-<a name="s-standards">6.2 Standard services and directory management</a>
-</h2>
+<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>
+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>
+<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>
+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.
-</p>
+global integrity and security on the integrity of the data on the user's side
+of the security boundary.
 
 <hr>
 
-<h2>
-<a name="s-reducepriv">6.3 Reducing the number of absolutely privileged subsystems</a>
-</h2>
+<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>
+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>
 
 <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.
-</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>
 
-<h2>
-<a name="s-noexcess">6.4 Do not give away excessive privilege to <code>userv</code>-using facilities</a>
-</h2>
+<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>
+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>
+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>
+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>
+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>
+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>
+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>
 
 <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.
-</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>
 
-<h2>
-<a name="s-notreally">6.5 <code>userv</code> can often replace <code>sudo</code>, but not <code>really</code></a>
-</h2>
+<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>
+<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#2" 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.
-</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>
 
-<h2>
-<a name="s-stdinerr">6.6 Error handling and input streams (eg stdin)</a>
-</h2>
+<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>
+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>
+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.
-</p>
+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>
 
-<h2>
-<a name="s-nogeneral">6.7 Don't give access to general-purpose utilities</a>
-</h2>
+<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
+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>
 
 <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>.
-</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">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">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>
 
-User service daemon and client specification<br>
+<p>
+User service daemon and client specification
 
 <address>
-1.0.1<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>
index 542590d..3c74939 100644 (file)
@@ -1,9 +1,11 @@
-<!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 - Footnotes</title>
 
 </head>
 
 <hr>
 
-  [<a href="index.html#abstract">Abstract</a>]
-  [<a href="index.html#copyright">Copyright Notice</a>]
-  [<a href="index.html#contents">Contents</a>]
+<h1>
+User service daemon and client specification
+<br>Footnotes
+</h1>
 
-<hr>
 
-<h1>User service daemon and client specification - Footnotes</h1>
+<h2><a href="ch-client.html#fr1" name="f1">1</a></h2>
 
-<hr>
-
-<h2><a href="ch-client.html#fr1" name="1">1</a>
-</h2>
-<p>
-<code>userv</code> is
-short for `user services', and is pronounced `you-serve'.
-</p><h2><a href="#fr2" name="2">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.
-</p><hr>
+<code>userv</code> is short for `user services', and is pronounced `you-serve'.
 
- [<a href="index.html#abstract">Abstract</a>]
- [<a href="index.html#copyright">Copyright Notice</a>]
- [<a href="index.html#contents">Contents</a>]
+<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>
 
-User service daemon and client specification<br>
+<p>
+User service daemon and client specification
 
 <address>
-1.0.1<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>
index 81b82d7..86f18e9 100644 (file)
-<!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</title>
 
 </head>
 
 <body>
 
+<a name="index"></a>
 <hr>
 
-  [<a href="#abstract">Abstract</a>]
-  [<a href="#copyright">Copyright Notice</a>]
-  [<a href="#contents">Contents</a>]
+[ <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>
+<h1>
+User service daemon and client specification
+</h1>
+
 
 <hr>
 
-<h2><a name="abstract">Abstract</a></h2>
+<a name="abstract"></a>
+<h2>Abstract</h2>
 
-This is a specification for a Unix system facility to allow one
-program to invoke another when only limited trust exists
-between them.
+<p>
+This is a specification for a Unix system facility to allow one program to
+invoke another when only limited trust exists between them.
 
-<h2><a name="copyright">Copyright Notice</a></h2>
+<hr>
 
-<p>
-<code>userv</code> is Copyright 1996-2000 Ian Jackson.
-</p>
+<a name="copyright"></a>
+<h2>Copyright Notice</h2>
 
 <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>
+<code>userv</code> is Copyright 1996-2003 Ian Jackson.
 
 <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>
+<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>
-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.
-</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>
 
-<h2><a name="contents">Contents</a></h2>
+<a name="contents"></a>
+<h2>Contents</h2>
 
 <ul>
-<li><a href="ch-intro.html">1 Introduction</a>
-<li><a href="ch-client.html">2 Client program usage</a>
+<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</a> Options
-<li><a href="ch-client.html#s-optoverride">2.2</a> Security-overriding options
+<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><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</a> File descriptors
-<li><a href="ch-envir.html#s3.2">3.2</a> Environment
+<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><a href="ch-config.html">4 Service-side configuration</a></li>
 <ul>
-<li><a href="ch-config.html#s4.1">4.1</a> Configuration file syntax
-<li><a href="ch-config.html#s-directives">4.2</a> Configuration file directives
-<li><a href="ch-config.html#s-configerrors">4.3</a> Errors in the configuration file
-<li><a href="ch-config.html#s-defaults">4.4</a> Defaults
+<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><a href="ch-notes.html">6 Applications and notes on use</a>
+<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</a> Examples
-<li><a href="ch-notes.html#s-standards">6.2</a> Standard services and directory management
-<li><a href="ch-notes.html#s-reducepriv">6.3</a> Reducing the number of absolutely privileged subsystems
-<li><a href="ch-notes.html#s-noexcess">6.4</a> Do not give away excessive privilege to <code>userv</code>-using facilities
-<li><a href="ch-notes.html#s-notreally">6.5</a> <code>userv</code> can often replace <code>sudo</code>, but not <code>really</code>
-<li><a href="ch-notes.html#s-stdinerr">6.6</a> Error handling and input streams (eg stdin)
-<li><a href="ch-notes.html#s-nogeneral">6.7</a> Don't give access to general-purpose utilities
+<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="#abstract">Abstract</a>]
- [<a href="#copyright">Copyright Notice</a>]
- [<a href="#contents">Contents</a>]
+[ <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>
 
-User service daemon and client specification<br>
+<p>
+User service daemon and client specification
 
 <address>
-1.0.1<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>
diff --git a/spec.ps b/spec.ps
index d3e0fe2..863190d 100644 (file)
--- a/spec.ps
+++ b/spec.ps
@@ -10,7 +10,7 @@
 %DVIPSWebPage: (www.radicaleye.com)
 %DVIPSCommandLine: dvips -o spec.ps spec
 %DVIPSParameters: dpi=600, compressed
-%DVIPSSource:  TeX output 2003.10.31:2300
+%DVIPSSource:  TeX output 2003.11.01:0111
 %%BeginProcSet: texc.pro
 %!
 /TeXDict 300 dict def TeXDict begin/N{def}def/B{bind def}N/S{exch}N/X{S
@@ -387,14 +387,14 @@ TeXDict begin
 452 875 a Ft(User)50 b(service)g(daemon)j(and)f(client)1312
 1037 y(speci\002cation)p Black Black 718 1275 a Fs(Ian)24
 b(Jackson)i Fr(<)t(ian@davenant.greenend.org.uk>)p Black
-Black 1592 1686 a Fq(1.0.1.1potatp.1)p Black Black 1654
-2184 a Fp(Abstract)0 2453 y Fq(This)d(is)h(a)f(speci\002cation)h(for)f
-(a)h(Unix)f(system)f(facility)j(to)e(allow)h(one)f(pr)n(ogram)g(to)f
+Black 1792 1686 a Fq(1.0.3)p Black Black 1654 2184 a
+Fp(Abstract)0 2453 y Fq(This)d(is)h(a)f(speci\002cation)h(for)f(a)h
+(Unix)f(system)f(facility)j(to)e(allow)h(one)f(pr)n(ogram)g(to)f
 (invoke)h(another)g(when)0 2566 y(only)f(limited)h(tr)o(ust)f(exists)f
 (between)g(them.)p Black Black eop
 %%Page: 2 2
 2 1 bop Black 0 TeXcolorgray Black Black 0 4108 a Fp(Copyright)31
-b(Notice)0 4375 y Fo(userv)20 b Fq(is)j(Copyright)f(1996-2000)k(Ian)d
+b(Notice)0 4375 y Fo(userv)20 b Fq(is)j(Copyright)f(1996-2003)k(Ian)d
 (Jackson.)0 4545 y Fo(userv)h Fq(is)j(fr)n(ee)f(softwar)n(e;)h(you)f
 (can)h(r)n(edistribute)e(it)i(and/or)f(modify)g(it)h(under)e(the)h
 (terms)f(of)i(the)e(GNU)0 4658 y(General)i(Public)h(License)e(as)h
index a28114e..ea30b7e 100644 (file)
--- a/spec.sgml
+++ b/spec.sgml
@@ -3,7 +3,7 @@
 <book>
 <title>User service daemon and client specification
 <author>Ian Jackson <email>ian@davenant.greenend.org.uk
-<version>1.0.1.1potatp.1</version>
+<version>1.0.3</version>
 
 <abstract>
 This is a specification for a Unix system facility to allow one
@@ -11,7 +11,7 @@ program to invoke another when only limited trust exists
 between them.
 
 <copyright>
-<prgn/userv/ is Copyright 1996-2000 Ian Jackson.
+<prgn/userv/ is Copyright 1996-2003 Ian Jackson.
 <p>
 
 <prgn/userv/ is free software; you can redistribute it and/or modify