PAM: Pluggable Authentication Modules
-------------------------------------

Author: MacGyver aka Habeeb J. Dihu <macgyver@tos.net>
Copyright(C) 1999, All Rights Reserved.

PAM stands for Pluggable Authentication Modules, a modular system
designed to eliminate the ages old problem of disparate authentication
mechanisms on Unix (ie: shadow, pwdb, MD5, etc).  Many operating
systems, including FreeBSD, Linux, and Solaris already support and use
PAM.

ProFTPD attempts to check for the necessary PAM support automatically,
and unless specifically overridden, will use PAM on those platforms
whenever possible.  In order to use PAM, you must configure a
configuration file.  On some systems, such as FreeBSD, this will be a
file called /etc/pam.conf.  On others, such as Linux, configuration is
taken from the directory /etc/pam.d, in a file called ftp.

FreeBSD:

To use PAM with ProFTPD, you must edit /etc/pam.conf and add the
following lines:

ftp auth    required    pam_unix.so         try_first_pass
ftp account required    pam_unix.so         try_first_pass

PAM authentication should now work properly.

Linux:
To use PAM with ProFTPD, you must edit /etc/pam.d/ftp and add the
following lines for RedHat installations:

#%PAM-1.0
auth       required     /lib/security/pam_listfile.so item=user sense=deny file=/etc/ftpusers onerr=succeed
auth       required     /lib/security/pam_pwdb.so shadow nullok
account    required     /lib/security/pam_pwdb.so
session    required     /lib/security/pam_pwdb.so

For SuSE:

#%PAM-1.0
auth       required     /lib/security/pam_listfile.so item=user sense=deny file=/etc/ftpusers onerr=succeed
auth       required     /lib/security/pam_unix.so shadow nullok
account    required     /lib/security/pam_unix.so
session    required     /lib/security/pam_unix.so

These settings are valid for RedHat and SuSE Linux systems.  Other Linux
distributions may differ.

PAM Configuration Options
-------------------------
1. PAMConfig
You may configure multiple authentication configurations using PAM
that optionally validate users against various things, such as an LDAP
directory, a MySQL database, or even a Windows NT domain.  Discussion
of alternate authentication modules for PAM is beyond the scope of
this document.  However, what is relevant is that ProFTPD allows you
to use different PAM authentication schemes for different virtual
servers.  You can do this by using the PAMConfig directive:

# This is the PAM configuration file that will be referenced when
# authenticating.  It can be set globally and/or per VirtualHost.
# The default is 'ftp'.
PAMConfig                       ftp

The default setting is 'ftp'.  However, if you set PAMConfig to be
'ftp.myhost', for example, ProFTPD will try to use the PAM
authentication settings for ftp.myhost, assuming you've set up your
PAM configuration file(s) properly.  To use the above example with
FreeBSD, you would need to add lines such as the following:

ftp.myhost auth    required    pam_unix.so         try_first_pass
ftp.myhost account required    pam_unix.so         try_first_pass

to your /etc/pam.conf file.  Under Linux, or if you're using a
directory like /etc/pam.d, you could simply copy the Linux
configuration above to a new file called /etc/pam.d/ftp.myhost.

The pattern here is that PAMConfig sets what's called the service name
in PAM lingo.  If you use /etc/pam.conf, the first field on any
configuration directive is the service name.  If you're using
/etc/pam.d, the service name is the name of the file, for example
/etc/pam.d/login happens to be the PAM configuration for the login
program.

2. AuthPAMAuthoritative

The directive AuthPAMAuthoritative refers to whether you want PAM to
be the final arbitrator of what is and is not a valid ProFTPD user.
It defaults to Off.  With this directive on, things like AuthUserFile
directives will *NOT* work properly, since PAM will detect these as
invalid users and inform ProFTPD not to attempt to process users
through any other authentication mechanisms.  If you set
AuthPAMAuthoritative to Off, then if PAM cannot authenticate a
specified user, it allows ProFTPD to select other authentication
mechanisms such as AuthUserFile and attempt to process them in that
fashion.

# Setting this to 'on' makes PAM the final authority on what gets
# authenticated.  Turning this off will tell PAM to allow other
# authentication modules compiled into ProFTPD a chance at the user.
AuthPAMAuthoritative            On

References
----------
More information and a much more complete primer about PAM can be
found at http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/