[PATCH 00/15] [libcap] Manual pages: various fixes

[PATCH 00/15] [libcap] Manual pages: various fixes

[Michael Kerrisk (man-pages)]

Hello Andrew,

There's a range of changes in this series. Some are trivial
fixes, and a few are more substantial. The first 11 patches are,
I think, uncontentious.

I would be happy if you check the details in patches patches 12 and 13:

  Manual pages: cap_get_file.3: NOTES: note the effect of the Ambient set
  Manual pages: cap_get_proc.3: Update description of capsetp()

and I've placed the last two patches at the and because there's
a (hopefully small) chance that you disagree with them.

Michael Kerrisk (man-pages) (15):
  Manual pages: various pages: Use "\-" for real minus signs
  Manual pages: cap_init.3: Formatting fix
  Manual pages: capsh.1: Various minor wording and formatting fixes
  Manual pages: cap_copy_ext.3: Typo fix
  Manual pages; cap_get_file.3: Fix some clumsily worded text
  Manual pages: getcap.8: Add missing word
  Manual pages: getcap.8: Fix a clumsily worded sentence
  Manual pages: getpcaps.8: Format options as a hanging list
  Manual pages: getpcaps.8: Remove a stray .br macro
  Manual pages: getpcaps.8: SEE ALSO: fix section number for capsh
  Manual pages: setcap.8: Typo fix
  Manual pages: cap_get_file.3: NOTES: note the effect of the Ambient set
  Manual pages: cap_get_proc.3: Update description of capsetp()
  Manual pages: cap_get_proc.3, capsh.1: Use "UID" and "GID" consistently
  Manual pages: capsh.1: Change .TP indent to the default

 doc/cap_copy_ext.3 |  2 +-
 doc/cap_get_file.3 | 19 +++++++----
 doc/cap_get_proc.3 | 50 +++++++++++++++++-----------
 doc/cap_init.3     |  2 +-
 doc/capsh.1        | 81 ++++++++++++++++++++++++++++------------------
 doc/getcap.8       |  4 +--
 doc/getpcaps.8     | 17 +++++-----
 doc/libpsx.3       |  6 ++--
 doc/setcap.8       |  2 +-
 9 files changed, 111 insertions(+), 72 deletions(-)

-- 
2.26.2

[PATCH 01/15] Manual pages: various pages: Use "\-" for real minus signs

[Michael Kerrisk (man-pages)]

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 doc/cap_get_proc.3 |  8 ++++----
 doc/capsh.1        | 14 +++++++-------
 doc/getpcaps.8     |  6 +++---
 doc/libpsx.3       |  6 +++---
 4 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/doc/cap_get_proc.3 b/doc/cap_get_proc.3
index fda00e0..fce8f59 100644
--- a/doc/cap_get_proc.3
+++ b/doc/cap_get_proc.3
@@ -242,11 +242,11 @@ is packaged with a separate POSIX semantics system call library:
 If your program uses POSIX threads, to achieve meaningful POSIX
 semantics capability manipulation, you should link your program with:
 .sp
-.B ld ... -lcap -lpsx -lpthread --wrap=pthread_create
+.B ld ... \-lcap \-lpsx \-lpthread \-\-wrap=pthread_create
 .sp
 or,
 .sp
-.B gcc ... -lcap -lpsx -lpthread -Wl,-wrap,pthread_create
+.B gcc ... \-lcap \-lpsx \-lpthread \-Wl,\-wrap,pthread_create
 .sp
 When linked this way, due to linker magic, libcap uses
 .BR psx_syscall "(3) and " psx_syscall6 (3)
@@ -362,10 +362,10 @@ Note, the above sequence can be performed by the
 .B capsh
 tool as follows:
 .sp
-.B sudo /sbin/capsh --user=nobody --mode=NOPRIV --print
+.B sudo /sbin/capsh \-\-user=nobody \-\-mode=NOPRIV \-\-print
 .sp
 where
-.B --print
+.B \-\-print
 displays the resulting privilege state.
 .SH "SEE ALSO"
 .BR libcap (3),
diff --git a/doc/capsh.1 b/doc/capsh.1
index 0b987f0..242727c 100644
--- a/doc/capsh.1
+++ b/doc/capsh.1
@@ -107,7 +107,7 @@ preparations for setting the uid without dropping capabilities in the
 process. Following this command the prevailing effective capabilities
 will be lowered.
 .TP
-.BI \-\-is-uid= <id>
+.BI \-\-is\-uid= <id>
 Exit with status 1 unless the current
 .IR uid " equals " <id> .
 .TP
@@ -120,7 +120,7 @@ using the
 .BR setgid (2)
 system call.
 .TP
-.BI \-\-is-gid= <id>
+.BI \-\-is\-gid= <id>
 Exit with status 1 unless the current
 .IR gid " equals " <id> .
 .TP
@@ -129,7 +129,7 @@ Set the supplementary groups to the numerical list provided. The
 groups are set with the
 .BR setgroups (2)
 system call. See
-.B --user
+.B \-\-user
 for a more convenient way of doing this.
 .TP
 .BI \-\-keep= <0|1>
@@ -152,7 +152,7 @@ the current process. In all cases,
 is deactivated when an
 .BR exec ()
 is performed. See
-.B --secbits
+.B \-\-secbits
 for ways to disable this feature.
 .TP
 .BI \-\-secbits= N
@@ -225,18 +225,18 @@ will cause capsh to promptly exit with a status of 1 when run on
 kernel 2.6.27.  However, when run on kernel 2.6.38 it will silently
 succeed.
 .TP
-.BI \-\-has-p= xxx
+.BI \-\-has\-p= xxx
 Exit with status 1 unless the
 .I permitted
 vector has capability
 .B xxx
 raised.
 .TP
-.B \-\-has-ambient
+.B \-\-has\-ambient
 Performs a check to see if the running kernel supports ambient
 capabilities. If not, the capsh command exits with status 1.
 .TP
-.BI \-\-has-a= xxx
+.BI \-\-has\-a= xxx
 Exit with status 1 unless the
 .I ambient
 vector has capability
diff --git a/doc/getpcaps.8 b/doc/getpcaps.8
index 53d342e..7b73e86 100644
--- a/doc/getpcaps.8
+++ b/doc/getpcaps.8
@@ -24,13 +24,13 @@ format.
 .PP
 Optional arguments:
 .PP
-.BR --help " or " --usage
+.BR \-\-help " or " \-\-usage
 Displays usage information and exits.
 .PP
-.BR --ugly " or " --legacy
+.BR \-\-ugly " or " \-\-legacy
 Displays output in a somewhat ugly legacy format.
 .PP
-.B --verbose
+.B \-\-verbose
 Displays usage in a legacy-like format but not quite so ugly in modern
 default terminal fonts.
 .SH SEE ALSO
diff --git a/doc/libpsx.3 b/doc/libpsx.3
index 615fceb..a907d8b 100644
--- a/doc/libpsx.3
+++ b/doc/libpsx.3
@@ -11,9 +11,9 @@ psx_syscall3, psx_syscall6 \- POSIX semantics for system calls
 .sp
 Link with one of these:
 .sp
-.I   ld ... -lpsx -lpthread --wrap=pthread_create
+.I   ld ... \-lpsx \-lpthread \-\-wrap=pthread_create
 .sp
-.I   gcc ... -lpsx -lpthread -Wl,-wrap,pthread_create
+.I   gcc ... \-lpsx \-lpthread \-Wl,\-wrap,pthread_create
 .SH DESCRIPTION
 The
 .B libpsx
@@ -58,7 +58,7 @@ and
 functions.
 .SH RETURN VALUE
 The return value for system call functions is generally the value
-returned by the kernel, or -1 in the case of an error. In such cases
+returned by the kernel, or \-1 in the case of an error. In such cases
 .BR errno (3)
 is set to the detailed error value. The
 .BR psx_syscall3 " and " psx_syscall6
-- 
2.26.2

[PATCH 02/15] Manual pages: cap_init.3: Formatting fix

[Michael Kerrisk (man-pages)]

Use nonbreaking space inside 'char *'. In addition to prevent a line break
between these two tokens, the space is not widened when performing line
fill. (The filling makes it look weird.)

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 doc/cap_init.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/cap_init.3 b/doc/cap_init.3
index 96cfea6..362db66 100644
--- a/doc/cap_init.3
+++ b/doc/cap_init.3
@@ -41,7 +41,7 @@ The
 argument may identify either a
 .I cap_t
 entity, or a
-.I char *
+.I "char\ *"
 entity allocated by the
 .BR cap_to_text ()
 function.
-- 
2.26.2

[PATCH 03/15] Manual pages: capsh.1: Various minor wording and formatting fixes

[Michael Kerrisk (man-pages)]

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 doc/capsh.1 | 47 ++++++++++++++++++++++++++++++++---------------
 1 file changed, 32 insertions(+), 15 deletions(-)

diff --git a/doc/capsh.1 b/doc/capsh.1
index 242727c..f19a3ea 100644
--- a/doc/capsh.1
+++ b/doc/capsh.1
@@ -10,7 +10,8 @@ this tool. This tool provides a handy wrapper for certain types
 of capability testing and environment creation. It also provides some
 debugging features useful for summarizing capability state.
 .SH OPTIONS
-The tool takes a number of optional arguments, acting on them in the
+.B capsh
+takes a number of optional arguments, acting on them in the
 order they are provided. They are as follows:
 .TP 22
 .B \-\-help
@@ -30,7 +31,7 @@ for specific commands.
 .B ==
 Execute
 .B capsh
-again with remaining arguments. Useful for testing
+again with the remaining arguments. Useful for testing
 .BR exec ()
 behavior.
 .TP
@@ -44,11 +45,12 @@ is a text-representation of capability state as per
 .TP
 .BI \-\-drop= cap-list
 Remove the listed capabilities from the prevailing bounding set. The
-capabilities are a comma separated list of capabilities as recognized
+capabilities are a comma-separated list of capabilities as recognized
 by the
 .BR cap_from_name (3)
-function. Use of this feature requires that the capsh program is
-operating with
+function. Use of this feature requires that
+.B capsh
+is operating with
 .B CAP_SETPCAP
 in its effective set.
 .TP
@@ -57,7 +59,9 @@ Set the inheritable set of capabilities for the current process to
 equal those provided in the comma separated list. For this action to
 succeed, the prevailing process should already have each of these
 capabilities in the union of the current inheritable and permitted
-capability sets, or the capsh program is operating with
+capability sets, or
+.B capsh
+should be operating with
 .B CAP_SETPCAP
 in its effective set.
 .TP
@@ -73,7 +77,7 @@ and set them all using
 and
 .BR cap_setgroups (3).
 Following this command, the effective capabilities will be cleared,
-but the permitted set will not be so the running program is still
+but the permitted set will not be, so the running program is still
 privileged.
 .TP
 .B \-\-modes
@@ -87,7 +91,9 @@ security mode. This is a set of securebits and prevailing capability
 arrangement recommended for its pre-determined security stance.
 .TP
 .BR \-\-inmode= <mode>
-Confirm that the prevailing mode is so named, or exit with a status 1.
+Confirm that the prevailing mode is that specified in
+.IR <mode> ,
+or exit with a status 1.
 .TP
 .BI \-\-uid= id
 Force all
@@ -156,9 +162,12 @@ is performed. See
 for ways to disable this feature.
 .TP
 .BI \-\-secbits= N
-Set the security-bits for the program, this is via
-.BR prctl "(2), " PR_SET_SECUREBITS
-API, and the list of supported bits and their meaning can be found in
+Set the security-bits for the program.
+This is done using the
+.BR prctl (2)
+.B PR_SET_SECUREBITS
+operation.
+The list of supported bits and their meaning can be found in
 the
 .B <sys/secbits.h>
 header file. The program will list these bits via the
@@ -221,7 +230,9 @@ $ \fBcapsh \-\-decode=3\fP
 As the kernel evolves, more capabilities are added. This option can be used
 to verify the existence of a capability on the system. For example,
 .BI \-\-supports= cap_syslog
-will cause capsh to promptly exit with a status of 1 when run on
+will cause
+.B capsh
+to promptly exit with a status of 1 when run on
 kernel 2.6.27.  However, when run on kernel 2.6.38 it will silently
 succeed.
 .TP
@@ -234,7 +245,9 @@ raised.
 .TP
 .B \-\-has\-ambient
 Performs a check to see if the running kernel supports ambient
-capabilities. If not, the capsh command exits with status 1.
+capabilities. If not,
+.B capsh
+exits with status 1.
 .TP
 .BI \-\-has\-a= xxx
 Exit with status 1 unless the
@@ -252,8 +265,12 @@ Removes the specified ambient capability from the running process.
 .B \-\-noamb
 Drops all ambient capabilities from the running process.
 .SH "EXIT STATUS"
-Following successful execution the tool exits with status 0. Following
-an error, the tool immediately exits with status 1.
+Following successful execution,
+.B capsh
+exits with status 0. Following
+an error,
+.B capsh
+immediately exits with status 1.
 .SH AUTHOR
 Written by Andrew G. Morgan <morgan@kernel.org>.
 .SH "REPORTING BUGS"
-- 
2.26.2

[PATCH 04/15] Manual pages: cap_copy_ext.3: Typo fix

[Michael Kerrisk (man-pages)]

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 doc/cap_copy_ext.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/cap_copy_ext.3 b/doc/cap_copy_ext.3
index 18c2fe6..acbb487 100644
--- a/doc/cap_copy_ext.3
+++ b/doc/cap_copy_ext.3
@@ -34,7 +34,7 @@ function in order to hold the capability data record created from
 .BR cap_copy_ext ()
 copies a capability state in working storage, identified by
 .IR cap_p ,
-from system managed space to user-managed space (pointed to by
+from system-managed space to user-managed space (pointed to by
 .IR ext_p )
 and returns the length of the resulting data record.  The size parameter
 represents the maximum size, in bytes, of the resulting data record.  The
-- 
2.26.2

[PATCH 05/15] Manual pages; cap_get_file.3: Fix some clumsily worded text

[Michael Kerrisk (man-pages)]

Make the text a bit easier to read, and also fix the terms used.

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 doc/cap_get_file.3 | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/cap_get_file.3 b/doc/cap_get_file.3
index c028148..ceacbaf 100644
--- a/doc/cap_get_file.3
+++ b/doc/cap_get_file.3
@@ -57,12 +57,12 @@ A NULL value for
 .IR cap_p
 is used to indicate that capabilities for the file should be deleted.
 For these functions to succeed, the calling process must have the
-effective capability,
-.BR CAP_SETFCAP ,
-enabled and either the effective user ID of the process must match the
+.BR CAP_SETFCAP
+capability in its effective set
+and either the effective user ID of the process must match the
 file owner or the calling process must have the
 .B CAP_FOWNER
-flag in its effective capability set.  The effects of writing the
+capability in its effective capability set.  The effects of writing the
 capability state to any file type other than a regular file are
 undefined.
 .PP
-- 
2.26.2

[PATCH 06/15] Manual pages: getcap.8: Add missing word

[Michael Kerrisk (man-pages)]

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 doc/getcap.8 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/getcap.8 b/doc/getcap.8
index d867203..367d010 100644
--- a/doc/getcap.8
+++ b/doc/getcap.8
@@ -6,7 +6,7 @@ getcap \- examine file capabilities
 \fBgetcap\fP [\-v] [\-n] [\-r] [\-h] \fIfilename\fP [ ... ]
 .SH DESCRIPTION
 .B getcap
-displays the name and capabilities of each specified
+displays the name and capabilities of each specified file.
 .SH OPTIONS
 .TP 4
 .B \-h
-- 
2.26.2

[PATCH 07/15] Manual pages: getcap.8: Fix a clumsily worded sentence

[Michael Kerrisk (man-pages)]

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 doc/getcap.8 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/getcap.8 b/doc/getcap.8
index 367d010..2ad8092 100644
--- a/doc/getcap.8
+++ b/doc/getcap.8
@@ -20,7 +20,7 @@ a file's capabilities.
 enables recursive search.
 .TP 4
 .B \-v
-enables to display all searched entries, even if it has no file-capabilities.
+display all searched entries, even if the have no file-capabilities.
 .TP 4
 .IR filename
 One file per line.
-- 
2.26.2

[PATCH 08/15] Manual pages: getpcaps.8: Format options as a hanging list

[Michael Kerrisk (man-pages)]

Make the options list more readable.

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 doc/getpcaps.8 | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/getpcaps.8 b/doc/getpcaps.8
index 7b73e86..fb3bc65 100644
--- a/doc/getpcaps.8
+++ b/doc/getpcaps.8
@@ -23,13 +23,13 @@ the
 format.
 .PP
 Optional arguments:
-.PP
+.TP
 .BR \-\-help " or " \-\-usage
 Displays usage information and exits.
-.PP
+.TP
 .BR \-\-ugly " or " \-\-legacy
 Displays output in a somewhat ugly legacy format.
-.PP
+.TP
 .B \-\-verbose
 Displays usage in a legacy-like format but not quite so ugly in modern
 default terminal fonts.
-- 
2.26.2

[PATCH 09/15] Manual pages: getpcaps.8: Remove a stray .br macro

[Michael Kerrisk (man-pages)]

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 doc/getpcaps.8 | 1 -
 1 file changed, 1 deletion(-)

diff --git a/doc/getpcaps.8 b/doc/getpcaps.8
index fb3bc65..dadd365 100644
--- a/doc/getpcaps.8
+++ b/doc/getpcaps.8
@@ -36,7 +36,6 @@ default terminal fonts.
 .SH SEE ALSO
 .BR capabilities (7),
 .BR capsh "(8), " setcap "(8) and " getcap (8).
-.br
 .SH AUTHOR
 This manual page was originally written by Robert Bihlmeyer
 <robbe@debian.org>, for the Debian GNU/Linux system (but may be used
-- 
2.26.2

[PATCH 10/15] Manual pages: getpcaps.8: SEE ALSO: fix section number for capsh

[Michael Kerrisk (man-pages)]

capsh is in Section 1, not Section 8. Also, reformat the SEE ALSO list
in a more conventional way.

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 doc/getpcaps.8 | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/getpcaps.8 b/doc/getpcaps.8
index dadd365..d519357 100644
--- a/doc/getpcaps.8
+++ b/doc/getpcaps.8
@@ -34,8 +34,10 @@ Displays output in a somewhat ugly legacy format.
 Displays usage in a legacy-like format but not quite so ugly in modern
 default terminal fonts.
 .SH SEE ALSO
+.BR capsh (1),
 .BR capabilities (7),
-.BR capsh "(8), " setcap "(8) and " getcap (8).
+.BR getcap (8),
+.BR setcap (8)
 .SH AUTHOR
 This manual page was originally written by Robert Bihlmeyer
 <robbe@debian.org>, for the Debian GNU/Linux system (but may be used
-- 
2.26.2

[PATCH 11/15] Manual pages: setcap.8: Typo fix

[Michael Kerrisk (man-pages)]

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 doc/setcap.8 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/setcap.8 b/doc/setcap.8
index ae044aa..582c781 100644
--- a/doc/setcap.8
+++ b/doc/setcap.8
@@ -39,7 +39,7 @@ is used to remove a capability set from a file. Note, setting an empty
 capability set is
 .B not the same
 as removing it. An empty set can be used to guarantee a file is not
-executed with privilege inspite of the fact that the prevailing
+executed with privilege in spite of the fact that the prevailing
 ambient+inheritable sets would otherwise bestow capabilities on
 executed binaries.
 .PP
-- 
2.26.2

[PATCH 12/15] Manual pages: cap_get_file.3: NOTES: note the effect of the Ambient set

[Michael Kerrisk (man-pages)]

The addition of Ambient capabilities in Linux 4.3 rendered the text on
the effect of the Effective bit during execve(2) out-of-date. Fix that.
Also add a couple of paragraph breaks to improve readability.

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 doc/cap_get_file.3 | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/doc/cap_get_file.3 b/doc/cap_get_file.3
index ceacbaf..dc7b571 100644
--- a/doc/cap_get_file.3
+++ b/doc/cap_get_file.3
@@ -103,13 +103,18 @@ or
 These functions are specified by withdrawn POSIX.1e draft specification.
 .SH NOTES
 Support for file capabilities is provided on Linux since version 2.6.24.
-
+.PP
 On Linux, the file Effective set is a single bit.
 If it is enabled, then all Permitted capabilities are enabled
 in the Effective set of the calling process when the file is executed;
-otherwise, no capabilities are enabled in the process's Effective set
+otherwise, the process's Ambient capabilities
+(or, before the Linux 4.3 addition of Ambient capabilities, no capabilities)
+are enabled in the process's Effective set
 following an
-.BR execve (2).
+.BR execve (2)
+(see
+.BR capabilities (7)).
+.PP
 Because the file Effective set is a single bit,
 if any capability is enabled in the Effective set of the
 .I cap_t
-- 
2.26.2

Re: [PATCH 12/15] Manual pages: cap_get_file.3: NOTES: note the effect of the Ambient set

[Andrew G. Morgan]

I've applied all but this one. This one seems to imply that if the
effective bit is lowered, but the permitted bits are raised, the
ambient will have some sort of effect. This isn't how it works. Any
file caps (even an empty set) suppresses any effect of the ambient
vector.

Cheers

Andrew

On Mon, Jul 20, 2020 at 2:14 AM Michael Kerrisk (man-pages)
<mtk.manpages@gmail.com> wrote:
>
> The addition of Ambient capabilities in Linux 4.3 rendered the text on
> the effect of the Effective bit during execve(2) out-of-date. Fix that.
> Also add a couple of paragraph breaks to improve readability.
>
> Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
> ---
>  doc/cap_get_file.3 | 11 ++++++++---
>  1 file changed, 8 insertions(+), 3 deletions(-)
>
> diff --git a/doc/cap_get_file.3 b/doc/cap_get_file.3
> index ceacbaf..dc7b571 100644
> --- a/doc/cap_get_file.3
> +++ b/doc/cap_get_file.3
> @@ -103,13 +103,18 @@ or
>  These functions are specified by withdrawn POSIX.1e draft specification.
>  .SH NOTES
>  Support for file capabilities is provided on Linux since version 2.6.24.
> -
> +.PP
>  On Linux, the file Effective set is a single bit.
>  If it is enabled, then all Permitted capabilities are enabled
>  in the Effective set of the calling process when the file is executed;
> -otherwise, no capabilities are enabled in the process's Effective set
> +otherwise, the process's Ambient capabilities
> +(or, before the Linux 4.3 addition of Ambient capabilities, no capabilities)
> +are enabled in the process's Effective set
>  following an
> -.BR execve (2).
> +.BR execve (2)
> +(see
> +.BR capabilities (7)).
> +.PP
>  Because the file Effective set is a single bit,
>  if any capability is enabled in the Effective set of the
>  .I cap_t
> --
> 2.26.2
>

Re: [PATCH 12/15] Manual pages: cap_get_file.3: NOTES: note the effect of the Ambient set

[Michael Kerrisk (man-pages)]

Hi Andrew,

On Mon, 20 Jul 2020 at 17:36, Andrew G. Morgan <morgan@kernel.org> wrote:
>
> I've applied all but this one. This one seems to imply that if the
> effective bit is lowered, but the permitted bits are raised, the
> ambient will have some sort of effect. This isn't how it works. Any
> file caps (even an empty set) suppresses any effect of the ambient
> vector.

Thanks for catching that. I was trying to capture this piece of the
execve() transformation rules:

P'(effective)   = F(effective) ? P'(permitted) : P'(ambient)

But of course, I failed to capture the detail that it is the process's
*new* ambient set (which, as you note, is cleared if the file has any
attached capabilities) that is assigned to the effective set. Perhaps
the text is best left as is. If I have some better idea, I'll come
back to you.

Thanks,

Michael

> On Mon, Jul 20, 2020 at 2:14 AM Michael Kerrisk (man-pages)
> <mtk.manpages@gmail.com> wrote:
> >
> > The addition of Ambient capabilities in Linux 4.3 rendered the text on
> > the effect of the Effective bit during execve(2) out-of-date. Fix that.
> > Also add a couple of paragraph breaks to improve readability.
> >
> > Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
> > ---
> >  doc/cap_get_file.3 | 11 ++++++++---
> >  1 file changed, 8 insertions(+), 3 deletions(-)
> >
> > diff --git a/doc/cap_get_file.3 b/doc/cap_get_file.3
> > index ceacbaf..dc7b571 100644
> > --- a/doc/cap_get_file.3
> > +++ b/doc/cap_get_file.3
> > @@ -103,13 +103,18 @@ or
> >  These functions are specified by withdrawn POSIX.1e draft specification.
> >  .SH NOTES
> >  Support for file capabilities is provided on Linux since version 2.6.24.
> > -
> > +.PP
> >  On Linux, the file Effective set is a single bit.
> >  If it is enabled, then all Permitted capabilities are enabled
> >  in the Effective set of the calling process when the file is executed;
> > -otherwise, no capabilities are enabled in the process's Effective set
> > +otherwise, the process's Ambient capabilities
> > +(or, before the Linux 4.3 addition of Ambient capabilities, no capabilities)
> > +are enabled in the process's Effective set
> >  following an
> > -.BR execve (2).
> > +.BR execve (2)
> > +(see
> > +.BR capabilities (7)).
> > +.PP
> >  Because the file Effective set is a single bit,
> >  if any capability is enabled in the Effective set of the
> >  .I cap_t
> > --
> > 2.26.2
> >



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 13/15] Manual pages: cap_get_proc.3: Update description of capsetp()

[Michael Kerrisk (man-pages)]

The details currently provided for capsetp() were current before 2008,
but ceased to be accurate with the 2008 addition of VFS file
capabilities in 2008. Update the text accordingly.

At the same time, add a subheading, a few paragraph breaks, and a few
other wording tweaks to make the description of capgetp() and capsetp()
more readable.

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 doc/cap_get_proc.3 | 40 +++++++++++++++++++++++++++-------------
 1 file changed, 27 insertions(+), 13 deletions(-)

diff --git a/doc/cap_get_proc.3 b/doc/cap_get_proc.3
index fce8f59..40475fd 100644
--- a/doc/cap_get_proc.3
+++ b/doc/cap_get_proc.3
@@ -251,7 +251,7 @@ or,
 When linked this way, due to linker magic, libcap uses
 .BR psx_syscall "(3) and " psx_syscall6 (3)
 to perform state setting system calls.
-.PP
+.SS capgetp() and capsetp()
 The library also supports the deprecated functions:
 .PP
 .BI "int capgetp(pid_t " pid ", cap_t " cap_d );
@@ -264,14 +264,20 @@ capabilities in a pre-allocated
 .IR cap_d .
 See
 .BR cap_init ()
-for information on allocating an empty capability set. This function,
-.BR capgetp (),
-is deprecated, you should use
+for information on allocating an empty capability set. This function
+is deprecated; you should use
 .BR cap_get_pid ().
 .PP
 .BR capsetp ()
-attempts to set the capabilities of some other process(es),
-.IR pid . 
+attempts to set the capabilities of the calling porcess or of
+some other process(es),
+.IR pid .
+Note that setting capabilities of another process is only possible on older
+kernels that do not provide VFS support for setting file capabilities.
+See
+.BR capset (2)
+for information on which kernels provide such support.
+.PP
 If
 .I pid
 is positive it refers to a specific process;  if it is zero, it refers
@@ -280,29 +286,37 @@ calling process and process '1' (typically
 .BR init (8));
 other negative values refer to the
 .I \-pid
-process group.  In order to use this function, the kernel must support
+process group.
+.PP
+In order to use this function, the kernel must support
 it and the calling process must have
 .B CAP_SETPCAP
 raised in its Effective capability set. The capabilities set in the
 target process(es) are those contained in
 .IR cap_d .
+.PP
 Kernels that support filesystem capabilities redefine the semantics of
 .B CAP_SETPCAP
-and on such systems this function will always fail for any target not
+and on such systems,
+.BR capsetp ()
+will always fail for any target not
 equal to the calling process.
 .BR capsetp ()
 returns zero for success, and \-1 on failure.
-
-Where supported by the kernel, the function
+.PP
+On kernels where it is (was) supported,
 .BR capsetp ()
 should be used with care.  It existed, primarily, to overcome an early
 lack of support for capabilities in the filesystems supported by
-Linux.  Note that, by default, the only processes that have
+Linux.  Note that on older kernels where
+.BR capsetp ()
+could be used to set the capabilities of another process,
+the only processes that had
 .B CAP_SETPCAP
-available to them are processes started as a kernel thread.
+available to them by default were processes started as kernel threads.
 (Typically this includes
 .BR init (8),
-kflushd and kswapd.) You will need to recompile the kernel to modify
+kflushd and kswapd.) A kernel recompilation was needed to modify
 this default.
 .SH EXAMPLE
 The code segment below raises the
-- 
2.26.2

[PATCH 14/15] Manual pages: cap_get_proc.3, capsh.1: Use "UID" and "GID" consistently

[Michael Kerrisk (man-pages)]

Replace terms such as "uid" and "use-id" with the more conventional
abbreviation UID.  Similarly for GID.

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 doc/cap_get_proc.3 |  2 +-
 doc/capsh.1        | 18 ++++++++++--------
 2 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/doc/cap_get_proc.3 b/doc/cap_get_proc.3
index 40475fd..74e5e8c 100644
--- a/doc/cap_get_proc.3
+++ b/doc/cap_get_proc.3
@@ -349,7 +349,7 @@ effective capabilities for the caller:
 
 .fi
 Alternatively, to completely drop privilege in a program launched
-setuid-root but wanting to run as a specific user-id etc. in such a
+setuid-root but wanting to run as a specific user ID etc. in such a
 way that neither it, nor any of its children can acquire privilege
 again:
 .nf
diff --git a/doc/capsh.1 b/doc/capsh.1
index f19a3ea..d124889 100644
--- a/doc/capsh.1
+++ b/doc/capsh.1
@@ -67,7 +67,7 @@ in its effective set.
 .TP
 .BI \-\-user= username
 Assume the identity of the named user. That is, look up the user's
-.IR uid " and " gid
+UID and GID
 with
 .BR getpwuid (3)
 and their group memberships with
@@ -97,7 +97,7 @@ or exit with a status 1.
 .TP
 .BI \-\-uid= id
 Force all
-.B uid
+UID
 values to equal
 .I id
 using the
@@ -108,18 +108,19 @@ effective set.
 .BR \-\-cap\-uid= <uid>
 use the
 .BR cap_setuid (3)
-function to set the uid of the current process. This performs all
-preparations for setting the uid without dropping capabilities in the
+function to set the UID of the current process. This performs all
+preparations for setting the UID without dropping capabilities in the
 process. Following this command the prevailing effective capabilities
 will be lowered.
 .TP
 .BI \-\-is\-uid= <id>
 Exit with status 1 unless the current
-.IR uid " equals " <id> .
+UID equals
+.IR <id> .
 .TP
 .BI \-\-gid= <id>
 Force all
-.B gid
+GID
 values to equal
 .I id
 using the
@@ -128,7 +129,8 @@ system call.
 .TP
 .BI \-\-is\-gid= <id>
 Exit with status 1 unless the current
-.IR gid " equals " <id> .
+GIQ equals
+.IR <id> .
 .TP
 .BI \-\-groups= <gid-list>
 Set the supplementary groups to the numerical list provided. The
@@ -142,7 +144,7 @@ for a more convenient way of doing this.
 In a non-pure capability mode, the kernel provides liberal privilege
 to the super-user. However, it is normally the case that when the
 super-user changes
-.I uid
+UID
 to some lesser user, then capabilities are dropped. For these
 situations, the kernel can permit the process to retain its
 capabilities after a
-- 
2.26.2

[PATCH 15/15] Manual pages: capsh.1: Change .TP indent to the default

[Michael Kerrisk (man-pages)]

Currently, the long list of options in this page is formatted as a
hanging list with a very deep indent (22), which causes the rendered
text to be rather narrow. That's uncomfortable when viewing on
something other than an 80 column display, and also causes some
ugliness in line breaks and line filling. Change to the more
traditional default indentation for .TP.

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 doc/capsh.1 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/capsh.1 b/doc/capsh.1
index d124889..b02793b 100644
--- a/doc/capsh.1
+++ b/doc/capsh.1
@@ -13,7 +13,7 @@ debugging features useful for summarizing capability state.
 .B capsh
 takes a number of optional arguments, acting on them in the
 order they are provided. They are as follows:
-.TP 22
+.TP
 .B \-\-help
 Display the list of commands supported by
 .BR capsh .
-- 
2.26.2