<?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://linux-pam.org/library/Linux-PAM-&linux-pam-version;.tar.bz2">
  <!ENTITY linux-pam-download-ftp  " ">
  <!ENTITY linux-pam-md5sum        "35b6091af95981b1b2cd60d813b5e4ee">
  <!ENTITY linux-pam-size          "1.1 MB">
  <!ENTITY linux-pam-buildsize     "22 MB">
  <!ENTITY linux-pam-time          "0.3 SBU">

  <!ENTITY linux-pam-docs-download "http://linux-pam.org/documentation/Linux-PAM-&linux-pam-version;-docs.tar.bz2">
  <!ENTITY linux-pam-docs-md5sum   "730895d1c6e1c706dc5ffe2419f9b3f5">
  <!ENTITY linux-pam-docs-size     "148 KB">
  <!ENTITY debian-pam-docs         "http://debian.securedservers.com/kernel/pub/linux/libs/pam">
]>

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

  <sect1info>
    <othername>$LastChangedBy: pierre $</othername>
    <date>$Date: 2015-02-22 17:34:08 -0500 (Sun, 22 Feb 2015) $</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 used to enable the local
      system administrator to choose how applications authenticate
      users.
    </para>

    &lfs77_checked;

    <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">
    <title>Optional Documentation</title>
      <listitem>
        <para>
          Download (HTTP): <ulink url="&linux-pam-docs-download;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &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="db"/>,
      <xref linkend="cracklib"/>,
      <xref linkend="libtirpc"/> and
      <ulink url="http://www.prelude-ids.org/">Prelude</ulink>
    </para>

    <bridgehead renderas="sect4">Optional (To Rebuild the Documentation)</bridgehead>
    <para role="optional">
      <xref linkend="DocBook"/>,
      <xref linkend="docbook-xsl"/>,
      <xref linkend="fop"/>,
      <xref linkend="libxslt"/> and
      <xref linkend="w3m"/>
    </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 --prefix=/usr \
            --sysconfdir=/etc \
            --libdir=/usr/lib \
            --enable-securedir=/lib/security \
            --docdir=/usr/share/doc/Linux-PAM-&linux-pam-version; &amp;&amp;
make</userinput></screen>

    <para>
      To test the results, a suitable <filename>/etc/pam.d/other</filename>
      configuration file must exist.
    </para>

    <caution>
      <title>Reinstallation or upgrade of Linux PAM</title>
      <para>
        If you have a system with Linux PAM installed and working, be careful
        when modifying the files in
        <filename class="directory">/etc/pam.d</filename>, since your system
        may become totally unusable. If you want to run the tests, you do not
        need to create another <filename>/etc/pam.d/other</filename> file. The
        installed one can be used for that purpose.
      </para>

      <para>
         You should also be aware that <command>make install</command>
         overwrites the configuration files in
         <filename class="directory">/etc/security</filename> as well as
         <filename>/etc/environment</filename>. In case you
         have modified those files, be sure to backup them.
      </para>
    </caution>

    <para>
      For a first installation, 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>.
      Ensure there are no errors produced by the tests before continuing the
      installation.
    </para>

    <para>
      Only in case of a first installation, 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 /sbin/unix_chkpwd &amp;&amp;

for file in pam pam_misc pamc
do
  mv -v /usr/lib/lib${file}.so.* /lib &amp;&amp;
  ln -sfv ../../lib/$(readlink /usr/lib/lib${file}.so) /usr/lib/lib${file}.so
done</userinput></screen>

  </sect2>

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

    <para>
      <parameter>--enable-securedir=/lib/security</parameter>:
      This switch sets install location for the
      <application>PAM</application> modules.
    </para>

    <para>
      <command>chmod -v 4755 /sbin/unix_chkpwd</command>:
      The <command>unix_chkpwd</command> helper program must be setuid
      so that non-<systemitem class="username">root</systemitem>
      processes can access the shadow file.
    </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>
      </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>

    </sect3>

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

      <para>
        Configuration information is placed in
        <filename class="directory">/etc/pam.d/</filename>.
        Below is an example file:
      </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</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.linux-pam.org/Linux-PAM-html/Linux-PAM_SAG.html">Linux-PAM
        System Administrators' Guide</ulink> is recommended for additional
        information.
      </para>

      <para>
        Refer to <ulink url="&debian-pam-docs;/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>
          mkhomedir_helper, pam_tally, pam_tally2,
          pam_timestamp_check, unix_chkpwd and
          unix_update
        </seg>
        <seg>
          libpam.so, libpamc.so and libpam_misc.so
        </seg>
        <seg>
          /etc/security,
          /lib/security,
          /usr/include/security and
          /usr/share/doc/Linux-PAM-&linux-pam-version;
        </seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="mkhomedir_helper">
        <term><command>mkhomedir_helper</command></term>
        <listitem>
          <para>
            is a helper binary that creates home directories.
          </para>
          <indexterm zone="linux-pam mkhomedir_helper">
            <primary sortas="b-mkhomedir_helper">mkhomedir_helper</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pam_tally">
        <term><command>pam_tally</command></term>
        <listitem>
          <para>
            is used to interrogate and manipulate the login counter file.
          </para>
          <indexterm zone="linux-pam pam_tally">
            <primary sortas="b-pam_tally">pam_tally</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pam_tally2">
        <term><command>pam_tally2</command></term>
        <listitem>
          <para>
            is used to interrogate and manipulate the login counter file, but
            does not have some limitations that <command>pam_tally</command>
            does.
          </para>
          <indexterm zone="linux-pam pam_tally2">
            <primary sortas="b-pam_tally2">pam_tally2</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pam_timestamp_check">
        <term><command>pam_timestamp_check</command></term>
        <listitem>
          <para>
            is used to check if the default timestamp is valid
          </para>
          <indexterm zone="linux-pam pam_timestamp_check">
            <primary sortas="b-pam_timestamp_check">pam_timestamp_check</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="unix_chkpwd">
        <term><command>unix_chkpwd</command></term>
        <listitem>
          <para>
            is a helper binary that verifies the password of the current user.
          </para>
          <indexterm zone="linux-pam unix_chkpwd">
            <primary sortas="b-unix_chkpwd">unix_chkpwd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="unix_update">
        <term><command>unix_update</command></term>
        <listitem>
          <para>
            is a helper binary that updates the password of a given user.
          </para>
          <indexterm zone="linux-pam unix_update">
            <primary sortas="b-unix_update">unix_update</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libpam">
        <term><filename class="libraryfile">libpam.so</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</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>
