persistent-keyring(7)

💖 persistent-keyring(7) 💖

okay so bestie, welcome to the Miscellaneous Information Manual section — yeah we're in the misc aisle today, and we are talking about the per-user persistent keyring. yes it's a whole thing and yes it's lowkey iconic. let's get into it 🫶

---

✨ NAME ✨

persistent-keyring — the per-user persistent keyring, aka the keyring that refuses to die with your session 💅

---

🌸 DESCRIPTION 🌸

okay so the persistent keyring is a keyring that exists to anchor keys on behalf of a user. every single UID the kernel deals with gets its own persistent keyring, and it's shared between all threads owned by that UID. one keyring, all your threads, no drama, we love a communal vibe 💖

it's got a name (a "description", if we're being formal) shaped exactly like this:

_persistent.<UID>

where <UID> is the user ID of the corresponding user. cute, right? very on-brand 🎀

here's the twist though: you can not access the persistent keyring directly. no, not even if you're a process with the appropriate UID. like, it doesn't matter how valid your credentials are, bestie — it's not answering the door. instead, it has to be linked to one of a process's keyrings first, and only then can that keyring access the persistent keyring by virtue of its possessor permits. that linking is done with the keyctl_get_persistent(3) function. that's the move. that's the whole ritual ✨

and if a persistent keyring doesn't exist yet when it gets accessed by keyctl_get_persistent(3)? boom, it's automatically created. no setup required, it just manifests 😌

---

every single time the keyctl_get_persistent(3) operation is performed, the persistent keyring's expiration timer gets reset to the value sitting in:

/proc/sys/kernel/keys/persistent_keyring_expiry

if that timeout is ever reached, the persistent keyring gets removed, and everything it was pinning down can then be garbage collected. it'll just get re-created on a subsequent call to keyctl_get_persistent(3) like nothing happened. phoenix energy fr fr 🔥

also, heads up: the persistent keyring is not directly searched by request_key(2). it only gets searched if it's been linked into one of the keyrings that is searched by request_key(2). so it's giving "only here if you invited me to the party" 🎀

the persistent keyring is independent of clone(2), fork(2), vfork(2), execve(2), and _exit(3). it persists until its expiration timer triggers, at which point it gets garbage collected. and that is the whole point, because it lets the persistent keyring carry keys beyond the life of the kernel's record of the corresponding UID (and destroying that record is exactly what takes down user-keyring(7) and user-session-keyring(7)). so the persistent keyring can hold authentication tokens for processes that run with no user interaction at all — like programs started by cron(8). bestie those lil cron jobs stay authenticated, no cap 👑

it's used to store UID-specific objects that themselves have limited lifetimes (kerberos tokens, for example 🍓). and if those tokens stop being used — meaning the persistent keyring isn't being accessed — then the persistent keyring's timeout makes sure the corresponding objects get automatically discarded. self-cleaning, self-care, we stan 🌈

---

🔑 Special operations 🔑

the keyutils library gives you the keyctl_get_persistent(3) function for manipulating persistent keyrings. (it's an interface to the keyctl(2) KEYCTL_GET_PERSISTENT operation, iykyk.) this operation lets the calling thread get the persistent keyring corresponding to its own UID — or, if the thread has the CAP_SETUID capability, the persistent keyring corresponding to some other UID in the same user namespace. flexing that capability, we see you 💅

---

📝 NOTES 📝

every user namespace owns a keyring called .persistent_register, and it contains links to all of the persistent keys in that namespace. (you can see the .persistent_register keyring when you read the contents of the /proc/keys file for the UID 0 in the namespace — peek at your own risk, it's giving archives 🗂️)

the keyctl_get_persistent(3) operation looks for a key with a name of the form _persistent.UID in that keyring, creates the key if it does not exist, and links it into the keyring. find it or found it, either way it ends up linked ✨

---

👀 SEE ALSO 👀

• keyctl(1)
• keyctl(3)
• keyctl_get_persistent(3)
• keyrings(7)
• process-keyring(7)
• session-keyring(7)
• thread-keyring(7)
• user-keyring(7)
• user-session-keyring(7)

go read them, they're all part of the family 💜

---

and that's the whole page bestie!! this was brought to you by Linux man-pages 6.20, dated 2026-06-05, and that date is giving "we're so back" ⭐ stay persistent (literally), protect your keys, and go touch some grass in a way that's independent of fork(2) 🌸💅🎀