Linux-PAM 0.99 upgrade guide

1. 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 them.

Note: 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.

Important: 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 app-portage/portage-utils.

Important: 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).

Code Listing 1.1: using qfile -o to check for orphan files

# qfile -o /etc/pam.d/*
/etc/pam.d/sshd
/etc/pam.d/system-auth~
/etc/pam.d/vmware-authd

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 pam_timestamp.

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.

Moved modules

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 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.

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 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:

Code Listing 1.2: Replace pam_stack usage with the include directive

(The old configuration)
auth    required     pam_stack.so    service=system-auth

(Replace it with this)
auth    include      system-auth

Important: 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 include directive.

Code Listing 1.3: Handling multiple-modules with pam_stack

(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.

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.

Updated July 2, 2008

Summary: This guide will help you through the upgrade path for Linux-PAM from 0.78 (or older) to Linux-PAM 0.99.

Diego Pettenò
Author

Donate to support our development efforts.