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

FreeBSD Manual Pages


home | help
su(1M)			System Administration Commands			su(1M)

       su - become super user or another user

       su [-] [	username  [ arg...]]

       The su command allows one to become another user	without	logging	off or
       to assume a role. The default user name is root (super user).

       To use su, the appropriate password must	be supplied  (unless  the  in-
       voker  is  already  root). If the password is correct, su creates a new
       shell process that has the real and effective user ID, group  IDs,  and
       supplementary  group list set to	those of the specified username. Addi-
       tionally, the new shell's project ID is set to the default  project  ID
       of   the	  specified   user.   See   getdefaultproj(3PROJECT),  setpro-
       ject(3PROJECT). The new shell will be the shell specified in the	 shell
       field of	username's password file entry (see passwd(4)).	If no shell is
       specified, /usr/bin/sh is used (see sh(1)). If superuser	 privilege  is
       requested  and  the  shell  for	the  superuser cannot be invoked using
       exec(2),	/sbin/sh is used as a fallback.	To return to  normal  user  ID
       privileges, type	an EOF character (<CTRL-D>) to exit the	new shell.

       Any  additional	arguments  given on the	command	line are passed	to the
       new shell. When using programs such as sh, an arg of the	form -c	string
       executes	 string	 using the shell and an	arg of -r gives	the user a re-
       stricted	shell.

       The following statements	are true if the	login shell is /usr/bin/sh  or
       an  empty string	(which defaults	to /usr/bin/sh)	in the specific	user's
       password	file entry. If the first argument to su	is a dash (-), the en-
       vironment  will	be changed to what would be expected if	the user actu-
       ally logged in as the specified user.  Otherwise,  the  environment  is
       passed along, with the exception	of $PATH,  which is controlled by PATH
       and SUPATH in /etc/default/su.

       All attempts to become another user using su are	logged in the log file
       /var/adm/sulog (see sulog(4)).

       su  uses	 pam(3PAM) for authentication, account management, and session

       The PAM configuration policy, listed through  /etc/pam.conf,  specifies
       the  modules  to	 be used for su. The following example shows a partial
       pam.conf	file with entries for the su command using the authentication,
       account management, and session management module.

       su   auth	requisite
       su   auth	required
       su   auth	required

       su   account	required
       su   account	required
       su   account	required

       su   session	required

       If  there  are  no entries for the su service, then the entries for the
       other service will be used.  If	multiple  authentication  modules  are
       listed, then the	user may be prompted for multiple passwords.

       Example	1:  Becoming User bin While Retaining Your Previously Exported

       To become user bin while	retaining your	previously  exported  environ-
       ment, execute:

       example%	su bin

       Example 2: Becoming User	bin and	Changing to bin's Login	Environment

       To become user bin but change the environment to	what would be expected
       if bin had originally logged in,	execute:

       example%	su - bin

       Example 3: Executing command with user bin's  Environment  and  Permis-

       To  execute  command  with the temporary	environment and	permissions of
       user bin, type:

       example%	su - bin -c "command args"

       Variables with LD_ prefix are removed for security  reasons.  Thus,  su
       bin will	not retain previously exported variables with LD_ prefix while
       becoming	user bin.

       If any of the LC_* variables ( LC_CTYPE,	LC_MESSAGES, LC_TIME,  LC_COL-
       LATE,  LC_NUMERIC, and LC_MONETARY) (see	environ(5)) are	not set	in the
       environment, the	operational behavior of	su for each corresponding  lo-
       cale  category is determined by the value of the	LANG environment vari-
       able. If	LC_ALL is set, its contents are	used to	override both the LANG
       and the other LC_* variables. If	none of	the above variables are	set in
       the environment,	the "C"	(U.S. style) locale determines how su behaves.

	     Determines	how su handles characters. When	LC_CTYPE is set	 to  a
	     valid  value,  su	can display and	handle text and	filenames con-
	     taining valid characters for that locale. su can display and han-
	     dle  Extended  Unix  Code	(EUC)  characters where	any individual
	     character can be 1, 2, or 3 bytes wide. su	can  also  handle  EUC
	     characters	 of  1,	 2,  or	more column widths. In the "C" locale,
	     only characters from ISO 8859-1 are valid.

	     Determines	how diagnostic and informative messages	are presented.
	     This  includes  the  language  and	style of the messages, and the
	     correct form of affirmative and negative responses.  In  the  "C"
	     locale,  the  messages are	presented in the default form found in
	     the program itself	(in most cases,	U.S. English).

	     user's login commands for sh and ksh

	     system's password file

	     system-wide sh and	ksh login commands

	     log file

	     the default parameters in this file are:

	     SULOG If defined, all attempts to su to another user  are	logged
		   in the indicated file.

		   If  defined,	 all  attempts to su to	root are logged	on the

	     PATH  Default path. (/usr/bin:)

		   Default  path   for	 a   user   invoking   su   to	 root.

		   Determines  whether the syslog(3C) LOG_AUTH facility	should
		   be used to log all su  attempts.  LOG_NOTICE	 messages  are
		   generated for su's to root, LOG_INFO	messages are generated
		   for su's to other users, and	LOG_CRIT messages  are	gener-
		   ated	for failed su attempts.

		   If present, sets the	number of seconds to wait before login
		   failure is printed to the screen and	another	login  attempt
		   is  allowed.	 Default  is  4	seconds. Minimum is 0 seconds.
		   Maximum is 5	seconds.

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Availability		     |SUNWcsu			   |

       csh(1),	env(1),	 ksh(1),  login(1),  roles(1),	 sh(1),	  syslogd(1M),
       exec(2),	  getdefaultproj(3PROJECT),  setproject(3PROJECT),  pam(3PAM),
       syslog(3C),   pam.conf(4),   passwd(4),	 profile(4),   sulog(4),   at-
       tributes(5),   environ(5),   pam_authtok_check(5),  pam_authtok_get(5),
       pam_authtok_store(5), pam_dhkeys(5),  pam_passwd_auth(5),  pam_unix(5),
       pam_unix_account(5), pam_unix_auth(5), pam_unix_session(5)

       The pam_unix(5) module might not	be supported in	a future release. Sim-
       ilar  functionality  is	provided  by  pam_authtok_check(5),  pam_auth-
       tok_get(5),  pam_authtok_store(5),  pam_dhkeys(5),  pam_passwd_auth(5),
       pam_unix_account(5), pam_unix_auth(5), and pam_unix_session(5).

SunOS 5.9			  24 Jan 2002				su(1M)


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

home | help