su(1) - c7

1SU(1)                            User Commands                           SU(1)
2
3
4

NAME

6       su - run a command with substitute user and group ID
7

SYNOPSIS

9       su [options...] [-] [user [args...]]
10

DESCRIPTION

12       su allows to run commands with substitute user and group ID.
13
14       When  called  without  arguments  su defaults to running an interactive
15       shell as root.
16
17       For backward compatibility su defaults to not change the current direc‐
18       tory  and  to  only  set the environment variables HOME and SHELL (plus
19       USER and LOGNAME if the target user is not root).  It is recommended to
20       always  use  the --login option (instead it's shortcut -) to avoid side
21       effects caused by mixing environments.
22
23       This version of su uses PAM for  authentication,  account  and  session
24       management.   Some  configuration options found in other su implementa‐
25       tions such as e.g. support of a wheel group have to be  configured  via
26       PAM.
27

OPTIONS

29       -c command, --command=command
30              Pass command to the shell with the -c option.
31
32       --session-command=command
33              Same as -c but do not create a new session (discouraged).
34
35       -f, --fast
36              Pass -f to the shell which may or may not be useful depending on
37              the shell.
38
39       -g, --group=group
40              specify the primary group, this option is allowed for root  user
41              only
42
43       -G, --supp-group=group
44              Specify  a  supplemental group.  This option is available to the
45              root user only.  The first specified supplementary group is also
46              used as a primary group if the option --group is unspecified.
47
48       -, -l, --login
49              Starts the shell as login shell with an environment similar to a
50              real login:
51
52                 o      clears all environment variables except for TERM
53
54                 o      initializes the  environment  variables  HOME,  SHELL,
55                        USER, LOGNAME, PATH
56
57                 o      changes to the target user's home directory
58
59                 o      sets  argv[0] of the shell to '-' in order to make the
60                        shell a login shell
61
62       -m, -p, --preserve-environment
63              Preserves the whole environment, ie does not  set  HOME,  SHELL,
64              USER  nor  LOGNAME.  The option is ignored if the option --login
65              is specified.
66
67       -s SHELL, --shell=SHELL
68              Runs the specified shell instead of the default.  The  shell  to
69              run is selected according to the following rules in order:
70
71                 o      the shell specified with --shell
72
73                 o      The  shell specified in the environment variable SHELL
74                        if the --preserve-environment option is used.
75
76                 o      the shell listed in the passwd  entry  of  the  target
77                        user
78
79                 o      /bin/sh
80
81              If  the  target  user has a restricted shell (i.e. not listed in
82              /etc/shells) the --shell option and the SHELL environment  vari‐
83              ables are ignored unless the calling user is root.
84
85       --help Display help text and exit.
86
87       --version
88              Display version information and exit.
89

CONFIG FILES

91       su  reads  the /etc/default/su and /etc/login.defs configuration files.
92       The following configuration items are relevant for su(1):
93
94       FAIL_DELAY (number)
95           Delay in seconds in case of authentication failure.  Number must be
96           a non-negative integer.
97
98       ENV_PATH (string)
99           Defines  the  PATH  environment  variable  for a regular user.  The
100           default value is /usr/local/bin:/bin:/usr/bin.
101
102       ENV_ROOTPATH (string)
103       ENV_SUPATH (string)
104           Defines the PATH environment variable for root. The  default  value
105           is /usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin.
106
107       ALWAYS_SET_PATH (boolean)
108           If set to yes and --login and --preserve-environment were not spec‐
109           ified su initializes PATH.
110

EXIT STATUS

112       su normally returns the exit status of the command it executed.  If the
113       command  was  killed  by  a signal, su returns the number of the signal
114       plus 128.
115
116       Exit status generated by su itself:
117
118                 1      Generic error before executing the requested command
119
120                 126    The requested command could not be executed
121
122                 127    The requested command could was not found
123

FILES

125       /etc/pam.d/su    default PAM configuration file
126       /etc/pam.d/su-l  PAM configuration file if --login is specified
127       /etc/default/su  command specific logindef config file
128       /etc/login.defs  global logindef config file
129

AUTHOR

134       Derived from coreutils' su which was based on  an  implementation  from
135       David MacKenzie.
136

AVAILABILITY

138       The  su command is part of the util-linux package and is available from
139       Linux   Kernel   Archive    ⟨ftp://ftp.kernel.org/pub/linux/utils/util-
140       linux/⟩.
141
142
143
144util-linux                         June 2012                             SU(1)