1 <?xml version="1.0" encoding="UTF-8"?>
3 Copyright (c) 1989 - 1990, Julianne Frances Haugh
4 Copyright (c) 2007 - 2008, Nicolas François
7 Redistribution and use in source and binary forms, with or without
8 modification, are permitted provided that the following conditions
10 1. Redistributions of source code must retain the above copyright
11 notice, this list of conditions and the following disclaimer.
12 2. Redistributions in binary form must reproduce the above copyright
13 notice, this list of conditions and the following disclaimer in the
14 documentation and/or other materials provided with the distribution.
15 3. The name of the copyright holders or contributors may not be used to
16 endorse or promote products derived from this software without
17 specific prior written permission.
19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
22 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23 HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
32 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
33 <!ENTITY CONSOLE SYSTEM "login.defs.d/CONSOLE.xml">
34 <!ENTITY CONSOLE_GROUPS SYSTEM "login.defs.d/CONSOLE_GROUPS.xml">
35 <!ENTITY DEFAULT_HOME SYSTEM "login.defs.d/DEFAULT_HOME.xml">
36 <!ENTITY ENV_HZ SYSTEM "login.defs.d/ENV_HZ.xml">
37 <!ENTITY ENVIRON_FILE SYSTEM "login.defs.d/ENVIRON_FILE.xml">
38 <!ENTITY ENV_PATH SYSTEM "login.defs.d/ENV_PATH.xml">
39 <!ENTITY ENV_SUPATH SYSTEM "login.defs.d/ENV_SUPATH.xml">
40 <!ENTITY ENV_TZ SYSTEM "login.defs.d/ENV_TZ.xml">
41 <!ENTITY LOGIN_STRING SYSTEM "login.defs.d/LOGIN_STRING.xml">
42 <!ENTITY MAIL_CHECK_ENAB SYSTEM "login.defs.d/MAIL_CHECK_ENAB.xml">
43 <!ENTITY MAIL_DIR SYSTEM "login.defs.d/MAIL_DIR.xml">
44 <!ENTITY QUOTAS_ENAB SYSTEM "login.defs.d/QUOTAS_ENAB.xml">
45 <!ENTITY SULOG_FILE SYSTEM "login.defs.d/SULOG_FILE.xml">
46 <!ENTITY SU_NAME SYSTEM "login.defs.d/SU_NAME.xml">
47 <!ENTITY SU_WHEEL_ONLY SYSTEM "login.defs.d/SU_WHEEL_ONLY.xml">
48 <!ENTITY SYSLOG_SU_ENAB SYSTEM "login.defs.d/SYSLOG_SU_ENAB.xml">
49 <!ENTITY USERGROUPS_ENAB SYSTEM "login.defs.d/USERGROUPS_ENAB.xml">
54 <refentrytitle>su</refentrytitle>
55 <manvolnum>1</manvolnum>
56 <refmiscinfo class="sectdesc">User Commands</refmiscinfo>
58 <refnamediv id='name'>
60 <refpurpose>change user ID or become superuser</refpurpose>
62 <refsynopsisdiv id='synopsis'>
66 <replaceable>options</replaceable>
70 <replaceable>username</replaceable>
76 <refsect1 id='description'>
77 <title>DESCRIPTION</title>
79 The <command>su</command> command is used to become another user during
80 a login session. Invoked without a <option>username</option>,
81 <command>su</command> defaults to
82 becoming the superuser. The optional argument <option>-</option> may
83 be used to provide an environment similar to what the user would
84 expect had the user logged in directly.
88 Additional arguments may be provided after the username, in which case
89 they are supplied to the user's login shell. In particular, an
90 argument of <option>-c</option> will cause the next argument to be
91 treated as a command by most command interpreters. The command will be
92 executed by the shell specified in <filename>/etc/passwd</filename>
97 You can use the <option>--</option> argument to separate
98 <command>su</command> options from the arguments supplied to the shell.
101 <para>The user will be prompted for a password, if appropriate. Invalid
102 passwords will produce an error message. All attempts, both valid and
103 invalid, are logged to detect abuse of the system.
107 The current environment is passed to the new shell. The value of
108 <envar>$PATH</envar> is reset to <filename>/bin:/usr/bin</filename>
109 for normal users, or <filename>/sbin:/bin:/usr/sbin:/usr/bin</filename>
110 for the superuser. This may be changed with the
111 <emphasis>ENV_PATH</emphasis> and <emphasis>ENV_SUPATH</emphasis>
112 definitions in <filename>/etc/login.defs</filename>.
116 A subsystem login is indicated by the presence of a "*" as the first
117 character of the login shell. The given home directory will be used as
118 the root of a new file system which the user is actually logged into.
122 <refsect1 id='options'>
123 <title>OPTIONS</title>
124 <para>The options which apply to the <command>su</command> command are:
126 <variablelist remap='IP'>
129 <option>-c</option>, <option>--command</option>
130 <replaceable>COMMAND</replaceable>
134 Specify a command that will be invoked by the shell using its
141 <option>-</option>, <option>-l</option>, <option>--login</option>
145 Provide an environment similar to what the user would expect had
146 the user logged in directly.
149 When <option>-</option> is used, it must be specified as the last
150 <command>su</command> option.
151 The other forms (<option>-l</option> and <option>--login</option>)
152 do not have this restriction.
158 <option>-s</option>, <option>--shell</option>
159 <replaceable>SHELL</replaceable>
162 <para>The shell that will be invoked.</para>
164 The invoked shell is chosen from (highest priority first):
167 <para>The shell specified with --shell.</para>
171 If <option>--preserve-environment</option> is used, the
172 shell specified by the <envar>$SHELL</envar> environment
178 The shell indicated in the <filename>/etc/passwd</filename>
179 entry for the target user.
184 <filename>/bin/sh</filename> if a shell could not be
185 found by any above method.
191 If the target user has a restricted shell (i.e. the shell field of
192 this user's entry in <filename>/etc/passwd</filename> is not
193 listed in <filename>/etc/shell</filename>), then the
194 <option>--shell</option> option or the <envar>$SHELL</envar>
195 environment variable won't be taken into account, unless
196 <command>su</command> is called by root.
202 <option>-m</option>, <option>-p</option>,
203 <option>--preserve-environment</option>
206 <para>Preserve the current environment.</para>
208 If the target user has a restricted shell, this option has no
209 effect (unless <command>su</command> is called by root).
216 <refsect1 id='caveats'>
217 <title>CAVEATS</title>
219 This version of <command>su</command> has many compilation options,
220 only some of which may be in use at any particular site.
224 <refsect1 id='configuration'>
225 <title>CONFIGURATION</title>
227 The following configuration variables in
228 <filename>/etc/login.defs</filename> change the behavior of this
235 <phrase condition="no_pam">&ENV_HZ;</phrase>
240 <phrase condition="no_pam">&LOGIN_STRING;</phrase>
242 <phrase condition="no_pam">&MAIL_DIR;</phrase>
248 <phrase condition="no_pam">&USERGROUPS_ENAB;</phrase>
252 <refsect1 id='files'>
256 <term><filename>/etc/passwd</filename></term>
258 <para>User account information.</para>
262 <term><filename>/etc/shadow</filename></term>
264 <para>Secure user account information.</para>
270 <refsect1 id='see_also'>
271 <title>SEE ALSO</title>
273 <refentrytitle>login</refentrytitle><manvolnum>1</manvolnum>
276 <refentrytitle>login.defs</refentrytitle><manvolnum>5</manvolnum>
279 <refentrytitle>sg</refentrytitle><manvolnum>1</manvolnum>
282 <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>