Man Linux: Main Page and Category List

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.
                                   Doesnt 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 (C)1996-2003,2006 Ian Jackson, except that this
     manpage is Copyright (C)2000 Ben Harris and Copyright (C)2003 Ian
     Jackson.

     GNU userv is licensed under the terms of the GNU General Public Licence,
     version 2 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, write to the Free Software Foundation, 59 Temple
     Place - Suite 330, Boston, MA 02111-1307, USA.

HISTORY

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