-<html><head>
-<title>User service daemon and client specification - Client program usage
-</title>
-<link rev=made href="mailto:ian@davenant.greenend.org.uk">
-</head><body>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+
+<html>
+
+<head>
+
+<title>User service daemon and client specification - Client program usage</title>
+
+</head>
+
+<body>
+
+<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>]
+
+<hr>
+
<h1>
-User service daemon and client specification - chapter 2<br>
+User service daemon and client specification - Chapter 2<br>
Client program usage
-
</h1>
-<pre>userv <var>options</var> [--] <var>service-user</var> <var>service-name</var> [<var>argument</var> ...]
-userv <var>options</var> -B|--builtin [--] <var>builtin-service</var> [<var>info-argument</var> ...]</pre><P>
+<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> ...]
+</pre>
+</p>
+
+<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 <code>-</code> to indicate
-that the service user is to be the same as the calling user.<P>
+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>
+<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>
+
<hr>
-<h2><A name="s2.1">
-2.1 Options
-</A></h2>
+<h2>
+<a name="s2.1">2.1 Options</a>
+</h2>
+
+<p>
Single-letter options may be combined as is usual with Unix programs,
and the value for such an option may appear in the same argument or in
the next.
<dl>
-<dt><code>-B</code><dt><code>--builtin</code><dd>Requests that a builtin service be provided. This is equivalent to
-using the <kbd>--override</kbd> option to specify a string consisting of
-<kbd>execute-builtin</kbd> followed by the <var>builtin-service</var>
-requested, and requesting a service user of <code>-</code> (indicating the
-calling user).<P>
+<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
+<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 <kbd>--override</kbd>
-options.<P>
+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.
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 <kbd>execute-builtin</kbd> will be
+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.
-<p><dt><code>-f</code><var>fd</var><code>[</code><var>modifiers</var><code>]=</code><var>filename</var><code></code><dt><code>--file </code><var>fd</var><code>[</code><var>modifiers</var><code>]=</code><var>filename</var><code></code><dd>Requests that data be copied in and out of the service using pipes.
+
+<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 <kbd>cat</kbd> invoked by the client; the
-other file descriptor passed to <kbd>cat</kbd> will be one inherited by
+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>
+on behalf of the caller.
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 <code>stdin</code>, <code>stdout</code> or <code>stderr</code>. The next argument is
+strings <samp>stdin</samp>, <samp>stdout</samp> or <samp>stderr</samp>. The next argument is
a filename which will be opened by the client with the privileges of
the calling user.
-<P>
+
<var>modifiers</var> is used to specify whether the file or descriptor is
to be read from or written to. It consists of a series of words
separated by commas. A comma may separate the <var>modifiers</var> from
the <var>fd</var> and is required if <var>fd</var> is not numeric.
-<P>
+
+<p>
The modifier words are:
<dl compact>
-<dt><code>read</code><dd><code>O_RDONLY</code>: Allow reading and not writing. May not be used with
-<code>write</code> or things that imply it.
-<dt><code>write</code><dd><code>O_WRONLY</code>: Allow writing and not reading. <em>Doesn't truncate or
-create</em> without <code>truncate</code> or <code>create</code>. <code>write</code> or things
-that imply it may not be used with <code>read</code>.
-<dt><code>overwrite</code><dd>Equivalent to <code>write,create,truncate</code>.
-<dt><code>create</code><dt><code>creat</code><dd><code>O_CREAT</code>: Creates the file if necessary. Implies <code>write</code>.
-<dt><code>exclusive</code><dt><code>excl</code><dd><code>O_EXCL</code>: Fails if the file already exists. Implies <code>write</code> and
-<code>create</code>. May not be used with <code>truncate</code>.
-<dt><code>truncate</code><dt><code>trunc</code><dd><code>O_TRUNC</code>: Truncate any existing file. Implies <code>write</code>.
-May not be used with <code>exclusive</code>.
-<dt><code>append</code><dd><code>O_APPEND</code>: All writes will append to the file. Implies <code>write</code>
-(but not <code>create</code>).
-<dt><code>sync</code><dd><code>O_SYNC</code>: Do writes synchronously. Implies <code>write</code>.
-<dt><code>wait</code><dt><code>nowait</code><dt><code>close</code><dd>These modifiers control the behaviour of the client, with respect to
+<dt><samp>read</samp><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>.
+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><code>fd</code><dd>The <var>filename</var> is not a filename but a numeric file descriptor.
-One or both of <code>read</code> and <code>write</code> must be specified, and no
-other words are allowed. The <var>filename</var> may also be <code>stdin</code>,
-<code>stdout</code> or <code>stderr</code> for file descriptor 0, 1 or 2 respectively.
+
+<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.
+
</dl>
-<P>
+</p>
-If no <var>modifiers</var> which imply <code>read</code> or <code>write</code> are used it
-is as if <code>write</code> had been specified, except that if the
+<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 <code>stdin</code>) it is as if <code>overwrite</code> had been
-specified (or <code>write</code> if only <code>fd</code> was specified).<P>
+numerically or with <samp>stdin</samp>) it is as if <samp>overwrite</samp> had been
+specified (or <samp>write</samp> if only <samp>fd</samp> was specified).
+</p>
-The client will also use <code>O_NOCTTY</code> when opening files specified by
-the caller, to avoid changing its controlling terminal.<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>
+the client and daemon will also appear on stderr.
+</p>
-If <code>wait</code> is specified, the client will wait for the pipe to be
+<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
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>
+exited.
+</p>
-If <code>close</code> is specified the client will immediately close the pipe
-connection by killing the relevant copy of <kbd>cat</kbd>. If the service
-uses the descriptor it will get <kbd>SIGPIPE</kbd> (or <kbd>EPIPE</kbd>) for a
+<p>
+If <samp>close</samp> is specified the client will immediately close the pipe
+connection by killing the relevant copy of <code>cat</code>. If the service
+uses the descriptor it will get <code>SIGPIPE</code> (or <code>EPIPE</code>) for a
writing descriptor or end of file for a reading one; the descriptor
-opened by or passed to the client will also be closed.<P>
+opened by or passed to the client will also be closed.
+</p>
-If <code>nowait</code> is specified then the client will not wait and the
+<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 <code>--signals stdout</code> is used) since diagnostics from
+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>
+confused with expected output.
+</p>
-The default is <code>wait</code> for writing file descriptors and <code>close</code>
+<p>
+The default is <samp>wait</samp> for writing file descriptors and <samp>close</samp>
for reading ones.
-<dt><code>-w</code><var>fd</var><code>=</code><var>action</var><code></code><dt><code>--fdwait</code><var>fd</var><code>=</code><var>action</var><code></code><dd>Sets the action on termination of the service for the specified file
-descriptor; <var>action</var> must be <code>wait</code>, <code>nowait</code> or <code>close</code>
+</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 <kbd>--file</kbd> or <kbd>--fdwait</kbd> option - even by a
-<kbd>--file</kbd> which does not specify an action on termination (in this
+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><code>-D</code><var>name</var><code>=</code><var>value</var><code></code><dt><code>--defvar </code><var>name</var><code>=</code><var>value</var><code></code><dd>Set a user-defined variable <var>name</var> to <var>value</var>. These
+
+<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 <code>u-</code><var>name</var><code></code> and are passed to the
-service in environment variables <code>USERV_U_</code><var>name</var><code></code>. <var>name</var>
+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><code>-t </code><var>seconds</var><code></code><dt><code>--timeout </code><var>seconds</var><code></code><dd>Time out the service if it takes longer than <var>seconds</var> seconds (a
+
+<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><code>-S</code> <var>method</var><dt><code>--signals</code> <var>method</var><dd>Affects the handling of the exit status when the service terminates
+
+<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
-<kbd>_exit</kbd>, so that only numbers from 0 to 255 can be returned and
+<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 <kbd>wait</kbd> family of system calls.)<P>
+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
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><code>number</code><dt><code>number-nocore</code><dd>The client's exit status will be the number of the signal which caused
-the termination of the service. If <code>number</code> is used rather than
-<code>number-nocore</code> then 128 will be added if the service dumped core.
-<code>number</code> is very like the exit code mangling done by the Bourne
+
+<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
+<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><code>highbit</code><dd>The client's exit status will be the number of the signal with
+
+<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><code>stdout</code><dd>The service's numeric wait status as two decimal numbers (high byte
+
+<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.</dl>
+and an error message will be printed to stderr as usual.
-<P>
+</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.
-<dt><code>-H</code><dt><code>--hidecwd</code><dd>Prevents the calling process's current directory name from being
+</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><code>-P</code><dt><code>--sigpipe</code><dd>If the service program is terminated due to a <kbd>SIGPIPE</kbd> the exit
+
+<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 <code>stdout</code> is in use.
-<dt><code>-h</code><dt><code>--help</code><dt><code>--copyright</code><dd><code>-h</code> or <code>--help</code> prints the client's usage message;
-<code>--copyright</code> prints the copyright and lack of warranty notice.
+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;
+<samp>--copyright</samp> prints the copyright and lack of warranty notice.
+
</dl>
+</p>
<hr>
-<h2><A name="s-optoverride">
-2.2 Security-overriding options
-</A></h2>
+<h2>
+<a name="s-optoverride">2.2 Security-overriding options</a>
+</h2>
+
+<p>
There are also some options which are available for debugging and to
allow the system administrator to override a user's policy. These
options are available only if the client is called by root or if the
calling user is the same as the service user.
<dl>
-<dt><code>--override </code><var>configuration-data</var><code></code><dt><code>--override-file </code><var>filename</var><code></code><dd>Do not read the usual configuration files. Instead, the client sends
+<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
<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
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><code>--spoof-user </code><var>user</var><code></code><dd>Pretend to the service that it is being called by <var>user</var> (which
+
+<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
-<code>--spoof-user</code> option will <em>not</em> affect which user is chosen if
-the service user is specified as just <code>-</code>; in this case the service
+<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.
-<p></dl>
+</dl>
+</p>
<hr>
-User service daemon and client specification
-- <A href="index.html#copyright"><kbd>userv</kbd> is Copyright 1996-1999 Ian Jackson.</A>
-<br>
-<A href="index.html#toc">Contents</A>; <A href="index.html#abstract">abstract</A>; <A href="ch-envir.html">next</A>; <A href="ch-intro.html">back</A>.
-<br>
-<address>0.61.1<br>
-Ian Jackson <A href="mailto:ian@davenant.greenend.org.uk">ian@davenant.greenend.org.uk</A></address>
-</body></html>
+
+[<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>]
+
+<hr>
+
+User service daemon and client specification<br>
+
+<address>
+1.0.1<br>
+Ian Jackson <a href="mailto:ian@davenant.greenend.org.uk">ian@davenant.greenend.org.uk</a>
+</address>
+
+</body>
+
+</html>
+
~ian / userv.git / blobdiff