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: src/usr.bin/su/su.1,v 1.40 2007/07/24 06:41:07 delphij Exp $
  34 .\"
  35 .Dd September 13, 2006
  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 flm
  45 .Op Ar login Op Ar args
  46 .Sh DESCRIPTION
  47 The
  48 .Nm
  49 utility requests appropriate user credentials via PAM
  50 and switches to that user ID
  51 (the default user is the superuser).
  52 A shell is then executed.
  53 .Pp
  54 PAM is used to set the policy
  55 .Xr su 1
  56 will use.
  57 In particular, by default only users in the
  58 .Dq Li admin
  59 or
  60 .Dq Li wheel
  61 groups can switch to UID 0
  62 .Pq Dq Li root .
  63 This group requirement may be changed by modifying the
  64 .Dq Li pam_group
  65 section of
  66 .Pa /etc/pam.d/su .
  67 See
  68 .Xr pam_group 8
  69 for details on how to modify this setting.
  70 .Pp
  71 By default, the environment is unmodified with the exception of
  72 .Ev USER ,
  73 .Ev HOME ,
  74 and
  75 .Ev SHELL .
  76 .Ev HOME
  77 and
  78 .Ev SHELL
  79 are set to the target login's default values.
  80 .Ev USER
  81 is set to the target login, unless the target login has a user ID of 0,
  82 in which case it is unmodified.
  83 The invoked shell is the one belonging to the target login.
  84 This is the traditional behavior of
  85 .Nm .
  86 .Pp
  87 The options are as follows:
  88 .Bl -tag -width Ds
  89 .It Fl f
  90 If the invoked shell is
  91 .Xr csh 1 ,
  92 this option prevents it from reading the
  93 .Dq Pa .cshrc
  94 file.
  95 .It Fl l
  96 Simulate a full login.
  97 The environment is discarded except for
  98 .Ev HOME ,
  99 .Ev SHELL ,
 100 .Ev PATH ,
 101 .Ev TERM ,
 102 and
 103 .Ev USER .
 104 .Ev HOME
 105 and
 106 .Ev SHELL
 107 are modified as above.
 108 .Ev USER
 109 is set to the target login.
 110 .Ev PATH
 111 is set to
 112 .Dq Pa /bin:/usr/bin .
 113 .Ev TERM
 114 is imported from your current environment.
 115 The invoked shell is the target login's, and
 116 .Nm
 117 will change directory to the target login's home directory.
 118 .It Fl
 119 (no letter) The same as
 120 .Fl l .
 121 .It Fl m
 122 Leave the environment unmodified.
 123 The invoked shell is your login shell, and no directory changes are made.
 124 As a security precaution, if the target user's shell is a non-standard
 125 shell (as defined by
 126 .Xr getusershell 3 )
 127 and the caller's real uid is
 128 non-zero,
 129 .Nm
 130 will fail.
 131 .El
 132 .Pp
 133 The
 134 .Fl l
 135 (or
 136 .Fl )
 137 and
 138 .Fl m
 139 options are mutually exclusive; the last one specified
 140 overrides any previous ones.
 141 .Pp
 142 If the optional
 143 .Ar args
 144 are provided on the command line, they are passed to the login shell of
 145 the target login.
 146 Note that all command line arguments before the target login name are
 147 processed by
 148 .Nm
 149 itself, everything after the target login name gets passed to the login
 150 shell.
 151 .Pp
 152 By default (unless the prompt is reset by a startup file) the super-user
 153 prompt is set to
 154 .Dq Sy \&#
 155 to remind one of its awesome power.
 156 .Sh ENVIRONMENT
 157 Environment variables used by
 158 .Nm :
 159 .Bl -tag -width HOME
 160 .It Ev HOME
 161 Default home directory of real user ID unless modified as
 162 specified above.
 163 .It Ev PATH
 164 Default search path of real user ID unless modified as specified above.
 165 .It Ev TERM
 166 Provides terminal type which may be retained for the substituted
 167 user ID.
 168 .It Ev USER
 169 The user ID is always the effective ID (the target user ID) after an
 170 .Nm
 171 unless the user ID is 0 (root).
 172 .El
 173 .Sh FILES
 174 .Bl -tag -width ".Pa /etc/pam.d/su" -compact
 175 .It Pa /etc/pam.d/su
 176 PAM configuration for
 177 .Nm .
 178 .El
 179 .Sh EXAMPLES
 180 .Bl -tag -width 5n -compact
 181 .It Li "su man -c catman"
 182 Runs the command
 183 .Li catman
 184 as user
 185 .Li man .
 186 You will be asked for man's password unless your real UID is 0.
 187 .It Li "su man -c 'catman /usr/share/man /usr/local/man'"
 188 Same as above, but the target command consists of more than a
 189 single word and hence is quoted for use with the
 190 .Fl c
 191 option being passed to the shell.
 192 (Most shells expect the argument to
 193 .Fl c
 194 to be a single word).
 195 .It Li "su -l foo"
 196 Simulate a login for user foo.
 197 .It Li "su - foo"
 198 Same as above.
 199 .It Li "su -"
 200 Simulate a login for root.
 201 .El
 202 .Sh SEE ALSO
 203 .Xr csh 1 ,
 204 .Xr sh 1 ,
 205 .Xr group 5 ,
 206 .Xr passwd 5 ,
 207 .Xr environ 7 ,
 208 .Xr pam_group 8
 209 .Sh HISTORY
 210 A
 211 .Nm
 212 command appeared in
 213 .At v1 .