User service daemon and client specification
Chapter 2 Client program usage

     userv options [--] service-user service-name [argument ...]
     userv options -B|--builtin [--] builtin-service [info-argument ...]

service-user specifies which user is to provide the service. The user may be a login name or a numeric uid, or - to indicate that the service user is to be the same as the calling user.

The service name is interpreted by the userv[1] daemon on behalf of the service user. It will often be the name of a program.

2.1 Options

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.

-B

--builtin

Requests that a builtin service be provided. This is equivalent to using the --override option to specify a string consisting of execute-builtin followed by the builtin-service requested, and requesting a service user of - (indicating the calling user).

If the builtin service being requested requires a service-argument then this must be supplied to the client in the same argument as the builtin-service. See Directives for changing execution settings, Section 4.2.4 for details of the builtin services available, and Security-overriding options, Section 2.2 for details of the --override options.

The actual service name passed will be the builtin-service; note that this actual service name (as opposed to the override data) and the info-arguments supplied will be ignored by most builtin services; the override mechanism and execute-builtin will be used to ensure that the right builtin service is called with the right service-arguments.

--file fd[modifiers]=filename

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 cat invoked by the client; the other file descriptor passed to cat will be one inherited by the client program from the caller or one opened by the client program on behalf of the caller.

The descriptor in the service program that should be connected must be specified as fd, either as a decimal number or as one of the strings stdin, stdout or stderr. The next argument is a filename which will be opened by the client with the privileges of the calling user.

modifiers 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 modifiers from the fd and is required if fd is not numeric.

The modifier words are:

read

O_RDONLY: Allow reading and not writing. May not be used with write or things that imply it.

write

O_WRONLY: Allow writing and not reading. Doesn't truncate or create without truncate or create. write or things that imply it may not be used with read.

overwrite

Equivalent to write,create,truncate.

create

creat

O_CREAT: Creates the file if necessary. Implies write.

exclusive

excl

O_EXCL: Fails if the file already exists. Implies write and create. May not be used with truncate.

truncate

trunc

O_TRUNC: Truncate any existing file. Implies write. May not be used with exclusive.

append

O_APPEND: All writes will append to the file. Implies write (but not create).

sync

O_SYNC: Do writes synchronously. Implies write.

wait

nowait

close

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.

fd

The filename is not a filename but a numeric file descriptor. One or both of read and write must be specified, and no other words are allowed. The filename may also be stdin, stdout or stderr for file descriptor 0, 1 or 2 respectively.

If no modifiers which imply read or write are used it is as if write had been specified, except that if the filedescriptor 0 of the service is being opened (either specified numerically or with stdin) it is as if overwrite had been specified (or write if only fd was specified).

The client will also use O_NOCTTY when opening files specified by the caller, to avoid changing its controlling terminal.

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.

If wait 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.

If close is specified the client will immediately close the pipe connection by killing the relevant copy of cat. If the service uses the descriptor it will get SIGPIPE (or EPIPE) 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.

If nowait 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 --signals stdout is used) since diagnostics from the service side may arrive after the client has exited and be confused with expected output.

The default is wait for writing file descriptors and close for reading ones.

-wfd=action

--fdwaitfd=action

Sets the action on termination of the service for the specified file descriptor; action must be wait, nowait or close as described above. The file descriptor must be specified as open when this option is encountered; this option is overridden by any later --file or --fdwait option - even by a --file which does not specify an action on termination (in this case the default will be used, as described above).

-Dname=value

--defvar name=value

Set a user-defined variable name to value. These user-defined variables are made available in the configuration language as the parameters u-name and are passed to the service in environment variables USERV_U_name. name may contain only alphanumerics and underscores, and must start with a letter. If several definitions are given for the same name then only the last is effective.

-t seconds

--timeout seconds

Time out the service if it takes longer than seconds seconds (a positive integer, in decimal). Timeout will produce a diagnostic on stderr and an exit status of 255. If seconds is zero then no timeout will be implemented (this is the default).

--signals method

Affects the handling of the exit status when the service terminates due to a signal. (The client will always finish by calling _exit, 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 wait family of system calls.)

The method may be one of the following:

status

The client's exit status will be status. This will not be distinguishable from the service really having exited with code status. This method is the default, with a status of 254.

number

number-nocore

The client's exit status will be the number of the signal which caused the termination of the service. If number is used rather than number-nocore then 128 will be added if the service dumped core. number is very like the exit code mangling done by the Bourne shell.

highbit

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.

stdout

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.

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.

-H

--hidecwd

Prevents the calling process's current directory name from being passed to the service; the null string will be passed instead.

-P

--sigpipe

If the service program is terminated due to a SIGPIPE 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 stdout is in use.

-h

--help

--copyright

-h or --help prints the client's usage message; --copyright prints the copyright and lack of warranty notice.

2.2 Security-overriding options

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.

--override configuration-data

--override-file filename

Do not read the usual configuration files. Instead, the client sends configuration-data (followed by a newline) or the contents of filename (which is opened in the context of the client) to the daemon and the daemon uses that data instead. The configuration-data 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.

--spoof-user user

Pretend to the service that it is being called by user (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 user. The --spoof-user option will not affect which user is chosen if the service user is specified as just -; in this case the service user will be the real calling user.