diff options
Diffstat (limited to 'upstream/opensuse-tumbleweed/man7/capabilities.7')
| -rw-r--r-- | upstream/opensuse-tumbleweed/man7/capabilities.7 | 112 |
1 files changed, 56 insertions, 56 deletions
diff --git a/upstream/opensuse-tumbleweed/man7/capabilities.7 b/upstream/opensuse-tumbleweed/man7/capabilities.7 index c8766d2c..98b65f4f 100644 --- a/upstream/opensuse-tumbleweed/man7/capabilities.7 +++ b/upstream/opensuse-tumbleweed/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-05-02 "Linux man-pages (unreleased)" .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 |