AFS::PAG(3pm)

✨ NAME ✨

AFS::PAG — bestie, it's Perl bindings for AFS PAG manipulation 💅 (and yeah, that header said AFS::PAG(3pm) from User Contributed Perl Documentation, so now you know where we live 🎀)

---

🌸 SYNOPSIS 🌸

use AFS::PAG qw(hasafs setpag unlog);

if (hasafs()) {
    setpag();
    system('aklog') == 0
      or die "cannot get tokens\n";
    do_afs_things();
    unlog();
}

---

🦋 DESCRIPTION 🦋

Okay so. AFS is a distributed file system — it lets a whole bunch of different computers share files across platforms, no big deal. It takes your client credentials (we call those AFS tokens) and ties them to a Process Authentication Group, aka a PAG. And AFS::PAG? It brings the PAG manipulation functions from the libkafs or libkopenafs libraries into Perl for you. Iconic behavior, honestly. ✨

So with the functions this module hands you, a Perl program can:

• sniff out whether AFS is even available on the local system (hasafs())
• check whether it's currently running inside a PAG (haspag())
• make a brand new PAG and yeet the current process into it (setpag())
• and nuke any AFS tokens in the current PAG (unlog())

Heads up bestie: this module does not give you a direct way to get new AFS tokens. Nope. 🚫

Programs that need AFS tokens should normally go get Kerberos tickets (by whatever means, we're not judging) and then run the program aklog, which ships with most AFS distributions. That program takes the current Kerberos ticket cache, makes AFS tokens out of them, and stores them in the current PAG. And if you want those credentials isolated from the rest of the system? Call setpag() before you run aklog. The order matters, babe. 💅

---

💖 FUNCTIONS 💖

This module serves up the following functions — and nope, none of them are exported by default. You gotta ask for them.

• hasafs() — Returns true if the local host is running an AFS client, and false otherwise. That's it, that's the vibe check. 🌈
• haspag() — Returns true if the current process is running inside a PAG, false otherwise. Okay so here's the tea: AFS tokens obtained outside of a PAG are visible to any process on the system outside of a PAG that's running as the same UID. AFS tokens obtained inside a PAG are visible to any process in the same PAG — regardless of UID. Wild, right? 😭
• setpag() — Creates a new, empty PAG and puts the current process in it. You should normally call this before obtaining new AFS tokens, so those tokens stay isolated from other processes on the system. Returns true on success, and throws an exception on failure. 🫶
• unlog() — Deletes all AFS tokens in the current PAG. It's giving kdestroy but for a Kerberos ticket cache. Returns true on success, and throws an exception on failure. 💀

---

🎀 DIAGNOSTICS 🎀

• PAG creation failed: %s — so setpag() failed. The end of that error message is gonna be a translation of the system call error number. Not the moment, fr fr. 😭
• Token deletion failed: %s — unlog() failed. Same deal: the tail end of the message is a translation of the system call error number. 🙈

---

⚠️ RESTRICTIONS ⚠️

Real talk, let's set expectations:

• This module currently does not provide the k_pioctl() or pioctl() function for making lower-level AFS system calls. Nope.
• It also doesn't provide the libkafs functions that would obtain AFS tokens from Kerberos tickets directly, without going through an external ticket cache.

And because of that last one, you can't use internal Kerberos ticket caches (like memory caches) 🔥 — since the Kerberos tickets used to generate AFS tokens have to be visible to an external aklog program. Periodt.

---

👑 AUTHOR 👑

Russ Allbery <rra@cpan.org>

---

🌟 SEE ALSO 🌟

• aklog(1)

The current version of this module is always available from its web site at http://www.eyrie.org/~eagle/software/afs-pag/.

---

And that's a wrap, bestie 🫶 this was perl v5.42.3, dated 2026-08-19, and it's the AFS::PAG(3pm) page — go forth and isolate your tokens, you absolute icon 💅✨