PAM_MATRIX(8)

✨ NAME ✨

pam_matrix — a PAM test module to retrieve module-specific PAM items 💖

---

🌸 SYNOPSIS 🌸

pam_matrix.so [...]

---

🦋 DESCRIPTION 🦋

okay so bestie, here's the deal: testing a PAM application usually means setting up a whole authentication backend, and that's so much effort for literally no reason 😭. That's where pam_matrix comes in — it lets you authenticate against a plain key-value text file, and you can hand it over either with an option or with an environment variable. iconic behaviour, honestly 💅

---

🚨 IMPORTANT 🚨

pam_matrix is a test tool. It should be considered completely insecure and never used outside test environments! 🛑

fr fr — and as you'll see when you read through the options and actions, a bunch of them make absolutely zero sense in the real world. They were added just to make tests possible. Not a single one of them is out here trying to be production-ready, no cap 💀

---

🎀 PASSWORD DATABASE 🎀

The pam_matrix module authenticates a user against a plain-text CSV file, and the format of the file goes like this:

username:password:allowed_service

Example: User bob allowed to authenticate with the service sshd

bob:secret:sshd

slay, that's the whole vibe 🌈

---

💅 OPTIONS 💅

• passdb=/path/to/file — the patch to the password database. If the database is not provided with this module option, pam_matrix.so reads the PAM_MATRIX_PASSWD environment variable and tries to load the file from there. And if that fails as well, PAM_AUTHINFO_UNAVAIL is returned. 🙈
• echo — if this option is provided, pam_matrix.so will ask for password using PAM_PROMPT_ECHO_ON, that is, the password will be echoed back to user. This option was added to make it possible to test conversation functions better. 👀
• verbose — if this option is provided, pam_matrix.so will display a PAM_TEXT_INFO message when authentication succeeds and a PAM_ERROR_MSG when authentication fails. This option was added to make it possible to test conversation functions better. ✨

---

👑 MODULE TYPES PROVIDED 👑

All module types (account, auth, password and session) are supported. periodt. 💜

• The auth module searches for the user in the passdb file and compares the provided password with the one in the passdb file.
• The password module is able to update the password in the passdb file.
• The access module compares the service name the PAM conversation was invoked with the allowed service for the user as set in the passdb file.
• The session module sets the HOMEDIR PAM environment variable to "/home/%u" where %u stands for the user who opens the session. The variable is unset on session close.

---

⭐ EXAMPLE ⭐

auth        required    pam_matrix.so passdb=/tmp/passdb verbose
account     required    pam_matrix.so passdb=/tmp/passdb verbose
password    required    pam_matrix.so passdb=/tmp/passdb verbose
session     required    pam_matrix.so passdb=/tmp/passdb verbose

---

and that's the whole page bestie, hope it ate 🫶 this one's dated 2015-11-04, and yeah, it's still out here living under the name PAM_MATRIX(8) — go forth and test responsibly (in a test environment only, please, I'm begging 🙏) 🧚