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 February 23, 2019 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 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 PROC_TRAPCAP_STATUS 75.It Dv PROC_ASLR_CTL 76Controls the Address Space Layout Randomization (ASLR) in the program 77images created 78by 79.Xr execve 2 80in the specified process or its descendants that did not changed 81the control nor modified it by other means. 82The 83.Va arg 84parameter must point to the integer variable holding one of the following 85values: 86.Bl -tag -width PROC_ASLR_FORCE_DISABLE 87.It Dv PROC_ASLR_FORCE_ENABLE 88Request that ASLR is enabled after execution, even if it is disabled 89system-wide. 90The image flag and set-uid might prevent ASLR enablement still. 91.It Dv PROC_ASLR_FORCE_DISABLE 92Request that ASLR is disabled after execution. 93Same notes as for 94.Dv PROC_ASLR_FORCE_ENABLE 95apply. 96.It Dv PROC_ASLR_NOFORCE 97Use system-wide configured policy for ASLR. 98.El 99.It Dv PROC_ASLR_STATUS 100Returns the current status of ASLR enablement for the target process. 101The 102.Va arg 103parameter must point to the integer variable, where one of the 104following values is written: 105.Bl -tag -width PROC_ASLR_FORCE_DISABLE 106.It Dv PROC_ASLR_FORCE_ENABLE 107.It Dv PROC_ASLR_FORCE_DISABLE 108.It Dv PROC_ASLR_NOFORCE 109.El 110.Pp 111If the currently executed image in the process itself has ASLR enabled, 112the 113.Dv PROC_ASLR_ACTIVE 114flag is or-ed with the value listed above. 115.It Dv PROC_SPROTECT 116Set process protection state. 117This is used to mark a process as protected from being killed if the system 118exhausts the available memory and swap. 119The 120.Fa arg 121parameter must point to an integer containing an operation and zero or more 122optional flags. 123The following operations are supported: 124.Bl -tag -width PPROT_CLEAR 125.It Dv PPROT_SET 126Mark the selected processes as protected. 127.It Dv PPROT_CLEAR 128Clear the protected state of selected processes. 129.El 130.Pp 131The following optional flags are supported: 132.Bl -tag -width PPROT_DESCEND 133.It Dv PPROT_DESCEND 134Apply the requested operation to all child processes of each selected process 135in addition to each selected process. 136.It Dv PPROT_INHERIT 137When used with 138.Dv PPROT_SET , 139mark all future child processes of each selected process as protected. 140Future child processes will also mark all of their future child processes. 141.El 142.It Dv PROC_REAP_ACQUIRE 143Acquires the reaper status for the current process. 144Reaper status means that children orphaned by the reaper's descendants 145that were forked after the acquisition of reaper status are reparented to the 146reaper process. 147After system initialization, 148.Xr init 8 149is the default reaper. 150.It Dv PROC_REAP_RELEASE 151Release the reaper state for the current process. 152The reaper of the current process becomes the new reaper of the 153current process's descendants. 154.It Dv PROC_REAP_STATUS 155Provides information about the reaper of the specified process, 156or the process itself when it is a reaper. 157The 158.Fa data 159argument must point to a 160.Vt procctl_reaper_status 161structure which is filled in by the syscall on successful return. 162.Bd -literal 163struct procctl_reaper_status { 164 u_int rs_flags; 165 u_int rs_children; 166 u_int rs_descendants; 167 pid_t rs_reaper; 168 pid_t rs_pid; 169}; 170.Ed 171The 172.Fa rs_flags 173may have the following flags returned: 174.Bl -tag -width REAPER_STATUS_REALINIT 175.It Dv REAPER_STATUS_OWNED 176The specified process has acquired reaper status and has not 177released it. 178When the flag is returned, the specified process 179.Fa id , 180pid, identifies the reaper, otherwise the 181.Fa rs_reaper 182field of the structure is set to the pid of the reaper 183for the specified process id. 184.It Dv REAPER_STATUS_REALINIT 185The specified process is the root of the reaper tree, i.e., 186.Xr init 8 . 187.El 188.Pp 189The 190.Fa rs_children 191field returns the number of children of the reaper among the descendants. 192It is possible to have a child whose reaper is not the specified process, 193since the reaper for any existing children is not reset on the 194.Dv PROC_REAP_ACQUIRE 195operation. 196The 197.Fa rs_descendants 198field returns the total number of descendants of the reaper(s), 199not counting descendants of the reaper in the subtree. 200The 201.Fa rs_reaper 202field returns the reaper pid. 203The 204.Fa rs_pid 205returns the pid of one reaper child if there are any descendants. 206.It Dv PROC_REAP_GETPIDS 207Queries the list of descendants of the reaper of the specified process. 208The request takes a pointer to a 209.Vt procctl_reaper_pids 210structure in the 211.Fa data 212parameter. 213.Bd -literal 214struct procctl_reaper_pids { 215 u_int rp_count; 216 struct procctl_reaper_pidinfo *rp_pids; 217}; 218.Ed 219When called, the 220.Fa rp_pids 221field must point to an array of 222.Vt procctl_reaper_pidinfo 223structures, to be filled in on return, 224and the 225.Fa rp_count 226field must specify the size of the array, 227into which no more than 228.Fa rp_count 229elements will be filled in by the kernel. 230.Pp 231The 232.Vt "struct procctl_reaper_pidinfo" 233structure provides some information about one of the reaper's descendants. 234Note that for a descendant that is not a child, it may be incorrectly 235identified because of a race in which the original child process exited 236and the exited process's pid was reused for an unrelated process. 237.Bd -literal 238struct procctl_reaper_pidinfo { 239 pid_t pi_pid; 240 pid_t pi_subtree; 241 u_int pi_flags; 242}; 243.Ed 244The 245.Fa pi_pid 246field is the process id of the descendant. 247The 248.Fa pi_subtree 249field provides the pid of the child of the reaper, which is the (grand-)parent 250of the process. 251The 252.Fa pi_flags 253field returns the following flags, further describing the descendant: 254.Bl -tag -width REAPER_PIDINFO_REAPER 255.It Dv REAPER_PIDINFO_VALID 256Set to indicate that the 257.Vt procctl_reaper_pidinfo 258structure was filled in by the kernel. 259Zero-filling the 260.Fa rp_pids 261array and testing the 262.Dv REAPER_PIDINFO_VALID 263flag allows the caller to detect the end 264of the returned array. 265.It Dv REAPER_PIDINFO_CHILD 266The 267.Fa pi_pid 268field identifies the direct child of the reaper. 269.It Dv REAPER_PIDINFO_REAPER 270The reported process is itself a reaper. 271The descendants of the subordinate reaper are not reported. 272.El 273.It Dv PROC_REAP_KILL 274Request to deliver a signal to some subset of the descendants of the reaper. 275The 276.Fa data 277parameter must point to a 278.Vt procctl_reaper_kill 279structure, which is used both for parameters and status return. 280.Bd -literal 281struct procctl_reaper_kill { 282 int rk_sig; 283 u_int rk_flags; 284 pid_t rk_subtree; 285 u_int rk_killed; 286 pid_t rk_fpid; 287}; 288.Ed 289The 290.Fa rk_sig 291field specifies the signal to be delivered. 292Zero is not a valid signal number, unlike for 293.Xr kill 2 . 294The 295.Fa rk_flags 296field further directs the operation. 297It is or-ed from the following flags: 298.Bl -tag -width REAPER_KILL_CHILDREN 299.It Dv REAPER_KILL_CHILDREN 300Deliver the specified signal only to direct children of the reaper. 301.It Dv REAPER_KILL_SUBTREE 302Deliver the specified signal only to descendants that were forked by 303the direct child with pid specified in the 304.Fa rk_subtree 305field. 306.El 307If neither the 308.Dv REAPER_KILL_CHILDREN 309nor the 310.Dv REAPER_KILL_SUBTREE 311flags are specified, all current descendants of the reaper are signalled. 312.Pp 313If a signal was delivered to any process, the return value from the request 314is zero. 315In this case, the 316.Fa rk_killed 317field identifies the number of processes signalled. 318The 319.Fa rk_fpid 320field is set to the pid of the first process for which signal 321delivery failed, e.g., due to permission problems. 322If no such process exists, the 323.Fa rk_fpid 324field is set to -1. 325.It Dv PROC_TRACE_CTL 326Enable or disable tracing of the specified process(es), according to the 327value of the integer argument. 328Tracing includes attachment to the process using the 329.Xr ptrace 2 330and 331.Xr ktrace 2 , 332debugging sysctls, 333.Xr hwpmc 4 , 334.Xr dtrace 1 , 335and core dumping. 336Possible values for the 337.Fa data 338argument are: 339.Bl -tag -width PROC_TRACE_CTL_DISABLE_EXEC 340.It Dv PROC_TRACE_CTL_ENABLE 341Enable tracing, after it was disabled by 342.Dv PROC_TRACE_CTL_DISABLE . 343Only allowed for self. 344.It Dv PROC_TRACE_CTL_DISABLE 345Disable tracing for the specified process. 346Tracing is re-enabled when the process changes the executing 347program with the 348.Xr execve 2 349syscall. 350A child inherits the trace settings from the parent on 351.Xr fork 2 . 352.It Dv PROC_TRACE_CTL_DISABLE_EXEC 353Same as 354.Dv PROC_TRACE_CTL_DISABLE , 355but the setting persists for the process even after 356.Xr execve 2 . 357.El 358.It Dv PROC_TRACE_STATUS 359Returns the current tracing status for the specified process in 360the integer variable pointed to by 361.Fa data . 362If tracing is disabled, 363.Fa data 364is set to -1. 365If tracing is enabled, but no debugger is attached by the 366.Xr ptrace 2 367syscall, 368.Fa data 369is set to 0. 370If a debugger is attached, 371.Fa data 372is set to the pid of the debugger process. 373.It Dv PROC_TRAPCAP_CTL 374Controls the capability mode sandbox actions for the specified 375sandboxed processes, 376on a return from any syscall which gives either a 377.Er ENOTCAPABLE 378or 379.Er ECAPMODE 380error. 381If the control is enabled, such errors from the syscalls cause 382delivery of the synchronous 383.Dv SIGTRAP 384signal to the thread immediately before returning from the syscalls. 385.Pp 386Possible values for the 387.Fa data 388argument are: 389.Bl -tag -width PROC_TRAPCAP_CTL_DISABLE 390.It Dv PROC_TRAPCAP_CTL_ENABLE 391Enable the 392.Dv SIGTRAP 393signal delivery on capability mode access violations. 394The enabled mode is inherited by the children of the process, 395and is kept after 396.Xr fexecve 2 397calls. 398.It Dv PROC_TRAPCAP_CTL_DISABLE 399Disable the signal delivery on capability mode access violations. 400Note that the global sysctl 401.Dv kern.trap_enotcap 402might still cause the signal to be delivered. 403See 404.Xr capsicum 4 . 405.El 406.Pp 407On signal delivery, the 408.Va si_errno 409member of the 410.Fa siginfo 411signal handler parameter is set to the syscall error value, 412and the 413.Va si_code 414member is set to 415.Dv TRAP_CAP . 416.Pp 417See 418.Xr capsicum 4 419for more information about the capability mode. 420.It Dv PROC_TRAPCAP_STATUS 421Return the current status of signalling capability mode access 422violations for the specified process. 423The integer value pointed to by the 424.Fa data 425argument is set to the 426.Dv PROC_TRAPCAP_CTL_ENABLE 427value if the process control enables signal delivery, and to 428.Dv PROC_TRAPCAP_CTL_DISABLE 429otherwise. 430.Pp 431See the note about sysctl 432.Dv kern.trap_enotcap 433above, which gives independent global control of signal delivery. 434.It Dv PROC_PDEATHSIG_CTL 435Request the delivery of a signal when the parent of the calling 436process exits. 437.Fa idtype 438must be 439.Dv P_PID 440and 441.Fa id 442must be the either caller's pid or zero, with no difference in effect. 443The value is cleared for child processes 444and when executing set-user-ID or set-group-ID binaries. 445.Fa arg 446must point to a value of type 447.Vt int 448indicating the signal 449that should be delivered to the caller. 450Use zero to cancel a previously requested signal delivery. 451.It Dv PROC_PDEATHSIG_STATUS 452Query the current signal number that will be delivered when the parent 453of the calling process exits. 454.Fa idtype 455must be 456.Dv P_PID 457and 458.Fa id 459must be the either caller's pid or zero, with no difference in effect. 460.Fa arg 461must point to a memory location that can hold a value of type 462.Vt int . 463If signal delivery has not been requested, it will contain zero 464on return. 465.El 466.Sh NOTES 467Disabling tracing on a process should not be considered a security 468feature, as it is bypassable both by the kernel and privileged processes, 469and via other system mechanisms. 470As such, it should not be utilized to reliably protect cryptographic 471keying material or other confidential data. 472.Sh RETURN VALUES 473If an error occurs, a value of -1 is returned and 474.Va errno 475is set to indicate the error. 476.Sh ERRORS 477The 478.Fn procctl 479system call 480will fail if: 481.Bl -tag -width Er 482.It Bq Er EFAULT 483The 484.Fa arg 485parameter points outside the process's allocated address space. 486.It Bq Er EINVAL 487The 488.Fa cmd 489argument specifies an unsupported command. 490.Pp 491The 492.Fa idtype 493argument specifies an unsupported identifier type. 494.It Bq Er EPERM 495The calling process does not have permission to perform the requested 496operation on any of the selected processes. 497.It Bq Er ESRCH 498No processes matched the requested 499.Fa idtype 500and 501.Fa id . 502.It Bq Er EINVAL 503An invalid operation or flag was passed in 504.Fa arg 505for a 506.Dv PROC_SPROTECT 507command. 508.It Bq Er EPERM 509The 510.Fa idtype 511argument is not equal to 512.Dv P_PID , 513or 514.Fa id 515is not equal to the pid of the calling process, for 516.Dv PROC_REAP_ACQUIRE 517or 518.Dv PROC_REAP_RELEASE 519requests. 520.It Bq Er EINVAL 521Invalid or undefined flags were passed to a 522.Dv PROC_REAP_KILL 523request. 524.It Bq Er EINVAL 525An invalid or zero signal number was requested for a 526.Dv PROC_REAP_KILL 527request. 528.It Bq Er EINVAL 529The 530.Dv PROC_REAP_RELEASE 531request was issued by the 532.Xr init 8 533process. 534.It Bq Er EBUSY 535The 536.Dv PROC_REAP_ACQUIRE 537request was issued by a process that had already acquired reaper status 538and has not yet released it. 539.It Bq Er EBUSY 540The 541.Dv PROC_TRACE_CTL 542request was issued for a process already being traced. 543.It Bq Er EPERM 544The 545.Dv PROC_TRACE_CTL 546request to re-enable tracing of the process 547.Po Dv PROC_TRACE_CTL_ENABLE Pc , 548or to disable persistence of 549.Dv PROC_TRACE_CTL_DISABLE 550on 551.Xr execve 2 552was issued for a non-current process. 553.It Bq Er EINVAL 554The value of the integer 555.Fa data 556parameter for the 557.Dv PROC_TRACE_CTL 558or 559.Dv PROC_TRAPCAP_CTL 560request is invalid. 561.It Bq Er EINVAL 562The 563.Dv PROC_PDEATHSIG_CTL 564or 565.Dv PROC_PDEATHSIG_STATUS 566request referenced an unsupported 567.Fa id , 568.Fa idtype 569or invalid signal number. 570.El 571.Sh SEE ALSO 572.Xr dtrace 1 , 573.Xr cap_enter 2, 574.Xr kill 2 , 575.Xr ktrace 2 , 576.Xr ptrace 2 , 577.Xr wait 2 , 578.Xr capsicum 4 , 579.Xr hwpmc 4 , 580.Xr init 8 581.Sh HISTORY 582The 583.Fn procctl 584function appeared in 585.Fx 10.0 . 586.Pp 587The reaper facility is based on a similar feature of Linux and 588DragonflyBSD, and first appeared in 589.Fx 10.2 . 590.Pp 591The 592.Dv PROC_PDEATHSIG_CTL 593facility is based on the prctl(PR_SET_PDEATHSIG, ...) feature of Linux, 594and first appeared in 595.Fx 11.2 . 596.Pp 597The ASLR support was added to system for the checklists compliance in 598.Fx 13.0 . 599