Change PAM Profiles Safely with pam-auth-update

One wrong profile toggle in pam-auth-update and the next login on the box is yours to fix from a rescue shell. This walks through checking the current state, changing one profile deliberately, and keeping a way back if it goes wrong.

Allow about fifteen minutes and keep a second administrative session open before you touch authentication policy on a remote machine. The examples are Ubuntu or Debian with libpam-runtime 1.5.3-5ubuntu5.7 on this machine; your package version and available profiles will differ. Changing anything needs root. Reading does not.

1. Record the current state

Start with checks that only read. They tell you the command, the package version, which profiles are available, and which stacks are managed:

$ command -v pam-auth-update
/usr/sbin/pam-auth-update
$ dpkg-query -W -f='${Package} ${Version}\n' libpam-runtime
libpam-runtime 1.5.3-5ubuntu5.7
$ find /usr/share/pam-configs -maxdepth 1 -type f -printf '%f\n' | sort
capability
mkhomedir
systemd
unix
$ ls -l /etc/pam.d/common-*

The profile names are the filenames under /usr/share/pam-configs, not the longer descriptions the interactive selector shows you. If a profile's effect is not obvious, read it before selecting it:

$ sed -n '1,120p' /usr/share/pam-configs/unix

$ backup_dir="${TMPDIR:-/tmp}/pam-common-backup-$(date +%Y%m%d-%H%M%S)"
$ mkdir "$backup_dir"
$ cp -a /etc/pam.d/common-* "$backup_dir"/
$ printf 'Backup: %s\n' "$backup_dir"

2. Look at the interactive selector first

Run the selector as root when you want to choose profiles by description:

$ sudo pam-auth-update

You will see entries such as Unix authentication, systemd session registration and home-directory creation. Select or clear entries, then confirm. The command writes the central policy into the /etc/pam.d/common-* files, which affect every installed service that includes those stacks.

Do not treat a profile description as harmless decoration. Unix authentication controls the normal password stack. mkhomedir can create a home directory at login. systemd adds session handling. The exact module lines and ordering come from each installed profile.

If the command reports local modifications, stop and inspect them. pam-auth-update tries to preserve local option changes, but adding modules inside its managed portion makes it treat a file as locally modified and stop making further changes unless forced.

3. Enable one known profile from a script

For a deliberate, repeatable change, pass the profile name directly. This enables the installed mkhomedir profile:

$ sudo pam-auth-update --enable mkhomedir

This is state-changing and needs elevated privileges. It does not mean every login now creates a home directory: the actual result depends on the module lines the profile adds and on the service's own PAM stack.

Check the managed files afterwards. Look for the profile's module entries and diff against your saved copy:

$ diff -u "$backup_dir/common-session" /etc/pam.d/common-session
$ grep -n 'pam_mkhomedir' /etc/pam.d/common-*

Your output may show a different module path or extra generated lines. What matters is that the intended profile's lines appear in the expected stack, and the unrelated local content is still there.

4. Disable or remove a profile deliberately

Disable a profile when it should stay installed but stop contributing to the central configuration:

$ sudo pam-auth-update --disable mkhomedir

Use --remove for the package-removal workflow, before the module package disappears from disk. Administrators normally disable; package maintainer scripts use removal so PAM does not keep references to modules that are about to vanish.

$ sudo pam-auth-update --remove PROFILE_NAME

Replace PROFILE_NAME with the real profile name; do not copy that placeholder into a production command. Never remove a profile just because its name is unfamiliar. Read its file and find out which stack it changes first.

5. Use force only after preserving evidence

--force overwrites the current PAM configuration without prompting. It is for administrators, not package maintainer scripts. Treat it as a recovery or controlled migration step, not as the next move when a warning is inconvenient.

Before using it, copy every affected common-* file and inspect the local changes. When local configuration must be overridden, the old files are saved in /etc/pam.d/ with a .pam-old suffix. Check that backup straight away:

$ sudo pam-auth-update --force --enable PROFILE_NAME
$ sudo find /etc/pam.d -maxdepth 1 -name 'common-*.pam-old' -printf '%f\n' | sort

This can change authentication behaviour for every service using the common stacks. Test the affected login or service while your existing administrative access is still open. If the change is unsafe, disable the profile if you can, or restore the reviewed files from your backup during the open recovery session:

$ sudo cp -a "$backup_dir"/common-* /etc/pam.d/
$ sudo diff -u "$backup_dir/common-auth" /etc/pam.d/common-auth

Restore only after checking that backup_dir names the backup you made for this change. A careless wildcard aimed at the wrong directory can overwrite a valid policy.

6. Understand the files PAM actually reads

Linux-PAM prefers individual service files under /etc/pam.d. A file such as /etc/pam.d/login describes the login service, and its lines take the form type control module-path module-arguments. The older /etc/pam.conf form includes a service field, but when /etc/pam.d exists, Linux-PAM ignores /etc/pam.conf entirely.

The common files are stacks included by service files, and their control flags matter: required records failure but continues through the stack, requisite can stop immediately, sufficient can return success early when no earlier required module failed, and optional normally matters only when it is the only module for that type. A malformed line can make authentication fail, and PAM logs it.

When you are diagnosing a result, read the service file and then each included common file in order. Do not assume editing one common stack explains every service: individual services can add extra rules, and local files in /etc/pam.d override vendor files of the same name.