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.

Introduction
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  package, and moved to separate packages, so you might need to merge them if you are relying on them.

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  directive replacing the deprecated   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.

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

The changes need to be applied to each and every file in the directory (the PAM services configuration files). Please make sure you remove eventual backup files before trying to update  , or the emerge process will fail as a safety measure.

As a safety device, the  ebuild checks the files present in  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  command present in.

The most common presence of orphan files in 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 for  , that is created by the   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: ,   (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 , and has been moved in.

Additionally, the berkdb USE flag, used to build the  module was removed; in its stead you will have to manually merge the   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 , 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  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. is no longer shipped with this package. Although for a while available as  for those needing it, a security bug forced the masking and removal of this package.

The need for  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  module.

Moved modules
The  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  is required for users needing this module.

The same holds true for the  module that is now available as  , just use the new package and that will be fine for you.

The  module has also been moved to its own package, as  , 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  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  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  into an updated one that works with the   directive, you just need to replace the lines as shown:

Please note that you might also need to reorder the calls when making this change, as sometimes modules like  were listed after  , even though they now need to be listed before the   directive.

This change will not result in feature loss ( didn't work with anything but the   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.

Acknowledgements
We would like to thank the following authors and editors for their contributions to this guide:
 * Diego Pettenò