Back to Contents
SU(1)                         User Commands                         SU(1)

NAME
       su - run a command with substitute user and group ID

SYNOPSIS
       su [options] [-] [user [argument...]]

DESCRIPTION
       su allows to run commands with a substitute user and group ID.

       When  called  with  no  user  specified, su defaults to running an
       interactive shell as root.  When  user  is  specified,  additional
       arguments  can  be  supplied, in which case they are passed to the
       shell.

       For backward compatibility, su defaults to not change the  current
       directory and to only set the environment variables HOME and SHELL
       (plus USER and LOGNAME if the target user is  not  root).   It  is
       recommended  to  always  use  the  --login  option (instead of its
       shortcut -) to avoid side effects caused by mixing environments.

       This version of su uses PAM for authentication, account  and  ses‐
       sion  management.   Some  configuration  options found in other su
       implementations, such as support for a wheel  group,  have  to  be
       configured via PAM.

       su  is  mostly  designed  for  unprivileged users, the recommended
       solution for privileged users (e.g., scripts executed by root)  is
       to  use  non-set-user-ID  command runuser(1) that does not require
       authentication and provide separate PAM configuration. If the  PAM
       session  is  not required at all then the recommend solution is to
       use command setpriv(1).

       Note that su in all cases use PAM (pam_getenvlist()) to  do  final
       environment  modification.   The command line options like --login
       or --preserve-environment affect environment before it's  modified
       by PAM.

OPTIONS
       -c, --command=command
              Pass command to the shell with the -c option.

       -f, --fast
              Pass  -f  to  the  shell,  which  may or may not be useful,
              depending on the shell.

       -g, --group=group
              Specify the primary group.  This option is available to the
              root user only.

       -G, --supp-group=group
              Specify  a supplemental group.  This option is available to
              the root user  only.   The  first  specified  supplementary
              group is also used as a primary group if the option --group
              is unspecified.

       -, -l, --login
              Start the shell as a login shell with an environment  simi‐
              lar to a real login:

                 o      clears  all the environment variables except TERM
                        and variables specified  by  --whitelist-environ‐
                        ment

                 o      initializes   the   environment  variables  HOME,
                        SHELL, USER, LOGNAME, and PATH

                 o      changes to the target user's home directory

                 o      sets argv[0] of the shell to '-' in order to make
                        the shell a login shell

       -m, -p, --preserve-environment
              Preserve  the  entire  environment,  i.e.,  it does not set
              HOME, SHELL, USER nor LOGNAME.  This option is  ignored  if
              the option --login is specified.

       -P, --pty
              Create  pseudo-terminal  for  the  session. The independent
              terminal provides better security as user  does  not  share
              terminal  with  the  original session.  This allow to avoid
              TIOCSTI  ioctl  terminal  injection  and  another  security
              attacks  against terminal file descriptors. The all session
              is also possible to move to background (e.g., "su  --pty  -
              username  -c  application  &").  If  the pseudo-terminal is
              enabled then su command works as a proxy between  the  ses‐
              sions (copy stdin and stdout).

              This  feature  is mostly designed for interactive sessions.
              If the standard input is not a terminal,  but  for  example
              pipe  (e.g., echo "date" | su --pty) than ECHO flag for the
              pseudo-terminal is disabled to avoid messy output.

       -s, --shell=shell
              Run the specified shell instead of the default.  The  shell
              to  run  is  selected  according to the following rules, in
              order:

                 o      the shell specified with --shell

                 o      the shell specified in the  environment  variable
                        SHELL,  if  the  --preserve-environment option is
                        used

                 o      the shell listed in the passwd entry of the  tar‐
                        get user

                 o      /bin/sh

              If the target user has a restricted shell (i.e., not listed
              in /etc/shells), the --shell option and the SHELL  environ‐
              ment variables are ignored unless the calling user is root.

       --session-command=command
              Same as -c but do not create a new session.  (Discouraged.)

       -w, --whitelist-environment=list
              Don't  reset environment variables specified in comma sepa‐
              rated  list  when  clears  environment  for  --login.   The
              whitelist  is  ignored  for the environment variables HOME,
              SHELL, USER, LOGNAME, and PATH.

       -V, --version
              Display version information and exit.

       -h, --help
              Display help text and exit.

SIGNALS
       Upon receiving either SIGINT, SIGQUIT or  SIGTERM,  su  terminates
       its  child and afterwards terminates itself with the received sig‐
       nal.  The child  is  terminated  by  SIGTERM,  after  unsuccessful
       attempt and 2 seconds of delay the child is killed by SIGKILL.

CONFIG FILES
       su  reads  the  /etc/default/su  and /etc/login.defs configuration
       files.  The following configuration items are relevant for su(1):

       FAIL_DELAY (number)
           Delay in seconds in case of  an  authentication  failure.  The
           number must be a non-negative integer.

       ENV_PATH (string)
           Defines the PATH environment variable for a regular user.  The
           default value is /usr/local/bin:/bin:/usr/bin.

       ENV_ROOTPATH (string)
       ENV_SUPATH (string)
           Defines the PATH environment variable  for  root.   ENV_SUPATH
           takes  precedence.   The  default  value  is  /usr/local/sbin:
           /usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin.

       ALWAYS_SET_PATH (boolean)
           If set to yes and --login and --preserve-environment were  not
           specified su initializes PATH.

       The  environment  variable  PATH may be different on systems where
       /bin and /sbin  are  merged  into  /usr,  this  variable  is  also
       affected  by  --login  command  line option and PAM system setting
       (e.g. pam_env).

EXIT STATUS
       su normally returns the exit status of the  command  it  executed.
       If  the  command  was killed by a signal, su returns the number of
       the signal plus 128.

       Exit status generated by su itself:

                 1      Generic error before executing the requested com‐
                        mand

                 126    The requested command could not be executed

                 127    The requested command was not found

FILES
       /etc/pam.d/su    default PAM configuration file
       /etc/pam.d/su-l  PAM configuration file if --login is specified
       /etc/default/su  command specific logindef config file
       /etc/login.defs  global logindef config file

NOTES
       For  security reasons su always logs failed log-in attempts to the
       btmp file, but it does not write to the lastlog file at all.  This
       solution  allows  to control su behavior by PAM configuration.  If
       you want to use the pam_lastlog module to  print  warning  message
       about  failed  log-in attempts then the pam_lastlog has to be con‐
       figured to update the lastlog file as well. For example by:

              session  required  pam_lastlog.so nowtmp

SEE ALSO
       setpriv(1), login.defs(5), shells(5), pam(8), runuser(1)

HISTORY
       This su command was derived from coreutils' su, which was based on
       an  implementation  by  David  MacKenzie.  The util-linux has been
       refactored by Karel Zak.

AVAILABILITY
       The su command is part of the util-linux package and is  available
       from  Linux Kernel Archive ⟨https://www.kernel.org/pub/linux/utils
       /util-linux/⟩.

util-linux                      July 2014                           SU(1)