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@xxxxxxxxx> 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/ http://www.alejandro-colomar.es/
