Provided by: util-linux_2.36.1-8ubuntu1_amd64 bug


       su - run a command with substitute user and group ID


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


       su allows commands to be run 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  session  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(3))  to do the final environment
       modification.  Command-line options such as --login and --preserve-environment affect  the
       environment before it is modified by PAM.


       -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  supplementary  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 not specified.

       -, -l, --login
              Start the shell as a login shell with an environment similar to a real login:

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

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

                 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., do not set HOME, SHELL, USER or LOGNAME.
              This option is ignored if the option --login is specified.

       -P, --pty
              Create a pseudo-terminal for the session. The independent terminal provides  better
              security as the user does not share a terminal with the original session.  This can
              be used to avoid TIOCSTI  ioctl  terminal  injection  and  other  security  attacks
              against  terminal  file  descriptors.   The entire session can also be moved to the
              background (e.g., "su --pty - username -c application &").  If the  pseudo-terminal
              is enabled, then su works as a proxy between the sessions (copy stdin and stdout).

              This feature is mostly designed for interactive sessions.  If the standard input is
              not a terminal, but for example a pipe (e.g., echo "date" |  su  --pty),  then  the
              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 target 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 environment variables are ignored unless  the  calling
              user is root.

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

       -w, --whitelist-environment=list
              Don't  reset  the  environment variables specified in the comma-separated list when
              clearing the 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.


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


       su  reads  the  /etc/default/su  and  /etc/login.defs  configuration files.  The following
       configuration items are relevant for su:

       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

       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

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


       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 command

                 126    The requested command could not be executed

                 127    The requested command was not found


       /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


       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 can be used to control su behavior by
       PAM  configuration.  If you want to use the pam_lastlog(8) module to print warning message
       about failed log-in attempts then pam_lastlog(8)  has  to  be  configured  to  update  the
       lastlog file as well. For example by:

              session  required nowtmp


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


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


       The su command is part of the util-linux  package  and  is  available  from  Linux  Kernel
       Archive ⟨⟩.