git: 1ac08a43cf65 - main - pdfork.2: document cap mode, namely pdopenpid(2) and pdptrace(2) errors

The branch main has been updated by kib:

URL: https://cgit.FreeBSD.org/src/commit/?id=1ac08a43cf657564ebc2e036434e89552a6d3829

commit 1ac08a43cf657564ebc2e036434e89552a6d3829
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2026-07-07 23:51:15 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
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 ,