shadow/man/su.1.xml

<?xml version="1.0" encoding="UTF-8"?>
<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='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>