summaryrefslogtreecommitdiffstats
path: root/man7/capabilities.7
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man7/capabilities.7112
1 files changed, 56 insertions, 56 deletions
diff --git a/man7/capabilities.7 b/man7/capabilities.7
index c8766d2..ad087f9 100644
--- a/man7/capabilities.7
+++ b/man7/capabilities.7
@@ -25,7 +25,7 @@
.\" other capabilities where the permitted or inheritable bit is set.
.\" 2011-09-07, mtk/Serge hallyn: Add CAP_SYSLOG
.\"
-.TH Capabilities 7 2023-05-03 "Linux man-pages 6.05.01"
+.TH Capabilities 7 2024-02-25 "Linux man-pages 6.7"
.SH NAME
capabilities \- overview of Linux capabilities
.SH DESCRIPTION
@@ -40,7 +40,7 @@ Privileged processes bypass all kernel permission checks,
while unprivileged processes are subject to full permission
checking based on the process's credentials
(usually: effective UID, effective GID, and supplementary group list).
-.PP
+.P
Starting with Linux 2.2, Linux divides the privileges traditionally
associated with superuser into distinct units, known as
.IR capabilities ,
@@ -832,7 +832,7 @@ be changed and retrieved.
.IP \[bu]
The filesystem must support attaching capabilities to an executable file,
so that a process gains those capabilities when the file is executed.
-.PP
+.P
Before Linux 2.6.24, only the first two of these requirements are met;
since Linux 2.6.24, all three requirements are met.
.\"
@@ -961,7 +961,7 @@ capabilities to increase during an
.BR execve (2),
this does not trigger the secure-execution mode described in
.BR ld.so (8).
-.PP
+.P
A child created via
.BR fork (2)
inherits copies of its parent's capability sets.
@@ -970,13 +970,13 @@ For details on how
affects capabilities, see
.I Transformation of capabilities during execve()
below.
-.PP
+.P
Using
.BR capset (2),
a thread may manipulate its own capability sets; see
.I Programmatically adjusting capability sets
below.
-.PP
+.P
Since Linux 3.2, the file
.I /proc/sys/kernel/cap_last_cap
.\" commit 73efc0394e148d0e15583e13712637831f926720
@@ -1002,7 +1002,7 @@ The file capability sets,
in conjunction with the capability sets of the thread,
determine the capabilities of a thread after an
.BR execve (2).
-.PP
+.P
The three file capability sets are:
.TP
.IR Permitted " (formerly known as " forced ):
@@ -1084,7 +1084,7 @@ with version 2 capabilities;
that is, on a modern Linux system,
there may be some files with version 2 capabilities
while others have version 3 capabilities.
-.PP
+.P
Before Linux 4.14,
the only kind of file capability extended attribute
that could be attached to a file was a
@@ -1095,7 +1095,7 @@ the version of the
.I security.capability
extended attribute that is attached to a file
depends on the circumstances in which the attribute was created.
-.PP
+.P
Starting with Linux 4.14, a
.I security.capability
extended attribute is automatically created as (or converted to)
@@ -1115,13 +1115,13 @@ meaning that (a) the thread has the
capability in its own user namespace;
and (b) the UID and GID of the file inode have mappings in
the writer's user namespace.
-.PP
+.P
When a
.B VFS_CAP_REVISION_3
.I security.capability
extended attribute is created, the root user ID of the creating thread's
user namespace is saved in the extended attribute.
-.PP
+.P
By contrast, creating or modifying a
.I security.capability
extended attribute from a privileged
@@ -1132,7 +1132,7 @@ namespace where the underlying filesystem was mounted
automatically results in the creation of a version 2
.RB ( VFS_CAP_REVISION_2 )
attribute.
-.PP
+.P
Note that the creation of a version 3
.I security.capability
extended attribute is automatic.
@@ -1161,7 +1161,7 @@ and
in order for those tools to be used to create and retrieve version 3
.I security.capability
attributes.
-.PP
+.P
Note that a file can have either a version 2 or a version 3
.I security.capability
extended attribute associated with it, but not both:
@@ -1176,7 +1176,7 @@ During an
.BR execve (2),
the kernel calculates the new capabilities of
the process using the following algorithm:
-.PP
+.P
.in +4n
.EX
P'(ambient) = (file is privileged) ? 0 : P(ambient)
@@ -1191,7 +1191,7 @@ P'(inheritable) = P(inheritable) [i.e., unchanged]
P'(bounding) = P(bounding) [i.e., unchanged]
.EE
.in
-.PP
+.P
where:
.RS 4
.TP
@@ -1206,7 +1206,7 @@ denotes the value of a thread capability set after the
F()
denotes a file capability set
.RE
-.PP
+.P
Note the following details relating to the above capability
transformation rules:
.IP \[bu] 3
@@ -1222,7 +1222,7 @@ That system-wide value was employed to calculate the new permitted set during
.BR execve (2)
in the same manner as shown above for
.IR P(bounding) .
-.PP
+.P
.IR Note :
during the capability transitions described above,
file capabilities may be ignored (treated as empty) for the same reasons
@@ -1231,7 +1231,7 @@ that the set-user-ID and set-group-ID bits are ignored; see
File capabilities are similarly ignored if the kernel was booted with the
.I no_file_caps
option.
-.PP
+.P
.IR Note :
according to the rules above,
if a process with nonzero user IDs performs an
@@ -1259,7 +1259,7 @@ so that the file permitted capabilities are automatically
enabled in the process effective set when executing the file.
The kernel recognizes a file which has the effective capability bit set
as capability-dumb for the purpose of the check described here.
-.PP
+.P
When executing a capability-dumb binary,
the kernel checks if the process obtained all permitted capabilities
that were specified in the file permitted set,
@@ -1288,7 +1288,7 @@ In order to mirror traditional UNIX semantics,
the kernel performs special treatment of file capabilities when
a process with UID 0 (root) executes a program and
when a set-user-ID-root program is executed.
-.PP
+.P
After having performed any changes to the process effective ID that
were triggered by the set-user-ID mode bit of the binary\[em]e.g.,
switching the effective user ID to 0 (root) because
@@ -1306,12 +1306,12 @@ below.)
If the effective user ID of the process is 0 (root) or
the file effective bit is in fact enabled,
then the file effective bit is notionally defined to be one (enabled).
-.PP
+.P
These notional values for the file's capability sets are then used
as described above to calculate the transformation of the process's
capabilities during
.BR execve (2).
-.PP
+.P
Thus, when a process with nonzero UIDs
.BR execve (2)s
a set-user-ID-root program that does not have capabilities attached,
@@ -1319,7 +1319,7 @@ or when a process whose real and effective UIDs are zero
.BR execve (2)s
a program, the calculation of the process's new
permitted capabilities simplifies to:
-.PP
+.P
.in +4n
.EX
P'(permitted) = P(inheritable) | P(bounding)
@@ -1327,14 +1327,14 @@ P'(permitted) = P(inheritable) | P(bounding)
P'(effective) = P'(permitted)
.EE
.in
-.PP
+.P
Consequently, the process gains all capabilities in its permitted and
effective capability sets,
except those masked out by the capability bounding set.
(In the calculation of P'(permitted),
the P'(ambient) term can be simplified away because it is by
definition a proper subset of P(inheritable).)
-.PP
+.P
The special treatments of user ID 0 (root) described in this subsection
can be disabled using the securebits mechanism described below.
.\"
@@ -1358,7 +1358,7 @@ the process gains just the capabilities granted by the program
(i.e., not all capabilities,
as would occur when executing a set-user-ID-root program
that does not have any associated file capabilities).
-.PP
+.P
Note that one can assign empty capability sets to a program file,
and thus it is possible to create a set-user-ID-root program that
changes the effective and saved set-user-ID of the process
@@ -1390,29 +1390,29 @@ and thereby cannot have this capability preserved in its
permitted set when it
.BR execve (2)s
a file that has the capability in its inheritable set.
-.PP
+.P
Note that the bounding set masks the file permitted capabilities,
but not the inheritable capabilities.
If a thread maintains a capability in its inheritable set
that is not in its bounding set,
then it can still gain that capability in its permitted set
by executing a file that has the capability in its inheritable set.
-.PP
+.P
Depending on the kernel version, the capability bounding set is either
a system-wide attribute, or a per-process attribute.
-.PP
+.P
.B "Capability bounding set from Linux 2.6.25 onward"
-.PP
+.P
From Linux 2.6.25, the
.I "capability bounding set"
is a per-thread attribute.
(The system-wide capability bounding set described below no longer exists.)
-.PP
+.P
The bounding set is inherited at
.BR fork (2)
from the thread's parent, and is preserved across an
.BR execve (2).
-.PP
+.P
A thread may remove capabilities from its capability bounding set using the
.BR prctl (2)
.B PR_CAPBSET_DROP
@@ -1425,7 +1425,7 @@ A thread can determine if a capability is in its bounding set using the
.BR prctl (2)
.B PR_CAPBSET_READ
operation.
-.PP
+.P
Removing capabilities from the bounding set is supported only if file
capabilities are compiled into the kernel.
Before Linux 2.6.33,
@@ -1445,14 +1445,14 @@ begins with a full bounding set minus
.BR CAP_SETPCAP ,
because this capability has a different meaning when there are
no file capabilities.
-.PP
+.P
Removing a capability from the bounding set does not remove it
from the thread's inheritable set.
However it does prevent the capability from being added
back into the thread's inheritable set in the future.
-.PP
+.P
.B "Capability bounding set prior to Linux 2.6.25"
-.PP
+.P
Before Linux 2.6.25, the capability bounding set is a system-wide
attribute that affects all threads on the system.
The bounding set is accessible via the file
@@ -1460,14 +1460,14 @@ The bounding set is accessible via the file
(Confusingly, this bit mask parameter is expressed as a
signed decimal number in
.IR /proc/sys/kernel/cap\-bound .)
-.PP
+.P
Only the
.B init
process may set capabilities in the capability bounding set;
other than that, the superuser (more precisely: a process with the
.B CAP_SYS_MODULE
capability) may only clear capabilities from this set.
-.PP
+.P
On a standard system the capability bounding set always masks out the
.B CAP_SETPCAP
capability.
@@ -1476,7 +1476,7 @@ To remove this restriction (dangerous!), modify the definition of
in
.I include/linux/capability.h
and rebuild the kernel.
-.PP
+.P
The system-wide capability bounding set feature was added
to Linux 2.2.11.
.\"
@@ -1521,7 +1521,7 @@ and
If the filesystem UID is changed from nonzero to 0,
then any of these capabilities that are enabled in the permitted set
are enabled in the effective set.
-.PP
+.P
If a thread that has a 0 value for one or more of its user IDs wants
to prevent its permitted capability set being cleared when it resets
all of its user IDs to nonzero values, it can do so using the
@@ -1625,7 +1625,7 @@ Setting this flag disallows raising ambient capabilities via the
.BR prctl (2)
.B PR_CAP_AMBIENT_RAISE
operation.
-.PP
+.P
Each of the above "base" flags has a companion "locked" flag.
Setting any of the "locked" flags is irreversible,
and has the effect of preventing further changes to the
@@ -1636,7 +1636,7 @@ The locked flags are:
.BR SECBIT_NOROOT_LOCKED ,
and
.BR SECBIT_NO_CAP_AMBIENT_RAISE_LOCKED .
-.PP
+.P
The
.I securebits
flags can be modified and retrieved using the
@@ -1653,7 +1653,7 @@ Note that the
constants are available only after including the
.I <linux/securebits.h>
header file.
-.PP
+.P
The
.I securebits
flags are inherited by child processes.
@@ -1662,12 +1662,12 @@ During an
all of the flags are preserved, except
.B SECBIT_KEEP_CAPS
which is always cleared.
-.PP
+.P
An application can use the following call to lock itself,
and all of its descendants,
into an environment where the only way of gaining capabilities
is by executing a program with associated file capabilities:
-.PP
+.P
.in +4n
.EX
prctl(PR_SET_SECUREBITS,
@@ -1683,13 +1683,13 @@ prctl(PR_SET_SECUREBITS,
.in
.\"
.\"
-.SS Per-user-namespace """set-user-ID-root""" programs
+.SS Per-user-namespace \[dq]set-user-ID-root\[dq] programs
A set-user-ID program whose UID matches the UID that
created a user namespace will confer capabilities
in the process's permitted and effective sets
when executed by any process inside that namespace
or any descendant user namespace.
-.PP
+.P
The rules about the transformation of the process's capabilities during the
.BR execve (2)
are exactly as described in
@@ -1710,7 +1710,7 @@ it gains the associated capabilities (within its user namespace)
as per the rules described in
.I Transformation of capabilities during execve()
above.
-.PP
+.P
Because version 2 file capabilities confer capabilities to
the executing process regardless of which user namespace it resides in,
only privileged processes are permitted to associate capabilities with a file.
@@ -1723,7 +1723,7 @@ For example, in user-namespaced containers,
it can be desirable to be able to create a binary that
confers capabilities only to processes executed inside that container,
but not to processes that are executed outside the container.
-.PP
+.P
Linux 4.14 added so-called namespaced file capabilities
to support such use cases.
Namespaced file capabilities are recorded as version 3 (i.e.,
@@ -1739,7 +1739,7 @@ When a version 3
extended attribute is created,
the kernel records not just the capability masks in the extended attribute,
but also the namespace root user ID.
-.PP
+.P
As with a binary that has
.B VFS_CAP_REVISION_2
file capabilities, a binary with
@@ -1770,13 +1770,13 @@ you may find the
.I \-u <username>
option useful.
Something like:
-.PP
+.P
.in +4n
.EX
$ \fBsudo strace \-o trace.log \-u ceci ./myprivprog\fP
.EE
.in
-.PP
+.P
From Linux 2.5.27 to Linux 2.6.26,
.\" commit 5915eb53861c5776cfec33ca4fcc1fd20d66dd27 removed
.\" CONFIG_SECURITY_CAPABILITIES
@@ -1784,7 +1784,7 @@ capabilities were an optional kernel component,
and could be enabled/disabled via the
.B CONFIG_SECURITY_CAPABILITIES
kernel configuration option.
-.PP
+.P
The
.IR /proc/ pid /task/TID/status
file can be used to view the capability sets of a thread.
@@ -1798,7 +1798,7 @@ Since Linux 3.8,
all nonexistent capabilities (above
.BR CAP_LAST_CAP )
are shown as disabled (0).
-.PP
+.P
The
.I libcap
package provides a suite of routines for setting and
@@ -1816,7 +1816,7 @@ It can be found at
.br
.UR https://git.kernel.org\:/pub\:/scm\:/libs\:/libcap\:/libcap.git\:/refs/
.UE .
-.PP
+.P
Before Linux 2.6.24, and from Linux 2.6.24 to Linux 2.6.32 if
file capabilities are not enabled, a thread with the
.B CAP_SETPCAP
@@ -1867,6 +1867,6 @@ created on the system.
.BR netcap (8), \" from libcap-ng
.BR pscap (8), \" from libcap-ng
.BR setcap (8)
-.PP
+.P
.I include/linux/capability.h
in the Linux kernel source tree