Adding upstream version 1.5.2.upstream/1.5.2upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

23 files changed, 1877 insertions, 0 deletions

diff --git a/doc/adg/Linux-PAM_ADG.xml b/doc/adg/Linux-PAM_ADG.xml
new file mode 100644
index 0000000..79452e1
--- /dev/null
+++ b/doc/adg/Linux-PAM_ADG.xml
@@ -0,0 +1,780 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+	"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<book id="adg">
+  <bookinfo>
+    <title>The Linux-PAM Application Developers' Guide</title>
+    <authorgroup>
+      <author>
+        <firstname>Andrew G.</firstname>
+        <surname>Morgan</surname>
+        <email>morgan@kernel.org</email>
+      </author>
+      <author>
+        <firstname>Thorsten</firstname>
+        <surname>Kukuk</surname>
+        <email>kukuk@thkukuk.de</email>
+      </author>
+    </authorgroup>
+    <releaseinfo>Version 1.1.2, 31. August 2010</releaseinfo>
+    <abstract>
+      <para>
+        This manual documents what an application developer needs to know
+        about the <emphasis remap='B'>Linux-PAM</emphasis> library. It
+        describes how an application might use the
+        <emphasis remap='B'>Linux-PAM</emphasis> library to authenticate
+        users. In addition it contains a description of the functions
+        to be found in <filename>libpam_misc</filename> library, that can
+        be used in general applications. Finally, it contains some comments
+        on PAM related security issues for the application developer.
+      </para>
+    </abstract>
+  </bookinfo>
+
+  <chapter id="adg-introduction">
+    <title>Introduction</title>
+    <section id="adg-introduction-description">
+      <title>Description</title>
+      <para>
+        <emphasis remap='B'>Linux-PAM</emphasis>
+        (Pluggable Authentication Modules for Linux) is a library that enables
+        the local system administrator to choose how individual applications
+        authenticate users. For an overview of the
+        <emphasis remap='B'>Linux-PAM</emphasis> library see the
+        <emphasis>Linux-PAM System Administrators' Guide</emphasis>.
+      </para>
+      <para>
+        It is the purpose of the <emphasis remap='B'>Linux-PAM</emphasis>
+        project to liberate the development of privilege granting software
+        from the development of secure and appropriate authentication schemes.
+        This is accomplished by providing a documented library of functions
+        that an application may use for all forms of user authentication
+        management. This library dynamically loads locally configured
+        authentication modules that actually perform the authentication tasks.
+      </para>
+      <para>
+        From the perspective of an application developer the information
+        contained in the local configuration of the PAM library should not be
+        important. Indeed it is intended that an application treat the
+        functions documented here as a 'black box' that will deal with all
+        aspects of user authentication. 'All aspects' includes user
+        verification, account management, session initialization/termination
+        and also the resetting of passwords
+        (<emphasis>authentication tokens</emphasis>).
+      </para>
+    </section>
+
+    <section id="adg-introduction-synopsis">
+      <title>Synopsis</title>
+      <para>
+        For general applications that wish to use the services provided by
+        <emphasis remap='B'>Linux-PAM</emphasis> the following is a summary
+        of the relevant linking information:
+        <programlisting>
+#include &lt;security/pam_appl.h&gt;
+
+cc -o application .... -lpam
+        </programlisting>
+      </para>
+      <para>
+        In addition to <command>libpam</command>, there is a library of
+        miscellaneous functions that make the job of writing
+        <emphasis>PAM-aware</emphasis> applications easier (this library is not
+        covered in the DCE-RFC for PAM and is specific to the Linux-PAM
+        distribution):
+        <programlisting>
+#include &lt;security/pam_appl.h&gt;
+#include &lt;security/pam_misc.h&gt;
+
+cc -o application .... -lpam -lpam_misc
+        </programlisting>
+      </para>
+    </section>
+  </chapter>
+
+  <chapter id="adg-overview">
+    <title>Overview</title>
+    <para>
+      Most service-giving applications are restricted. In other words,
+      their service is not available to all and every prospective client.
+      Instead, the applying client must jump through a number of hoops to
+      convince the serving application that they are authorized to obtain
+      service.
+    </para>
+    <para>
+      The process of <emphasis>authenticating</emphasis> a client is what
+      PAM is designed to manage. In addition to authentication, PAM provides
+      account management, credential management, session management and
+      authentication-token (password changing) management services.  It is
+      important to realize when writing a PAM based application that these
+      services are provided in a manner that is
+      <emphasis remap='B'>transparent</emphasis> to the application. That is
+      to say, when the application is written, no assumptions can be made
+      about <emphasis>how</emphasis> the client will be authenticated.
+    </para>
+    <para>
+      The process of authentication is performed by the PAM library via a
+      call to <function>pam_authenticate()</function>. The return value
+      of this function will indicate whether a named client (the
+      <emphasis>user</emphasis>) has been authenticated. If the PAM library
+      needs to prompt the user for any information, such as their
+      <emphasis>name</emphasis> or a <emphasis>password</emphasis>
+      then it will do so. If the PAM library is configured to authenticate
+      the user using some silent protocol, it will do this too. (This
+      latter case might be via some hardware interface for example.)
+    </para>
+    <para>
+      It is important to note that the application must leave all decisions
+      about when to prompt the user at the discretion of the PAM library.
+    </para>
+    <para>
+      The PAM library, however, must work equally well for different styles
+      of application. Some applications, like the familiar
+      <command>login</command> and <command>passwd</command> are terminal
+      based applications, exchanges of information with the client in
+      these cases is as plain text messages. Graphically based applications,
+      however, have a more sophisticated interface. They generally interact
+      with the user via specially constructed dialogue boxes. Additionally,
+      network based services require that text messages exchanged with the
+      client are specially formatted for automated processing: one such
+      example is <command>ftpd</command> which prefixes each exchanged
+      message with a numeric identifier.
+    </para>
+    <para>
+      The presentation of simple requests to a client is thus something very
+      dependent on the protocol that the serving application will use. In
+      spite of the fact that PAM demands that it drives the whole
+      authentication process, it is not possible to leave such protocol
+      subtleties up to the PAM library.  To overcome this potential problem,
+      the application provides the PAM library with a
+      <emphasis>conversation</emphasis> function.  This function is called
+      from <emphasis>within</emphasis> the PAM library and enables the PAM
+      to directly interact with the client. The sorts of things that this
+      conversation function must be able to do are prompt the user with
+      text and/or obtain textual input from the user for processing by the
+      PAM library. The details of this function are provided in a later
+      section.
+    </para>
+    <para>
+      For example, the conversation function may be called by the PAM
+      library with a request to prompt the user for a password. Its job is
+      to reformat the prompt request into a form that the client will
+      understand. In the case of <command>ftpd</command>, this might involve
+      prefixing the string with the number <command>331</command> and sending
+      the request over the network to a connected client. The conversation
+      function will then obtain any reply and, after extracting the typed
+      password, will return this string of text to the PAM library. Similar
+      concerns need to be addressed in the case of an X-based graphical
+      server.
+    </para>
+    <para>
+      There are a number of issues that need to be addressed when one is
+      porting an existing application to become PAM compliant. A section
+      below has been devoted to this: Porting legacy applications.
+    </para>
+    <para>
+      Besides authentication, PAM provides other forms of management.
+      Session management is provided with calls to
+      <function>pam_open_session()</function> and
+      <function>pam_close_session()</function>. What these functions
+      actually do is up to the local administrator. But typically, they
+      could be used to log entry and exit from the system or for mounting
+      and unmounting the user's home directory. If an application provides
+      continuous service for a period of time, it should probably call
+      these functions, first open after the user is authenticated and then
+      close when the service is terminated.
+    </para>
+    <para>
+      Account management is another area that an application developer
+      should include with a call to <function>pam_acct_mgmt()</function>.
+      This call will perform checks on the good health of the user's account
+      (has it expired etc.). One of the things this function may check is
+      whether the user's authentication token has expired - in such a case the
+      application may choose to attempt to update it with a call to
+      <function>pam_chauthtok()</function>, although some applications
+      are not suited to this task (<command>ftp</command> for example)
+      and in this case the application should deny access to the user.
+    </para>
+    <para>
+      PAM is also capable of setting and deleting the user's credentials with
+      the call <function>pam_setcred()</function>. This function should
+      always be called after the user is authenticated and before service
+      is offered to the user. By convention, this should be the last call
+      to the PAM library before the PAM session is opened. What exactly a
+      credential is, is not well defined. However, some examples are given
+      in the glossary below.
+    </para>
+  </chapter>
+
+  <chapter id="adg-interface">
+    <title>
+      The public interface to <emphasis remap='B'>Linux-PAM</emphasis>
+    </title>
+    <para>
+      Firstly, the relevant include file for the
+      <emphasis remap='B'>Linux-PAM</emphasis> library is
+      <function>&lt;security/pam_appl.h&gt;</function>.
+      It contains the definitions for a number of functions. After
+      listing these functions, we collect some guiding remarks for
+      programmers.
+    </para>
+    <section id="adg-interface-by-app-expected">
+      <title>What can be expected by the application</title>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+       href="pam_start.xml"/>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+       href="pam_end.xml"/>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+       href="pam_set_item.xml"/>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+       href="pam_get_item.xml"/>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+       href="pam_strerror.xml"/>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+       href="pam_fail_delay.xml"/>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+       href="pam_authenticate.xml"/>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+       href="pam_setcred.xml"/>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+       href="pam_acct_mgmt.xml"/>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+       href="pam_chauthtok.xml"/>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+       href="pam_open_session.xml"/>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+       href="pam_close_session.xml"/>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+       href="pam_putenv.xml"/>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+       href="pam_getenv.xml"/>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+       href="pam_getenvlist.xml"/>
+    </section>
+    <section id="adg-interface-of-app-expected">
+      <title>What is expected of an application</title>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+       href="pam_conv.xml"/>
+    </section>
+    <section id="adg-interface-programming-notes">
+      <title>Programming notes</title>
+      <para>
+        Note, all of the authentication service function calls accept the
+        token <emphasis remap='B'>PAM_SILENT</emphasis>, which instructs
+        the modules to not send messages to the application. This token
+        can be logically OR'd with any one of the permitted tokens specific
+        to the individual function calls.
+        <emphasis remap='B'>PAM_SILENT</emphasis> does not override the
+        prompting of the user for passwords etc., it only stops informative
+        messages from being generated.
+      </para>
+    </section>
+  </chapter>
+
+  <chapter id="adg-security">
+    <title>
+      Security issues of <emphasis remap='B'>Linux-PAM</emphasis>
+    </title>
+    <para>
+      PAM, from the perspective of an application, is a convenient API for
+      authenticating users. PAM modules generally have no increased
+      privilege over that possessed by the application that is making use of
+      it. For this reason, the application must take ultimate responsibility
+      for protecting the environment in which PAM operates.
+    </para>
+    <para>
+      A poorly (or maliciously) written application can defeat any
+      <emphasis remap='B'>Linux-PAM</emphasis> module's authentication
+      mechanisms by simply ignoring it's return values. It is the
+      applications task and responsibility to grant privileges and access
+      to services.  The <emphasis remap='B'>Linux-PAM</emphasis> library
+      simply assumes the responsibility of <emphasis>authenticating</emphasis>
+      the user; ascertaining that the user <emphasis>is</emphasis> who they
+      say they are. Care should be taken to anticipate all of the documented
+      behavior of the <emphasis remap='B'>Linux-PAM</emphasis> library
+      functions. A failure to do this will most certainly lead to a future
+      security breach.
+    </para>
+
+    <section id="adg-security-library-calls">
+      <title>Care about standard library calls</title>
+      <para>
+        In general, writers of authorization-granting applications should
+        assume that each module is likely to call any or
+        <emphasis>all</emphasis> 'libc' functions. For 'libc' functions
+        that return pointers to static/dynamically allocated structures
+        (ie. the library allocates the memory and the user is not expected
+        to '<function>free()</function>' it) any module call to this
+        function is likely to corrupt a pointer previously
+        obtained by the application. The application programmer should
+        either re-call such a 'libc' function after a call to the
+        <emphasis remap='B'>Linux-PAM</emphasis> library, or copy the
+        structure contents to some safe area of memory before passing
+        control to the <emphasis remap='B'>Linux-PAM</emphasis> library.
+      </para>
+      <para>
+        Two important function classes that fall into this category are
+        <citerefentry>
+          <refentrytitle>getpwnam</refentrytitle><manvolnum>3</manvolnum>
+        </citerefentry> and <citerefentry>
+          <refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
+        </citerefentry>.
+      </para>
+    </section>
+
+    <section id="adg-security-service-name">
+      <title>Choice of a service name</title>
+      <para>
+        When picking the <emphasis>service-name</emphasis> that
+        corresponds to the first entry in the
+        <emphasis remap='B'>Linux-PAM</emphasis> configuration file,
+        the application programmer should <emphasis>avoid</emphasis>
+        the temptation of choosing something related to
+        <varname>argv[0]</varname>. It is a trivial matter for any user
+        to invoke any application on a system under a different name and
+        this should not be permitted to cause a security breach.
+      </para>
+      <para>
+        In general, this is always the right advice if the program is
+        setuid, or otherwise more privileged than the user that invokes
+        it. In some cases, avoiding this advice is convenient, but as an
+        author of such an application, you should consider well the ways
+        in which your program will be installed and used. (Its often the
+        case that programs are not intended to be setuid, but end up
+        being installed that way for convenience. If your program falls
+        into this category, don't fall into the trap of making this mistake.)
+      </para>
+      <para>
+        To invoke some <emphasis>target</emphasis> application by
+        another name, the user may symbolically link the target application
+        with the desired name. To be precise all the user need do is,
+        <command>ln -s /target/application ./preferred_name</command>
+        and then run <command>./preferred_name</command>.
+      </para>
+      <para>
+        By studying the <emphasis remap='B'>Linux-PAM</emphasis>
+        configuration file(s), an attacker can choose the
+        <command>preferred_name</command> to be that of a service enjoying
+        minimal protection; for example a game which uses
+        <emphasis remap='B'>Linux-PAM</emphasis> to restrict access to
+        certain hours of the day.  If the service-name were to be linked
+        to the filename under which the service was invoked, it
+        is clear that the user is effectively in the position of
+        dictating which authentication scheme the service uses. Needless
+        to say, this is not a secure situation.
+      </para>
+      <para>
+        The conclusion is that the application developer should carefully
+        define the service-name of an application. The safest thing is to
+        make it a single hard-wired name.
+      </para>
+    </section>
+
+    <section id="adg-security-conv-function">
+      <title>The conversation function</title>
+      <para>
+        Care should be taken to ensure that the <function>conv()</function>
+        function is robust. Such a function is provided in the library
+        <command>libpam_misc</command> (see
+        <link linkend="adg-libpam-functions">below</link>).
+      </para>
+    </section>
+
+    <section id="adg-security-user-identity">
+      <title>The identity of the user</title>
+      <para>
+        The <emphasis remap='B'>Linux-PAM</emphasis> modules will need
+        to determine the identity of the user who requests a service,
+        and the identity of the user who grants the service. These two
+        users will seldom be the same. Indeed there is generally a third
+        user identity to be considered, the new (assumed) identity of
+        the user once the service is granted.
+      </para>
+      <para>
+        The need for keeping tabs on these identities is clearly an
+        issue of security. One convention that is actively used by
+        some modules is that the identity of the user requesting a
+        service should be the current <emphasis>UID</emphasis>
+        (user ID) of the running process; the identity of the
+        privilege granting user is the <emphasis>EUID</emphasis>
+        (effective user ID) of the running process; the identity of
+        the user, under whose name the service will be executed, is
+        given by the contents of the <emphasis>PAM_USER</emphasis>
+        <citerefentry>
+          <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
+        </citerefentry>. Note, modules can change the values of
+        <emphasis>PAM_USER</emphasis> and <emphasis>PAM_RUSER</emphasis>
+        during any of the <function>pam_*()</function> library calls.
+        For this reason, the application should take care to use the
+        <function>pam_get_item()</function> every time it wishes to
+        establish who the authenticated user is (or will currently be).
+      </para>
+      <para>
+        For network-serving databases and other applications that provide
+        their own security model (independent of the OS kernel) the above
+        scheme is insufficient to identify the requesting user.
+      </para>
+      <para>
+        A more portable solution to storing the identity of the requesting
+        user is to use the <emphasis>PAM_RUSER</emphasis> <citerefentry>
+        <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
+        </citerefentry>. The application should supply this value before
+        attempting to authenticate the user with
+        <function>pam_authenticate()</function>. How well this name can be
+        trusted will ultimately be at the discretion of the local
+        administrator (who configures PAM for your application) and a
+        selected module may attempt to override the value where it can
+        obtain more reliable data. If an application is unable to determine
+        the identity of the requesting entity/user, it should not call
+        <citerefentry>
+          <refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
+        </citerefentry> to set <emphasis>PAM_RUSER</emphasis>.
+      </para>
+      <para>
+        In addition to the <emphasis>PAM_RUSER</emphasis> item, the
+        application should supply the <emphasis>PAM_RHOST</emphasis>
+        (<emphasis>requesting host</emphasis>) item. As a general rule,
+        the following convention for its value can be assumed:
+        NULL = unknown; localhost = invoked directly from the local system;
+        <emphasis>other.place.xyz</emphasis> = some component of the
+        user's connection originates from this remote/requesting host. At
+        present, PAM has no established convention for indicating whether
+        the application supports a trusted path to communication from
+        this host.
+      </para>
+    </section>
+
+    <section id="adg-security-resources">
+      <title>Sufficient resources</title>
+      <para>
+        Care should be taken to ensure that the proper execution of an
+        application is not compromised by a lack of system resources. If an
+        application is unable to open sufficient files to perform its service,
+        it should fail gracefully, or request additional resources.
+        Specifically, the quantities manipulated by the <citerefentry>
+        <refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum>
+      </citerefentry> family of commands should be taken into consideration.
+      </para>
+      <para>
+        This is also true of conversation prompts. The application should not
+        accept prompts of arbitrary length with out checking for resource
+        allocation failure and dealing with such extreme conditions gracefully
+        and in a manner that preserves the PAM API. Such tolerance may be
+        especially important when attempting to track a malicious adversary.
+      </para>
+    </section>
+  </chapter>
+
+  <chapter id='adg-libpam_misc'>
+    <title>A library of miscellaneous helper functions</title>
+    <para>
+      To aid the work of the application developer a library of
+      miscellaneous functions is provided.  It is called
+      <command>libpam_misc</command>, and contains a text based
+      conversation function, and routines for enhancing the standard
+      PAM-environment variable support.
+    </para>
+    <para>
+      The functions, structures and macros, made available by this
+      library can be defined by including
+      <function>&lt;security/pam_misc.h&gt;</function>. It should be
+      noted that this library is specific to
+      <emphasis remap='B'>Linux-PAM</emphasis> and is not referred to in
+      the defining DCE-RFC (see <link linkend="adg-see-also">See also</link>)
+      below.
+    </para>
+    <section id='adg-libpam-functions'>
+      <title>Functions supplied</title>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+       href="pam_misc_conv.xml"/>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+       href="pam_misc_paste_env.xml"/>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+       href="pam_misc_drop_env.xml"/>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+       href="pam_misc_setenv.xml"/>
+    </section>
+  </chapter>
+
+  <chapter id='adg-porting'>
+    <title>Porting legacy applications</title>
+    <para>
+      The point of PAM is that the application is not supposed to
+      have any idea how the attached authentication modules will choose
+      to authenticate the user. So all they can do is provide a conversation
+      function that will talk directly to the user(client) on the modules'
+      behalf.
+    </para>
+    <para>
+      Consider the case that you plug a retinal scanner into the login
+      program. In this situation the user would be prompted: "please look
+      into the scanner". No username or password would be needed - all this
+      information could be deduced from the scan and a database lookup. The
+      point is that the retinal scanner is an ideal task for a "module".
+    </para>
+    <para>
+      While it is true that a pop-daemon program is designed with the POP
+      protocol in mind and no-one ever considered attaching a retinal
+      scanner to it, it is also the case that the "clean" PAM'ification of
+      such a daemon would allow for the possibility of a scanner module
+      being be attached to it. The point being that the "standard"
+      pop-authentication protocol(s) [which will be needed to satisfy
+      inflexible/legacy clients] would be supported by inserting an
+      appropriate pam_qpopper module(s).  However, having rewritten
+      <command>popd</command> once in this way any new protocols can be
+      implemented in-situ.
+    </para>
+    <para>
+      One simple test of a ported application would be to insert the
+      <command>pam_permit</command> module and see if the application
+      demands you type a password...  In such a case, <command>xlock</command>
+      would fail to lock the terminal - or would at best be a screen-saver,
+      ftp would give password free access to all etc..  Neither of
+      these is a very secure thing to do, but they do illustrate how
+      much flexibility PAM puts in the hands of the local admin.
+    </para>
+    <para>
+      The key issue, in doing things correctly, is identifying what is part
+      of the authentication procedure (how many passwords etc..) the
+      exchange protocol (prefixes to prompts etc., numbers like 331 in the
+      case of ftpd) and what is part of the service that the application
+      delivers.  PAM really needs to have total control in the
+      authentication "procedure", the conversation function should only
+      deal with reformatting user prompts and extracting responses from raw
+      input.
+    </para>
+  </chapter>
+
+  <chapter id='adg-glossary'>
+    <title>Glossary of PAM related terms</title>
+    <para>
+      The following are a list of terms used within this document.
+    </para>
+    <variablelist>
+      <varlistentry>
+        <term>Authentication token</term>
+        <listitem>
+          <para>
+            Generally, this is a password. However, a user can authenticate
+            him/herself in a variety of ways. Updating the user's
+            authentication token thus corresponds to
+            <emphasis>refreshing</emphasis> the object they use to
+            authenticate themself with the system. The word password is
+            avoided to keep open the possibility that the authentication
+            involves a retinal scan or other non-textual mode of
+            challenge/response.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>Credentials</term>
+        <listitem>
+          <para>
+            Having successfully authenticated the user, PAM is able to
+            establish certain characteristics/attributes of the user.
+            These are termed <emphasis>credentials</emphasis>. Examples
+            of which are group memberships to perform privileged tasks
+            with, and <emphasis>tickets</emphasis> in the form of
+            environment variables etc. . Some user-credentials, such as
+            the user's UID and GID (plus default group memberships) are
+            not deemed to be PAM-credentials. It is the responsibility
+            of the application to grant these directly.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </chapter>
+
+  <chapter id='adg-example'>
+    <title>An example application</title>
+    <para>
+      To get a flavor of the way a <emphasis remap='B'>Linux-PAM</emphasis>
+      application is written we include the following example. It prompts
+      the user for their password and indicates whether their account
+      is valid on the standard output, its return code also indicates
+      the success (<returnvalue>0</returnvalue> for success;
+      <returnvalue>1</returnvalue> for failure).
+    </para>
+    <programlisting><![CDATA[
+/*
+  This program was contributed by Shane Watts
+  [modifications by AGM and kukuk]
+
+  You need to add the following (or equivalent) to the
+  /etc/pam.d/check_user file:
+  # check authorization
+  auth       required     pam_unix.so
+  account    required     pam_unix.so
+ */
+
+#include <security/pam_appl.h>
+#include <security/pam_misc.h>
+#include <stdio.h>
+
+static struct pam_conv conv = {
+    misc_conv,
+    NULL
+};
+
+int main(int argc, char *argv[])
+{
+    pam_handle_t *pamh=NULL;
+    int retval;
+    const char *user="nobody";
+
+    if(argc == 2) {
+        user = argv[1];
+    }
+
+    if(argc > 2) {
+        fprintf(stderr, "Usage: check_user [username]\n");
+        exit(1);
+    }
+
+    retval = pam_start("check_user", user, &conv, &pamh);
+
+    if (retval == PAM_SUCCESS)
+        retval = pam_authenticate(pamh, 0);    /* is user really user? */
+
+    if (retval == PAM_SUCCESS)
+        retval = pam_acct_mgmt(pamh, 0);       /* permitted access? */
+
+    /* This is where we have been authorized or not. */
+
+    if (retval == PAM_SUCCESS) {
+        fprintf(stdout, "Authenticated\n");
+    } else {
+        fprintf(stdout, "Not Authenticated\n");
+    }
+
+    if (pam_end(pamh,retval) != PAM_SUCCESS) {     /* close Linux-PAM */
+        pamh = NULL;
+        fprintf(stderr, "check_user: failed to release authenticator\n");
+        exit(1);
+    }
+
+    return ( retval == PAM_SUCCESS ? 0:1 );       /* indicate success */
+}
+]]>
+    </programlisting>
+  </chapter>
+
+  <chapter id='adg-files'>
+    <title>Files</title>
+    <variablelist>
+      <varlistentry>
+        <term><filename>/usr/include/security/pam_appl.h</filename></term>
+        <listitem>
+          <para>
+            Header file with interfaces for
+            <emphasis remap='B'>Linux-PAM</emphasis> applications.
+           </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><filename>/usr/include/security/pam_misc.h</filename></term>
+        <listitem>
+          <para>
+            Header file for useful library functions for making
+            applications easier to write.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </chapter>
+
+  <chapter id="adg-see-also">
+    <title>See also</title>
+    <itemizedlist>
+      <listitem>
+        <para>
+          The Linux-PAM System Administrators' Guide.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The Linux-PAM Module Writers' Guide.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH
+          PLUGGABLE AUTHENTICATION MODULES'', Open Software Foundation
+          Request For Comments 86.0, October 1995.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </chapter>
+
+  <chapter id='adg-author'>
+    <title>Author/acknowledgments</title>
+    <para>
+      This document was written by Andrew G. Morgan (morgan@kernel.org)
+      with many contributions from
+      Chris Adams, Peter Allgeyer, Tim Baverstock, Tim Berger, Craig S. Bell,
+      Derrick J. Brashear, Ben Buxton, Seth Chaiklin, Oliver Crow, Chris Dent,
+      Marc Ewing, Cristian Gafton, Emmanuel Galanos, Brad M. Garcia,
+      Eric Hester, Roger Hu, Eric Jacksch, Michael K. Johnson, David Kinchlea,
+      Olaf Kirch, Marcin Korzonek, Thorsten Kukuk, Stephen Langasek,
+      Nicolai Langfeldt, Elliot Lee, Luke Kenneth Casson Leighton,
+      Al Longyear, Ingo Luetkebohle, Marek Michalkiewicz, Robert Milkowski,
+      Aleph One, Martin Pool, Sean Reifschneider, Jan Rekorajski, Erik Troan,
+      Theodore Ts'o, Jeff Uphoff, Myles Uyema, Savochkin Andrey Vladimirovich,
+      Ronald Wahl, David Wood, John Wilmes, Joseph S. D. Yao
+      and Alex O. Yuriev.
+    </para>
+    <para>
+      Thanks are also due to Sun Microsystems, especially to Vipin Samar and
+      Charlie Lai for their advice. At an early stage in the development of
+      <emphasis remap='B'>Linux-PAM</emphasis>, Sun graciously made the
+      documentation for their implementation of PAM available. This act
+      greatly accelerated the development of
+      <emphasis remap='B'>Linux-PAM</emphasis>.
+    </para>
+  </chapter>
+
+  <chapter id='adg-copyright'>
+    <title>Copyright information for this document</title>
+    <programlisting>
+Copyright (c) 2006 Thorsten Kukuk &lt;kukuk@thkukuk.de&gt;
+Copyright (c) 1996-2002 Andrew G. Morgan &lt;morgan@kernel.org&gt;
+    </programlisting>
+    <para>
+      Redistribution and use in source and binary forms, with or without
+      modification, are permitted provided that the following conditions are
+      met:
+    </para>
+    <programlisting>
+1. Redistributions of source code must retain the above copyright
+   notice, and the entire permission notice in its entirety,
+   including the disclaimer of warranties.
+
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+3. The name of the author may not be used to endorse or promote
+   products derived from this software without specific prior
+   written permission.
+    </programlisting>
+    <para>
+      Alternatively, this product may be distributed under the terms of
+      the GNU General Public License (GPL), in which case the provisions
+      of the GNU GPL are required instead of the above restrictions.
+      (This clause is necessary due to a potential bad interaction between
+      the GNU GPL and the restrictions contained in a BSD-style copyright.)
+    </para>
+    <programlisting>
+THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
+TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
+USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+    </programlisting>
+  </chapter>
+</book>
diff --git a/doc/adg/Makefile.am b/doc/adg/Makefile.am
new file mode 100644
index 0000000..77bd7a9
--- /dev/null
+++ b/doc/adg/Makefile.am
@@ -0,0 +1,113 @@
+#
+# Copyright (c) 2006 Thorsten Kukuk <kukuk@thkukuk.de>
+#
+
+CLEANFILES = Linux-PAM_ADG.fo *~
+
+EXTRA_DIST = $(XMLS)
+
+XMLS = Linux-PAM_ADG.xml $(shell ls $(srcdir)/pam_*.xml)
+DEP_XMLS = $(shell ls $(top_srcdir)/doc/man/pam_*.xml)
+
+if ENABLE_REGENERATE_MAN
+MAINTAINERCLEANFILES = Linux-PAM_ADG.txt Linux-PAM_ADG.pdf html/*.html
+
+all: Linux-PAM_ADG.txt html/Linux-PAM_ADG.html Linux-PAM_ADG.pdf
+
+Linux-PAM_ADG.pdf: $(XMLS) $(DEP_XMLS)
+if ENABLE_GENERATE_PDF
+	$(XMLLINT) --nonet --xinclude --postvalid --noent --noout $<
+	$(XSLTPROC) --stringparam generate.toc "book toc" \
+	  --stringparam section.autolabel 1 \
+	  --stringparam section.label.includes.component.label 1 \
+	  --stringparam toc.max.depth 3 --xinclude --nonet \
+	http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl $< > Linux-PAM_ADG.fo
+	$(FO2PDF) Linux-PAM_ADG.fo $@
+else
+	echo "No fo2pdf processor installed, skip PDF generation"
+endif
+
+Linux-PAM_ADG.txt: $(XMLS) $(DEP_XMLS)
+	$(XMLLINT) --nonet --xinclude --postvalid --noent --noout $<
+	$(XSLTPROC) --stringparam generate.toc "book toc" \
+	  --stringparam section.autolabel 1 \
+	  --stringparam section.label.includes.component.label 1 \
+	  --stringparam toc.max.depth 3 --xinclude --nonet \
+	  http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl $< | $(BROWSER) > $@
+
+html/Linux-PAM_ADG.html: $(XMLS) $(DEP_XMLS)
+	@test -d html || mkdir -p html
+	$(XMLLINT) --nonet --xinclude --postvalid --noent --noout $<
+	$(XSLTPROC) --stringparam base.dir html/ \
+	  --stringparam root.filename Linux-PAM_ADG \
+	  --stringparam use.id.as.filename 1 \
+	  --stringparam chunk.first.sections 1 \
+	  --stringparam section.autolabel 1 \
+	  --stringparam section.label.includes.component.label 1 \
+	  --stringparam toc.max.depth 3 --xinclude --nonet \
+	  --stringparam chunker.output.encoding UTF-8 \
+	  http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl $<
+
+distclean-local:
+	-rm -rf html Linux-PAM_ADG.txt Linux-PAM_ADG.pdf
+
+endif
+
+install-data-local:
+	$(mkinstalldirs) $(DESTDIR)$(docdir)
+	$(mkinstalldirs) $(DESTDIR)$(pdfdir)
+	$(mkinstalldirs) $(DESTDIR)$(htmldir)
+	if test -f html/Linux-PAM_ADG.html; then \
+	    $(install_sh_DATA) html/Linux-PAM_ADG.html html/adg-*.html \
+		$(DESTDIR)$(htmldir)/; \
+	elif test -f $(srcdir)/html/Linux-PAM_ADG.html; then \
+	    $(install_sh_DATA) $(srcdir)/html/Linux-PAM_ADG.html \
+		$(srcdir)/html/adg-*.html \
+		$(DESTDIR)$(htmldir)/; \
+	fi
+	if test -f Linux-PAM_ADG.txt; then \
+	    $(install_sh_DATA) Linux-PAM_ADG.txt $(DESTDIR)$(docdir)/; \
+	elif test -f $(srcdir)/Linux-PAM_ADG.txt; then \
+	    $(install_sh_DATA) $(srcdir)/Linux-PAM_ADG.txt \
+		$(DESTDIR)$(docdir)/; \
+	fi
+	if test -f Linux-PAM_ADG.pdf; then \
+	    $(install_sh_DATA) Linux-PAM_ADG.pdf $(DESTDIR)$(pdfdir)/; \
+	elif test -f $(srcdir)/Linux-PAM_ADG.pdf; then \
+	    $(install_sh_DATA) $(srcdir)/Linux-PAM_ADG.pdf \
+		$(DESTDIR)$(pdfdir)/; \
+	fi
+
+uninstall-local:
+	-rm $(DESTDIR)$(htmldir)/Linux-PAM_ADG.html
+	-rm $(DESTDIR)$(htmldir)/adg-*.html
+	-rm $(DESTDIR)$(docdir)/Linux-PAM_ADG.txt
+	-rm $(DESTDIR)$(pdfdir)/Linux-PAM_ADG.pdf
+
+releasedocs: all
+	$(mkinstalldirs) $(top_builddir)/Linux-PAM-$(VERSION)/doc/adg/html
+	if test -f html/Linux-PAM_ADG.html; then \
+	    cp -ap html/Linux-PAM_ADG.html html/adg-*.html \
+		$(top_builddir)/Linux-PAM-$(VERSION)/doc/adg/html/; \
+	elif test -f $(srcdir)/html/Linux-PAM_ADG.html; then \
+	    cp -ap $(srcdir)/html/Linux-PAM_ADG.html \
+		$(srcdir)/html/adg-*.html \
+		$(top_builddir)/Linux-PAM-$(VERSION)/doc/adg/html/; \
+	else exit 1; \
+	fi
+	if test -f Linux-PAM_ADG.txt; then \
+	    cp -p Linux-PAM_ADG.txt \
+		$(top_builddir)/Linux-PAM-$(VERSION)/doc/adg/; \
+	elif test -f $(srcdir)/Linux-PAM_ADG.txt; then \
+	    cp -p $(srcdir)/Linux-PAM_ADG.txt \
+		$(top_builddir)/Linux-PAM-$(VERSION)/doc/adg/; \
+	else exit 1; \
+	fi
+	if test -f Linux-PAM_ADG.pdf; then \
+	    cp -p Linux-PAM_ADG.pdf \
+		$(top_builddir)/Linux-PAM-$(VERSION)/doc/adg/; \
+	elif test -f $(srcdir)/Linux-PAM_ADG.pdf; then \
+	    cp -p $(srcdir)/Linux-PAM_ADG.pdf \
+		$(top_builddir)/Linux-PAM-$(VERSION)/doc/adg/; \
+	else exit 1; \
+	fi
diff --git a/doc/adg/Makefile.in b/doc/adg/Makefile.in
new file mode 100644
index 0000000..194c8a0
--- /dev/null
+++ b/doc/adg/Makefile.in
@@ -0,0 +1,623 @@
+# Makefile.in generated by automake 1.16.3 from Makefile.am.
+# @configure_input@
+
+# Copyright (C) 1994-2020 Free Software Foundation, Inc.
+
+# This Makefile.in is free software; the Free Software Foundation
+# gives unlimited permission to copy and/or distribute it,
+# with or without modifications, as long as this notice is preserved.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE.
+
+@SET_MAKE@
+
+#
+# Copyright (c) 2006 Thorsten Kukuk <kukuk@thkukuk.de>
+#
+VPATH = @srcdir@
+am__is_gnu_make = { \
+  if test -z '$(MAKELEVEL)'; then \
+    false; \
+  elif test -n '$(MAKE_HOST)'; then \
+    true; \
+  elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \
+    true; \
+  else \
+    false; \
+  fi; \
+}
+am__make_running_with_option = \
+  case $${target_option-} in \
+      ?) ;; \
+      *) echo "am__make_running_with_option: internal error: invalid" \
+              "target option '$${target_option-}' specified" >&2; \
+         exit 1;; \
+  esac; \
+  has_opt=no; \
+  sane_makeflags=$$MAKEFLAGS; \
+  if $(am__is_gnu_make); then \
+    sane_makeflags=$$MFLAGS; \
+  else \
+    case $$MAKEFLAGS in \
+      *\\[\ \	]*) \
+        bs=\\; \
+        sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \
+          | sed "s/$$bs$$bs[$$bs $$bs	]*//g"`;; \
+    esac; \
+  fi; \
+  skip_next=no; \
+  strip_trailopt () \
+  { \
+    flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \
+  }; \
+  for flg in $$sane_makeflags; do \
+    test $$skip_next = yes && { skip_next=no; continue; }; \
+    case $$flg in \
+      *=*|--*) continue;; \
+        -*I) strip_trailopt 'I'; skip_next=yes;; \
+      -*I?*) strip_trailopt 'I';; \
+        -*O) strip_trailopt 'O'; skip_next=yes;; \
+      -*O?*) strip_trailopt 'O';; \
+        -*l) strip_trailopt 'l'; skip_next=yes;; \
+      -*l?*) strip_trailopt 'l';; \
+      -[dEDm]) skip_next=yes;; \
+      -[JT]) skip_next=yes;; \
+    esac; \
+    case $$flg in \
+      *$$target_option*) has_opt=yes; break;; \
+    esac; \
+  done; \
+  test $$has_opt = yes
+am__make_dryrun = (target_option=n; $(am__make_running_with_option))
+am__make_keepgoing = (target_option=k; $(am__make_running_with_option))
+pkgdatadir = $(datadir)/@PACKAGE@
+pkgincludedir = $(includedir)/@PACKAGE@
+pkglibdir = $(libdir)/@PACKAGE@
+pkglibexecdir = $(libexecdir)/@PACKAGE@
+am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
+install_sh_DATA = $(install_sh) -c -m 644
+install_sh_PROGRAM = $(install_sh) -c
+install_sh_SCRIPT = $(install_sh) -c
+INSTALL_HEADER = $(INSTALL_DATA)
+transform = $(program_transform_name)
+NORMAL_INSTALL = :
+PRE_INSTALL = :
+POST_INSTALL = :
+NORMAL_UNINSTALL = :
+PRE_UNINSTALL = :
+POST_UNINSTALL = :
+build_triplet = @build@
+host_triplet = @host@
+subdir = doc/adg
+ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
+am__aclocal_m4_deps = $(top_srcdir)/m4/attribute.m4 \
+	$(top_srcdir)/m4/gettext.m4 $(top_srcdir)/m4/iconv.m4 \
+	$(top_srcdir)/m4/intlmacosx.m4 \
+	$(top_srcdir)/m4/jh_path_xml_catalog.m4 \
+	$(top_srcdir)/m4/ld-O1.m4 $(top_srcdir)/m4/ld-as-needed.m4 \
+	$(top_srcdir)/m4/ld-no-undefined.m4 \
+	$(top_srcdir)/m4/ld-z-now.m4 $(top_srcdir)/m4/lib-ld.m4 \
+	$(top_srcdir)/m4/lib-link.m4 $(top_srcdir)/m4/lib-prefix.m4 \
+	$(top_srcdir)/m4/libprelude.m4 $(top_srcdir)/m4/libtool.m4 \
+	$(top_srcdir)/m4/ltoptions.m4 $(top_srcdir)/m4/ltsugar.m4 \
+	$(top_srcdir)/m4/ltversion.m4 $(top_srcdir)/m4/lt~obsolete.m4 \
+	$(top_srcdir)/m4/nls.m4 $(top_srcdir)/m4/po.m4 \
+	$(top_srcdir)/m4/progtest.m4 \
+	$(top_srcdir)/m4/warn_lang_flags.m4 \
+	$(top_srcdir)/m4/warnings.m4 $(top_srcdir)/configure.ac
+am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
+	$(ACLOCAL_M4)
+DIST_COMMON = $(srcdir)/Makefile.am $(am__DIST_COMMON)
+mkinstalldirs = $(install_sh) -d
+CONFIG_HEADER = $(top_builddir)/config.h
+CONFIG_CLEAN_FILES =
+CONFIG_CLEAN_VPATH_FILES =
+AM_V_P = $(am__v_P_@AM_V@)
+am__v_P_ = $(am__v_P_@AM_DEFAULT_V@)
+am__v_P_0 = false
+am__v_P_1 = :
+AM_V_GEN = $(am__v_GEN_@AM_V@)
+am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@)
+am__v_GEN_0 = @echo "  GEN     " $@;
+am__v_GEN_1 = 
+AM_V_at = $(am__v_at_@AM_V@)
+am__v_at_ = $(am__v_at_@AM_DEFAULT_V@)
+am__v_at_0 = @
+am__v_at_1 = 
+SOURCES =
+DIST_SOURCES =
+am__can_run_installinfo = \
+  case $$AM_UPDATE_INFO_DIR in \
+    n|no|NO) false;; \
+    *) (install-info --version) >/dev/null 2>&1;; \
+  esac
+am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
+am__DIST_COMMON = $(srcdir)/Makefile.in
+DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
+ACLOCAL = @ACLOCAL@
+AMTAR = @AMTAR@
+AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@
+AR = @AR@
+AUTOCONF = @AUTOCONF@
+AUTOHEADER = @AUTOHEADER@
+AUTOMAKE = @AUTOMAKE@
+AWK = @AWK@
+BROWSER = @BROWSER@
+BUILD_CFLAGS = @BUILD_CFLAGS@
+BUILD_CPPFLAGS = @BUILD_CPPFLAGS@
+BUILD_LDFLAGS = @BUILD_LDFLAGS@
+CC = @CC@
+CCDEPMODE = @CCDEPMODE@
+CC_FOR_BUILD = @CC_FOR_BUILD@
+CFLAGS = @CFLAGS@
+CPP = @CPP@
+CPPFLAGS = @CPPFLAGS@
+CRYPTO_LIBS = @CRYPTO_LIBS@
+CRYPT_CFLAGS = @CRYPT_CFLAGS@
+CRYPT_LIBS = @CRYPT_LIBS@
+CYGPATH_W = @CYGPATH_W@
+DEFS = @DEFS@
+DEPDIR = @DEPDIR@
+DLLTOOL = @DLLTOOL@
+DSYMUTIL = @DSYMUTIL@
+DUMPBIN = @DUMPBIN@
+ECHO_C = @ECHO_C@
+ECHO_N = @ECHO_N@
+ECHO_T = @ECHO_T@
+ECONF_CFLAGS = @ECONF_CFLAGS@
+ECONF_LIBS = @ECONF_LIBS@
+EGREP = @EGREP@
+EXEEXT = @EXEEXT@
+EXE_CFLAGS = @EXE_CFLAGS@
+EXE_LDFLAGS = @EXE_LDFLAGS@
+FGREP = @FGREP@
+FO2PDF = @FO2PDF@
+GETTEXT_MACRO_VERSION = @GETTEXT_MACRO_VERSION@
+GMSGFMT = @GMSGFMT@
+GMSGFMT_015 = @GMSGFMT_015@
+GREP = @GREP@
+INSTALL = @INSTALL@
+INSTALL_DATA = @INSTALL_DATA@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
+INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
+INTLLIBS = @INTLLIBS@
+INTL_MACOSX_LIBS = @INTL_MACOSX_LIBS@
+LD = @LD@
+LDFLAGS = @LDFLAGS@
+LEX = @LEX@
+LEXLIB = @LEXLIB@
+LEX_OUTPUT_ROOT = @LEX_OUTPUT_ROOT@
+LIBAUDIT = @LIBAUDIT@
+LIBCRYPT = @LIBCRYPT@
+LIBDB = @LIBDB@
+LIBDL = @LIBDL@
+LIBICONV = @LIBICONV@
+LIBINTL = @LIBINTL@
+LIBOBJS = @LIBOBJS@
+LIBPRELUDE_CFLAGS = @LIBPRELUDE_CFLAGS@
+LIBPRELUDE_CONFIG = @LIBPRELUDE_CONFIG@
+LIBPRELUDE_CONFIG_PREFIX = @LIBPRELUDE_CONFIG_PREFIX@
+LIBPRELUDE_LDFLAGS = @LIBPRELUDE_LDFLAGS@
+LIBPRELUDE_LIBS = @LIBPRELUDE_LIBS@
+LIBPRELUDE_PREFIX = @LIBPRELUDE_PREFIX@
+LIBPRELUDE_PTHREAD_CFLAGS = @LIBPRELUDE_PTHREAD_CFLAGS@
+LIBS = @LIBS@
+LIBSELINUX = @LIBSELINUX@
+LIBTOOL = @LIBTOOL@
+LIPO = @LIPO@
+LN_S = @LN_S@
+LTLIBICONV = @LTLIBICONV@
+LTLIBINTL = @LTLIBINTL@
+LTLIBOBJS = @LTLIBOBJS@
+LT_SYS_LIBRARY_PATH = @LT_SYS_LIBRARY_PATH@
+MAKEINFO = @MAKEINFO@
+MANIFEST_TOOL = @MANIFEST_TOOL@
+MKDIR_P = @MKDIR_P@
+MSGFMT = @MSGFMT@
+MSGFMT_015 = @MSGFMT_015@
+MSGMERGE = @MSGMERGE@
+NIS_CFLAGS = @NIS_CFLAGS@
+NIS_LIBS = @NIS_LIBS@
+NM = @NM@
+NMEDIT = @NMEDIT@
+NSL_CFLAGS = @NSL_CFLAGS@
+NSL_LIBS = @NSL_LIBS@
+OBJDUMP = @OBJDUMP@
+OBJEXT = @OBJEXT@
+OTOOL = @OTOOL@
+OTOOL64 = @OTOOL64@
+PACKAGE = @PACKAGE@
+PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
+PACKAGE_NAME = @PACKAGE_NAME@
+PACKAGE_STRING = @PACKAGE_STRING@
+PACKAGE_TARNAME = @PACKAGE_TARNAME@
+PACKAGE_URL = @PACKAGE_URL@
+PACKAGE_VERSION = @PACKAGE_VERSION@
+PATH_SEPARATOR = @PATH_SEPARATOR@
+PKG_CONFIG = @PKG_CONFIG@
+PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@
+PKG_CONFIG_PATH = @PKG_CONFIG_PATH@
+POSUB = @POSUB@
+RANLIB = @RANLIB@
+SCONFIGDIR = @SCONFIGDIR@
+SECUREDIR = @SECUREDIR@
+SED = @SED@
+SET_MAKE = @SET_MAKE@
+SHELL = @SHELL@
+STRINGPARAM_HMAC = @STRINGPARAM_HMAC@
+STRINGPARAM_VENDORDIR = @STRINGPARAM_VENDORDIR@
+STRIP = @STRIP@
+TIRPC_CFLAGS = @TIRPC_CFLAGS@
+TIRPC_LIBS = @TIRPC_LIBS@
+USE_NLS = @USE_NLS@
+VERSION = @VERSION@
+WARN_CFLAGS = @WARN_CFLAGS@
+XGETTEXT = @XGETTEXT@
+XGETTEXT_015 = @XGETTEXT_015@
+XGETTEXT_EXTRA_OPTIONS = @XGETTEXT_EXTRA_OPTIONS@
+XMLCATALOG = @XMLCATALOG@
+XMLLINT = @XMLLINT@
+XML_CATALOG_FILE = @XML_CATALOG_FILE@
+XSLTPROC = @XSLTPROC@
+YACC = @YACC@
+YFLAGS = @YFLAGS@
+abs_builddir = @abs_builddir@
+abs_srcdir = @abs_srcdir@
+abs_top_builddir = @abs_top_builddir@
+abs_top_srcdir = @abs_top_srcdir@
+ac_ct_AR = @ac_ct_AR@
+ac_ct_CC = @ac_ct_CC@
+ac_ct_DUMPBIN = @ac_ct_DUMPBIN@
+am__include = @am__include@
+am__leading_dot = @am__leading_dot@
+am__quote = @am__quote@
+am__tar = @am__tar@
+am__untar = @am__untar@
+bindir = @bindir@
+build = @build@
+build_alias = @build_alias@
+build_cpu = @build_cpu@
+build_os = @build_os@
+build_vendor = @build_vendor@
+builddir = @builddir@
+datadir = @datadir@
+datarootdir = @datarootdir@
+docdir = @docdir@
+dvidir = @dvidir@
+exec_prefix = @exec_prefix@
+host = @host@
+host_alias = @host_alias@
+host_cpu = @host_cpu@
+host_os = @host_os@
+host_vendor = @host_vendor@
+htmldir = @htmldir@
+includedir = @includedir@
+infodir = @infodir@
+install_sh = @install_sh@
+libdir = @libdir@
+libexecdir = @libexecdir@
+localedir = @localedir@
+localstatedir = @localstatedir@
+mandir = @mandir@
+mkdir_p = @mkdir_p@
+oldincludedir = @oldincludedir@
+pam_xauth_path = @pam_xauth_path@
+pdfdir = @pdfdir@
+prefix = @prefix@
+program_transform_name = @program_transform_name@
+psdir = @psdir@
+sbindir = @sbindir@
+sharedstatedir = @sharedstatedir@
+srcdir = @srcdir@
+sysconfdir = @sysconfdir@
+systemdunitdir = @systemdunitdir@
+target_alias = @target_alias@
+top_build_prefix = @top_build_prefix@
+top_builddir = @top_builddir@
+top_srcdir = @top_srcdir@
+CLEANFILES = Linux-PAM_ADG.fo *~
+EXTRA_DIST = $(XMLS)
+XMLS = Linux-PAM_ADG.xml $(shell ls $(srcdir)/pam_*.xml)
+DEP_XMLS = $(shell ls $(top_srcdir)/doc/man/pam_*.xml)
+@ENABLE_REGENERATE_MAN_TRUE@MAINTAINERCLEANFILES = Linux-PAM_ADG.txt Linux-PAM_ADG.pdf html/*.html
+all: all-am
+
+.SUFFIXES:
+$(srcdir)/Makefile.in:  $(srcdir)/Makefile.am  $(am__configure_deps)
+	@for dep in $?; do \
+	  case '$(am__configure_deps)' in \
+	    *$$dep*) \
+	      ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \
+	        && { if test -f $@; then exit 0; else break; fi; }; \
+	      exit 1;; \
+	  esac; \
+	done; \
+	echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/adg/Makefile'; \
+	$(am__cd) $(top_srcdir) && \
+	  $(AUTOMAKE) --gnu doc/adg/Makefile
+Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
+	@case '$?' in \
+	  *config.status*) \
+	    cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \
+	  *) \
+	    echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles)'; \
+	    cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles);; \
+	esac;
+
+$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
+	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+
+$(top_srcdir)/configure:  $(am__configure_deps)
+	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(ACLOCAL_M4):  $(am__aclocal_m4_deps)
+	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(am__aclocal_m4_deps):
+
+mostlyclean-libtool:
+	-rm -f *.lo
+
+clean-libtool:
+	-rm -rf .libs _libs
+tags TAGS:
+
+ctags CTAGS:
+
+cscope cscopelist:
+
+
+distdir: $(BUILT_SOURCES)
+	$(MAKE) $(AM_MAKEFLAGS) distdir-am
+
+distdir-am: $(DISTFILES)
+	@srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+	topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+	list='$(DISTFILES)'; \
+	  dist_files=`for file in $$list; do echo $$file; done | \
+	  sed -e "s|^$$srcdirstrip/||;t" \
+	      -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \
+	case $$dist_files in \
+	  */*) $(MKDIR_P) `echo "$$dist_files" | \
+			   sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \
+			   sort -u` ;; \
+	esac; \
+	for file in $$dist_files; do \
+	  if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
+	  if test -d $$d/$$file; then \
+	    dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \
+	    if test -d "$(distdir)/$$file"; then \
+	      find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
+	    fi; \
+	    if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
+	      cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \
+	      find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
+	    fi; \
+	    cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \
+	  else \
+	    test -f "$(distdir)/$$file" \
+	    || cp -p $$d/$$file "$(distdir)/$$file" \
+	    || exit 1; \
+	  fi; \
+	done
+check-am: all-am
+check: check-am
+all-am: Makefile
+installdirs:
+install: install-am
+install-exec: install-exec-am
+install-data: install-data-am
+uninstall: uninstall-am
+
+install-am: all-am
+	@$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+
+installcheck: installcheck-am
+install-strip:
+	if test -z '$(STRIP)'; then \
+	  $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+	    install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+	      install; \
+	else \
+	  $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+	    install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+	    "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \
+	fi
+mostlyclean-generic:
+
+clean-generic:
+	-test -z "$(CLEANFILES)" || rm -f $(CLEANFILES)
+
+distclean-generic:
+	-test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
+	-test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES)
+
+maintainer-clean-generic:
+	@echo "This command is intended for maintainers to use"
+	@echo "it deletes files that may require special tools to rebuild."
+	-test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES)
+@ENABLE_REGENERATE_MAN_FALSE@distclean-local:
+clean: clean-am
+
+clean-am: clean-generic clean-libtool mostlyclean-am
+
+distclean: distclean-am
+	-rm -f Makefile
+distclean-am: clean-am distclean-generic distclean-local
+
+dvi: dvi-am
+
+dvi-am:
+
+html: html-am
+
+html-am:
+
+info: info-am
+
+info-am:
+
+install-data-am: install-data-local
+
+install-dvi: install-dvi-am
+
+install-dvi-am:
+
+install-exec-am:
+
+install-html: install-html-am
+
+install-html-am:
+
+install-info: install-info-am
+
+install-info-am:
+
+install-man:
+
+install-pdf: install-pdf-am
+
+install-pdf-am:
+
+install-ps: install-ps-am
+
+install-ps-am:
+
+installcheck-am:
+
+maintainer-clean: maintainer-clean-am
+	-rm -f Makefile
+maintainer-clean-am: distclean-am maintainer-clean-generic
+
+mostlyclean: mostlyclean-am
+
+mostlyclean-am: mostlyclean-generic mostlyclean-libtool
+
+pdf: pdf-am
+
+pdf-am:
+
+ps: ps-am
+
+ps-am:
+
+uninstall-am: uninstall-local
+
+.MAKE: install-am install-strip
+
+.PHONY: all all-am check check-am clean clean-generic clean-libtool \
+	cscopelist-am ctags-am distclean distclean-generic \
+	distclean-libtool distclean-local distdir dvi dvi-am html \
+	html-am info info-am install install-am install-data \
+	install-data-am install-data-local install-dvi install-dvi-am \
+	install-exec install-exec-am install-html install-html-am \
+	install-info install-info-am install-man install-pdf \
+	install-pdf-am install-ps install-ps-am install-strip \
+	installcheck installcheck-am installdirs maintainer-clean \
+	maintainer-clean-generic mostlyclean mostlyclean-generic \
+	mostlyclean-libtool pdf pdf-am ps ps-am tags-am uninstall \
+	uninstall-am uninstall-local
+
+.PRECIOUS: Makefile
+
+
+@ENABLE_REGENERATE_MAN_TRUE@all: Linux-PAM_ADG.txt html/Linux-PAM_ADG.html Linux-PAM_ADG.pdf
+
+@ENABLE_REGENERATE_MAN_TRUE@Linux-PAM_ADG.pdf: $(XMLS) $(DEP_XMLS)
+@ENABLE_GENERATE_PDF_TRUE@@ENABLE_REGENERATE_MAN_TRUE@	$(XMLLINT) --nonet --xinclude --postvalid --noent --noout $<
+@ENABLE_GENERATE_PDF_TRUE@@ENABLE_REGENERATE_MAN_TRUE@	$(XSLTPROC) --stringparam generate.toc "book toc" \
+@ENABLE_GENERATE_PDF_TRUE@@ENABLE_REGENERATE_MAN_TRUE@	  --stringparam section.autolabel 1 \
+@ENABLE_GENERATE_PDF_TRUE@@ENABLE_REGENERATE_MAN_TRUE@	  --stringparam section.label.includes.component.label 1 \
+@ENABLE_GENERATE_PDF_TRUE@@ENABLE_REGENERATE_MAN_TRUE@	  --stringparam toc.max.depth 3 --xinclude --nonet \
+@ENABLE_GENERATE_PDF_TRUE@@ENABLE_REGENERATE_MAN_TRUE@	http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl $< > Linux-PAM_ADG.fo
+@ENABLE_GENERATE_PDF_TRUE@@ENABLE_REGENERATE_MAN_TRUE@	$(FO2PDF) Linux-PAM_ADG.fo $@
+@ENABLE_GENERATE_PDF_FALSE@@ENABLE_REGENERATE_MAN_TRUE@	echo "No fo2pdf processor installed, skip PDF generation"
+
+@ENABLE_REGENERATE_MAN_TRUE@Linux-PAM_ADG.txt: $(XMLS) $(DEP_XMLS)
+@ENABLE_REGENERATE_MAN_TRUE@	$(XMLLINT) --nonet --xinclude --postvalid --noent --noout $<
+@ENABLE_REGENERATE_MAN_TRUE@	$(XSLTPROC) --stringparam generate.toc "book toc" \
+@ENABLE_REGENERATE_MAN_TRUE@	  --stringparam section.autolabel 1 \
+@ENABLE_REGENERATE_MAN_TRUE@	  --stringparam section.label.includes.component.label 1 \
+@ENABLE_REGENERATE_MAN_TRUE@	  --stringparam toc.max.depth 3 --xinclude --nonet \
+@ENABLE_REGENERATE_MAN_TRUE@	  http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl $< | $(BROWSER) > $@
+
+@ENABLE_REGENERATE_MAN_TRUE@html/Linux-PAM_ADG.html: $(XMLS) $(DEP_XMLS)
+@ENABLE_REGENERATE_MAN_TRUE@	@test -d html || mkdir -p html
+@ENABLE_REGENERATE_MAN_TRUE@	$(XMLLINT) --nonet --xinclude --postvalid --noent --noout $<
+@ENABLE_REGENERATE_MAN_TRUE@	$(XSLTPROC) --stringparam base.dir html/ \
+@ENABLE_REGENERATE_MAN_TRUE@	  --stringparam root.filename Linux-PAM_ADG \
+@ENABLE_REGENERATE_MAN_TRUE@	  --stringparam use.id.as.filename 1 \
+@ENABLE_REGENERATE_MAN_TRUE@	  --stringparam chunk.first.sections 1 \
+@ENABLE_REGENERATE_MAN_TRUE@	  --stringparam section.autolabel 1 \
+@ENABLE_REGENERATE_MAN_TRUE@	  --stringparam section.label.includes.component.label 1 \
+@ENABLE_REGENERATE_MAN_TRUE@	  --stringparam toc.max.depth 3 --xinclude --nonet \
+@ENABLE_REGENERATE_MAN_TRUE@	  --stringparam chunker.output.encoding UTF-8 \
+@ENABLE_REGENERATE_MAN_TRUE@	  http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl $<
+
+@ENABLE_REGENERATE_MAN_TRUE@distclean-local:
+@ENABLE_REGENERATE_MAN_TRUE@	-rm -rf html Linux-PAM_ADG.txt Linux-PAM_ADG.pdf
+
+install-data-local:
+	$(mkinstalldirs) $(DESTDIR)$(docdir)
+	$(mkinstalldirs) $(DESTDIR)$(pdfdir)
+	$(mkinstalldirs) $(DESTDIR)$(htmldir)
+	if test -f html/Linux-PAM_ADG.html; then \
+	    $(install_sh_DATA) html/Linux-PAM_ADG.html html/adg-*.html \
+		$(DESTDIR)$(htmldir)/; \
+	elif test -f $(srcdir)/html/Linux-PAM_ADG.html; then \
+	    $(install_sh_DATA) $(srcdir)/html/Linux-PAM_ADG.html \
+		$(srcdir)/html/adg-*.html \
+		$(DESTDIR)$(htmldir)/; \
+	fi
+	if test -f Linux-PAM_ADG.txt; then \
+	    $(install_sh_DATA) Linux-PAM_ADG.txt $(DESTDIR)$(docdir)/; \
+	elif test -f $(srcdir)/Linux-PAM_ADG.txt; then \
+	    $(install_sh_DATA) $(srcdir)/Linux-PAM_ADG.txt \
+		$(DESTDIR)$(docdir)/; \
+	fi
+	if test -f Linux-PAM_ADG.pdf; then \
+	    $(install_sh_DATA) Linux-PAM_ADG.pdf $(DESTDIR)$(pdfdir)/; \
+	elif test -f $(srcdir)/Linux-PAM_ADG.pdf; then \
+	    $(install_sh_DATA) $(srcdir)/Linux-PAM_ADG.pdf \
+		$(DESTDIR)$(pdfdir)/; \
+	fi
+
+uninstall-local:
+	-rm $(DESTDIR)$(htmldir)/Linux-PAM_ADG.html
+	-rm $(DESTDIR)$(htmldir)/adg-*.html
+	-rm $(DESTDIR)$(docdir)/Linux-PAM_ADG.txt
+	-rm $(DESTDIR)$(pdfdir)/Linux-PAM_ADG.pdf
+
+releasedocs: all
+	$(mkinstalldirs) $(top_builddir)/Linux-PAM-$(VERSION)/doc/adg/html
+	if test -f html/Linux-PAM_ADG.html; then \
+	    cp -ap html/Linux-PAM_ADG.html html/adg-*.html \
+		$(top_builddir)/Linux-PAM-$(VERSION)/doc/adg/html/; \
+	elif test -f $(srcdir)/html/Linux-PAM_ADG.html; then \
+	    cp -ap $(srcdir)/html/Linux-PAM_ADG.html \
+		$(srcdir)/html/adg-*.html \
+		$(top_builddir)/Linux-PAM-$(VERSION)/doc/adg/html/; \
+	else exit 1; \
+	fi
+	if test -f Linux-PAM_ADG.txt; then \
+	    cp -p Linux-PAM_ADG.txt \
+		$(top_builddir)/Linux-PAM-$(VERSION)/doc/adg/; \
+	elif test -f $(srcdir)/Linux-PAM_ADG.txt; then \
+	    cp -p $(srcdir)/Linux-PAM_ADG.txt \
+		$(top_builddir)/Linux-PAM-$(VERSION)/doc/adg/; \
+	else exit 1; \
+	fi
+	if test -f Linux-PAM_ADG.pdf; then \
+	    cp -p Linux-PAM_ADG.pdf \
+		$(top_builddir)/Linux-PAM-$(VERSION)/doc/adg/; \
+	elif test -f $(srcdir)/Linux-PAM_ADG.pdf; then \
+	    cp -p $(srcdir)/Linux-PAM_ADG.pdf \
+		$(top_builddir)/Linux-PAM-$(VERSION)/doc/adg/; \
+	else exit 1; \
+	fi
+
+# Tell versions [3.59,3.63) of GNU make to not export all variables.
+# Otherwise a system limit (for SysV at least) may be exceeded.
+.NOEXPORT:
diff --git a/doc/adg/pam_acct_mgmt.xml b/doc/adg/pam_acct_mgmt.xml
new file mode 100644
index 0000000..6a3a37d
--- /dev/null
+++ b/doc/adg/pam_acct_mgmt.xml
@@ -0,0 +1,18 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<section id='adg-pam_acct_mgmt'>
+  <title>Account validation management</title>
+  <funcsynopsis>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_acct_mgmt.3.xml" xpointer='xpointer(//funcsynopsis[@id = "pam_acct_mgmt-synopsis"]/*)'/>
+  </funcsynopsis>
+  <section id='adg-pam_acct_mgmt-description'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_acct_mgmt.3.xml" xpointer='xpointer(//refsect1[@id = "pam_acct_mgmt-description"]/*)'/>
+  </section>
+  <section id='adg-pam_acct_mgmt-return_values'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_acct_mgmt.3.xml" xpointer='xpointer(//refsect1[@id = "pam_acct_mgmt-return_values"]/*)'/>
+  </section>
+</section>
diff --git a/doc/adg/pam_authenticate.xml b/doc/adg/pam_authenticate.xml
new file mode 100644
index 0000000..2ca9b54
--- /dev/null
+++ b/doc/adg/pam_authenticate.xml
@@ -0,0 +1,18 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<section id='adg-pam_authenticate'>
+  <title>Authenticating the user</title>
+  <funcsynopsis>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_authenticate.3.xml" xpointer='xpointer(//funcsynopsis[@id = "pam_authenticate-synopsis"]/*)'/>
+  </funcsynopsis>
+  <section id='adg-pam_authenticate-description'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_authenticate.3.xml" xpointer='xpointer(//refsect1[@id = "pam_authenticate-description"]/*)'/>
+  </section>
+  <section id='adg-pam_authenticate-return_values'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_authenticate.3.xml" xpointer='xpointer(//refsect1[@id = "pam_authenticate-return_values"]/*)'/>
+  </section>
+</section>
diff --git a/doc/adg/pam_chauthtok.xml b/doc/adg/pam_chauthtok.xml
new file mode 100644
index 0000000..1c613da
--- /dev/null
+++ b/doc/adg/pam_chauthtok.xml
@@ -0,0 +1,18 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<section id='adg-pam_chauthtok'>
+  <title>Updating authentication tokens</title>
+  <funcsynopsis>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_chauthtok.3.xml" xpointer='xpointer(//funcsynopsis[@id = "pam_chauthtok-synopsis"]/*)'/>
+  </funcsynopsis>
+  <section id='adg-pam_chauthtok-description'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_chauthtok.3.xml" xpointer='xpointer(//refsect1[@id = "pam_chauthtok-description"]/*)'/>
+  </section>
+  <section id='adg-pam_chauthtok-return_values'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_chauthtok.3.xml" xpointer='xpointer(//refsect1[@id = "pam_chauthtok-return_values"]/*)'/>
+  </section>
+</section>
diff --git a/doc/adg/pam_close_session.xml b/doc/adg/pam_close_session.xml
new file mode 100644
index 0000000..4b93fc3
--- /dev/null
+++ b/doc/adg/pam_close_session.xml
@@ -0,0 +1,18 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<section id='adg-pam_close_session'>
+  <title>terminating PAM session management</title>
+  <funcsynopsis>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_close_session.3.xml" xpointer='xpointer(//funcsynopsis[@id = "pam_close_session-synopsis"]/*)'/>
+  </funcsynopsis>
+  <section id='adg-pam_close_session-description'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_close_session.3.xml" xpointer='xpointer(//refsect1[@id = "pam_close_session-description"]/*)'/>
+  </section>
+  <section id='adg-pam_close_session-return_values'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_close_session.3.xml" xpointer='xpointer(//refsect1[@id = "pam_close_session-return_values"]/*)'/>
+  </section>
+</section>
diff --git a/doc/adg/pam_conv.xml b/doc/adg/pam_conv.xml
new file mode 100644
index 0000000..01b7512
--- /dev/null
+++ b/doc/adg/pam_conv.xml
@@ -0,0 +1,35 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<section id='adg-pam_conv'>
+  <title>The conversation function</title>
+  <funcsynopsis>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_conv.3.xml" xpointer='xpointer(//funcsynopsis[@id = "pam_conv-synopsis"]/*)'/>
+  </funcsynopsis>
+  <programlisting>
+struct pam_message {
+    int msg_style;
+    const char *msg;
+};
+
+struct pam_response {
+    char *resp;
+    int resp_retcode;
+};
+
+struct pam_conv {
+    int (*conv)(int num_msg, const struct pam_message **msg,
+                struct pam_response **resp, void *appdata_ptr);
+    void *appdata_ptr;
+};
+  </programlisting>
+  <section id='adg-pam_conv-description'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_conv.3.xml" xpointer='xpointer(//refsect1[@id = "pam_conv-description"]/*)'/>
+  </section>
+  <section id='adg-pam_conv-return_values'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_conv.3.xml" xpointer='xpointer(//refsect1[@id = "pam_conv-return_values"]/*)'/>
+  </section>
+</section>
diff --git a/doc/adg/pam_end.xml b/doc/adg/pam_end.xml
new file mode 100644
index 0000000..efa328b
--- /dev/null
+++ b/doc/adg/pam_end.xml
@@ -0,0 +1,18 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<section id='adg-pam_end'>
+  <title>Termination of PAM transaction</title>
+  <funcsynopsis>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_end.3.xml" xpointer='xpointer(//funcsynopsis[@id = "pam_end-synopsis"]/*)'/>
+  </funcsynopsis>
+  <section id='adg-pam_end-description'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_end.3.xml" xpointer='xpointer(//refsect1[@id = "pam_end-description"]/*)'/>
+  </section>
+  <section id='adg-pam_end-return_values'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_end.3.xml" xpointer='xpointer(//refsect1[@id = "pam_end-return_values"]/*)'/>
+  </section>
+</section>
diff --git a/doc/adg/pam_fail_delay.xml b/doc/adg/pam_fail_delay.xml
new file mode 100644
index 0000000..589e114
--- /dev/null
+++ b/doc/adg/pam_fail_delay.xml
@@ -0,0 +1,18 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<section id='adg-pam_fail_delay'>
+  <title>Request a delay on failure</title>
+  <funcsynopsis>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_fail_delay.3.xml" xpointer='xpointer(//funcsynopsis[@id = "pam_fail_delay-synopsis"]/*)'/>
+  </funcsynopsis>
+  <section id='adg-pam_fail_delay-description'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_fail_delay.3.xml" xpointer='xpointer(//refsect1[@id = "pam_fail_delay-description"]/*)'/>
+  </section>
+  <section id='adg-pam_fail_delay-return_values'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_fail_delay.3.xml" xpointer='xpointer(//refsect1[@id = "pam_fail_delay-return_values"]/*)'/>
+  </section>
+</section>
diff --git a/doc/adg/pam_get_item.xml b/doc/adg/pam_get_item.xml
new file mode 100644
index 0000000..f23c734
--- /dev/null
+++ b/doc/adg/pam_get_item.xml
@@ -0,0 +1,18 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<section id='adg-pam_get_item'>
+  <title>Getting PAM items</title>
+  <funcsynopsis>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_get_item.3.xml" xpointer='xpointer(//funcsynopsis[@id = "pam_get_item-synopsis"]/*)'/>
+  </funcsynopsis>
+  <section id='adg-pam_get_item-description'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_get_item.3.xml" xpointer='xpointer(//refsect1[@id = "pam_get_item-description"]/*)'/>
+  </section>
+  <section id='adg-pam_get_item-return_values'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_get_item.3.xml" xpointer='xpointer(//refsect1[@id = "pam_get_item-return_values"]/*)'/>
+  </section>
+</section>
diff --git a/doc/adg/pam_getenv.xml b/doc/adg/pam_getenv.xml
new file mode 100644
index 0000000..61d69c3
--- /dev/null
+++ b/doc/adg/pam_getenv.xml
@@ -0,0 +1,18 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<section id='adg-pam_getenv'>
+  <title>Get a PAM environment variable</title>
+  <funcsynopsis>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_getenv.3.xml" xpointer='xpointer(//funcsynopsis[@id = "pam_getenv-synopsis"]/*)'/>
+  </funcsynopsis>
+  <section id='adg-pam_getenv-description'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_getenv.3.xml" xpointer='xpointer(//refsect1[@id = "pam_getenv-description"]/*)'/>
+  </section>
+  <section id='adg-pam_getenv-return_values'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_getenv.3.xml" xpointer='xpointer(//refsect1[@id = "pam_getenv-return_values"]/*)'/>
+  </section>
+</section>
diff --git a/doc/adg/pam_getenvlist.xml b/doc/adg/pam_getenvlist.xml
new file mode 100644
index 0000000..d3c2fcd
--- /dev/null
+++ b/doc/adg/pam_getenvlist.xml
@@ -0,0 +1,18 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<section id='adg-pam_getenvlist'>
+  <title>Getting the PAM environment</title>
+  <funcsynopsis>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_getenvlist.3.xml" xpointer='xpointer(//funcsynopsis[@id = "pam_getenvlist-synopsis"]/*)'/>
+  </funcsynopsis>
+  <section id='adg-pam_getenvlist-description'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_getenvlist.3.xml" xpointer='xpointer(//refsect1[@id = "pam_getenvlist-description"]/*)'/>
+  </section>
+  <section id='adg-pam_getenvlist-return_values'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_getenvlist.3.xml" xpointer='xpointer(//refsect1[@id = "pam_getenvlist-return_values"]/*)'/>
+  </section>
+</section>
diff --git a/doc/adg/pam_misc_conv.xml b/doc/adg/pam_misc_conv.xml
new file mode 100644
index 0000000..2dc760c
--- /dev/null
+++ b/doc/adg/pam_misc_conv.xml
@@ -0,0 +1,14 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<section id='adg-misc_conv'>
+  <title>Text based conversation function</title>
+  <funcsynopsis>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/misc_conv.3.xml" xpointer='xpointer(//funcsynopsis[@id = "misc_conv-synopsis"]/*)'/>
+  </funcsynopsis>
+  <section id='adg-misc_conv-description'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/misc_conv.3.xml" xpointer='xpointer(//refsect1[@id = "misc_conv-description"]/*)'/>
+  </section>
+</section>
diff --git a/doc/adg/pam_misc_drop_env.xml b/doc/adg/pam_misc_drop_env.xml
new file mode 100644
index 0000000..956d481
--- /dev/null
+++ b/doc/adg/pam_misc_drop_env.xml
@@ -0,0 +1,14 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<section id='adg-pam_misc_drop_env'>
+  <title>Liberating a locally saved environment</title>
+  <funcsynopsis>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_misc_drop_env.3.xml" xpointer='xpointer(//funcsynopsis[@id = "pam_misc_drop_env-synopsis"]/*)'/>
+  </funcsynopsis>
+  <section id='adg-pam_misc_drop_env-description'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_misc_drop_env.3.xml" xpointer='xpointer(//refsect1[@id = "pam_misc_drop_env-description"]/*)'/>
+  </section>
+</section>
diff --git a/doc/adg/pam_misc_paste_env.xml b/doc/adg/pam_misc_paste_env.xml
new file mode 100644
index 0000000..c6d3856
--- /dev/null
+++ b/doc/adg/pam_misc_paste_env.xml
@@ -0,0 +1,14 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<section id='adg-pam_misc_paste_env'>
+  <title>Transcribing an environment to that of PAM</title>
+  <funcsynopsis>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_misc_paste_env.3.xml" xpointer='xpointer(//funcsynopsis[@id = "pam_misc_paste_env-synopsis"]/*)'/>
+  </funcsynopsis>
+  <section id='adg-pam_misc_paste_env-description'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_misc_paste_env.3.xml" xpointer='xpointer(//refsect1[@id = "pam_misc_paste_env-description"]/*)'/>
+  </section>
+</section>
diff --git a/doc/adg/pam_misc_setenv.xml b/doc/adg/pam_misc_setenv.xml
new file mode 100644
index 0000000..3b1a32e
--- /dev/null
+++ b/doc/adg/pam_misc_setenv.xml
@@ -0,0 +1,14 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<section id='adg-pam_misc_setenv'>
+  <title>BSD like PAM environment variable setting</title>
+  <funcsynopsis>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_misc_setenv.3.xml" xpointer='xpointer(//funcsynopsis[@id = "pam_misc_setenv-synopsis"]/*)'/>
+  </funcsynopsis>
+  <section id='adg-pam_misc_setenv-description'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_misc_setenv.3.xml" xpointer='xpointer(//refsect1[@id = "pam_misc_setenv-description"]/*)'/>
+  </section>
+</section>
diff --git a/doc/adg/pam_open_session.xml b/doc/adg/pam_open_session.xml
new file mode 100644
index 0000000..ba738a5
--- /dev/null
+++ b/doc/adg/pam_open_session.xml
@@ -0,0 +1,18 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<section id='adg-pam_open_session'>
+  <title>Start PAM session management</title>
+  <funcsynopsis>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_open_session.3.xml" xpointer='xpointer(//funcsynopsis[@id = "pam_open_session-synopsis"]/*)'/>
+  </funcsynopsis>
+  <section id='adg-pam_open_session-description'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_open_session.3.xml" xpointer='xpointer(//refsect1[@id = "pam_open_session-description"]/*)'/>
+  </section>
+  <section id='adg-pam_open_session-return_values'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_open_session.3.xml" xpointer='xpointer(//refsect1[@id = "pam_open_session-return_values"]/*)'/>
+  </section>
+</section>
diff --git a/doc/adg/pam_putenv.xml b/doc/adg/pam_putenv.xml
new file mode 100644
index 0000000..e55f1a4
--- /dev/null
+++ b/doc/adg/pam_putenv.xml
@@ -0,0 +1,18 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<section id='adg-pam_putenv'>
+  <title>Set or change PAM environment variable</title>
+  <funcsynopsis>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_putenv.3.xml" xpointer='xpointer(//funcsynopsis[@id = "pam_putenv-synopsis"]/*)'/>
+  </funcsynopsis>
+  <section id='adg-pam_putenv-description'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_putenv.3.xml" xpointer='xpointer(//refsect1[@id = "pam_putenv-description"]/*)'/>
+  </section>
+  <section id='adg-pam_putenv-return_values'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_putenv.3.xml" xpointer='xpointer(//refsect1[@id = "pam_putenv-return_values"]/*)'/>
+  </section>
+</section>
diff --git a/doc/adg/pam_set_item.xml b/doc/adg/pam_set_item.xml
new file mode 100644
index 0000000..4116938
--- /dev/null
+++ b/doc/adg/pam_set_item.xml
@@ -0,0 +1,18 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<section id='adg-pam_set_item'>
+  <title>Setting PAM items</title>
+  <funcsynopsis>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_set_item.3.xml" xpointer='xpointer(//funcsynopsis[@id = "pam_set_item-synopsis"]/*)'/>
+  </funcsynopsis>
+  <section id='adg-pam_set_item-description'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_set_item.3.xml" xpointer='xpointer(//refsect1[@id = "pam_set_item-description"]/*)'/>
+  </section>
+  <section id='adg-pam_set_item-return_values'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_set_item.3.xml" xpointer='xpointer(//refsect1[@id = "pam_set_item-return_values"]/*)'/>
+  </section>
+</section>
diff --git a/doc/adg/pam_setcred.xml b/doc/adg/pam_setcred.xml
new file mode 100644
index 0000000..1d3d23c
--- /dev/null
+++ b/doc/adg/pam_setcred.xml
@@ -0,0 +1,18 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<section id='adg-pam_setcred'>
+  <title>Setting user credentials</title>
+  <funcsynopsis>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_setcred.3.xml" xpointer='xpointer(//funcsynopsis[@id = "pam_setcred-synopsis"]/*)'/>
+  </funcsynopsis>
+  <section id='adg-pam_setcred-description'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_setcred.3.xml" xpointer='xpointer(//refsect1[@id = "pam_setcred-description"]/*)'/>
+  </section>
+  <section id='adg-pam_setcred-return_values'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_setcred.3.xml" xpointer='xpointer(//refsect1[@id = "pam_setcred-return_values"]/*)'/>
+  </section>
+</section>
diff --git a/doc/adg/pam_start.xml b/doc/adg/pam_start.xml
new file mode 100644
index 0000000..e5ec848
--- /dev/null
+++ b/doc/adg/pam_start.xml
@@ -0,0 +1,18 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<section id='adg-pam_start'>
+  <title>Initialization of PAM transaction</title>
+  <funcsynopsis>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_start.3.xml" xpointer='xpointer(//funcsynopsis[@id = "pam_start-synopsis"]/*)'/>
+  </funcsynopsis>
+  <section id='adg-pam_start-description'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_start.3.xml" xpointer='xpointer(//refsect1[@id = "pam_start-description"]/*)'/>
+  </section>
+  <section id='adg-pam_start-return_values'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_start.3.xml" xpointer='xpointer(//refsect1[@id = "pam_start-return_values"]/*)'/>
+  </section>
+</section>
diff --git a/doc/adg/pam_strerror.xml b/doc/adg/pam_strerror.xml
new file mode 100644
index 0000000..35b08a2
--- /dev/null
+++ b/doc/adg/pam_strerror.xml
@@ -0,0 +1,18 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<section id='adg-pam_strerror'>
+  <title>Strings describing PAM error codes</title>
+  <funcsynopsis>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_strerror.3.xml" xpointer='xpointer(//funcsynopsis[@id = "pam_strerror-synopsis"]/*)'/>
+  </funcsynopsis>
+  <section id='adg-pam_strerror-description'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_strerror.3.xml" xpointer='xpointer(//refsect1[@id = "pam_strerror-description"]/*)'/>
+  </section>
+  <section id='adg-pam_strerror-return_values'>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="../man/pam_strerror.3.xml" xpointer='xpointer(//refsect1[@id = "pam_strerror-return_values"]/*)'/>
+  </section>
+</section>