Linux-PAM 0.99 upgrade guide
This guide is written to help you through the process of upgrading from older
Linux-PAM versions to the new versions based on 0.99 series. With 0.99, Gentoo
does not use RedHat/Fedora patches anymore, and thus some features previously
supported are no longer available (on the other hand, even RedHat stopped
supporting and providing some of these features).
For this reason, the upgrade from the old Linux-PAM to the new one is not
straightforward, and might require changing the authentication configuration for
the system or for services if it wasn't updated automatically during that time.
Also some modules were removed from the sys-libs/pam package, and moved
to separate packages, so you might need to merge them if you are relying on
Don't be scared of this guide: if you installed your system after about
September 2005, the upgrade path should be quite painless, and this guide will
just be an interesting read to you. If your system is older, but you upgraded
regularly, and didn't configure PAM manually, you should also be fine, as most
of the configuration files would have been upgraded already for you. If you
customised your PAM configuration, you will probably have to upgrade it
manually, but then you should already know how to handle that.
Please note that there is no loss of functionality coming from the update: most
of the RedHat patches are currently implemented in Linux-PAM through slightly
different methods, like the include directive replacing the deprecated
pam_stack module. The modules were moved to their own packages to
maintain the clean design of the ebuild, and to allow packages whose default
configuration requires these optional modules to just depend on them.
It is important to keep Linux-PAM up to date, because it is an important piece
in a system, as it's the default authentication provider for Gentoo Linux. For
this reason, the upgrade to Linux-PAM 0.99 is suggested as an high priority to
keep the system safe and secure.
After upgrading PAM, from any version to any version, you have to restart those
services that are using it to avoid internal ABI mismatches. This includes
sshd, vixie-cron (and probably any other cron service), mail
servers, and in general almost every service that accepts users.
What users have to do for most of the cases is either to install a new package
(because the module was migrated out of the main sys-libs/pam ebuild), or
to change the configuration so that it does not use the modules that were
dropped. If you made changes to the PAM service configuration files, you should
be able to handle all the changes. For those who never changed a configuration
file, there is only one change that needs to be done, documented in the pam_stack and the include directive section.
The changes need to be applied to each and every file in the
/etc/pam.d/ directory (the PAM services configuration
files). Please make sure you remove eventual backup files (*~)
before trying to update sys-libs/pam, or the emerge process will fail as
a safety measure.
As a safety device, the sys-libs/pam ebuild checks the files present in
/etc/pam.d/ for the now-deprecated modules, and stops the merge
process in case they are still used, to avoid locking you out of your own
system. Because of the nature of configuration files, you might still have old
configuration files for packages you already removed, so you should check first
that there are no orphan files (files not belonging to any package), for
instance through the qfile command present in
The safety check will also check the comment lines, which means that you also
need to remove the comments that refers to the removed modules. This is meant as
an extra safety so that users don't uncomment lines that will disallow them from
logging in on their system. If you want to keep the comment in there as
documentation, you're invited to split up the modules' names (for instance in
Code Listing 1.1: using qfile -o to check for orphan files
# qfile -o /etc/pam.d/*
The most common presence of orphan files in /etc/pam.d are the
backup files created by most editors, ending with a tilde character
(~). The remaining files, unless you created them yourself for your
particular setup, should be safe to remove (or at least move away), as they are
probably leftovers from previously installed packages. A special exception for
this is /etc/pam.d/vmware-authd for vmware-server, that is
created by the vmware-config.pl script (but it should be safe to remove
unless you edited it manually, you'll just have to re-execute the script).
What are the main changes?
As we said, the main change between 0.78 and 0.99 is that the RedHat patches
aren't applied anymore, but this does not explain what really changed for users.
To a minimum, the following modules are not available anymore: pam_stack,
pam_pwdb (ex-pwdb USE flag), and
The pam_chroot USE flag is no longer present, as the module (previously
coming from RedHat patches) is no longer built in sys-libs/pam, and has
been moved in sys-auth/pam_chroot.
Additionally, the berkdb USE flag, used to build the pam_userdb
module was removed; in its stead you will have to manually merge the
sys-auth/pam_userdb package that provides the module with the same name.
Also the pam_console USE flag was removed, and the module is no longer
available, please see this in its own section.
For all the missing modules, besides pam_stack, please feel free to ask
about their destiny on Bugzilla, providing a use case for them, and they might
be resurrected in their own packages too.
The case against pam_console
The pam_console module was designed by RedHat to allow setting different
permissions on devices for users logging in via hardware access (either in X
through the various graphical login applications, or through the console
login).This approach caused more than a few problems in the past with users
unable to get their devices working, and was then disabled by default, linked to
a pam_console USE flag for those needing it.
As of version 0.99 of Linux-PAM the whole RedHat patchset was dropped.
pam_console is no longer shipped with this package. Although for a while
available as sys-auth/pam_console for those needing it, a security bug forced
the masking and removal of this package.
The need for pam_console is being mitigated by HAL switching to
ConsoleKit as alternative. Those still needing a behaviour similar to
pam_console's are invited to update their code so that ConsoleKit can be used
instead, or use a plugdev group together with pam_group module.
The pam_userdb module, used to provide authentication against a simple
Berkeley DB file, was previously available through the berkdb USE flag.
As this module requires a static inline copy of Berkeley DB to work correctly,
it was moved to its own package to simplify maintenance of PAM, and to reduce
the risk of problems. The package is sys-auth/pam_userdb.
It is important to note that even though the module's code is updated, taken
from the last PAM release, the Berkeley DB copy is still at 4.3; no upgrade of
this is planned, as such upgrades usually are not backwards compatible. For this
reason, unless a security bug is found, you'll still need to use Berkeley DB
4.3 tools to manipulate the users' database.
Nothing more than using sys-auth/pam_userdb is required for users needing
The same holds true for the pam_chroot module that is now available as
sys-auth/pam_chroot, just use the new package and that will be fine for
The pam_radius module has also been moved to its own package,
as sys-auth/pam_radius, although nothing is noted at the time
of writing with respect to the compatibility with the previous version
as provided by Linux-PAM 0.78.
pam_stack and the include directive
PAM was designed to allow configuring different software and services with
different authentication facilities, for instance accepting local users through
the usual Unix authentication facilities, but also allowing mail users
authenticate against a database. For most desktop users and for those servers
who don't expect connections from non-system users (like HTTP servers) though,
most of the services would just use the same authentication against the system
For this reason, to avoid managing multiple copies of the same exact PAM
configuration file, many Linux distributions started writing extensions to them
to allow keeping a single system or more commonly system-auth
configuration, and then telling the other services to use that one to
Up to version 0.77, Linux-PAM itself didn't provide any of such extensions, and
Gentoo's package followed RedHat's solution through the pam_stack module
that hijacked PAM's internals to get a second pass over a different service
configuration. This method was not standard, not portable, and required heavy
patching of the internal library structure.
An alternative solution was instead designed by ALTlinux for OpenPAM, and was to
use an include directive, that would be handled internally by the PAM
implementation, effectively loading the configuration for that service and
passing through the equivalent class's modules. This is the same extension
implemented by Linux-PAM 0.78 and later, and the current only supported option
for Gentoo (as it works on both the supported implementations).
To convert an old configuration file that uses pam_stack into an updated
one that works with the include directive, you just need to replace the
lines as shown:
Code Listing 1.2: Replace pam_stack usage with the include directive
auth required pam_stack.so service=system-auth
auth include system-auth
There are four facilities in PAM configuration: auth, account,
password and session. You need to update the configuration files
for all of them, not just auth.
Please note that you might also need to reorder the calls when making this
change, as sometimes modules like pam_nologin were listed after
pam_stack, even though they now need to be listed before the
Code Listing 1.3: Handling multiple-modules with pam_stack
auth required pam_stack.so service=system-auth
auth required pam_nologin.so
auth required pam_nologin.so
auth include system-auth
This change will not result in feature loss (pam_stack didn't work
with anything but the required directive), and it should always be safe.
All the recent PAM configurations installed by ebuilds in the Portage tree are
updated to use the new syntax.
The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.