<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pwhistory.conf">

  <refmeta>
    <refentrytitle>pwhistory.conf</refentrytitle>
    <manvolnum>5</manvolnum>
    <refmiscinfo class="source">Linux-PAM</refmiscinfo>
    <refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
  </refmeta>

  <refnamediv xml:id="pwhistory.conf-name">
    <refname>pwhistory.conf</refname>
    <refpurpose>pam_pwhistory configuration file</refpurpose>
  </refnamediv>

  <refsect1 xml:id="pwhistory.conf-description">

    <title>DESCRIPTION</title>
    <para>
       <emphasis remap="B">pwhistory.conf</emphasis> provides a way to configure the
       default settings for saving the last passwords for each user.
       This file is read by the <emphasis>pam_pwhistory</emphasis> module and is the
       preferred method over configuring <emphasis>pam_pwhistory</emphasis> directly.
    </para>
    <para>
       The file has a very simple <emphasis>name = value</emphasis> format with possible comments
       starting with <emphasis>#</emphasis> character. The whitespace at the beginning of line, end
       of line, and around the <emphasis>=</emphasis> sign is ignored.
    </para>
  </refsect1>

  <refsect1 xml:id="pwhistory.conf-options">

    <title>OPTIONS</title>
         <variablelist>
            <varlistentry>
              <term>
                debug
              </term>
              <listitem>
                <para>
                  Turns on debugging via
                  <citerefentry>
                    <refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
                  </citerefentry>.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                enforce_for_root
              </term>
              <listitem>
                <para>
                  If this option is set, the check is enforced for root, too.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                remember=N
              </term>
              <listitem>
                <para>
                  The last <replaceable>N</replaceable> passwords for each
                  user are saved.
                  The default is <emphasis>10</emphasis>. Value of
                  <emphasis>0</emphasis> makes the module to keep the existing
                  contents of the <filename>opasswd</filename> file unchanged.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                retry=N
              </term>
              <listitem>
                <para>
                  Prompt user at most <replaceable>N</replaceable> times
                  before returning with error. The default is 1.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                file=/path/filename
              </term>
              <listitem>
                <para>
                  Store password history in file
                  <replaceable>/path/filename</replaceable> rather than the default
                  location. The default location is
	                <filename>/etc/security/opasswd</filename>.
                </para>
              </listitem>
            </varlistentry>
        </variablelist>
  </refsect1>

  <refsect1 xml:id="pwhistory.conf-examples">
    <title>EXAMPLES</title>
    <para>
      /etc/security/pwhistory.conf file example:
    </para>
    <programlisting>
debug
remember=5
file=/tmp/opasswd
    </programlisting>
  </refsect1>

  <refsect1 xml:id="pwhistory.conf-files">
    <title>FILES</title>
    <variablelist>
      <varlistentry>
        <term>/etc/security/pwhistory.conf</term>
        <listitem>
          <para>the config file for custom options</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 xml:id="pwhistory.conf-see_also">
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>pwhistory</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pam_pwhistory</refentrytitle><manvolnum>8</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 xml:id="pwhistory.conf-author">
    <title>AUTHOR</title>
      <para>
        pam_pwhistory was written by Thorsten Kukuk. The support for
        pwhistory.conf was written by Iker Pedrosa.
      </para>
  </refsect1>

</refentry>