path: root/doc/man/pam.8.xml
diff options
authorThorsten Kukuk <>2006-02-12 22:24:34 +0000
committerThorsten Kukuk <>2006-02-12 22:24:34 +0000
commitf7827ccfd255e23f285eb8aec7ddf71af94dd6ff (patch)
tree171eea4e7e13be3c8e5d2c4748db91b4244782bf /doc/man/pam.8.xml
parent2c388144eb7c68aa31c20c00f6c054c219bf72a2 (diff)
Relevant BUGIDs:
Purpose of commit: cleanup Commit summary: --------------- Merge manual pages and sgml docu as xml, update them. 2006-02-12 Thorsten Kukuk <> * Add doc/man/Makefile. * Make.xml.rules: Enable xincludes for manual pages. * doc/ (EXRA_DIST): Remove manual pages. (SUBDIR): Add man subdirectory. * doc/man/ New. * doc/man/pam_acct_mgmt.3: New. * doc/man/pam_acct_mgmt.3.xml: New. * doc/man/pam_get_data.3: New. * doc/man/pam_get_data.3.xml: New. * doc/man/pam_set_data.3: New. * doc/man/pam_set_data.3.xml: New. * doc/man/pam.8.xml: New. * doc/man/pam.8: Regenerated from xml file. * doc/man/pam_authenticate.3.xml: New. * doc/man/pam_authenticate.3: Regenerated from xml file. * doc/man/pam_chauthtok.3.xml: New. * doc/man/pam_chauthtok.3: Regenerated from xml file. * doc/man/pam_close_session.3.xml: New. * doc/man/pam_close_session.3: Regenerated from xml file. * doc/man/pam_end.3.xml: New. * doc/man/pam_end.3: Regenerated from xml file. * doc/man/pam_fail_delay.3.xml: New. * doc/man/pam_fail_delay.3: Regenerated from xml file. * doc/man/pam_get_item.3.xml: New. * doc/man/pam_get_item.3: Regenerated from xml file. * doc/man/ New. * doc/man/pam_open_session.3.xml: New. * doc/man/pam_open_session.3: Regenerated from xml file. * doc/man/pam_set_item.3.xml: New. * doc/man/pam_set_item.3: Regenerated from xml file. * doc/man/pam_setcred.3.xml: New. * doc/man/pam_setcred.3: Regenerated from xml file. * doc/man/pam_start.3.xml: New. * doc/man/pam_start.3: Regenerated from xml file. * doc/man/pam_strerror.3.xml: New. * doc/man/pam_strerror.3: Regenerated from xml file. * doc/man/template-man: Removed.
Diffstat (limited to 'doc/man/pam.8.xml')
1 files changed, 392 insertions, 0 deletions
diff --git a/doc/man/pam.8.xml b/doc/man/pam.8.xml
new file mode 100644
index 00000000..e8a78234
--- /dev/null
+++ b/doc/man/pam.8.xml
@@ -0,0 +1,392 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "">
+<refentry id='pam'>
+<refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+<refnamediv id='name'>
+<refpurpose>Pluggable Authentication Modules for Linux</refpurpose>
+<!-- body begins here -->
+<refsect1 id='description'><title>DESCRIPTION</title>
+<para>This manual is intended to offer a quick introduction to
+<emphasis remap='B'>Linux-PAM</emphasis>.
+For more information the reader is directed to the
+<emphasis remap='B'>Linux-PAM system administrators' guide</emphasis>.</para>
+<para><emphasis remap='B'>Linux-PAM</emphasis>
+Is a system of libraries that handle the authentication tasks of
+applications (services) on the system. The library provides a stable
+general interface (Application Programming Interface - API) that
+privilege granting programs (such as
+defer to to perform standard authentication tasks.</para>
+<para>The principal feature of the PAM approach is that the nature of the
+authentication is dynamically configurable. In other words, the
+system administrator is free to choose how individual
+service-providing applications will authenticate users. This dynamic
+configuration is set by the contents of the single
+<emphasis remap='B'>Linux-PAM</emphasis>
+configuration file
+Alternatively, the configuration can be set by individual
+configuration files located in the
+<emphasis remap='I'>The presence of this directory will cause </emphasis><emphasis remap='B'>Linux-PAM</emphasis><emphasis remap='I'> to ignore</emphasis>
+<para>From the point of view of the system administrator, for whom this
+manual is provided, it is not of primary importance to understand the
+internal behavior of the
+<emphasis remap='B'>Linux-PAM</emphasis>
+library. The important point to recognize is that the configuration
+<emphasis remap='I'>define</emphasis>
+the connection between applications
+<emphasis remap='B'></emphasis>(<emphasis remap='B'>services</emphasis>)
+and the pluggable authentication modules
+<emphasis remap='B'></emphasis>(<emphasis remap='B'>PAM</emphasis>s)
+that perform the actual authentication tasks.</para>
+<para><emphasis remap='B'>Linux-PAM</emphasis>
+separates the tasks of
+<emphasis remap='I'>authentication</emphasis>
+into four independent management groups:
+<emphasis remap='B'>account</emphasis> management;
+<emphasis remap='B'>auth</emphasis>entication management;
+<emphasis remap='B'>password</emphasis> management;
+<emphasis remap='B'>session</emphasis> management.
+(We highlight the abbreviations used for these groups in the
+configuration file.)</para>
+<para>Simply put, these groups take care of different aspects of a typical
+user's request for a restricted service:</para>
+<para><emphasis remap='B'>account</emphasis> -
+provide account verification types of service: has the user's password
+expired?; is this user permitted access to the requested service?</para>
+<!-- .br -->
+<para><emphasis remap='B'>auth</emphasis>entication -
+authenticate a user and set up user credentials. Typically this is via
+some challenge-response request that the user must satisfy: if you are
+who you claim to be please enter your password. Not all authentications
+are of this type, there exist hardware based authentication schemes
+(such as the use of smart-cards and biometric devices), with suitable
+modules, these may be substituted seamlessly for more standard
+approaches to authentication - such is the flexibility of
+<emphasis remap='B'>Linux-PAM</emphasis>.</para>
+<!-- .br -->
+<para><emphasis remap='B'>password</emphasis> -
+this group's responsibility is the task of updating authentication
+mechanisms. Typically, such services are strongly coupled to those of
+<emphasis remap='B'>auth</emphasis>
+group. Some authentication mechanisms lend themselves well to being
+updated with such a function. Standard UN*X password-based access is
+the obvious example: please enter a replacement password.</para>
+<!-- .br -->
+<para><emphasis remap='B'>session</emphasis> -
+this group of tasks cover things that should be done prior to a
+service being given and after it is withdrawn. Such tasks include the
+maintenance of audit trails and the mounting of the user's home
+directory. The
+<emphasis remap='B'>session</emphasis>
+management group is important as it provides both an opening and
+closing hook for modules to affect the services available to a user.</para>
+<refsect1 id='the_configuration_files'><title>The configuration file(s)</title>
+<para>When a
+<emphasis remap='B'>Linux-PAM</emphasis>
+aware privilege granting application is started, it activates its
+attachment to the PAM-API. This activation performs a number of
+tasks, the most important being the reading of the configuration file(s):
+Alternatively, this may be the contents of the
+<para>These files list the
+<emphasis remap='B'>PAM</emphasis>s
+that will do the authentication tasks required by this service, and
+the appropriate behavior of the PAM-API in the event that individual
+<emphasis remap='B'>PAM</emphasis>s
+<para>The syntax of the
+configuration file is as follows. The file is made
+up of a list of rules, each rule is typically placed on a single line,
+but may be extended with an escaped end of line: `\&lt;LF&gt;'. Comments
+are preceded with `#' marks and extend to the next end of line.</para>
+<para>The format of each rule is a space separated collection of tokens, the
+first three being case-insensitive:</para>
+<!-- .br -->
+<para><emphasis remap='B'> service type control module-path module-arguments</emphasis></para>
+<para>The syntax of files contained in the
+directory, are identical except for the absence of any
+<emphasis remap='I'>service</emphasis>
+field. In this case, the
+<emphasis remap='I'>service</emphasis>
+is the name of the file in the
+directory. This filename must be in lower case.</para>
+<para>An important feature of
+<emphasis remap='B'>Linux-PAM</emphasis>,
+is that a number of rules may be
+<emphasis remap='I'>stacked</emphasis>
+to combine the services of a number of PAMs for a given authentication
+<emphasis remap='B'>service</emphasis>
+is typically the familiar name of the corresponding application:
+<emphasis remap='B'>login</emphasis>
+<emphasis remap='B'>su</emphasis>
+are good examples. The
+<emphasis remap='B'>service</emphasis>-name, <emphasis remap='B'>other</emphasis>,
+is reserved for giving
+<emphasis remap='I'>default</emphasis>
+rules. Only lines that mention the current service (or in the absence
+of such, the
+<emphasis remap='B'>other</emphasis>
+entries) will be associated with the given service-application.</para>
+<emphasis remap='B'>type</emphasis>
+is the management group that the rule corresponds to. It is used to
+specify which of the management groups the subsequent module is to
+be associated with. Valid entries are:
+<emphasis remap='B'>account</emphasis>;
+<emphasis remap='B'>auth</emphasis>;
+<emphasis remap='B'>password</emphasis>;
+<emphasis remap='B'>session</emphasis>.
+The meaning of each of these tokens was explained above.</para>
+<para>The third field,
+<emphasis remap='B'>control</emphasis>,
+indicates the behavior of the PAM-API should the module fail to
+succeed in its authentication task. There are two types of syntax for
+this control field: the simple one has a single simple keyword; the
+more complicated one involves a square-bracketed selection of
+<emphasis remap='B'>value=action</emphasis>
+<para>For the simple (historical) syntax valid
+<emphasis remap='B'>control</emphasis>
+values are:
+<emphasis remap='B'>requisite</emphasis>
+- failure of such a PAM results in the immediate termination of the
+authentication process;
+<emphasis remap='B'>required</emphasis>
+- failure of such a PAM will ultimately lead to the PAM-API returning
+failure but only after the remaining
+<emphasis remap='I'>stacked</emphasis>
+modules (for this
+<emphasis remap='B'>service</emphasis>
+<emphasis remap='B'>type</emphasis>)
+have been invoked;
+<emphasis remap='B'>sufficient</emphasis>
+- success of such a module is enough to satisfy the authentication
+requirements of the stack of modules (if a prior
+<emphasis remap='B'>required</emphasis>
+module has failed the success of this one is
+<emphasis remap='I'>ignored</emphasis>);
+<emphasis remap='B'>optional</emphasis>
+- the success or failure of this module is only important if it is the
+only module in the stack associated with this
+<emphasis remap='B'>service</emphasis>+<emphasis remap='B'>type</emphasis>.</para>
+<para>New control directive first introduced in ALT Linux is
+<emphasis remap='B'>include</emphasis>
+- include all lines of given type from the configuration
+file specified as an argument to this control.</para>
+<para>For the more complicated syntax valid
+<emphasis remap='B'>control</emphasis>
+values have the following form:</para>
+<para>[value1=action1<emphasis remap='B'>value2=action2</emphasis>...]</para>
+<emphasis remap='B'>valueN</emphasis>
+corresponds to the return code from the function invoked in the module
+for which the line is defined. It is selected from one of these:
+<emphasis remap='B'>success</emphasis>;
+<emphasis remap='B'>open_err</emphasis>;
+<emphasis remap='B'>symbol_err</emphasis>;
+<emphasis remap='B'>service_err</emphasis>;
+<emphasis remap='B'>system_err</emphasis>;
+<emphasis remap='B'>buf_err</emphasis>;
+<emphasis remap='B'>perm_denied</emphasis>;
+<emphasis remap='B'>auth_err</emphasis>;
+<emphasis remap='B'>cred_insufficient</emphasis>;
+<emphasis remap='B'>authinfo_unavail</emphasis>;
+<emphasis remap='B'>user_unknown</emphasis>;
+<emphasis remap='B'>maxtries</emphasis>;
+<emphasis remap='B'>new_authtok_reqd</emphasis>;
+<emphasis remap='B'>acct_expired</emphasis>;
+<emphasis remap='B'>session_err</emphasis>;
+<emphasis remap='B'>cred_unavail</emphasis>;
+<emphasis remap='B'>cred_expired</emphasis>;
+<emphasis remap='B'>cred_err</emphasis>;
+<emphasis remap='B'>no_module_data</emphasis>;
+<emphasis remap='B'>conv_err</emphasis>;
+<emphasis remap='B'>authtok_err</emphasis>;
+<emphasis remap='B'>authtok_recover_err</emphasis>;
+<emphasis remap='B'>authtok_lock_busy</emphasis>;
+<emphasis remap='B'>authtok_disable_aging</emphasis>;
+<emphasis remap='B'>try_again</emphasis>;
+<emphasis remap='B'>ignore</emphasis>;
+<emphasis remap='B'>abort</emphasis>;
+<emphasis remap='B'>authtok_expired</emphasis>;
+<emphasis remap='B'>module_unknown</emphasis>;
+<emphasis remap='B'>bad_item</emphasis>; and
+<emphasis remap='B'>default</emphasis>.
+The last of these,
+<emphasis remap='B'>default</emphasis>,
+implies 'all
+<emphasis remap='B'>valueN</emphasis>'s
+not mentioned explicitly. Note, the full list of PAM errors is
+available in /usr/include/security/_pam_types.h . The
+<emphasis remap='B'>actionN</emphasis>
+can be: an unsigned integer,
+<emphasis remap='B'>J</emphasis>,
+signifying an action of 'jump over the next J modules in the stack';
+or take one of the following forms:
+<!-- .br -->
+<emphasis remap='B'>ignore</emphasis>
+- when used with a stack of modules, the module's return status will
+not contribute to the return code the application obtains;
+<!-- .br -->
+<emphasis remap='B'>bad</emphasis>
+- this action indicates that the return code should be thought of as
+indicative of the module failing. If this module is the first in the
+stack to fail, its status value will be used for that of the whole
+<!-- .br -->
+<emphasis remap='B'>die</emphasis>
+- equivalent to bad with the side effect of terminating the module
+stack and PAM immediately returning to the application.
+<!-- .br -->
+<emphasis remap='B'>ok</emphasis>
+- this tells PAM that the administrator thinks this return code
+should contribute directly to the return code of the full stack of
+modules. In other words, if the former state of the stack would lead
+to a return of
+<emphasis remap='B'>PAM_SUCCESS</emphasis>,
+the module's return code will override this value. Note, if the former
+state of the stack holds some value that is indicative of a modules
+failure, this 'ok' value will not be used to override that value.
+<!-- .br -->
+<emphasis remap='B'>done</emphasis>
+- equivalent to ok with the side effect of terminating the module
+stack and PAM immediately returning to the application.
+<!-- .br -->
+<emphasis remap='B'>reset</emphasis>
+- clear all memory of the state of the module stack and start again
+with the next stacked module.</para>
+<para><emphasis remap='B'>module-path</emphasis>
+- this is either the full filename of the PAM to be used by the
+application (it begins with a '/'), or a relative pathname from the
+default module location:
+<para><emphasis remap='B'>module-arguments</emphasis>
+- these are a space separated list of tokens that can be used to
+modify the specific behavior of the given PAM. Such arguments will be
+documented for each individual module.</para>
+<refsect1 id='files'><title>FILES</title>
+<para><filename>/etc/pam.conf</filename> - the configuration file
+<!-- .br -->
+<filename>/etc/pam.d/</filename> - the
+<emphasis remap='B'>Linux-PAM</emphasis>
+configuration directory. Generally, if this directory is present, the
+file is ignored.
+<!-- .br -->
+<filename>/lib/</filename> - the dynamic library
+<!-- .br -->
+<filename>/lib/security/*.so</filename> - the PAMs</para>
+<refsect1 id='errors'><title>ERRORS</title>
+<para>Typically errors generated by the
+<emphasis remap='B'>Linux-PAM</emphasis>
+system of libraries, will be written to
+<refsect1 id='conforming_to'><title>CONFORMING TO</title>
+<para>DCE-RFC 86.0, October 1995.
+<!-- .br -->
+Contains additional features, but remains backwardly compatible with
+this RFC.</para>
+<refsect1 id='bugs'><title>BUGS</title>
+<para>None known.</para>
+<refsect1 id='see_also'><title>SEE ALSO</title>
+<para>The three
+<emphasis remap='B'>Linux-PAM</emphasis>
+Guides, for
+<emphasis remap='B'>system administrators</emphasis>,
+<emphasis remap='B'>module developers</emphasis>,
+<emphasis remap='B'>application developers</emphasis>. </para>