Welcome to python-prctl’s documentation!

The linux prctl function allows you to control specific characteristics of a process’ behaviour. Usage of the function is fairly messy though, due to limitations in C and linux. This module provides a nice non-messy python(ic) interface. Most of the text in this documentation is based on text from the linux manpages prctl(2) and capabilities(7)

Besides prctl, this library also wraps libcap for complete capability handling and allows you to set the process name as seen in ps and top.

Downloading and installing

Before you try to install python-prctl, you will need to install the following:

• gcc

• libc development headers

• libcap development headers

On Debian and Ubuntu, this is done as follows:

$ sudo apt-get install build-essential libcap-dev

On Fedora and other RPM-based distributions:

$ sudo yum install gcc glibc-devel libcap-devel

The latest stable version can be installed with distutils:

$ sudo easy_install python-prctl

The latest development source for python-prctl can be downloaded from GitHub. Installing is again done with distutils.

$ git clone http://github.com/seveas/python-prctl
$ cd python-prctl
$ python setup.py build
$ sudo python setup.py install

The prctl module is now ready to use.

prctl – Control process attributes

prctl.set_child_subreaper(flag)

When processes double-fork, they get implicitly re-parented to PID 1. Using this function, processes can mark themselves as service manager and will remain parent of any such processes they launch, becoming a sort of sub-init. They will then be responsible for handling SIGCHLD and calling wait() in them.

This is only available in linux 3.4 and newer

prctl.get_child_subreaper()

Determine whether we are a sub-init.

This is only available in linux 3.4 and newer

prctl.set_dumpable(flag)

Set the state of the flag determining whether core dumps are produced for this 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 is executed and also by various system calls that manipulate process UIDs and GIDs).

prctl.get_dumpable()

Return the state of the dumpable flag.

prctl.set_endian(endianness)

Set the endian-ness of the calling process. Valid values are ENDIAN_BIG, ENDIAN_LITTLE and ENDIAN_PPC_LITTLE (PowerPC pseudo little endian).

Note

This function only works on PowerPC systems. An OSError is raised when called on other systems.

prctl.get_endian()

Return the endian-ness of the calling process, see set_endian().

prctl.set_fpemu(flag)

Set floating-point emulation control flag. Pass FPEMU_NOPRINT to silently emulate fp operations accesses, or FPEMU_SIGFPE to not emulate fp operations and send SIGFPE instead.

Note

This function only works on ia64 systems. An OSError is raised when called on other systems.

prctl.get_fpemu()

Get floating-point emulation control flag. See set_fpemu().

prctl.set_fpexc(mode)

Set floating-point exception mode. Pass FP_EXC_SW_ENABLE to use FPEXC for FP exception, FP_EXC_DIV for floating-point divide by zero, FP_EXC_OVF for floating-point overflow, FP_EXC_UND for floating-point underflow, FP_EXC_RES for floating-point inexact result, FP_EXC_INV for floating-point invalid operation, FP_EXC_DISABLED for FP exceptions disabled, FP_EXC_NONRECOV for async non-recoverable exception mode, FP_EXC_ASYNC for async recoverable exception mode, FP_EXC_PRECISE for precise exception mode. Modes can be combined with the | operator.

Note

This function only works on PowerPC systems. An OSError is raised when called on other systems.

prctl.get_fpexc()

Return the floating-point exception mode as a bitmap of enabled modes. See set_fpexc().

prctl.set_io_flusher(is_flusher)

Put the process in IO_FLUSHER state, which, which allows it special treatment to make progress when allocating memory. This is used by process involved in the block layer or filesystem i/o path, such as fuse daemons or scsi device emulation daemons.

This is only available in linux 5.6 and newer

prctl.get_io_flusher()

Return the IO_FLUSHER state of the process.

This is only available in linux 5.6 and newer

prctl.set_keepcaps(flag)

Set the state of the thread’s “keep capabilities” flag, which determines whether the thread’s effective and permitted capability sets are cleared when a change is made to the thread’s user IDs such that the thread’s real UID, effective UID, and saved set-user-ID all become non-zero when at least one of them previously had the value 0. (By default, these credential sets are cleared). This value will be reset to False on subsequent calls to execve().

prctl.get_keepcaps()

Return the current state of the calling thread’s “keep capabilities” flag.

prctl.set_mce_kill(policy)

Set the machine check memory corruption kill policy for the current thread. The policy can be early kill (MCE_KILL_EARLY), late kill (MCE_KILL_LATE), or the system-wide default (MCE_KILL_DEFAULT). Early kill means that the task receives a SIGBUS signal as soon as hardware memory corruption is detected inside its address space. In late kill mode, the process is only killed when it accesses a corrupted page. The policy is inherited by children. use the system-wide default. The system-wide default is defined by /proc/sys/vm/memory_failure_early_kill

This is only available in linux 2.6.32 and newer

prctl.get_mce_kill()

Return the current per-process machine check kill policy.

This is only available in linux 2.6.32 and newer

prctl.pr_mpx_enable_management()

prctl.pr_mpx_disable_management()

Enable or disable intel memory protection extensions. See prctl(2) for details and limitations.

This is only available in linux 3.19 and newer, but no longer available in linux 5.4 and newer.

prctl.set_name(name)

Set the process name for the calling process, the name can be up to 16 bytes long. This name is displayed in the output of ps and top. The initial value is the name of the executable. For python applications this will likely be python.

Note

Use set_proctitle() to set the name that’s shown with ps aux() and top -c()

prctl.get_name()

Return the (first 16 bytes of) the name for the calling process.

prctl.set_no_new_privs()

Once this is set, no operation that can grant new privileges (such as execve’ing a setuid binary) will actually grant new privileges.

This is only available in linux 3.5 and newer

prctl.get_no_new_privs()

Get whether new privileges can be granted to this pid.

This is only available in linux 3.5 and newer

prctl.pac_reset_keys(keys)

Securely reset the thread’s pointer authentication keys to fresh random values generated by the kernel. The keys must be a logical or of any of the keys you want to reset, or 0 to reset all keys. The available keys are PR_PAC_APIAKEY, PR_PAC_APIBKEY, PR_PAC_APDAKEY, PR_PAC_APDBKEY and PR_PAC_APGAKEY.

For more information, see the kernel source file Documentation/arm64/pointer-authentication.rst

This is only available in linux 5.0 and newer

Note

This function only works on arm64 systems. An OSError is raised when called on other systems.

prctl.set_proctitle(title)

Set the process name for the calling process by overwriting the C-level **argv variable. The original value of **argv is then no longer visible. in ps, proc, or /proc/self/cmdline.

Names longer that what fits in **argv will be silently truncated. To set a longer title, make your application accept bogus arguments and call the application with these arguments.

Note

This function is not actually part of the standard pctrl() syscall, but was added because it nicely complements set_name().

prctl.set_pdeathsig(signal)

Set the parent death signal of the calling process (either a valid signal value from the signal module, 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 fork().

Warning

The “parent” in this case is considered to be the thread that created this process. In other words, the signal will be sent when that thread terminates (via, for example, pthread_exit()), rather than after all of the threads in the parent process terminate.

prctl.get_pdeathsig()

Return the current value of the parent process death signal. See set_pdeathsig().

prctl.set_ptracer(pid)

Sets the top of the process tree that is allowed to use PTRACE() on the calling process, assuming other requirements are met (matching uid, wasn’t setuid, etc). Use pid 0 to disallow all processes. For more details, see /etc/sysctl.d/10-ptrace.conf.

This is only available in linux 3.4 and newer

prctl.get_ptracer(pid)

Returns the top of the process tree that is allowed to use PTRACE() on the calling process. See set_ptracer().

This is only available in linux 3.4 and newer

prctl.set_seccomp(mode)

Set the secure computing mode for the calling thread. In the current implementation, mode must be True. After the secure computing mode has been set to True, the only system calls that the thread is permitted to make are read(), write(), _exit(), and sigreturn(). Other system calls result in the delivery of a SIGKILL signal. Secure computing mode is useful for number-crunching applications that may need to execute untrusted byte code, perhaps obtained by reading from a pipe or socket. This operation is only available if the kernel is configured with CONFIG_SECCOMP enabled.

prctl.get_seccomp()

Return the secure computing mode of the calling thread. Not very useful for the current implementation, but may be useful for other possible future modes: if the caller is not in secure computing mode, this operation returns False; if the caller is in secure computing mode, then the prctl() call will cause a SIGKILL signal to be sent to the process. This operation is only available if the kernel is configured with CONFIG_SECCOMP enabled.

prctl.set_speculation_ctrl(feature, value)

Sets the state of a speculation misfeature (SPEC_STORE_BYPASS or SPEC_INDIRECT_BRANCH). The value is one of PR_SPEC_ENABLE to enable the feature, PR_SPEC_DISABLE to disable it, PR_SPEC_FORCE_DISABLE to disable it permanently for the thread and PR_SPEC_DISABLE_NOEXEC to disable it until the next execve().

This is only available in linux 4.17 and newer

prctl.get_speculation_ctrl(feature)

Returns the state of a speculation misfeature (SPEC_STORE_BYPASS or SPEC_INDIRECT_BRANCH). The value is one of the values that can be set by pr_set_speculation_ctrl(), possibly logically OR’ed with const:PR_SPEC_PRCTL to indicate that the value can be controlled er thread by that function. If all bits are 0, the CPU is not affected by the misfeature.

This is only available in linux 4.17 and newer

prctl.task_perf_events_disable()

prctl.task_perf_events_enable()

Disable or enable all performance counters attached to the calling process, regardless of whether the counters were created by this process or another process. Performance counters created by the calling process for other processes are unaffected.

prctl.set_thp_disable(is_disabled)

Disable transparent huge ages for the current process. This flag is inhereted by child process and preserved across execve.

This is only available in linux 3.15 and newer

prctl.get_thp_disable()

Return whether transparent huge pages are disabled for the current process.

This is only available in linux 3.15 and newer

prctl.get_tid_address()

Allows the process to obtain its own clear_tid_address, used when checkpointing/restoring processes.

This is only available in linux 3.5 and newer

prctl.set_timerslack()

Control the default “rounding” in nanoseconds that is used by select(), poll() and friends.

The default value of the slack is 50 microseconds; this is significantly less than the kernels average timing error but still allows the kernel to group timers somewhat to preserve power behavior.

This is only available in linux 2.6.28 and newer

prctl.get_timerslack(value)

Return the current timing slack, see get_timing_slack()

This is only available in linux 2.6.28 and newer

prctl.set_timing(flag)

Set whether to use (normal, traditional) statistical process timing or accurate timestamp based process timing, by passing TIMING_STATISTICAL or PR_TIMING_TIMESTAMP. TIMING_TIMESTAMP is not currently implemented (attempting to set this mode will cause an OSError).

prctl.get_timing()

Return which process timing method is currently in use.

prctl.set_tsc(flag)

Set the state of the flag determining whether the timestamp counter can be read by the process. Pass TSC_ENABLE to allow it to be read, or TSC_SIGSEGV to generate a SIGSEGV when the process tries to read the timestamp counter.

Note

This function only works on x86 systems. An OSError is raised when called on other systems.

prctl.get_tsc()

Return the state of the flag determining whether the timestamp counter can be read, see set_tsc().

prctl.set_unalign(flag)

Set unaligned access control flag. Pass UNALIGN_NOPRINT to silently fix up unaligned user accesses, or UNALIGN_SIGBUS to generate SIGBUS on unaligned user access.

Note

This function only works on ia64, parisc, PowerPC and Alpha systems. An OSError is raised when called on other systems.

prctl.get_unalign()

Return unaligned access control bits, see set_unalign().

prctl.set_securebits(bitmap)

Set the “securebits” flags of the calling thread.

Note

It is not recommended to use this function directly, use the securebits object instead.

prctl.get_securebits()

Get the “securebits” flags of the calling thread.

Note

As with set_securebits(), it is not recommended to use this function directly, use the securebits object instead.

prctl.capbset_read(capability)

Return whether the specified capability is in the calling thread’s capability bounding set. The capability bounding set dictates whether the process can receive the capability through a file’s permitted capability set on a subsequent call to execve(). An OSError will be raised when an invalid capability is specified.

Note

It is not recommended to use this function directly, use the capbset object instead.

prctl.capbset_drop(capability)

If the calling thread has the CAP_SETPCAP capability, then drop the specified capability specified by from the calling thread’s capability bounding set. Any children of the calling thread will inherit the newly reduced bounding set.

An OSError will be raised if the calling thread does not have the CAP_SETPCAP capability or when the specified capability is invalid or when capabilities are not enabled in the kernel.

Note

As with capbset_read(), it is not recommended to use this function directly, use the capbset object instead.

Capabilities and the capability bounding set

For the purpose of performing permission checks, traditional Unix implementations distinguish two categories of processes: privileged processes (whose effective user ID is 0, referred to as superuser or root), and unprivileged processes (whose effective UID is non-zero). Privileged processes bypass all kernel permission checks, while unprivileged processes are subject to full permission checking based on the process’s credentials (usually: effective UID, effective GID, and supplementary group list).

Starting with kernel 2.2, Linux divides the privileges traditionally associated with superuser into distinct units, known as capabilities, which can be independently enabled and disabled. Capabilities are a per-thread attribute.

Each thread has three capability sets containing zero or more of the capabilities described below

Permitted (the cap_permitted object):

This is a limiting superset for the effective capabilities that the thread may assume. It is also a limiting superset for the capabilities that may be added to the inheritable set by a thread that does not have the setpcap capability in its effective set.

If a thread drops a capability from its permitted set, it can never re-acquire that capability (unless it execve() s either a set-user-ID-root program, or a program whose associated file capabilities grant that capability).

Inheritable (the cap_inheritable object):

This is a set of capabilities preserved across an execve(). It provides a mechanism for a process to assign capabilities to the permitted set of the new program during an execve().

Effective (the cap_effective object):

This is the set of capabilities used by the kernel to perform permission checks for the thread.

A child created via fork() inherits copies of its parent’s capability sets. See below for a discussion of the treatment of capabilities during execve().

The capbset object represents the current capability bounding set of the process. The capability bounding set dictates whether the process can receive the capability through a file’s permitted capability set on a subsequent call to execve(). All attributes of capbset are True by default, unless a parent process already removed them from the bounding set.

These four objects have a number of attributes, all of which are properties. For the capability bounding set and the effective capabilities, these can only be set to False, this drops them from the corresponding set.

All details about capabilities and capability bounding sets can be found in the capabilities(7) manpage, on which most text below is based.

These are the attributes (set refers to each of the above objects):

set.audit_control

Enable and disable kernel auditing; change auditing filter rules; retrieve auditing status and filtering rules.

set.audit_read

Allow reading the audit log via a multicast netlink socket.

set.audit_write

Write records to kernel auditing log.

set.block_suspend

Employ features that can block system suspend (epoll(7) EPOLLWAKEUP, /proc/sys/wake_lock).

set.bpf

Employ privileged BPF operations; see bpf(2) and bpf-helpers(7).

set.chown

Make arbitrary changes to file UIDs and GIDs (see chown(2)).

set.dac_override

Bypass file read, write, and execute permission checks. (DAC is an abbreviation of “discretionary access control”.)

set.dac_read_search

Bypass file read permission checks and directory read and execute permission checks.

set.fowner

• Bypass permission checks on operations that normally require the file system UID of the process to match the UID of the file (e.g., chmod(), utime()), excluding those operations covered by dac_override and dac_read_search.

• Set extended file attributes (see chattr(1)) on arbitrary files.

• Set Access Control Lists (ACLs) on arbitrary files.

• Ignore directory sticky bit on file deletion.

• Specify O_NOATIME for arbitrary files in open() and fcntl().

set.fsetid

Don’t clear set-user-ID and set-group-ID permission bits when a file is modified; set the set-group-ID bit for a file whose GID does not match the file system or any of the supplementary GIDs of the calling process.

set.ipc_lock

Lock memory (mlock(), mlockall(), mmap(), shmctl()).

set.ipc_owner

Bypass permission checks for operations on System V IPC objects.

set.kill

Bypass permission checks for sending signals (see kill(2)). This includes use of the ioctl() KDSIGACCEPT operation.

set.lease

Establish leases on arbitrary files (see fcntl(2)).

set.linux_immutable

Set the FS_APPEND_FL and FS_IMMUTABLE_FL i-node flags (see chattr(1)).

set.mac_admin

Allow MAC configuration or state changes. Implemented for the Smack LSM.

set.mac_override

Override Mandatory Access Control (MAC). Implemented for the Smack Linux Security Module (LSM).

set.mknod

Create special files using mknod().

set.net_admin

Perform various network-related operations (e.g., setting privileged socket options, enabling multicasting, interface configuration, modifying routing tables).

set.net_bind_service

Bind a socket to Internet domain privileged ports (port numbers less than 1024).

set.net_broadcast

(Unused) Make socket broadcasts, and listen to multicasts.

set.net_raw

Use RAW and PACKET sockets.

set.perfmon

Employ various performance-monitoring mechanisms, including perf_event_open() and various BPF operations that have performance implications..

set.setgid

Make arbitrary manipulations of process GIDs and supplementary GID list; forge GID when passing socket credentials via Unix domain sockets.

set.setfcap

Set file capabilities.

set.setpcap

If file capabilities are not supported: grant or remove any capability in the caller’s permitted capability set to or from any other process. (This property of setpcap is not available when the kernel is configured to support file capabilities, since setpcap has entirely different semantics for such kernels.)

If file capabilities are supported: add any capability from the calling thread’s bounding set to its inheritable set; drop capabilities from the bounding set (via capbset_drop()); make changes to the securebits flags.

set.setuid

Make arbitrary manipulations of process UIDs (setuid(), setreuid(), setresuid(), setfsuid()); make forged UID when passing socket credentials via Unix domain sockets.

set.syslog

Allow configuring the kernel’s syslog (printk behaviour). Before linux 2.6.38 the sys_admin capability was needed for this.

This is only available in linux 2.6.38 and newer

set.sys_admin

Perform a range of system administration operations, which change per kernel version. See capabilities(7) for details.

set.sys_boot

Use reboot() and kexec_load().

set.sys_chroot

Use chroot().

set.sys_module

Load and unload kernel modules (see init_module(2) and delete_module(2)).

set.sys_nice

• Raise process nice value (nice(), setpriority()) and change the nice value for arbitrary processes.

• Set real-time scheduling policies for calling process, and set scheduling policies and priorities for arbitrary processes (sched_setscheduler(), sched_setparam()).

• Set CPU affinity for arbitrary processes (sched_setaffinity())

• Set I/O scheduling class and priority for arbitrary processes (ioprio_set()).

• Apply migrate_pages() to arbitrary processes and allow processes to be migrated to arbitrary nodes.

• Apply move_pages() to arbitrary processes.

• Use the MPOL_MF_MOVE_ALL flag with mbind() and move_pages().

set.sys_pacct

Use acct().

set.sys_ptrace

Trace arbitrary processes using ptrace().

set.sys_rawio

Perform a range of privileged i/o operations, which change per kernel version. See capabilities(7) for details.

set.sys_resource

Use a set of privileged resources, which change per kernel version. See capabilities(7) for details.

set.sys_time

Set system clock (settimeofday(), stime(), adjtimex()); set real-time (hardware) clock.

set.sys_tty_config

Use vhangup().

set.wake_alarm

Allow triggering something that will wake the system.

This is only available in linux 3.0 and newer

The four capabilities objects also have two additional methods, to make dropping many capabilities at the same time easier:

set.drop(cap[, ...])

Drop all capabilities given as arguments from the set.

set.limit(cap[, ...])

Drop all but the given capabilities from the set.

These function accept both names of capabilities as given above and the CAP_ constants as defined in capabilities.h. These constants are available as prctl.CAP_SYS_ADMIN et cetera.

Capabilities and execve()

During an execve(), the kernel calculates the new capabilities of the process using the following algorithm:

• P’(permitted) = (P(inheritable) & F(inheritable)) | (F(permitted) & cap_bset)

• P’(effective) = F(effective) ? P’(permitted) : 0

• P’(inheritable) = P(inheritable) [i.e., unchanged]

Where:

• P denotes the value of a thread capability set before the execve()

• P’ denotes the value of a capability set after the execve()

• F denotes a file capability set

• cap_bset is the value of the capability bounding set

The downside of this is that you need to set file capabilities if you want to make applications capabilities-friendly via wrappers. For instance, to allow an http daemon to listen on port 80 without it needing root privileges, you could do the following:

prctl.cap_inheritable.net_bind_service = True
os.setuid(pwd.getpwnam('www-data').pw_uid)
os.execve("/usr/sbin/httpd", ["/usr/sbin/httpd"], os.environ)

This only works if /usr/sbin/httpd has CAP_NET_BIND_SOCK in its inheritable and effective sets. You can do this with the setcap tool shipped with libcap.

$ sudo setcap cap_net_bind_service=ie /usr/sbin/httpd
$ getcap /usr/sbin/httpd
/usr/sbin/httpd = cap_net_bind_service+ei

Note that it only sets the capability in the inheritable set, so this capability is only granted if the program calling execve has it in its inheritable set too. The effective set of file capabilities does not exist in linux, it is a single bit that specifies whether capabilities in the permitted set are automatically raised in the effective set upon execve().

Establishing a capabilities-only environment with securebits

With a kernel in which file capabilities are enabled, Linux implements a set of per-thread securebits flags that can be used to disable special handling of capabilities for UID 0 (root). The securebits flags are inherited by child processes. During an execve(), all of the flags are preserved, except keep_caps which is always cleared.

These capabilities are available via get_securebits(), but are easier accessed via the securebits object. This object has attributes tell you whether specific securebits are set, or unset.

The following attributes are available:

securebits.keep_caps

Setting this flag allows a thread that has one or more 0 UIDs to retain its capabilities when it switches all of its UIDs to a non-zero value. If this flag is not set, then such a UID switch causes the thread to lose all capabilities. This flag is always cleared on an execve().

securebits.no_setuid_fixup

Setting this flag stops the kernel from adjusting capability sets when the thread’s effective and file system UIDs are switched between zero and non-zero values. (See the subsection Effect of User ID Changes on Capabilities in capabilities(7))

securebits.noroot

If this bit is set, then the kernel does not grant capabilities when a set-user-ID-root program is executed, or when a process with an effective or real UID of 0 calls execve(). (See the subsection Capabilities and execution of programs by root in capabilities(7))

securebits.keep_caps_locked

Like keep_caps, but irreversible

securebits.no_setuid_fixup_locked

Like no_setuid_fixup, but irreversible

securebits.noroot_locked

Like noroot, but irreversible

_prctl – Basic C wrapper around prctl

This is the lower level C module that wraps the prctl() syscall in a way that it is easy to call from a python module. It should not be used directly, applications and other libraries should use the functionality provided by the prctl module.

This section of the documentation is meant for people who want to contribute to python-prctl.

static PyObject* prctl_prctl(PyObject *self, PyObject *args)

This is the prctl() wrapper. It accepts as argument either one or two int variables or an int and a str.

The mandatory first int must be one of the PR_SET_*, PR_GET_*, or PR_CAPBSET_* constants defined in sys/prctl.h. The accepted values of the second argument depend on the first argument, see prctl(2).

The function validates arguments, calls prctl() in the argument-specific way and returns the proper value, whether prctl() returns it as return value or stores it in one of the parameters.

static PyObject* prctl_set_proctitle(PyObject *self, PyObject *args)

Set the process title by mangling **argv. Mandatory argument is a str.

PyMODINIT_FUNC init_prctl(void)

Create the module instance and add all the relevant constants to the module. That means all PR_*, CAP_* and SECBIT_* constants mentioned in prctl(2) and capabilities(7). To avoid repeating yourself all the time, use the namedconstant and namedattribute macros when adding new values.