CAP_TEXT_FORMATS(7)

✨ CAPABILITY TEXT FORMATS ✨

okay bestie, so libcap(3) — the capability library, you know the one — speaks two different string dialects for talking about capabilities, and you're gonna learn both. 💅

• the original text format, made for the standard capability Set, and it's what getcap(8), setcap(8) and capsh(8) all use on the command line 🫶
• the IAB-tuple text format, which the pam_cap(8) Linux-PAM module can use, plus captree(8) and capsh(8) ✨

both of these formats get extensive support inside libcap(3), and also in the 'kernel.org/pub/linux/libs/security/libcap/cap' Go package. no cap. 🦋

---

🎀 THE CAPABILITY SET TEXT FORMAT 🎀

this one is specified in the defunct POSIX.1e draft [1] — yes, the very draft that introduced capabilities in the first place. iconic behaviour. and it can represent both process capabilities and file capabilities, so it's versatile like that. 👑

so how does the textual representation of capability sets actually go? it's one or more whitespace-separated clauses. each clause does some operations on a capability set. here's the key thing: the set starts out with all capabilities lowered, and the meaning of the whole string is just the state of the capability set after every clause has been applied, in order. ✨

each clause is a list of comma-separated capability names (or just the word all), followed by an action-list. an action-list is a sequence of operator + flag pairs. the legal operators are =, + and -. the legal flags are e, i and p. and babes, these flags are case-sensitive — they mean the Effective, Inheritable and Permitted sets respectively. 🎯

in the capability name lists, all names are case-insensitive. the special name all specifies all capabilities — it's literally equivalent to a list that names every single capability individually. 💖

you can also specify unnamed capabilities by number. why? because this feature makes sure libcap can support capabilities that weren't even allocated back when libcap was compiled. slay. but generally, upgrading libcap will add names for recently allocated capabilities, so the numbers are more of a fallback vibe. 🙈

now, the = operator: it means the listed capabilities are first reset in all three capability sets. the flags that follow (and they're optional when they're hanging out with this operator) say that the listed capabilities for the corresponding set should be raised. for example:

• "all=p" means lower every capability in the Effective and Inheritable sets, but raise all of the Permitted capabilities 🔥
• "cap_fowner=ep" means raise the Effective and Permitted override-file-ownership capability, while lowering this Inheritable capability

and here's a cute little special case: when the leading operator is = and no list of capabilities is provided, the action-list is assumed to refer to all capabilities. so these three clauses are all equivalent to each other (and yes, they all indicate a completely empty capability set):

"all=";
"=";
"cap_chown,<every-other-capability>=".

now the other two operators, + and - — they're needy, okay? both of them require an explicit preceding capability list and one or more explicit trailing flags. no exceptions. 😤

• the + operator will raise all of the listed capabilities in the flagged capability sets
• the - operator will lower all of the listed capabilities in the flagged capability sets

for example: "all+p" will raise all of the Permitted capabilities, and "cap_fowner-i" will lower the override-file-ownership in the Inheritable set. 💜

and an action list can totally consist of multiple operator flag pairs — the actions are performed in left-to-right order. so like, "cap_fowner+p-i" is equivalent to "cap_fowner+p cap_fowner-i". as another example, "cap_fowner+pe-i" and "cap_fowner=+pe" are equivalent. the more you know. ⭐

---

🌈 THE IAB TUPLE TEXT FORMAT 🌈

this format is a pure Linux extension, bestie. it started out life as the format used by pam_cap(8), and it can also be employed by capsh(8). glow up. ✨

the IAB tuple text format is a comma separated list of capability values. each capability is prefixed by:

• nothing (or %) — that's Inh 🌸
• ! — that's Bound, but think Blocked 💀
• ^ — that's Amb 🌟

...or, honestly, some combination of those. and since the Amb vector is constrained to be no greater than the Inh vector, ^ is equivalent to %^. also, unless B is non-zero, % can be omitted entirely. 🧚

the following are legal text representations:

"!%cap_chown"              (Bound but Inh)
"!cap_chown,^cap_chown"    (Bound, Inh+Amb)
"cap_setuid,!cap_chown"    (Inh, Bound)

and as noted above, this text representation is what's used in the configuration file syntax (see capability.conf(5)) for the pam_cap(8) Linux-PAM security module. iykyk. 💅

---

👑 SEE ALSO 👑

• [1] a copy of the last POSIX.1e draft for security extensions can be downloaded from the https://sites.google.com/site/fullycapable/ website. please report bugs as directed at that site. 🐛

related manual pages: libcap(3), capsh(1), setcap(8), getcap(8), captree(8), pam_cap(8), cap_from_text(3), cap_iab(3).

---

and that's the whole page, bestie — brought to you by the Linux Programmer's Manual, dated 2025-03-19. go forth and format your capabilities correctly. periodt. 💖✨🎀