pam_mount(8)

📦
version 2.23 · 6 versions
, in arch rolling

💅 pam_mount(8) — the pam_mount manual, but make it make sense 🎀

okay bestie, welcome to pam_mount (that's the pam_mount page from the pam_mount 2.23 set, iykyk) — a PAM module that can mount volumes for a user session. yes. it mounts stuff. on login. and unmounts on logout. we love a full lifecycle. ✨

🌸 NAME 🌸

pam_mount — a PAM module that can mount volumes for a user session. periodt.

✨ OVERVIEW ✨

okay so picture this: environments with central file servers where a user wants to mount on login and unmount on logout. like (semi-)diskless stations where a million users log on, and where statically mounting the entire /home from a server is literally a security risk, or listing every possible volume in /etc/fstab just isn't feasible. yeah. that's the vibe this module was born for. 🦋

here's what you're getting:

  • Users can define their own list of volumes without having to touch (possibly non-writable) global config files. main character energy fr.
  • Single sign-on feature — the user types the password just once (at login). one password. one. 🙌
  • Transparent mount process — it just happens, no drama.
  • No stored passwords. none. zero. we don't do that here. 🔐
  • Volumes are unmounted on logout, which frees system resources and doesn't leave your data exposed. slay.

the module also supports mounting local filesystems of any kind that the normal mount utility supports, plus extra code to make sure certain volumes are set up properly, because often they need more than just a mount call — think encrypted volumes. this includes SMB/CIFS, FUSE, dm-crypt and LUKS. iconic lineup ngl.

⚠️ if you're planning to use pam_mount to protect volumes on your computer with an encrypted filesystem, please know there are many other issues you need to consider to actually protect your data. for example, you probably want to disable or encrypt your swap partition (the cryptoswap can help you do this). do not assume a system is secure without carefully considering potential threats. no cap, do the homework. 😭

🎀 CONFIGURATION 🎀

the primary config file for the pam_mount module is pam_mount.conf.xml. on most platforms this file is read from /etc/security/pam_mount.conf.xml. on OpenBSD, pam_mount reads its configuration file from /etc/pam_mount.conf.xml instead. see pam_mount.conf(5) for all the deets on how to use it. 📖

individual users may define additional volumes to mount if allowed by pam_mount.conf.xml (usually ~/.pam_mount.conf.xml). the volume keyword is the only valid keyword in these per-user config files — like, the only one, don't try it. if the luserconf parameter is set in pam_mount.conf.xml, allowing user-defined volumes, then users may mount and unmount any volume they own at any mount point they own. 💀

🚨 heads up: on some filesystem configurations this may be a security flaw, so user-defined volumes are not allowed by the example pam_mount.conf.xml distributed with pam_mount. read the room before you flip that switch.

💜 PAM CONFIGURATION 💜

also (yes, there's an also), you must include two entries in the system's applicable /etc/pam.d/service config files. like so:

                  auth     required  pam_securetty.so
                  auth     required  pam_pwdb.so shadow nullok
                  auth     required  pam_nologin.so
              +++ auth     optional  pam_mount.so
                  account  required  pam_pwdb.so
                  password required  pam_cracklib.so
                  password required  pam_pwdb.so shadow nullok use_authtok
                  session  required  pam_pwdb.so
                  session  optional  pam_console.so
              +++ session  optional  pam_mount.so

when "sufficient" is used in the second column, you must make sure pam_mount is added before this entry. otherwise pam_mount will not get executed should a previous PAM module succeed, and then you're just standing there like 🧍. also be aware of the "include" statements — these make PAM look into the specified file. if there's a "sufficient" statement, then the pam_mount entry must either be in the included file before the "sufficient" statement, or before the "include" statement.

if you use pam_ldap, pam_winbind, or any other authentication services that make use of PAM's sufficient keyword, model your configuration on this order:

              •••
              account sufficient  pam_ldap.so
              auth    required    pam_mount.so
              auth    sufficient  pam_ldap.so use_first_pass
              auth    required    pam_unix.so use_first_pass
              session optional    pam_mount.so
              •••

this allows for:

  1. pam_mount, as the first "auth" module, will prompt for a password and export it to the PAM system. 🫶
  2. pam_ldap will use the password from the PAM system to try and authenticate the user. if this succeeds, the user will be authenticated. if it fails, pam_unix will try to authenticate. 🔁
  3. pam_unix will try to authenticate the user if pam_ldap failed. if pam_unix fails, then the authentication will be refused (due to the "required"). 🚫

alternatively, the following is possible (thanks to Andrew Morgan for the hint!):

              auth [success=2 default=ignore] pam_unix2.so
              auth [success=1 default=ignore] pam_ldap.so use_first_pass
              auth requisite pam_deny.so
              auth optional pam_mount.so

it may seem odd, but the first three lines will make it so that at least one of pam_unix2 or pam_ldap has to succeed. and as you can see, pam_mount will be run after successful authentication with these subsystems. ✨

🦋 ENCRYPTED DISKS 🦋

pam_mount supports a few types of crypto. the most common are encfs, dm-crypt and dm-crypt+LUKS.

🌈 encfs

the first one uses the FUSE layer. files within the encfs container are stored as single encrypted files on the host in a previously-existing directory. if you store lots of files, it's recommended to have a lower filesystem that is strong in this area, such as xfs — but some software and/or your partitioning decisions may force you to use a different fs, and that's okay. the 1:1 mapping of files also allows encrypted files to be reasonably efficiently rsync'ed, for example, without having to open the encrypted container. creation is done through the encfs(1) tool. 🎀

💅 dm-crypt

dm-crypt provides whole-filesystem/entire-partition encryption. you can also create a container file, but the idea is that it's represented as a block device on which you still have to create a filesystem. in fact, this way you can select a filesystem of your choice. the downside is that shrinking is often not possible (there's no such issue in encfs, because it uses the lower fs). suitable dm-crypt containers (and auxiliary files), using block devices or plain files, can be created using the pmt-ehd(8) tool. 🔥

pmt-ehd creates filesystem key material — which is a bunch of random bytes that will be used to en-/decrypt the volume. this material itself is encrypted with your own password. this is done so that you can change the password without having to reencrypt all of your data. the way that works?? obsessed. 💖

👑

LUKS is an extension for dm-crypt to support multi-password containers. unless you specifically need it, the above two solutions are recommended. don't be extra for no reason.

📝 NOTE: the key file that pmt-ehd(8) will create represents the filesystem key material as encrypted with your password. it is thus safe to store this on an unsecured filesystem. yes really. 💚

🔧 TROUBLESHOOTING 🔧

to make sure your system and, possibly, the remote server are all properly configured, you should try to mount all or some of the volumes by hand, using the same commands and mount points provided in pam_mount.conf.xml. this will save you a lot of grief, since debugging the mounting process via pam_mount is genuinely more difficult. trust. 😭

if you can mount the volumes by hand but it's not happening via pam_mount, you may want to enable the "debug" option in pam_mount.conf.xml to see what's actually going on. turn on the debug, bestie.

verify that the user owns the mount point and has sufficient permissions over it. pam_mount will verify this itself and will refuse to mount the remote volume if the user does not own that directory. it's giving boundaries. 💅

if pam_mount is having trouble unmounting volumes upon logging out, enable the debug variable. this causes pam_mount to run ofl on logout and write its output to the system's log. 📋

🌟 AUTHORS 🌟

  • W. Michael Petullo
  • Jan Engelhardt (current maintainer) 👑

🫶 COMMUNITY SUPPORT 🫶

the following two forms of communication are available. the maintainer has no preference, though you will reach more users who could answer by means of the mailing list. so like, the mailing list is lowkey the move. 📬

https://sf.net/projects/pam-mount/support

and that's the whole page, bestie — this was pam_mount from the pam_mount 2.23 release, dated 2026-03-26 (the pam_mount(8) manual, if you're keeping score). go mount something responsibly 💖✨🎀🦋🌸

📦 where this page comes from