<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY CONSOLE SYSTEM "login.defs.d/CONSOLE.xml"> <!ENTITY CONSOLE_GROUPS SYSTEM "login.defs.d/CONSOLE_GROUPS.xml"> <!ENTITY DEFAULT_HOME SYSTEM "login.defs.d/DEFAULT_HOME.xml"> <!ENTITY ENV_HZ SYSTEM "login.defs.d/ENV_HZ.xml"> <!ENTITY ENVIRON_FILE SYSTEM "login.defs.d/ENVIRON_FILE.xml"> <!ENTITY ENV_PATH SYSTEM "login.defs.d/ENV_PATH.xml"> <!ENTITY ENV_SUPATH SYSTEM "login.defs.d/ENV_SUPATH.xml"> <!ENTITY ENV_TZ SYSTEM "login.defs.d/ENV_TZ.xml"> <!ENTITY LOGIN_STRING SYSTEM "login.defs.d/LOGIN_STRING.xml"> <!ENTITY MAIL_CHECK_ENAB SYSTEM "login.defs.d/MAIL_CHECK_ENAB.xml"> <!ENTITY MAIL_DIR SYSTEM "login.defs.d/MAIL_DIR.xml"> <!ENTITY QUOTAS_ENAB SYSTEM "login.defs.d/QUOTAS_ENAB.xml"> <!ENTITY SULOG_FILE SYSTEM "login.defs.d/SULOG_FILE.xml"> <!ENTITY SU_NAME SYSTEM "login.defs.d/SU_NAME.xml"> <!ENTITY SU_WHEEL_ONLY SYSTEM "login.defs.d/SU_WHEEL_ONLY.xml"> <!ENTITY SYSLOG_SU_ENAB SYSTEM "login.defs.d/SYSLOG_SU_ENAB.xml"> <!ENTITY USERGROUPS_ENAB SYSTEM "login.defs.d/USERGROUPS_ENAB.xml"> ]> <refentry id='su.1'> <!-- $Id$ --> <refmeta> <refentrytitle>su</refentrytitle> <manvolnum>1</manvolnum> <refmiscinfo class="sectdesc">User Commands</refmiscinfo> </refmeta> <refnamediv id='name'> <refname>su</refname> <refpurpose>change user ID or become superuser</refpurpose> </refnamediv> <refsynopsisdiv id='synopsis'> <cmdsynopsis> <command>su</command> <arg choice='opt'> <replaceable>options</replaceable> </arg> <arg choice='opt'> <arg choice='plain'> <replaceable>LOGIN</replaceable> </arg> </arg> </cmdsynopsis> </refsynopsisdiv> <refsect1 id='description'> <title>DESCRIPTION</title> <para> The <command>su</command> command is used to become another user during a login session. Invoked without a <option>username</option>, <command>su</command> defaults to becoming the superuser. The optional argument <option>-</option> may be used to provide an environment similar to what the user would expect had the user logged in directly. </para> <para> Additional arguments may be provided after the username, in which case they are supplied to the user's login shell. In particular, an argument of <option>-c</option> will cause the next argument to be treated as a command by most command interpreters. The command will be executed by the shell specified in <filename>/etc/passwd</filename> for the target user. </para> <para> You can use the <option>--</option> argument to separate <command>su</command> options from the arguments supplied to the shell. </para> <para>The user will be prompted for a password, if appropriate. Invalid passwords will produce an error message. All attempts, both valid and invalid, are logged to detect abuse of the system. </para> <para> The current environment is passed to the new shell. The value of <envar>$PATH</envar> is reset to <filename>/bin:/usr/bin</filename> for normal users, or <filename>/sbin:/bin:/usr/sbin:/usr/bin</filename> for the superuser. This may be changed with the <emphasis>ENV_PATH</emphasis> and <emphasis>ENV_SUPATH</emphasis> definitions in <filename>/etc/login.defs</filename>. </para> <para> A subsystem login is indicated by the presence of a "*" as the first character of the login shell. The given home directory will be used as the root of a new file system which the user is actually logged into. </para> </refsect1> <refsect1 id='options'> <title>OPTIONS</title> <para>The options which apply to the <command>su</command> command are: </para> <variablelist remap='IP'> <varlistentry> <term> <option>-c</option>, <option>--command</option> <replaceable>COMMAND</replaceable> </term> <listitem> <para> Specify a command that will be invoked by the shell using its <option>-c</option>. </para> </listitem> </varlistentry> <varlistentry> <term> <option>-</option>, <option>-l</option>, <option>--login</option> </term> <listitem> <para> Provide an environment similar to what the user would expect had the user logged in directly. </para> <para> When <option>-</option> is used, it must be specified as the last <command>su</command> option. The other forms (<option>-l</option> and <option>--login</option>) do not have this restriction. </para> </listitem> </varlistentry> <varlistentry> <term> <option>-s</option>, <option>--shell</option> <replaceable>SHELL</replaceable> </term> <listitem> <para>The shell that will be invoked.</para> <para> The invoked shell is chosen from (highest priority first): <itemizedlist> <listitem> <para>The shell specified with --shell.</para> </listitem> <listitem> <para> If <option>--preserve-environment</option> is used, the shell specified by the <envar>$SHELL</envar> environment variable. </para> </listitem> <listitem> <para> The shell indicated in the <filename>/etc/passwd</filename> entry for the target user. </para> </listitem> <listitem> <para> <filename>/bin/sh</filename> if a shell could not be found by any above method. </para> </listitem> </itemizedlist> </para> <para> If the target user has a restricted shell (i.e. the shell field of this user's entry in <filename>/etc/passwd</filename> is not listed in <filename>/etc/shell</filename>), then the <option>--shell</option> option or the <envar>$SHELL</envar> environment variable won't be taken into account, unless <command>su</command> is called by root. </para> </listitem> </varlistentry> <varlistentry> <term> <option>-m</option>, <option>-p</option>, <option>--preserve-environment</option> </term> <listitem> <para>Preserve the current environment.</para> <para> If the target user has a restricted shell, this option has no effect (unless <command>su</command> is called by root). </para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1 id='caveats'> <title>CAVEATS</title> <para> This version of <command>su</command> has many compilation options, only some of which may be in use at any particular site. </para> </refsect1> <refsect1 id='configuration'> <title>CONFIGURATION</title> <para> The following configuration variables in <filename>/etc/login.defs</filename> change the behavior of this tool: </para> <variablelist> &CONSOLE; &CONSOLE_GROUPS; &DEFAULT_HOME; <phrase condition="no_pam">&ENV_HZ;</phrase> &ENVIRON_FILE; &ENV_PATH; &ENV_SUPATH; &ENV_TZ; <phrase condition="no_pam">&LOGIN_STRING;</phrase> &MAIL_CHECK_ENAB; <phrase condition="no_pam">&MAIL_DIR;</phrase> "AS_ENAB; &SULOG_FILE; &SU_NAME; &SU_WHEEL_ONLY; &SYSLOG_SU_ENAB; <phrase condition="no_pam">&USERGROUPS_ENAB;</phrase> </variablelist> </refsect1> <refsect1 id='files'> <title>FILES</title> <variablelist> <varlistentry> <term><filename>/etc/passwd</filename></term> <listitem> <para>User account information.</para> </listitem> </varlistentry> <varlistentry> <term><filename>/etc/shadow</filename></term> <listitem> <para>Secure user account information.</para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1 id='see_also'> <title>SEE ALSO</title> <para><citerefentry> <refentrytitle>login</refentrytitle><manvolnum>1</manvolnum> </citerefentry>, <citerefentry> <refentrytitle>login.defs</refentrytitle><manvolnum>5</manvolnum> </citerefentry>, <citerefentry> <refentrytitle>sg</refentrytitle><manvolnum>1</manvolnum> </citerefentry>, <citerefentry> <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum> </citerefentry> </para> </refsect1> </refentry>