The branch main has been updated by kib: URL: https://cgit.FreeBSD.org/src/commit/?id=1ac08a43cf657564ebc2e036434e89552a6d3829
commit 1ac08a43cf657564ebc2e036434e89552a6d3829 Author: Konstantin Belousov <[email protected]> AuthorDate: 2026-07-07 23:51:15 +0000 Commit: Konstantin Belousov <[email protected]> CommitDate: 2026-08-28 11:55:11 +0000 pdfork.2: document cap mode, namely pdopenpid(2) and pdptrace(2) errors Reviewed by: markj Sponsored by: The FreeBSD Foundation MFC after: 1 week Differential revision: https://reviews.freebsd.org/D58989 --- lib/libsys/pdfork.2 | 33 +++++++++++++++++++++++++++++++++ lib/libsys/ptrace.2 | 10 ++++++++++ 2 files changed, 43 insertions(+) diff --git a/lib/libsys/pdfork.2 b/lib/libsys/pdfork.2 index 6ac85f717d01..1806158e668f 100644 --- a/lib/libsys/pdfork.2 +++ b/lib/libsys/pdfork.2 @@ -176,6 +176,18 @@ specifying any file descriptors for the same process fail with the .Er ESRCH error. .Pp +The +.Fn pdopenpid +system call is allowed in the capability mode +.Pq see Xr capsicum 4 +when the target process is the child of the calling process, or +when the calling process is the debugger of the target process. +The debugger is attached to its target by +.Xr ptrace 2 , +.Xr pdptrace 2 , +or by other means, e.g., by debugging the target process' parent with +the follow-on-fork mode enabled. +.Pp .Fn pdgetpid queries the process ID (PID) in the process descriptor .Fa fd . @@ -454,6 +466,27 @@ The specified process does not have a file descriptor table. refers to a file that cannot be duplicated across a process boundary, such as a kqueue. .El +.Pp +The +.Fn pdptrace +system call returns the same errors as +.Xr ptrace 2 , +as well as the following specific errors: +.Bl -tag -width Er +.It Bq Er ECAPMODE +The process issuing the +.Fn pdptrace +call is in capability mode, +and the +.Dv security.bsd.allow_ptrace_in_cap_mode +tunable is set to +.Dv false . +.It Bq Er ENOTCAPABLE +The process called +.Fn pdptrace +on the process descriptor that does not have the +.Dv CAP_PTRACE +capability enabled. .Sh SEE ALSO .Xr close 2 , .Xr fork 2 , diff --git a/lib/libsys/ptrace.2 b/lib/libsys/ptrace.2 index 612de4c5fc31..2f620155eed9 100644 --- a/lib/libsys/ptrace.2 +++ b/lib/libsys/ptrace.2 @@ -180,6 +180,12 @@ process, even if the requesting process' jail is an ancestor of the target process'. These requests will fail with error .Er ESRCH . +.It Dv security.bsd.allow_ptrace_in_cap_mode +Setting this sysctl to true allows the +.Fn ptrace +requests issued by the processes in capability mode, +see +.Xr pdptrace 2 . .It Dv securelevel and init The .Xr init 1 @@ -1522,6 +1528,10 @@ enough. .Fa pve_pathlen holds the minimum buffer size required on return. .El +.It Bq ECAPMODE +The process issuing the +.Fn ptrace +call is in capability mode. .El .Sh SEE ALSO .Xr execve 2 ,
