.TH US 1 "JULY 2021" "Alessandro Mauri"

.SH NAME
us \- execute command with another identity

.SH SYNOPSIS
.SY us
.OP \-hseA
.OP \-u user
.OP \-g group
.OP \-C config
.OP command
.OP args
.YS

.SH DESCRIPTION
.PP
The
.BR us
utility executes the given command as another identity, which by default is
root. If no command is specified, it starts a shell as that user.
.PP
In order to execute anything users need to authenticate and the user + target
identity configuration must be allowed in the configuration file, see
.BR us.conf(5)
for more information.
.PP
By default when a command or shell gets executed a new environment gets created,
USER is set with the target user, as well as LOGNAME, SHELL and HOME get all set
with the default values for the target user.
PATH, TERM, EDITOR, VISUAL, DISPLAY and XAUTHORITY instead are kept between
execution.
Lastly a new variable US_USER is added (but not overridden) which contains the
calling user's username.
.PP
Invoking the program logs by default to
.BR syslog(2)
the outcome of the invocation, this behavior can be changed in the config.

.SH OPTIONS
.IP \-h
Print usage info message.
.IP \-s
Use the calling user's SHELL instead of the target user's one.
.IP \-e
Keep the entire environment between execution instead of just PATH, TERM,
EDITOR, VISUAL, DISPLAY and XAUTHORITY; user variables still get overridden.
.IP \-A
Instead of prompting for a password,
.BR us
executes the command specified in the variable US_ASKPASS and reads it's stdout
as the password. If US_ASKPASS is not specified then it will fall back
prompting the password.
.IP "\-u user"
Change the target identity to
.I user
(default is root).
.IP "\-g group"
Set the group of the target user to
.I group
instead of the target user's default, also add it to the group list.
.IP "\-C config"
Use the specified config file

.SH "RETURN VALUE"
The
.BR us
utility returns 0 on success and != 0 on failure which may occur on various
occasions. An error message will be outputted to specify the reason.

.SH "SEE ALSO"
.BR su(1)
.BR us.conf(5)

.SH AUTHOR
Alessandro Mauri <alemauri001@tuta.io>