Provided by: userv_1.2.1~beta4_amd64 bug

NAME

     userv — request user services

SYNOPSIS

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

DESCRIPTION

     userv is used to have a task performed under different userid while maintaining limited
     trust between caller and callee.

     service-user specifies which user account is to perform the task.  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 daemon on behalf of the service user.  This is
     controlled by configuration files in the service user's filespace; consult the userv
     specification for details.

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
                 the specification, or the output of
                       userv -B help
                 for details of the builtin services available, and below 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.

     -f | --file fd[fdmodifiers]=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.

     -w | --fdwait fd=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).

     -D | --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 | --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).

     -S | --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
                 Prints the client's usage message.

     --copyright
                 Prints the copyright and lack of warranty notice.

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 file
                 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.

ENVIRONMENT

     LOGNAME, USER    These are used to determine the name of the calling user, to be passed to
                      the service in USERV_USER.  Their values will only be used if they
                      correspond to the calling UID.

FILES

     /var/run/userv/socket             UNIX-domain socket used for communication between userv
                                       and uservd.

     /var/run/userv/%x.%x.%x           Pipes used for connecting file descriptors in the client
                                       and the service.

SEE ALSO

     uservd(8)

     Ian Jackson, User service daemon and client specification.

COPYRIGHT

     GNU userv is copyright Ian Jackson and other contributors.  See README or userv --copright
     for full authorship information.

     GNU userv is licensed under the terms of the GNU General Public Licence, version 3 or (at
     your option) any later version, and it comes with NO WARRANTY, not even the implied warranty
     of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
     for details.

     You should have received a copy of the GNU General Public License along with userv, if not,
     see http://www.gnu.org/licenses/

HISTORY

     userv was initially written in 1996 by Ian Jackson.  It became GNU userv in 1999, and
     version 1.0 was released in 2000.