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 May 12, 2018 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_REAPER" 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.It Dv REAPER_PIDINFO_REAPER 230The reported process is itself a reaper. 231The descendants of the subordinate reaper are not reported. 232.El 233.It Dv PROC_REAP_KILL 234Request to deliver a signal to some subset of the descendants of the reaper. 235The 236.Fa data 237parameter must point to a 238.Vt procctl_reaper_kill 239structure, which is used both for parameters and status return. 240.Bd -literal 241struct procctl_reaper_kill { 242 int rk_sig; 243 u_int rk_flags; 244 pid_t rk_subtree; 245 u_int rk_killed; 246 pid_t rk_fpid; 247}; 248.Ed 249The 250.Fa rk_sig 251field specifies the signal to be delivered. 252Zero is not a valid signal number, unlike for 253.Xr kill 2 . 254The 255.Fa rk_flags 256field further directs the operation. 257It is or-ed from the following flags: 258.Bl -tag -width "Dv REAPER_KILL_CHILDREN" 259.It Dv REAPER_KILL_CHILDREN 260Deliver the specified signal only to direct children of the reaper. 261.It Dv REAPER_KILL_SUBTREE 262Deliver the specified signal only to descendants that were forked by 263the direct child with pid specified in the 264.Fa rk_subtree 265field. 266.El 267If neither the 268.Dv REAPER_KILL_CHILDREN 269nor the 270.Dv REAPER_KILL_SUBTREE 271flags are specified, all current descendants of the reaper are signalled. 272.Pp 273If a signal was delivered to any process, the return value from the request 274is zero. 275In this case, the 276.Fa rk_killed 277field identifies the number of processes signalled. 278The 279.Fa rk_fpid 280field is set to the pid of the first process for which signal 281delivery failed, e.g., due to permission problems. 282If no such process exists, the 283.Fa rk_fpid 284field is set to -1. 285.It Dv PROC_TRACE_CTL 286Enable or disable tracing of the specified process(es), according to the 287value of the integer argument. 288Tracing includes attachment to the process using the 289.Xr ptrace 2 290and 291.Xr ktrace 2 , 292debugging sysctls, 293.Xr hwpmc 4 , 294.Xr dtrace 1 , 295and core dumping. 296Possible values for the 297.Fa data 298argument are: 299.Bl -tag -width "Dv PROC_TRACE_CTL_DISABLE_EXEC" 300.It Dv PROC_TRACE_CTL_ENABLE 301Enable tracing, after it was disabled by 302.Dv PROC_TRACE_CTL_DISABLE . 303Only allowed for self. 304.It Dv PROC_TRACE_CTL_DISABLE 305Disable tracing for the specified process. 306Tracing is re-enabled when the process changes the executing 307program with the 308.Xr execve 2 309syscall. 310A child inherits the trace settings from the parent on 311.Xr fork 2 . 312.It Dv PROC_TRACE_CTL_DISABLE_EXEC 313Same as 314.Dv PROC_TRACE_CTL_DISABLE , 315but the setting persists for the process even after 316.Xr execve 2 . 317.El 318.It Dv PROC_TRACE_STATUS 319Returns the current tracing status for the specified process in 320the integer variable pointed to by 321.Fa data . 322If tracing is disabled, 323.Fa data 324is set to -1. 325If tracing is enabled, but no debugger is attached by the 326.Xr ptrace 2 327syscall, 328.Fa data 329is set to 0. 330If a debugger is attached, 331.Fa data 332is set to the pid of the debugger process. 333.It Dv PROC_TRAPCAP_CTL 334Controls the capability mode sandbox actions for the specified 335sandboxed processes, 336on a return from any syscall which gives either a 337.Er ENOTCAPABLE 338or 339.Er ECAPMODE 340error. 341If the control is enabled, such errors from the syscalls cause 342delivery of the synchronous 343.Dv SIGTRAP 344signal to the thread immediately before returning from the syscalls. 345.Pp 346Possible values for the 347.Fa data 348argument are: 349.Bl -tag -width "Dv PROC_TRAPCAP_CTL_DISABLE" 350.It Dv PROC_TRAPCAP_CTL_ENABLE 351Enable the 352.Dv SIGTRAP 353signal delivery on capability mode access violations. 354The enabled mode is inherited by the children of the process, 355and is kept after 356.Xr fexecve 2 357calls. 358.It Dv PROC_TRAPCAP_CTL_DISABLE 359Disable the signal delivery on capability mode access violations. 360Note that the global sysctl 361.Dv kern.trap_enotcap 362might still cause the signal to be delivered. 363See 364.Xr capsicum 4 . 365.El 366.Pp 367On signal delivery, the 368.Va si_errno 369member of the 370.Fa siginfo 371signal handler parameter is set to the syscall error value, 372and the 373.Va si_code 374member is set to 375.Dv TRAP_CAP . 376.Pp 377See 378.Xr capsicum 4 379for more information about the capability mode. 380.It Dv PROC_TRAPCAP_STATUS 381Return the current status of signalling capability mode access 382violations for the specified process. 383The integer value pointed to by the 384.Fa data 385argument is set to the 386.Dv PROC_TRAPCAP_CTL_ENABLE 387value if the process control enables signal delivery, and to 388.Dv PROC_TRAPCAP_CTL_DISABLE 389otherwise. 390.Pp 391See the note about sysctl 392.Dv kern.trap_enotcap 393above, which gives independent global control of signal delivery. 394.It Dv PROC_PDEATHSIG_CTL 395Request the delivery of a signal when the parent of the calling 396process exits. 397.Fa idtype 398must be 399.Dv P_PID 400and 401.Fa id 402must be the either caller's pid or zero, with no difference in effect. 403The value is cleared for child processes 404and when executing set-user-ID or set-group-ID binaries. 405.Fa arg 406must point to a value of type 407.Vt int 408indicating the signal 409that should be delivered to the caller. 410Use zero to cancel a previously requested signal delivery. 411.It Dv PROC_PDEATHSIG_STATUS 412Query the current signal number that will be delivered when the parent 413of the calling process exits. 414.Fa idtype 415must be 416.Dv P_PID 417and 418.Fa id 419must be the either caller's pid or zero, with no difference in effect. 420.Fa arg 421must point to a memory location that can hold a value of type 422.Vt int . 423If signal delivery has not been requested, it will contain zero 424on return. 425.El 426.Sh NOTES 427Disabling tracing on a process should not be considered a security 428feature, as it is bypassable both by the kernel and privileged processes, 429and via other system mechanisms. 430As such, it should not be utilized to reliably protect cryptographic 431keying material or other confidential data. 432.Sh RETURN VALUES 433If an error occurs, a value of -1 is returned and 434.Va errno 435is set to indicate the error. 436.Sh ERRORS 437The 438.Fn procctl 439system call 440will fail if: 441.Bl -tag -width Er 442.It Bq Er EFAULT 443The 444.Fa arg 445parameter points outside the process's allocated address space. 446.It Bq Er EINVAL 447The 448.Fa cmd 449argument specifies an unsupported command. 450.Pp 451The 452.Fa idtype 453argument specifies an unsupported identifier type. 454.It Bq Er EPERM 455The calling process does not have permission to perform the requested 456operation on any of the selected processes. 457.It Bq Er ESRCH 458No processes matched the requested 459.Fa idtype 460and 461.Fa id . 462.It Bq Er EINVAL 463An invalid operation or flag was passed in 464.Fa arg 465for a 466.Dv PROC_SPROTECT 467command. 468.It Bq Er EPERM 469The 470.Fa idtype 471argument is not equal to 472.Dv P_PID , 473or 474.Fa id 475is not equal to the pid of the calling process, for 476.Dv PROC_REAP_ACQUIRE 477or 478.Dv PROC_REAP_RELEASE 479requests. 480.It Bq Er EINVAL 481Invalid or undefined flags were passed to a 482.Dv PROC_REAP_KILL 483request. 484.It Bq Er EINVAL 485An invalid or zero signal number was requested for a 486.Dv PROC_REAP_KILL 487request. 488.It Bq Er EINVAL 489The 490.Dv PROC_REAP_RELEASE 491request was issued by the 492.Xr init 8 493process. 494.It Bq Er EBUSY 495The 496.Dv PROC_REAP_ACQUIRE 497request was issued by a process that had already acquired reaper status 498and has not yet released it. 499.It Bq Er EBUSY 500The 501.Dv PROC_TRACE_CTL 502request was issued for a process already being traced. 503.It Bq Er EPERM 504The 505.Dv PROC_TRACE_CTL 506request to re-enable tracing of the process 507.Po Dv PROC_TRACE_CTL_ENABLE Pc , 508or to disable persistence of 509.Dv PROC_TRACE_CTL_DISABLE 510on 511.Xr execve 2 512was issued for a non-current process. 513.It Bq Er EINVAL 514The value of the integer 515.Fa data 516parameter for the 517.Dv PROC_TRACE_CTL 518or 519.Dv PROC_TRAPCAP_CTL 520request is invalid. 521.It Bq Er EINVAL 522The 523.Dv PROC_PDEATHSIG_CTL 524or 525.Dv PROC_PDEATHSIG_STATUS 526request referenced an unsupported 527.Fa id , 528.Fa idtype 529or invalid signal number. 530.El 531.Sh SEE ALSO 532.Xr dtrace 1 , 533.Xr cap_enter 2, 534.Xr kill 2 , 535.Xr ktrace 2 , 536.Xr ptrace 2 , 537.Xr wait 2 , 538.Xr capsicum 4 , 539.Xr hwpmc 4 , 540.Xr init 8 541.Sh HISTORY 542The 543.Fn procctl 544function appeared in 545.Fx 10.0 . 546The reaper facility is based on a similar feature of Linux and 547DragonflyBSD, and first appeared in 548.Fx 10.2 . 549The 550.Dv PROC_PDEATHSIG_CTL 551facility is based on the prctl(PR_SET_PDEATHSIG, ...) feature of Linux, 552and first appeared in 553.Fx 11.2 . 554