CAPNG_APPLY(3)

✨ CAPNG_APPLY ✨

okay bestie, gather round, because this is the capng_apply page from the Libcap-ng API and it's lowkey the moment where all your carefully hoarded capability settings actually get yeeted into the kernel. 💅

🌸 NAME 🌸

capng_apply — apply the stored capabilities settings

🎀 SYNOPSIS 🎀

#include <cap-ng.h>

int capng_apply(capng_select_t set);

🦋 DESCRIPTION 🦋

so here's the tea: capng_apply transfers the internal POSIX capabilities settings you've been curating (slay) over to the kernel. it's the "go" button. the "post it" button. the "manifest it and it's real now" button. 🔥

and you get to pick what gets applied with the set argument:

• CAPNG_SELECT_CAPS — the traditional capabilities, classic behavior, iconic ✨
• CAPNG_SELECT_BOUNDS — the bounding set
• CAPNG_SELECT_BOTH — when you want both of them, because why choose 😌
• CAPNG_SELECT_AMBIENT — if you're only operating on the ambient capabilities
• CAPNG_SELECT_ALL — applying literally everything, main character energy, no crumbs left 👑

💖 RETURN VALUE 💖

it returns 0 on success, and a negative value on failure. and babes, the negative values are specific. here's the whole roster, no skips:

• -1 — not initialized
• -2 — CAPNG_SELECT_BOUNDS and failure to drop a bounding set capability
• -3 — CAPNG_SELECT_BOUNDS and failure to re-read bounding set
• -4 — CAPNG_SELECT_BOUNDS and process does not have CAP_SETPCAP
• -5 — CAPNG_SELECT_CAPS and failure in capset syscall
• -6 — CAPNG_SELECT_AMBIENT and process has no capabilities and failed clearing ambient capabilities
• -7 — CAPNG_SELECT_AMBIENT and process has capabilities and failed clearing ambient capabilities
• -8 — CAPNG_SELECT_AMBIENT and process has capabilities and failed setting an ambient capability
• -9 — Unable to acquire process capabilities to check if CAP_SETPCAP is set.

not me getting a -9 and spiraling 😭 every single one of these is a real, distinct vibe check failure, so read the number, don't just assume.

⭐ NOTES ⭐

okay this part is important, bestie, so sit up. 🫶

if you are doing multi-threaded programming, calling this function will only set capabilities on the calling thread. all other threads are unaffected. so if you want to set overall capabilities for a multi-threaded process, you will need to do that before creating any threads. periodt. see the capset syscall for more information on this topic.

also — and this is the part that gets people — bits in the bounding set can only be dropped. you cannot set them. it's giving one-way street, no u-turns, no take-backs 💀 after dropping bounding set capabilities, the bounding set is synchronized with the kernel to reflect the true state in the kernel.

🌈 SEE ALSO 🌈

• capset(2)
• capng_update(3)
• capabilities(7)

👑 AUTHOR 👑

Steve Grubb

and that's the whole page, bestie. this is CAPNG_APPLY(3) from the Libcap-ng API, brought to you by Red Hat, dated Sept 2023. go forth and apply those capabilities, you absolute icon 💜🦋✨