PAM_CHROOT(8)

📦
version 1.7.2 · 5 versions
, in fedora 44

✨ pam_chroot — bestie, we're locking u in a directory 💅

okay so real talk, the manual name here is pam_chroot(8) and it lives in the pam-redhat manual, and it's genuinely one of those modules that's like... simple on the surface, absolutely feral underneath. let's get into it 🫶

🌸 NAME 🌸

pam_chroot — a PAM module that lets a user get chrooted in session. that's it. that's the whole vibe. 🎀

🌈 SYNOPSIS 🌈

pam_chroot.so [debug] [onerr]

look at her. two options. minimal. iconic. ✨

💖 DESCRIPTION 💖

so here's the tea. when the calling application tries to open a session, pam_chroot goes and opens /etc/security/chroot.conf and hunts for a line that looks like this:

user directory

and the "user" in that line? bestie, it's not a plain username. it's literally a regular expression. 🧚 so if the PAM_USER that the session is being opened for matches that regex, the module will attempt to chroot() to the directory listed. slay.

important. the calling application must be executing with root privileges, otherwise it cannot chroot() at all. no root, no chroot, no exceptions.

and here's where it gets spicy 🌶️ — if the application needs to exec() other programs (like a server process, or spawning a shell), you're gonna have to duplicate some portions of an actual root environment under the chroot()ed directory for it to work at all. that includes configuration and logging files, btw, not just the fun stuff.

DOUBLE IMPORTANT, no cap: if this is configured incorrectly, the module may potentially render the service unusable and, under some circumstances, pose a security risk. that's not me being dramatic, that's the manpage being dramatic and honestly it earned it. 💀

and one specific thing that WILL get u in trouble: the new root directory and all of its parent directories must not be writable by anyone but root. all of them. every single one. the whole chain. 👑

🎀 OPTIONS 🎀

  • debug — logs debug messages to syslog. ur little paper trail. keep it. 📝
  • onerr= — the values can be "succeed" or "fail". this is the action to take if the configuration file can not be opened, if the chroot() fails, or if the user does not match any of the expressions listed in the configuration file. the default is "succeed".

🦋 MODULE TYPES PROVIDED 🦋

only the session module type is provided. just the one. she's specialized. 💅

⭐ RETURN VALUES ⭐

  • PAM_SUCCESS — everything was successful. we love to see it. 🥳
  • PAM_SESSION_ERR — session error. 😭

🍓 FILES 🍓

  • /etc/security/chroot.conf — the chroot configuration file. this is where u write ur user directory lines and pray the regex does what u meant. 🙈

👑 SEE ALSO 👑

pam.d(5), pam(8) — go read these too, bestie, they're the group chat u wanna be in. 🫶

💜 AUTHOR 💜

the original pam_chroot was written by Matthew Kirkwood and it was obtained from ftp://ferret.lmh.ox.ac.uk/users/weejock/pam_chroot/.

nalin ported this module for Red Hat.

and that's the whole page, bestie 💖✨ this lil slice of the pam-redhat manual is dated 07/08/2026 — go forth, chroot responsibly, and don't make ur service unusable, i'm literally begging 🥺🌸🦋

📦 where this page comes from