shadow/man/suauth.5.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
		"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<refentry id='suauth.5'>
  <!-- $Id: suauth.5.xml,v 1.5 2005/04/27 16:44:12 kloczek Exp $ -->
  <refmeta>
    <refentrytitle>suauth</refentrytitle>
    <manvolnum>5</manvolnum>
    <refmiscinfo class='source'>Feb 14, 1996</refmiscinfo>
  </refmeta>
  <refnamediv id='name'>
    <refname>suauth</refname>
    <refpurpose>Detailed su control file</refpurpose>
  </refnamediv>
  <!-- body begins here -->
  <refsynopsisdiv id='synopsis'>
    <cmdsynopsis>
      <command>/etc/suauth</command>    
    </cmdsynopsis>
  </refsynopsisdiv>
  
  <refsect1 id='description'>
    <title>DESCRIPTION</title>
    <para>The file <filename>/etc/suauth</filename>      is referenced
      whenever the su command is called. It can change the behaviour of the
      su command, based upon
    </para>
    
    <!-- .RS -->
    <literallayout remap='.nf'>
      1) the user su is targetting
    </literallayout>
    <!-- .fi -->
    <para>2) the user executing the su command (or any groups he might be
      a member of)
    </para>
    <!-- .RE -->
    
    <para>The file is formatted like this, with lines starting with a #
      being treated as comment lines and ignored;
    </para>
    
    <!-- .RS -->
    <literallayout remap='RS'>
      to-id:from-id:ACTION
    </literallayout>
    <!-- remap='RE' -->
    
    <para>Where to-id is either the word
      <emphasis remap='B'>ALL</emphasis>,
      a list of usernames
      delimited by "," or the words
      <emphasis remap='B'>ALL EXCEPT</emphasis>
      followed by a list
      of usernames delimited by ","
    </para>
    
    <para>from-id is formatted the same as to-id except the extra word
      <emphasis remap='B'>GROUP</emphasis>
      is recognised.
      <emphasis remap='B'>ALL EXCEPT GROUP</emphasis>
      is perfectly valid too.
      Following
      <emphasis remap='B'>GROUP</emphasis>
      appears one or more group names, delimited by
      ",". It is not sufficient to have primary group id of the
      relevant group, an entry in
      <citerefentry>
        <refentrytitle>/etc/group</refentrytitle><manvolnum>5</manvolnum>
      </citerefentry>
      is neccessary.
    </para>
    
    <para>Action can be one only of the following currently supported
      options.
    </para>
    <variablelist remap='TP'>
      <varlistentry>
        <term>
          <emphasis remap='B'>DENY</emphasis>
        </term>
        <listitem>
          <para>The attempt to su is stopped before a password is
            even asked for.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <emphasis remap='B'>NOPASS</emphasis>
        </term>
        <listitem>
          <para>The attempt to su is automatically successful; no
            password is
            asked for.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <emphasis remap='B'>OWNPASS</emphasis>
        </term>
        <listitem>
          <para>For the su command to be successful, the user must
            enter
            his or her own password. They are told this.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
    
    <para>Note there are three separate fields delimited by a colon. No
      whitespace must surround this colon. Also note that the file
      is examined sequentially line by line, and the first applicable
      rule is used without examining the file further. This makes it
      possible for a system administrator to exercise as fine control
      as he or she wishes.
    </para>
  </refsect1>
  
  <refsect1 id='example'>
    <title>EXAMPLE</title>
    <literallayout remap='.nf'>
      # sample /etc/suauth file
      #
      # A couple of privileged usernames may
      # su to root with their own password.
      #
      root:chris,birddog:OWNPASS
      # 
      # Anyone else may not su to root unless in
      # group wheel. This is how BSD does things.
      #
      root:ALL EXCEPT GROUP wheel:DENY
      #
      # Perhaps terry and birddog are accounts
      # owned by the same person.
      # Access can be arranged between them
      # with no password.
      #
      terry:birddog:NOPASS
      birddog:terry:NOPASS
      #
    </literallayout>
    <!-- .fi -->
  </refsect1>
  
  <refsect1 id='files'>
    <title>FILES</title>
    <variablelist>
      <varlistentry>
        <term><filename>/etc/suauth</filename></term>
        <listitem></listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  
  <refsect1 id='bugs'>
    <title>BUGS</title>
    <para>There could be plenty lurking. The file parser is particularly
      unforgiving about syntax errors, expecting no spurious whitespace
      (apart from beginning and end of lines), and a specific token
      delimiting different things.
    </para>
  </refsect1>
  
  <refsect1 id='diagnostics'>
    <title>DIAGNOSTICS</title>
    <para>An error parsing the file is reported using
      <citerefentry>
        <refentrytitle>syslogd</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>
      as level ERR on
      facility AUTH.
    </para>
  </refsect1>
  
  <refsect1 id='see_also'>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>su</refentrytitle><manvolnum>1</manvolnum>
      </citerefentry>
    </para>
  </refsect1>
  
  <refsect1 id='author'>
    <title>AUTHOR</title>
    <literallayout remap='.nf'>
      Chris Evans (lady0110@sable.ox.ac.uk)
      Lady Margaret Hall
      Oxford University
      England
    </literallayout>
  </refsect1>
</refentry>