1 files changed, 138 insertions, 0 deletions
diff --git a/doc/man/PAM.8 b/doc/man/PAM.8
new file mode 100644
index 00000000..e9cfba00
--- /dev/null
+++ b/doc/man/PAM.8
@@ -0,0 +1,138 @@
+'\" t
+.\"     Title: pam
+.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
+.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
+.\"      Date: 04/01/2016
+.\"    Manual: Linux-PAM Manual
+.\"    Source: Linux-PAM Manual
+.\"  Language: English
+.\"
+.TH "PAM" "8" "04/01/2016" "Linux-PAM Manual" "Linux-PAM Manual"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+PAM, pam \- Pluggable Authentication Modules for Linux
+.SH "DESCRIPTION"
+.PP
+This manual is intended to offer a quick introduction to
+\fBLinux\-PAM\fR\&. For more information the reader is directed to the
+\fBLinux\-PAM system administrators\*(Aq guide\fR\&.
+.PP
+\fBLinux\-PAM\fR
+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
+\fBlogin\fR(1)
+and
+\fBsu\fR(1)) defer to to perform standard authentication tasks\&.
+.PP
+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
+\fBLinux\-PAM\fR
+configuration file
+/etc/pam\&.conf\&. Alternatively, the configuration can be set by individual configuration files located in the
+/etc/pam\&.d/
+directory\&. The presence of this directory will cause
+\fBLinux\-PAM\fR
+to
+\fIignore\fR/etc/pam\&.conf\&.
+.PP
+Vendor\-supplied PAM configuration files might be installed in the system directory
+/usr/lib/pam\&.d/
+instead of the machine configuration directory
+/etc/pam\&.d/\&. If no machine configuration file is found, the vendor\-supplied file is used\&. All files in
+/etc/pam\&.d/
+override files with the same name in
+/usr/lib/pam\&.d/\&.
+.PP
+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
+\fBLinux\-PAM\fR
+library\&. The important point to recognize is that the configuration file(s)
+\fIdefine\fR
+the connection between applications
+(\fBservices\fR) and the pluggable authentication modules
+(\fBPAM\fRs) that perform the actual authentication tasks\&.
+.PP
+\fBLinux\-PAM\fR
+separates the tasks of
+\fIauthentication\fR
+into four independent management groups:
+\fBaccount\fR
+management;
+\fBauth\fRentication management;
+\fBpassword\fR
+management; and
+\fBsession\fR
+management\&. (We highlight the abbreviations used for these groups in the configuration file\&.)
+.PP
+Simply put, these groups take care of different aspects of a typical user\*(Aqs request for a restricted service:
+.PP
+\fBaccount\fR
+\- provide account verification types of service: has the user\*(Aqs password expired?; is this user permitted access to the requested service?
+.PP
+\fBauth\fRentication \- 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
+\fBLinux\-PAM\fR\&.
+.PP
+\fBpassword\fR
+\- this group\*(Aqs responsibility is the task of updating authentication mechanisms\&. Typically, such services are strongly coupled to those of the
+\fBauth\fR
+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\&.
+.PP
+\fBsession\fR
+\- 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\*(Aqs home directory\&. The
+\fBsession\fR
+management group is important as it provides both an opening and closing hook for modules to affect the services available to a user\&.
+.SH "FILES"
+.PP
+/etc/pam\&.conf
+.RS 4
+the configuration file
+.RE
+.PP
+/etc/pam\&.d
+.RS 4
+the
+\fBLinux\-PAM\fR
+configuration directory\&. Generally, if this directory is present, the
+/etc/pam\&.conf
+file is ignored\&.
+.RE
+.PP
+/usr/lib/pam\&.d
+.RS 4
+the
+\fBLinux\-PAM\fR
+vendor configuration directory\&. Files in
+/etc/pam\&.d
+override files with the same name in this directory\&.
+.RE
+.SH "ERRORS"
+.PP
+Typically errors generated by the
+\fBLinux\-PAM\fR
+system of libraries, will be written to
+\fBsyslog\fR(3)\&.
+.SH "CONFORMING TO"
+.PP
+DCE\-RFC 86\&.0, October 1995\&. Contains additional features, but remains backwardly compatible with this RFC\&.
+.SH "SEE ALSO"
+.PP
+\fBpam\fR(3),
+\fBpam_authenticate\fR(3),
+\fBpam_sm_setcred\fR(3),
+\fBpam_strerror\fR(3),
+\fBPAM\fR(8)