1 .\" Copyright (c) 2013 Hudson River Trading LLC
2 .\" Written by: John H. Baldwin <jhb@FreeBSD.org>
3 .\" All rights reserved.
5 .\" Copyright (c) 2014 The FreeBSD Foundation
6 .\" Portions of this documentation were written by Konstantin Belousov
7 .\" under sponsorship from the FreeBSD Foundation.
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
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.
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
43 .Fn procctl "idtype_t idtype" "id_t id" "int cmd" "void *data"
47 system call provides for control over processes.
52 arguments specify the set of processes to control.
53 If multiple processes match the identifier,
57 to control as many of the selected processes as possible.
58 An error is only returned if no selected processes successfully complete
60 The following identifier types are supported:
61 .Bl -tag -width P_PGID
63 Control the process with the process ID
66 zero is a shortcut for the calling process ID.
68 Control processes belonging to the process group with the ID
72 The control request to perform is specified by the
76 All status changing requests
78 require the caller to have the right to debug the target.
79 All status query requests
81 require the caller to have the right to observe the target.
83 The following commands are supported:
84 .Bl -tag -width PROC_TRAPCAP_STATUS
86 Controls the Address Space Layout Randomization (ASLR) in the program
90 in the specified process or its descendants that did not changed
91 the control nor modified it by other means.
94 parameter must point to the integer variable holding one of the following
96 .Bl -tag -width PROC_ASLR_FORCE_DISABLE
97 .It Dv PROC_ASLR_FORCE_ENABLE
98 Request that ASLR is enabled after execution, even if it is disabled
100 The image flag and set-uid might prevent ASLR enablement still.
101 .It Dv PROC_ASLR_FORCE_DISABLE
102 Request that ASLR is disabled after execution.
104 .Dv PROC_ASLR_FORCE_ENABLE
106 .It Dv PROC_ASLR_NOFORCE
107 Use the system-wide configured policy for ASLR.
109 .It Dv PROC_ASLR_STATUS
110 Returns the current status of ASLR enablement for the target process.
113 parameter must point to the integer variable, where one of the
114 following values is written:
115 .Bl -tag -width PROC_ASLR_FORCE_DISABLE
116 .It Dv PROC_ASLR_FORCE_ENABLE
117 .It Dv PROC_ASLR_FORCE_DISABLE
118 .It Dv PROC_ASLR_NOFORCE
121 If the currently executed image in the process itself has ASLR enabled,
124 flag is or-ed with the value listed above.
125 .It Dv PROC_PROTMAX_CTL
126 Controls implicit application of PROT_MAX protection equal to the
130 syscall, in the target process.
133 parameter must point to the integer variable holding one of the following
135 .Bl -tag -width PROC_PROTMAX_FORCE_DISABLE
136 .It Dv PROC_PROTMAX_FORCE_ENABLE
137 Enables implicit PROT_MAX application,
138 even if it is disabled system-wide by the sysctl
139 .Va vm.imply_prot_max .
140 The image flag might still prevent the enablement.
141 .It Dv PROC_PROTMAX_FORCE_DISABLE
142 Request that implicit application of PROT_MAX be disabled.
144 .Dv PROC_PROTMAX_FORCE_ENABLE
146 .It Dv PROC_PROTMAX_NOFORCE
147 Use the system-wide configured policy for PROT_MAX.
149 .It Dv PROC_PROTMAX_STATUS
150 Returns the current status of implicit PROT_MAX enablement for the
154 parameter must point to the integer variable, where one of the
155 following values is written:
156 .Bl -tag -width PROC_PROTMAX_FORCE_DISABLE
157 .It Dv PROC_PROTMAX_FORCE_ENABLE
158 .It Dv PROC_PROTMAX_FORCE_DISABLE
159 .It Dv PROC_PROTMAX_NOFORCE
162 If the currently executed image in the process itself has implicit PROT_MAX
163 application enabled, the
164 .Dv PROC_PROTMAX_ACTIVE
165 flag is or-ed with the value listed above.
167 Set process protection state.
168 This is used to mark a process as protected from being killed if the system
169 exhausts the available memory and swap.
172 parameter must point to an integer containing an operation and zero or more
174 The following operations are supported:
175 .Bl -tag -width PPROT_CLEAR
177 Mark the selected processes as protected.
179 Clear the protected state of selected processes.
182 The following optional flags are supported:
183 .Bl -tag -width PPROT_DESCEND
185 Apply the requested operation to all child processes of each selected process
186 in addition to each selected process.
190 mark all future child processes of each selected process as protected.
191 Future child processes will also mark all of their future child processes.
193 .It Dv PROC_REAP_ACQUIRE
194 Acquires the reaper status for the current process.
195 Reaper status means that children orphaned by the reaper's descendants
196 that were forked after the acquisition of reaper status are reparented to the
198 After system initialization,
200 is the default reaper.
201 .It Dv PROC_REAP_RELEASE
202 Release the reaper state for the current process.
203 The reaper of the current process becomes the new reaper of the
204 current process's descendants.
205 .It Dv PROC_REAP_STATUS
206 Provides information about the reaper of the specified process,
207 or the process itself when it is a reaper.
210 argument must point to a
211 .Vt procctl_reaper_status
212 structure which is filled in by the syscall on successful return.
214 struct procctl_reaper_status {
217 u_int rs_descendants;
224 may have the following flags returned:
225 .Bl -tag -width REAPER_STATUS_REALINIT
226 .It Dv REAPER_STATUS_OWNED
227 The specified process has acquired reaper status and has not
229 When the flag is returned, the specified process
231 pid, identifies the reaper, otherwise the
233 field of the structure is set to the pid of the reaper
234 for the specified process id.
235 .It Dv REAPER_STATUS_REALINIT
236 The specified process is the root of the reaper tree, i.e.,
242 field returns the number of children of the reaper among the descendants.
243 It is possible to have a child whose reaper is not the specified process,
244 since the reaper for any existing children is not reset on the
245 .Dv PROC_REAP_ACQUIRE
249 field returns the total number of descendants of the reaper(s),
250 not counting descendants of the reaper in the subtree.
253 field returns the reaper pid.
256 returns the pid of one reaper child if there are any descendants.
257 .It Dv PROC_REAP_GETPIDS
258 Queries the list of descendants of the reaper of the specified process.
259 The request takes a pointer to a
260 .Vt procctl_reaper_pids
265 struct procctl_reaper_pids {
267 struct procctl_reaper_pidinfo *rp_pids;
272 field must point to an array of
273 .Vt procctl_reaper_pidinfo
274 structures, to be filled in on return,
277 field must specify the size of the array,
278 into which no more than
280 elements will be filled in by the kernel.
283 .Vt "struct procctl_reaper_pidinfo"
284 structure provides some information about one of the reaper's descendants.
285 Note that for a descendant that is not a child, it may be incorrectly
286 identified because of a race in which the original child process exited
287 and the exited process's pid was reused for an unrelated process.
289 struct procctl_reaper_pidinfo {
297 field is the process id of the descendant.
300 field provides the pid of the child of the reaper, which is the (grand-)parent
304 field returns the following flags, further describing the descendant:
305 .Bl -tag -width REAPER_PIDINFO_REAPER
306 .It Dv REAPER_PIDINFO_VALID
307 Set to indicate that the
308 .Vt procctl_reaper_pidinfo
309 structure was filled in by the kernel.
312 array and testing the
313 .Dv REAPER_PIDINFO_VALID
314 flag allows the caller to detect the end
315 of the returned array.
316 .It Dv REAPER_PIDINFO_CHILD
319 field identifies the direct child of the reaper.
320 .It Dv REAPER_PIDINFO_REAPER
321 The reported process is itself a reaper.
322 The descendants of the subordinate reaper are not reported.
324 .It Dv PROC_REAP_KILL
325 Request to deliver a signal to some subset of the descendants of the reaper.
328 parameter must point to a
329 .Vt procctl_reaper_kill
330 structure, which is used both for parameters and status return.
332 struct procctl_reaper_kill {
342 field specifies the signal to be delivered.
343 Zero is not a valid signal number, unlike for
347 field further directs the operation.
348 It is or-ed from the following flags:
349 .Bl -tag -width REAPER_KILL_CHILDREN
350 .It Dv REAPER_KILL_CHILDREN
351 Deliver the specified signal only to direct children of the reaper.
352 .It Dv REAPER_KILL_SUBTREE
353 Deliver the specified signal only to descendants that were forked by
354 the direct child with pid specified in the
359 .Dv REAPER_KILL_CHILDREN
361 .Dv REAPER_KILL_SUBTREE
362 flags are specified, all current descendants of the reaper are signalled.
364 If a signal was delivered to any process, the return value from the request
368 field identifies the number of processes signalled.
371 field is set to the pid of the first process for which signal
372 delivery failed, e.g., due to permission problems.
373 If no such process exists, the
376 .It Dv PROC_TRACE_CTL
377 Enable or disable tracing of the specified process(es), according to the
378 value of the integer argument.
379 Tracing includes attachment to the process using the
387 Possible values for the
390 .Bl -tag -width PROC_TRACE_CTL_DISABLE_EXEC
391 .It Dv PROC_TRACE_CTL_ENABLE
392 Enable tracing, after it was disabled by
393 .Dv PROC_TRACE_CTL_DISABLE .
394 Only allowed for self.
395 .It Dv PROC_TRACE_CTL_DISABLE
396 Disable tracing for the specified process.
397 Tracing is re-enabled when the process changes the executing
401 A child inherits the trace settings from the parent on
403 .It Dv PROC_TRACE_CTL_DISABLE_EXEC
405 .Dv PROC_TRACE_CTL_DISABLE ,
406 but the setting persists for the process even after
409 .It Dv PROC_TRACE_STATUS
410 Returns the current tracing status for the specified process in
411 the integer variable pointed to by
413 If tracing is disabled,
416 If tracing is enabled, but no debugger is attached by the
421 If a debugger is attached,
423 is set to the pid of the debugger process.
424 .It Dv PROC_TRAPCAP_CTL
425 Controls the capability mode sandbox actions for the specified
427 on a return from any syscall which gives either a
432 If the control is enabled, such errors from the syscalls cause
433 delivery of the synchronous
435 signal to the thread immediately before returning from the syscalls.
437 Possible values for the
440 .Bl -tag -width PROC_TRAPCAP_CTL_DISABLE
441 .It Dv PROC_TRAPCAP_CTL_ENABLE
444 signal delivery on capability mode access violations.
445 The enabled mode is inherited by the children of the process,
449 .It Dv PROC_TRAPCAP_CTL_DISABLE
450 Disable the signal delivery on capability mode access violations.
451 Note that the global sysctl
452 .Dv kern.trap_enotcap
453 might still cause the signal to be delivered.
458 On signal delivery, the
462 signal handler parameter is set to the syscall error value,
467 The system call number is stored in the
471 signal handler parameter.
472 The other system call parameters can be read from the
474 but the system call number is typically stored in the register
475 that also contains the return value and so is unavailable in the
480 for more information about the capability mode.
481 .It Dv PROC_TRAPCAP_STATUS
482 Return the current status of signalling capability mode access
483 violations for the specified process.
484 The integer value pointed to by the
486 argument is set to the
487 .Dv PROC_TRAPCAP_CTL_ENABLE
488 value if the process control enables signal delivery, and to
489 .Dv PROC_TRAPCAP_CTL_DISABLE
492 See the note about sysctl
493 .Dv kern.trap_enotcap
494 above, which gives independent global control of signal delivery.
495 .It Dv PROC_PDEATHSIG_CTL
496 Request the delivery of a signal when the parent of the calling
503 must be the either caller's pid or zero, with no difference in effect.
504 The value is cleared for child processes
505 and when executing set-user-ID or set-group-ID binaries.
507 must point to a value of type
509 indicating the signal
510 that should be delivered to the caller.
511 Use zero to cancel a previously requested signal delivery.
512 .It Dv PROC_PDEATHSIG_STATUS
513 Query the current signal number that will be delivered when the parent
514 of the calling process exits.
520 must be the either caller's pid or zero, with no difference in effect.
522 must point to a memory location that can hold a value of type
524 If signal delivery has not been requested, it will contain zero
526 .It Dv PROC_STACKGAP_CTL
527 Controls the stack gaps in the specified process.
528 A stack gap is the part of the growth area for a
530 mapped region that is reserved and never filled by memory.
531 Instead, the process is guaranteed to receive a
533 signal on accessing pages in the gap.
534 Gaps protect against stack overflow corrupting memory adjacent
539 argument must point to an integer variable containing flags.
540 The following flags are allowed:
541 .Bl -tag -width PROC_STACKGAP_DISABLE_EXEC
542 .It Dv PROC_STACKGAP_ENABLE
543 This flag is only accepted for consistency with
544 .Dv PROC_STACKGAP_STATUS .
545 If stack gaps are enabled, the flag is ignored.
546 If disabled, the flag causes an
548 error to be returned.
549 After gaps are disabled in a process, they can only be re-enabled when an
552 .It Dv PROC_STACKGAP_DISABLE
553 Disable stack gaps for the process.
554 For existing stacks, the gap is no longer a reserved part of the growth
555 area and can be filled by memory on access.
556 .It Dv PROC_STACKGAP_ENABLE_EXEC
557 Enable stack gaps for programs started after an
559 by the specified process.
560 .It Dv PROC_STACKGAP_DISABLE_EXEC
561 Inherit disabled stack gaps state after
563 In other words, if the currently executing program has stack gaps disabled,
564 they are kept disabled on exec.
565 If gaps were enabled, they are kept enabled after exec.
568 The stack gap state is inherited from the parent on
570 .It Dv PROC_STACKGAP_STATUS
571 Returns the current stack gap state for the specified process.
573 must point to an integer variable, which is used to return a bitmask
574 consisting of the following flags:
575 .Bl -tag -width PROC_STACKGAP_DISABLE_EXEC
576 .It Dv PROC_STACKGAP_ENABLE
577 Stack gaps are enabled.
578 .It Dv PROC_STACKGAP_DISABLE
579 Stack gaps are disabled.
580 .It Dv PROC_STACKGAP_ENABLE_EXEC
581 Stack gaps are enabled in the process after
583 .It Dv PROC_STACKGAP_DISABLE_EXEC
584 Stack gaps are disabled in the process after
587 .It Dv PROC_NO_NEW_PRIVS_CTL
588 Allows one to ignore the SUID and SGID bits on the program
591 in the specified process and its future descendants.
594 parameter must point to the integer variable holding the following
596 .Bl -tag -width PROC_NO_NEW_PRIVS_ENABLE
597 .It Dv PROC_NO_NEW_PRIVS_ENABLE
598 Request SUID and SGID bits to be ignored.
601 It is not possible to disable it once it has been enabled.
602 .It Dv PROC_NO_NEW_PRIVS_STATUS
603 Returns the current status of SUID/SGID enablement for the target process.
606 parameter must point to the integer variable, where one of the
607 following values is written:
608 .Bl -tag -width PROC_NO_NEW_PRIVS_DISABLE
609 .It Dv PROC_NO_NEW_PRIVS_ENABLE
610 .It Dv PROC_NO_NEW_PRIVS_DISABLE
612 .It Dv PROC_WXMAP_CTL
613 Controls the 'write exclusive against execution' permissions for the
614 mappings in the process address space.
615 It overrides the global settings established by the
616 .Dv kern.elf{32/64}.allow_wx
618 and the corresponding bit in the ELF control note, see
623 parameter must point to the integer variable holding one of the
625 .Bl -tag -width PROC_WX_MAPPINGS_DISALLOW_EXEC
626 .It Dv PROC_WX_MAPPINGS_PERMIT
627 Enable creation of mappings that have both write and execute
628 protection attributes, in the specified process' address space.
629 .It Dv PROC_WX_MAPPINGS_DISALLOW_EXEC
630 In the new address space created by
632 disallow creation of mappings that have both write and execute
636 Once creation of writeable and executable mappings is allowed,
637 it is impossible (and pointless) to disallow it.
638 The only way to ensure the absence of such mappings after they
639 were enabled in a given process, is to set the
640 .Dv PROC_WX_MAPPINGS_DISALLOW_EXEC
644 .It Dv PROC_WXMAP_STATUS
645 Returns the current status of the 'write exclusive against execution'
646 enforcement for the specified process.
649 parameter must point to the integer variable, where one of the
650 following values is written:
651 .Bl -tag -width PROC_WX_MAPPINGS_DISALLOW_EXEC
652 .It Dv PROC_WX_MAPPINGS_PERMIT
653 Creation of simultaneously writable and executable mapping is permitted,
654 otherwise the process cannot create such mappings.
655 .It Dv PROC_WX_MAPPINGS_DISALLOW_EXEC
658 the new address space should disallow creation of simultaneously
659 writable and executable mappings.
662 Additionally, if the address space of the process disallows
663 creation of simultaneously writable and executable mappings and
664 it is guaranteed that no such mapping was created since address space
666 .Dv PROC_WXORX_ENFORCE
667 flag is set in the returned value.
669 .Sh x86 MACHINE-SPECIFIC REQUESTS
670 .Bl -tag -width PROC_KPTI_STATUS
673 Controls the Kernel Page Table Isolation (KPTI) option for the children
674 of the specified process.
675 For the command to work, the
677 tunable must be enabled on boot.
678 It is not possible to change the KPTI setting for a running process,
681 where the address space is reinitialized.
685 parameter must point to an integer variable containing one of the
687 .Bl -tag -width PROC_KPTI_CTL_DISABLE_ON_EXEC
688 .It Dv PROC_KPTI_CTL_ENABLE_ON_EXEC
691 .It Dv PROC_KPTI_CTL_DISABLE_ON_EXEC
694 Only root or a process having the
696 privilege might use this option.
698 .It Dv PROC_KPTI_STATUS
699 Returns the current KPTI status for the specified process.
701 must point to the integer variable, which returns the
703 .Bl -tag -width PROC_KPTI_CTL_DISABLE_ON_EXEC
704 .It Dv PROC_KPTI_CTL_ENABLE_ON_EXEC
705 .It Dv PROC_KPTI_CTL_DISABLE_ON_EXEC
708 The status is or-ed with the
709 .Va PROC_KPTI_STATUS_ACTIVE
710 in case KPTI is active for the current address space of the process.
712 Disabling tracing on a process should not be considered a security
713 feature, as it is bypassable both by the kernel and privileged processes,
714 and via other system mechanisms.
715 As such, it should not be utilized to reliably protect cryptographic
716 keying material or other confidential data.
718 Note that processes can trivially bypass the 'no simultaneously
719 writable and executable mappings' policy by first marking some mapping
720 as writeable and write code to it, then removing write and adding
722 This may be legitimately required by some programs, such as JIT compilers.
724 If an error occurs, a value of -1 is returned and
726 is set to indicate the error.
736 parameter points outside the process's allocated address space.
740 argument specifies an unsupported command.
744 argument specifies an unsupported identifier type.
746 The calling process does not have permission to perform the requested
747 operation on any of the selected processes.
749 No processes matched the requested
754 An invalid operation or flag was passed in
762 argument is not equal to
766 is not equal to the pid of the calling process, for
767 .Dv PROC_REAP_ACQUIRE
769 .Dv PROC_REAP_RELEASE
772 Invalid or undefined flags were passed to a
776 An invalid or zero signal number was requested for a
781 .Dv PROC_REAP_RELEASE
782 request was issued by the
787 .Dv PROC_REAP_ACQUIRE
788 request was issued by a process that had already acquired reaper status
789 and has not yet released it.
793 request was issued for a process already being traced.
797 request to re-enable tracing of the process
798 .Po Dv PROC_TRACE_CTL_ENABLE Pc ,
799 or to disable persistence of
800 .Dv PROC_TRACE_CTL_DISABLE
803 was issued for a non-current process.
805 The value of the integer
814 .Dv PROC_PDEATHSIG_CTL
816 .Dv PROC_PDEATHSIG_STATUS
817 request referenced an unsupported
820 or invalid signal number.
842 The reaper facility is based on a similar feature of Linux and
843 DragonflyBSD, and first appeared in
847 .Dv PROC_PDEATHSIG_CTL
848 facility is based on the prctl(PR_SET_PDEATHSIG, ...) feature of Linux,
849 and first appeared in
852 The ASLR support was added to system for the checklists compliance in