source: postlfs/security/linux-pam.xml@ de7f20e

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

  <!ENTITY linux-pam-download-http "http://www.kernel.org/pub/linux/libs/pam/library/Linux-PAM-&linux-pam-version;.tar.bz2">
  <!ENTITY linux-pam-download-ftp  "ftp://ftp.kernel.org/pub/linux/libs/pam/library/Linux-PAM-&linux-pam-version;.tar.bz2">
  <!ENTITY linux-pam-md5sum        "189171821b56aaf791cc890d0707ea82">
  <!ENTITY linux-pam-size          "1.0 MB">
  <!ENTITY linux-pam-buildsize     "21 MB (includes installing the optional documentation)">
  <!ENTITY linux-pam-time          "0.6 SBU">

  <!ENTITY linux-pam-docs-download "http://www.kernel.org/pub/linux/libs/pam/documentation/Linux-PAM-&linux-pam-version;-docs.tar.bz2">
  <!ENTITY linux-pam-docs-md5sum   "c171a8f19ac79f51cc524c89bfa98716">
  <!ENTITY linux-pam-docs-size     "700 KB">
]>

<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>
      <listitem>
        <para>Download MD5sum: &linux-pam-docs-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size &linux-pam-docs-size;</para>
      </listitem>
    </itemizedlist>

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

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><xref linkend="cracklib"/>,
    <xref linkend="x-window-system"/>,
    <xref linkend="db"/> (for the pam_userdb module), and
    <ulink url="http://www.prelude-ids.org/">Prelude</ulink></para>

    <bridgehead renderas="sect4">Optional (To {,Re}build the Documentation)</bridgehead>
    <para role="optional"><xref linkend="libxslt"/>,
    <xref linkend="DocBook"/>,
    <xref linkend="docbook-xsl"/>,
    <xref linkend="w3m"/>, and
    <xref linkend="fop"/></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 by issuing
    the following command.</para>

<screen><userinput>tar xf ../Linux-PAM-&linux-pam-version;-docs.tar.bz2 --strip-components=1</userinput></screen>

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

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

    <para>To test the results, a configuration file must be created. This file
    will be removed after the tests have completed. Ensure there are no errors
    produced by the tests before continuing the installation. First create the
    configuration file by issuing the following commands as the
    <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>install -v -m755 -d /etc/pam.d &amp;&amp;

cat &gt; /etc/pam.d/other &lt;&lt; "EOF"
auth     required       pam_deny.so
account  required       pam_deny.so
password required       pam_deny.so
session  required       pam_deny.so
EOF</userinput></screen>

    <para>Now run the tests by issuing <command>make check</command>.</para>

    <para>Remove the configuration file created earlier by issuing the
    following command as the
    <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>rm -rfv /etc/pam.d</userinput></screen>

    <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 /lib/libpam{,c,_misc}.la /usr/lib &amp;&amp;
sed -i 's| /lib| /usr/lib|' /usr/lib/libpam_misc.la &amp;&amp;

if [ -L /lib/libpam.so ]; then
   for LINK in libpam{,c,_misc}.so; do
       ln -v -sf ../../lib/$(readlink /lib/${LINK}) /usr/lib/${LINK} &amp;&amp;
       rm -v /lib/${LINK}
   done
fi</userinput></screen>

  </sect2>

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

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

    <para><parameter>--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>

    <!-- This appears unnecessary as the xauth module is created even if X
         has not yet been installed.
    <para><parameter>-with-xauth=/usr/X11R6/bin/xauth</parameter>: This
    parameter forces the build of the pam_xauth module, even if xauth is not
    yet installed.  Omit this switch if you have no plans to build
    <application>Xorg</application>, or modify the path if you intend to
    install <application>Xorg</application> into a non-standard path.</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 /lib/libpam{,c,_misc}.la /usr/lib</command>: This
    command moves the <application>Libtool</application> library files to
    <filename class='directory'>/usr/lib</filename> as they are expected to
    reside there.</para>

    <para><command>sed -i 's| /lib| /usr/lib|'
    /usr/lib/libpam_misc.la</command>: This command corrects an installation
    reference due to the file being moved in the previous step.</para>

    <para><command>for ...; do ...; done</command>: These commands are used
    to relocate the <filename class='symlink'>.so</filename> symbolic links
    into the <filename class='directory'>/usr/lib</filename> directory by
    cloning and then removing the existing symlinks. Using
    <command>readlink</command> ensures the new symlinks point at the correct
    library filenames.</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/Linux-PAM_SAG.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 third-party 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}, libpam_misc.{so,a} and
        numerous PAM modules</seg>
        <seg>/etc/pam.d, /etc/security, /lib/security,
        /usr/include/security, /usr/share/doc/Linux-PAM-&linux-pam-version;
        and /var/run/sepermit</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>