source: postlfs/security/linux-pam.xml@ 06be400

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY linux-pam-download-http "http://www.kernel.org/pub/linux/libs/pam/pre/library/Linux-PAM-&linux-pam-version;.tar.bz2">
  <!ENTITY linux-pam-download-ftp  "ftp://ftp.kernel.org/pub/linux/libs/pam/pre/library/Linux-PAM-&linux-pam-version;.tar.bz2">
  <!ENTITY linux-pam-md5sum        "267ea71253615342261f9fc486d06647">
  <!ENTITY linux-pam-size          "783 KB">
  <!ENTITY linux-pam-buildsize     "19.8 MB">
  <!ENTITY linux-pam-time          "0.5 SBU">
  <!ENTITY linux-pam-docs-download "http://www.kernel.org/pub/linux/libs/pam/pre/doc/Linux-PAM-&linux-pam-version;-docs.tar.bz2">
]>

<sect1 id="linux-pam" xreflabel="Linux-PAM-&linux-pam-version;">
  <?dbhtml filename="linux-pam.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>Linux-PAM-&linux-pam-version;</title>

  <indexterm zone="linux-pam">
    <primary sortas="a-Linux-PAM">Linux-PAM</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Linux-PAM</title>

    <para>The <application>Linux-PAM</application> package contains
    Pluggable Authentication Modules. This is useful to enable the
    local system administrator to choose how applications authenticate
    users.</para>

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&linux-pam-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&linux-pam-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &linux-pam-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &linux-pam-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &linux-pam-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &linux-pam-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing='compact'>
      <listitem>
        <para>Optional documentation:
        <ulink url="&linux-pam-docs-download;"/></para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Linux-PAM Dependencies</bridgehead>

    <!-- Moved to optional after discussion on BLFS-Dev

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended"><xref linkend="cracklib"/></para>

    -->

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><xref linkend="cracklib"/>,
    <!-- <xref linkend="db"/> (for the pam_userdb module), -->
    <ulink url="http://www.prelude-ids.org/">Prelude</ulink>, and
    <ulink url="http://sourceforge.net/projects/sgmltools-lite/">sgmltools-lite</ulink></para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/linux-pam"/></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Linux-PAM</title>

    <para>If you downloaded the documentation, unpack the tarball into the
    <filename class='directory'>doc</filename> directory of the source
    tree:</para>

<screen><userinput>tar -xf ../Linux-PAM-&linux-pam-version;-docs.tar.bz2 -C doc</userinput></screen>

    <para>Install <application>Linux-PAM</application> by
    running the following commands:</para>

<screen><userinput>./configure --libdir=/usr/lib \
            --sbindir=/lib/security \
            --enable-securedir=/lib/security \
            --enable-docdir=/usr/share/doc/Linux-PAM-&linux-pam-version; \
            --enable-read-both-confs &amp;&amp;
make</userinput></screen>

    <para>The test suite will not provide meaningful results until the package
    has been installed and configured. If, after installing the package and
    creating a minimum configuration as shown below in the 'other' example,
    you wish to run the tests, issue <command>make check</command>.</para>

    <tip>
      <para>Don't delete the <application>Linux-PAM</application> source tree
      until after you reinstall the <application>Shadow</application> package.
      The reinstallation of the Shadow package includes much more stringent
      security for the PAM configuration, and you can run the
      <application>Linux-PAM</application> test suite after completing the
      <application>Shadow</application> instructions to test the new setup. All
      the tests should pass.</para>
    </tip>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>make install &amp;&amp;
chmod -v 4755 /lib/security/unix_chkpwd &amp;&amp;
mv -v /lib/security/pam_tally /sbin &amp;&amp;
mv -v /usr/lib/libpam*.so.0* /lib &amp;&amp;
ln -v -sf ../../lib/libpam.so.0.81.3 /usr/lib/libpam.so &amp;&amp;
ln -v -sf ../../lib/libpamc.so.0.81.0 /usr/lib/libpamc.so &amp;&amp;
ln -v -sf ../../lib/libpam_misc.so.0.81.2 /usr/lib/libpam_misc.so</userinput></screen>

    <para>If you downloaded the documentation, install it using the following
    command:</para>

<screen role="root"><userinput>for DOCTYPE in html pdf ps txts
do
    cp -v -R doc/$DOCTYPE /usr/share/doc/Linux-PAM-&linux-pam-version;
done</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para><parameter>--libdir=/usr/lib</parameter>: This parameter results in
    the libraries being installed in
    <filename class='directory'>/usr/lib</filename>.</para>

    <para><parameter>--sbindir=/lib/security</parameter>: This parameter
    results in two executables, one which is not intended to be run from the
    command line, being installed in the same directory as the PAM modules.
    One of the executables is later moved to the
    <filename class='directory'>/sbin</filename> directory.</para>

    <para><parameter>--enable-securedir=/lib/security</parameter>: This
    parameter results in the PAM modules being installed in
    <filename class='directory'>/lib/security</filename>.</para>

    <para><parameter>--enable-docdir=...</parameter>: This parameter results in
    the documentation being installed in a versioned directory name.</para>

    <para><parameter>--enable-read-both-confs</parameter>: This parameter
    allows the local administrator to choose which configuration file setup to
    use.</para>

    <para><command>chmod -v 4755 /lib/security/unix_chkpwd</command>:
    The <command>unix_chkpwd</command> password-helper program must be setuid
    so that non-<systemitem class="username">root</systemitem> processes can
    access the shadow-password file.</para>

    <para><command>mv -v /lib/security/pam_tally /sbin</command>: The
    <command>pam_tally</command> program is designed to be run by the system
    administrator, possibly in single-user mode, so it is moved to the
    appropriate directory.</para>

    <para><command>mv -v /usr/lib/libpam*.so.0* /lib</command>: This command
    moves the dynamic libraries to <filename class='directory'>/lib</filename>
    as they may be required in single user mode.</para>

    <para><command>ln -v -sf ...</command>: These commands recreate the
    <filename class='symlink'>.so</filename> symlinks as the libraries they
    pointed to were moved to <filename class='directory'>/lib</filename>.</para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring Linux-PAM</title>

    <sect3 id="pam-config">
      <title>Config Files</title>

      <para><filename>/etc/security/*</filename> and
      <filename>/etc/pam.d/*</filename> or
      <filename>/etc/pam.conf</filename></para>

      <indexterm zone="linux-pam pam-config">
        <primary sortas="e-etc-security">/etc/security/*</primary>
      </indexterm>

      <indexterm zone="linux-pam pam-config">
        <primary sortas="e-etc-pam.d">/etc/pam.d/*</primary>
      </indexterm>

      <indexterm zone="linux-pam pam-config">
        <primary sortas="e-etc-pam.conf">/etc/pam.conf</primary>
      </indexterm>

    </sect3>

    <sect3>
      <title>Configuration Information</title>

      <para>Configuration information is placed in
      <filename class='directory'>/etc/pam.d/</filename> or
      <filename>/etc/pam.conf</filename> depending on system administrator
       preference. Below are example files of each type:</para>

<screen><literal># Begin /etc/pam.d/other

auth            required        pam_unix.so     nullok
account         required        pam_unix.so
session         required        pam_unix.so
password        required        pam_unix.so     nullok

# End /etc/pam.d/other

# Begin /etc/pam.conf

other           auth            required        pam_unix.so     nullok
other           account         required        pam_unix.so
other           session         required        pam_unix.so
other           password        required        pam_unix.so     nullok

# End /etc/pam.conf</literal></screen>

      <para>The <application>PAM</application> man page
      (<command>man pam</command>) provides a good starting point for
      descriptions of fields and allowable entries. The <ulink
      url="http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/pam.html">
      Linux-PAM System Administrators' Guide</ulink>
      is recommended for additional information.</para>

      <para>Refer to <ulink
      url="http://www.kernel.org/pub/linux/libs/pam/modules.html"/>
      for a list of various modules available.</para>

      <important>
        <para>You should now reinstall the <xref linkend="shadow"/>
        package.</para>
      </important>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Program</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>pam_tally</seg>
        <seg>libpam.{so,a}, libpamc.{so,a}, and libpam_misc.{so,a}</seg>
        <seg>/etc/pam.d, /etc/security, /lib/security and
        /usr/include/security</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="pam_tally">
        <term><command>pam_tally</command></term>
        <listitem>
          <para>is used to view or manipulate the <filename>faillog</filename>
          file.</para>
          <indexterm zone="linux-pam pam_tally">
            <primary sortas="b-pam_tally">pam_tally</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libpam">
        <term><filename class='libraryfile'>libpam.{so,a}</filename></term>
        <listitem>
          <para>provides the interfaces between applications and the
          PAM modules.</para>
          <indexterm zone="linux-pam libpam">
            <primary sortas="c-libpam">libpam.{so,a}</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>