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.
* pam_ldaphome (pam-modules)ldaphome.  Maintain home directories and
                                       SSH keys od LDAP users.
* pam_umotd    (pam-modules)umotd.     Display a user-specific MOTD.
* pam_groupmember (pam_modules)groupmember. Test group membership.
* pam_innetgr  (pam-modules)innetgr.   Check NIS netgroup.
* pamck:       (pam-modules)pamck.     Verify PAM Access.
* usergitconfig: (pam-modules)usergitconfig.  Initialize user @file{.gitconfig} file.
* ldappubkey:    (pam-modules)ldappubkey.     Get user's public ssh keys from the LDAP database.
@end direntry
@end ifinfo

@copying
Copyright @copyright{} 2005--2022 Sergey Poznyakoff

Permission is granted to copy, distribute and/or modify this document
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, and no special Front- or Back- Cover texts.
@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.
* ldaphome::            Maintain home directories and SSH keys of LDAP users.
* umotd::               Display a user-specific MOTD.
* groupmember::         Test group membership.
* innetgr::             Check NIS netgroup.

* 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::
* disabling password checking::
* 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.

pam_ldaphome

* ldaphome example::
* ldappubkey::
* usergitconfig::

Example of pam_ldaphome configuration

* 5.x::         Openssh versions prior to 6.2p1.
* 6.2p1::       Openssh versions 6.2p1 and newer.

pam_umotd

* summary of pam_umotd options::

pam_groupmember

* summary of pam_groupmember options::

@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 audit, common option
@item audit
Log full debugging information (equivalent to @code{debug=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 name 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

@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::
* disabling password checking::
* 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 disabling password checking
@section Disabling password checking

You can instruct @command{pam_fshadow} to skip password checking using
the @code{skip-password} option.  When given this option,
the module will only check whether the user is listed in the password
and/or shadow files, and whether the user's account in the latter is
active and has not expired.  This way @command{pam_fshadow} can 
be used as an auxiliary module in the stack, actual authentication being
performed by one of the modules before it.

This option can be used both in plain and in virtual domain mode.  The
use of either file (but not both) can be disabled by the
@code{nopasswd} and @code{noshadow} options.

@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 noshadow
   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{skip-password}
@item skip-password
Skip password verification.  Check only that the user name is listed
in the password and/or shadow files.  @xref{disabling password checking}.

@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{transform} 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.

@xkwindex{default-file, described}
@item default-file @var{file}
Name of the MySQL @dfn{default file}, which should be consulted in
order to obtain connection parameters and credentials.  When
specified, the keywords described above become optional.

@xkwindex{default-group, described}
@item default-group @var{name}
Name of the @dfn{group} in MySQL default file to use.  Default is
@samp{mysql}.  This keyword is meaningful only if @code{default-file}
is given.
@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-md5-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 ldaphome
@chapter pam_ldaphome
@c Maintain home directories and SSH keys of LDAP users.
@set MODULE pam_ldaphome
The @command{pam_ldaphome} facilitates maintenance of a centralized
LDAP user database.  It can be installed as a part of
authentication or session management stack.  When invoked, it creates
the user home directory, if it does not already exist, and ensures his
@file{.ssh/authorized_keys} is in sync with the database.

Apart from common options, this module understands only one
implementation-specific option:

@table @option
@opindex config, @command{pam_ldaphome} option
@item config=@var{file}
Read configuration from @var{file}.  Default is
@file{pam_ldaphome.conf} in @var{sysconfdir}.
@end table

Actual module configuration is read from the configuration file.

@menu
* ldaphome config::
* ldaphome example::
* ldappubkey::
* usergitconfig::
@end menu

@node ldaphome config
@section Configuration file for @command{pam_ldaphome}

@command{Pam_ldaphome} reads its configuration from two files: the
configuration file supplied with the @command{config} command line
option and the system-wide LDAP configuration file
@file{/etc/ldap.conf}.

The syntax of the former is described in @ref{config, SQL configuration
file}.  Allowed keywords are discussed below.

The syntax of the @file{/etc/ldap.conf} configuration file is
described in @ref{ldap.conf,,LDAP configuration file,ldap.conf(5),
ldap.conf(5) manpage}.  Its parsing can be suppressed using the
@command{ldap-config} statement (see below).

From @file{/etc/ldap.conf}, the following statements are used:
@samp{base}, @samp{binddn}, @samp{bindpw}, @samp{tls_cacert},
@samp{uri}.  The @samp{ssl} statement is understood if its value is
@samp{start_tls} or @samp{off}.  Other values are silently ignored.

In general, all statements defined below can appear in both files.
However, since @file{/etc/ldap.conf} is read by other system utilities
as well, we do not recommend using @command{pam_ldaphome}-specific
keywords in it.

The values read from @command{pam_ldaphome} configuration file
override those obtained from the standard LDAP configuration file.

@subheading LDAP configuration

@deffn {pam_ldaphome config} base @var{searchbase}
Use @var{searchbase} as the starting point for the search instead of
the default, e.g.:

@example
base dc=gnu,dc=org,dc=ua
@end example
@end deffn

@deffn {pam_ldaphome config} binddn @var{dn}
Use the Distinguished Name @var{dn} to bind to the LDAP directory.
Example:

@example
binddn cn=Manager,dc=gnu,dc=org,dc=ua
@end example
@end deffn

@deffn {pam_ldaphome config} bindpw @var{password}
If @code{binddn} statement is used, this statement supplies the
password for simple authentication.
@end deffn

@deffn {pam_ldaphome config} bindpwfile @var{file}
Read password for simple authentication from @var{file}.
@end deffn

@deffn {pam_ldaphome config} filter @var{expr}
Sets the LDAP filter expression to return a user profile.  The
@var{expr} should conform to the string representation for search
filters as defined in RFC 4515.
@end deffn

@deffn {pam_ldaphome config} ldap-config @var{file}
Read LDAP configuration from @var{file} (default --
@file{/etc/ldap.conf}).  Special value @samp{none} disables this
feature.
@end deffn

@deffn {pam_ldaphome config} ldap-version @var{v}
Sets the LDAP version to use.  Valid values for @var{v} are @samp{2}
and @samp{3} (the default).
@end deffn

@deffn {pam_ldaphome config} pubkey-attr @var{text}
Defines the name of the attribute which holds the user public key.
@end deffn

@deffn {pam_ldaphome config} tls @var{val}
Controls whether TLS is desired or required.  If @var{val} is
@samp{no} (the default), TLS will not be used.  If it is @samp{yes},
the module will issue the @samp{StartTLS} command, but will continue
anyway if it fails.  Finally, if @var{val} is @samp{only}, TLS is
mandatory, and the module will not establish LDAP connection unless
@samp{StartTLS} succeeds.
@end deffn

@deffn {pam_ldaphome config} tls-cacert @var{val}
@deffnx {pam_ldaphome config} tls_cacert @var{val}
Full pathname to the CA certificate file.  Used if TLS is enabled.
The second form (@samp{tls_cacert}) is for use in
@file{/etc/ldap.conf} file.
@end deffn

@deffn {pam_ldaphome config} uri @var{arg}
Sets the URI of the LDAP server to consult for the user profile.
Example:

@example
uri ldap://127.0.0.1/
@end example
@end deffn

@subheading Home directory creation
@deffn {pam_ldaphome config} allow-home-dir @var{path}
If present, this option controls where @command{pam_ldaphome} should
try to create home directories.  Its value is a list of directories
separated by colons.  The user's home directory will be created only
if the directory part of its name is listed in @var{path}.
@end deffn

@deffn {pam_ldaphome config} copy-buf-size @var{n}
Sets the size of the buffer used to copy files from the skeleton
directory to the newly created home.  The default size is 16384 bytes.
@end deffn

@deffn {pam_ldaphome config} home-dir-mode @var{mode}
Sets the mode (octal) for the created user directories.
@end deffn

@deffn {pam_ldaphome config} skel @var{dir}
Supplies the name of a @dfn{skeleton directory}.  The contents of this
directory is copied to the newly created user home directory.  The
file modes and permissions are preserved.
@end deffn

@subheading Authorized keys file
@deffn {pam_ldaphome config} authorized_keys @var{name}
Sets the pathname (relative to the home directory) for the authorized
keys file.  The default is @samp{.ssh/authorized_keys}.  For normal
operation, this value must be the same as the value of
@samp{AuthorizedKeysFile} variable in @file{sshd_config}.  Unless you
change the latter, there's no need to edit it.
@end deffn

@deffn {pam_ldaphome config} import-public-keys @var{bool}
When set to @samp{no}, disables importing public keys from LDAP.  You
may wish to use this option if you are using @command{openssh} 6.1 or
later with @command{ldappubkey} as @samp{AuthorizedKeysCommand}.
@end deffn

@deffn {pam_ldaphome config} keyfile-mode @var{mode}
Sets the mode (octal) for the created authorized keys file.
@end deffn

@deffn {pam_ldaphome config} user-keys-boundary @var{string}
User key files can contain both keys managed by @command{pam_ldaphome}
and added by the user.  These two groups of keys must be separated by
a special comment line, which informs the module that all keys
below it must be retained.

This feature is enabled by the @code{user-keys-boundary} setting.
The delimiting comment is formed as @samp{#@var{string}}.  E.g. if the
configuration file contains:

@example
user-keys-boundary :user-defined
@end example

@noindent
then the line @samp{#:user-defined} can be used to delimit
ldap-synchronized and user-specific keys.
@end deffn

@subheading Access control
@deffn {pam_ldaphome config} allow-groups @var{group} [@var{group}...]
Only handle members of the listed groups.
@end deffn

@deffn {pam_ldaphome config} min-gid @var{n}
Sets the minimal GID.  For users with GIDs less than @var{n},
@command{pam_ldaphome} returns PAM_SUCCESS immediately.
@end deffn

@deffn {pam_ldaphome config} min-uid @var{n}
Sets the minimal UID.  For users with UIDs less than @var{n},
@command{pam_ldaphome} returns PAM_SUCCESS immediately.  This allows
you to have a set of basic users whose credentials are kept in the
system database and who will not be disturbed by
@command{pam_ldaphome}.  See also @samp{min-gid} and
@samp{allow-groups}.
@end deffn

@subheading Initialization script
The following statements instruct @command{pam_ldaphome} to invoke an
external command after initializing the user home directory.  This can
be used to customize the files copied from the skeleton directory
according to the user.

@deffn {pam_ldaphome config} exec-timeout @var{seconds}
Sets maximum time the @command{initrc-command} is allowed to run.  If
it runs longer than @var{seconds}, it will be terminated with a
@samp{SIGKILL}, and the module will return PAM_SYSTEM_ERR.
@end deffn

@deffn {pam_ldaphome config} initrc-command @var{command}
Run @command{command} after populating the user home directory with
files from the skeleton directory.

The user login name is passed to the command as its argument.  Before
invoking, the current working directory is changed to the user home,
standard input is closed, and standard output is redirected to
standard errror.

The command is run under the current user privileges, unless the
variable @option{initrc-root} is set to true.

The command should exit with code 0 on success.  If it exits with a
non-zero code, @command{pam_ldaphome} will report
@samp{PAM_SYSTEM_ERR}.
@end deffn

@deffn {pam_ldaphome config} initrc-root @var{bool}
When set to @code{true}, @command{initrc-command} will be run with
root privileges.  In this case, the environment variable
@env{PAM_LDAPHOME_USER} will be initialized to the name of the
user who is trying to log in.
@end deffn

@deffn {pam_ldaphome config} initrc-log @var{file}
This statement redirects the standard output and error from the 
@command{initrc-command} to @var{file}.
@end deffn

@deffn {pam_ldaphome config} initrc-environ @var{env} ...
Modifies the environment of @command{initrc-command}.

This statement takes one or more arguments.  Each argument can be one
of:

@table @asis
@item - (a dash)
Clear the environment.  This is understood only when used as the first
argument.

@item -@var{name}
Unset the environment variable @var{name}.

@item -@var{name}=@var{val}
Unset the environment variable @var{name} only if its value is @var{val}.

@item @var{name}
Retain the environment variable @var{name}.

@item @var{name}=@var{value}
Define environment variable @var{name} to have given @var{value}.

@item @var{name}+=@var{value}
Retain variable @var{name} and append @var{value} to its existing
value.  If no such variable is present in the environment, it is
created and @var{value} is assigned to it.  However, if @var{value}
begins with a punctuation character, this character is removed from it
before the assignment.  This is convenient for using this construct with
environment variables like @env{PATH}, e.g.:

@smallexample
PATH+=:/sbin
@end smallexample

In this example, if @env{PATH} exists, @samp{:/sbin} will be appended
to it.  Otherwise, it will be created and @samp{/sbin} will be
assigned to it.

@item @var{name}=+@var{value}
Retain variable @var{name} and prepend @var{value} to its existing
value.  If no such variable is present in the environment, it is
created and @var{value} is assigned to it.  However, if @var{value}
ends with a punctuation character, this character is removed from it
before assignment. 
@end table

The @var{value} part can be enclosed in single or double quotes, in
which case the usual shell dequoting rules apply.
@end deffn

@node ldaphome example
@section Example of pam_ldaphome configuration
This example assumes you are using GNU/Linux.  The aim of this
configuration is to allow remote access via sshd to users present only
in the LDAP database, using ssh shared-key authentication.  The exact
way of achieving this depends on the version of @command{opennsh}
daemon in use.  The @command{openssh} version 6.2p1 introduced a
possibility to obtain public keys by invoking an external command,
so there are two main usage cases, as described in the subsections
that follow.

@menu
* 5.x::         Openssh versions prior to 6.2p1.
* 6.2p1::       Openssh versions 6.2p1 and newer.
@end menu

@node 5.x
@subsection Openssh versions prior to 6.2p1

The user public keys are kept in @samp{grayPublicKey} attribute of his
LDAP entry.  When a user logs in for the first time, his home directory
does not exist yet and consequently @command{sshd} is not able to verify his
key.  Therefore it falls back to the interactive authentication (it is
supposed, of course, that @samp{UsePAM} is set to @samp{yes} in the
sshd configuration file).  The authentication stage is supposed to
create user home directory, populate his @file{.ssh/authorized_keys}
with his public keys and present user with a descriptive text
prompting him to cancel his current authentication attempt and retry
it again.  The corresponding @file{pam.conf} section looks as follows:

@subsubheading pam.conf
@example
sshd auth [success=ok try_again=1 default=die] \
    pam_ldaphome.so 
sshd auth [success=done ignore=ignore default=die] \
    pam_unix.so
sshd auth [default=die]  pam_echo.so file=/etc/ldaphome.txt
@end example

The first line does most of the job.  If @command{pam_ldaphome.so}
succeeds in creating the user directory it will return
@samp{try_again}.  This will cause skipping the next stack entry, so
control will go to @command{pam_echo.so}, which will print a
descriptive text from @file{/etc/ldaphome.txt} and exit indicating
authentication failure.

The @command{pam_ldaphome.so} module returns @samp{success} if the
user who is trying to log in should not be handled by it (e.g. because
his UID is less than the @samp{min-uid} setting, etc.).  In this case,
authentication will be handled by @command{pam_unix.so}.  This allows
normal system accounts to function as usual.  This is very important,
because it will allow to access the machine even when the LDAP
database is not available for some reason.

@subsubheading pam_ldaphome.conf
The @command{pam_ldaphome.so} configuration handles users with uids
and gids greater than or equal to 1000 and pertaining to the group
@samp{remote}.  User home dirs are populated from the @file{/etc/skel}
directory. 

@example
min-uid 1000
min-gid 1000
allow-groups remote 
skel /etc/skel
base dc=gnu,dc=org,dc=ua
filter (&(objectClass=posixAccount)(uid=$user))
pubkey-attr grayPublicKey
@end example

@subsubheading Schema
@anchor{ldap-schema}
The LDAP schema should include an attribute to keep the user public
keys.  The author uses the following schema:

@example
# depends upon:
#    nis.schema

# Attribute Definitions
attributetype ( 1.3.6.1.4.1.9163.2.1.0 NAME 'grayPublicKey'
    DESC 'SSH public key'
    EQUALITY caseExactIA5Match
    SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
# Object Class Definitions
objectclass ( 1.3.6.1.4.1.9163.2.2.0 NAME 'grayAccount'
    DESC 'Abstraction of an employee account'
    SUP posixAccount AUXILIARY
    MUST ( cn $ uid $ uidNumber $ gidNumber $ homeDirectory )
    MAY ( userPassword $ loginShell $ gecos $ grayPublicKey ) )
@end example

@subsubheading /etc/nsswitch.conf
The @samp{passwd} and @samp{group} entries in
@file{/etc/nsswitch.conf} file should be as follows:

@example
passwd:         files ldap
group:          files ldap
@end example

@node 6.2p1
@subsection Openssh versions 6.2p1 and newer

@kindex AuthorizedKeysCommand
@kindex AuthorizedKeysCommandUser
Versions of @command{openssh} starting from 6.2p1 are able to
read public keys from the standard output of an external program.
This can be used to improve the configuration described in the
previous subsection so that the user is not required to cancel
his session upon the very first connection.  To that effect,
@command{pam-modules} includes the utility @command{ldappubkey},
distributed in the @file{examples} subdirectory (@pxref{ldappubkey}).
Copy that utility to a convenient location (@file{/usr/libexec} would
be a wise choice), and add the following two lines to your
@file{/etc/ssh/sshd_config} file:

@example
AuthorizedKeysCommand           /usr/libexec/ldappubkeys
AuthorizedKeysCommandUser       nobody
@end example

@noindent
Two points should be observed.  First, the argument to
@code{AuthorizedKeysCommand} (and all its pathname components) must be
owned by root and be writable only for the owner.  Second, the use
of @code{AuthorizedKeysCommandUser} statement is mandatory.  Of
course, you can chose any suitable user (not necessarily @samp{nobody}).

After restarting @command{sshd}, it will invoke @command{ldappubkeys}
on each log in attempt with the login name of the user as its
argument.  The utility will look up that user in the LDAP database,
and if found, will print his piblic keys on its standard output.  The
@command{sshd} will then read the keys and try to authorize user
against each of them.  If none of the keys matches the private key
supplied by the user, @command{sshd} will attempt public keys read
from the user's @file{~/.ssh/authorized_keys} file (or another file,
if overridden by the @code{AuthorizedKeysFile} statement in
@file{/etc/ssh/sshd_config}).

Most of the configuration described in the previous subsection remains
in effect.  However, the authentication stack won't be invoked if
@command{ldappubkeys} functions successfully.  The
@command{pam_ldaphome} module must be invoked as a part of
@samp{session} stack instead.  The following example assumes
it is invoked at the top of the stack:

@example
sshd session [success=ignore try_again=ignore default=die] \
   pam_ldaphome.so
@end example

@node ldappubkey
@section ldappubkey
@cindex ldappubkey

The @command{ldappubkey} utility is a simple Perl program which takes
user login name as its argument and produces on the standard output
public ssh keys for that user, each on a separate line.  The program
is designed for use with @command{openssh} version 6.2p1 or higher.
It is distributed in the @file{examples} subdirectory and is not
installed by default.  The only prerequisite for its use is the
@command{Net::LDAP} module.  @xref{6.2p1,, Use of pam_ldaphome with
openssh version 6.2p1}, for instructions of its use.

The utility looks up for its configuration in the following files:
@file{/etc/ldap.conf}, @file{/etc/ldap/ldap.conf} and
@file{/etc/openldap/ldap.conf}.  These files are tried in this order and
the first one of them that exists is read.

The following configuration statements are used (all keywords are
case-insensitive):

@anchor{ldap.conf statements}
@deffn {ldap.conf} uri ldap[si]://[@var{name}[:@var{port}]] ...
Specifies the URI of the LDAP server (or servers) to connect to.  The default
is @samp{ldap://127.0.0.1}.
@end deffn

@deffn {ldap.conf} base @var{dn}
Specifies the default base DN to use when performing LDAP operations.
The base must be specified as a Distinguished Name in LDAP format.
@end deffn

@deffn {ldap.conf} binddn @var{dn}
Specifies the default DN to bind as.
@end deffn

@deffn {ldap.conf} bindpw @var{password}
Specifies the password to use with @code{binddn}.
@end deffn

@deffn {ldap.conf} uid @var{attr}
Defines the name of the attribute to use instead of @code{uid}.  The
LDAP record is searched using the following filter:

@example
(&(objectClass=posixAccount)(@var{attr}=@var{login}))
@end example
@end deffn

@deffn {ldap.conf} publickeyattribute @var{attr} [@var{attr}...]
List of attributes that hold the public keys.  Default is
@samp{grayPublicKey} (@pxref{ldap-schema}).
@end deffn

@deffn {ldap.conf} publickeyfilter @var{filter}
LDAP filter used to retrieve the objects that contain public keys. The
@var{filter} string can contain the following variables:

@table @asis
@item $uid
The value of the @samp{uid} setting (see above).
    
@item $arg
First command line argument.
    
@item $hostname
Full hostname of the machine.    
@end table

The default value is:
@example
  (&(objectClass=posixAccount)($uid=$arg))
@end example
@end deffn


@node usergitconfig
@section usergitconfig
@cindex usergitconfig

The @file{examples} subdirectory of the @command{pam-modules}
distribution contains a program @command{usergitconfig} which
is designed to customize user's @file{.gitconfig} file using
attributes from his LDAP entry.

The command reads the @file{.gitconfig} file and replaces any
occurrence of @samp{$@{@var{attr}@}} with the value of the LDAP
attribute @var{attr}.  Not defined attributes are replaced with
empty strings.

To use this utility with @command{pam_ldaphome}, first make sure
you have Perl @command{Net::LDAP} module installed.  Copy
@command{usergitconfig} to some location of preference (say,
@file{/usr/libexec}), and add the following to @command{pam_ldaphome}
configuration file:

@example
skel /etc/skel
initrc-command /usr/libexec/usergitconfig
@end example

The @file{/etc/skel} directory should contain the file @file{.gitconfig}.
Suppose its contents is as follows:

@example
[user]
        name = $@{cn@}
        email = $@{mail@}
@end example

@noindent
Then, after successful completion of @command{pam_ldaphome}, the
user's @file{.gitconfig} file will contain his real name and email
set properly from the database.

For the @command{gituserconfig} LDAP configuration options, see
@ref{ldap.conf statements}.

@node umotd
@chapter pam_umotd
@set MODULE pam_umotd
@cindex motd
@cindex message of the day
The @command{pam_umotd} module displays a user-specific @dfn{message
of the day} (@sc{motd}).  The text can be taken either from a disk
file, or read from the standard output of a program launched for
that purpose.

This module is Linux-specific.

The module is normally started as a part of the @dfn{session} stack,
e.g.:

@example
session optional pam_umotd.so file=/etc/motd
@end example

The @option{file} option specifies the file to read the @sc{motd}
from.  By default the output size is limited to 2000 bytes (a usual
80x25 screen-worth of characters).  If the input file is bigger than
that, it will be truncated.  The size limit can be controlled using
the @option{max-size} parameter:

@example
session optional pam_umotd.so max-size=1024 file=/etc/motd
@end example

Another safety-related parameter is @option{max-la}, which controls
the maximum 5-minute load average, under which the message will be
displayed.  If the current LA is greater than this value, the module
will return immediately without displaying anything@footnote{As of
version @value{VERSION} this functionality relies on the file
@file{/proc/loadavg}.}.

The @sc{motd} can be generated on the fly, by launching an external
program and displaying its output.  This allows you to create dynamic,
user-specific @sc{motd}s.  To select this mode, use the @option{exec}
parameter.  The rest of arguments after this parameter are taken to be
the name of the program to be run and its command line arguments.
Before starting the program, the arguments undergo item expansion (@pxref{item
expansion}).  For example: 

@example
@group
session optional pam_umotd.so max-size=1024 max-la=5.0 timeout=5 \
           exec /usr/bin/genmotd $@{user@} $@{tty@}
@end group                    
@end example

This example runs the program @file{/usr/bin/genmotd} passing it the
user login name and the tty name as its argument.  Notice the
@option{timeout} parameter, which controls the maximum time (in
seconds) the program will be allowed to run.  If it runs longer than that,
it will be killed.  The default timeout is 10 seconds.

@menu
* summary of pam_umotd options::
@end menu

@node summary of pam_umotd options
@section Summary of @command{pam_umotd} options

This section summarizes the options understood by @command{pam_umotd}.

@table @option
@opsummary{file}
@item file=@var{filename}
Read and display text from file @var{filename}.

@opsummary{exec}
@item exec
Execute a program and display its output.  The rest of arguments after
this parameter are taken to be the program name and its command line
arguments.  The arguments are subject to item expansion (@pxref{item
expansion}).  The program inherits the current environment.

@opsummary{timeout}
@item timeout=@var{n}
Limit the execution time of the program started via the @option{exec}
option to @var{n} seconds.  The default value is 10.  

@opsummary{max-size}
@item max-size=@var{n}
Limit the output size to @var{n} bytes.  Default is 2000.

@opsummary{max-la}
@item max-la=@var{d}
Exit immediately if the 5-minute load average is greater than or equal
to @var{d} (a floating-point number).
@end table

@node groupmember
@chapter pam_groupmember
@set MODULE pam_umotd
@cindex groupmember
@cindex group membership
@cindex test group membership

The @command{pam_groupmember} module checks whether the user is member
of one or more groups.  Both primary and supplementary groups are
checked.  The list of groups to be checked is given with the
@option{groups} option.  Its argument is a comma-separated list of
group names of numeric IDs, prefixed with @samp{+} sign.

The module returns PAM_SUCCESS if the user is member of one of the
supplied groups and PAM_AUTH_ERR on otherwise.  The return value can
be inverted using the @option{sense=deny} option.

Additionally, the module can return PAM_USER_UNKNOWN if the user is
not known and PAM_AUTHINFO_UNAVAIL if unable to retrieve the user
name.

The @command{pam_groupmember} module can be used in any PAM service stack.

@menu
* summary of pam_groupmember options::
@end menu

@node summary of pam_groupmember options
@section Summary of @command{pam_groupmember} options

@table @option
@opsummary{groups}
@item groups=@var{group-list}
Defines groups to check against.  The argument is a comma-separated
list of group names or IDs.  Group IDs must be prefixed with a plus
sign.

@opsummary{sense}
@item sense=@{allow|deny@}
   What to do on success.  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 innetgr
@chapter Check NIS netgroup
@set MODULE pam_innetgr
@prindex pam_innetgr
@cindex netgroups
@cindex NIS

The @command{pam_innetgr} module checks if the user and current host
match a triple in the NIS netgroup supplied via the @samp{netgroup}
argument. It returns success if so, and @samp{PAM_AUTH_ERR} otherwise.

Another possible return values are: @samp{PAM_AUTHINFO_UNAVAIL}, if
the input information was not sufficient (e.g. the username was not
supplied, or the module was unable to determine the host or domain
name), and @samp{PAM_SERVICE_ERR}, if a generic error condition (such
as a lack of memory) occurred.

In order to determine host and domain name parts, the following
approach is used. First, the @samp{gethostname} function is called to
obtain the hostname part. If the @samp{getdomainname} function is
available, it is used to determine the domain part. If the resulting
domain part is @samp{NULL} or the string @samp{(none)}, the
@samp{gethostbyname} function is invoked with the hostname as its
argument. The returned name (technically speaking, the @samp{h_name}
member of the @samp{struct hostent}) is used as the canonical name of
the server. It is split on the first occurrence of the dot character.
The second part is used as the domain name. The options described
below control this process.

This module can be used in any PAM service stack.

@menu
* summary of pam_innetgr options::
@end menu

@node summary of pam_innetgr options
@section Summary of @command{pam_innetgr} options

The following table summarizes the options specific for this
module. @xref{common options}, for the list of common options.

@table @option
@opsummary{netgroup}
@item netgroup=@var{name}
Name of the netgroup to use. This option is mandatory.

@opsummary{hostname}
@item hostname=@var{string}
Defines the hostname of the current host. By default it is determined
using the @code{gethostname} system call.

@opsummary{domainname}
@item domainname=@var{string}
Defines the domainname of the current host.

@opsummary{nogetdomainname}
@item nogetdomainname
Disable the use of @code{getdomainname} libc function. By default it
is used to determine the domain name. If it fails or returns a string
@samp{(none)}, than the module tries to get the fully qualified name
of the server and uses the part after the first dot as the domain
name. Using the @samp{nogetdomainname} option instructs it to always
use the latter method.

Never use this option together with @samp{noresove}.

@opsummary{noresolve}
@item noresolve
Don't fallback to obtaining the fully qualified domain name of the
host from DNS in order to obtain the domain part. This means that
if @code{getdomainname} call fails or is not available on your system,
the module will return @code{PAM_SERVICE_ERR}.

Never use this option together with @samp{nogetdomainname}.

@opsummary{sense}
@item sense=@{allow|deny@}
   What to do on success.  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 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