Add manpages; remove invariant sections from pam-modules.texi

10 files changed, 1642 insertions, 12 deletions

diff --git a/doc/.gitignore b/doc/.gitignore
index 3cc99a1..8ae6011 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -1,5 +1,9 @@
 Makefile
 Makefile.in
+config.so
+pam_fshadow.8
+pam_mysql.8
+pam_pgsql.8
 pam-modules.info*
 stamp-vti
 version.texi
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 99ac7d5..76df136 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -16,9 +16,51 @@
 
 info_TEXINFOS=pam-modules.texi
 pam_modules_TEXINFOS=fdl.texi macros.texi
+dist_man_MANS = pamck.1
+
+if PAM_COND_FSHADOW
+  dist_man_MANS += pam_fshadow.8
+endif
+if PAM_COND_REGEX
+  dist_man_MANS += pam_regex.8
+endif
+if PAM_COND_LOG
+  dist_man_MANS += pam_log.8
+endif
+#if PAM_COND_LDAPHOME
+#  dist_man_MANS += pam_ldaphome.8
+#endif
+if PAM_COND_UMOTD
+  dist_man_MANS += pam_umotd.8
+endif
+if PAM_COND_MYSQL
+  dist_man_MANS += pam_mysql.8
+endif
+if PAM_COND_PGSQL
+  dist_man_MANS += pam_pgsql.8
+endif
+
+config.so: $(top_srcdir)/configure.ac $(top_srcdir)/doc/Makefile.am
+	$(AM_V_GEN){\
+                echo ".ds ET $(sysconfdir)"; \
+        } > config.so
+
+BUILD_MANS=pam_fshadow.8 pam_mysql.8 pam_pgsql.8
+CLEANFILES=$(BUILD_MANS) config.so
+
+pam_fshadow.8 pam_mysql.8 pam_pgsql.8: config.so
+
+.8in.8:
+	$(AM_V_GEN){\
+                echo '.\" -*- buffer-read-only: t -*- vi: set ro:';\
+                echo '.\" THIS FILE IS GENERATED AUTOMATICALLY; DO NOT EDIT!';\
+                soelim -I$(top_builddir)/doc $<;\
+        } > $@
 
 EXTRA_DIST = \
- gendocs_template
+ gendocs_template\
+ pam_fshadow.8in\
+ pam_mysql.8in
 
 clean-local:
 	rm -rf manual
diff --git a/doc/pam-modules.texi b/doc/pam-modules.texi
index 7c2d881..35d31cb 100644
--- a/doc/pam-modules.texi
+++ b/doc/pam-modules.texi
@@ -46,15 +46,9 @@ Boston, MA 02110-1301, USA
 Copyright @copyright{} 2005, 2007-2012, 2014 Sergey Poznyakoff
 
 Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.2 or
+under the terms of the GNU Free Documentation License, Version 1.3 or
 any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover texts being ``PAM-modules Manual'',
-and with the Back-Cover Texts as in (a) below.  A copy of the license
-is included in the section entitled ``GNU Free Documentation License''.
-
-(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
-this GNU Manual, like GNU software.  Copies published by the Free
-Software Foundation raise funds for GNU development.''
+Invariant Sections, and no special Front- or Back- Cover texts/
 @end copying
 
 @titlepage
@@ -219,7 +213,7 @@ from which the @code{PAM_RUSER} entity is requesting service).  That is
 user.  In some applications, @code{PAM_RHOST} may be @samp{NULL}.
 
 @item ruser
-@code{PAM_RUSER}.  The requesting entity: user's sername for a locally
+@code{PAM_RUSER}.  The requesting entity: user's name for a locally
 requesting user or a remote requesting user.  In some cases,
 @code{PAM_RUSER} may be @samp{NULL}.
 
@@ -496,7 +490,7 @@ This section summarizes all @command{pam_fshadow} command line options:
 options, nopasswd}.
 
 @opsummary{noshadow}
-@item nopasswd
+@item noshadow
    Use only @file{passwd} for authentication.  @xref{pam_fshadow common
 options, noshadow}.
 
@@ -939,7 +933,7 @@ algorithm name in curly braces.  This variable is @code{true} by
 default. 
 
 @kwindex allow-md5-pass, @command{pam_mysql} configuration keyword
-@item allow-md5l-pass @var{bool}
+@item allow-md5-pass @var{bool}
 The returned password may be encrypted using MySQL @code{md5}
 function.  This keyword is specific for @command{pam_mysql}.
 
diff --git a/doc/pam_fshadow.8in b/doc/pam_fshadow.8in
new file mode 100644
index 0000000..eb990d1
--- /dev/null
+++ b/doc/pam_fshadow.8in
@@ -0,0 +1,223 @@
+.\" This file is part of PAM-Modules -*- nroff -*-
+.\" Copyright (C) 2001-2014 Sergey Poznyakoff
+.\"
+.\" PAM-Modules is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\"
+.\" PAM-Modules is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with PAM-Modules.  If not, see <http://www.gnu.org/licenses/>.
+.so config.so
+.TH PAM_FSHADOW 8 "March 30, 2014" "PAM-MODULES" "Pam-Modules User Reference"
+.SH NAME
+pam_fshadow \- use alternative passwd and/or shadow files
+.SH SYNOPSIS
+.nh
+.na
+\fBpam_fshadow\fR\
+ [\fBbasic\fR|\fBextended\fR]\
+ [\fBignore\-case\fR|\fBicase\fR|\fBcase\fR]\
+ [\fBnopasswd\fR]\
+ [\fBnoshadow\fR]\
+ [\fBregex=\fIEXPR\fR]\
+ [\fBrevert\-index\fR]\
+ [\fBsysconfdir=\fIDIR\fR]\
+ [\fBuse_authtok\fR]\
+ [\fBdebug\fR[\fB=\fINUMBER\fR]]\
+ [\fBwaitdebug\fR]\
+ [\fBaudit\fR]
+.ad
+.hy
+.SH DESCRIPTION
+Authenticates the user against alternative \fBpasswd\fR and
+\fBshadow\fR files.  There are two operation modes:
+\fBplain\fR mode, in which the module uses only
+one \fBpasswd\fR,\fBshadow\fR pair, and \fBvirtual domain\fR mode,
+which selects the pair to use based depending on the authentication
+token (the user name).
+.PP
+In plain mode, \fBpam_fshadow\fR checks the supplied user name and
+authentication token against the \fBpasswd\fR and \fBshadow\fR files
+located in the system configuration directory.  The latter is set when
+configuring the package and defaults to \fB\*(ET\fR.  Its
+location can be changed using the \fBsysconfdir\fR command line
+parameter.
+.PP
+The command line options \fBnopasswd\fR and \fBnoshadow\fR are
+provided to disable reading of either file.  E.g. if \fBnoshadow\fR is
+given, the module will expect all authentication information to be
+stored in the \fBpasswd\fR file.
+.PP
+The \fBvirtual domain\fR mode select the \fBpasswd\fR,\fBshadow\fR
+pair to use depending on the user name.  To that effect, the user name
+is first split into the \fBlocal\fR and \fBauthentication domain\fR
+parts using a regular expression supplied with the \fBregex\fR option.
+The configuration directory name is then constructed by concatenating the
+system configuration directory, a directory separator character (\fB/\fR),
+and the name of the authentication domain.   The authentication then
+proceeds as described above for the plain mode.  If the supplied user name
+does not match the regular expression, \fBpam_fshadow\fR falls back to
+the plain mode.
+.SH OPTIONS
+.TP
+\fBbasic\fR
+The argument to the \fBregex\fR option is a basic regular expression. 
+.TP
+\fBextended\fR
+The argument to the \fBregex\fR option is a POSIX extended regular
+expression.  This is the default.
+.TP
+\fBignore\-case\fR, \fBicase\fR
+Use case-insensitive regex matching.
+.TP
+Use case-sensitive regex matching (default).
+.TP
+\fBnopasswd\fR
+Use only \fBshadow\fR file for authentication.
+.TP
+\fBnoshadow\fR
+Use only \fBpasswd\fR file for authentication.
+.TP
+\fBregex=\fIEXPR\fR
+Defines a regular expression for splitting user name into the proper
+name and authentication domain.  The expression must contain two
+parentesized groups.  If it matches, the group 1 will be used to
+extract local user name and the group 2 will select the authentication
+domain.  The \fBrevert\-index\fR option changes this behavior, causing
+group 1 to be used for authentication domain and group 2 for user
+name.  For example:
+.RS
+.EX
+regex=(.*)@(.*)
+.EE
+.RE
+
+This regular expression will match user names like \fBsmith@domain\fR.
+.TP
+\fBrevert\-index\fR
+Use group #2 from the regular expression as the user name and group #1
+as the authentication domain. 
+.TP
+\fBsysconfdir=\fIDIR\fR
+Use \fIDIR\fR as the system configuration directory, instead of the
+default \fB\*(ET\fR.
+.TP
+\fBuse_authtok\fR
+Do not prompt the user for password, take it from the saved
+authentication tokens.
+.TP
+\fBdebug\fR\fB=\fINUMBER\fR]
+Set debugging level (0 <= \fINUMBER\fR <= 100).
+.TP
+\fBwaitdebug\fR
+Wait for \fIN\fR seconds before starting up.  This option is intended
+to facilitate attaching to the module with
+.BR gdb (1).
+It is available only if the package was configured with
+the \fB\-\-enable\-debug\fR option.
+.TP
+\fBaudit\fR
+Log auditing information.
+.SH MODULE TYPES PROVIDED
+.BR auth ,
+.BR session ,
+.BR account .
+.SH RETURN VALUES
+.TP
+.B PAM_SUCCESS
+Successful return.
+.TP
+.B PAM_AUTH_ERR
+Authentication failed.
+.TP
+.B PAM_AUTHINFO_UNAVAIL
+The input information is not sufficient.
+.TP
+.B PAM_AUTHTOK_RECOVER_ERR
+Failed to obtain stored authentication token.  This code can be
+returned if \fBuse_authtok\fR was used.
+.TP
+.B PAM_SERVICE_ERR
+Can't open \fBpasswd\fR or \fBshadow\fR file, or get username or
+password.
+.TP
+.B PAM_USER_UNKNOWN
+Supplied username not found.
+.TP
+.B PAM_SYSTEM_ERR
+Out of memory.
+.SH EXAMPLES
+.nr step 1 1
+.IP \n[step].
+Plain mode.  Use the file \fB/etc/ftpauth/shadow\fR for authentication.
+.PP
+.EX
+auth required pam_fshadow.so sysconfdir=/etc/ftpauth nopasswd
+.EE
+.IP \n+[step].
+Authenticate against files located in \fB/etc/authdomain\fR.  E.g. if the
+supplied user name were \fBsmith@ftp\fR, it would use the files
+.B /etc/authdomain/ftp/passwd
+and
+.BR /etc/authdomain/ftp/shadow :
+.PP
+auth required pam_fshadow.so sysconfdir=/etc/authdomain regex=(.*)@(.*) 
+.PP
+.EX
+.EE
+.SH NOTE
+This manpage is a short description of \fBpam_fshadow\fR.  For a detailed
+discussion, including examples and usage recommendations, refer to the
+\fBPAM-modules Manual\fR available in texinfo format.  If the \fBinfo\fR
+reader and the tar documentation are properly installed on your
+system, the command
+.PP
+.RS +4
+.B info pam-modules
+.RE
+.PP
+should give you access to the complete manual.
+.PP
+You can also view the manual using the info mode in
+.BR emacs (1),
+or find it in various formats online at
+.PP
+.RS +4
+.B http://www.gnu.org.ua/software/pam-modules/manual
+.RE
+.PP
+If any discrepancies occur between this manpage and the
+\fBPAM-modules Manual\fR, the later shall be considered the authoritative
+source.
+.SH "SEE ALSO"
+.BR pam.conf (5),
+.BR pam.d (5),
+.BR pam (8),
+.BR regex (7).
+.SH AUTHORS
+Sergey Poznyakoff <gray@gnu.org>
+.SH "BUG REPORTS"
+Report bugs to <bug\-pam\-modules@gnu.org.ua>.
+.SH COPYRIGHT
+Copyright \(co 2001-2014 Sergey Poznyakoff
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:
+
diff --git a/doc/pam_log.8 b/doc/pam_log.8
new file mode 100644
index 0000000..0554dba
--- /dev/null
+++ b/doc/pam_log.8
@@ -0,0 +1,130 @@
+.\" This file is part of PAM-Modules -*- nroff -*-
+.\" Copyright (C) 2001-2014 Sergey Poznyakoff
+.\"
+.\" PAM-Modules is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\"
+.\" PAM-Modules is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with PAM-Modules.  If not, see <http://www.gnu.org/licenses/>.
+.TH PAM_LOG 8 "March 28, 2014" "PAM-MODULES" "Pam-Modules User Reference"
+.SH NAME
+pam_log \- log messages to syslog
+.SH SYNOPSIS
+.nh
+.na
+\fBpam_log\fR [\fB\-audit\fR]\
+ [\fB\-debug\fR[\fB=\fILEVEL\fR]]\
+ [\fB\-noopen\fR]\
+ [\fB\-waitdebug\fR[\fB=\fISECONDS\fR]]\
+ [\fB\-pri=\fIFACILITY\fB.\fIPRIORITY\fR]\
+ [\fB\-tag=\fILABEL\fR] \fITEXT\fR...
+.ad
+.hy
+.SH DESCRIPTION
+Sends diagnostic text to syslog.
+.SH OPTIONS
+.TP
+\fB\-pri=\fIFACILITY\fB.\fIPRIORITY\fR
+Send text to the given syslog facility and priority.  Valid values for
+\fIFACILITY\fR are:
+.BR user ,
+.BR daemon ,
+.BR auth ,
+.BR authpriv ", and "
+.BR local0 " through " local7 .
+Valid values for \fIPRIORITY\fR are:
+.BR emerg ,
+.BR alert ,
+.BR crit ,
+.BR err ,
+.BR warning ,
+.BR notice ,
+.BR info ", and "
+.BR debug .
+
+Either part can be omitted, in which case the following defaults are
+used: \fIFACILITY=\fBauthpriv\fR, \fIPRIORITY=\fBinfo\fR.
+.TP
+\fB\-tag=\fILABEL\fR
+Use \fILABEL\fR as the syslog tag, instead of the module name.
+.TP
+\fB\-debug\fR[\fB=\fINUMBER\fR]
+Set debugging level (0 <= \fINUMBER\fR <= 100).
+.TP
+\fB\-audit\fR
+Log auditing information.
+.TP
+\fB\-waitdebug=\fIN\fR
+Wait for \fIN\fR seconds before starting up.  This option is intended
+to facilitate attaching to the module with
+.BR gdb (1).
+It is available only if the package was configured with
+the \fB\-\-enable\-debug\fR option.
+.SH MODULE TYPES PROVIDED
+All module types (\fBaccount\fR, \fBauth\fR, \fBpassword\fR and
+\fBsession\fR) are provided.
+.SH RETURN VALUES
+.TP
+.B PAM_IGNORE
+Ignore this module.
+.SH EXAMPLES
+.EX
+account requisite pam_log.so -tag FTP \\
+      -pri=daemon.info User ${user:-unknown} is granted FTP access
+.EE      
+.SH NOTE
+This manpage is a short description of \fBpam_log\fR.  For a detailed
+discussion, including examples and usage recommendations, refer to the
+\fBPAM-modules Manual\fR available in texinfo format.  If the \fBinfo\fR
+reader and the tar documentation are properly installed on your
+system, the command
+.PP
+.RS +4
+.B info pam-modules
+.RE
+.PP
+should give you access to the complete manual.
+.PP
+You can also view the manual using the info mode in
+.BR emacs (1),
+or find it in various formats online at
+.PP
+.RS +4
+.B http://www.gnu.org.ua/software/pam-modules/manual
+.RE
+.PP
+If any discrepancies occur between this manpage and the
+\fBPAM-modules Manual\fR, the later shall be considered the authoritative
+source.
+.SH "SEE ALSO"
+.BR pam.conf (5),
+.BR pam.d (5),
+.BR pam (8).
+.SH AUTHORS
+Sergey Poznyakoff <gray@gnu.org>
+.SH "BUG REPORTS"
+Report bugs to <bug\-pam\-modules@gnu.org.ua>.
+.SH COPYRIGHT
+Copyright \(co 2001-2014 Sergey Poznyakoff
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:
+
diff --git a/doc/pam_mysql.8in b/doc/pam_mysql.8in
new file mode 100644
index 0000000..39506b6
--- /dev/null
+++ b/doc/pam_mysql.8in
@@ -0,0 +1,374 @@
+.\" This file is part of PAM-Modules -*- nroff -*-
+.\" Copyright (C) 2001-2014 Sergey Poznyakoff
+.\"
+.\" PAM-Modules is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\"
+.\" PAM-Modules is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with PAM-Modules.  If not, see
+.\" <http://www.gnu.org/licenses/>.
+.so config.so
+.TH PAM_MYSQL 8 "April 2, 2014" "PAM-MODULES" "Pam-Modules User Reference"
+.SH NAME
+pam_mysql \- authenticate using a MySQL database
+.SH SYNOPSIS
+.nh
+.na
+\fBpam_mysql\fR [\fBconfig=\fIFILE\fR]\
+ [\fBuse_authtok\fR]\
+ [\fBdebug\fR[\fB=\fINUMBER\fR]]\
+ [\fBwaitdebug\fR]\
+ [\fBaudit\fR]
+.ad
+.hy
+.SH DESCRIPTION
+Provides authentication and account management services via a MySQL
+database.
+.PP
+When used in the \fBauth\fR stack, the module first connects to the
+database using credentials supplied in the configuration file (see
+below).  Then, it retrieves the value of the \fBpasswd\-query\fR
+configuration parameter and performs \fBPAM\fR item expansion over
+it.  The resulting query is sent to the \fBSQL\fR server.  If this
+query produces a non-empty result, the first column from the first
+tuple is used as encrypted user password and is compared with the
+supplied authentication token.  If it matches, the user is
+authenticated successfully.  The comparison includes the following
+checks, performed in that order until one of them returns match or the
+list is exhausted: 
+.nr step 1 1
+.IP \n[step].
+Compare the retrieved password with the result of the system
+.BR crypt (3)
+function called with the authentication token and retrieved password
+as its arguments
+.IP \n+[step].
+Encrypt the authentication token using the
+.B MySQL
+password encoding algorithm and compare the result with the retrieved
+password.
+.IP \n+[step].
+Compare password with the MD5 sum of the authentication token.
+.IP \n+[step].
+Assume the password is encrypted using the
+.BR LDAP -style
+encoding and compare it accordingly.
+.IP \n+[step].
+Compare both strings literally.  This check is performed only if
+the
+.B allow\-plaintext\-pass
+configuration parameter is set.
+.PP
+Any of these checks can be disabled using the corresponding
+configuration setting.
+.SH CONFIGURATION
+The configuration information is supplied in a file
+.BR \*(ET/pam_sql.conf .
+An alternative location can be given via the \fBconfig\fR command line
+option.  The file is a usual UNIX-style configuration file with
+comments introduced by the \fB#\fR character.  Long statements can be
+split across several physical lines of text by ending each line but
+the last with a backslash character. 
+.PP
+The following statements are defined.
+.SS Database connection configuration
+.TP
+.BI host " NAME"
+Sets hostname or IP address of the MySQL server.
+
+If the database is listening on the local socket, the \fINAME\fR
+is the pathname of the local socket.
+.TP
+.BI port " NUMBER"
+Sets the MySQL port number.  The default value is 3306.
+.TP
+.BI db " NAME"
+Sets the database name.
+.TP
+.BI login " NAME"
+Sets the database user name.  The user must have \fBSELECT\fR
+privileges on tables in the authentication database.
+.TP
+.BI pass " TEXT"
+Sets password for database access.
+.SS Queries
+These statements define \fBSQL\fR queries used by the module.  The
+argument of each statement is subject to
+.BR "PAM item expansion" ,
+which is described in detail in the following section.
+.TP
+.BI passwd\-query " QUERY"
+Defines \fBSQL\fR query to be used to obtain the user's password from the
+database.
+.TP
+.BI session\-start\-query " QUERY"
+Defines \fBSQL\fR query to be executed on session start.
+.TP
+.BI session\-stop\-query " QUERY"
+Defines \fBSQL\fR query to be executed on session termination.
+.TP
+.BI setenv\-query " QUERY"
+This query is available when the package is compiled with
+.B Linux PAM
+implementation.  The data it selects from the database are then
+stored in the \fBPAM\fR environment.  Only the first tuple returned
+is used; the column names are treated as environment variable names,
+and column values as their values. 
+.SS Password encryption
+The variables in this subsections control how the module treats
+passwords returned by the 
+.BR passwd\-query .
+Their argument is a boolean value: \fByes\fR, \fBtrue\fR or \fBt\fR,
+for true value and \fBno\fR, \fBfalse\fR or \fBf\fR, for false value.
+.TP
+.BI allow\-plaintext\-pass " BOOL"
+Controls whether the
+.B passwd\-query
+may return a plaintext password.
+.TP
+.BI allow\-ldap\-pass " BOOL"
+The returned password may be a
+.BR LDAP -style
+password hash, i.e. the hash value encoded as base-64 and prefixed
+with a hashing algorithm name in curly braces.  This variable is
+\fBtrue\fR by default. 
+.TP
+.BI allow\-md5-pass " BOOL"
+The returned password may be encrypted using \fBMySQL md5\fR
+function.
+.TP
+.BI allow\-mysql\-pass " BOOL"
+The returned password may be encrypted using \fBMySQL password\fR
+function.
+.SH PAM ITEM EXPANSION
+The query strings described in the previous section are subject to
+item expansion prior to being sent to the \fBMySQL\fR server.  This
+feature is similar to the shell variable expansion.  During item
+expansion, any occurrence of \fB$\fINAME\fR is replaced with the
+actual value of the \fBPAM\fR item \fINAME\fR.  If the item in
+question is not defined, an empty string is substituted instead.  A
+limited support for the shell-style default values is available:
+namely, the notation \fB${\fIITEM\fB:-\fIVALUE\fB}\fR expands to the
+value of \fBITEM\fR if it is set, and to \fIVALUE\fR otherwise.
+Notice, that \fIVALUE\fR must be a literal value (string or numeric).
+.PP
+The following table lists valid \fBPAM\fR item names:
+.TP
+.B service
+.BR PAM_SERVICE .
+The service name (identifies the \fBPAM\fR stack that will be used).
+.TP
+.B user
+.BR PAM_USER .
+The username of the entity under whose identity service will be given.
+.TP
+.B tty
+.BR PAM_TTY .
+The terminal name: prefixed by \fB/dev/\fR if it is a device file; for
+graphical, X-based, applications the value for this item is usually
+the \fB$DISPLAY\fR environment variable. 
+.TP
+.B rhost
+.BR PAM_RHOST .
+The requesting hostname (the hostname of the machine
+from which the \fBPAM_RUSER\fR entity is requesting service).  That is
+\fBPAM_RUSER@PAM_RHOST\fR identifies the requesting user.  In some
+applications, \fBPAM_RHOST\fR may be \fBNULL\fR.
+.TP
+.B ruser
+.BR PAM_RUSER .
+The requesting entity: user's name for a locally requesting user or a
+remote requesting user.  In some cases, \fBPAM_RUSER\fR may be \fBNULL\fR.
+.TP
+.B prompt
+.BR PAM_USER_PROMPT .
+The string used when prompting for a user's name.  The default value
+for this string is:
+.sp
+.nh
+.na
+.B Please enter username: 
+.ad
+.hy
+.TP
+.B password
+.BR PAM_AUTHTOK .
+The authentication token (often a password).
+.SH OPTIONS
+.TP
+.BI config= FILE
+Read configuration from \fIFILE\fR instead of
+.BR \*(ET/pam_sql.conf .
+.TP
+\fBuse_authtok\fR
+Do not prompt the user for password, take it from the saved
+authentication tokens.
+.TP
+\fBdebug\fR\fB=\fINUMBER\fR]
+Set debugging level (0 <= \fINUMBER\fR <= 100).
+.TP
+\fBwaitdebug\fR
+Wait for \fIN\fR seconds before starting up.  This option is intended
+to facilitate attaching to the module with
+.BR gdb (1).
+It is available only if the package was configured with
+the \fB\-\-enable\-debug\fR option.
+.TP
+\fBaudit\fR
+Log auditing information.
+.SH MODULE TYPES PROVIDED
+.BR auth ,
+.BR session .
+.SH RETURN VALUES
+.TP
+.B PAM_SUCCESS
+Successful termination
+.TP
+.B PAM_AUTH_ERR
+Authentication failed.
+.TP
+.B PAM_USER_UNKNOWN
+Supplied username not found.
+.TP
+.B PAM_AUTHTOK_RECOVER_ERR
+Failed to obtain stored authentication token.  This code can be
+returned if \fBuse_authtok\fR was used.
+.TP
+.B PAM_SERVICE_ERR
+Some configuration or internal module error: required configuration
+parameter is missing, etc.
+.SH EXAMPLES
+.SS Simple authentication
+This example assumes the authentication table of the following
+structure:
+.PP
+.EX
+CREATE TABLE auth (
+   user char(32),
+   passwd char(128),
+   PRIMARY KEY (user_name)
+);
+.PP
+The configuration file will look like:
+.PP
+.EX
+# Authentication data
+host localhost
+db userdb
+login test
+pass guessme
+# Retrieve password from the database.
+passwd-query SELECT passwd\\
+             FROM auth\
+             WHERE user='${user}'
+.EE
+.SS Accounting
+This example assumes the accounting table of the following structure:
+.PP
+.EX
+CREATE TABLE acct (
+  type int,        -- 0 for active session, 1 for a terminated one
+  user char(32),   -- user name
+  host char(256),  -- remote host name
+  tty char(16),    -- tty name
+  service char(32),-- PAM service name
+  ts  datetime,    -- timestamp
+  duration int,    -- duration of the session if type==1
+  primary key (user,host,service,tty)
+);  
+.EE
+.PP
+The correspondig configuration statements (without the database
+credentials part) are:
+.EX
+session-start-query INSERT INTO acct\\
+                    (type, user, service, tty, host, ts)\\
+                    VALUES(0, $user, $service, $tty, $rhost, now())
+session-stop-query  UPDATE acct\\
+                    SET type=1, duration=now()-ts\\
+                    WHERE user='$user'\\
+                      AND host='$host'\\
+                      AND service='$service'\\
+                      AND tty='$tty'
+.EE
+.SS Setting the Environment
+This example assumes the following table structure:
+.PP
+.EX
+CREATE TABLE userprop (
+  user varchar(32),
+  dir varchar(128),
+  uid int,
+  gid int
+);
+.EE
+.PP
+The following 
+.B setenv\-query
+statement will set the \fBPAM\fR environment variables
+.BR home ,
+.BR uid ", and"
+.BR gid :
+.PP
+.EX
+setenv-query SELECT dir as home, uid, gid\\
+             FROM userprop\\
+             WHERE username='$user'
+.EE
+.SH NOTE
+This manpage is a short description of \fBpam_mysql\fR.  For a detailed
+discussion, including examples and usage recommendations, refer to the
+\fBPAM-modules Manual\fR available in texinfo format.  If the \fBinfo\fR
+reader and the tar documentation are properly installed on your
+system, the command
+.PP
+.RS +4
+.B info pam-modules
+.RE
+.PP
+should give you access to the complete manual.
+.PP
+You can also view the manual using the info mode in
+.BR emacs (1),
+or find it in various formats online at
+.PP
+.RS +4
+.B http://www.gnu.org.ua/software/pam-modules/manual
+.RE
+.PP
+If any discrepancies occur between this manpage and the
+\fBPAM-modules Manual\fR, the later shall be considered the authoritative
+source.
+.SH "SEE ALSO"
+.BR pam_pgsql (8),
+.BR pam.conf (5),
+.BR pam.d (5),
+.BR pam (8).
+.SH AUTHORS
+Sergey Poznyakoff <gray@gnu.org>
+.SH "BUG REPORTS"
+Report bugs to <bug\-pam\-modules@gnu.org.ua>.
+.SH COPYRIGHT
+Copyright \(co 2001-2014 Sergey Poznyakoff
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:
+
diff --git a/doc/pam_pgsql.8in b/doc/pam_pgsql.8in
new file mode 100644
index 0000000..6aa39bf
--- /dev/null
+++ b/doc/pam_pgsql.8in
@@ -0,0 +1,365 @@
+.\" This file is part of PAM-Modules -*- nroff -*-
+.\" Copyright (C) 2001-2014 Sergey Poznyakoff
+.\"
+.\" PAM-Modules is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\"
+.\" PAM-Modules is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with PAM-Modules.  If not, see
+.\" <http://www.gnu.org/licenses/>.
+.so config.so
+.TH PAM_PGSQL 8 "April 2, 2014" "PAM-MODULES" "Pam-Modules User Reference"
+.SH NAME
+pam_pgsql \- authenticate using a PostgreSQL database
+.SH SYNOPSIS
+.nh
+.na
+\fBpam_pgsql\fR [\fBconfig=\fIFILE\fR]\
+ [\fBuse_authtok\fR]\
+ [\fBdebug\fR[\fB=\fINUMBER\fR]]\
+ [\fBwaitdebug\fR]\
+ [\fBaudit\fR]
+.ad
+.hy
+.SH DESCRIPTION
+Provides authentication and account management services via a PostgreSQL
+database.
+.PP
+When used in the \fBauth\fR stack, the module first connects to the
+database using credentials supplied in the configuration file (see
+below).  Then, it retrieves the value of the \fBpasswd\-query\fR
+configuration parameter and performs \fBPAM\fR item expansion over
+it.  The resulting query is sent to the \fBSQL\fR server.  If this
+query produces a non-empty result, the first column from the first
+tuple is used as encrypted user password and is compared with the
+supplied authentication token.  If it matches, the user is
+authenticated successfully.  The comparison includes the following
+checks, performed in that order until one of them returns match or the
+list is exhausted: 
+.nr step 1 1
+.IP \n[step].
+Compare the retrieved password with the result of the system
+.BR crypt (3)
+function called with the authentication token and retrieved password
+as its arguments
+.IP \n+[step].
+Compare password with the MD5 sum of the authentication token.
+.IP \n+[step].
+Assume the password is encrypted using the
+.BR LDAP -style
+encoding and compare it accordingly.
+.IP \n+[step].
+Compare both strings literally.  This check is performed only if
+the
+.B allow\-plaintext\-pass
+configuration parameter is set.
+.PP
+Any of these checks can be disabled using the corresponding
+configuration setting.
+.SH CONFIGURATION
+The configuration information is supplied in a file
+.BR \*(ET/pam_sql.conf .
+An alternative location can be given via the \fBconfig\fR command line
+option.  The file is a usual UNIX-style configuration file with
+comments introduced by the \fB#\fR character.  Long statements can be
+split across several physical lines of text by ending each line but
+the last with a backslash character. 
+.PP
+The following statements are defined.
+.SS Database connection configuration
+.TP
+.BI host " NAME"
+Sets hostname or IP address of the PostgreSQL server.
+
+If the database is listening on the local socket, the \fINAME\fR
+is the pathname of the local socket.
+.TP
+.BI port " NUMBER"
+Sets the PostgreSQL port number.  The default value is 5432.
+.TP
+.BI db " NAME"
+Sets the database name.
+.TP
+.BI login " NAME"
+Sets the database user name.  The user must have \fBSELECT\fR
+privileges on tables in the database.
+.TP
+.BI pass " TEXT"
+Sets password for database access.
+.SS Queries
+These statements define \fBSQL\fR queries used by the module.  The
+argument of each statement is subject to
+.BR "PAM item expansion" ,
+which is described in detail in the following section.
+.TP
+.BI passwd\-query " QUERY"
+Defines \fBSQL\fR query to be used to obtain the user's password from the
+database.
+.TP
+.BI session\-start\-query " QUERY"
+Defines \fBSQL\fR query to be executed on session start.
+.TP
+.BI session\-stop\-query " QUERY"
+Defines \fBSQL\fR query to be executed on session termination.
+.TP
+.BI setenv\-query " QUERY"
+This query is available when the package is compiled with
+.B Linux PAM
+implementation.  The data it selects from the database are then
+stored in the \fBPAM\fR environment.  Only the first tuple returned
+is used; the column names are treated as environment variable names,
+and column values as their values. 
+.SS Password encryption
+The variables in this subsections control how the module treats
+passwords returned by the 
+.BR passwd\-query .
+Their argument is a boolean value: \fByes\fR, \fBtrue\fR or \fBt\fR,
+for true value and \fBno\fR, \fBfalse\fR or \fBf\fR, for false value.
+.TP
+.BI allow\-plaintext\-pass " BOOL"
+Controls whether the
+.B passwd\-query
+may return a plaintext password.
+.TP
+.BI allow\-ldap\-pass " BOOL"
+The returned password may be a
+.BR LDAP -style
+password hash, i.e. the hash value encoded as base-64 and prefixed
+with a hashing algorithm name in curly braces.  This variable is
+\fBtrue\fR by default. 
+.TP
+.BI allow\-md5-pass " BOOL"
+The returned password may be encrypted using \fBPostgreSQL md5\fR
+function.
+.SH PAM ITEM EXPANSION
+The query strings described in the previous section are subject to
+item expansion prior to being sent to the \fBPostgreSQL\fR server.  This
+feature is similar to the shell variable expansion.  During item
+expansion, any occurrence of \fB$\fINAME\fR is replaced with the