Safely Enable and Disable PAM Profiles with pam-auth-update

You will change a packaged PAM profile without losing sight of the files that control login, authentication and sessions. The workflow uses pam-auth-update to select profiles, checks the generated common-* files, and gives you a way back if a selection is wrong.

Allow about fifteen minutes and arrange a second administrative session before changing authentication policy on a remote machine. The examples are for Ubuntu or Debian systems using libpam-runtime 1.5.3-5ubuntu5.7 on this machine. Package versions and available profiles vary. You need root privileges for changes, but not for reading the files.

1. Record the current state

Start with read-only checks. They identify the command, package version, available profile files and managed PAM stacks:

$ 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 shown by the interactive selector. Read a profile before selecting it if its effect is unclear:

$ 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. Review the interactive profile selector

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

$ sudo pam-auth-update

The installed command presents entries such as Unix authentication, systemd session registration and home-directory creation. Select or clear entries, then confirm the change. The command writes the central policy in the /etc/pam.d/common-* files, which affect all installed services that include 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 example enables the installed mkhomedir profile:

$ sudo pam-auth-update --enable mkhomedir

The command is state-changing and requires elevated privileges. It does not mean that every login immediately creates a home directory: the result depends on the module lines that the profile adds and on the service's PAM stack.

Inspect the managed files after the command. Look for the profile's module entries and review the diff against the saved copy:

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

Your output may contain a different module path or additional generated lines. The useful result is that the intended profile's lines appear in the expected stack and unrelated local content remains present.

4. Disable or remove a profile deliberately

Disable a profile when it should remain installed but should no longer contribute to the central configuration:

$ sudo pam-auth-update --disable mkhomedir

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

$ sudo pam-auth-update --remove PROFILE_NAME

Replace PROFILE_NAME with the actual profile name. Do not copy that literal placeholder into a production command. Never remove a profile merely because its name is unfamiliar; read its file and establish 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 operation, not as the next step 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 immediately:

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

This command can change authentication behaviour for every service using the common stacks. Test the affected login or service while your existing administrative access remains available. If the change is unsafe, disable the profile if possible, 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 that PAM 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 have 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.

The common files are stacks included by service files. Their controls 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 is logged by PAM.

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