path: root/modules/pam_lastlog/pam_lastlog.8.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="pam_lastlog">

  <refmeta>
    <refentrytitle>pam_lastlog</refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
  </refmeta>

  <refnamediv id="pam_lastlog-name">
    <refname>pam_lastlog</refname>
    <refpurpose>PAM module to display date of last login and perform inactive account lock out</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis id="pam_lastlog-cmdsynopsis">
      <command>pam_lastlog.so</command>
      <arg choice="opt">
	debug
      </arg>
      <arg choice="opt">
        silent
      </arg>
      <arg choice="opt">
        never
      </arg>
      <arg choice="opt">
        nodate
      </arg>
      <arg choice="opt">
        nohost
      </arg>
      <arg choice="opt">
        noterm
      </arg>
      <arg choice="opt">
        nowtmp
      </arg>
      <arg choice="opt">
        noupdate
      </arg>
      <arg choice="opt">
        showfailed
      </arg>
      <arg choice="opt">
        inactive=&lt;days&gt;
      </arg>
      <arg choice="opt">
        unlimited
      </arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1 id="pam_lastlog-description">

    <title>DESCRIPTION</title>

    <para>
      pam_lastlog is a PAM module to display a line of information
      about the last login of the user. In addition, the module maintains
      the <filename>/var/log/lastlog</filename> file.
    </para>
    <para>
      Some applications may perform this function themselves. In such
      cases, this module is not necessary.
    </para>
    <para>
      The module checks <option>LASTLOG_UID_MAX</option> option in
      <filename>/etc/login.defs</filename> and does not update or display
      last login records for users with UID higher than its value.
      If the option is not present or its value is invalid, no user ID
      limit is applied.
    </para>
    <para>
      If the module is called in the auth or account phase, the accounts that
      were not used recently enough will be disallowed to log in. The
      check is not performed for the root account so the root is never
      locked out. It is also not performed for users with UID higher
      than the <option>LASTLOG_UID_MAX</option> value.
    </para>
  </refsect1>

  <refsect1 id="pam_lastlog-options">

    <title>OPTIONS</title>
    <variablelist>
      <varlistentry>
        <term>
          <option>debug</option>
        </term>
        <listitem>
          <para>
            Print debug information.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>silent</option>
        </term>
        <listitem>
          <para>
            Don't inform the user about any previous login,
            just update the <filename>/var/log/lastlog</filename> file.
            This option does not affect display of bad login attempts.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>never</option>
        </term>
        <listitem>
          <para>
            If the <filename>/var/log/lastlog</filename> file does
            not contain any old entries for the user, indicate that
            the user has never previously logged in with a welcome
            message.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>nodate</option>
        </term>
        <listitem>
          <para>
            Don't display the date of the last login.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>noterm</option>
        </term>
        <listitem>
          <para>
            Don't display the terminal name on which the
            last login was attempted.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>nohost</option>
        </term>
        <listitem>
          <para>
            Don't indicate from which host the last login was
            attempted.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>nowtmp</option>
        </term>
        <listitem>
          <para>
            Don't update the wtmp entry.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>noupdate</option>
        </term>
        <listitem>
          <para>
            Don't update any file.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>showfailed</option>
        </term>
        <listitem>
          <para>
            Display number of failed login attempts and the date of the
            last failed attempt from btmp. The date is not displayed
            when <option>nodate</option> is specified.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>inactive=&lt;days&gt;</option>
        </term>
        <listitem>
          <para>
            This option is specific for the auth or account phase. It
            specifies the number of days after the last login of the user
            when the user will be locked out by the module. The default
            value is 90.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>unlimited</option>
        </term>
        <listitem>
          <para>
	    If the <emphasis>fsize</emphasis> limit is set, this option can be
	    used to override it, preventing failures on systems with large UID
	    values that lead lastlog to become a huge sparse file.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id="pam_lastlog-types">
    <title>MODULE TYPES PROVIDED</title>
    <para>
      The <option>auth</option> and <option>account</option> module type
      allows one to lock out users who did not login recently enough.
      The <option>session</option> module type is provided for displaying
      the information about the last login and/or updating the lastlog and
      wtmp files.
    </para>
  </refsect1>

  <refsect1 id='pam_lastlog-return_values'>
    <title>RETURN VALUES</title>
    <para>
      <variablelist>

        <varlistentry>
          <term>PAM_SUCCESS</term>
          <listitem>
            <para>
              Everything was successful.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>PAM_SERVICE_ERR</term>
          <listitem>
            <para>
	      Internal service module error.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>PAM_USER_UNKNOWN</term>
          <listitem>
            <para>
	      User not known.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>PAM_AUTH_ERR</term>
          <listitem>
            <para>
	      User locked out in the auth or account phase due to
	      inactivity.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>PAM_IGNORE</term>
          <listitem>
            <para>
	      There was an error during reading the lastlog file
	      in the auth or account phase and thus inactivity
	      of the user cannot be determined.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>
    </para>
  </refsect1>

  <refsect1 id='pam_lastlog-examples'>
    <title>EXAMPLES</title>
    <para>
      Add the following line to <filename>/etc/pam.d/login</filename> to
      display the last login time of a user:
    </para>
      <programlisting>
    session  required  pam_lastlog.so nowtmp
      </programlisting>
    <para>
     To reject the user if he did not login during the previous 50 days
     the following line can be used:
    </para>
      <programlisting>
    auth  required  pam_lastlog.so inactive=50
      </programlisting>
  </refsect1>

  <refsect1 id="pam_lastlog-files">
    <title>FILES</title>
    <variablelist>
      <varlistentry>
        <term><filename>/var/log/lastlog</filename></term>
        <listitem>
          <para>Lastlog logging file</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id='pam_lastlog-see_also'>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
	<refentrytitle>limits.conf</refentrytitle><manvolnum>5</manvolnum>
      </citerefentry>,
      <citerefentry>
	<refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
      </citerefentry>,
      <citerefentry>
	<refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum>
      </citerefentry>,
      <citerefentry>
	<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>
    </para>
  </refsect1>

  <refsect1 id='pam_lastlog-author'>
    <title>AUTHOR</title>
      <para>
        pam_lastlog was written by Andrew G. Morgan &lt;morgan@kernel.org&gt;.
      </para>
      <para>
        Inactive account lock out added by Tomáš Mráz &lt;tm@t8m.info&gt;.
      </para>
  </refsect1>

</refentry>