Linux-PAM: the pluggable authentication stack almost every Linux login uses

The configuration is a stack of module calls per service

Linux-PAM is described in the repository simply as the Linux PAM, Pluggable Authentication Modules for Linux, project. What that means in practice is that a login is not one function call but an ordered stack of module invocations, and the configuration for each service lives in its own file under /etc/pam.d. The build and test scaffolding in this repository makes the four standard stack types visible, because the sample /etc/pam.d/other file the README asks you to create contains exactly four entries, one per stack: auth, account, password and session, each marked required and each pointing at pam_deny.so. pam_deny.so always fails, so that file is a deny-everything configuration used for testing, not something you would deploy. That structure is the key mental model. The auth stack decides whether the user is who they claim to be, the account stack checks the account is valid, the password stack handles credential changes, and the session stack manages the session. Each is a list of modules, and the ordering and the control flags in those lists are where the real behaviour lives.

Building with Meson is four commands

The README gives the build sequence with no ceremony. First the prerequisites, which you find by looking at ci/install-dependencies.sh, with the caveat that the script is targeted at Debian based Linux distributions so package names and availability might differ elsewhere. Then you configure the build:

mkdir build
meson setup <your-options> build

Then you compile:

meson compile -C build

And then you run the tests, which is the step the README treats as mandatory rather than optional:

meson test -C build

If a test fails, you should not continue to install this build. That sentence is the whole reason the test step exists in a project like this. The meson_options.txt file at the root is where the configure options live, and the presence of a Makefile alongside meson.build is worth noting, since some packagers still expect one. The repository also carries pgp.keys.asc, which is the signing key set used to verify release artefacts.

The install step carries its own warning

The README is unusually blunt about the last command. It says that if you are worried, do not even think about doing the next line, because most Linux distributions already support PAM out of the box, so if something goes wrong with installing the code from this version your box may stop working. The command itself is:

meson install -C build

That is an unusual amount of caution to find in a build README, and it is proportionate. PAM sits underneath every login, every su, every ssh session and every setuid binary that checks credentials. If the newly installed libraries and modules are inconsistent with what the running system expects, the failure mode is a machine you cannot log into. The advice that follows is to report problems to the bug reporting database on GitHub, and the release history shows a project on a steady cadence, with v1.7.1 on 2025-06-17, v1.7.2 on 2026-01-22 and v1.7.3 on 2026-09-24, and the last push on 2026-10-13.

The repository layout shows the four parts of the system

The top-level entries separate the pieces, and it is a useful map of what PAM actually consists of. libpam/ is the core library, and libpam_internal/ holds the internal helpers. libpam_misc/ is the set of modules that do not belong to a particular category, such as the ones that print a message or manage environment variables, and libpamc/ is the client side library for a program that wants to authenticate through PAM rather than being the target of it. The modules/ directory holds the individual module sources, one per file type, and that is where pam_unix.so, pam_deny.so, pam_env.so and the rest come from. The conf/ directory holds configuration, doc/ holds documentation, po/ holds translations, examples/ holds example programs with a README, and xtests/ and tests/ hold the test suites. There is also a maint/ directory, which is where a project with this history keeps the scripts that maintain it rather than the code itself.

Example programs show the module author's view

The examples directory is small and it is aimed at people writing modules rather than people configuring them. There are six source files and a README. vpass.c is the one to read first, because it is a pass-through module that does nothing except report success, which is how you learn the shape of a module without learning any policy. check_user.c demonstrates how a module inspects the account being authenticated and can fail the stack. blank.c is the minimal module with nothing in it. tty_conv.c converts terminal types, xsh.c is an example of executing a shell, and there is a separate meson.build for the directory so the examples are built with the rest of the tree. The library directory carries a header describing the public interface, and the module side of the API is what these examples demonstrate. If you are evaluating this project as a platform for writing authentication modules, the examples are the fastest way to understand the interface without reading the whole of libpam/.

Documentation generation needs a specific docbook version

One dependency detail in the README is easy to miss and will cost an afternoon if you get it wrong. To generate manual pages from the XML source files you need the docbook-xsl stylesheets in version 1.69.1 or newer, because older versions had a bug which generates a broken layout. So the manual page build is a separate toolchain from the C build, and it has its own version floor that is not derived from anything in the repository. The doc/ directory holds the documentation sources, and the project publishes the manuals separately from the source tree. This is a small illustration of a broader point about PAM. The code is stable and the packaging is settled, but the surrounding documentation tooling has its own lifecycle, and the version floor is stricter than a newcomer would guess from the era of the surrounding code.

Where PAM is the wrong tool

PAM is the wrong abstraction in two situations that come up regularly. The first is a service that does not want to be a PAM service at all. PAM is a stack-of-modules design for authenticating a local user against a local system, and the module set here reflects that: unix accounts, shadow passwords, and the account and session handling around them. If your service already has its own authentication, adding PAM to it means wrapping your protocol in a module interface, which buys you the policy language and costs you a process boundary. The second situation is a container image. A container that needs an auth stack usually wants something small and explicit, and shipping a full PAM implementation with its configuration directory into an image to satisfy a package manager is a lot of surface area for a problem that a single well-written check would solve. For those cases, the pieces in this repository are the reference for how the existing stack behaves, not a component to embed.

Editorial conclusion

Adopt Linux-PAM if you are building a Linux authentication stack, packaging PAM for a distribution, or writing PAM modules, and you want the reference implementation rather than a reimplementation. Do not adopt it casually on a running machine, because the README warns that if something goes wrong with installing from this version your box may stop working. Before you commit, read the build and install steps in full, run the test suite, and make sure the file /etc/pam.d/other exists with the deny rules it needs, since the tests require it.

Frequently asked questions

Official sources

1. Issues
2. linux-pam/linux-pam on GitHub
3. README
4. Releases