Fix PAM Module Configuration Error 'Module is unknown'

When does this error show up?

You're setting up or fixing login authentication on a Linux system — maybe Ubuntu 22.04, CentOS 7, or Debian 11. You try to log in via SSH or at the console, and boom: Module is unknown in the system logs, or a straight-up failure to authenticate. I've seen this a lot when someone edits /etc/pam.d/sshd or /etc/pam.d/common-auth and adds a module that doesn't exist on the system.

Real-world trigger: you copy a PAM config from a security guide online that references pam_tally2.so for brute-force protection, but your system uses pam_faillock.so instead. Or you misspelled pam_unix.so as pam_unixx.so. The error is clear: the module file isn't there.

What's causing it?

PAM (Pluggable Authentication Modules) needs two things to work: the module binary (.so file) and the config file that calls it. If the module binary is missing, or the path in the config is wrong, PAM throws 'Module is unknown'. The binary lives in /lib/x86_64-linux-gnu/security/ on modern 64-bit systems, or /usr/lib/security/ on some older ones. If you're on 32-bit, it's /lib/i386-linux-gnu/security/.

Sometimes the module exists but the config line has a typo — like a missing .so extension or wrong module name. And sometimes you installed a package that provides the module, but the package didn't put the file where PAM expects it. Annoying, but fixable.

How to fix it in 5 steps

I'll give you the steps that have worked for me dozens of times. Do them in order.

Find the missing module name. Look at the PAM config file that's failing. Common files: /etc/pam.d/sshd, /etc/pam.d/login, /etc/pam.d/common-auth. Open it with nano /etc/pam.d/sshd. The line that says auth required pam_foo.so — that pam_foo.so is your culprit.
Check if the module file exists. Run: ls /lib/x86_64-linux-gnu/security/pam_foo.so (replace pam_foo with your module). If the file's missing, you'll get a 'No such file' error. That's your root cause.
Find the right module path. Some systems use /usr/lib/security/. On RHEL/CentOS 7, it's /usr/lib64/security/. Run find /usr -name "pam*.so" | grep -i foo to search more broadly. If the module exists but in a different location, you'll need to create a symlink or fix the path in the config.
Install the missing package. If the file doesn't exist at all, you need the package that includes it. Common ones: pam_tally2 comes from libpam-modules on Ubuntu/Debian. pam_faillock is part of pam on RHEL. Use your package manager: sudo apt install libpam-modules or sudo yum install pam.
Test the fix. After installing, verify the module exists again with ls. Then open a new SSH session (don't close your current one!) and try to log in. If it works, you're golden. If not, check journalctl -xe or /var/log/auth.log for the error.

What to check if it still fails

You did the steps, but the error's still there. Here's what I'd check next:

Typo in the config file. Read the line again. Did you write pam_unix.so or pam_Unix.so? Module names are case-sensitive. Also check for extra spaces or missing .so.
Wrong module path. Some configs allow a full path like /lib/security/pam_faillock.so. If you're using a custom path, make sure it's correct. I've seen people point to /lib/security on 64-bit systems where it should be /lib/x86_64-linux-gnu/security.
Missing dependencies. Some PAM modules need other libraries. For example, pam_sss.so requires libsss packages. Run ldd /lib/x86_64-linux-gnu/security/pam_foo.so to see if any shared library is missing. If you see 'not found', install that dependency.
Permission issue. The module file must be readable by root. Check with ls -l /lib/x86_64-linux-gnu/security/pam_foo.so. If it's owned by a weird user or has no read permission, run sudo chmod 644 on it.

If nothing works, temporarily comment out the offending line in the PAM config (add # at the start) to regain access, then debug more. But honestly, 9 times out of 10, it's a missing package or a typo. You'll fix it fast.