PAM_WRAPPER(1)

💖 PAM_WRAPPER 💖

okay so bestie, welcome to pam_wrapper(1) — the preloadable wrapper to test PAM applications and PAM Modules. yes, the one. she's iconic, she's a preloadable library, and she's about to make your testing era so much easier. 🎀

✨ SYNOPSIS ✨

LD_PRELOAD=libpam_wrapper.so PAM_WRAPPER=1
PAM_WRAPPER_SERVICE_DIR=/path_to_config ./myapplication

that's it. that's the whole vibe check. two lines and you're in. 🦋

🌸 DESCRIPTION 🌸

so this tool lets you test either your PAM application or your PAM module. pick your fighter, both are valid. 💅

if you're testing a PAM application, we wrote a little something something called pam_matrix for you (more on her below, she's further down the page, keep scrolling babe).

if you're testing a PAM module, you can use the pamtest library we implemented — it simplifies testing of modules, lowkey a lifesaver. and the best part? you can combine it with the cmocka unit testing framework, or you can use the provided Python bindings to write tests for your module in Python. write your tests in Python, bestie. main character energy. 🐍✨

🌈 ENVIRONMENT VARIABLES 🌈

pam_wrapper is activated and controlled by environment variables — that's the whole control panel, no config file drama. you can set the following variables:

• PAM_WRAPPER — if you load the pam_wrapper and enable it with setting PAM_WRAPPER=1, all PAM calls will be wrapped so you are able to specify a directory with the service files pam_wrapper should be using. no 1, no wrapping. periodt.
• PAM_WRAPPER_SERVICE_DIR — the directory to read PAM service files from. that's her whole job. 📁

if you want to use pam_matrix (see below, she's coming) or want to test your own PAM module, you need to specify the absolute path to your module in the service files. absolute. not relative. we said what we said.

• PAM_WRAPPER_DEBUGLEVEL — if you need to see what is going on in pam_wrapper itself or try to find a bug, you can enable logging support in pam_wrapper if you built it with debug symbols. (that caveat is load-bearing, don't @ me.) the levels are:
  • 0 = ERROR
  • 1 = WARNING
  • 2 = DEBUG
  • 3 = TRACE
• PAM_WRAPPER_USE_SYSLOG — by default pam logs will go to the pam_wrapper DEBUG log level and will not be sent to the syslog. if you want to log to the syslog too, you can set this variable to 1. yes, "to the syslog to" — that's the original phrasing, we're keeping it, she's quirky. 🫶
• PAM_WRAPPER_KEEP_DIR — if this option is set to 1, then pam_wrapper won't delete its temporary directories. mostly useful for pam_wrapper development. your temp dirs, your choice. 💀
• PAM_WRAPPER_DISABLE_DEEPBIND — this allows you to disable deep binding in pam_wrapper. useful for running valgrind tools or sanitizers like (address, undefined, thread). so if valgrind is being dramatic, this is your girl. 🔥

🎀 EXAMPLE 🎀

a service file for pam_wrapper should look like this:

auth            required        /usr/lib/pam_wrapper/pam_matrix.so passdb=/path/to/pdb
account         required        /usr/lib/pam_wrapper/pam_matrix.so passdb=/path/to/pdb
password        required        /usr/lib/pam_wrapper/pam_matrix.so passdb=/path/to/pdb
session         required        /usr/lib/pam_wrapper/pam_matrix.so passdb=/path/to/pdb

copy that exactly, character for character. every line. auth, account, password, session. all four. no skipping the "boring" ones, bestie, they're all doing work. ✨

the name of the file should represent the service name used by your PAM application. so name it like it means it. 💖

and then:

LD_PRELOAD=./libpam_wrapper.so PAM_WRAPPER=1
PAM_WRAPPER_SERVICE_DIR=./pam_services ./my_pam_app

boom. running. slay. 👑

🧚 PAM_MATRIX 🧚

we offer a module to make testing of PAM applications easier. you find more information in the pam_matrix(8) manpage. go read her next, she's got lore. 📖

💜 AUTHOR 💜

The Samba Team — Author. legends, honestly. not me being obsessed with the people who wrote the thing. 🥹

and that's the whole page, no cap. every variable, every value, every caveat — all of it, untouched, just with better vibes. 💅

okay bye bestie, go write some tests. this was pam_wrapper manual page PAM_WRAPPER(1), dated 2020-01-31, brought to you by the PAM_WRAPPER(1) source. mwah. 😘💖✨