path: root/doc/pam-modules.texi

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

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

@include version.texi

@ifinfo
@dircategory System Utilities
@direntry
* PAM-modules: (pam-modules).       A collection of PAM modules.
@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 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

@page
@summarycontents
@page
@contents

@node Top, Intro, (dir), (dir)

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

@menu
* Intro::               Introduction to PAM-modules

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::                 Simple SQL authentication.                        
* Reporting Bugs::      How to Report a Bug.

Appendices

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

@end menu

@node Intro, fshadow, Top, Top
@chapter Introduction to PAM-modules

     PAM-modules is a collection of @acronym{PAM
modules} for user authentication and logging.  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.

     All modules from the package support the following command line
arguments:

@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 (user password, in particular). 

@opindex waitdebug, common option
@opindex enable-debug, @option{--enable-debug}, @command{configure} option
@item waitdebug[=@var{interval}]
     Wait for @var{interval} seconds before starting the operation.
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 AT pam_regex.c:240
@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

@node fshadow, regex, Intro, Top
@chapter Authentication against an alternative shadow file.

@prindex pam_fshadow
     This 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. 

@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 uses the
authentication token as the user name and verifies it 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 password
with the retrieved hash as its second argument (the @code{seed}) and
its result is compared with the hash.  If the two strings are the
same, the user is authenticated successfully.

     Otherwise, if @file{passwd} contains no password, the shadow file is
examined and the 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 supplied password (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.

@table @option
@opindex nopasswd, @command{pam_fshadow} option
@item nopasswd
     Do not require @file{passwd} file to be present.  Only
@file{shadow} is used for authentication.

@opindex sysconfdir, @command{pam_fshadow} option
@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.

@opindex use_authtok, @command{pam_fshadow} option
@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

@cindex virtual domain mode, pam_fshadow
@cindex pam_fshadow, virtual domain

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

@opindex regex, @command{pam_fshadow} option
@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 used to split the authentication token.  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 flavor of the
regular expression and the way of retrieving the authentication data
from the token.  These options are: 

@table @option
@opindex basic, @command{pam_fshadow} option
@item basic
     Use basic regular expression.  This is the default.

@opindex extended, @command{pam_fshadow} option      
@item extended
     Use extended regular expression.

@opindex ignore-case, @command{pam_fshadow} option
@opindex icase, @command{pam_fshadow} option     
@item ignore-case
@itemx icase
     Use case-insensitive regular expression.

@opindex revert-index, @command{pam_fshadow} option     
@item revert-index
     Use group 2 as the user name and group 1 as the authentication domain.
@end table

     To summarize, 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 for the password databases
under the @file{/etc/auth} directory.  For example, if the supplied
authentication token was @samp{smith@@ftp}, then the module will look
for the user name @samp{smith} in the files
@file{/etc/auth/ftp/passwd} and @file{/etc/auth/ftp/shadow}.

@node regex, log, fshadow, Top
@chapter Authentication using regular expressions.

@prindex pam_regex
     The module @command{pam_regex} allows to control user access by
matching their login name against a regular expression.  It
may be useful, for example, in authentication stacks for such services
as @acronym{FTP} or @acronym{HTTP}. 
     
@table @code
@opindex basic, @command{pam_regex} option
@item basic
     Use basic regular expression.

@opindex case, @command{pam_regex} option     
@item case
     Use case-insensitive regular expression.

@opindex extended, @command{pam_regex} option     
@item extended
     Use extended regular expression.

@opindex icase, @command{pam_regex} option
@opindex ignore-case, @command{pam_regex} option
@item ignore-case
@itemx icase
     Use case-insensitive regular expression.

@opindex regex, @command{pam_regex} option     
@item regex=@var{string}
     The user name must match the given regular expression.  This
option is mandatory.  The default expression flavor is
``basic, case-sensitive'', but this can be changed using other
options (see above).

@opindex sense, @command{pam_regex} option
@item sense=@{allow|deny@}
     What to do if user name matches the regexp.  Default is @samp{allow}.

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

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

@end table

     Here's an example of using this module:
     
@smallexample
httpd auth  required  pam_regex.so sense=deny regex=.*@@.*
@end smallexample

This example denies login for users whose login names contain the
@samp{@@} character.

@node log, sql, regex, Top
@chapter Log arbitrary messages to syslog.

@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 PAM
service stack.

     Before logging, each command line argument is subject to @dfn{variable
substitiution}.  During this phase, any occurrence of
@code{$@var{variable}} is substituted by the value of @var{variable}.
If the @var{variable} is not defined, emtpy string is substituted
instead.  A limited support for the shell-style default values is
available: namely, the notation
@code{$@{@var{variable}:-@var{value}@}} expands to the value of
@var{variable} if it is set, and to @var{value} otherwise. 

     The supported variables are:

@multitable @columnfractions .30 .50
@headitem Variable name @tab @acronym{PAM} variable
@item service @tab PAM_SERVICE 
@item user    @tab PAM_USER 
@item tty     @tab PAM_TTY 
@item rhost   @tab PAM_RHOST 
@item ruser   @tab PAM_RUSER 
@item prompt  @tab PAM_USER_PROMPT
@item password @tab PAM_AUTHTOK
@end multitable

     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.

     The following table lists all the supported options:

@table @option
@opindex -debug, @command{pam_log} option
@item -debug[=@var{level}]
Similar to @option{debug} in other modules (@pxref{Intro}).

@opindex -no-open, @command{pam_log} option
@item -no-open
Reserved for future use.

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

@opindex -pri, @command{pam_regex} option
@item -pri=@var{facility}.@var{priority}
Requests to 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} can be omitted, in which case
the following defaults are used: @var{facility}=@code{authpriv},
@var{priority}=@code{info}.

@opindex -tag, @command{pam_log} option
@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, Reporting Bugs, log, Top
@chapter Simple SQL authentication.

@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:
@command{pam_mysql}, for MySQL and @command{pam_pgsql} for
PostgreSQL.  Both modules share the same set of options and provide
similar functionality.  To authenticate a user, each module connects
to the database and issues a query which should return the user
password.  Then the obtained password is compared with the
authentication token, using a preconfigured algorithm.  If it matches,
the user is authenticated successfully. 

     The options, common for both modules are:

@table @option
@opindex use_authtok, @command{pam_mysql} option
@opindex use_authtok, @command{pam_pgsql} 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.

@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}.
@end table

@cindex configuration file, @command{pam_pgsql}
@cindex configuration file, @command{pam_mysql}
     The 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.

     The keywords, common for both modules are:

@table @code
@opindex host, @command{pam_mysql} configuration variable
@opindex host, @command{pam_pgsql} configuration variable
@item host @var{hostname}
Defines the host where the database is running.

@opindex port, @command{pam_mysql} configuration variable
@opindex port, @command{pam_pgsql} configuration variable
@item port @var{number}
Defines the SQL port number.

@opindex db, @command{pam_mysql} configuration variable
@opindex db, @command{pam_pgsql} configuration variable
@item db @var{database}
Sets the database name.

@opindex login, @command{pam_mysql} configuration variable
@opindex login, @command{pam_pgsql} configuration variable
@item login @var{string}
Sets the SQL user name.

@opindex pass, @command{pam_mysql} configuration variable
@opindex pass, @command{pam_pgsql} configuration variable
@item pass @var{password}
Sets the SQL user password

@opindex query, @command{pam_mysql} configuration variable
@opindex query, @command{pam_pgsql} configuration variable
@item query @var{query}
Defines the query used to obtain the user's password from the
database.  The query can contain the following meta-characters:

@cindex meta-characters in @acronym{SQL} queries
@cindex u, %u, a meta-character
@cindex p, %p, a meta-character
@cindex %, %%, a meta-character
@multitable @columnfractions .15 .40
@headitem Meta-char @tab Replaced by
@item %u @tab User name
@item %p @tab User password (authentication token)
@item %% @tab Literal @samp{%} character
@end multitable

@end table

     Variables, specific for @command{pam_pgsql}:

@table @code
@opindex allow-plaintext-pass, @command{pam_pgsql} configuration variable
@item allow-plaintext-pass @var{bool}
The returned password can be plaintext.  Without this option, it is
supposed to be encrypted using the system @code{crypt} function.
@end table

     Variables, specific for @command{pam_mysql}:
     
@table @code
@opindex allow-mysql-pass, @command{pam_mysql} configuration variable
@item allow-mysql-pass @var{bool}
The returned password can be encrypted using MySQL @code{password}
function.

@opindex allow-plaintext-pass, @command{pam_mysql} configuration variable
@item allow-plaintext-pass @var{bool}
The returned password can be plaintext.
@end table

@node Reporting Bugs, Copying This Manual, sql, Top
@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 when reporting a 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, Concept Index, Reporting Bugs, Top
@include fdl.texi

@node Concept Index,  , Copying This Manual, Top
@comment node-name,  next,  previous,  up
@unnumbered Concept Index

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

@printindex cp

@bye