PAM: Pluggable Authentication Modules
-------------------------------------
Author: The ProFTPD Project team
Copyright(C) 1999, 2000-2. 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 (if they are not already present):
ftpd auth required pam_unix.so try_first_pass
ftpd account required pam_unix.so try_first_pass
ftpd session required pam_permit.so
In your proftpd.conf, you'll need to set AuthPAMConfig to 'ftpd'. 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_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_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.
NOTE: If you are using a 64-bit system, you may need to change the above
paths from "/lib/security/..." to "/lib64/security/...". Without this
correction, on 64-bit systems, your proftpd logs may contain errors
like:
PAM unable to dlopen(/lib/security/pam_pwdb.so)
PAM [dlerror: /lib/security/pam_pwdb.so: cannot open shared object file:
No such file or directory]
After updating the paths in your /etc/pam.d/ftp file, be sure to restart
proftpd, so that the new PAM configuration takes effect.
Mac OS X
--------
To use PAM with ProFTPD, you must edit /etc/pam.d/ftp and add the
following lines:
auth required pam_unix.so try_first_pass
account required pam_unix.so try_first_pass
session required pam_permit.so
Or, if you are running Mac OSX 10.3 or later, you should have an
/etc/pam.d/ftpd file that contains the following:
auth sufficient pam_securityserver.so
auth required pam_deny.so
account required pam_permit.so
password required pam_deny.so
session required pam_permit.so
Then, in your proftpd.conf, use:
<IfModule mod_auth_pam.c>
AuthPAMConfig ftpd
</IfModule>
PAM Configuration Options
-------------------------
1. AuthPAM
You may selectively enable or disable PAM authentication. This is
especially useful in environments where you are receiving ProFTPD in a
distribution, and you want to disable the builtin PAM authentication
module. The default is to enable PAM authentication. You may disable
it as follows:
# This enables or disables the PAM authentication module.
# The default is 'on'.
AuthPAM on
2. AuthPAMConfig
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 AuthPAMConfig 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'.
AuthPAMConfig ftp
The default setting is 'ftp'. However, if you set AuthPAMConfig 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 AuthPAMConfig 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.
3. Authoritative PAM module
This refers to whether you wish 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.
# The following makes PAM the final authority on what gets
# authenticated.
AuthOrder mod_auth_pam.c* mod_auth_unix.c
Note the "*" suffix on the mod_auth_pam.c name, which indicates that that
module is to be treated authoritatively.
Issues
------
Some PAM libraries on various platforms impose restrictions on the login
name length. Login names that exceed these lengths can cause the PAM
libraries to fail or crash. If you know the length restriction for your
platform, you can compile proftpd such that it will not handle logins of
that length:
CFLAGS='-DPR_TUNABLE_LOGIN_MAX=16' ./configure ...
would set a maximum length of 16 characters to proftpd login names. Note,
though, that by using backends such as SQL tables or LDAP directories,
longer logins may actually be used, leading to possible interoperability
problems between those auth modules and mod_auth_pam.
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/
