xref: /freebsd/share/man/man9/p_candebug.9 (revision 56b17de1e8360fe131d425de20b5e75ff3ea897c)
1.\"
2.\" Copyright (c) 2003 Joseph Koshy <jkoshy@FreeBSD.org>
3.\" Copyright (c) 2023 Olivier Certner <olce.freebsd@certner.fr>
4.\"
5.\" All rights reserved.
6.\"
7.\" This program is free software.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
19.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
20.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
21.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
23.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
24.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
25.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
27.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28.\"
29.Dd August 18, 2023
30.Dt P_CANDEBUG 9
31.Os
32.Sh NAME
33.Nm p_candebug
34.Nd determine debuggability of a process
35.Sh SYNOPSIS
36.In sys/param.h
37.In sys/proc.h
38.Ft int
39.Fn p_candebug "struct thread *td" "struct proc *p"
40.Sh DESCRIPTION
41This function determines if a given process
42.Fa p
43is debuggable by some thread
44.Fa td .
45.Pp
46The following
47.Xr sysctl 8
48variables directly influence the behaviour of
49.Fn p_candebug :
50.Bl -tag -width indent
51.It Va security.bsd.unprivileged_proc_debug
52Must be set to a non-zero value to allow unprivileged processes
53access to the kernel's debug facilities.
54.It Va kern.securelevel
55Debugging of the init process is not allowed if this variable is
56.Li 1
57or greater.
58.El
59.Pp
60Other such variables indirectly influence it; see
61.Xr cr_bsd_visible 9 .
62.Sh RETURN VALUES
63The
64.Fn p_candebug
65function
66returns
67.Li 0
68if the process denoted by
69.Fa p
70is debuggable by thread
71.Fa td ,
72or a non-zero error return value otherwise.
73.Sh ERRORS
74.Bl -tag -width Er
75.It Bq Er EPERM
76An unprivileged process attempted to debug another process but the system is
77configured to deny it
78.Po
79see
80.Xr sysctl 8
81variable
82.Va security.bsd.unprivileged_proc_debug
83above
84.Pc .
85.It Bq Er ESRCH
86Thread
87.Fa td
88has been jailed and the process to debug does not belong to the same jail or one
89of its sub-jails, as determined by
90.Xr prison_check 9 .
91.It Bq Er ESRCH
92.Xr cr_bsd_visible 9
93denied visibility according to the BSD security policies in force.
94.It Bq Er EPERM
95Thread
96.Fa td
97lacks superuser credentials and its (effective) group set is not a superset of
98process
99.Fa p Ns 's
100whole group set
101.Pq "including real, effective and saved group IDs" .
102.It Bq Er EPERM
103Thread
104.Fa td
105lacks superuser credentials and its (effective) user ID does not match all user
106IDs of process
107.Fa p .
108.It Bq Er EPERM
109Thread
110.Fa td
111lacks superuser credentials and process
112.Fa p
113is executing a set-user-ID or set-group-ID executable.
114.It Bq Er EPERM
115Process
116.Fa p
117denotes the initial process
118.Fn initproc
119and the
120.Xr sysctl 8
121variable
122.Va kern.securelevel
123is greater than zero.
124.It Bq Er EBUSY
125Process
126.Fa p
127is in the process of being
128.Fn exec Ns 'ed.
129.It Bq Er EPERM
130Process
131.Fa p
132denied debuggability
133.Po
134see
135.Xr procctl 2 ,
136command
137.Dv PROC_TRACE_CTL
138.Pc .
139.El
140.Sh SEE ALSO
141.Xr procctl 2 ,
142.Xr cr_bsd_visible 9 ,
143.Xr mac 9 ,
144.Xr p_cansee 9 ,
145.Xr prison_check 9
146