| blob | 686ea14949684003af3de553186afcceedbe04a9 |
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.48 2007/10/27 18:43:37 christos Exp $
30 .\"
31 .Dd October 27, 2007
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 .It Fl
190 Same as
191 .Fl l .
192 .It Fl m
193 Leave the environment unmodified.
194 The invoked shell is your login shell, and no directory changes are made.
195 As a security precaution, if the target user's shell is a non-standard
196 shell (as defined by
197 .Xr getusershell 3 )
198 and the caller's real uid is
199 non-zero,
200 .Nm
201 will fail.
202 .El
203 .Pp
204 The
205 .Fl l
206 and
207 .Fl m
208 options are mutually exclusive; the last one specified
209 overrides any previous ones.
210 .Pp
211 Only users in group
212 .Dq wheel
213 (normally gid 0),
214 as listed in
215 .Pa /etc/group ,
216 can
217 .Nm
218 to
219 .Dq root ,
220 unless group wheel does not exist or has no members.
221 (If you do not want anybody to be able to
222 .Nm
223 to
224 .Dq root ,
225 make
226 .Dq root
227 the only member of group
228 .Dq wheel ,
229 which is the default.)
230 .Pp
231 For sites with very large user populations, group
232 .Dq wheel
233 can contain the names of other groups that will be considered authorized
234 to
235 .Nm
236 to
237 .Dq root .
238 .Pp
239 By default (unless the prompt is reset by a startup file) the super-user
240 prompt is set to
241 .Dq Sy \&#
242 to remind one of its awesome power.
243 .Sh CUSTOMIZATION
244 .Bl -tag -width ""
245 .It Changing required group
246 For the
247 .Xr pam 8
248 version of
249 .Nm
250 the name of the required group can be changed by setting
251 .Ar gname
252 in
253 .Xr pam.conf 5 :
254 .Bd -literal
255 auth requisite pam_group.so no_warn group=gname root_only fail_safe
256 .Ed
257 .Pp
258 For the non
259 .Xr pam 8
260 version of
261 .Nm
262 the same can be achieved by compiling with
263 .Dv SU_GROUP
264 set to the desired group name.
265 .It Supplying own password
266 .Nm
267 can be configured so that users in a particular group can supply their
268 own password to become
269 .Dq root .
270 For the
271 .Xr pam 8
272 version of
273 .Nm
274 this can be done by adding a line to
275 .Xr pam.conf 5
276 such as:
277 .Bd -literal
278 auth sufficient pam_group.so no_warn group=gname root_only authenticate
279 .Ed
280 .Pp
281 where
282 .Ar gname
283 is the name of the desired group.
284 For the non
285 .Xr pam 8
286 version of
287 .Nm
288 the same can be achieved by compiling with
289 .Dv SU_ROOTAUTH
290 set to the desired group name.
291 .It Indirect groups
292 This option is not available with the
293 .Xr pam 8
294 version of
295 .Nm .
296 For the non
297 .Xr pam 8
298 version of
299 .Nm ,
300 if
301 .Dv SU_INDIRECT_GROUP
302 is defined, the
303 .Ar SU_GROUP
304 and
305 .Ar SU_ROOTAUTH
306 groups are treated as indirect groups.
307 The group members of those two groups are treated as groups themselves.
308 .El
309 .Sh EXIT STATUS
310 .Nm
311 returns the exit status of the executed subshell, or 1 if any error
312 occurred while switching privileges.
313 .Sh ENVIRONMENT
314 Environment variables used by
315 .Nm :
316 .Bl -tag -width "HOME"
317 .It Ev HOME
318 Default home directory of real user ID unless modified as
319 specified above.
320 .It Ev LOGNAME
321 The user ID is always the effective ID (the target user ID) after an
322 .Nm
323 unless the user ID is 0 (root).
324 .It Ev PATH
325 Default search path of real user ID unless modified as specified above.
326 .It Ev TERM
327 Provides terminal type which may be retained for the substituted
328 user ID.
329 .It Ev USER
330 The user ID is always the effective ID (the target user ID) after an
331 .Nm
332 unless the user ID is 0 (root).
333 .El
334 .Sh EXAMPLES
335 To become user username and use the same environment as in original shell, execute:
336 .Bd -literal -offset indent
337 su username
338 .Ed
339 .Pp
340 To become user username and use environment as if full login would be performed,
341 execute:
342 .Bd -literal -offset indent
343 su -l username
344 .Ed
345 .Pp
346 When a
347 .Fl c
348 option is included
349 .Em after
350 the
351 .Ar login
352 name it is not a
353 .Nm
354 option, because any arguments after the
355 .Ar login
356 are passed to the shell.
357 (See
358 .Xr csh 1 ,
359 .Xr ksh 1
360 or
361 .Xr sh 1
362 for details.)
363 To execute arbitrary command with privileges of user
364 .Em username ,
365 execute:
366 .Bd -literal -offset indent
367 su username -c "command args"
368 .Ed
369 .Sh SEE ALSO
370 .Xr csh 1 ,
371 .Xr kinit 1 ,
372 .Xr login 1 ,
373 .Xr sh 1 ,
374 .Xr skey 1 ,
375 .Xr setusercontext 3 ,
376 .Xr group 5 ,
377 .Xr login.conf 5 ,
378 .Xr passwd 5 ,
379 .Xr environ 7 ,
380 .Xr kerberos 8
381 .Sh HISTORY
382 A
383 .Nm
384 command existed in
385 .At v5
386 (and probably earlier).