.\"	$OpenBSD: su.1,v 1.31 2015/07/30 08:03:49 jmc Exp $
.\"
.\" Copyright (c) 1988, 1990 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	from: @(#)su.1	6.12 (Berkeley) 7/29/91
.\"
.Dd $Mdocdate: July 30 2015 $
.Dt SU 1
.Os
.Sh NAME
.Nm su
.Nd substitute user identity
.Sh SYNOPSIS
.Nm su
.Bk -words
.Op Fl fKLlm
.Op Fl a Ar auth-type
.Op Fl c Ar login-class
.Op Fl s Ar login-shell
.Op Ar login Op Ar "shell arguments"
.Ek
.Sh DESCRIPTION
The
.Nm
utility allows a user to run a shell with the user and group ID of another user
without having to log out and in as that other user.
.Pp
By default, the environment is unmodified with the exception of
.Ev LOGNAME ,
.Ev HOME ,
.Ev SHELL ,
and
.Ev USER .
.Ev HOME
and
.Ev SHELL
are set to the target login's default values.
.Ev LOGNAME
and
.Ev USER
are set to the target login, unless the target login has a user ID of 0
and the
.Fl l
flag was not specified,
in which case it is unmodified.
The invoked shell is the target login's.
This is the traditional behavior of
.Nm su .
.Pp
If not using
.Fl m
and the target login has a user ID of 0 then the
.Ev PATH
variable and umask value
(see
.Xr umask 2 )
are always set according to the
.Pa /etc/login.conf
file (see
.Xr login.conf 5 ) .
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl
Same as the
.Fl l
option (deprecated).
.It Fl a Ar auth-type
Specify an authentication type such as
.Dq skey
or
.Dq radius .
.It Fl c Ar login-class
Specify a login class.
You may only override the default class if you're already root.
.It Fl f
If the invoked shell is
.Xr csh 1 ,
this option prevents it from reading the
.Dq Pa .cshrc
file.
.It Fl K
This is shorthand for
.Dq Nm Fl a Ar passwd ,
provided for backwards compatibility.
.It Fl L
Loop until a correct username and password combination is entered,
similar to
.Xr login 1 .
Note that in this mode target
.Ar login
must be specified explicitly, either on the command line or interactively.
Additionally,
.Nm
will prompt for the password even when invoked by root.
.It Fl l
Simulate a full login.
The environment is discarded except for
.Ev HOME ,
.Ev SHELL ,
.Ev PATH ,
.Ev TERM ,
.Ev LOGNAME ,
and
.Ev USER .
.Ev HOME
and
.Ev SHELL
are modified as above.
.Ev LOGNAME
and
.Ev USER
are set to the target login.
.Ev PATH
is set to the value specified by the
.Dq path
entry in
.Xr login.conf 5 .
.Ev TERM
is imported from your current environment.
The invoked shell is the target login's, and
.Nm
will change directory to the target login's home directory.
.It Fl m
Leave the environment unmodified.
The invoked shell is your login shell, and no directory changes are made.
As a security precaution, if the target user's shell is a non-standard
shell (as defined by
.Xr getusershell 3 )
and the caller's real UID is
non-zero,
.Nm
will fail.
.It Fl s Ar login-shell
Specify the path to an alternate login shell.
You may only override the shell if you're already root.
This option will override the shell even if the
.Fl m
option is specified.
.El
.Pp
The
.Fl l
and
.Fl m
options are mutually exclusive; the last one specified
overrides any previous ones.
.Pp
If the optional
.Ar "shell arguments"
are provided on the command line, they are passed to the login shell of
the target login.
This allows it to pass arbitrary commands via the
.Fl c
option as understood by most shells.
Note that
.Fl c
usually expects a single argument only; you have to quote it when
passing multiple words.
.Pp
If group 0 (normally
.Dq wheel )
has users listed then only those users can
.Nm
to
.Dq root .
It is not sufficient to change a user's
.Pa /etc/passwd
entry to add them to the
.Dq wheel
group; they must explicitly be listed in
.Pa /etc/group .
If no one is in the
.Dq wheel
group, it is ignored, and anyone who knows the root password is permitted to
.Nm
to
.Dq root .
.Pp
By default (unless the prompt is reset by a startup file) the superuser
prompt is set to
.Dq Sy \&#
to remind one of its awesome power.
.Sh ENVIRONMENT
.Bl -tag -width LOGNAME
.It Ev HOME
Default home directory of real user ID unless modified as
specified above.
.It Ev LOGNAME
The user ID is always the effective ID (the target user ID) after an
.Nm
unless the user ID is 0 (root).
.It Ev PATH
Default search path of real user ID unless modified as specified above.
.It Ev TERM
Provides terminal type which may be retained for the substituted
user ID.
.It Ev USER
Same as
.Ev LOGNAME .
.El
.Sh EXAMPLES
Run the command
.Dq makewhatis
as user
.Dq bin .
You will be asked for bin's password unless your real UID is 0.
.Pp
.Dl $ su bin -c makewhatis
.Pp
Same as above, but the target command consists of more than a
single word:
.Pp
.Dl $ su bin -c 'makewhatis /usr/local/man'
.Pp
Same as above, but the target command is run with the resource
limits of the login class
.Dq staff .
Note that the first
.Fl c
option applies to
.Nm
while the second is an argument to the shell.
.Pp
.Dl $ su -c staff bin -c 'makewhatis /usr/local/man'
.Pp
Pretend a login for user
.Dq foo :
.Pp
.Dl $ su -l foo
.Pp
Same as above, but use S/Key for authentication:
.Pp
.Dl $ su -a skey -l foo
.Sh SEE ALSO
.Xr doas 1 ,
.Xr login 1 ,
.Xr setusercontext 3 ,
.Xr group 5 ,
.Xr login.conf 5 ,
.Xr passwd 5 ,
.Xr environ 7
.Sh HISTORY
A
.Nm
command appeared in
.At v7 .
.Sh BUGS
The login name is not optional for root if there are shell arguments.