* [PATCH 01/15] Manual pages: various pages: Use "\-" for real minus signs
2020-07-20 9:13 [PATCH 00/15] [libcap] Manual pages: various fixes Michael Kerrisk (man-pages)
@ 2020-07-20 9:13 ` Michael Kerrisk (man-pages)
2020-07-20 9:13 ` [PATCH 02/15] Manual pages: cap_init.3: Formatting fix Michael Kerrisk (man-pages)
` (13 subsequent siblings)
14 siblings, 0 replies; 18+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-07-20 9:13 UTC (permalink / raw)
To: mtk.manpages, Andrew Morgan; +Cc: linux-security-module
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
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 02/15] Manual pages: cap_init.3: Formatting fix
2020-07-20 9:13 [PATCH 00/15] [libcap] Manual pages: various fixes Michael Kerrisk (man-pages)
2020-07-20 9:13 ` [PATCH 01/15] Manual pages: various pages: Use "\-" for real minus signs Michael Kerrisk (man-pages)
@ 2020-07-20 9:13 ` Michael Kerrisk (man-pages)
2020-07-20 9:13 ` [PATCH 03/15] Manual pages: capsh.1: Various minor wording and formatting fixes Michael Kerrisk (man-pages)
` (12 subsequent siblings)
14 siblings, 0 replies; 18+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-07-20 9:13 UTC (permalink / raw)
To: mtk.manpages, Andrew Morgan; +Cc: linux-security-module
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
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 03/15] Manual pages: capsh.1: Various minor wording and formatting fixes
2020-07-20 9:13 [PATCH 00/15] [libcap] Manual pages: various fixes Michael Kerrisk (man-pages)
2020-07-20 9:13 ` [PATCH 01/15] Manual pages: various pages: Use "\-" for real minus signs Michael Kerrisk (man-pages)
2020-07-20 9:13 ` [PATCH 02/15] Manual pages: cap_init.3: Formatting fix Michael Kerrisk (man-pages)
@ 2020-07-20 9:13 ` Michael Kerrisk (man-pages)
2020-07-20 9:13 ` [PATCH 04/15] Manual pages: cap_copy_ext.3: Typo fix Michael Kerrisk (man-pages)
` (11 subsequent siblings)
14 siblings, 0 replies; 18+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-07-20 9:13 UTC (permalink / raw)
To: mtk.manpages, Andrew Morgan; +Cc: linux-security-module
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
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 04/15] Manual pages: cap_copy_ext.3: Typo fix
2020-07-20 9:13 [PATCH 00/15] [libcap] Manual pages: various fixes Michael Kerrisk (man-pages)
` (2 preceding siblings ...)
2020-07-20 9:13 ` [PATCH 03/15] Manual pages: capsh.1: Various minor wording and formatting fixes Michael Kerrisk (man-pages)
@ 2020-07-20 9:13 ` Michael Kerrisk (man-pages)
2020-07-20 9:13 ` [PATCH 05/15] Manual pages; cap_get_file.3: Fix some clumsily worded text Michael Kerrisk (man-pages)
` (10 subsequent siblings)
14 siblings, 0 replies; 18+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-07-20 9:13 UTC (permalink / raw)
To: mtk.manpages, Andrew Morgan; +Cc: linux-security-module
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
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 05/15] Manual pages; cap_get_file.3: Fix some clumsily worded text
2020-07-20 9:13 [PATCH 00/15] [libcap] Manual pages: various fixes Michael Kerrisk (man-pages)
` (3 preceding siblings ...)
2020-07-20 9:13 ` [PATCH 04/15] Manual pages: cap_copy_ext.3: Typo fix Michael Kerrisk (man-pages)
@ 2020-07-20 9:13 ` Michael Kerrisk (man-pages)
2020-07-20 9:13 ` [PATCH 06/15] Manual pages: getcap.8: Add missing word Michael Kerrisk (man-pages)
` (9 subsequent siblings)
14 siblings, 0 replies; 18+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-07-20 9:13 UTC (permalink / raw)
To: mtk.manpages, Andrew Morgan; +Cc: linux-security-module
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
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 06/15] Manual pages: getcap.8: Add missing word
2020-07-20 9:13 [PATCH 00/15] [libcap] Manual pages: various fixes Michael Kerrisk (man-pages)
` (4 preceding siblings ...)
2020-07-20 9:13 ` [PATCH 05/15] Manual pages; cap_get_file.3: Fix some clumsily worded text Michael Kerrisk (man-pages)
@ 2020-07-20 9:13 ` Michael Kerrisk (man-pages)
2020-07-20 9:13 ` [PATCH 07/15] Manual pages: getcap.8: Fix a clumsily worded sentence Michael Kerrisk (man-pages)
` (8 subsequent siblings)
14 siblings, 0 replies; 18+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-07-20 9:13 UTC (permalink / raw)
To: mtk.manpages, Andrew Morgan; +Cc: linux-security-module
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
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 07/15] Manual pages: getcap.8: Fix a clumsily worded sentence
2020-07-20 9:13 [PATCH 00/15] [libcap] Manual pages: various fixes Michael Kerrisk (man-pages)
` (5 preceding siblings ...)
2020-07-20 9:13 ` [PATCH 06/15] Manual pages: getcap.8: Add missing word Michael Kerrisk (man-pages)
@ 2020-07-20 9:13 ` Michael Kerrisk (man-pages)
2020-07-20 9:13 ` [PATCH 08/15] Manual pages: getpcaps.8: Format options as a hanging list Michael Kerrisk (man-pages)
` (7 subsequent siblings)
14 siblings, 0 replies; 18+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-07-20 9:13 UTC (permalink / raw)
To: mtk.manpages, Andrew Morgan; +Cc: linux-security-module
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
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 08/15] Manual pages: getpcaps.8: Format options as a hanging list
2020-07-20 9:13 [PATCH 00/15] [libcap] Manual pages: various fixes Michael Kerrisk (man-pages)
` (6 preceding siblings ...)
2020-07-20 9:13 ` [PATCH 07/15] Manual pages: getcap.8: Fix a clumsily worded sentence Michael Kerrisk (man-pages)
@ 2020-07-20 9:13 ` Michael Kerrisk (man-pages)
2020-07-20 9:13 ` [PATCH 09/15] Manual pages: getpcaps.8: Remove a stray .br macro Michael Kerrisk (man-pages)
` (6 subsequent siblings)
14 siblings, 0 replies; 18+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-07-20 9:13 UTC (permalink / raw)
To: mtk.manpages, Andrew Morgan; +Cc: linux-security-module
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
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 09/15] Manual pages: getpcaps.8: Remove a stray .br macro
2020-07-20 9:13 [PATCH 00/15] [libcap] Manual pages: various fixes Michael Kerrisk (man-pages)
` (7 preceding siblings ...)
2020-07-20 9:13 ` [PATCH 08/15] Manual pages: getpcaps.8: Format options as a hanging list Michael Kerrisk (man-pages)
@ 2020-07-20 9:13 ` Michael Kerrisk (man-pages)
2020-07-20 9:13 ` [PATCH 10/15] Manual pages: getpcaps.8: SEE ALSO: fix section number for capsh Michael Kerrisk (man-pages)
` (5 subsequent siblings)
14 siblings, 0 replies; 18+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-07-20 9:13 UTC (permalink / raw)
To: mtk.manpages, Andrew Morgan; +Cc: linux-security-module
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
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 10/15] Manual pages: getpcaps.8: SEE ALSO: fix section number for capsh
2020-07-20 9:13 [PATCH 00/15] [libcap] Manual pages: various fixes Michael Kerrisk (man-pages)
` (8 preceding siblings ...)
2020-07-20 9:13 ` [PATCH 09/15] Manual pages: getpcaps.8: Remove a stray .br macro Michael Kerrisk (man-pages)
@ 2020-07-20 9:13 ` Michael Kerrisk (man-pages)
2020-07-20 9:13 ` [PATCH 11/15] Manual pages: setcap.8: Typo fix Michael Kerrisk (man-pages)
` (4 subsequent siblings)
14 siblings, 0 replies; 18+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-07-20 9:13 UTC (permalink / raw)
To: mtk.manpages, Andrew Morgan; +Cc: linux-security-module
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
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 11/15] Manual pages: setcap.8: Typo fix
2020-07-20 9:13 [PATCH 00/15] [libcap] Manual pages: various fixes Michael Kerrisk (man-pages)
` (9 preceding siblings ...)
2020-07-20 9:13 ` [PATCH 10/15] Manual pages: getpcaps.8: SEE ALSO: fix section number for capsh Michael Kerrisk (man-pages)
@ 2020-07-20 9:13 ` Michael Kerrisk (man-pages)
2020-07-20 9:13 ` [PATCH 12/15] Manual pages: cap_get_file.3: NOTES: note the effect of the Ambient set Michael Kerrisk (man-pages)
` (3 subsequent siblings)
14 siblings, 0 replies; 18+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-07-20 9:13 UTC (permalink / raw)
To: mtk.manpages, Andrew Morgan; +Cc: linux-security-module
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
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 12/15] Manual pages: cap_get_file.3: NOTES: note the effect of the Ambient set
2020-07-20 9:13 [PATCH 00/15] [libcap] Manual pages: various fixes Michael Kerrisk (man-pages)
` (10 preceding siblings ...)
2020-07-20 9:13 ` [PATCH 11/15] Manual pages: setcap.8: Typo fix Michael Kerrisk (man-pages)
@ 2020-07-20 9:13 ` Michael Kerrisk (man-pages)
2020-07-20 15:36 ` Andrew G. Morgan
2020-07-20 9:13 ` [PATCH 13/15] Manual pages: cap_get_proc.3: Update description of capsetp() Michael Kerrisk (man-pages)
` (2 subsequent siblings)
14 siblings, 1 reply; 18+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-07-20 9:13 UTC (permalink / raw)
To: mtk.manpages, Andrew Morgan; +Cc: linux-security-module
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
^ permalink raw reply related [flat|nested] 18+ messages in thread
* Re: [PATCH 12/15] Manual pages: cap_get_file.3: NOTES: note the effect of the Ambient set
2020-07-20 9:13 ` [PATCH 12/15] Manual pages: cap_get_file.3: NOTES: note the effect of the Ambient set Michael Kerrisk (man-pages)
@ 2020-07-20 15:36 ` Andrew G. Morgan
2020-07-20 20:21 ` Michael Kerrisk (man-pages)
0 siblings, 1 reply; 18+ messages in thread
From: Andrew G. Morgan @ 2020-07-20 15:36 UTC (permalink / raw)
To: Michael Kerrisk (man-pages); +Cc: LSM List
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
>
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 12/15] Manual pages: cap_get_file.3: NOTES: note the effect of the Ambient set
2020-07-20 15:36 ` Andrew G. Morgan
@ 2020-07-20 20:21 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 18+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-07-20 20:21 UTC (permalink / raw)
To: Andrew G. Morgan; +Cc: LSM List
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/
^ permalink raw reply [flat|nested] 18+ messages in thread
* [PATCH 13/15] Manual pages: cap_get_proc.3: Update description of capsetp()
2020-07-20 9:13 [PATCH 00/15] [libcap] Manual pages: various fixes Michael Kerrisk (man-pages)
` (11 preceding siblings ...)
2020-07-20 9:13 ` [PATCH 12/15] Manual pages: cap_get_file.3: NOTES: note the effect of the Ambient set Michael Kerrisk (man-pages)
@ 2020-07-20 9:13 ` Michael Kerrisk (man-pages)
2020-07-20 9:13 ` [PATCH 14/15] Manual pages: cap_get_proc.3, capsh.1: Use "UID" and "GID" consistently Michael Kerrisk (man-pages)
2020-07-20 9:13 ` [PATCH 15/15] Manual pages: capsh.1: Change .TP indent to the default Michael Kerrisk (man-pages)
14 siblings, 0 replies; 18+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-07-20 9:13 UTC (permalink / raw)
To: mtk.manpages, Andrew Morgan; +Cc: linux-security-module
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
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 14/15] Manual pages: cap_get_proc.3, capsh.1: Use "UID" and "GID" consistently
2020-07-20 9:13 [PATCH 00/15] [libcap] Manual pages: various fixes Michael Kerrisk (man-pages)
` (12 preceding siblings ...)
2020-07-20 9:13 ` [PATCH 13/15] Manual pages: cap_get_proc.3: Update description of capsetp() Michael Kerrisk (man-pages)
@ 2020-07-20 9:13 ` Michael Kerrisk (man-pages)
2020-07-20 9:13 ` [PATCH 15/15] Manual pages: capsh.1: Change .TP indent to the default Michael Kerrisk (man-pages)
14 siblings, 0 replies; 18+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-07-20 9:13 UTC (permalink / raw)
To: mtk.manpages, Andrew Morgan; +Cc: linux-security-module
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
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 15/15] Manual pages: capsh.1: Change .TP indent to the default
2020-07-20 9:13 [PATCH 00/15] [libcap] Manual pages: various fixes Michael Kerrisk (man-pages)
` (13 preceding siblings ...)
2020-07-20 9:13 ` [PATCH 14/15] Manual pages: cap_get_proc.3, capsh.1: Use "UID" and "GID" consistently Michael Kerrisk (man-pages)
@ 2020-07-20 9:13 ` Michael Kerrisk (man-pages)
14 siblings, 0 replies; 18+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-07-20 9:13 UTC (permalink / raw)
To: mtk.manpages, Andrew Morgan; +Cc: linux-security-module
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
^ permalink raw reply related [flat|nested] 18+ messages in thread