usr.bin/su/su.1

   1 .\" Copyright (c) 1988, 1990, 1993, 1994
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)su.1        8.2 (Berkeley) 4/18/94
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd July 1, 2008
  36 .Dt SU 1
  37 .Os
  38 .Sh NAME
  39 .Nm su
  40 .Nd substitute user identity
  41 .Sh SYNOPSIS
  42 .Nm
  43 .Op Fl
  44 .Op Fl flms
  45 .Op Fl c Ar class
  46 .Op Ar login Op Ar args
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 utility requests appropriate user credentials via PAM
  51 and switches to that user ID
  52 (the default user is the superuser).
  53 A shell is then executed.
  54 .Pp
  55 PAM is used to set the policy
  56 .Xr su 1
  57 will use.
  58 In particular, by default only users in the
  59 .Dq Li wheel
  60 group can switch to UID 0
  61 .Pq Dq Li root .
  62 This group requirement may be changed by modifying the
  63 .Dq Li pam_group
  64 section of
  65 .Pa /etc/pam.d/su .
  66 See
  67 .Xr pam_group 8
  68 for details on how to modify this setting.
  69 .Pp
  70 By default, the environment is unmodified with the exception of
  71 .Ev USER ,
  72 .Ev HOME ,
  73 and
  74 .Ev SHELL .
  75 .Ev HOME
  76 and
  77 .Ev SHELL
  78 are set to the target login's default values.
  79 .Ev USER
  80 is set to the target login, unless the target login has a user ID of 0,
  81 in which case it is unmodified.
  82 The invoked shell is the one belonging to the target login.
  83 This is the traditional behavior of
  84 .Nm .
  85 Resource limits and session priority applicable to the original user's
  86 login class (see
  87 .Xr login.conf 5 )
  88 are also normally retained unless the target login has a user ID of 0.
  89 .Pp
  90 The options are as follows:
  91 .Bl -tag -width Ds
  92 .It Fl f
  93 If the invoked shell is
  94 .Xr csh 1 ,
  95 this option prevents it from reading the
  96 .Dq Pa .cshrc
  97 file.
  98 .It Fl l
  99 Simulate a full login.
 100 The environment is discarded except for
 101 .Ev HOME ,
 102 .Ev SHELL ,
 103 .Ev PATH ,
 104 .Ev TERM ,
 105 and
 106 .Ev USER .
 107 .Ev HOME
 108 and
 109 .Ev SHELL
 110 are modified as above.
 111 .Ev USER
 112 is set to the target login.
 113 .Ev PATH
 114 is set to
 115 .Dq Pa /bin:/usr/bin .
 116 .Ev TERM
 117 is imported from your current environment.
 118 Environment variables may be set or overridden from the login class
 119 capabilities database according to the class of the target login.
 120 The invoked shell is the target login's, and
 121 .Nm
 122 will change directory to the target login's home directory.
 123 Resource limits and session priority are modified to that for the
 124 target account's login class.
 125 .It Fl
 126 (no letter) The same as
 127 .Fl l .
 128 .It Fl m
 129 Leave the environment unmodified.
 130 The invoked shell is your login shell, and no directory changes are made.
 131 As a security precaution, if the target user's shell is a non-standard
 132 shell (as defined by
 133 .Xr getusershell 3 )
 134 and the caller's real uid is
 135 non-zero,
 136 .Nm
 137 will fail.
 138 .It Fl s
 139 Set the MAC label to the user's default label as part of the user
 140 credential setup.
 141 Setting the MAC label may fail if the MAC label of the invoking process
 142 is not sufficient to transition to the user's default MAC label.
 143 If the label cannot be set,
 144 .Nm
 145 will fail.
 146 .It Fl c Ar class
 147 Use the settings of the specified login class.
 148 Only allowed for the super-user.
 149 .El
 150 .Pp
 151 The
 152 .Fl l
 153 (or
 154 .Fl )
 155 and
 156 .Fl m
 157 options are mutually exclusive; the last one specified
 158 overrides any previous ones.
 159 .Pp
 160 If the optional
 161 .Ar args
 162 are provided on the command line, they are passed to the login shell of
 163 the target login.
 164 Note that all command line arguments before the target login name are
 165 processed by
 166 .Nm
 167 itself, everything after the target login name gets passed to the login
 168 shell.
 169 .Pp
 170 By default (unless the prompt is reset by a startup file) the super-user
 171 prompt is set to
 172 .Dq Sy \&#
 173 to remind one of its awesome power.
 174 .Sh ENVIRONMENT
 175 Environment variables used by
 176 .Nm :
 177 .Bl -tag -width HOME
 178 .It Ev HOME
 179 Default home directory of real user ID unless modified as
 180 specified above.
 181 .It Ev PATH
 182 Default search path of real user ID unless modified as specified above.
 183 .It Ev TERM
 184 Provides terminal type which may be retained for the substituted
 185 user ID.
 186 .It Ev USER
 187 The user ID is always the effective ID (the target user ID) after an
 188 .Nm
 189 unless the user ID is 0 (root).
 190 .El
 191 .Sh FILES
 192 .Bl -tag -width ".Pa /etc/pam.d/su" -compact
 193 .It Pa /etc/pam.d/su
 194 PAM configuration for
 195 .Nm .
 196 .El
 197 .Sh EXAMPLES
 198 .Bl -tag -width 5n -compact
 199 .It Li "su -m man -c catman"
 200 Runs the command
 201 .Li catman
 202 as user
 203 .Li man .
 204 You will be asked for man's password unless your real UID is 0.
 205 Note that the
 206 .Fl m
 207 option is required since user
 208 .Dq man
 209 does not have a valid shell by default.
 210 .It Li "su -m man -c 'catman /usr/share/man /usr/local/man'"
 211 Same as above, but the target command consists of more than a
 212 single word and hence is quoted for use with the
 213 .Fl c
 214 option being passed to the shell.
 215 (Most shells expect the argument to
 216 .Fl c
 217 to be a single word).
 218 .It Li "su -m -c staff man -c 'catman /usr/share/man /usr/local/man'"
 219 Same as above, but the target command is run with the resource limits of
 220 the login class
 221 .Dq staff .
 222 Note: in this example, the first
 223 .Fl c
 224 option applies to
 225 .Nm
 226 while the second is an argument to the shell being invoked.
 227 .It Li "su -l foo"
 228 Simulate a login for user foo.
 229 .It Li "su - foo"
 230 Same as above.
 231 .It Li "su -"
 232 Simulate a login for root.
 233 .El
 234 .Sh SEE ALSO
 235 .Xr csh 1 ,
 236 .Xr sh 1 ,
 237 .Xr group 5 ,
 238 .Xr login.conf 5 ,
 239 .Xr passwd 5 ,
 240 .Xr environ 7 ,
 241 .Xr pam_group 8
 242 .Sh HISTORY
 243 A
 244 .Nm
 245 command appeared in
 246 .At v1 .