+++ /dev/null
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
-
-<html>
-
-<head>
-
-<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
-
-<title>User service daemon and client specification - Client program usage</title>
-
-</head>
-
-<body>
-
-<a name="ch-client"></a>
-<hr>
-
-[ <a href="ch-intro.html">previous</a> ]
-[ <a href="index.html#contents">Contents</a> ]
-[ <a href="ch-intro.html">1</a> ]
-[ 2 ]
-[ <a href="ch-envir.html">3</a> ]
-[ <a href="ch-config.html">4</a> ]
-[ <a href="ch-ipass.html">5</a> ]
-[ <a href="ch-notes.html">6</a> ]
-[ <a href="ch-envir.html">next</a> ]
-
-<hr>
-
-<h1>
-User service daemon and client specification
-<br>Chapter 2 - Client program usage
-</h1>
-
-
-<pre>
- userv <var>options</var> [--] <var>service-user</var> <var>service-name</var> [<var>argument</var> ...]
- userv <var>options</var> -B|--builtin [--] <var>builtin-service</var> [<var>info-argument</var> ...]
-</pre>
-
-<hr>
-
-
-<p>
-<var>service-user</var> specifies which user is to provide the service. The
-user may be a login name or a numeric uid, or <samp>-</samp> to indicate that
-the service user is to be the same as the calling user.
-
-<p>
-The service name is interpreted by the userv[<a href="footnotes.html#f1"
-name="fr1">1</a>] daemon on behalf of the service user. It will often be the
-name of a program.
-
-<hr>
-
-<a name="s2.1"></a>
-<h2>2.1 Options</h2>
-
-<p>
-Single-letter options may be combined as is usual with Unix programs, and the
-value for such an option may appear in the same argument or in the next.
-<dl>
-<dt><samp>-B</samp></dt>
-<dt><samp>--builtin</samp></dt>
-<dd>
-Requests that a builtin service be provided. This is equivalent to using the
-<code>--override</code> option to specify a string consisting of
-<code>execute-builtin</code> followed by the <var>builtin-service</var>
-requested, and requesting a service user of <samp>-</samp> (indicating the
-calling user).
-
-<p>
-If the builtin service being requested requires a <var>service-argument</var>
-then this must be supplied to the client in the same argument as the
-<var>builtin-service</var>. See <a
-href="ch-config.html#s-dirs-execution">Directives for changing execution
-settings, Section 4.2.4</a> for details of the builtin services available, and
-<a href="ch-client.html#s-optoverride">Security-overriding options, Section
-2.2</a> for details of the <code>--override</code> options.
-
-<p>
-The actual service name passed will be the <var>builtin-service</var>; note
-that this actual service name (as opposed to the override data) and the
-<var>info-argument</var>s supplied will be ignored by most builtin services;
-the override mechanism and <code>execute-builtin</code> will be used to ensure
-that the right builtin service is called with the right
-<var>service-argument</var>s.
-</dd>
-</dl>
-<dl>
-<dt><samp>--file <var>fd</var>[<var>modifiers</var>]=<var>filename</var></samp></dt>
-<dd>
-Requests that data be copied in and out of the service using pipes. For each
-file or descriptor this will be done by creating a pipe, one end of which is
-passed to the service program and the other end of which is passed to a copy of
-<code>cat</code> invoked by the client; the other file descriptor passed to
-<code>cat</code> will be one inherited by the client program from the caller or
-one opened by the client program on behalf of the caller.
-
-<p>
-The descriptor in the service program that should be connected must be
-specified as <var>fd</var>, either as a decimal number or as one of the strings
-<samp>stdin</samp>, <samp>stdout</samp> or <samp>stderr</samp>. The next
-argument is a filename which will be opened by the client with the privileges
-of the calling user.
-
-<p>
-<var>modifiers</var> is used to specify whether the file or descriptor is to be
-read from or written to. It consists of a series of words separated by commas.
-A comma may separate the <var>modifiers</var> from the <var>fd</var> and is
-required if <var>fd</var> is not numeric.
-
-<p>
-The modifier words are:
-<dl>
-<dt><samp>read</samp></dt>
-<dd>
-<samp>O_RDONLY</samp>: Allow reading and not writing. May not be used with
-<samp>write</samp> or things that imply it.
-</dd>
-<dt><samp>write</samp></dt>
-<dd>
-<samp>O_WRONLY</samp>: Allow writing and not reading. <em>Doesn't truncate or
-create</em> without <samp>truncate</samp> or <samp>create</samp>.
-<samp>write</samp> or things that imply it may not be used with
-<samp>read</samp>.
-</dd>
-<dt><samp>overwrite</samp></dt>
-<dd>
-Equivalent to <samp>write,create,truncate</samp>.
-</dd>
-<dt><samp>create</samp></dt>
-<dt><samp>creat</samp></dt>
-<dd>
-<samp>O_CREAT</samp>: Creates the file if necessary. Implies
-<samp>write</samp>.
-</dd>
-<dt><samp>exclusive</samp></dt>
-<dt><samp>excl</samp></dt>
-<dd>
-<samp>O_EXCL</samp>: Fails if the file already exists. Implies
-<samp>write</samp> and <samp>create</samp>. May not be used with
-<samp>truncate</samp>.
-</dd>
-<dt><samp>truncate</samp></dt>
-<dt><samp>trunc</samp></dt>
-<dd>
-<samp>O_TRUNC</samp>: Truncate any existing file. Implies <samp>write</samp>.
-May not be used with <samp>exclusive</samp>.
-</dd>
-<dt><samp>append</samp></dt>
-<dd>
-<samp>O_APPEND</samp>: All writes will append to the file. Implies
-<samp>write</samp> (but not <samp>create</samp>).
-</dd>
-<dt><samp>sync</samp></dt>
-<dd>
-<samp>O_SYNC</samp>: Do writes synchronously. Implies <samp>write</samp>.
-</dd>
-<dt><samp>wait</samp></dt>
-<dt><samp>nowait</samp></dt>
-<dt><samp>close</samp></dt>
-<dd>
-These modifiers control the behaviour of the client, with respect to the pipes
-carrying data to and from the service, when the service terminates. See below.
-</dd>
-<dt><samp>fd</samp></dt>
-<dd>
-The <var>filename</var> is not a filename but a numeric file descriptor. One
-or both of <samp>read</samp> and <samp>write</samp> must be specified, and no
-other words are allowed. The <var>filename</var> may also be
-<samp>stdin</samp>, <samp>stdout</samp> or <samp>stderr</samp> for file
-descriptor 0, 1 or 2 respectively.
-</dd>
-</dl>
-
-<p>
-If no <var>modifiers</var> which imply <samp>read</samp> or <samp>write</samp>
-are used it is as if <samp>write</samp> had been specified, except that if the
-filedescriptor 0 of the service is being opened (either specified numerically
-or with <samp>stdin</samp>) it is as if <samp>overwrite</samp> had been
-specified (or <samp>write</samp> if only <samp>fd</samp> was specified).
-
-<p>
-The client will also use <samp>O_NOCTTY</samp> when opening files specified by
-the caller, to avoid changing its controlling terminal.
-
-<p>
-By default stdin, stdout and stderr of the service will be connected to the
-corresponding descriptors on the client. Diagnostics from the client and
-daemon will also appear on stderr.
-
-<p>
-If <samp>wait</samp> is specified, the client will wait for the pipe to be
-closed, and only exit after this has happened. This means that either the
-receiving end of the pipe connection was closed while data was still available
-at the sending end, or that the end of file was reached on the reading file
-descriptor. Errors encountered reading or writing in the client at this stage
-will be considered a system error and cause the client to exit with status 255,
-but will not cause disconnection at the service side since the service has
-already exited.
-
-<p>
-If <samp>close</samp> is specified the client will immediately close the pipe
-connection by killing the relevant copy of <code>cat</code>. If the service
-uses the descriptor it will get <code>SIGPIPE</code> (or <code>EPIPE</code>)
-for a writing descriptor or end of file for a reading one; the descriptor
-opened by or passed to the client will also be closed.
-
-<p>
-If <samp>nowait</samp> is specified then the client will not wait and the
-connection will remain open after the client terminates. Data may continue to
-be passed between the inheritors of the relevant descriptor on the service side
-and the corresponding file or descriptor on the client side until either side
-closes their descriptor. This should not usually be specified for stderr (or
-stdout if <samp>--signals stdout</samp> is used) since diagnostics from the
-service side may arrive after the client has exited and be confused with
-expected output.
-
-<p>
-The default is <samp>wait</samp> for writing file descriptors and
-<samp>close</samp> for reading ones.
-</dd>
-</dl>
-<dl>
-<dt><samp>-w<var>fd</var>=<var>action</var></samp></dt>
-<dt><samp>--fdwait<var>fd</var>=<var>action</var></samp></dt>
-<dd>
-Sets the action on termination of the service for the specified file
-descriptor; <var>action</var> must be <samp>wait</samp>, <samp>nowait</samp> or
-<samp>close</samp> as described above. The file descriptor must be specified
-as open when this option is encountered; this option is overridden by any later
-<code>--file</code> or <code>--fdwait</code> option - even by a
-<code>--file</code> which does not specify an action on termination (in this
-case the default will be used, as described above).
-</dd>
-</dl>
-<dl>
-<dt><samp>-D<var>name</var>=<var>value</var></samp></dt>
-<dt><samp>--defvar <var>name</var>=<var>value</var></samp></dt>
-<dd>
-Set a user-defined variable <var>name</var> to <var>value</var>. These
-user-defined variables are made available in the configuration language as the
-parameters <samp>u-<var>name</var></samp> and are passed to the service in
-environment variables <samp>USERV_U_<var>name</var></samp>. <var>name</var>
-may contain only alphanumerics and underscores, and must start with a letter.
-If several definitions are given for the same <var>name</var> then only the
-last is effective.
-</dd>
-</dl>
-<dl>
-<dt><samp>-t <var>seconds</var></samp></dt>
-<dt><samp>--timeout <var>seconds</var></samp></dt>
-<dd>
-Time out the service if it takes longer than <var>seconds</var> seconds (a
-positive integer, in decimal). Timeout will produce a diagnostic on stderr and
-an exit status of 255. If <var>seconds</var> is zero then no timeout will be
-implemented (this is the default).
-</dd>
-</dl>
-<dl>
-<dt><samp>--signals</samp> <var>method</var></dt>
-<dd>
-Affects the handling of the exit status when the service terminates due to a
-signal. (The client will always finish by calling <code>_exit</code>, so that
-only numbers from 0 to 255 can be returned and not the full range of numbers
-and signal indications which can be returned by the <code>wait</code> family of
-system calls.)
-
-<p>
-The <var>method</var> may be one of the following:
-<dl>
-<dt><var>status</var></dt>
-<dd>
-The client's exit status will be <var>status</var>. This will not be
-distinguishable from the service really having exited with code
-<var>status</var>. This method is the default, with a <var>status</var> of
-254.
-</dd>
-<dt><samp>number</samp></dt>
-<dt><samp>number-nocore</samp></dt>
-<dd>
-The client's exit status will be the number of the signal which caused the
-termination of the service. If <samp>number</samp> is used rather than
-<samp>number-nocore</samp> then 128 will be added if the service dumped core.
-<samp>number</samp> is very like the exit code mangling done by the Bourne
-shell.
-</dd>
-<dt><samp>highbit</samp></dt>
-<dd>
-The client's exit status will be the number of the signal with 128 added. If
-the service exits normally with an exit code of greater than 127 then 127 will
-be returned.
-</dd>
-<dt><samp>stdout</samp></dt>
-<dd>
-The service's numeric wait status as two decimal numbers (high byte first) and
-a textual description of its meaning will be printed to the client's standard
-output. It will be preceded by a newline and followed by an extra newline, and
-the numbers are separated from each other and from the textual description by
-single spaces. The exit status of the client will be zero, unless a system
-error occurs in which case no exit status and description will be printed to
-stdout, and an error message will be printed to stderr as usual.
-</dd>
-</dl>
-
-<p>
-Problems such as client usage errors, the service not being found or permission
-being denied or failure of a system call are system errors. An error message
-describing the problem will be printed on the client's stderr, and the client's
-exit status will be 255. If the client dies due to a signal this should be
-treated as a serious system error.
-</dd>
-</dl>
-<dl>
-<dt><samp>-H</samp></dt>
-<dt><samp>--hidecwd</samp></dt>
-<dd>
-Prevents the calling process's current directory name from being passed to the
-service; the null string will be passed instead.
-</dd>
-</dl>
-<dl>
-<dt><samp>-P</samp></dt>
-<dt><samp>--sigpipe</samp></dt>
-<dd>
-If the service program is terminated due to a <code>SIGPIPE</code> the exit
-status of the client will be zero, even if it would have been something else
-according to the exit status method specified. This option has no effect on
-the code and description printed if the exit status method <samp>stdout</samp>
-is in use.
-</dd>
-</dl>
-<dl>
-<dt><samp>-h</samp></dt>
-<dt><samp>--help</samp></dt>
-<dt><samp>--copyright</samp></dt>
-<dd>
-<samp>-h</samp> or <samp>--help</samp> prints the client's usage message;
-<samp>--copyright</samp> prints the copyright and lack of warranty notice.
-</dd>
-</dl>
-
-<hr>
-
-<a name="s-optoverride"></a>
-<h2>2.2 Security-overriding options</h2>
-
-<p>
-There are also some options which are available for debugging and to allow the
-system administrator to override a user's policy. These options are available
-only if the client is called by root or if the calling user is the same as the
-service user.
-<dl>
-<dt><samp>--override <var>configuration-data</var></samp></dt>
-<dt><samp>--override-file <var>filename</var></samp></dt>
-<dd>
-Do not read the usual configuration files. Instead, the client sends
-<var>configuration-data</var> (followed by a newline) or the contents of
-<var>filename</var> (which is opened in the context of the client) to the
-daemon and the daemon uses that data instead. The
-<var>configuration-data</var> must all be in one argument. It will have a
-single newline appended so that a single directive can easily be given, but if
-more than one directive is required it will have to contain one or more real
-newlines.
-</dd>
-</dl>
-<dl>
-<dt><samp>--spoof-user <var>user</var></samp></dt>
-<dd>
-Pretend to the service that it is being called by <var>user</var> (which may be
-a username or a uid). This will also affect the group and supplementary groups
-supplied to the service; they will be the standard group and supplementary
-groups for <var>user</var>. The <samp>--spoof-user</samp> option will
-<em>not</em> affect which user is chosen if the service user is specified as
-just <samp>-</samp>; in this case the service user will be the real calling
-user.
-</dd>
-</dl>
-
-<hr>
-
-[ <a href="ch-intro.html">previous</a> ]
-[ <a href="index.html#contents">Contents</a> ]
-[ <a href="ch-intro.html">1</a> ]
-[ 2 ]
-[ <a href="ch-envir.html">3</a> ]
-[ <a href="ch-config.html">4</a> ]
-[ <a href="ch-ipass.html">5</a> ]
-[ <a href="ch-notes.html">6</a> ]
-[ <a href="ch-envir.html">next</a> ]
-
-<hr>
-
-<p>
-User service daemon and client specification
-
-<address>
-1.0.3<br>
-Ian Jackson <code><a href="mailto:ian@davenant.greenend.org.uk">ian@davenant.greenend.org.uk</a></code>
-</address>
-
-<hr>
-
-</body>
-
-</html>
-
~ian / userv.git / blobdiff