PAGSH(1)

✨ PAGSH(1) — the AFS Command Reference glow-up ✨

okay bestie, we're in the AFS Command Reference section of the manual and today's main character is pagsh (and its lowkey retired cousin pagsh.krb). buckle up, this one's actually kind of iconic.

🌸 NAME 🌸

pagsh, pagsh.krb — creates a new PAG 💫

🎀 SYNOPSIS 🎀

pagsh

pagsh.krb

💅 DESCRIPTION 💅

so the pagsh command spins up a whole new command shell (owned by whoever ran the command, i.e. you, queen) and hooks a brand-new process authentication group — a PAG — onto both the shell and the user. and what even is a PAG? it's a number, and that number is guaranteed to identify whoever's issuing commands inside that new shell uniquely to the local Cache Manager. instead of using the issuer's UNIX UID, the Cache Manager uses the PAG to identify the issuer in the credential structure it builds to keep track of every user. it's giving unique identifier energy, fr fr.

so any tokens you snag after that (probably for other cells, no big deal) get associated with the PAG instead of with your UNIX UID. and this whole distinction thing? two big advantages, and they both eat:

• it means processes spawned by the user inherit the PAG, so they literally share the token, which means they get access to AFS as the authenticated user. like, in a lot of environments, printer daemons and other daemons run under identities (think the local superuser root) that AFS server processes only recognize as anonymous. and unless PAGs are in the picture, those daemons cannot touch files in directories whose access control lists (ACLs) don't extend permissions to the system:anyuser group. so yeah. PAGs or nothing. 🙈
• it shuts down a potential security loophole. see, UNIX lets literally anyone already logged in as the local superuser root on a machine assume any other identity by issuing the UNIX su command. if the credential structure is identified by a UNIX UID instead of a PAG, then local superuser root can just assume a UNIX UID and use whatever tokens are attached to it. using a PAG as the identifier eliminates that possibility entirely. not on our watch. 💀

and the (mostly obsolete) pagsh.krb command? same as pagsh except it ALSO sets the KRBTKFILE environment variable — the one that controls the default Kerberos v4 ticket cache — to /tmp/tktpX where X is the number of the user's PAG. this is only useful for AFS cells still using Kerberos v4 outside of AFS, and it has no effect for cells using Kerberos v5 and aklog or klog.krb5. periodt.

---

⚠️ CAUTIONS ⚠️

bestie. read this part. for real.

every PAG you create eats two of the memory slots the kernel uses to record the UNIX groups associated with a user. if none of those slots are available, the pagsh command fails. not a problem with most operating systems though, since they hand out at least 16 slots per user. slay.

in cells that don't use an AFS-modified login utility, use this command to get a PAG before you issue the klog command (or just include the -setpag argument to the klog command, your call). if a PAG is not acquired, the Cache Manager stores the token in a credential structure identified by local UID rather than PAG. and that? that creates the potential security exposure we described up in "DESCRIPTION". so don't skip it. 🫶

if users of NFS client machines for which AFS is supported are going to issue this command as part of authenticating with AFS, then do not use the fs exportafs command's -uidcheck on argument to enable UID checking on NFS/AFS Translator machines. enabling UID checking prevents this command from succeeding. see klog(1).

if UID checking is not enabled on Translator machines, then by default it is possible to issue this command on a properly configured NFS client machine that's accessing AFS via the NFS/AFS Translator — assuming that the NFS client machine is a supported system type. the pagsh binary accessed by the NFS client must be owned by, and grant setuid privilege to, the local superuser root. the complete set of mode bits must be -rwsr-xr-x. this is not a requirement when the command is issued on AFS client machines. ikyk. 👑

but if the translator machine's administrator has enabled UID checking by including the -uidcheck on argument to the fs exportafs command, the command fails with an error message similar to this one:

Warning: Remote setpag to <translator_machine> has failed (err=8). . .
setpag: Exec format error

---

🦋 EXAMPLES 🦋

in the following example, the issuer invokes the C shell instead of the default Bourne shell:

# pagsh -c /bin/csh

main character behavior honestly.

---

💖 PRIVILEGE REQUIRED 💖

None 🎀

---

🌈 SEE ALSO 🌈

aklog(1), fs_exportafs(1), klog(1), tokens(1)

---

📜 COPYRIGHT 📜

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

this documentation is covered by the IBM Public License Version 1.0. it was converted from HTML to POD by software written by Chas Williams and Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.

---

okay that's the whole page, you're fully caught up, no notes 💜 this was OpenAFS, dated 2026-07-27 — go forth and acquire your PAGs responsibly, bestie 🧚✨