1.\" Copyright (c) 2013 Hudson River Trading LLC 2.\" Written by: John H. Baldwin <[email protected]> 3.\" All rights reserved. 4.\" 5.\" Copyright (c) 2014 The FreeBSD Foundation 6.\" Portions of this documentation were written by Konstantin Belousov 7.\" under sponsorship from the FreeBSD Foundation. 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 AUTHOR AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" $FreeBSD$ 31.\" 32.Dd September 27, 2016 33.Dt PROCCTL 2 34.Os 35.Sh NAME 36.Nm procctl 37.Nd control processes 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In sys/procctl.h 42.Ft int 43.Fn procctl "idtype_t idtype" "id_t id" "int cmd" "void *arg" 44.Sh DESCRIPTION 45The 46.Fn procctl 47system call provides for control over processes. 48The 49.Fa idtype 50and 51.Fa id 52arguments specify the set of processes to control. 53If multiple processes match the identifier, 54.Nm 55will make a 56.Dq best effort 57to control as many of the selected processes as possible. 58An error is only returned if no selected processes successfully complete 59the request. 60The following identifier types are supported: 61.Bl -tag -width "Dv P_PGID" 62.It Dv P_PID 63Control the process with the process ID 64.Fa id . 65.It Dv P_PGID 66Control processes belonging to the process group with the ID 67.Fa id . 68.El 69.Pp 70The control request to perform is specified by the 71.Fa cmd 72argument. 73The following commands are supported: 74.Bl -tag -width "Dv PROC_TRAPCAP_STATUS" 75.It Dv PROC_SPROTECT 76Set process protection state. 77This is used to mark a process as protected from being killed if the system 78exhausts the available memory and swap. 79The 80.Fa arg 81parameter must point to an integer containing an operation and zero or more 82optional flags. 83The following operations are supported: 84.Bl -tag -width "Dv PPROT_CLEAR" 85.It Dv PPROT_SET 86Mark the selected processes as protected. 87.It Dv PPROT_CLEAR 88Clear the protected state of selected processes. 89.El 90.Pp 91The following optional flags are supported: 92.Bl -tag -width "Dv PPROT_DESCEND" 93.It Dv PPROT_DESCEND 94Apply the requested operation to all child processes of each selected process 95in addition to each selected process. 96.It Dv PPROT_INHERIT 97When used with 98.Dv PPROT_SET , 99mark all future child processes of each selected process as protected. 100Future child processes will also mark all of their future child processes. 101.El 102.It Dv PROC_REAP_ACQUIRE 103Acquires the reaper status for the current process. 104Reaper status means that children orphaned by the reaper's descendants 105that were forked after the acquisition of reaper status are reparented to the 106reaper process. 107After system initialization, 108.Xr init 8 109is the default reaper. 110.It Dv PROC_REAP_RELEASE 111Release the reaper state for the current process. 112The reaper of the current process becomes the new reaper of the 113current process's descendants. 114.It Dv PROC_REAP_STATUS 115Provides information about the reaper of the specified process, 116or the process itself when it is a reaper. 117The 118.Fa data 119argument must point to a 120.Vt procctl_reaper_status 121structure which is filled in by the syscall on successful return. 122.Bd -literal 123struct procctl_reaper_status { 124 u_int rs_flags; 125 u_int rs_children; 126 u_int rs_descendants; 127 pid_t rs_reaper; 128 pid_t rs_pid; 129}; 130.Ed 131The 132.Fa rs_flags 133may have the following flags returned: 134.Bl -tag -width "Dv REAPER_STATUS_REALINIT" 135.It Dv REAPER_STATUS_OWNED 136The specified process has acquired reaper status and has not 137released it. 138When the flag is returned, the specified process 139.Fa id , 140pid, identifies the reaper, otherwise the 141.Fa rs_reaper 142field of the structure is set to the pid of the reaper 143for the specified process id. 144.It Dv REAPER_STATUS_REALINIT 145The specified process is the root of the reaper tree, i.e., 146.Xr init 8 . 147.El 148.Pp 149The 150.Fa rs_children 151field returns the number of children of the reaper among the descendants. 152It is possible to have a child whose reaper is not the specified process, 153since the reaper for any existing children is not reset on the 154.Dv PROC_REAP_ACQUIRE 155operation. 156The 157.Fa rs_descendants 158field returns the total number of descendants of the reaper(s), 159not counting descendants of the reaper in the subtree. 160The 161.Fa rs_reaper 162field returns the reaper pid. 163The 164.Fa rs_pid 165returns the pid of one reaper child if there are any descendants. 166.It Dv PROC_REAP_GETPIDS 167Queries the list of descendants of the reaper of the specified process. 168The request takes a pointer to a 169.Vt procctl_reaper_pids 170structure in the 171.Fa data 172parameter. 173.Bd -literal 174struct procctl_reaper_pids { 175 u_int rp_count; 176 struct procctl_reaper_pidinfo *rp_pids; 177}; 178.Ed 179When called, the 180.Fa rp_pids 181field must point to an array of 182.Vt procctl_reaper_pidinfo 183structures, to be filled in on return, 184and the 185.Fa rp_count 186field must specify the size of the array, 187into which no more than 188.Fa rp_count 189elements will be filled in by the kernel. 190.Pp 191The 192.Vt "struct procctl_reaper_pidinfo" 193structure provides some information about one of the reaper's descendants. 194Note that for a descendant that is not a child, it may be incorrectly 195identified because of a race in which the original child process exited 196and the exited process's pid was reused for an unrelated process. 197.Bd -literal 198struct procctl_reaper_pidinfo { 199 pid_t pi_pid; 200 pid_t pi_subtree; 201 u_int pi_flags; 202}; 203.Ed 204The 205.Fa pi_pid 206field is the process id of the descendant. 207The 208.Fa pi_subtree 209field provides the pid of the child of the reaper, which is the (grand-)parent 210of the process. 211The 212.Fa pi_flags 213field returns the following flags, further describing the descendant: 214.Bl -tag -width "Dv REAPER_PIDINFO_VALID" 215.It Dv REAPER_PIDINFO_VALID 216Set to indicate that the 217.Vt procctl_reaper_pidinfo 218structure was filled in by the kernel. 219Zero-filling the 220.Fa rp_pids 221array and testing the 222.Dv REAPER_PIDINFO_VALID 223flag allows the caller to detect the end 224of the returned array. 225.It Dv REAPER_PIDINFO_CHILD 226The 227.Fa pi_pid 228field identifies the direct child of the reaper. 229.El 230.It Dv PROC_REAP_KILL 231Request to deliver a signal to some subset of the descendants of the reaper. 232The 233.Fa data 234parameter must point to a 235.Vt procctl_reaper_kill 236structure, which is used both for parameters and status return. 237.Bd -literal 238struct procctl_reaper_kill { 239 int rk_sig; 240 u_int rk_flags; 241 pid_t rk_subtree; 242 u_int rk_killed; 243 pid_t rk_fpid; 244}; 245.Ed 246The 247.Fa rk_sig 248field specifies the signal to be delivered. 249Zero is not a valid signal number, unlike for 250.Xr kill 2 . 251The 252.Fa rk_flags 253field further directs the operation. 254It is or-ed from the following flags: 255.Bl -tag -width "Dv REAPER_KILL_CHILDREN" 256.It Dv REAPER_KILL_CHILDREN 257Deliver the specified signal only to direct children of the reaper. 258.It Dv REAPER_KILL_SUBTREE 259Deliver the specified signal only to descendants that were forked by 260the direct child with pid specified in the 261.Fa rk_subtree 262field. 263.El 264If neither the 265.Dv REAPER_KILL_CHILDREN 266nor the 267.Dv REAPER_KILL_SUBTREE 268flags are specified, all current descendants of the reaper are signalled. 269.Pp 270If a signal was delivered to any process, the return value from the request 271is zero. 272In this case, the 273.Fa rk_killed 274field identifies the number of processes signalled. 275The 276.Fa rk_fpid 277field is set to the pid of the first process for which signal 278delivery failed, e.g., due to permission problems. 279If no such process exists, the 280.Fa rk_fpid 281field is set to -1. 282.It Dv PROC_TRACE_CTL 283Enable or disable tracing of the specified process(es), according to the 284value of the integer argument. 285Tracing includes attachment to the process using the 286.Xr ptrace 2 287and 288.Xr ktrace 2 , 289debugging sysctls, 290.Xr hwpmc 4 , 291.Xr dtrace 1 , 292and core dumping. 293Possible values for the 294.Fa data 295argument are: 296.Bl -tag -width "Dv PROC_TRACE_CTL_DISABLE_EXEC" 297.It Dv PROC_TRACE_CTL_ENABLE 298Enable tracing, after it was disabled by 299.Dv PROC_TRACE_CTL_DISABLE . 300Only allowed for self. 301.It Dv PROC_TRACE_CTL_DISABLE 302Disable tracing for the specified process. 303Tracing is re-enabled when the process changes the executing 304program with the 305.Xr execve 2 306syscall. 307A child inherits the trace settings from the parent on 308.Xr fork 2 . 309.It Dv PROC_TRACE_CTL_DISABLE_EXEC 310Same as 311.Dv PROC_TRACE_CTL_DISABLE , 312but the setting persists for the process even after 313.Xr execve 2 . 314.El 315.It Dv PROC_TRACE_STATUS 316Returns the current tracing status for the specified process in 317the integer variable pointed to by 318.Fa data . 319If tracing is disabled, 320.Fa data 321is set to -1. 322If tracing is enabled, but no debugger is attached by the 323.Xr ptrace 2 324syscall, 325.Fa data 326is set to 0. 327If a debugger is attached, 328.Fa data 329is set to the pid of the debugger process. 330.It Dv PROC_TRAPCAP_CTL 331Controls the capability mode sandbox actions for the specified 332sandboxed processes, 333on a return from any syscall which gives either a 334.Er ENOTCAPABLE 335or 336.Er ECAPMODE 337error. 338If the control is enabled, such errors from the syscalls cause 339delivery of the synchronous 340.Dv SIGTRAP 341signal to the thread immediately before returning from the syscalls. 342.Pp 343Possible values for the 344.Fa data 345argument are: 346.Bl -tag -width "Dv PROC_TRAPCAP_CTL_DISABLE" 347.It Dv PROC_TRAPCAP_CTL_ENABLE 348Enable the 349.Dv SIGTRAP 350signal delivery on capability mode access violations. 351The enabled mode is inherited by the children of the process, 352and is kept after 353.Xr fexecve 2 354calls. 355.It Dv PROC_TRAPCAP_CTL_DISABLE 356Disable the signal delivery on capability mode access violations. 357Note that the global sysctl 358.Dv kern.trap_enocap 359might still cause the signal to be delivered. 360See 361.Xr capsicum 4 . 362.El 363.Pp 364On signal delivery, the 365.Va si_errno 366member of the 367.Fa siginfo 368signal handler parameter is set to the syscall error value, 369and the 370.Va si_code 371member is set to 372.Dv TRAP_CAP . 373.Pp 374See 375.Xr capsicum 4 376for more information about the capability mode. 377.It Dv PROC_TRAPCAP_STATUS 378Return the current status of signalling capability mode access 379violations for the specified process. 380The integer value pointed to by the 381.Fa data 382argument is set to the 383.Dv PROC_TRAPCAP_CTL_ENABLE 384value if the process control enables signal delivery, and to 385.Dv PROC_TRAPCAP_CTL_DISABLE 386otherwise. 387.Pp 388See the note about sysctl 389.Dv kern.trap_enocap 390above, which gives independent global control of signal delivery. 391.El 392.Sh NOTES 393Disabling tracing on a process should not be considered a security 394feature, as it is bypassable both by the kernel and privileged processes, 395and via other system mechanisms. 396As such, it should not be utilized to reliably protect cryptographic 397keying material or other confidential data. 398.Sh RETURN VALUES 399If an error occurs, a value of -1 is returned and 400.Va errno 401is set to indicate the error. 402.Sh ERRORS 403The 404.Fn procctl 405system call 406will fail if: 407.Bl -tag -width Er 408.It Bq Er EFAULT 409The 410.Fa arg 411parameter points outside the process's allocated address space. 412.It Bq Er EINVAL 413The 414.Fa cmd 415argument specifies an unsupported command. 416.Pp 417The 418.Fa idtype 419argument specifies an unsupported identifier type. 420.It Bq Er EPERM 421The calling process does not have permission to perform the requested 422operation on any of the selected processes. 423.It Bq Er ESRCH 424No processes matched the requested 425.Fa idtype 426and 427.Fa id . 428.It Bq Er EINVAL 429An invalid operation or flag was passed in 430.Fa arg 431for a 432.Dv PROC_SPROTECT 433command. 434.It Bq Er EPERM 435The 436.Fa idtype 437argument is not equal to 438.Dv P_PID , 439or 440.Fa id 441is not equal to the pid of the calling process, for 442.Dv PROC_REAP_ACQUIRE 443or 444.Dv PROC_REAP_RELEASE 445requests. 446.It Bq Er EINVAL 447Invalid or undefined flags were passed to a 448.Dv PROC_REAP_KILL 449request. 450.It Bq Er EINVAL 451An invalid or zero signal number was requested for a 452.Dv PROC_REAP_KILL 453request. 454.It Bq Er EINVAL 455The 456.Dv PROC_REAP_RELEASE 457request was issued by the 458.Xr init 8 459process. 460.It Bq Er EBUSY 461The 462.Dv PROC_REAP_ACQUIRE 463request was issued by a process that had already acquired reaper status 464and has not yet released it. 465.It Bq Er EBUSY 466The 467.Dv PROC_TRACE_CTL 468request was issued for a process already being traced. 469.It Bq Er EPERM 470The 471.Dv PROC_TRACE_CTL 472request to re-enable tracing of the process 473.Po Dv PROC_TRACE_CTL_ENABLE Pc , 474or to disable persistence of 475.Dv PROC_TRACE_CTL_DISABLE 476on 477.Xr execve 2 478was issued for a non-current process. 479.It Bq Er EINVAL 480The value of the integer 481.Fa data 482parameter for the 483.Dv PROC_TRACE_CTL 484or 485.Dv PROC_TRAPCAP_CTL 486request is invalid. 487.El 488.Sh SEE ALSO 489.Xr dtrace 1 , 490.Xr cap_enter 2, 491.Xr kill 2 , 492.Xr ktrace 2 , 493.Xr ptrace 2 , 494.Xr wait 2 , 495.Xr capsicum 4 , 496.Xr hwpmc 4 , 497.Xr init 8 498.Sh HISTORY 499The 500.Fn procctl 501function appeared in 502.Fx 10.0 . 503The reaper facility is based on a similar feature of Linux and 504DragonflyBSD, and first appeared in 505.Fx 10.2 . 506