pam-modules/doc/pam-modules.texi

\input texinfo @c -*-texinfo-*-
@smallbook
@c %**start of header
@setfilename pam-modules.info
@settitle PAM-modules Manual
@c %**end of header
@setchapternewpage odd

@defcodeindex pr
@defcodeindex op
@defcodeindex kw
@syncodeindex pr cp
@syncodeindex op cp
@syncodeindex kw cp

@include version.texi
@include macros.texi
@include rendition.texi

@ifinfo
@dircategory System Utilities
@direntry
* PAM-modules: (pam-modules).          A collection of PAM modules.
* pam_fshadow: (pam-modules)fshadow.   Authentication using an
                                       alternative shadow file.
* pam_regex:   (pam-modules)regex.     Access control using regular
                                       expressions.
* pam_mysql:   (pam-modules)sql.       MySQL authentication and
                                       session management.
* pam_pgsql:   (pam-modules)sql.       PostgreSQL authentication and
                                       session management.
* pam_log:     (pam-modules)log.       Format and log arbitrary
                                       messages to syslog.
* pamck:       (pam-modules)pamck.     Verify PAM Access.                                       
@end direntry
@end ifinfo

@copying
Published by the Free Software Foundation,
51 Franklin Street, Fifth Floor
Boston, MA 02110-1301, USA

Copyright @copyright{} 2005, 2007-2011 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
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.''
@end copying

@titlepage
@title PAM-modules
@subtitle version @value{VERSION}, @value{UPDATED}
@author Sergey Poznyakoff.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@ifnothtml
@page
@summarycontents
@page
@end ifnothtml
@contents

@ifnottex
@node Top
@top PAM modules

This edition of the @cite{PAM-modules Manual}, last updated @value{UPDATED},
documents PAM-modules Version @value{VERSION}.
@end ifnottex

@menu
* Intro::               Introduction to PAM-modules
* pamck::               Verify PAM Authentication

Individual modules

* fshadow::             Authentication against an alternative shadow
                        file.
* regex::               Check if the username matches certain regular
                        expression.
* log::                 Log arbitrary messages to syslog.
* sql::                 Modules for SQL authentication and session management.

* Reporting Bugs::      How to Report a Bug.

Appendices

* Copying This Manual:: The GNU Free Documentation License.
* Concept Index::       Index of Concepts.

@detailmenu
 --- The Detailed Node Listing ---

Authentication against an alternative shadow file.

* plain mode::
* virtual domain mode::
* summary of pam_fshadow options::

Authentication using regular expressions.

* access control::           Using pam_regex as access control module.
* user name transformation:: Using pam_regex to alter user names.
* summary of pam_regex options::

SQL Authentication and Session Management.

* config::      Configuration file.
* sql auth::    Using @acronym{SQL} modules in authentication stack.
* sql setenv::  Setting @acronym{PAM} environment from an
                @acronym{SQL} database.
* sql session:: Using @acronym{SQL} modules for session management.
* sql summary:: Summary of configuration statements.

@end detailmenu
@end menu

@node Intro
@chapter Introduction to PAM-modules
   
   PAM-modules is a collection of various pluggable authentication
modules.  This manual describes each module in detail.  The reader is
expected to be sufficiently proficient with general @acronym{UNIX}
administration issues and with Pluggable Authentication Modules
(@acronym{PAM}) in particular.  

   Each module is configurable from its command line.  Modules that
require such amounts of configuration data, that are inconvenient to
pass from the command line (@pxref{sql}), implement their separate
configuration files.

   Several command line options are common for all modules.  These are:

@anchor{common options}
@table @option
@opindex debug, common option
@cindex debugging hints
@item debug[=@var{level}]
   Change debugging level (0 <= @var{level} <= 100).  The debugging
information will be logged via @code{syslog} channel
@code{auth.debug}.  Notice, that debugging output can reveal
authentication credentials.  In particular, user password is displayed
on debugging level 100.

@opindex waitdebug, common option
@opindex enable-debug, @option{--enable-debug}, @command{configure} option
@item waitdebug[=@var{interval}]
   Wait for @var{interval} seconds before starting.  This option is
intended for the package developers and is not enabled, unless you
configure the package with @option{--enable-debug} option.  Most
probably you will not need this option.  The following 
description is provided in case you decide to participate in
@command{PAM-modules} development: 

   When this option is present, the module displays the
following diagnostics in @command{syslog} @code{auth.crit} channel:

@smallexample
WAITING FOR DEBUG
@end smallexample

@noindent
and waits for @var{interval} seconds (default 3600) before actually
starting to do anything.  The developer is supposed to attach to the
process with a debugger, set the @code{interval} variable to 0 and to
continue execution of the module in the debugging mode.
@end table

@cindex PAM item expansion
@cindex expansion, PAM item
@anchor{item expansion}
   Some modules perform @acronym{PAM} @dfn{item expansion} on their
arguments.  It is a feature similar to shell's variable expansion.
During item expansion, any occurrence of @code{$@var{name}} in a
string is replaced by the value of the @acronym{PAM} item @var{name}.
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 @code{$@{@var{item}:-@var{value}@}}
expands to the value of @var{item} if it is set, and to @var{value}
otherwise.  Notice, that @var{value} must be a literal value (string
or numeric).

   The following table lists @acronym{PAM} item names:

@table @samp
@item service
@code{PAM_SERVICE}.  The service name (which identifies
the @acronym{PAM} stack that will be used).

@item user
@code{PAM_USER}.  The username of the entity under whose identity
service will be given. 

@item tty
@code{PAM_TTY}.  The terminal name: prefixed by
@samp{/dev/} if it is a device file; for graphical, X-based,
applications the value for this item is usually the @env{$DISPLAY}
environment variable.

@item rhost
@code{PAM_RHOST}.  The requesting hostname (the hostname of the machine
from which the @code{PAM_RUSER} entity is requesting service).  That is
@samp{@code{PAM_RUSER}@@@code{PAM_RHOST}} identifies the requesting
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
requesting user or a remote requesting user.  In some cases,
@code{PAM_RUSER} may be @samp{NULL}.

@item prompt
@code{PAM_USER_PROMPT}.  The string used when prompting for a user's
name.  The default value for this string is @samp{Please enter
username: }.

@item password
@code{PAM_AUTHTOK}.  The authentication token (often a password).
@end table

   Item expansion is used by @command{pam_log}, @command{pam_mysql}
and @command{pam_pgsql}. 

@node pamck
@chapter Verify PAM Access
@prindex pamck

The @command{pamck} utility checks if a user can be authenticated using
@acronym{PAM}.  The user name is specified in the command line, so the
simplest invocation is:

@smallexample
$ pamck user
@end smallexample

When used this way, @command{pamck} first authenticates @samp{user},
by calling @code{pam_authenticate}, and then performs account
management (@code{pam_acct_mgmt}).  If both functions return success,
the utility prints @samp{OK} on the standard output and exits with
zero code.  In case of failure, it displays diagnostics on standard
error and exits with error code 2.

It exits with code 1 in case of usage error (e.g. wrong command line
option).

If password is required, the utility asks about it, and waits for the
user input.  When reading user input, terminal echo is turned off to
prevent password compromising.

Alternatively, the password may be given on the command line, as the
second argument:

@smallexample
$ pamck user pass
@end smallexample

By default, @command{pamck} uses @acronym{PAM} service @samp{check}.
Another service name may be supplied using the @option{-s} command
line option:

@smallexample
$ pamck -s login user
@end smallexample

The @option{-g} command line option allows to select the @acronym{PAM}
management group to check.  It takes the name of the group as an
argument.  Allowed group names are:

@table @asis
@item auth
Authentication group.  Call @code{pam_authenticate}.

@item acct
Account management.  Call @code{pam_acct_mgmt}.

@item open
Session management.  Call @code{pam_open_session}.

@item close
Session management.  Call @code{pam_close_session}.

@item pass
Password management.  Call @code{pam_chauthtok}.
@end table

The following table summarizes available command line options:

@table @option
@item -s @var{service}
Select service name to use.

@item -g @var{group}
Select @acronym{PAM} management group to check.

@item -h
Print short help summary and exit.

@item -v
Print program version and copyright information and exit.
@end table

@node fshadow
@chapter Authentication against an alternative shadow file.
@set MODULE pam_fshadow
@prindex pam_fshadow
   The @command{pam_fshadow} module provides authentication against an
alternative @file{shadow} file, or @file{passwd} / @file{shadow} pair
(or pairs).  There are two main operation modes: @dfn{plain} mode, in which
@command{pam_fshadow} uses only one @file{passwd}/@file{shadow} pair,
and @dfn{virtual domain} mode, which allows to select the pair to use
based on the authentication token (the user name).  First, let's
describe the plain mode. 

@menu
* plain mode::
* virtual domain mode::
* summary of pam_fshadow options::
@end menu

@node plain mode
@section Using @command{pam_fshadow} in plain mode.

@cindex plain mode, pam_fshadow
@cindex pam_fshadow, plain
   Plain mode is the default operation mode for @command{pam_fshadow}.
In this mode, the module checks the supplied user name and
authentication token against the @file{passwd}/@file{shadow} pair
located in the system configuration directory (which is set when
configuring the package and defaults to @file{@var{prefix}/etc}).
This default location can be changed using the @option{sysconfdir}
option (see below).  The authentication is performed as follows:

   First, the user name is looked up in @file{passwd} file and the
corresponding record is fetched.  If this record contains a valid
password hash (i.e. its second field is at least 2 characters long),
the system @code{crypt} function is called on the supplied
authentication token with the retrieved hash as its second argument
(the @code{seed}) and its result is compared with the hash.  If the
two strings compare equal, the user is authenticated successfully.

   Otherwise, if @file{passwd} contains no password, the shadow file is
examined and hash retrieved from there is used.  If the record
retrieved from the shadow file has not expired, and if its password
hash field matches the authentication token (using the algorithm
described above), the user is authenticated successfully.

   Several options are provided to alter the default behavior.  All
of them, except @command{sysconfdir}, have the same effect in the
virtual domain mode as well.  The table below summarizes these options.

@anchor{pam_fshadow common options}
@table @option
@xopindex{nopasswd, introduced}
@item nopasswd
   Do not require @file{passwd} file to be present.  Only
@file{shadow} is used for authentication.

@xopindex{noshadow, introduced}
@item noshadow
   Do not require @file{shadow} file to be present.  Only
@file{passwd} is used for authentication.  Notice, that it is an error
to specify both @code{nopasswd} and @code{noshadow}.

@xopindex{sysconfdir, introduced}
@item sysconfdir=@var{dir}
   Set full name of the directory where @file{shadow} and
@file{passwd} are located.  By default the system configuration
directory will be used.

@xopindex{use_authtok, introduced}
@item use_authtok       
   Do not prompt the user for password, take it from the saved
authentication tokens.  This option is useful when @command{pam_fshadow}
is used as a non-first module in a stack of authentication modules.
@end table

   The following example illustrates the use of @command{pam_fshadow} in
plain mode in @file{pam.conf} file: 

@smallexample
tuhs auth  required   pam_fshadow.so \
                      sysconfdir=/home/tuhs/tuhs/etc nopasswd use_authtok
@end smallexample

@node virtual domain mode
@section Using @command{pam_fshadow} in virtual domain mode.
@cindex virtual domain mode, pam_fshadow
@cindex pam_fshadow, virtual domain

   In @dfn{virtual domain} mode, @command{pam_fshadow} uses the
user name to determine where to look for the
@file{passwd}/@file{shadow} file pair.  The name is split into 
@dfn{user name proper} and @dfn{authentication domain}.  The 
configuration directory name is then constructed by concatenating the
system configuration directory, a directory separator character (@samp{/}),
and the name of the authentication domain.  Then, authentication
proceeds as described above for the plain mode.  If the supplied user name
does not match the regular expression, @command{pam_fshadow} proceeds
as in plain mode. 

@xopindex{regex, introduced}
@cindex enabling virtual domain mode, @command{pam_fshadow}
@cindex virtual domain mode, enabling (@command{pam_fshadow})
   This mode is enabled by the option @option{regex}, which supplies
a regular expression to split user names.  This
regular expression must contain two parenthesized @dfn{groups}.  First of
them is used to extract the user name, and the second one is used
to extract the authentication domain.  For example, the following option:

@smallexample
regex=(.*)@@(.*)
@end smallexample

@noindent
instructs @command{pam_fshadow} to use any characters before the
@samp{@@} as the user name, and anything following it as the
authentication domain.

   Several options are provided, that control the type of 
regular expression and the way of retrieving authentication data
from the user name.  These options are: 

@table @option
@xopindex{basic, introduced}
@item basic
   Use basic regular expression. 

@xopindex{extended, introduced}
@item extended
   Use extended regular expression.  This is the default.

@xopindex{ignore-case, introduced}
@xopindex{icase, introduced}
@item ignore-case
@itemx icase
   Use case-insensitive regular expression.

@xopindex{case, introduced}     
@item case
   Use case-sensitive regular expressions (default).

@xopindex{revert-index, introduced}
@item revert-index
   Use group #2 as the user name and group #1 as the authentication domain.
@end table

   As an example, consider the following @file{pam.conf} entry:

@smallexample     
check auth required pam_fshadow.so \
   sysconfdir=/etc/auth regex=(.*)@@(.*) extended 
@end smallexample

@noindent
It instructs @command{pam_fshadow} to use @samp{@@} as the
username/domain separator and to look up password databases
under the @file{/etc/auth} directory.  For example, if the supplied
user name was @samp{smith@@ftp}, then the module will look
for the user name @samp{smith} in files
@file{/etc/auth/ftp/passwd} and @file{/etc/auth/ftp/shadow}.

@node summary of pam_fshadow options
@section Summary of pam_fshadow options

This section summarizes all @command{pam_fshadow} command line options:

@table @option
@opsummary{basic}
@item basic
   Use basic regular expressions.  @xref{virtual domain mode}.

@opsummary{extended}
@item extended
   Use extended regular expression (default).  @xref{virtual domain mode}.

@opsummary{ignore-case}
@opsummary{icase}
@item ignore-case
@itemx icase
   Use case-insensitive regular expressions.  @xref{virtual domain mode}.

@opsummary{nopasswd}
@item nopasswd
   Use only @file{shadow} for authentication.  @xref{pam_fshadow common
options, nopasswd}.

@opsummary{noshadow}
@item nopasswd
   Use only @file{passwd} for authentication.  @xref{pam_fshadow common
options, noshadow}.

@opsummary{regex}
@item regex=@var{expr}
   Define a regular expression for splitting user name into the proper
name and authentication domain.

@opsummary{revert-index}
@item revert-index
   In the regular expression introduced by @code{regex}, group #1
selects authentication domain, and group #2 selects user name.
@xref{virtual domain mode, revert-index}.

@opsummary{sysconfdir}
@item sysconfdir=@var{dir}
   Assume @var{dir} as the system configuration directory.
@xref{pam_fshadow common options, sysconfdir}.

@opsummary{use_authtok}
@item use_authtok
   Do not prompt the user for password, take it from the saved
authentication tokens.

@xref{pam_fshadow common options, use_authtok}.

@end table

@node regex
@chapter Authentication using regular expressions.
@set MODULE pam_regex

@prindex pam_regex
   The module @command{pam_regex} is a general-purpose tool for 
authentication using regular expressions.  You can use it, for
example, to allow or deny access depending on whether the user name
matches a given regular expression.  Another possible use is to
modify user names following a predefined pattern (as in
@command{sed}), to supply modules that follow it in the @acronym{PAM}
stack with a normalized user name.

  As a quick start example, the following @file{pam.conf} entry
forbids access for any user names that look like email addresses:

@smallexample
httpd auth  required  pam_regex.so sense=deny regex=.*@@.*
@end smallexample

  Here, the argument @option{regex} supplies a regular expression to
match against, and @option{sense=deny} states that any name matching
this expression must be denied.

@menu
* access control::           Using pam_regex as access control module.
* user name transformation:: Using pam_regex to alter user names.
* summary of pam_regex options::
@end menu

@node access control
@section Using @command{pam_regex} to control access.

@xopindex{regex, described}
   To control access depending on supplied user name, two options
are provided.  The option @option{regex} introduces a regular
expression with which to compare a user name:

@table @option
@item regex=@var{expression}
   Compare user name with @var{expression}.  By default, extended
regular expressions with case-sensitive matching are used, but 
this can be changed using other options (see below).
@end table

   When this option is used, @command{pam_regex} allows only login
attempts with user names that match @var{expression}.  The
@option{sense} command line option is provided to control that
behavior:

@table @option
@xopindex{sense, described}
@item sense=@{allow|deny@}
   What to do if the user name matches the @var{expression}.  The value
@samp{allow} means to return @code{PAM_SUCCESS}, @samp{deny} means to
return @code{PAM_AUTH_ERR}.  Default is @samp{allow}.
@end table

@node user name transformation
@section Using @command{pam_regex} to alter user names.

  Another common use for @command{pam_regex} is to alter user names.
This mode is enabled when the @option{transfer} option is used in the
command line:

@table @option
@xopindex{transform, described}
@item transform=@var{expression}
   Transform the user name using given regular expression.
@end table

   Its argument, @var{expression}, is a @command{sed}-like replace
expression of the form:

@smallexample
s/@var{regexp}/@var{replace}/[@var{flags}]
@end smallexample

@noindent
where @var{regexp} is a @dfn{regular expression}, @var{replace} is a
replacement for each file name part that matches @var{regexp}.  Both
@var{regexp} and @var{replace} are described in detail in
@ref{The "s" Command, The "s" Command, The `s' Command, sed, GNU sed}.

As in @command{sed}, you can give several replace expressions,
separated by a semicolon.

Supported @var{flags} are:

@table @samp
@cindex g, @option{transform} flag, @command{@value{MODULE}}
@item g
Apply the replacement to @emph{all} matches to the @var{regexp}, not
just the first.

@cindex i, @option{transform} flag, @command{@value{MODULE}}
@item i
Use case-insensitive matching

@cindex x, @option{transform} flag, @command{@value{MODULE}}
@item x
@var{regexp} is an @dfn{extended regular expression} (@pxref{Extended
regexps, Extended regular expressions, Extended regular expressions,
sed, GNU sed}).

@item @var{number}
Only replace the @var{number}th match of the @var{regexp}.

Note: the @var{posix} standard does not specify what should happen
when you mix the @samp{g} and @var{number} modifiers.  @command{Pam_regex}
follows the GNU @command{sed} implementation in this regard, so
the interaction is defined to be: ignore matches before the
@var{number}th, and then match and replace all matches from the
@var{number}th on.

@end table

Any delimiter can be used in lieue of @samp{/}, the only requirement being
that it be used consistently throughout the expression.  For example,
the following two expressions are equivalent:

@smallexample
@group
s/one/two/
s,one,two,
@end group
@end smallexample

  Changing delimiters is often useful when the @var{regex} contains
slashes.  For instance, it is more convenient to write @code{s,/,-,} than
@code{s/\//-/}.

  The following example converts the user name to
lower case and removes any suffix starting from the @samp{@@} symbol:

@smallexample
@group
pam_regex.so extended transform=s/.*/\L&/g;s/@@.*// 
@end group
@end smallexample

  Both @option{transform} and @option{regex} can be used
simultaneously.  For example, the following command line first
converts the user name to lower case and removes anything after the
@samp{@@} symbol, and then compares it to the given regular
expression.  Access is denied if the resulting user name matches
the expression.  

@smallexample
@group
pam_regex.so extended transform=s/.*/\L&/g;s/@@.*// \
             regex=^(anoncvs|anonymous)$ sense=deny
@end group
@end smallexample

@node summary of pam_regex options
@section Summary of @command{pam_regex} options:

@table @option
@opsummary{basic}
@item basic
   Use basic regular expressions.

@opsummary{case}     
@item case
   Use case-sensitive regular expressions (default).

@opsummary{extended}     
@item extended
   Use extended regular expressions (default).

@opsummary{icase}
@opsummary{ignore-case}
@item ignore-case
@itemx icase
   Use case-insensitive regular expressions.

@opsummary{regex}
@item regex=@var{expression}
   Compare user name with @var{expression}.  

@opsummary{sense}
@item sense=@{allow|deny@}
   What to do if user name matches the @var{expression}.  The value
@samp{allow} means to return @code{PAM_SUCCESS}, @samp{deny} means to
return @code{PAM_AUTH_ERR}.  Default is @samp{allow}.

@opsummary{user}
@item user=@var{string}
   Upon successful matching, set @acronym{PAM} user name to @var{string}.

@end table

@node log
@chapter Log arbitrary messages to syslog.
@set MODULE pam_log

@prindex pam_log
   The @command{pam_log} module is a diagnostic tool.  It works
similarly to the shell @command{echo} command, outputting its
arguments to the @command{syslog}.  The module can be used in any
@acronym{PAM} service stack.

   In order to be discerned from arguments, all @command{pam_log}'s
options begin with a dash (@samp{-}).  They must precede any
non-option arguments.  If the first non-option argument happens to
begin with a dash, you can inhibit its special handling by placing
@samp{--} before it.

   After collecting all options, the module scans the rest of its
command line arguments, performs item expansion (@pxref{item
expansion}) and outputs the resulting string to the syslog. 

     The following table lists all the supported options:

@table @option
@opsummary{-audit}
@item -audit
Similar to @option{audit} in other modules (@pxref{Intro}).

@opsummary{-debug}
@item -debug[=@var{level}]
Similar to @option{debug} in other modules (@pxref{Intro}).

@opsummary{-noopen}
@item -noopen
Reserved for future use.

@opsummary{-waitdebug}
@item -waitdebug[=@var{interval}]
Similar to @option{waitdebug} in other modules (@pxref{Intro}).

@opsummary{-pri}
@item -pri=@var{facility}.@var{priority}
Send log messages to the given syslog facility and
priority.  The @var{facility} part can be any of: @samp{user},
@samp{daemon}, @samp{auth}, @samp{authpriv}, @samp{local0}, @samp{local1},
@samp{local2}, @samp{local3}, @samp{local4}, @samp{local5}, @samp{local6},
@samp{local7}. 

   The @var{priority} is any of the following: @samp{emerg}, @samp{alert}, 
@samp{crit}, @samp{err}, @samp{warning}, @samp{notice}, @samp{info},
@samp{debug}. 

   Either @var{facility} or @var{priority} (but not both) can be
omitted, in which case the following defaults are used:
@var{facility}=@code{authpriv}, @var{priority}=@code{info}.

@opsummary{-tag}
@item -tag=@var{label}
Use @var{label} as the syslog tag, instead of the module name.
@end table

   The following example illustrates the use of this module:

@smallexample
@group
cvs auth       required  pam_regex.so extended \
    regex=^(anoncvs|anonymous)$ sense=allow 
cvs account    requisite pam_log.so -tag CVS-ACCESS \
    -pri=daemon.info User $@{user:-unknown@} is granted CVS access
cvs account    required   pam_permit.so
cvs session    required   pam_permit.so
@end group
@end smallexample

@node sql
@chapter SQL Authentication and Session Management.
@set MODULE pam_sql
@prindex pam_pgsql
@prindex pam_mysql
@cindex MySQL, using for authentication
@cindex PostreSQL, using for authentication
   The package provides two modules for @acronym{SQL} authentication
and session management: @command{pam_mysql}, for MySQL and
@command{pam_pgsql} for PostgreSQL.  Both modules share the same set
of options and provide similar functionality.  

   Connecting to an @acronym{SQL} database requires a set of
credentials that cannot be conveniently passed via the command
line.  Therefore, both @acronym{SQL} modules use a special
@dfn{configuration file} to obtain the necessary data.  By default,
this file is located in the system configuration directory (usually,
@file{/usr/local/etc}), and is named @file{pam_sql.conf}.  However,
another location can be specified in the command line, using
@option{config} command line option.

  The command line options understood by both modules are:

@table @option
@opindex config, @command{pam_sql} option
@opindex config, @command{pam_pgsql} option
@opindex config, @command{pam_mysql} option
@item config=@var{file}
     Read SQL access credentials from the given @var{file}.

@opindex use_authtok, @command{pam_sql} option
@opindex use_authtok, @command{pam_pgsql} option
@opindex use_authtok, @command{pam_mysql} option
@item use_authtok       
   Do not prompt the user for password, take it from the saved
authentication tokens.  This option is useful when this module is
not the first in the stack of authentication modules.
@end table

@menu
* config::      Configuration file.
* sql auth::    Using @acronym{SQL} modules in authentication stack.
* sql setenv::  Setting @acronym{PAM} environment from an
                @acronym{SQL} database.
* sql session:: Using @acronym{SQL} modules for session management.
* sql summary:: Summary of configuration statements.
@end menu

@node config
@section Configuration File.
@cindex configuration file, @command{pam_pgsql}
@cindex configuration file, @command{pam_mysql}
   Configuration file has a simple line-oriented syntax.  Empty
lines and lines beginning with @samp{#} are ignored.  Nonempty lines
consist of a keyword and its value, separated by any amount of 
white space.

   Long statements can be split over several lines by placing
@samp{\} character at the end of each line, e.g.:

@smallexample
@group
query select password \
      from users \
      where user_name='$user'
@end group
@end smallexample

   Basic configuration statements provide @acronym{SQL} credentials
needed for accessing the database:

@table @code
@xkwindex{host, described}
@item host @var{hostname}
   Sets hostname or @acronym{IP} address of the machine where the database is
running.  If the database is only listening on the local socket
(@option{--skip-networking} for MySQL, or lack of @option{-i} for
PostgreSQL), then @code{host} should be the name of the local socket.

@xkwindex{port, described}
@item port @var{number}
   Sets the @acronym{SQL} port number.  This statement is optional.  Use it
only if your database is running on a port different from the standard.

@xkwindex{db, described}
@item db @var{database}
   Sets database name.

@xkwindex{login, described}
@item login @var{string}
   Sets @acronym{SQL} user name.

@xkwindex{pass, described}
@item pass @var{password}
   Sets @acronym{SQL} user password.
@end table

@node sql auth
@section Using @acronym{SQL} modules in authentication stack.
@cindex SQL authentication
@cindex authentication, SQL
@cindex authentication, pam_mysql
@cindex authentication, pam_pgsql
@cindex pam_mysql authentication
@cindex pam_pgsql authentication
@xkwindex{passwd-query, described}
When used in the @code{auth} stack, both @acronym{SQL} modules work as
follows.  First, the module connects to the database using credentials
supplied in the configuration file (see the previous section).  Then,
it retrieves the value of @code{passwd-query} from the configuration
file and performs @acronym{PAM} item expansion over it (@pxref{item
expansion}).  The resulting query is sent to the @acronym{SQL}
server.  If this query produces a non-empty result, the
first column from the first tuple is used as encrypted user password and
compared with the supplied authentication token.  If
it matches, the user is authenticated successfully.  The comparison
consists of the following checks, performed in that order until
one of them returns match or the list is exhausted:

@enumerate 1
@item System @code{crypt} function.
@item MySQL password encoding algorithm (for MySQL only)
@item Compare @acronym{MD5} sum of the token with the encrypted
password.
@item Compare passwords using @acronym{LDAP} algorithm.
@item Compare both strings literally (only if
@code{allow-plaintext-pass} is set in the configuration file.
@end enumerate

   The following configuration keywords can be used to disable or
enable particular stages of the comparison.  The value @var{bool}
should be @samp{yes}, @samp{true} or @samp{t} to indicate
@code{true}.  Any other value is taken to mean @code{false}.

@table @code
@xkwindex{allow-plaintext-pass, described}
@item allow-plaintext-pass @var{bool}
The returned password may be plaintext.  Without this option, it is
supposed to be encrypted using the system @code{crypt} function.

@xkwindex{allow-ldap-pass, described}
@item allow-ldap-pass @var{bool}
The returned password may be a @acronym{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 @code{true} by
default. 

@kwindex allow-md5-pass, @command{pam_mysql} configuration keyword
@item allow-md5l-pass @var{bool}
The returned password may be encrypted using MySQL @code{md5}
function.  This keyword is specific for @command{pam_mysql}.

@kwindex allow-mysql-pass, @command{pam_mysql} configuration keyword
@item allow-mysql-pass @var{bool}
The returned password may be encrypted using MySQL @code{password}
function.  This keyword is specific for @command{pam_mysql}.
@end table

@node sql setenv
@section Setting @acronym{PAM} environment from an @acronym{SQL} database.
@cindex environment, setting from @code{pam_mysql} or @code{pam_pgsql}
@cindex Linux PAM
   This is an experimental feature, available when compiled with
@command{Linux PAM} libraries.  It allows to pass some additional
information from the database to the application program using
@acronym{PAM} environment.

@xkwindex{setenv-query, described}
   Special configuration keyword @code{setenv-query} defines an
@acronym{SQL} query for setting the environment.  After expanding
@acronym{PAM} items (@pxref{item expansion}), this query is executed
and the first tuple (row) is taken from its result.  Each column in
this tuple creates an environment variable: the column name becomes
the name of environment variable, the column value becomes the
variable value.

   Consider for example, the following @acronym{SQL} table:

@smallexample
CREATE TABLE userprop (
  username varchar(32),
  dir varchar(128),
  uid int,
  gid int
);
@end smallexample
@noindent
which contains, among others, the following data:

@smallexample
("smith", "/var/spool/dir/1", 16, 10000)
@end smallexample

@noindent
   Let the configuration file contain this query definition:

@smallexample
setenv-query SELECT dir as home, uid, gid \
             FROM userprop \
             WHERE username='$user'
@end smallexample

@noindent
Now assume that the user @samp{smith} is authenticated using
@command{pam_mysql}.  The @code{setenv-query} is executed.  Then,
after @code{pam_authenticate} the @acronym{PAM} environment will
contain: 

@smallexample
home=/var/spool/dir/1
uid=16
gid=10000
@end smallexample

@node sql session
@section Using @acronym{SQL} modules for session management.
@cindex SQL session management
@cindex session management, SQL
   Both @command{pam_mysql} and @command{pam_pgsql} can be used for
session management.  This makes it possible to use your @acronym{SQL}
database instead of system @file{wtmp}/@file{utmp} files, or as a
complement to them.

   To enable SQL session management, the configuration file must
define the following two variables:

@table @command
@xkwindex{session-start-query, described}
@item session-start-query @var{query}
Defines the query to be executed when the session begins.

@xkwindex{session-stop-query, described}
@item session-stop-query @var{query}
Defines the query to be executed when the session ends.  
@end table

   Before executing, both queries are subject to item expansion
(@pxref{item expansion}).

   As an example, consider the following configuration file
statements:
   
@smallexample
session-start-query INSERT INTO acct \
                    (status, username, tty, starttime) \
                    VALUES(0, '$user', now(), '$tty')
session-stop-query  UPDATE acct \
                    SET status=1,
                        sessiontime=age(now(), starttime) \
                    WHERE username='$user'
@end smallexample

   They assume that the PostgreSQL table @samp{acct} has the following
structure: 

@table @code
@item status int
Status of the record: @samp{0} if the session is active, @samp{1} if
it is closed.

@item username varchar(32)
User name.

@item tty varchar(16)
@acronym{TTY} from where the user logged in.

@item starttime timestamp
Time when the session was started.

@item sessiontime interval
Duration of the session if @code{status=1}.
@end table

@node sql summary
@section Summary of configuration statements.
   This section summarizes all available configuration file statements.
For each statement it provides a short description and a reference to
the section in this manual where it is described.

@table @code
@kwsummary{allow-ldap-pass}
@item allow-ldap-pass @var{bool}
   The returned password may be a @acronym{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 @code{true} by
default.  @xref{sql auth}.

@kwsummary{allow-md5-pass}
@item allow-md5l-pass @var{bool}
   The returned password may be encrypted using MySQL @code{md5}
function.  This keyword is specific for @command{pam_mysql}.
@xref{sql auth}.

@kwsummary{allow-mysql-pass}
@item allow-mysql-pass @var{bool}
The returned password may be encrypted using MySQL @code{password}
function.  This keyword can be used only in @command{pam_mysql}
configuration.  @xref{sql auth}.

@kwsummary{allow-plaintext-pass}
@item allow-plaintext-pass @var{bool}
   The returned password may be plaintext.  Without this option, it is
supposed to be encrypted using the system @code{crypt} function.
@xref{sql auth}. 

@kwsummary{db}
@item db @var{database}
   Sets the database name.  @xref{config}.

@kwsummary{host}
@item port @var{number}
   Defines the SQL port number.  @xref{config}.

@kwsummary{login}
@item login @var{string}
   Sets the SQL user name.  @xref{config}.

@kwsummary{pass}
@item pass @var{password}
   Sets the SQL user password.  @xref{config}. 

@kwsummary{passwd-query}
@item passwd-query @var{query}
   Defines the query used to obtain the user's password from the
database.  The @var{query} is subject to item expansion
(@pxref{item expansion}).

   @xref{sql auth}, for a detailed description.
   
@kwsummary{session-start-query}
@item session-start-query @var{query}
   Defines the query to be executed on session start.  The @var{query} is
subject to item expansion (@pxref{item expansion}).  @xref{sql
session}, for a detailed description.

@kwsummary{session-stop-query}
@item session-stop-query @var{query}
   Defines the query to be executed on session stop.  The @var{query} is
subject to item expansion (@pxref{item expansion}).  @xref{sql
session}, for a detailed description.

@kwsummary{setenv-query}
@item setenv-query @var{query}
   This query is available when the package is compiled with @code{Linux
PAM} implementation.  It allows to select arbitrary data from the
database and to store them in @acronym{PAM} environment.  The
first tuple returned from @var{query} is selected, the column names
are used as environment variable names, and column values as their
values. 

The @var{query} is subject to item expansion (@pxref{item expansion}).

@xref{sql setenv}, for a detailed description.
@end table

@node Reporting Bugs
@chapter How to Report a Bug

Email bug reports to @email{bug-pam-modules@@gnu.org.ua}.

As the purpose of bug reporting is to improve software, please be sure
to include maximum information that is needed to reproduce the bug.
The information needed is:

@itemize
@item Version of the package you are using.
@item Compilation options used when configuring the package.
@item Conditions under which the bug appears.
@end itemize

@node Copying This Manual
@appendix GNU Free Documentation License
@include fdl.texi

@node Concept Index, 
@comment node-name,  next,  previous,  up
@unnumbered Concept Index

This is a general index of all issues discussed in this manual.

@printindex cp

@bye