USERV(1) | General Commands Manual | USERV(1) |
userv
— request
user services
userv |
[option ...] [-- ]
service-user service-name
[argument ...] |
userv |
[option ...] -B |
--builtin [-- ]
builtin-service
[info-argument ...] |
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.
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
--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
--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]=filenamecat
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
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
fd
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=actionwait
’,
‘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=valueu-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-S
|
--signals
method_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:
number
,
number-nocore
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
stdout
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
-P
|
--sigpipe
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
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--spoof-user
user--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.LOGNAME
,
USER
USERV_USER
. Their values will only
be used if they correspond to the calling UID.userv
and uservd
.Ian Jackson, User service daemon and client specification.
GNU userv is Copyright 1996-2017 Ian Jackson; Copyright 2000 Ben Harris; and Copyright 2016-2017 Peter Benie.
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/
userv
was initially written in 1996 by Ian
Jackson. It became GNU userv
in 1999, and version
1.0 was released in 2000.
November 3, 1999 | userv |