Project:PAM/Upgrade to 0.99
This guide will help you through the upgrade path for Linux-PAM from 0.78 (or older) to Linux-PAM 0.99.
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 them.
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
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 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 pam _stack.so ).
title?using qfile -o to check for orphan files
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_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
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
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_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
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 this module.
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 you.
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 password database.
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 authenticate.
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:
(The old configuration) auth required pam_stack.so service=system-auth (Replace it with this) auth include system-auth
There are four facilities in PAM configuration:
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
(Old way) auth required pam_stack.so service=system-auth auth required pam_nologin.so (New way) 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.
We would like to thank the following authors and editors for their contributions to this guide:
- Diego Pettenò