PAM_XAUTH(8)

📦
version 1.7.3 · 17 versions
, in arch rolling

✨ PAM_XAUTH — okay so like, forwarding xauth keys between users 💅

bestie this is the pam_xauth page from the Linux-PAM Manual and honestly it's giving "quietly saving your entire X session" energy. let's get into it 🫶

🌸 NAME 🌸

pam_xauth — a PAM module that forwards xauth keys between users. that's it, that's the whole vibe. ✨

🦋 SYNOPSIS 🦋

pam_xauth.so [debug] [xauthpath=/path/to/xauth] [systemuser=UID]
             [targetuser=UID]

💖 DESCRIPTION 💖

so the pam_xauth PAM module is literally designed to forward xauth keys (which people sometimes call "cookies" 🍪) between users. no cap.

here's the situation without it: when xauth is enabled and a user hits up the su(1) command to assume somebody else's privileges, that user can't access the original user's X display anymore, because the new user doesn't have the key needed to get in. rude, honestly. pam_xauth fixes this by forwarding the key from the user running su (the source user) to the user whose identity the source user is assuming (the target user) when the session is created — and then destroying the key when the session is torn down. iconic behavior, truly. 🔥

so for example: when you run su(1) from an xterm session, you'll be able to run X programs without explicitly dealing with the xauth(1) xauth command or ~/.Xauthority files. slay. no more manual key wrangling bestie.

lowkey important: pam_xauth will only forward keys if xauth can list a key connected to the $DISPLAY environment variable. so if it can't find one, no forwarding happens, periodt.

primitive access control is provided by ~/.xauth/export in the invoking user's home directory and ~/.xauth/import in the target user's home directory.

  • if a user has a ~/.xauth/import file, they will only receive cookies from users listed in that file. if there's no ~/.xauth/import file, they'll accept cookies from any other user. generous queen. 👑
  • if a user has a .xauth/export file, they will only forward cookies to users listed in that file. if there's no ~/.xauth/export file and the invoking user is not root, they'll forward cookies to any other user. if there's no ~/.xauth/export file and the invoking user is root, they will not forward cookies to other users. (root said "absolutely not" 💀)

both the import and export files support wildcards (such as *). and both can be empty, which signifies that no users are allowed. empty file = closed sign on the door, bestie.

🎀 OPTIONS 🎀

  • debug — prints debug information. for when you need to see what's actually going on in there 👀
  • xauthpath=/path/to/xauth — specify the path to the xauth program. by default it's expected in /usr/X11R6/bin/xauth, /usr/bin/xauth, or /usr/bin/X11/xauth.
  • systemuser=UID — specify the highest UID which will be assumed to belong to a "system" user. pam_xauth will refuse to forward credentials to users with a UID less than or equal to this number, except for root and the "targetuser", if specified.
  • targetuser=UID — specify a single target UID which is exempt from the systemuser check. one (1) special little exception 💜

🌈 MODULE TYPES PROVIDED 🌈

only the session type is provided. that's the only one on the menu, and she ate. 💅

⭐ RETURN VALUES ⭐

  • PAM_BUF_ERR — memory buffer error. 😭
  • PAM_PERM_DENIED — permission denied by import/export file. the files said no.
  • PAM_SESSION_ERR — cannot determine user name, UID, or access the user's home directory.
  • PAM_SUCCESS — success!! we love to see it ✨
  • PAM_USER_UNKNOWN — user not known. who is she? 🙈

🧚 EXAMPLES 🧚

add the following line to /etc/pam.d/su to forward xauth keys between users when calling su:

session  optional  pam_xauth.so

literally one line. one. line. that's the whole setup bestie 🫶

🔥 IMPLEMENTATION DETAILS 🔥

okay this part is the "iykyk" section, pay attention:

pam_xauth will work only if it is used from a setuid application in which the getuid() call returns the id of the user running the application, and for which PAM can supply the name of the account that the user is attempting to assume. the typical application of this type is su(1). the application must call both pam_open_session() and pam_close_session() with the ruid set to the uid of the calling user and the euid set to root, and must have provided as the PAM_USER item the name of the target user.

pam_xauth calls xauth(1) as the source user to extract the key for $DISPLAY, then calls xauth as the target user to merge the key into a temporary database and later remove the database.

⚠️ and here's the thing bestie: pam_xauth cannot be told to not remove the keys when the session is closed. that's just not an option. it's gonna clean up after itself whether you like it or not 💀

🌸 FILES 🌸

  • ~/.xauth/import — XXX
  • ~/.xauth/export — XXX

🦋 SEE ALSO 🦋

pam.conf(5), pam.d(5), pam(8)

💜 AUTHOR 💜

pam_xauth was written by Nalin Dahyabhai <nalin@redhat.com>, based on the original version by Michael K. Johnson <johnsonm@redhat.com>. legends, both of them 👑

and that's the whole page, bestie!! this was Linux-PAM, dated 09/27/2026 — pam_xauth(8), out. go forward those keys and stay hydrated 💖✨🎀

📦 where this page comes from