lib/libc/sys/procctl.2

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