Re: [PATCH] capabilities.7: improve internal references

Alejandro Colomar (man-pages)
2022-02-07T14:56:34Z

Hi Kir,

On 2/4/22 22:00, Kir Kolyshkin wrote:
> Trying to make this man page easier to navigate.
>
> Fix a few cases of "see above/below" without a specific reference to a
> subsection by quoting the subsection name (making it easier to look it up).
> Use the same formatting rule as used by some of the other existing
> references, i.e. italicise it.
>
> For uniformity, remove words such as "the subsection" and "under", using
> "(see|described in) <subsection title> (above|below)" template.
>
> Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>

Patch applied. Thanks,

Alex
> ---
> man7/capabilities.7 | 65 ++++++++++++++++++++++++++++-----------------
> 1 file changed, 41 insertions(+), 24 deletions(-)
>
> diff --git a/man7/capabilities.7 b/man7/capabilities.7
> index c65524496..d524288b0 100644
> --- a/man7/capabilities.7
> +++ b/man7/capabilities.7
> @@ -398,7 +398,7 @@ write a user ID mapping in a user namespace (see
> .B CAP_SYS_ADMIN
> .IR Note :
> this capability is overloaded; see
> -.IR "Notes to kernel developers" ,
> +.I Notes to kernel developers
> below.
> .IP
> .PD 0
> @@ -952,7 +952,9 @@ Since Linux 2.6.25, this is a per-thread capability set.
> In older kernels, the capability bounding set was a system wide attribute
> shared by all threads on the system.
> .IP
> -For more details on the capability bounding set, see below.
> +For more details, see
> +.I Capability bounding set
> +below.
> .TP
> .IR Ambient " (since Linux 4.3)"
> .\" commit 58319057b7847667f0c9585b9de0e8932b0fdb08
> @@ -983,12 +985,17 @@ this does not trigger the secure-execution mode described in
> A child created via
> .BR fork (2)
> inherits copies of its parent's capability sets.
> -See below for a discussion of the treatment of capabilities during
> -.BR execve (2).
> +For details on how
> +.BR execve (2)
> +affects capabilities, see
> +.I Transformation of capabilities during execve()
> +below.
> .PP
> Using
> .BR capset (2),
> -a thread may manipulate its own capability sets (see below).
> +a thread may manipulate its own capability sets; see
> +.I Programmatically adjusting capability sets
> +below.
> .PP
> Since Linux 3.2, the file
> .I /proc/sys/kernel/cap_last_cap
> @@ -1042,7 +1049,9 @@ Enabling the file effective capability bit implies
> that any file permitted or inheritable capability that causes a
> thread to acquire the corresponding permitted capability during an
> .BR execve (2)
> -(see the transformation rules described below) will also acquire that
> +(see
> +.I Transformation of capabilities during execve()
> +below) will also acquire that
> capability in its effective set.
> Therefore, when assigning capabilities to a file
> .RB ( setcap (8),
> @@ -1080,7 +1089,7 @@ it automatically uses the version 2 scheme
> .BR VFS_CAP_REVISION_3 " (since Linux 4.14)"
> .\" commit 8db6c34f1dbc8e06aa016a9b829b06902c3e1340
> Version 3 file capabilities are provided
> -to support namespaced file capabilities (described below).
> +to support namespaced file capabilities, described below.
> .IP
> As with version 2 file capabilities,
> version 3 capability masks are 64 bits in size.
> @@ -1249,8 +1258,9 @@ its permitted and effective sets will be cleared.
> For the treatment of capabilities when a process with a
> user ID of zero performs an
> .BR execve (2),
> -see below under
> -.IR "Capabilities and execution of programs by root" .
> +see
> +.I Capabilities and execution of programs by root
> +below.
> .\"
> .SS Safety checking for capability-dumb binaries
> A capability-dumb binary is an application that has been
> @@ -1306,8 +1316,9 @@ If the real or effective user ID of the process is 0 (root),
> then the file inheritable and permitted sets are ignored;
> instead they are notionally considered to be all ones
> (i.e., all capabilities enabled).
> -(There is one exception to this behavior, described below in
> -.IR "Set-user-ID-root programs that have file capabilities" .)
> +(There is one exception to this behavior, described in
> +.I Set-user-ID-root programs that have file capabilities
> +below.)
> .IP 2.
> If the effective user ID of the process is 0 (root) or
> the file effective bit is in fact enabled,
> @@ -1346,8 +1357,9 @@ can be disabled using the securebits mechanism described below.
> .\"
> .\"
> .SS Set-user-ID-root programs that have file capabilities
> -There is one exception to the behavior described under
> -.IR "Capabilities and execution of programs by root" .
> +There is one exception to the behavior described in
> +.I Capabilities and execution of programs by root
> +above.
> If (a) the binary that is being executed has capabilities attached and
> (b) the real user ID of the process is
> .I not
> @@ -1611,17 +1623,18 @@ operation.
> Setting this flag stops the kernel from adjusting the process's
> permitted, effective, and ambient capability sets when
> the thread's effective and filesystem UIDs are switched between
> -zero and nonzero values.
> -(See the subsection
> -.IR "Effect of user ID changes on capabilities" .)
> +zero and nonzero values. See
> +.I Effect of user ID changes on capabilities
> +above.
> .TP
> .B SECBIT_NOROOT
> If this bit is set, then the kernel does not grant capabilities
> when a set-user-ID-root program is executed, or when a process with
> an effective or real UID of 0 calls
> .BR execve (2).
> -(See the subsection
> -.IR "Capabilities and execution of programs by root" .)
> +(See
> +.I Capabilities and execution of programs by root
> +above.)
> .TP
> .B SECBIT_NO_CAP_AMBIENT_RAISE
> Setting this flag disallows raising ambient capabilities via the
> @@ -1695,10 +1708,11 @@ or any descendant user namespace.
> .PP
> The rules about the transformation of the process's capabilities during the
> .BR execve (2)
> -are exactly as described in the subsections
> -.IR "Transformation of capabilities during execve()"
> +are exactly as described in
> +.I Transformation of capabilities during execve()
> and
> -.IR "Capabilities and execution of programs by root" ,
> +.I Capabilities and execution of programs by root
> +above,
> with the difference that, in the latter subsection, "root"
> is the UID of the creator of the user namespace.
> .\"
> @@ -1709,8 +1723,9 @@ Traditional (i.e., version 2) file capabilities associate
> only a set of capability masks with a binary executable file.
> When a process executes a binary with such capabilities,
> it gains the associated capabilities (within its user namespace)
> -as per the rules described above in
> -"Transformation of capabilities during execve()".
> +as per the rules described in
> +.I Transformation of capabilities during execve()
> +above.
> .PP
> Because version 2 file capabilities confer capabilities to
> the executing process regardless of which user namespace it resides in,
> @@ -1732,7 +1747,9 @@ Namespaced file capabilities are recorded as version 3 (i.e.,
> .I security.capability
> extended attributes.
> Such an attribute is automatically created in the circumstances described
> -above under "File capability extended attribute versioning".
> +in
> +.I File capability extended attribute versioning
> +above.
> When a version 3
> .I security.capability
> extended attribute is created,

--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/