man-pages/man7/capabilities.7

.\" Copyright (c) 2002 by Michael Kerrisk <mtk-manpages@gmx.net>
.\"
.\" 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.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" 6 Aug 2002 - Initial Creation
.\" Modified 2003-05-23, Michael Kerrisk, <mtk-manpages@gmx.net>
.\" Modified 2004-05-27, Michael Kerrisk, <mtk-manpages@gmx.net>
.\" 2004-12-08, mtk Added O_NOATIME for CAP_FOWNER
.\" 2005-08-16, mtk, Added CAP_AUDIT_CONTROL and CAP_AUDIT_WRITE
.\"
.\" FIXME Capabilities are actually per-thread.
.\"
.TH CAPABILITIES 7 2005-10-28 "Linux 2.6.14" "Linux Programmer's Manual"
.SH NAME
capabilities \- overview of Linux capabilities
.SH DESCRIPTION
For the purpose of performing permission checks,
traditional Unix implementations distinguish two categories of processes:
.I privileged
processes (whose effective user ID is 0, referred to as superuser or root),
and
.I 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 
.IR capabilities ,
which can be independently enabled and disabled.
.SS Capabilities List

As at Linux 2.6.14, the following capabilities are implemented:
.TP
.BR CAP_AUDIT_CONTROL " (since Linux 2.6.11)"
Enable and disable kernel auditing; change auditing filter rules;
retrieve auditing status and filtering rules.
.TP
.BR CAP_AUDIT_WRITE " (since Linux 2.6.11)"
Allow records to be written to kernel auditing log.
.TP
.B CAP_CHOWN
Allow arbitrary changes to file UIDs and GIDs (see
.BR chown (2)).
.TP
.B CAP_DAC_OVERRIDE
Bypass file read, write, and execute permission checks.
(DAC = "discretionary access control".)
.TP
.B CAP_DAC_READ_SEARCH
Bypass file read permission checks and
directory read and execute permission checks.
.TP
.B CAP_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.,
.BR chmod (2),
.BR utime (2)),
excluding those operations covered by the
.B CAP_DAC_OVERRIDE
and
.BR CAP_DAC_READ_SEARCH ;
set extended file attributes (see
.BR chattr (1))
on arbitrary files;
set Access Control Lists (ACLs) on arbitrary files;
ignore directory sticky bit on file deletion;
specify
.B O_NOATIME
for arbitrary files in
.BR open (2)
and
.BR fcntl (2).
.TP
.B CAP_FSETID
Don't clear set-user-ID and set-group-ID bits when a file is modified;
permit setting of 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.
.TP
.B CAP_IPC_LOCK
Permit memory locking
.RB ( mlock (2),
.BR mlockall (2),
.BR mmap (2),
.BR shmctl (2)).
.TP
.B CAP_IPC_OWNER
Bypass permission checks for operations on System V IPC objects.
.TP
.B CAP_KILL
Bypass permission checks for sending signals (see
.BR kill (2)).
This includes use of the KDSIGACCEPT ioctl.
.\" FIXME CAP_KILL also an effect for threads + setting child
.\"       termination signal to other than SIGCHLD; but what are
.\"       the details?
.TP
.B CAP_LEASE
(Linux 2.4 onwards)  Allow file leases to be established on
arbitrary files (see
.BR fcntl (2)).
.TP
.B CAP_LINUX_IMMUTABLE
Allow setting of the
.B EXT2_APPEND_FL
and
.B EXT2_IMMUTABLE_FL
.\" These attributes are now available on ext2, ext3, Reiserfs
extended file attributes (see
.BR chattr (1)).
.TP
.B CAP_MKNOD
(Linux 2.4 onwards)
Allow creation of special files using
.BR mknod (2).
.TP
.B CAP_NET_ADMIN
Allow various network-related operations
(e.g., setting privileged socket options,
enabling multicasting, interface configuration,
modifying routing tables).
.TP
.B CAP_NET_BIND_SERVICE
Allow binding to Internet domain reserved socket ports
(port numbers less than 1024).
.TP
.B CAP_NET_BROADCAST
(Unused)  Allow socket broadcasting, and listening multicasts.
.TP
.B CAP_NET_RAW
Permit use of RAW and PACKET sockets.
.\" Also various IP options and setsockopt(SO_BINDTODEVICE)
.TP
.B CAP_SETGID
Allow arbitrary manipulations of process GIDs and supplementary GID list;
allow forged GID when passing socket credentials via Unix domain sockets.
.TP
.B CAP_SETPCAP
Grant or remove any capability in the caller's
permitted capability set to or from any other process.
.TP
.B CAP_SETUID
Allow arbitrary manipulations of process UIDs
.RB ( setuid (2),
.BR setreuid (2),
.BR setresuid (2),
.BR setfsuid (2));
allow forged UID when passing socket credentials via Unix domain sockets.
.\" FIXME CAP_SETUID also an effect in exec(); document this.
.TP
.B CAP_SYS_ADMIN
Permit a range of system administration operations including:
.BR quotactl (2),
.BR mount (2),
.BR umount (2),
.BR swapon (2) ,
.BR swapoff (2) ,
.BR sethostname (2),
.BR setdomainname (2),
.B IPC_SET
and
.B IPC_RMID
operations on arbitrary System V IPC objects;
perform operations on
.I trusted
and
.I security
Extended Attributes (see
.BR attr (5));
call
.BR lookup_dcookie (2);
perform 
.BR keyctl (2)
.B KEYCTL_CHOWN
and
.B KEYCTL_SETPERM 
operations.
allow forged UID when passing socket credentials;
exceed
.IR /proc/sys/fs/file-max ,
the system-wide limit on the number of open files,
in system calls that open files (e.g.,
.BR accept (2),
.BR execve (2),
.BR open (2),
.BR pipe (2); 
without this capability these system calls will fail with the error 
.B ENFILE 
if this limit is encountered).
.\" FIXME 2.6.14-rc1 permits the following with CAP_SYS_ADMIN: 
.\"       /* Allow setting zone reclaim policy */
.\"       Document this.
.\" FIXME CAP_SYS_ADMIN has an affect for ioprio_set()
.TP
.B CAP_SYS_BOOT
Permit calls to
.BR reboot (2)
and
.BR kexec_load (2).
.TP
.B CAP_SYS_CHROOT
Permit calls to
.BR chroot (2).
.TP
.B CAP_SYS_MODULE
Allow loading and unloading of kernel modules;
allow modifications to capability bounding set (see
.BR init_module (2)
and
.BR delete_module (2)).
.TP
.B CAP_SYS_NICE
Allow raising process nice value
.RB ( nice (2),
.BR setpriority (2))
and changing of the nice value for arbitrary processes;
allow setting of real-time scheduling policies for calling process,
and setting scheduling policies and priorities for arbitrary processes
.RB ( sched_setscheduler (2),
.BR sched_setparam (2));
set CPU affinity for arbitrary processes
.RB ( sched_setaffinity ()).
.\" FIXME Probably CAP_SYS_NICE will have a new affect in 2.6.16
.\" 	  for MPOL_MF_MOVE_ALL and migrate_pages(2)
.\" FIXME CAP_SYS_NICE has an affect for ioprio_set()
.TP
.B CAP_SYS_PACCT
Permit calls to
.BR acct (2).
.TP
.B CAP_SYS_PTRACE
Allow arbitrary processes to be traced using
.BR ptrace (2)
.TP
.B CAP_SYS_RAWIO
Permit I/O port operations
.RB ( iopl (2)
and
.BR ioperm (2));
access
.IT /proc/kcore .
.TP
.B CAP_SYS_RESOURCE
Permit: use of reserved space on ext2 file systems;
.BR ioctl (2)
calls controlling ext3 journaling;
disk quota limits to be overridden;
resource limits to be increased (see
.BR setrlimit (2));
.B RLIMIT_NPROC
resource limit to be overridden;
.I msg_qbytes
limit for a message queue to be
raised above the limit in
.IR /proc/sys/kernel/msgmnb
(see
.BR msgop (2)
and
.BR msgctl (2).
.TP
.B CAP_SYS_TIME
Allow modification of system clock
.RB ( settimeofday (2),
.BR stime (2),
.BR adjtimex (2));
allow modification of real-time (hardware) clock
.TP
.B CAP_SYS_TTY_CONFIG
Permit calls to
.BR vhangup (2).
.SS Process Capabilities
Each process has three capability sets containing zero or more
of the above capabilities:
.TP
.IR Effective :
the capabilities used by the kernel to
perform permission checks for the process.
.TP
.IR Permitted :
the capabilities that the process may assume
(i.e., a limiting superset for the effective and inheritable sets).
If a process drops a capability from its permitted set,
it can never re-acquire that capability (unless it 
.BR exec ()s 
a set-user-ID-root program).
.TP
.IR inheritable :
the capabilities preserved across an
.BR execve (2).
.PP
A child created via
.BR fork (2)
inherits copies of its parent's capability sets.
See below for a discussion of the treatment of capabilities during
.BR exec ().
.PP
Using
.BR capset (2),
a process may manipulate its own capability sets, or, if it has the
.B CAP_SETPCAP
capability, those of another process.
.SS Capability bounding set
When a program is execed, the permitted and effective capabilities
are ANDed with the current value of the so-called
.IR "capability bounding set" ,
defined in the file
.IR /proc/sys/kernel/cap-bound .
This parameter can be used to place a system-wide limit on the
capabilities granted to all subsequently executed programs.
(Confusingly, this bit mask parameter is expressed as a
signed decimal number in
.IR /proc/sys/kernel/cap-bound .)

Only the
.B init
process may set bits in the capability bounding set;
other than that, the superuser may only clear bits in this set.

On a standard system the capability bounding set always masks out the
.B CAP_SETPCAP
capability.
To remove this restriction (dangerous!), modify the definition of
.B CAP_INIT_EFF_SET
in
.I include/linux/capability.h
and rebuild the kernel.

The capability bounding set feature was added to Linux starting with
kernel version 2.2.11.
.SS Current and Future Implementation
A full implementation of capabilities requires:
.IP 1. 4
that for all privileged operations,
the kernel check whether the process has the required
capability in its effective set.
.IP 2. 4
that the kernel provide 
system calls allowing a process's capability sets to
be changed and retrieved.
.IP 3. 4
file system support for attaching capabilities to an executable file,
so that a process gains those capabilities when the file is execed.
.PP
As at Linux 2.6.14, only the first two of these requirements are met.

Eventually, it should be possible to associate three 
capability sets with an executable file, which,
in conjunction with the capability sets of the process,
will determine the capabilities of a process after an
.BR exec ():
.TP
.IR Inheritable " (formerly known as " allowed ):
this set is ANDed with the process's inheritable set to determine which
inheritable capabilities are permitted to the process after the 
.BR exec ().
.TP
.IR Permitted " (formerly known as " forced ):
the capabilities automatically permitted to the process,
regardless of the process's inheritable capabilities.
.TP
.IR Effective :
those capabilities in the process's new permitted set are
also to be set in the new effective set.
(F(effective) would normally be either all zeroes or all ones.)
.PP
In the meantime, since the current implementation does not
support file capability sets, during an 
.BR exec ():
.IP 1. 4
All three file capability sets are initially assumed to be cleared.
.IP 2. 4
If a set-user-ID-root program is being execed,
or the real user ID of the process is 0 (root)
then the file inheritable and permitted sets are defined to be all ones
(i.e., all capabilities enabled).
.IP 3. 4
If a set-user-ID-root program is being executed,
then the file effective set is defined to be all ones.
.SS Transformation of Process Capabilities During exec()
.PP
During an 
.BR exec (), 
the kernel calculates the new capabilities of
the process using the following algorithm:
.in +4
.nf

P'(permitted) = (P(inheritable) & F(inheritable)) | 
                (F(permitted) & cap_bset)

P'(effective) = P'(permitted) & F(effective)

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

.fi
.in -4
where:
.IP P 10
denotes the value of a process capability set before the 
.BR exec ()
.IP P' 10
denotes the value of a capability set after the 
.BR exec ()
.IP F 10
denotes a file capability set
.IP cap_bset 10
is the value of the capability bounding set.
.PP
In the current implementation, the upshot of this algorithm is that
when a process 
.BR exec ()s
a set-user-ID-root program, or when a process with an effective UID of 0
.BR exec ()s
a program,
it gains all capabilities in its permitted and effective capability sets, 
except those masked out by the capability bounding set (i.e., 
.BR CAP_SETPCAP ).
.\" If a process with real UID 0, and non-zero effective UID does an 
.\" exec(), then it gets all capabilities (less CAP_SETPCAP) in its 
.\" permitted set, and no effective capabilities
This provides semantics that are the same as those provided by
traditional Unix systems.
.SS Effect of User ID Changes on Capabilities
To preserve the traditional semantics for transitions between 
0 and non-zero user IDs, 
the kernel makes the following changes to a process's capability 
sets on changes to the process's real, effective, saved set, 
and file system user IDs (using
.BR setuid (2),
.BR setresuid (2),
or similar):
.IP 1. 4
If one or more of the real, effective or saved set user IDs 
was previously 0, and as a result of the UID changes all of these IDs 
have a non-zero value, 
then all capabilities are cleared from the permitted and effective 
capability sets.
.IP 2. 4
If the effective user ID is changed from 0 to non-zero, 
then all capabilities are cleared from the effective set.
.IP 3. 4
If the effective user ID is changed from non-zero to 0,
then the permitted set is copied to the effective set. 
.IP 4. 4
If the file system user ID is changed from 0 to non-zero (see
.BR setfsuid (2))
then the following capabilities are cleared from the effective set:
.BR CAP_CHOWN ,
.BR CAP_DAC_OVERRIDE ,
.BR CAP_DAC_READ_SEARCH ,
.BR CAP_FOWNER ,
and
.BR CAP_FSETID .
If the file system UID is changed from non-zero to 0,
then any of these capabilities that are enabled in the permitted set 
are enabled in the effective set.
.PP
If a process that has a 0 value for one or more of its user IDs wants
to prevent its permitted capability set being cleared when it resets
all of its user IDs to non-zero values, it can do so using the
.BR prctl ()
.B PR_SET_KEEPCAPS
operation.
.SH NOTES
The
.I libcap
package provides a suite of routines for setting and
getting process capabilities that is more comfortable and less likely
to change than the interface provided by
.BR capset (2)
and
.BR capget (2).
.SH "CONFORMING TO"
No standards govern capabilities, but the Linux capability implementation
is based on the withdrawn POSIX 1003.1e draft standard.
.SH BUGS
There is as yet no file system support allowing capabilities to be
associated with executable files.
.SH "SEE ALSO"
.BR capget (2),
.BR prctl (2),
.BR setfsuid (2)