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

<?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        "7b73e58b7ce79ffa321d408de06db2c4">
  <!ENTITY linux-pam-size          "1.1 MB">
  <!ENTITY linux-pam-buildsize     "28 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   "43d19ccf40c1feb074e29922626f4971">
  <!ENTITY linux-pam-docs-size     "144 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$</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 used to enable the local
      system administrator to choose how applications authenticate
      users.
    </para>

    &lfs72_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 \
            --docdir=/usr/share/doc/Linux-PAM-&linux-pam-version; \
            --disable-nis &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 /sbin/security/unix_chkpwd</userinput></screen>
  </sect2>

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

    <para>
      <option>--disable-nis</option>: This switch disables building
      of the Network Information Service/Yellow Pages support in
      pam_unix and pam_access modules. Remove it if you have installed
      <xref linkend="libtirpc"/>.
    </para>

    <para>
      <command>chmod -v 4755 /sbin/security/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="&debian-pam-docs;/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>