Provided by: liblinux-prctl-perl_1.5.0-1build1_amd64 bug

NAME

       Linux::Prctl - Perl extension for controlling process characteristics

SYNOPSIS

         use Linux::Prctl;

DESCRIPTION

       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.

   EXPORTS
       There are 2 export tags: :constants and :functions. These export what you think they will.

       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).

       get_dumpable()

       Return the state of the dumpable flag.

       set_endian(endiannes)

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

       This function only works on PowerPC systems.

       get_endian()

       Return the endian-ness of the calling process, see set_endian

       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.

       This function only works on ia64 systems.

       get_fpemu()

       Get floating-point emulation control flag. See set_fpemu.

       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.

       This function only works on PowerPC systems.

       get_fpexc()

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

       set_keepcaps(flag)

       Set the state of the thread's "keep capabilities" flag, which determines whether the
       threads's effective and permitted capability sets are 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 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.

       get_keepcaps()

       Return the current state of the calling threads's "keep capabilities" flag.

       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 function is only available for kernel 2.6.32 and newer

       get_mce_kill()

       Return the current per-process machine check kill policy.

       This function is only available for kernel 2.6.32 and newer

       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 perl applications this will likely be perl. As of perl 5.14, assigning to
       $0 also sets the process name.

       get_name()

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

       set_pdeathsig(signal)

       Set the parent process death signal of the calling process (either a valid signal value
       from the :mod: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.

       get_pdeathsig()

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

       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 function is only available for kernel 3.4 and newer, or Ubuntu 10.10 and newer.

       get_ptracer(pid)

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

       This function is only available for kernel 3.4 and newer, or Ubuntu 10.10 and newer.

       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.

       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.

       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 function is only available for kernel 2.6.28 and newer

       get_timerslack(value)

       Return the current timing slack, see get_timing_slack

       This function is only available for kernel 2.6.28 and newer

       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

       get_timing()

       Return which process timing method is currently in use.

       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.

       This function only works on x86 systems.

       get_tsc()

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

       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.

       This function only works on ia64, parisc, PowerPC and Alpha systems.

       get_unalign

       Return unaligned access control bits, see set_unalign.

       set_securebits(bitmap)

       Set the "securebits" flags of the calling thread.

       It is not recommended to use this function directly, use the %Linux::Prctl::securebits
       hash instead.

       get_securebits()

       Get the "securebits" flags of the calling thread.

       As with set_securebits, it is not recommended to use this function directly, use the
       %Linux::Prctl::securebits hash instead.

       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.

       It is not recommended to use this function directly, use the %Linux::Prctl::cap_* hashes
       instead.

       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.

       As with capbset_read, it is not recommended to use this function directly, use the
       %Linux::Prctl::cap_* hashes 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 %Linux::Prctl::cap_permitted hash):

       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).

       Inheritabe (the %Linux::Prctl::cap_inheritable hash):

       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 %Linux::Prctl::cap_effective hash):

       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 :func:`execve`.

       The $Linux::Prctl::capbset hash represents the current capability bounding sets 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
       items of this hash are true by default, unless a parent process already removed them from
       the bounding set.

       These four hashes have a number of keys. 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 keys of the hashes:

       audit_control

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

       audit_write

       Write records to kernel auditing log.

       chown

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

       dac_override

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

       dac_read_search

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

       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.

       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.

       ipc_lock

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

       ipc_owner

       Bypass permission checks for operations on System V IPC objects.

       kill

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

       lease

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

       linux_immutable

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

       mac_admin

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

       mac_override

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

       mknod

       Create special files using mknod.

       net_admin

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

       net_bind_service

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

       net_broadcast

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

       net_raw

       Use RAW and PACKET sockets.

       setgid

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

       setfcap

       Set file capabilities.

       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.

       setuid

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

       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.

       sys_admin

       Perform a range of system administration operations including: quotactl, mount, umount,
       swapon, swapoff, sethostname, and setdomainname.
       Perform IPC_SET and IPC_RMID operations on arbitrary System V IPC objects.
       Perform operations on trusted and security Extended Attributes (see attr(5)).
       Use lookup_dcookie.
       Use ioprio_set to assign the IOPRIO_CLASS_RT scheduling class.
       Forge UID when passing socket credentials.
       Exceed /proc/sys/fs/file-max, the system-wide limit on the number of open files, in system
       calls that open files (e.g., accept, execve, open, pipe).
       Employ CLONE_NEWNS flag with clone and unshare.
       Perform KEYCTL_CHOWN and KEYCTL_SETPERM keyctl operations.

       sys_boot

       Use reboot and kexec_load.

       sys_chroot

       Use chroot.

       sys_module

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

       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.

       sys_pacct

       Use acct.

       sys_ptrace

       Trace arbitrary processes using ptrace.

       sys_rawio

       Perform I/O port operations (iopl and ioperm); access /proc/kcore.

       sys_resource

       Use reserved space on ext2 file systems.
       Make ioctl calls controlling ext3 journaling.
       Override disk quota limits.
       Increase resource limits (see setrlimit(2)).
       Override RLIMIT_NPROC resource limit.
       Raise msg_qbytes limit for a System V message queue above the limit in
       /proc/sys/kernel/msgmnb (see msgop(2) and msgctl(2)).

       sys_time

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

       sys_tty_config

       Use vhangup.

       wake_alarm

       Allow triggering something that will wake the system.

       This is only available in linux 3.0 and newer

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

       drop(cap [, ...])

       Drop all capabilities given as arguments from the 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 CAP_SYS_ADMIN et cetera.

   Capabilities and execve
       During an execve(2), 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:

        %Linux::Prctl.cap_inheritable{net_bind_service} = 1;
        $< = 1000;
        exec "/usr/sbin/httpd";

       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(8) 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
       $Linux::prctl::securebits hash. This hash has keys that tell you whether specific
       securebits are set, or unset.

       The following keys are available:

       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.

       no_setuid_fixup

       Setting this flag stops the kernel from adjusting capability sets when the threads'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))

       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))

       keep_caps_locked

       Like keep_caps, but irreversible

       no_setuid_fixup_locked

       Like no_setuid_fixup, but irreversible

       noroot_locked

       Like noroot, but irreversible

TODO

       - None of the capability stuff is actually implemented at the moment

SEE ALSO

       Manpages: capabilities(7) and prctl(2)

       Github source: <http://github.com/seveas/Linux-Prctl>

AUTHOR

       Dennis Kaarsemaker, <dennis@kaarsemaker.net>

COPYRIGHT AND LICENSE

       Copyright (C) 2011 by Dennis Kaarsemaker

       This program is free software: you can redistribute it and/or modify it under the terms of
       the GNU General Public License as published by the Free Software Foundation, either
       version 3 of the License, or (at your option) any later version.