Bug 216667

Summary:	Self-contradictory description of inheritable capability set
Product:	Documentation	Reporter:	robryk
Component:	man-pages	Assignee:	documentation_man-pages (documentation_man-pages)
Status:	NEEDINFO ---
Severity:	normal	CC:	borrelli, rhmcruiser, robryk
Priority:	P1
Hardware:	All
OS:	Linux
Kernel Version:		Subsystem:
Regression:	No	Bisected commit-id:

Description robryk 2022-11-06 03:04:42 UTC

man capabilities says about the inheritable capset of a process:

> This is a set of capabilities preserved across an execve(2).  Inheritable
> capabilities remain inheritable when executing any program, (...)

I understand this to mean that any capability in the inheritable set will stay inheritable across an execve (i.e. the inheritable set will not shrink across execve).

The same manpage says in the next paragraph:

> Because inheritable capabilities are not generally preserved across execve(2)
> when running as a non-root user (...)

This seems to say the exact opposite of how I read the previous paragraph.

I am probably misunderstanding something basic here, but I am unlikely to be the only person who does so, so I think it bears making this part clearer.

(When I try to look at the rest of the manpage to get more clarity, I fail:
 - the section that describes capability transformations across execve() seems to say that inheritable capset stays constant,
 - the description of ambient capabilities implies that inheritable capabilities differ from ambient insofar ambient ones are more "durable" across execve().)

Comment 1 Monthero Ronald 2023-05-19 02:11:21 UTC

It's to make a distinction between a root user and non root user for the process. The first part of the paragraph below is for root user and the later part is for execve run as non root user. And on other hand applications ( using execve) that run with few elevated capability flags can use ambient capabilities.  The statement you quoted from man page  - Inheritable section below: 
--- 
Inheritable
              This  is  a  set of capabilities preserved across an execve(2).  Inheritable capabilities remain inheritable when executing
              any program, and inheritable capabilities are added to the permitted set when executing a program that has the  correspond‐
              ing bits set in the file inheritable set.

              Because inheritable capabilities are not generally preserved across execve(2) when running as a non-root user, applications
              that wish to run helper programs with elevated capabilities should consider using ambient capabilities, described below.
---

Comment 2 Monthero Ronald 2023-05-19 02:28:13 UTC

If curious you can also check the process capabilities set and decode their capabilities set flags for -  permitted, inherited and ambient as below.
The capabilities set can differ based on process , user and privileges 

Example:

test$ ps alx | grep docker 
4     0    2068       1  20   0 1834532 76808 -     Ssl  ?          0:16 /usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock
0  1000   70187   65976  20   0  17868  2504 pipe_r S+   pts/7      0:00 grep --color=auto docker
test$ 
test$ egrep Cap  /proc/2068/status 
CapInh:	0000000000000000
CapPrm:	000001ffffffffff
CapEff:	000001ffffffffff
CapBnd:	000001ffffffffff
CapAmb:	0000000000000000
test$ 

Decode the capability flags for this process

test$ capsh --decode=000001ffffffffff
0x000001ffffffffff=cap_chown,cap_dac_override,cap_dac_read_search,cap_fowner,cap_fsetid,cap_kill,cap_setgid,cap_setuid,cap_setpcap,cap_linux_immutable,cap_net_bind_service,cap_net_broadcast,cap_net_admin,cap_net_raw,cap_ipc_lock,cap_ipc_owner,cap_sys_module,cap_sys_rawio,cap_sys_chroot,cap_sys_ptrace,cap_sys_pacct,cap_sys_admin,cap_sys_boot,cap_sys_nice,cap_sys_resource,cap_sys_time,cap_sys_tty_config,cap_mknod,cap_lease,cap_audit_write,cap_audit_control,cap_setfcap,cap_mac_override,cap_mac_admin,cap_syslog,cap_wake_alarm,cap_block_suspend,cap_audit_read,cap_perfmon,cap_bpf,cap_checkpoint_restore
test$

Comment 3 Alejandro Colomar 2023-05-19 13:26:21 UTC

If you still feel some wording could be improved, I encourage you to send
a patch, according to the ./CONTRIBUTING file in the repo.

Comment 4 Monthero Ronald 2023-05-25 00:55:54 UTC

imho the current info of capabilities seem congruous.