path: root/usr.bin/su/su.1

.\"	$OpenBSD: su.1,v 1.38 2022/12/22 19:53:23 kn 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: December 22 2022 $
.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-argument ...
.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.
All of the real, effective, and saved user and group IDs as well as all
supplementary group IDs are always set according to the target user.
If the target
.Ar login
name is not specified,
.Dq root
is used.
.Pp
By default, the shell of the target login is invoked and the
.Ev SHELL
and
.Ev HOME
environment variables are set according to the target login,
whereas the current working directory remains unchanged.
If the target login has a user ID of 0,
.Ev LOGNAME
and
.Ev USER
are preserved and
.Ev PATH
and the
.Xr umask 2
value are set according to
.Xr login.conf 5 ;
otherwise,
.Ev LOGNAME
and
.Ev USER
are set to the target login and
.Ev PATH
and the
.Xr umask 2
value are preserved.
The
.Ev TERM
environment variable is always preserved.
The rest of the environment remains unmodified by default.
.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 executing system or user startup files.
For other shells, start a regular shell instead of a login shell when
the
.Fl l
option is used.
Useful to skip reading shell initialization files.
.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 shell of the target login is invoked and the current working
directory is changed to the home directory of the target login.
.Ev HOME ,
.Ev SHELL ,
.Ev LOGNAME ,
and
.Ev USER
are set to the default values for the target login.
.Ev PATH
and the
.Xr umask 2
value are set according to
.Xr login.conf 5 .
Except for preserving
.Ev TERM ,
the rest of the environment is discarded.
.It Fl m
Leave the environment unmodified.
The login shell of the invoking user is started,
and the current working directory is not changed.
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 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 .
.Sh ENVIRONMENT
The following list provides the values of environment variables
in the new shell that is started by
.Nm .
.Bl -tag -width LOGNAME
.It Ev HOME
The home directory of the target login, except that it remains unchanged with
.Fl m .
.It Ev LOGNAME
The target login by default, but unchanged if the target login has
a UID of 0 or if
.Fl m
is given.
.It Ev PATH
The search path.
It remains unchanged by default, but is set according to the target login
if the target login has a UID of 0 or if
.Fl l
is given.
.It Ev PWD
The current working directory.
It remains unchanged by default,
but is set to the home directory of the target login with
.Fl l .
.It Ev SHELL
The new shell that is started.
It is the shell of the target login by default,
but the shell of the invoking user with
.Fl m .
.It Ev TERM
The terminal type.
It is always retained from the invoking process.
.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 first appeared in
.At v1 .
.Sh BUGS
The login name is not optional for root if there are shell arguments.