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