xref: /openbsd/usr.bin/su/su.1 (revision 404b540a)
1.\"	$OpenBSD: su.1,v 1.24 2007/05/31 19:20:17 jmc Exp $
2.\"
3.\" Copyright (c) 1988, 1990 The Regents of the University of California.
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\" 3. Neither the name of the University nor the names of its contributors
15.\"    may be used to endorse or promote products derived from this software
16.\"    without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
30.\"	from: @(#)su.1	6.12 (Berkeley) 7/29/91
31.\"
32.Dd $Mdocdate: May 31 2007 $
33.Dt SU 1
34.Os
35.Sh NAME
36.Nm su
37.Nd substitute user identity
38.Sh SYNOPSIS
39.Nm su
40.Op Fl fKLlm
41.Op Fl a Ar auth-type
42.Op Fl c Ar login-class
43.Op Ar login Op Ar "shell arguments"
44.Sh DESCRIPTION
45.Nm
46requests the Kerberos password for
47.Ar login
48(or for
49.Dq Ar login Ns .root ,
50if no login is provided), and switches to
51that user and group ID after obtaining a Kerberos ticket granting access.
52A shell is then executed, and any additional
53.Ar "shell arguments"
54after the login name
55are passed to the shell.
56.Nm
57will resort to the local password file to find the password for
58.Ar login
59if there is a Kerberos error or if Kerberos is not installed.
60If
61.Nm
62is executed by root, no password is requested and a shell
63with the appropriate user ID is executed; no additional Kerberos tickets
64are obtained.
65.Pp
66By default, the environment is unmodified with the exception of
67.Ev LOGNAME ,
68.Ev HOME ,
69.Ev SHELL ,
70and
71.Ev USER .
72.Ev HOME
73and
74.Ev SHELL
75are set to the target login's default values.
76.Ev LOGNAME
77and
78.Ev USER
79are set to the target login, unless the target login has a user ID of 0
80and the
81.Fl l
82flag was not specified,
83in which case it is unmodified.
84The invoked shell is the target login's.
85This is the traditional behavior of
86.Nm su .
87.Pp
88If not using
89.Fl m
90and the target login has a user ID of 0 then the
91.Ev PATH
92variable and umask value
93(see
94.Xr umask 2 )
95are always set according to the
96.Pa /etc/login.conf
97file (see
98.Xr login.conf 5 ) .
99.Pp
100The options are as follows:
101.Bl -tag -width Ds
102.It Fl
103Same as the
104.Fl l
105option (deprecated).
106.It Fl a Ar auth-type
107Specify an authentication type such as
108.Dq skey ,
109.Dq securid ,
110or
111.Dq krb5 .
112.It Fl c Ar login-class
113Specify a login class.
114You may only override the default class if you're already root.
115.It Fl f
116If the invoked shell is
117.Xr csh 1 ,
118this option prevents it from reading the
119.Dq Pa .cshrc
120file.
121.It Fl K
122Do not attempt to use Kerberos to authenticate the user.
123.It Fl L
124Loop until a correct username and password combination is entered,
125similar to
126.Xr login 1 .
127Note that in this mode target
128.Ar login
129must be specified explicitly, either on the command line or interactively.
130Additionally,
131.Nm
132will prompt for the password even when invoked by root.
133.It Fl l
134Simulate a full login.
135The environment is discarded except for
136.Ev HOME ,
137.Ev SHELL ,
138.Ev PATH ,
139.Ev TERM ,
140.Ev LOGNAME ,
141and
142.Ev USER .
143.Ev HOME
144and
145.Ev SHELL
146are modified as above.
147.Ev LOGNAME
148and
149.Ev USER
150are set to the target login.
151.Ev PATH
152is set to the value specified by the
153.Dq path
154entry in
155.Xr login.conf 5 .
156.Ev TERM
157is imported from your current environment.
158The invoked shell is the target login's, and
159.Nm
160will change directory to the target login's home directory.
161.It Fl m
162Leave the environment unmodified.
163The invoked shell is your login shell, and no directory changes are made.
164As a security precaution, if the target user's shell is a non-standard
165shell (as defined by
166.Xr getusershell 3 )
167and the caller's real UID is
168non-zero,
169.Nm
170will fail.
171.El
172.Pp
173The
174.Fl l
175and
176.Fl m
177options are mutually exclusive; the last one specified
178overrides any previous ones.
179.Pp
180If the optional
181.Ar "shell arguments"
182are provided on the command line, they are passed to the login shell of
183the target login.
184This allows it to pass arbitrary commands via the
185.Fl c
186option as understood by most shells.
187Note that
188.Fl c
189usually expects a single argument only; you have to quote it when
190passing multiple words.
191.Pp
192If group 0 (normally
193.Dq wheel )
194has users listed then only those users can
195.Nm
196to
197.Dq root .
198It is not sufficient to change a user's
199.Pa /etc/passwd
200entry to add them to the
201.Dq wheel
202group; they must explicitly be listed in
203.Pa /etc/group .
204If no one is in the
205.Dq wheel
206group, it is ignored, and anyone who knows the root password is permitted to
207.Nm
208to
209.Dq root .
210.Pp
211By default (unless the prompt is reset by a startup file) the superuser
212prompt is set to
213.Dq Sy \&#
214to remind one of its awesome power.
215.Sh ENVIRONMENT
216.Bl -tag -width LOGNAME
217.It Ev HOME
218Default home directory of real user ID unless modified as
219specified above.
220.It Ev LOGNAME
221The user ID is always the effective ID (the target user ID) after an
222.Nm
223unless the user ID is 0 (root).
224.It Ev PATH
225Default search path of real user ID unless modified as specified above.
226.It Ev TERM
227Provides terminal type which may be retained for the substituted
228user ID.
229.It Ev USER
230Same as
231.Ev LOGNAME .
232.El
233.Sh EXAMPLES
234Run the command
235.Dq makewhatis
236as user
237.Dq bin .
238You will be asked for bin's password unless your real UID is 0.
239.Pp
240.Dl $ su bin -c makewhatis
241.Pp
242Same as above, but the target command consists of more than a
243single word:
244.Pp
245.Dl $ su bin -c 'makewhatis /usr/local/man'
246.Pp
247Same as above, but the target command is run with the resource
248limits of the login class
249.Dq staff .
250Note that the first
251.Fl c
252option applies to
253.Nm
254while the second is an argument to the shell.
255.Pp
256.Dl $ su -c staff bin -c 'makewhatis /usr/local/man'
257.Pp
258Pretend a login for user
259.Dq foo :
260.Pp
261.Dl $ su -l foo
262.Pp
263Same as above, but use S/Key for authentication:
264.Pp
265.Dl $ su -a skey -l foo
266.Sh SEE ALSO
267.Xr csh 1 ,
268.Xr kinit 1 ,
269.Xr login 1 ,
270.Xr sh 1 ,
271.Xr skey 1 ,
272.Xr setusercontext 3 ,
273.Xr group 5 ,
274.Xr login.conf 5 ,
275.Xr passwd 5 ,
276.Xr environ 7 ,
277.Xr sudo 8
278.Sh HISTORY
279A
280.Nm
281command appeared in
282.At v7 .
283.Sh BUGS
284There is no direct way to force a particular shell to be used.
285.Pp
286The login name is not optional for root if there are shell arguments.
287