prctl.2: Executing a file with capabilities also resets the parent death signal

[thirdparty/man-pages.git] / man2 / prctl.2

.\" Copyright (C) 1998 Andries Brouwer (aeb@cwi.nl)
.\" and Copyright (C) 2002, 2006, 2008, 2012, 2013 Michael Kerrisk <mtk.manpages@gmail.com>
.\" and Copyright Guillem Jover <guillem@hadrons.org>
.\" and Copyright (C) 2014 Dave Hansen / Intel
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.\" Modified Thu Nov 11 04:19:42 MET 1999, aeb: added PR_GET_PDEATHSIG
.\" Modified 27 Jun 02, Michael Kerrisk
.\" 	Added PR_SET_DUMPABLE, PR_GET_DUMPABLE,
.\"	PR_SET_KEEPCAPS, PR_GET_KEEPCAPS
.\" Modified 2006-08-30 Guillem Jover <guillem@hadrons.org>
.\"	Updated Linux versions where the options where introduced.
.\"	Added PR_SET_TIMING, PR_GET_TIMING, PR_SET_NAME, PR_GET_NAME,
.\"	PR_SET_UNALIGN, PR_GET_UNALIGN, PR_SET_FPEMU, PR_GET_FPEMU,
.\"	PR_SET_FPEXC, PR_GET_FPEXC
.\" 2008-04-29 Serge Hallyn, Document PR_CAPBSET_READ and PR_CAPBSET_DROP
.\" 2008-06-13 Erik Bosman, <ejbosman@cs.vu.nl>
.\"     Document PR_GET_TSC and PR_SET_TSC.
.\" 2008-06-15 mtk, Document PR_SET_SECCOMP, PR_GET_SECCOMP
.\" 2009-10-03 Andi Kleen, document PR_MCE_KILL
.\" 2012-04 Cyrill Gorcunov, Document PR_SET_MM
.\" 2012-04-25 Michael Kerrisk, Document PR_TASK_PERF_EVENTS_DISABLE and
.\"				PR_TASK_PERF_EVENTS_ENABLE
.\" 2012-09-20 Kees Cook, update PR_SET_SECCOMP for mode 2
.\" 2012-09-20 Kees Cook, document PR_SET_NO_NEW_PRIVS, PR_GET_NO_NEW_PRIVS
.\" 2012-10-25 Michael Kerrisk, Document PR_SET_TIMERSLACK and
.\"                             PR_GET_TIMERSLACK
.\" 2013-01-10 Kees Cook, document PR_SET_PTRACER
.\" 2012-02-04 Michael kerrisk, document PR_{SET,GET}_CHILD_SUBREAPER
.\" 2014-11-10 Dave Hansen, document PR_MPX_{EN,DIS}ABLE_MANAGEMENT
.\"
.\"
.TH PRCTL 2 2015-02-01 "Linux" "Linux Programmer's Manual"
.SH NAME
prctl \- operations on a process
.SH SYNOPSIS
.nf
.B #include <sys/prctl.h>
.sp
.BI "int prctl(int " option ", unsigned long " arg2 ", unsigned long " arg3 ,
.BI "          unsigned long " arg4 ", unsigned long " arg5 );
.fi
.SH DESCRIPTION
.BR prctl ()
is called with a first argument describing what to do
(with values defined in \fI<linux/prctl.h>\fP), and further
arguments with a significance depending on the first one.
The first argument can be:
.TP
.BR PR_CAPBSET_READ " (since Linux 2.6.25)"
Return (as the function result) 1 if the capability specified in
.I arg2
is in the calling thread's capability bounding set,
or 0 if it is not.
(The capability constants are defined in
.IR <linux/capability.h> .)
The capability bounding set dictates
whether the process can receive the capability through a
file's permitted capability set on a subsequent call to
.BR execve (2).

If the capability specified in
.I arg2
is not valid, then the call fails with the error
.BR EINVAL .
.TP
.BR PR_CAPBSET_DROP " (since Linux 2.6.25)"
If the calling thread has the
.B CAP_SETPCAP
capability, then drop the capability specified by
.I arg2
from the calling thread's capability bounding set.
Any children of the calling thread will inherit the newly
reduced bounding set.

The call fails with the error:
.B EPERM
if the calling thread does not have the
.BR CAP_SETPCAP ;
.BR EINVAL
if
.I arg2
does not represent a valid capability; or
.BR EINVAL
if file capabilities are not enabled in the kernel,
in which case bounding sets are not supported.
.TP
.BR PR_SET_CHILD_SUBREAPER " (since Linux 3.4)"
.\" commit ebec18a6d3aa1e7d84aab16225e87fd25170ec2b
If
.I arg2
is nonzero,
set the "child subreaper" attribute of the calling process;
if
.I arg2
is zero, unset the attribute.
When a process is marked as a child subreaper,
all of the children that it creates, and their descendants,
will be marked as having a subreaper.
In effect, a subreaper fulfills the role of
.BR init (1)
for its descendant processes.
Upon termination of a process
that is orphaned (i.e., its immediate parent has already terminated)
and marked as having a subreaper,
the nearest still living ancestor subreaper
will receive a
.BR SIGCHLD
signal and be able to
.BR wait (2)
on the process to discover its termination status.
.TP
.BR PR_GET_CHILD_SUBREAPER " (since Linux 3.4)"
Return the "child subreaper" setting of the caller,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_SET_DUMPABLE " (since Linux 2.3.20)"
Set the state of the flag determining whether core dumps are produced
for the calling process upon delivery of a signal whose default behavior is
to produce a core dump.

Normally, this flag is set for a process by default, but it is cleared
when a set-user-ID or set-group-ID program,
or a program that has file capabilities associated with it (see
.BR capabilities (7)),
is executed.
It is also set by various system calls that manipulate process UIDs and GIDs.

In kernels up to and including 2.6.12,
.I arg2
must be either 0 (process is not dumpable) or 1 (process is dumpable).
Between kernels 2.6.13 and 2.6.17, the value 2 was also permitted,
which caused any binary which normally would not be dumped
to be dumped readable by root only;
for security reasons, this feature has been removed.
.\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=115270289030630&w=2
.\" Subject:    Fix prctl privilege escalation (CVE-2006-2451)
.\" From:       Marcel Holtmann <marcel () holtmann ! org>
.\" Date:       2006-07-12 11:12:00
(See also the description of
.I /proc/sys/fs/suid_dumpable
in
.BR proc (5).)

Processes that are not dumpable can not be attached via
.BR ptrace (2)
.BR PTRACE_ATTACH .
.TP
.BR PR_GET_DUMPABLE " (since Linux 2.3.20)"
Return (as the function result) the current state of the calling
process's dumpable flag.
.\" Since Linux 2.6.13, the dumpable flag can have the value 2,
.\" but in 2.6.13 PR_GET_DUMPABLE simply returns 1 if the dumpable
.\" flags has a nonzero value.  This was fixed in 2.6.14.
.TP
.BR PR_SET_ENDIAN " (since Linux 2.6.18, PowerPC only)"
Set the endian-ness of the calling process to the value given
in \fIarg2\fP, which should be one of the following:
.\" Respectively 0, 1, 2
.BR PR_ENDIAN_BIG ,
.BR PR_ENDIAN_LITTLE ,
or
.B PR_ENDIAN_PPC_LITTLE
(PowerPC pseudo little endian).
.TP
.BR PR_GET_ENDIAN " (since Linux 2.6.18, PowerPC only)"
Return the endian-ness of the calling process,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_SET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)"
Set floating-point emulation control bits to \fIarg2\fP.
Pass \fBPR_FPEMU_NOPRINT\fP to silently emulate fp operations accesses, or
\fBPR_FPEMU_SIGFPE\fP to not emulate fp operations and send
.B SIGFPE
instead.
.TP
.BR PR_GET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)"
Return floating-point emulation control bits,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_SET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)"
Set floating-point exception mode to \fIarg2\fP.
Pass \fBPR_FP_EXC_SW_ENABLE\fP to use FPEXC for FP exception enables,
\fBPR_FP_EXC_DIV\fP for floating-point divide by zero,
\fBPR_FP_EXC_OVF\fP for floating-point overflow,
\fBPR_FP_EXC_UND\fP for floating-point underflow,
\fBPR_FP_EXC_RES\fP for floating-point inexact result,
\fBPR_FP_EXC_INV\fP for floating-point invalid operation,
\fBPR_FP_EXC_DISABLED\fP for FP exceptions disabled,
\fBPR_FP_EXC_NONRECOV\fP for async nonrecoverable exception mode,
\fBPR_FP_EXC_ASYNC\fP for async recoverable exception mode,
\fBPR_FP_EXC_PRECISE\fP for precise exception mode.
.TP
.BR PR_GET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)"
Return floating-point exception mode,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_SET_KEEPCAPS " (since Linux 2.2.18)"
Set the state of the thread's "keep capabilities" flag,
which determines whether the threads's permitted
capability set is cleared when a change is made to the threads's user IDs
such that the threads's real UID, effective UID, and saved set-user-ID
all become nonzero when at least one of them previously had the value 0.
By default, the permitted capability set is cleared when such a change is made;
setting the "keep capabilities" flag prevents it from being cleared.
.I arg2
must be either 0 (permitted capabilities are cleared)
or 1 (permitted capabilities are kept).
(A thread's
.I effective
capability set is always cleared when such a credential change is made,
regardless of the setting of the "keep capabilities" flag.)
The "keep capabilities" value will be reset to 0 on subsequent calls to
.BR execve (2).
.TP
.BR PR_GET_KEEPCAPS " (since Linux 2.2.18)"
Return (as the function result) the current state of the calling threads's
"keep capabilities" flag.
.TP
.BR PR_SET_NAME " (since Linux 2.6.9)"
Set the name of the calling thread,
using the value in the location pointed to by
.IR "(char\ *) arg2" .
The name can be up to 16 bytes long,
.\" TASK_COMM_LEN in include/linux/sched.h
including the terminating null byte.
(If the length of the string, including the terminating null byte,
exceeds 16 bytes, the string is silently truncated.)
This is the same attribute that can be set via
.BR pthread_setname_np (3)
and retrieved using
.BR pthread_getname_np (3).
The attribute is likewise accessible via
.IR /proc/self/task/[tid]/comm ,
where
.I tid
is the name of the calling thread.
.TP
.BR PR_GET_NAME " (since Linux 2.6.11)"
Return the name of the calling thread,
in the buffer pointed to by
.IR "(char\ *) arg2" .
The buffer should allow space for up to 16 bytes;
the returned string will be null-terminated.
.TP
.BR PR_SET_NO_NEW_PRIVS " (since Linux 3.5)"
Set the calling process's
.I no_new_privs
bit to the value in
.IR arg2 .
With
.I no_new_privs
set to 1,
.BR execve (2)
promises not to grant privileges to do anything
that could not have been done without the
.BR execve (2)
call (for example,
rendering the set-user-ID and set-group-ID permission bits,
and file capabilities non-functional).
Once set, this bit cannot be unset.
The setting of this bit is inherited by children created by
.BR fork (2)
and
.BR clone (2),
and preserved across
.BR execve (2).

For more information, see the kernel source file
.IR Documentation/prctl/no_new_privs.txt .
.TP
.BR PR_GET_NO_NEW_PRIVS " (since Linux 3.5)"
Return (as the function result) the value of the
.I no_new_privs
bit for the current process.
A value of 0 indicates the regular
.BR execve (2)
behavior.
A value of 1 indicates
.BR execve (2)
will operate in the privilege-restricting mode described above.
.TP
.BR PR_SET_PDEATHSIG " (since Linux 2.1.57)"
Set the parent process death signal
of the calling process to \fIarg2\fP (either a signal value
in the range 1..maxsig, or 0 to clear).
This is the signal that the calling process will get when its
parent dies.
This value is cleared for the child of a
.BR fork (2)
and (since Linux 2.4.36 / 2.6.23)
when executing a set-user-ID or set-group-ID binary,
or a binary that has associated capabilities (see
.BR capabilities (7)).
This value is preserved across
.BR execve (2).
.TP
.BR PR_GET_PDEATHSIG " (since Linux 2.3.15)"
Return the current value of the parent process death signal,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_SET_PTRACER " (since Linux 3.4)"
.\" commit 2d514487faf188938a4ee4fb3464eeecfbdcf8eb
.\" commit bf06189e4d14641c0148bea16e9dd24943862215
This is meaningful only when the Yama LSM is enabled and in mode 1
("restricted ptrace", visible via
.IR /proc/sys/kernel/yama/ptrace_scope ).
When a "ptracer process ID" is passed in \fIarg2\fP,
the caller is declaring that the ptracer process can
.BR ptrace (2)
the calling process as if it were a direct process ancestor.
Each
.B PR_SET_PTRACER
operation replaces the previous "ptracer process ID".
Employing
.B PR_SET_PTRACER
with
.I arg2
set to 0 clears the caller's "ptracer process ID".
If
.I arg2
is
.BR PR_SET_PTRACER_ANY ,
the ptrace restrictions introduced by Yama are effectively disabled for the
calling process.

For further information, see the kernel source file
.IR Documentation/security/Yama.txt .
.TP
.BR PR_SET_SECCOMP " (since Linux 2.6.23)"
.\" See http://thread.gmane.org/gmane.linux.kernel/542632
.\" [PATCH 0 of 2] seccomp updates
.\" andrea@cpushare.com
Set the secure computing (seccomp) mode for the calling thread, to limit
the available system calls.
The more recent
.BR seccomp (2)
system call provides a superset of the functionality of
.BR PR_SET_SECCOMP .

The seccomp mode is selected via
.IR arg2 .
(The seccomp constants are defined in
.IR <linux/seccomp.h> .)

With
.IR arg2
set to
.BR SECCOMP_MODE_STRICT ,
the only system calls that the thread is permitted to make are
.BR read (2),
.BR write (2),