Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SU(1)			  BSD General Commands Manual			 SU(1)

     su	-- substitute user identity

     su	[-dfKlm] [-c login-class] [login[:group] [shell	arguments]]
     su	[-dfKlm] [-c login-class] [:group [shell arguments]]

     su	allows one user	to become another user login without logging out and
     in	as the new user.  If a group is	specified and login is a member	of
     group, then the group is changed to group rather than to login's primary
     group.  If	login is omitted and group is provided (form two above), then
     login is assumed to be the	current	username.

     When executed by a	user, the login	user's password	is requested.  When
     using Kerberos, the password for login (or	for "login.root", if no	login
     is	provided) is requested,	and su switches	to that	user and group ID af-
     ter obtaining a Kerberos ticket granting ticket.  A shell is then exe-
     cuted, and	any additional shell arguments after the login name are	passed
     to	the shell.  su will resort to the local	password file to find the
     password for login	if there is a Kerberos error.  If su is	executed by
     root, no password is requested and	a shell	with the appropriate user ID
     is	executed; no additional	Kerberos tickets are obtained.

     Alternatively, if the user	enters the password "s/key", authentication
     will use the S/Key	one-time password system as described in skey(1).
     S/Key is a	Trademark of Bellcore.

     By	default, the environment is unmodified with the	exception of LOGNAME,
     USER, HOME, SHELL,	and SU_FROM.  HOME and SHELL are set to	the target lo-
     gin's default values.  LOGNAME and	USER are set to	the target login, un-
     less the target login has a user ID of 0, in which	case they are unmodi-
     fied.  SU_FROM is set to the caller's login.  The invoked shell is	the
     target login's.  With the exception of SU_FROM this is the	traditional
     behavior of su.

     The options are as	follows:

     -c	     Specify a login class.  You may only override the default class
	     if	you're already root.  See login.conf(5)	for details.

     -d	     Same as -l, but does not change the current directory.

     -f	     If	the invoked shell is csh(1), this option prevents it from
	     reading the ".cshrc" file.	 If the	invoked	shell is sh(1),	or
	     ksh(1), this option unsets	ENV, thus preventing the shell from
	     executing the startup file	pointed	to by this variable.

     -K	     Do	not attempt to use Kerberos to authenticate the	user.

     -l	     Simulate a	full login.  The environment is	discarded except for
	     SHELL, and	SU_FROM	are modified as	above.	LOGNAME	and USER are
	     set to the	target login.  PATH is set to the path specified in
	     the /etc/login.conf file (or to the default of
	     "/usr/bin:/bin:/usr/pkg/bin:/usr/local/bin" ).  TERM is imported
	     from your current environment.  The invoked shell is the target
	     login's, and su will change directory to the target login's home

     -	     Same as -l.

     -m	     Leave the environment unmodified.	The invoked shell is your lo-
	     gin shell,	and no directory changes are made.  As a security pre-
	     caution, if the target user's shell is a non-standard shell (as
	     defined by	getusershell(3)) and the caller's real uid is non-
	     zero, su will fail.

     The -l and	-m options are mutually	exclusive; the last one	specified
     overrides any previous ones.

     Only users	in group "wheel" (normally gid 0), as listed in	/etc/group,
     can su to "root", unless group wheel does not exist or has	no members.
     (If you do	not want anybody to be able to su to "root", make "root" the
     only member of group "wheel", which is the	default.)

     For sites with very large user populations, group "wheel" can contain the
     names of other groups that	will be	considered authorized to su to "root".

     By	default	(unless	the prompt is reset by a startup file) the super-user
     prompt is set to "#" to remind one	of its awesome power.

     Changing required group
       For the pam(8) version of su the	name of	the required group can be
       changed by setting gname	in pam.conf(5):

       auth requisite no_warn group=gname root_only fail_safe

       For the non pam(8) version of su	the same can be	achieved by compiling
       with SU_GROUP set to the	desired	group name.

     Supplying own password
       su can be configured so that users in a particular group	can supply
       their own password to become "root".  For the pam(8) version of su this
       can be done by adding a line to pam.conf(5) such	as:

       auth sufficient no_warn group=gname	root_only authenticate

       where gname is the name of the desired group.  For the non pam(8) ver-
       sion of su the same can be achieved by compiling	with SU_ROOTAUTH set
       to the desired group name.

     Indirect groups
       This option is not available with the pam(8) version of su.  For	the
       non pam(8) version of su, if SU_INDIRECT_GROUP is defined, the SU_GROUP
       and SU_ROOTAUTH groups are treated as indirect groups.  The group mem-
       bers of those two groups	are treated as groups themselves.

     su	returns	the exit status	of the executed	subshell, or 1 if any error
     occurred while switching privileges.

     Environment variables used	by su:

     HOME  Default home	directory of real user ID unless modified as specified

	   The user ID is always the effective ID (the target user ID) after
	   an su unless	the user ID is 0 (root).

     PATH  Default search path of real user ID unless modified as specified

     TERM  Provides terminal type which	may be retained	for the	substituted
	   user	ID.

     USER  The user ID is always the effective ID (the target user ID) after
	   an su unless	the user ID is 0 (root).

     To	become user username and use the same environment as in	original
     shell, execute:

	   su username

     To	become user username and use environment as if full login would	be
     performed,	execute:

	   su -l username

     When a -c option is included after	the login name it is not a su option,
     because any arguments after the login are passed to the shell.  (See
     csh(1), ksh(1) or sh(1) for details.)  To execute arbitrary command with
     privileges	of user	username, execute:

	   su username -c "command args"

     csh(1), kinit(1), login(1), sh(1),	skey(1), setusercontext(3), group(5),
     login.conf(5), passwd(5), environ(7), kerberos(8)

     A su command existed in Version 5 AT&T UNIX (and probably earlier).

BSD			       October 27, 2007				   BSD


Want to link to this manual page? Use this URL:

home | help