| blob | 1226c3051a66a6b61203e36308c08202e0b3422b |
1 .\" Copyright (c) 1988, 1990, 1993, 1994
2 .\" The Regents of the University of California. All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. Neither the name of the University nor the names of its contributors
13 .\" may be used to endorse or promote products derived from this software
14 .\" without specific prior written permission.
15 .\"
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .\" SUCH DAMAGE.
27 .\"
28 .\" from: @(#)su.1 8.2 (Berkeley) 4/18/94
29 .\" $NetBSD: su.1,v 1.51 2014/09/19 16:02:58 wiz Exp $
30 .\"
31 .Dd November 20, 2012
32 .Dt SU 1
33 .Os
34 .Sh NAME
35 .Nm su
36 .Nd substitute user identity
37 .Sh SYNOPSIS
38 .Nm
39 .Op Fl dfKlm
40 .Op Fl c Ar login-class
41 .Oo
42 .Ar login Ns Op : Ns Ar group
43 .Op Ar "shell arguments"
44 .Oc
45 .Nm
46 .Op Fl dfKlm
47 .Op Fl c Ar login-class
48 .Oo
49 .Ns : Ns Ar group
50 .Op Ar "shell arguments"
51 .Oc
52 .Sh DESCRIPTION
53 .Nm
54 allows one user to become another user
55 .Ar login
56 without logging out and in as
57 the new user.
58 If a
59 .Ar group
60 is specified and
61 .Ar login
62 is a member of
63 .Ar group ,
64 then the group is changed to
65 .Ar group
66 rather than to
67 .Ar login Ns 's
68 primary group.
69 If
70 .Ar login
71 is omitted and
72 .Ar group
73 is provided (form two above), then
74 .Ar login
75 is assumed to be the current username.
76 .Pp
77 When executed by a user, the
78 .Ar login
79 user's password is requested.
80 When using Kerberos, the password for
81 .Ar login
82 (or for
83 .Dq Ar login Ns .root ,
84 if no login is provided) is requested, and
85 .Nm
86 switches to that user and group ID after obtaining a Kerberos ticket
87 granting ticket.
88 A shell is then executed, and any additional
89 .Ar "shell arguments"
90 after the login name are passed to the shell.
91 .Nm
92 will resort to the local password file to find the password for
93 .Ar login
94 if there is a Kerberos error.
95 If
96 .Nm
97 is executed by root, no password is requested and a shell
98 with the appropriate user ID is executed; no additional Kerberos tickets
99 are obtained.
100 .Pp
101 Alternatively, if the user enters the password "s/key", authentication
102 will use the S/Key one-time password system as described in
103 .Xr skey 1 .
104 S/Key is a Trademark of Bellcore.
105 .Pp
106 By default, the environment is unmodified with the exception of
107 .Ev LOGNAME ,
108 .Ev USER ,
109 .Ev HOME ,
110 .Ev SHELL ,
111 and
112 .Ev SU_FROM .
113 .Ev HOME
114 and
115 .Ev SHELL
116 are set to the target login's default values.
117 .Ev LOGNAME
118 and
119 .Ev USER
120 are set to the target login, unless the target login has a user ID of 0,
121 in which case they are unmodified.
122 .Ev SU_FROM
123 is set to the caller's login.
124 The invoked shell is the target login's.
125 With the exception of
126 .Ev SU_FROM
127 this is the traditional behavior of
128 .Nm .
129 .Pp
130 The options are as follows:
131 .Bl -tag -width Ds
132 .It Fl c
133 Specify a login class.
134 You may only override the default class if you're already root.
135 See
136 .Xr login.conf 5
137 for details.
138 .It Fl d
139 Same as
140 .Fl l ,
141 but does not change the current directory.
142 .It Fl f
143 If the invoked shell is
144 .Xr csh 1 ,
145 this option prevents it from reading the
146 .Dq Pa .cshrc
147 file.
148 If the invoked shell is
149 .Xr sh 1 ,
150 or
151 .Xr ksh 1 ,
152 this option unsets
153 .Ev ENV ,
154 thus preventing the shell from executing the startup file pointed to by
155 this variable.
156 .It Fl K
157 Do not attempt to use Kerberos to authenticate the user.
158 .It Fl l
159 Simulate a full login.
160 The environment is discarded except for
161 .Ev HOME ,
162 .Ev SHELL ,
163 .Ev PATH ,
164 .Ev TERM ,
165 .Ev LOGNAME ,
166 .Ev USER ,
167 and
168 .Ev SU_FROM .
169 .Ev HOME ,
170 .Ev SHELL ,
171 and
172 .Ev SU_FROM
173 are modified as above.
174 .Ev LOGNAME
175 and
176 .Ev USER
177 are set to the target login.
178 .Ev PATH
179 is set to the path specified in the
180 .Pa /etc/login.conf
181 file (or to the default of
182 .Dq Pa /usr/bin:/bin:/usr/pkg/bin:/usr/local/bin
183 ).
184 .Ev TERM
185 is imported from your current environment.
186 The invoked shell is the target login's, and
187 .Nm
188 will change directory to the target login's home directory.
189 The
190 .Xr utmp 5 ,
191 .Xr wtmp 5 ,
192 and
193 .Xr lastlogin 5
194 databases are not updated.
195 .It Fl
196 Same as
197 .Fl l .
198 .It Fl m
199 Leave the environment unmodified.
200 The invoked shell is your login shell, and no directory changes are made.
201 As a security precaution, if the target user's shell is a non-standard
202 shell (as defined by
203 .Xr getusershell 3 )
204 and the caller's real uid is
205 non-zero,
206 .Nm
207 will fail.
208 .El
209 .Pp
210 The
211 .Fl l
212 and
213 .Fl m
214 options are mutually exclusive; the last one specified
215 overrides any previous ones.
216 .Pp
217 Only users in group
218 .Dq wheel
219 (normally gid 0),
220 as listed in
221 .Pa /etc/group ,
222 can
223 .Nm
224 to
225 .Dq root ,
226 unless group wheel does not exist or has no members.
227 (If you do not want anybody to be able to
228 .Nm
229 to
230 .Dq root ,
231 make
232 .Dq root
233 the only member of group
234 .Dq wheel ,
235 which is the default.)
236 .Pp
237 For sites with very large user populations, group
238 .Dq wheel
239 can contain the names of other groups that will be considered authorized
240 to
241 .Nm
242 to
243 .Dq root .
244 .Pp
245 By default (unless the prompt is reset by a startup file) the super-user
246 prompt is set to
247 .Dq Sy \&#
248 to remind one of its awesome power.
249 .Sh CUSTOMIZATION
250 .Bl -tag -width ""
251 .It Changing required group
252 For the
253 .Xr pam 8
254 version of
255 .Nm
256 the name of the required group can be changed by setting
257 .Ar gname
258 in
259 .Xr pam.conf 5 :
260 .Bd -literal
261 auth requisite pam_group.so no_warn group=gname root_only fail_safe
262 .Ed
263 .Pp
264 For the non
265 .Xr pam 8
266 version of
267 .Nm
268 the same can be achieved by compiling with
269 .Dv SU_GROUP
270 set to the desired group name.
271 .It Supplying own password
272 .Nm
273 can be configured so that users in a particular group can supply their
274 own password to become
275 .Dq root .
276 For the
277 .Xr pam 8
278 version of
279 .Nm
280 this can be done by adding a line to
281 .Xr pam.conf 5
282 such as:
283 .Bd -literal
284 auth sufficient pam_group.so no_warn group=gname root_only authenticate
285 .Ed
286 .Pp
287 where
288 .Ar gname
289 is the name of the desired group.
290 For the non
291 .Xr pam 8
292 version of
293 .Nm
294 the same can be achieved by compiling with
295 .Dv SU_ROOTAUTH
296 set to the desired group name.
297 .It Indirect groups
298 This option is not available with the
299 .Xr pam 8
300 version of
301 .Nm .
302 For the non
303 .Xr pam 8
304 version of
305 .Nm ,
306 if
307 .Dv SU_INDIRECT_GROUP
308 is defined, the
309 .Ar SU_GROUP
310 and
311 .Ar SU_ROOTAUTH
312 groups are treated as indirect groups.
313 The group members of those two groups are treated as groups themselves.
314 .El
315 .Sh ENVIRONMENT
316 Environment variables used by
317 .Nm :
318 .Bl -tag -width "HOME"
319 .It Ev HOME
320 Default home directory of real user ID unless modified as
321 specified above.
322 .It Ev LOGNAME
323 The user ID is always the effective ID (the target user ID) after an
324 .Nm
325 unless the user ID is 0 (root).
326 .It Ev PATH
327 Default search path of real user ID unless modified as specified above.
328 .It Ev TERM
329 Provides terminal type which may be retained for the substituted
330 user ID.
331 .It Ev USER
332 The user ID is always the effective ID (the target user ID) after an
333 .Nm
334 unless the user ID is 0 (root).
335 .El
336 .Sh EXIT STATUS
337 .Nm
338 returns the exit status of the executed subshell, or 1 if any error
339 occurred while switching privileges.
340 .Sh EXAMPLES
341 To become user username and use the same environment as in original shell, execute:
342 .Bd -literal -offset indent
343 su username
344 .Ed
345 .Pp
346 To become user username and use environment as if full login would be performed,
347 execute:
348 .Bd -literal -offset indent
349 su -l username
350 .Ed
351 .Pp
352 When a
353 .Fl c
354 option is included
355 .Em after
356 the
357 .Ar login
358 name it is not a
359 .Nm
360 option, because any arguments after the
361 .Ar login
362 are passed to the shell.
363 (See
364 .Xr csh 1 ,
365 .Xr ksh 1
366 or
367 .Xr sh 1
368 for details.)
369 To execute arbitrary command with privileges of user
370 .Em username ,
371 execute:
372 .Bd -literal -offset indent
373 su username -c "command args"
374 .Ed
375 .Sh SEE ALSO
376 .Xr csh 1 ,
377 .Xr kinit 1 ,
378 .Xr login 1 ,
379 .Xr sh 1 ,
380 .Xr skey 1 ,
381 .Xr setusercontext 3 ,
382 .Xr group 5 ,
383 .Xr login.conf 5 ,
384 .Xr passwd 5 ,
385 .Xr environ 7 ,
386 .Xr kerberos 8
387 .Sh HISTORY
388 A
389 .Nm
390 command existed in
391 .At v5
392 (and probably earlier).