Skip to contentSkip to conversation

Manual pages: getcap.8, getpcaps.8, setcap.8: SEE ALSO: add capabilities(7)

PATCH Applied Michael Kerrisk (man-pages) 2 participants 18 messages Jul 16, 2020 – Jul 17, 2020 Security (LSM)

lore
Share & tools
lore
#0 lore raw

PATCH 1/16 Manual pages: getcap.8, getpcaps.8, setcap.8: SEE ALSO: add capabilities(7)

---
 doc/getcap.8   | 1 +
 doc/getpcaps.8 | 1 +
 doc/setcap.8   | 1 +
 3 files changed, 3 insertions(+)
doc/getcap.8 +1 -0
index 05ee9bb..0547ff9 100644
@@ -31,4 +31,5 @@ https://bugzilla.kernel.org/buglist.cgi?component=libcap&list_id=1047723&product
 .SH "SEE ALSO"
 .BR cap_get_file (3),
 .BR cap_to_text (3),
+.BR capabilities (7),
 .BR setcap (8)
doc/getpcaps.8 +1 -0
index b070a3c..53d342e 100644
@@ -34,6 +34,7 @@ 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 capabilities (7),
 .BR capsh "(8), " setcap "(8) and " getcap (8).
 .br
 .SH AUTHOR
doc/setcap.8 +1 -0
index 445ed03..da95afb 100644
@@ -58,4 +58,5 @@ https://bugzilla.kernel.org/buglist.cgi?component=libcap&list_id=1047723&product
 .SH "SEE ALSO"
 .BR cap_from_text (3),
 .BR cap_get_file (3),
+.BR capabilities (7),
 .BR getcap (8)
Signature · 1 line
2.26.2
#1 lore raw

PATCH 2/16 Manual pages: cap_get_file.3, getcap.8, setcap.8: SEE ALSO: add user_namespaces(7)

Since namespaces are mentioned in this page, it's wise also to have a reference to the relevant page that explains the concept.

---
 doc/cap_get_file.3 | 3 ++-
 doc/getcap.8       | 1 +
 doc/setcap.8       | 1 +
 3 files changed, 4 insertions(+), 1 deletion(-)
doc/cap_get_file.3 +2 -1
index a99ab40..9c115a6 100644
@@ -136,4 +136,5 @@ Permitted or Inheritable flag enabled.
 .BR cap_from_text (3),
 .BR cap_get_proc (3),
 .BR cap_init (3),
-.BR capabilities (7)
+.BR capabilities (7),
+.BR user_namespaces (7)
doc/getcap.8 +1 -0
index 0547ff9..497699c 100644
@@ -32,4 +32,5 @@ https://bugzilla.kernel.org/buglist.cgi?component=libcap&list_id=1047723&product
 .BR cap_get_file (3),
 .BR cap_to_text (3),
 .BR capabilities (7),
+.BR user_namespaces (7),
 .BR setcap (8)
doc/setcap.8 +1 -0
index da95afb..99e3c36 100644
@@ -59,4 +59,5 @@ https://bugzilla.kernel.org/buglist.cgi?component=libcap&list_id=1047723&product
 .BR cap_from_text (3),
 .BR cap_get_file (3),
 .BR capabilities (7),
+.BR user_namespaces (7),
 .BR getcap (8)
Signature · 1 line
2.26.2
#2 lore raw

PATCH 3/16 Manual pages: setcap.8: Formatting fix: use bold for function name

In reply to Michael Kerrisk (man-pages)
---
 doc/setcap.8 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
doc/setcap.8 +1 -1
index 99e3c36..90aa13f 100644
@@ -25,7 +25,7 @@ argument is also verified.
 The
 .I capabilities
 are specified in the form described in
-.IR cap_from_text (3).
+.BR cap_from_text (3).
 .PP
 The special capability string,
 .BR '\-' ,
Signature · 1 line
2.26.2
#3 lore raw

PATCH 4/16 Manual pages: cap_from_text.3: typo fix

In reply to Michael Kerrisk (man-pages)
---
 doc/cap_from_text.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
doc/cap_from_text.3 +1 -1
index 455a52d..e59ca59 100644
@@ -172,7 +172,7 @@ The example program below demonstrates the use of
 .BR cap_from_text ()
 and
 .BR cap_to_text ().
-The following shell session shows a some example runs:
+The following shell session shows some example runs:
 .nf
 
 $ ./a.out "cap_chown=p cap_chown+e"
Signature · 1 line
2.26.2
#4 lore raw

PATCH 5/16 Manual pages: cap_get_file.3, getcap.8, setcap.8: clarify "namespace"

In reply to Michael Kerrisk (man-pages)

In these pages, the "namespace" that is being mentioned is the "user namespace". Make this clearer by adding the word "user".

---
 doc/cap_get_file.3 | 2 +-
 doc/getcap.8       | 2 +-
 doc/setcap.8       | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)
doc/cap_get_file.3 +1 -1
index 9c115a6..42255ee 100644
@@ -69,7 +69,7 @@ capability state to any file type other than a regular file are
 undefined.
 .PP
 A capability set held in memory can be associated with the rootid in
-use in a specific namespace. It is possible to get and set this value
+use in a specific user namespace. It is possible to get and set this value
 (in the memory copy) with
 .BR cap_get_nsowner ()
 and
doc/getcap.8 +1 -1
index 497699c..d867203 100644
@@ -13,7 +13,7 @@ displays the name and capabilities of each specified
 prints quick usage.
 .TP 4
 .B \-n
-prints any non-zero namespace rootid value found to be associated with
+prints any non-zero user namespace rootid value found to be associated with
 a file's capabilities.
 .TP 4
 .B \-r
doc/setcap.8 +1 -1
index 90aa13f..ae044aa 100644
@@ -15,7 +15,7 @@ to the
 specified.  The optional
 .B \-n <rootid>
 argument can be used to set the file capability for use only in a
-namespace with this rootid owner. The
+user namespace with this rootid owner. The
 .B \-v
 option is used to verify that the specified capabilities are currently
 associated with the file. If \-v and \-n are supplied, the
Signature · 1 line
2.26.2
#5 lore raw

PATCH 6/16 Manual pages: cap_get_file.3: Remove stray macros that have no effect

In reply to Michael Kerrisk (man-pages)

These macros give warnings from 'mandoc -T lint'.

---
 doc/cap_get_file.3 | 2 --
 1 file changed, 2 deletions(-)
doc/cap_get_file.3 +0 -2
index 42255ee..c028148 100644
@@ -6,8 +6,6 @@
 cap_get_file, cap_set_file, cap_get_fd, cap_set_fd \- capability
 manipulation on files
 .SH SYNOPSIS
-.B
-.sp
 .B #include <sys/capability.h>
 .sp
 .BI "cap_t cap_get_file(const char *" path_p );
Signature · 1 line
2.26.2
#6 lore raw

PATCH 7/16 Manual pages: cap_get_proc.3: s/UNCERTAIN/CAP_MODE_UNCERTAIN/

In reply to Michael Kerrisk (man-pages)

Use the proper name of the constant in DESCRIPTION.

---
 doc/cap_get_proc.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
doc/cap_get_proc.3 +1 -1
index b0a61d1..ded1491 100644
@@ -168,7 +168,7 @@ returns
 which
 .BR cap_get_name ()
 declares as
-.IR "UNCERTAIN" .
+.BR CAP_MODE_UNCERTAIN .
 Supported modes are:
 .BR CAP_MODE_NOPRIV ", " CAP_MODE_PURE1E_INIT " and " CAP_MODE_PURE1E .
 .PP
Signature · 1 line
2.26.2
#7 lore raw

PATCH 8/16 Manual pages: cap_get_proc.3: formatting fix

In reply to Michael Kerrisk (man-pages)
---
 doc/cap_get_proc.3 | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
doc/cap_get_proc.3 +2 -1
index ded1491..f90c4f5 100644
@@ -261,7 +261,8 @@ The library also supports the deprecated functions:
 .BR capgetp ()
 attempts to obtain the capabilities of some other process; storing the
 capabilities in a pre-allocated
-.IR cap_d . See
+.IR cap_d .
+See
 .BR cap_init ()
 for information on allocating an empty capability set. This function,
 .BR capgetp (),
Signature · 1 line
2.26.2
#8 lore raw

PATCH 9/16 Manual pages: capsh.1: spelling fixes

In reply to Michael Kerrisk (man-pages)
---
 doc/capsh.1 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
doc/capsh.1 +2 -2
index cd30dc3..24e80b7 100644
@@ -103,7 +103,7 @@ effective set.
 use the
 .BR cap_setuid (3)
 function to set the uid of the current process. This performs all
-prepations for setting the uid without dropping capabilities in the
+preparations for setting the uid without dropping capabilities in the
 process. Following this command the prevailing effective capabilities
 will be lowered.
 .TP
@@ -242,7 +242,7 @@ vector has capability
 raised.
 .TP
 .BI \-\-addamb= xxx
-Adds the specificed ambient capability to the running process.
+Adds the specified ambient capability to the running process.
 .TP
 .BI \-\-delamb= xxx
 Removes the specified ambient capability from the running process.
Signature · 1 line
2.26.2
#9 lore raw

PATCH 10/16 Manual pages: capsh.1: Remove stray .TP macro

In reply to Michael Kerrisk (man-pages)
---
 doc/capsh.1 | 2 --
 1 file changed, 2 deletions(-)
doc/capsh.1 +0 -2
index 24e80b7..522e719 100644
@@ -249,8 +249,6 @@ Removes the specified ambient capability from the running process.
 .TP
 .B \-\-noamb
 Drops all ambient capabilities from the running process.
-.TP
-
 .SH "EXIT STATUS"
 Following successful execution the tool exits with status 0. Following
 an error, the tool immediately exits with status 1.
Signature · 1 line
2.26.2
#10 lore raw

PATCH 11/16 Manual pages: capsh.1: Correct/update the Cap field example for /proc/PID/status

In reply to Michael Kerrisk (man-pages)

The /proc/1/status output shown for --decode=N is bogus (e.g., ffffffffffffffff == 64 capability bits). Furthermore, showing CAP_SETPCAP as missing from CapEff is historical, and ceased to be actual more than 10 years ago.

Replace with a more current example, and also add the CapAmb field.

This change renders some of the following text obsolete; that will be fixed in the next patch.

---
 doc/capsh.1 | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)
doc/capsh.1 +5 -4
index 522e719..916353a 100644
@@ -198,10 +198,11 @@ This is a convenience feature. If you look at
 there are some capability related fields of the following form:
 .nf
 
- CapInh:	0000000000000000
- CapPrm:	ffffffffffffffff
- CapEff:	fffffffffffffeff
- CapBnd:	ffffffffffffffff
+CapInh:	0000000000000000
+CapPrm:	0000003fffffffff
+CapEff:	0000003fffffffff
+CapBnd:	0000003fffffffff
+CapAmb:	0000000000000000
 
 .fi
 This option provides a quick way to decode a capability vector
Signature · 1 line
2.26.2
#11 lore raw

PATCH 12/16 Manual pages: capsh.1: Update the capsh --decode example

In reply to Michael Kerrisk (man-pages)

With the update to the output of /proc/1/status in the previous patch, the example no longer matches. So, add a different example.

---
 doc/capsh.1 | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)
doc/capsh.1 +5 -7
index 916353a..fd6a5ba 100644
@@ -206,15 +206,13 @@ CapAmb:	0000000000000000
 
 .fi
 This option provides a quick way to decode a capability vector
-represented in this form. For example, the missing capability from
-this effective set is 0x0100. By running:
+represented in this hexadecimal form.
+Here's an example that decodes the two lowest capability bits:
+.IP
 .nf
-
- capsh \-\-decode=0x0100
-
+$ \fBcapsh \-\-decode=3\fP
+0x0000000000000003=cap_chown,cap_dac_override
 .fi
-we observe that the missing capability is:
-.BR cap_setpcap .
 .TP
 .BI \-\-supports= xxx
 As the kernel evolves, more capabilities are added. This option can be used
Signature · 1 line
2.26.2
#12 lore raw

PATCH 13/16 Manual pages: capsh.1: Describe the argument of --secbits in more detail

In reply to Michael Kerrisk (man-pages)

The page currently gives the reader no clue about the format of the argument.

---
 doc/capsh.1 | 3 +++
 1 file changed, 3 insertions(+)
doc/capsh.1 +3 -0
index fd6a5ba..0b987f0 100644
@@ -164,6 +164,9 @@ the
 header file. The program will list these bits via the
 .B \-\-print
 command.
+The argument is expressed as a numeric bitmask,
+in any of the formats permitted by
+.BR strtoul (3).
 .TP
 .BI \-\-chroot= path
 Execute the
Signature · 1 line
2.26.2
#13 lore raw

PATCH 14/16 pam_cap.c: Spelling fix in output string

In reply to Michael Kerrisk (man-pages)
---
 pam_cap/pam_cap.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
pam_cap/pam_cap.c +1 -1
index 3030692..6927f7b 100644
@@ -321,7 +321,7 @@ int pam_sm_authenticate(pam_handle_t *pamh, int flags,
 
     } else {
 
-	D(("there are no capabilities restrctions on this user"));
+	D(("there are no capabilities restrictions on this user"));
 	return PAM_IGNORE;
 
     }
Signature · 1 line
2.26.2
#14 lore raw

PATCH 15/16 Various source files: spelling fixes on comments

In reply to Michael Kerrisk (man-pages)
---
 libcap/cap_proc.c                      | 6 +++---
 libcap/include/uapi/linux/capability.h | 2 +-
 libcap/include/uapi/linux/securebits.h | 2 +-
 psx/include/sys/psx_syscall.h          | 2 +-
 psx/psx.c                              | 6 +++---
 5 files changed, 9 insertions(+), 9 deletions(-)
libcap/cap_proc.c +3 -3
index 1c97beb..3929f66 100644
@@ -75,7 +75,7 @@ static struct syscaller_s singlethread = {
 static int _libcap_overrode_syscalls = 1;
 
 /*
- * psx_load_syscalls() is weakly defined so we can have it overriden
+ * psx_load_syscalls() is weakly defined so we can have it overridden
  * by libpsx if that library is linked. Specifically, when libcap
  * calls psx_load_sycalls() it is prepared to override the default
  * values for the syscalls that libcap uses to change security state.
@@ -238,7 +238,7 @@ cap_t cap_get_pid(pid_t pid)
 
 /*
  * set the caps on a specific process/pg etc.. The kernel has long
- * since deprecated this asynchronus interface. DON'T EXPECT THIS TO
+ * since deprecated this asynchronous interface. DON'T EXPECT THIS TO
  * EVER WORK AGAIN.
  */
 
@@ -468,7 +468,7 @@ static int _cap_set_mode(struct syscaller_s *sc, cap_mode_t flavor)
  * set, these modes cannot be undone by the affected process tree and
  * can only be done by "cap_setpcap" permitted processes. Note, a side
  * effect of this function, whether it succeeds or fails, is to clear
- * atleast the CAP_EFFECTIVE flags for the current process.
+ * at least the CAP_EFFECTIVE flags for the current process.
  */
 int cap_set_mode(cap_mode_t flavor)
 {
libcap/include/uapi/linux/capability.h +1 -1
index 3281e73..b9ae18b 100644
@@ -368,7 +368,7 @@ struct vfs_ns_cap_data {
 
 #define CAP_AUDIT_READ       37
 
-/* Alow system performace and observability privileged opeations using
+/* Alow system performance and observability privileged operations using
  * perf_events, i915_perf and other kernel subsystems. */
 
 #define CAP_PERFMON	     38
libcap/include/uapi/linux/securebits.h +1 -1
index 6dae4e9..e9b1309 100644
@@ -22,7 +22,7 @@
 #define SECBIT_NOROOT_LOCKED	(issecure_mask(SECURE_NOROOT_LOCKED))
 
 /* When set, setuid to/from uid 0 does not trigger capability-"fixup".
-   When unset, to provide compatiblility with old programs relying on
+   When unset, to provide compatibility with old programs relying on
    set*uid to gain/lose privilege, transitions to/from uid 0 cause
    capabilities to be gained/lost. */
 #define SECURE_NO_SETUID_FIXUP		2
psx/include/sys/psx_syscall.h +1 -1
index c089a88..8044fbd 100644
@@ -35,7 +35,7 @@ int __real_pthread_create(pthread_t *thread, const pthread_attr_t *attr,
 
 /*
  * psx_syscall performs the specified syscall on all psx registered
- * threads. The mecanism by which this occurs is much less efficient
+ * threads. The mechanism by which this occurs is much less efficient
  * than a standard system call on Linux, so it should only be used
  * when POSIX semantics are required to change process relevant
  * security state.
psx/psx.c +3 -3
index cabd342..b494072 100644
@@ -29,7 +29,7 @@
 #include <sys/syscall.h>
 
 /*
- * psx_load_syscalls() is weakly defined so we can have it overriden
+ * psx_load_syscalls() is weakly defined so we can have it overridden
  * by libpsx if it is linked. Specifically, when libcap calls
  * psx_load_sycalls it will override their defaut values. As can be
  * seen here this present function is a no-op. However, if libpsx is
@@ -272,7 +272,7 @@ static void _psx_forked_child(void) {
      * The only way we can get here is if state is _PSX_INFORK and was
      * previously _PSX_IDLE. However, none of the registered threads
      * exist in this newly minted child process, so we have to reset
-     * the tracking structure to avoid any confusion. We also skuttle
+     * the tracking structure to avoid any confusion. We also scuttle
      * any chance of the PSX API working on more than one thread in
      * the child by leaving the state as _PSX_INFORK. We do support
      * all psx_syscall()s by reverting to them being direct in the
@@ -343,7 +343,7 @@ static void _psx_exiting(void *node) {
 }
 
 /*
- * _psx_start_fn is a trampolene for the intended start function, it
+ * _psx_start_fn is a trampoline for the intended start function, it
  * is called blocked (_PSX_CREATE), but releases the block before
  * calling starter->fn. Before releasing the block, the TLS specific
  * attributes are initialized for use by the interrupt handler under
Signature · 1 line
2.26.2
#15 lore raw

PATCH 16/16 capsh.c: Spelling fixes in usage() message

In reply to Michael Kerrisk (man-pages)
---
 progs/capsh.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
progs/capsh.c +2 -2
index 94bf57d..7bed98e 100644
@@ -879,10 +879,10 @@ int main(int argc, char *argv[], char *envp[])
 		   "  --delamb=xxx   remove xxx,... capabilities from ambient\n"
 		   "  --noamb        reset (drop) all ambient capabilities\n"
 		   "  --caps=xxx     set caps as per cap_from_text()\n"
-		   "  --inh=xxx      set xxx,.. inheritiable set\n"
+		   "  --inh=xxx      set xxx,.. inheritable set\n"
 		   "  --secbits=<n>  write a new value for securebits\n"
 		   "  --iab=...      use cap_iab_from_text() to set iab\n"
-		   "  --keep=<n>     set keep-capabability bit to <n>\n"
+		   "  --keep=<n>     set keep-capability bit to <n>\n"
 		   "  --uid=<n>      set uid to <n> (hint: id <username>)\n"
 		   "  --cap-uid=<n>  libcap cap_setuid() to change uid\n"
 		   "  --is-uid=<n>   exit 1 if uid != <n>\n"
Signature · 1 line
2.26.2
#16 lore raw

Re: [PATCH 16/16] capsh.c: Spelling fixes in usage() message

Thanks! Applied all of them except 07_16. Instead, I've hopefully clarified the intent of the text with some quotes.

Cheers

Andrew

https://git.kernel.org/pub/scm/libs/libcap/libcap.git/commit/?id=34e4e00b983a2c0fc5f13b403871a8fb5860bb89

Quoted 26 lines · Michael Kerrisk (man-pages)
---
 progs/capsh.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
progs/capsh.c +2 -3
index 94bf57d..7bed98e 100644
@@ -879,10 +879,10 @@ int main(int argc, char *argv[], char *envp[])
                   "  --delamb=xxx   remove xxx,... capabilities from ambient\n"
                   "  --noamb        reset (drop) all ambient capabilities\n"
                   "  --caps=xxx     set caps as per cap_from_text()\n"
-                  "  --inh=xxx      set xxx,.. inheritiable set\n"
+                  "  --inh=xxx      set xxx,.. inheritable set\n"
                   "  --secbits=<n>  write a new value for securebits\n"
                   "  --iab=...      use cap_iab_from_text() to set iab\n"
-                  "  --keep=<n>     set keep-capabability bit to <n>\n"
+                  "  --keep=<n>     set keep-capability bit to <n>\n"
                   "  --uid=<n>      set uid to <n> (hint: id <username>)\n"
                   "  --cap-uid=<n>  libcap cap_setuid() to change uid\n"
                   "  --is-uid=<n>   exit 1 if uid != <n>\n"
--

2.26.2

#17 lore raw

Re: [PATCH 16/16] capsh.c: Spelling fixes in usage() message

Quoted 3 lines · Andrew G. Morgan

Thanks! Applied all of them except 07_16. Instead, I've hopefully clarified the intent of the text with some quotes.

Okay. Thanks, Andrew.

Cheers,

Michael

Quoted 30 lines

https://git.kernel.org/pub/scm/libs/libcap/libcap.git/commit/?id=34e4e00b983a2c0fc5f13b403871a8fb5860bb89

Quoted 26 lines · Michael Kerrisk (man-pages)
---
 progs/capsh.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
progs/capsh.c +2 -3
index 94bf57d..7bed98e 100644
@@ -879,10 +879,10 @@ int main(int argc, char *argv[], char *envp[])
                   "  --delamb=xxx   remove xxx,... capabilities from ambient\n"
                   "  --noamb        reset (drop) all ambient capabilities\n"
                   "  --caps=xxx     set caps as per cap_from_text()\n"
-                  "  --inh=xxx      set xxx,.. inheritiable set\n"
+                  "  --inh=xxx      set xxx,.. inheritable set\n"
                   "  --secbits=<n>  write a new value for securebits\n"
                   "  --iab=...      use cap_iab_from_text() to set iab\n"
-                  "  --keep=<n>     set keep-capabability bit to <n>\n"
+                  "  --keep=<n>     set keep-capability bit to <n>\n"
                   "  --uid=<n>      set uid to <n> (hint: id <username>)\n"
                   "  --cap-uid=<n>  libcap cap_setuid() to change uid\n"
                   "  --is-uid=<n>   exit 1 if uid != <n>\n"
--

2.26.2

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