1CAPABILITIES(7) Linux Programmer's Manual CAPABILITIES(7)
2
6 capabilities - overview of Linux capabilities
7
9 For the purpose of performing permission checks, traditional UNIX im‐
10 plementations distinguish two categories of processes: privileged pro‐
11 cesses (whose effective user ID is 0, referred to as superuser or
12 root), and unprivileged processes (whose effective UID is nonzero).
13 Privileged processes bypass all kernel permission checks, while unpriv‐
14 ileged processes are subject to full permission checking based on the
15 process's credentials (usually: effective UID, effective GID, and sup‐
16 plementary group list).
17 Starting with kernel 2.2, Linux divides the privileges traditionally
19 associated with superuser into distinct units, known as capabilities,
20 which can be independently enabled and disabled. Capabilities are a
21 per-thread attribute.
22 Capabilities list
24 The following list shows the capabilities implemented on Linux, and the
25 operations or behaviors that each capability permits:
26 CAP_AUDIT_CONTROL (since Linux 2.6.11)
28 Enable and disable kernel auditing; change auditing filter
29 rules; retrieve auditing status and filtering rules.
30 CAP_AUDIT_READ (since Linux 3.16)
32 Allow reading the audit log via a multicast netlink socket.
33 CAP_AUDIT_WRITE (since Linux 2.6.11)
35 Write records to kernel auditing log.
36 CAP_BLOCK_SUSPEND (since Linux 3.5)
38 Employ features that can block system suspend (epoll(7) EPOLL‐
39 WAKEUP, /proc/sys/wake_lock).
40 CAP_BPF (since Linux 5.8)
42 Employ privileged BPF operations; see bpf(2) and bpf-helpers(7).
43 This capability was added in Linux 5.8 to separate out BPF func‐
45 tionality from the overloaded CAP_SYS_ADMIN capability.
46 CAP_CHECKPOINT_RESTORE (since Linux 5.9)
48 * Update /proc/sys/kernel/ns_last_pid (see pid_namespaces(7));
49 * employ the set_tid feature of clone3(2);
50 * read the contents of the symbolic links in
51 /proc/[pid]/map_files for other processes.
52 This capability was added in Linux 5.9 to separate out check‐
54 point/restore functionality from the overloaded CAP_SYS_ADMIN
55 capability.
56 CAP_CHOWN
58 Make arbitrary changes to file UIDs and GIDs (see chown(2)).
59 CAP_DAC_OVERRIDE
61 Bypass file read, write, and execute permission checks. (DAC is
62 an abbreviation of "discretionary access control".)
63 CAP_DAC_READ_SEARCH
65 * Bypass file read permission checks and directory read and exe‐
66 cute permission checks;
67 * invoke open_by_handle_at(2);
68 * use the linkat(2) AT_EMPTY_PATH flag to create a link to a
69 file referred to by a file descriptor.
70 CAP_FOWNER
72 * Bypass permission checks on operations that normally require
73 the filesystem UID of the process to match the UID of the file
74 (e.g., chmod(2), utime(2)), excluding those operations covered
75 by CAP_DAC_OVERRIDE and CAP_DAC_READ_SEARCH;
76 * set inode flags (see ioctl_iflags(2)) on arbitrary files;
77 * set Access Control Lists (ACLs) on arbitrary files;
78 * ignore directory sticky bit on file deletion;
79 * modify user extended attributes on sticky directory owned by
80 any user;
81 * specify O_NOATIME for arbitrary files in open(2) and fcntl(2).
82 CAP_FSETID
84 * Don't clear set-user-ID and set-group-ID mode bits when a file
85 is modified;
86 * set the set-group-ID bit for a file whose GID does not match
87 the filesystem or any of the supplementary GIDs of the calling
88 process.
89 CAP_IPC_LOCK
91 * Lock memory (mlock(2), mlockall(2), mmap(2), shmctl(2));
92 * Allocate memory using huge pages (memfd_create(2) mmap(2),
93 shmctl(2)).
94 CAP_IPC_OWNER
95 Bypass permission checks for operations on System V IPC objects.
96 CAP_KILL
97 Bypass permission checks for sending signals (see kill(2)).
98 This includes use of the ioctl(2) KDSIGACCEPT operation.
99 CAP_LEASE (since Linux 2.4)
100 Establish leases on arbitrary files (see fcntl(2)).
101 CAP_LINUX_IMMUTABLE
102 Set the FS_APPEND_FL and FS_IMMUTABLE_FL inode flags (see
103 ioctl_iflags(2)).
104 CAP_MAC_ADMIN (since Linux 2.6.25)
105 Allow MAC configuration or state changes. Implemented for the
106 Smack Linux Security Module (LSM).
107 CAP_MAC_OVERRIDE (since Linux 2.6.25)
108 Override Mandatory Access Control (MAC). Implemented for the
109 Smack LSM.
110 CAP_MKNOD (since Linux 2.4)
111 Create special files using mknod(2).
112 CAP_NET_ADMIN
113 Perform various network-related operations:
114 * interface configuration;
115 * administration of IP firewall, masquerading, and accounting;
116 * modify routing tables;
117 * bind to any address for transparent proxying;
118 * set type-of-service (TOS);
119 * clear driver statistics;
120 * set promiscuous mode;
121 * enabling multicasting;
122 * use setsockopt(2) to set the following socket options: SO_DE‐
123 BUG, SO_MARK, SO_PRIORITY (for a priority outside the range 0
124 to 6), SO_RCVBUFFORCE, and SO_SNDBUFFORCE.
125 CAP_NET_BIND_SERVICE
127 Bind a socket to Internet domain privileged ports (port numbers
128 less than 1024).
129 CAP_NET_BROADCAST
131 (Unused) Make socket broadcasts, and listen to multicasts.
132 CAP_NET_RAW
134 * Use RAW and PACKET sockets;
135 * bind to any address for transparent proxying.
136 CAP_PERFMON (since Linux 5.8)
138 Employ various performance-monitoring mechanisms, including:
139 * call perf_event_open(2);
141 * employ various BPF operations that have performance implica‐
142 tions.
143 This capability was added in Linux 5.8 to separate out perfor‐
145 mance monitoring functionality from the overloaded CAP_SYS_ADMIN
146 capability. See also the kernel source file Documentation/ad‐
147 min-guide/perf-security.rst.
148 CAP_SETGID
150 * Make arbitrary manipulations of process GIDs and supplementary
151 GID list;
152 * forge GID when passing socket credentials via UNIX domain
153 sockets;
154 * write a group ID mapping in a user namespace (see user_name‐
155 spaces(7)).
156 CAP_SETFCAP (since Linux 2.6.24)
158 Set arbitrary capabilities on a file.
159 CAP_SETPCAP
161 If file capabilities are supported (i.e., since Linux 2.6.24):
162 add any capability from the calling thread's bounding set to its
163 inheritable set; drop capabilities from the bounding set (via
164 prctl(2) PR_CAPBSET_DROP); make changes to the securebits flags.
165 If file capabilities are not supported (i.e., kernels before
167 Linux 2.6.24): grant or remove any capability in the caller's
168 permitted capability set to or from any other process. (This
169 property of CAP_SETPCAP is not available when the kernel is con‐
170 figured to support file capabilities, since CAP_SETPCAP has en‐
171 tirely different semantics for such kernels.)
172 CAP_SETUID
174 * Make arbitrary manipulations of process UIDs (setuid(2), se‐
175 treuid(2), setresuid(2), setfsuid(2));
176 * forge UID when passing socket credentials via UNIX domain
177 sockets;
178 * write a user ID mapping in a user namespace (see user_name‐
179 spaces(7)).
180 CAP_SYS_ADMIN
182 Note: this capability is overloaded; see Notes to kernel devel‐
183 opers, below.
184 * Perform a range of system administration operations including:
186 quotactl(2), mount(2), umount(2), pivot_root(2), swapon(2),
187 swapoff(2), sethostname(2), and setdomainname(2);
188 * perform privileged syslog(2) operations (since Linux 2.6.37,
189 CAP_SYSLOG should be used to permit such operations);
190 * perform VM86_REQUEST_IRQ vm86(2) command;
191 * access the same checkpoint/restore functionality that is gov‐
192 erned by CAP_CHECKPOINT_RESTORE (but the latter, weaker capa‐
193 bility is preferred for accessing that functionality).
194 * perform the same BPF operations as are governed by CAP_BPF
195 (but the latter, weaker capability is preferred for accessing
196 that functionality).
197 * employ the same performance monitoring mechanisms as are gov‐
198 erned by CAP_PERFMON (but the latter, weaker capability is
199 preferred for accessing that functionality).
200 * perform IPC_SET and IPC_RMID operations on arbitrary System V
201 IPC objects;
202 * override RLIMIT_NPROC resource limit;
203 * perform operations on trusted and security extended attributes
204 (see xattr(7));
205 * use lookup_dcookie(2);
206 * use ioprio_set(2) to assign IOPRIO_CLASS_RT and (before Linux
207 2.6.25) IOPRIO_CLASS_IDLE I/O scheduling classes;
208 * forge PID when passing socket credentials via UNIX domain
209 sockets;
210 * exceed /proc/sys/fs/file-max, the system-wide limit on the
211 number of open files, in system calls that open files (e.g.,
212 accept(2), execve(2), open(2), pipe(2));
213 * employ CLONE_* flags that create new namespaces with clone(2)
214 and unshare(2) (but, since Linux 3.8, creating user namespaces
215 does not require any capability);
216 * access privileged perf event information;
217 * call setns(2) (requires CAP_SYS_ADMIN in the target name‐
218 space);
219 * call fanotify_init(2);
220 * perform privileged KEYCTL_CHOWN and KEYCTL_SETPERM keyctl(2)
221 operations;
222 * perform madvise(2) MADV_HWPOISON operation;
223 * employ the TIOCSTI ioctl(2) to insert characters into the in‐
224 put queue of a terminal other than the caller's controlling
225 terminal;
226 * employ the obsolete nfsservctl(2) system call;
227 * employ the obsolete bdflush(2) system call;
228 * perform various privileged block-device ioctl(2) operations;
229 * perform various privileged filesystem ioctl(2) operations;
230 * perform privileged ioctl(2) operations on the /dev/random de‐
231 vice (see random(4));
232 * install a seccomp(2) filter without first having to set the
233 no_new_privs thread attribute;
234 * modify allow/deny rules for device control groups;
235 * employ the ptrace(2) PTRACE_SECCOMP_GET_FILTER operation to
236 dump tracee's seccomp filters;
237 * employ the ptrace(2) PTRACE_SETOPTIONS operation to suspend
238 the tracee's seccomp protections (i.e., the PTRACE_O_SUS‐
239 PEND_SECCOMP flag);
240 * perform administrative operations on many device drivers;
241 * modify autogroup nice values by writing to /proc/[pid]/auto‐
242 group (see sched(7)).
243 CAP_SYS_BOOT
245 Use reboot(2) and kexec_load(2).
246 CAP_SYS_CHROOT
248 * Use chroot(2);
249 * change mount namespaces using setns(2).
250 CAP_SYS_MODULE
252 * Load and unload kernel modules (see init_module(2) and
253 delete_module(2));
254 * in kernels before 2.6.25: drop capabilities from the system-
255 wide capability bounding set.
256 CAP_SYS_NICE
258 * Lower the process nice value (nice(2), setpriority(2)) and
259 change the nice value for arbitrary processes;
260 * set real-time scheduling policies for calling process, and set
261 scheduling policies and priorities for arbitrary processes
262 (sched_setscheduler(2), sched_setparam(2), sched_setattr(2));
263 * set CPU affinity for arbitrary processes (sched_setaffin‐
264 ity(2));
265 * set I/O scheduling class and priority for arbitrary processes
266 (ioprio_set(2));
267 * apply migrate_pages(2) to arbitrary processes and allow pro‐
268 cesses to be migrated to arbitrary nodes;
269 * apply move_pages(2) to arbitrary processes;
270 * use the MPOL_MF_MOVE_ALL flag with mbind(2) and move_pages(2).
271 CAP_SYS_PACCT
273 Use acct(2).
274 CAP_SYS_PTRACE
276 * Trace arbitrary processes using ptrace(2);
277 * apply get_robust_list(2) to arbitrary processes;
278 * transfer data to or from the memory of arbitrary processes us‐
279 ing process_vm_readv(2) and process_vm_writev(2);
280 * inspect processes using kcmp(2).
281 CAP_SYS_RAWIO
283 * Perform I/O port operations (iopl(2) and ioperm(2));
284 * access /proc/kcore;
285 * employ the FIBMAP ioctl(2) operation;
286 * open devices for accessing x86 model-specific registers (MSRs,
287 see msr(4));
288 * update /proc/sys/vm/mmap_min_addr;
289 * create memory mappings at addresses below the value specified
290 by /proc/sys/vm/mmap_min_addr;
291 * map files in /proc/bus/pci;
292 * open /dev/mem and /dev/kmem;
293 * perform various SCSI device commands;
294 * perform certain operations on hpsa(4) and cciss(4) devices;
295 * perform a range of device-specific operations on other de‐
296 vices.
297 CAP_SYS_RESOURCE
299 * Use reserved space on ext2 filesystems;
300 * make ioctl(2) calls controlling ext3 journaling;
301 * override disk quota limits;
302 * increase resource limits (see setrlimit(2));
303 * override RLIMIT_NPROC resource limit;
304 * override maximum number of consoles on console allocation;
305 * override maximum number of keymaps;
306 * allow more than 64hz interrupts from the real-time clock;
307 * raise msg_qbytes limit for a System V message queue above the
308 limit in /proc/sys/kernel/msgmnb (see msgop(2) and msgctl(2));
309 * allow the RLIMIT_NOFILE resource limit on the number of "in-
310 flight" file descriptors to be bypassed when passing file de‐
311 scriptors to another process via a UNIX domain socket (see
312 unix(7));
313 * override the /proc/sys/fs/pipe-size-max limit when setting the
314 capacity of a pipe using the F_SETPIPE_SZ fcntl(2) command;
315 * use F_SETPIPE_SZ to increase the capacity of a pipe above the
316 limit specified by /proc/sys/fs/pipe-max-size;
317 * override /proc/sys/fs/mqueue/queues_max,
318 /proc/sys/fs/mqueue/msg_max, and /proc/sys/fs/mqueue/msg‐
319 size_max limits when creating POSIX message queues (see
320 mq_overview(7));
321 * employ the prctl(2) PR_SET_MM operation;
322 * set /proc/[pid]/oom_score_adj to a value lower than the value
323 last set by a process with CAP_SYS_RESOURCE.
324 CAP_SYS_TIME
326 Set system clock (settimeofday(2), stime(2), adjtimex(2)); set
327 real-time (hardware) clock.
328 CAP_SYS_TTY_CONFIG
330 Use vhangup(2); employ various privileged ioctl(2) operations on
331 virtual terminals.
332 CAP_SYSLOG (since Linux 2.6.37)
334 * Perform privileged syslog(2) operations. See syslog(2) for
335 information on which operations require privilege.
336 * View kernel addresses exposed via /proc and other interfaces
337 when /proc/sys/kernel/kptr_restrict has the value 1. (See the
338 discussion of the kptr_restrict in proc(5).)
339 CAP_WAKE_ALARM (since Linux 3.0)
341 Trigger something that will wake up the system (set CLOCK_REAL‐
342 TIME_ALARM and CLOCK_BOOTTIME_ALARM timers).
343 Past and current implementation
345 A full implementation of capabilities requires that:
346 1. For all privileged operations, the kernel must check whether the
348 thread has the required capability in its effective set.
349 2. The kernel must provide system calls allowing a thread's capability
351 sets to be changed and retrieved.
352 3. The filesystem must support attaching capabilities to an executable
354 file, so that a process gains those capabilities when the file is
355 executed.
356 Before kernel 2.6.24, only the first two of these requirements are met;
358 since kernel 2.6.24, all three requirements are met.
359 Notes to kernel developers
361 When adding a new kernel feature that should be governed by a capabil‐
362 ity, consider the following points.
363 * The goal of capabilities is divide the power of superuser into
365 pieces, such that if a program that has one or more capabilities is
366 compromised, its power to do damage to the system would be less than
367 the same program running with root privilege.
368 * You have the choice of either creating a new capability for your new
370 feature, or associating the feature with one of the existing capa‐
371 bilities. In order to keep the set of capabilities to a manageable
372 size, the latter option is preferable, unless there are compelling
373 reasons to take the former option. (There is also a technical
374 limit: the size of capability sets is currently limited to 64 bits.)
375 * To determine which existing capability might best be associated with
377 your new feature, review the list of capabilities above in order to
378 find a "silo" into which your new feature best fits. One approach
379 to take is to determine if there are other features requiring capa‐
380 bilities that will always be used along with the new feature. If
381 the new feature is useless without these other features, you should
382 use the same capability as the other features.
383 * Don't choose CAP_SYS_ADMIN if you can possibly avoid it! A vast
385 proportion of existing capability checks are associated with this
386 capability (see the partial list above). It can plausibly be called
387 "the new root", since on the one hand, it confers a wide range of
388 powers, and on the other hand, its broad scope means that this is
389 the capability that is required by many privileged programs. Don't
390 make the problem worse. The only new features that should be asso‐
391 ciated with CAP_SYS_ADMIN are ones that closely match existing uses
392 in that silo.
393 * If you have determined that it really is necessary to create a new
395 capability for your feature, don't make or name it as a "single-use"
396 capability. Thus, for example, the addition of the highly specific
397 CAP_SYS_PACCT was probably a mistake. Instead, try to identify and
398 name your new capability as a broader silo into which other related
399 future use cases might fit.
400 Thread capability sets
402 Each thread has the following capability sets containing zero or more
403 of the above capabilities:
404 Permitted
406 This is a limiting superset for the effective capabilities that
407 the thread may assume. It is also a limiting superset for the
408 capabilities that may be added to the inheritable set by a
409 thread that does not have the CAP_SETPCAP capability in its ef‐
410 fective set.
411 If a thread drops a capability from its permitted set, it can
413 never reacquire that capability (unless it execve(2)s either a
414 set-user-ID-root program, or a program whose associated file ca‐
415 pabilities grant that capability).
416 Inheritable
418 This is a set of capabilities preserved across an execve(2).
419 Inheritable capabilities remain inheritable when executing any
420 program, and inheritable capabilities are added to the permitted
421 set when executing a program that has the corresponding bits set
422 in the file inheritable set.
423 Because inheritable capabilities are not generally preserved
425 across execve(2) when running as a non-root user, applications
426 that wish to run helper programs with elevated capabilities
427 should consider using ambient capabilities, described below.
428 Effective
430 This is the set of capabilities used by the kernel to perform
431 permission checks for the thread.
432 Bounding (per-thread since Linux 2.6.25)
434 The capability bounding set is a mechanism that can be used to
435 limit the capabilities that are gained during execve(2).
436 Since Linux 2.6.25, this is a per-thread capability set. In
438 older kernels, the capability bounding set was a system wide at‐
439 tribute shared by all threads on the system.
440 For more details on the capability bounding set, see below.
442 Ambient (since Linux 4.3)
444 This is a set of capabilities that are preserved across an ex‐
445 ecve(2) of a program that is not privileged. The ambient capa‐
446 bility set obeys the invariant that no capability can ever be
447 ambient if it is not both permitted and inheritable.
448 The ambient capability set can be directly modified using
450 prctl(2). Ambient capabilities are automatically lowered if ei‐
451 ther of the corresponding permitted or inheritable capabilities
452 is lowered.
453 Executing a program that changes UID or GID due to the set-user-
455 ID or set-group-ID bits or executing a program that has any file
456 capabilities set will clear the ambient set. Ambient capabili‐
457 ties are added to the permitted set and assigned to the effec‐
458 tive set when execve(2) is called. If ambient capabilities
459 cause a process's permitted and effective capabilities to in‐
460 crease during an execve(2), this does not trigger the secure-ex‐
461 ecution mode described in ld.so(8).
462 A child created via fork(2) inherits copies of its parent's capability
464 sets. See below for a discussion of the treatment of capabilities dur‐
465 ing execve(2).
466 Using capset(2), a thread may manipulate its own capability sets (see
468 below).
469 Since Linux 3.2, the file /proc/sys/kernel/cap_last_cap exposes the nu‐
471 merical value of the highest capability supported by the running ker‐
472 nel; this can be used to determine the highest bit that may be set in a
473 capability set.
474 File capabilities
476 Since kernel 2.6.24, the kernel supports associating capability sets
477 with an executable file using setcap(8). The file capability sets are
478 stored in an extended attribute (see setxattr(2) and xattr(7)) named
479 security.capability. Writing to this extended attribute requires the
480 CAP_SETFCAP capability. The file capability sets, in conjunction with
481 the capability sets of the thread, determine the capabilities of a
482 thread after an execve(2).
483 The three file capability sets are:
485 Permitted (formerly known as forced):
487 These capabilities are automatically permitted to the thread,
488 regardless of the thread's inheritable capabilities.
489 Inheritable (formerly known as allowed):
491 This set is ANDed with the thread's inheritable set to determine
492 which inheritable capabilities are enabled in the permitted set
493 of the thread after the execve(2).
494 Effective:
496 This is not a set, but rather just a single bit. If this bit is
497 set, then during an execve(2) all of the new permitted capabili‐
498 ties for the thread are also raised in the effective set. If
499 this bit is not set, then after an execve(2), none of the new
500 permitted capabilities is in the new effective set.
501 Enabling the file effective capability bit implies that any file
503 permitted or inheritable capability that causes a thread to ac‐
504 quire the corresponding permitted capability during an execve(2)
505 (see the transformation rules described below) will also acquire
506 that capability in its effective set. Therefore, when assigning
507 capabilities to a file (setcap(8), cap_set_file(3),
508 cap_set_fd(3)), if we specify the effective flag as being en‐
509 abled for any capability, then the effective flag must also be
510 specified as enabled for all other capabilities for which the
511 corresponding permitted or inheritable flags is enabled.
512 File capability extended attribute versioning
514 To allow extensibility, the kernel supports a scheme to encode a ver‐
515 sion number inside the security.capability extended attribute that is
516 used to implement file capabilities. These version numbers are inter‐
517 nal to the implementation, and not directly visible to user-space ap‐
518 plications. To date, the following versions are supported:
519 VFS_CAP_REVISION_1
521 This was the original file capability implementation, which sup‐
522 ported 32-bit masks for file capabilities.
523 VFS_CAP_REVISION_2 (since Linux 2.6.25)
525 This version allows for file capability masks that are 64 bits
526 in size, and was necessary as the number of supported capabili‐
527 ties grew beyond 32. The kernel transparently continues to sup‐
528 port the execution of files that have 32-bit version 1 capabil‐
529 ity masks, but when adding capabilities to files that did not
530 previously have capabilities, or modifying the capabilities of
531 existing files, it automatically uses the version 2 scheme (or
532 possibly the version 3 scheme, as described below).
533 VFS_CAP_REVISION_3 (since Linux 4.14)
535 Version 3 file capabilities are provided to support namespaced
536 file capabilities (described below).
537 As with version 2 file capabilities, version 3 capability masks
539 are 64 bits in size. But in addition, the root user ID of name‐
540 space is encoded in the security.capability extended attribute.
541 (A namespace's root user ID is the value that user ID 0 inside
542 that namespace maps to in the initial user namespace.)
543 Version 3 file capabilities are designed to coexist with version
545 2 capabilities; that is, on a modern Linux system, there may be
546 some files with version 2 capabilities while others have version
547 3 capabilities.
548 Before Linux 4.14, the only kind of file capability extended attribute
550 that could be attached to a file was a VFS_CAP_REVISION_2 attribute.
551 Since Linux 4.14, the version of the security.capability extended at‐
552 tribute that is attached to a file depends on the circumstances in
553 which the attribute was created.
554 Starting with Linux 4.14, a security.capability extended attribute is
556 automatically created as (or converted to) a version 3 (VFS_CAP_REVI‐
557 SION_3) attribute if both of the following are true:
558 (1) The thread writing the attribute resides in a noninitial user name‐
560 space. (More precisely: the thread resides in a user namespace
561 other than the one from which the underlying filesystem was
562 mounted.)
563 (2) The thread has the CAP_SETFCAP capability over the file inode,
565 meaning that (a) the thread has the CAP_SETFCAP capability in its
566 own user namespace; and (b) the UID and GID of the file inode have
567 mappings in the writer's user namespace.
568 When a VFS_CAP_REVISION_3 security.capability extended attribute is
570 created, the root user ID of the creating thread's user namespace is
571 saved in the extended attribute.
572 By contrast, creating or modifying a security.capability extended at‐
574 tribute from a privileged (CAP_SETFCAP) thread that resides in the
575 namespace where the underlying filesystem was mounted (this normally
576 means the initial user namespace) automatically results in the creation
577 of a version 2 (VFS_CAP_REVISION_2) attribute.
578 Note that the creation of a version 3 security.capability extended at‐
580 tribute is automatic. That is to say, when a user-space application
581 writes (setxattr(2)) a security.capability attribute in the version 2
582 format, the kernel will automatically create a version 3 attribute if
583 the attribute is created in the circumstances described above. Corre‐
584 spondingly, when a version 3 security.capability attribute is retrieved
585 (getxattr(2)) by a process that resides inside a user namespace that
586 was created by the root user ID (or a descendant of that user name‐
587 space), the returned attribute is (automatically) simplified to appear
588 as a version 2 attribute (i.e., the returned value is the size of a
589 version 2 attribute and does not include the root user ID). These au‐
590 tomatic translations mean that no changes are required to user-space
591 tools (e.g., setcap(1) and getcap(1)) in order for those tools to be
592 used to create and retrieve version 3 security.capability attributes.
593 Note that a file can have either a version 2 or a version 3 secu‐
595 rity.capability extended attribute associated with it, but not both:
596 creation or modification of the security.capability extended attribute
597 will automatically modify the version according to the circumstances in
598 which the extended attribute is created or modified.
599 Transformation of capabilities during execve()
601 During an execve(2), the kernel calculates the new capabilities of the
602 process using the following algorithm:
603 P'(ambient) = (file is privileged) ? 0 : P(ambient)
605 P'(permitted) = (P(inheritable) & F(inheritable)) |
607 (F(permitted) & P(bounding)) | P'(ambient)
608 P'(effective) = F(effective) ? P'(permitted) : P'(ambient)
610 P'(inheritable) = P(inheritable) [i.e., unchanged]
612 P'(bounding) = P(bounding) [i.e., unchanged]
614 where:
616 P() denotes the value of a thread capability set before the ex‐
618 ecve(2)
619 P'() denotes the value of a thread capability set after the ex‐
621 ecve(2)
622 F() denotes a file capability set
624 Note the following details relating to the above capability transforma‐
626 tion rules:
627 * The ambient capability set is present only since Linux 4.3. When
629 determining the transformation of the ambient set during execve(2),
630 a privileged file is one that has capabilities or has the set-user-
631 ID or set-group-ID bit set.
632 * Prior to Linux 2.6.25, the bounding set was a system-wide attribute
634 shared by all threads. That system-wide value was employed to cal‐
635 culate the new permitted set during execve(2) in the same manner as
636 shown above for P(bounding).
637 Note: during the capability transitions described above, file capabili‐
639 ties may be ignored (treated as empty) for the same reasons that the
640 set-user-ID and set-group-ID bits are ignored; see execve(2). File ca‐
641 pabilities are similarly ignored if the kernel was booted with the
642 no_file_caps option.
643 Note: according to the rules above, if a process with nonzero user IDs
645 performs an execve(2) then any capabilities that are present in its
646 permitted and effective sets will be cleared. For the treatment of ca‐
647 pabilities when a process with a user ID of zero performs an execve(2),
648 see below under Capabilities and execution of programs by root.
649 Safety checking for capability-dumb binaries
651 A capability-dumb binary is an application that has been marked to have
652 file capabilities, but has not been converted to use the libcap(3) API
653 to manipulate its capabilities. (In other words, this is a traditional
654 set-user-ID-root program that has been switched to use file capabili‐
655 ties, but whose code has not been modified to understand capabilities.)
656 For such applications, the effective capability bit is set on the file,
657 so that the file permitted capabilities are automatically enabled in
658 the process effective set when executing the file. The kernel recog‐
659 nizes a file which has the effective capability bit set as capability-
660 dumb for the purpose of the check described here.
661 When executing a capability-dumb binary, the kernel checks if the
663 process obtained all permitted capabilities that were specified in the
664 file permitted set, after the capability transformations described
665 above have been performed. (The typical reason why this might not oc‐
666 cur is that the capability bounding set masked out some of the capabil‐
667 ities in the file permitted set.) If the process did not obtain the
668 full set of file permitted capabilities, then execve(2) fails with the
669 error EPERM. This prevents possible security risks that could arise
670 when a capability-dumb application is executed with less privilege that
671 it needs. Note that, by definition, the application could not itself
672 recognize this problem, since it does not employ the libcap(3) API.
673 Capabilities and execution of programs by root
675 In order to mirror traditional UNIX semantics, the kernel performs spe‐
676 cial treatment of file capabilities when a process with UID 0 (root)
677 executes a program and when a set-user-ID-root program is executed.
678 After having performed any changes to the process effective ID that
680 were triggered by the set-user-ID mode bit of the binary—e.g., switch‐
681 ing the effective user ID to 0 (root) because a set-user-ID-root pro‐
682 gram was executed—the kernel calculates the file capability sets as
683 follows:
684 1. If the real or effective user ID of the process is 0 (root), then
686 the file inheritable and permitted sets are ignored; instead they
687 are notionally considered to be all ones (i.e., all capabilities en‐
688 abled). (There is one exception to this behavior, described below
689 in Set-user-ID-root programs that have file capabilities.)
690 2. If the effective user ID of the process is 0 (root) or the file ef‐
692 fective bit is in fact enabled, then the file effective bit is no‐
693 tionally defined to be one (enabled).
694 These notional values for the file's capability sets are then used as
696 described above to calculate the transformation of the process's capa‐
697 bilities during execve(2).
698 Thus, when a process with nonzero UIDs execve(2)s a set-user-ID-root
700 program that does not have capabilities attached, or when a process
701 whose real and effective UIDs are zero execve(2)s a program, the calcu‐
702 lation of the process's new permitted capabilities simplifies to:
703 P'(permitted) = P(inheritable) | P(bounding)
705 P'(effective) = P'(permitted)
707 Consequently, the process gains all capabilities in its permitted and
709 effective capability sets, except those masked out by the capability
710 bounding set. (In the calculation of P'(permitted), the P'(ambient)
711 term can be simplified away because it is by definition a proper subset
712 of P(inheritable).)
713 The special treatments of user ID 0 (root) described in this subsection
715 can be disabled using the securebits mechanism described below.
716 Set-user-ID-root programs that have file capabilities
718 There is one exception to the behavior described under Capabilities and
719 execution of programs by root. If (a) the binary that is being exe‐
720 cuted has capabilities attached and (b) the real user ID of the process
721 is not 0 (root) and (c) the effective user ID of the process is 0
722 (root), then the file capability bits are honored (i.e., they are not
723 notionally considered to be all ones). The usual way in which this
724 situation can arise is when executing a set-UID-root program that also
725 has file capabilities. When such a program is executed, the process
726 gains just the capabilities granted by the program (i.e., not all capa‐
727 bilities, as would occur when executing a set-user-ID-root program that
728 does not have any associated file capabilities).
729 Note that one can assign empty capability sets to a program file, and
731 thus it is possible to create a set-user-ID-root program that changes
732 the effective and saved set-user-ID of the process that executes the
733 program to 0, but confers no capabilities to that process.
734 Capability bounding set
736 The capability bounding set is a security mechanism that can be used to
737 limit the capabilities that can be gained during an execve(2). The
738 bounding set is used in the following ways:
739 * During an execve(2), the capability bounding set is ANDed with the
741 file permitted capability set, and the result of this operation is
742 assigned to the thread's permitted capability set. The capability
743 bounding set thus places a limit on the permitted capabilities that
744 may be granted by an executable file.
745 * (Since Linux 2.6.25) The capability bounding set acts as a limiting
747 superset for the capabilities that a thread can add to its inherita‐
748 ble set using capset(2). This means that if a capability is not in
749 the bounding set, then a thread can't add this capability to its in‐
750 heritable set, even if it was in its permitted capabilities, and
751 thereby cannot have this capability preserved in its permitted set
752 when it execve(2)s a file that has the capability in its inheritable
753 set.
754 Note that the bounding set masks the file permitted capabilities, but
756 not the inheritable capabilities. If a thread maintains a capability
757 in its inheritable set that is not in its bounding set, then it can
758 still gain that capability in its permitted set by executing a file
759 that has the capability in its inheritable set.
760 Depending on the kernel version, the capability bounding set is either
762 a system-wide attribute, or a per-process attribute.
763 Capability bounding set from Linux 2.6.25 onward
765 From Linux 2.6.25, the capability bounding set is a per-thread attri‐
767 bute. (The system-wide capability bounding set described below no
768 longer exists.)
769 The bounding set is inherited at fork(2) from the thread's parent, and
771 is preserved across an execve(2).
772 A thread may remove capabilities from its capability bounding set using
774 the prctl(2) PR_CAPBSET_DROP operation, provided it has the CAP_SETPCAP
775 capability. Once a capability has been dropped from the bounding set,
776 it cannot be restored to that set. A thread can determine if a capa‐
777 bility is in its bounding set using the prctl(2) PR_CAPBSET_READ opera‐
778 tion.
779 Removing capabilities from the bounding set is supported only if file
781 capabilities are compiled into the kernel. In kernels before Linux
782 2.6.33, file capabilities were an optional feature configurable via the
783 CONFIG_SECURITY_FILE_CAPABILITIES option. Since Linux 2.6.33, the con‐
784 figuration option has been removed and file capabilities are always
785 part of the kernel. When file capabilities are compiled into the ker‐
786 nel, the init process (the ancestor of all processes) begins with a
787 full bounding set. If file capabilities are not compiled into the ker‐
788 nel, then init begins with a full bounding set minus CAP_SETPCAP, be‐
789 cause this capability has a different meaning when there are no file
790 capabilities.
791 Removing a capability from the bounding set does not remove it from the
793 thread's inheritable set. However it does prevent the capability from
794 being added back into the thread's inheritable set in the future.
795 Capability bounding set prior to Linux 2.6.25
797 In kernels before 2.6.25, the capability bounding set is a system-wide
799 attribute that affects all threads on the system. The bounding set is
800 accessible via the file /proc/sys/kernel/cap-bound. (Confusingly, this
801 bit mask parameter is expressed as a signed decimal number in
802 /proc/sys/kernel/cap-bound.)
803 Only the init process may set capabilities in the capability bounding
805 set; other than that, the superuser (more precisely: a process with the
806 CAP_SYS_MODULE capability) may only clear capabilities from this set.
807 On a standard system the capability bounding set always masks out the
809 CAP_SETPCAP capability. To remove this restriction (dangerous!), mod‐
810 ify the definition of CAP_INIT_EFF_SET in include/linux/capability.h
811 and rebuild the kernel.
812 The system-wide capability bounding set feature was added to Linux
814 starting with kernel version 2.2.11.
815 Effect of user ID changes on capabilities
817 To preserve the traditional semantics for transitions between 0 and
818 nonzero user IDs, the kernel makes the following changes to a thread's
819 capability sets on changes to the thread's real, effective, saved set,
820 and filesystem user IDs (using setuid(2), setresuid(2), or similar):
821 1. If one or more of the real, effective, or saved set user IDs was
823 previously 0, and as a result of the UID changes all of these IDs
824 have a nonzero value, then all capabilities are cleared from the
825 permitted, effective, and ambient capability sets.
826 2. If the effective user ID is changed from 0 to nonzero, then all ca‐
828 pabilities are cleared from the effective set.
829 3. If the effective user ID is changed from nonzero to 0, then the per‐
831 mitted set is copied to the effective set.
832 4. If the filesystem user ID is changed from 0 to nonzero (see setf‐
834 suid(2)), then the following capabilities are cleared from the ef‐
835 fective set: CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
836 CAP_FOWNER, CAP_FSETID, CAP_LINUX_IMMUTABLE (since Linux 2.6.30),
837 CAP_MAC_OVERRIDE, and CAP_MKNOD (since Linux 2.6.30). If the
838 filesystem UID is changed from nonzero to 0, then any of these capa‐
839 bilities that are enabled in the permitted set are enabled in the
840 effective set.
841 If a thread that has a 0 value for one or more of its user IDs wants to
843 prevent its permitted capability set being cleared when it resets all
844 of its user IDs to nonzero values, it can do so using the
845 SECBIT_KEEP_CAPS securebits flag described below.
846 Programmatically adjusting capability sets
848 A thread can retrieve and change its permitted, effective, and inheri‐
849 table capability sets using the capget(2) and capset(2) system calls.
850 However, the use of cap_get_proc(3) and cap_set_proc(3), both provided
851 in the libcap package, is preferred for this purpose. The following
852 rules govern changes to the thread capability sets:
853 1. If the caller does not have the CAP_SETPCAP capability, the new in‐
855 heritable set must be a subset of the combination of the existing
856 inheritable and permitted sets.
857 2. (Since Linux 2.6.25) The new inheritable set must be a subset of the
859 combination of the existing inheritable set and the capability
860 bounding set.
861 3. The new permitted set must be a subset of the existing permitted set
863 (i.e., it is not possible to acquire permitted capabilities that the
864 thread does not currently have).
865 4. The new effective set must be a subset of the new permitted set.
867 The securebits flags: establishing a capabilities-only environment
869 Starting with kernel 2.6.26, and with a kernel in which file capabili‐
870 ties are enabled, Linux implements a set of per-thread securebits flags
871 that can be used to disable special handling of capabilities for UID 0
872 (root). These flags are as follows:
873 SECBIT_KEEP_CAPS
875 Setting this flag allows a thread that has one or more 0 UIDs to
876 retain capabilities in its permitted set when it switches all of
877 its UIDs to nonzero values. If this flag is not set, then such
878 a UID switch causes the thread to lose all permitted capabili‐
879 ties. This flag is always cleared on an execve(2).
880 Note that even with the SECBIT_KEEP_CAPS flag set, the effective
882 capabilities of a thread are cleared when it switches its effec‐
883 tive UID to a nonzero value. However, if the thread has set
884 this flag and its effective UID is already nonzero, and the
885 thread subsequently switches all other UIDs to nonzero values,
886 then the effective capabilities will not be cleared.
887 The setting of the SECBIT_KEEP_CAPS flag is ignored if the
889 SECBIT_NO_SETUID_FIXUP flag is set. (The latter flag provides a
890 superset of the effect of the former flag.)
891 This flag provides the same functionality as the older prctl(2)
893 PR_SET_KEEPCAPS operation.
894 SECBIT_NO_SETUID_FIXUP
896 Setting this flag stops the kernel from adjusting the process's
897 permitted, effective, and ambient capability sets when the
898 thread's effective and filesystem UIDs are switched between zero
899 and nonzero values. (See the subsection Effect of user ID
900 changes on capabilities.)
901 SECBIT_NOROOT
903 If this bit is set, then the kernel does not grant capabilities
904 when a set-user-ID-root program is executed, or when a process
905 with an effective or real UID of 0 calls execve(2). (See the
906 subsection Capabilities and execution of programs by root.)
907 SECBIT_NO_CAP_AMBIENT_RAISE
909 Setting this flag disallows raising ambient capabilities via the
910 prctl(2) PR_CAP_AMBIENT_RAISE operation.
911 Each of the above "base" flags has a companion "locked" flag. Setting
913 any of the "locked" flags is irreversible, and has the effect of pre‐
914 venting further changes to the corresponding "base" flag. The locked
915 flags are: SECBIT_KEEP_CAPS_LOCKED, SECBIT_NO_SETUID_FIXUP_LOCKED,
916 SECBIT_NOROOT_LOCKED, and SECBIT_NO_CAP_AMBIENT_RAISE_LOCKED.
917 The securebits flags can be modified and retrieved using the prctl(2)
919 PR_SET_SECUREBITS and PR_GET_SECUREBITS operations. The CAP_SETPCAP
920 capability is required to modify the flags. Note that the SECBIT_*
921 constants are available only after including the <linux/securebits.h>
922 header file.
923 The securebits flags are inherited by child processes. During an ex‐
925 ecve(2), all of the flags are preserved, except SECBIT_KEEP_CAPS which
926 is always cleared.
927 An application can use the following call to lock itself, and all of
929 its descendants, into an environment where the only way of gaining ca‐
930 pabilities is by executing a program with associated file capabilities:
931 prctl(PR_SET_SECUREBITS,
933 /* SECBIT_KEEP_CAPS off */
934 SECBIT_KEEP_CAPS_LOCKED |
935 SECBIT_NO_SETUID_FIXUP |
936 SECBIT_NO_SETUID_FIXUP_LOCKED |
937 SECBIT_NOROOT |
938 SECBIT_NOROOT_LOCKED);
939 /* Setting/locking SECBIT_NO_CAP_AMBIENT_RAISE
940 is not required */
941 Per-user-namespace "set-user-ID-root" programs
943 A set-user-ID program whose UID matches the UID that created a user
944 namespace will confer capabilities in the process's permitted and ef‐
945 fective sets when executed by any process inside that namespace or any
946 descendant user namespace.
947 The rules about the transformation of the process's capabilities during
949 the execve(2) are exactly as described in the subsections Transforma‐
950 tion of capabilities during execve() and Capabilities and execution of
951 programs by root, with the difference that, in the latter subsection,
952 "root" is the UID of the creator of the user namespace.
953 Namespaced file capabilities
955 Traditional (i.e., version 2) file capabilities associate only a set of
956 capability masks with a binary executable file. When a process exe‐
957 cutes a binary with such capabilities, it gains the associated capabil‐
958 ities (within its user namespace) as per the rules described above in
959 "Transformation of capabilities during execve()".
960 Because version 2 file capabilities confer capabilities to the execut‐
962 ing process regardless of which user namespace it resides in, only
963 privileged processes are permitted to associate capabilities with a
964 file. Here, "privileged" means a process that has the CAP_SETFCAP ca‐
965 pability in the user namespace where the filesystem was mounted (nor‐
966 mally the initial user namespace). This limitation renders file capa‐
967 bilities useless for certain use cases. For example, in user-names‐
968 paced containers, it can be desirable to be able to create a binary
969 that confers capabilities only to processes executed inside that con‐
970 tainer, but not to processes that are executed outside the container.
971 Linux 4.14 added so-called namespaced file capabilities to support such
973 use cases. Namespaced file capabilities are recorded as version 3
974 (i.e., VFS_CAP_REVISION_3) security.capability extended attributes.
975 Such an attribute is automatically created in the circumstances de‐
976 scribed above under "File capability extended attribute versioning".
977 When a version 3 security.capability extended attribute is created, the
978 kernel records not just the capability masks in the extended attribute,
979 but also the namespace root user ID.
980 As with a binary that has VFS_CAP_REVISION_2 file capabilities, a bi‐
982 nary with VFS_CAP_REVISION_3 file capabilities confers capabilities to
983 a process during execve(). However, capabilities are conferred only if
984 the binary is executed by a process that resides in a user namespace
985 whose UID 0 maps to the root user ID that is saved in the extended at‐
986 tribute, or when executed by a process that resides in a descendant of
987 such a namespace.
988 Interaction with user namespaces
990 For further information on the interaction of capabilities and user
991 namespaces, see user_namespaces(7).
992
994 No standards govern capabilities, but the Linux capability implementa‐
995 tion is based on the withdrawn POSIX.1e draft standard; see
996 ⟨https://archive.org/details/posix_1003.1e-990310⟩.
997
999 When attempting to strace(1) binaries that have capabilities (or set-
1000 user-ID-root binaries), you may find the -u <username> option useful.
1001 Something like:
1002 $ sudo strace -o trace.log -u ceci ./myprivprog
1004 From kernel 2.5.27 to kernel 2.6.26, capabilities were an optional ker‐
1006 nel component, and could be enabled/disabled via the CONFIG_SECU‐
1007 RITY_CAPABILITIES kernel configuration option.
1008 The /proc/[pid]/task/TID/status file can be used to view the capability
1010 sets of a thread. The /proc/[pid]/status file shows the capability
1011 sets of a process's main thread. Before Linux 3.8, nonexistent capa‐
1012 bilities were shown as being enabled (1) in these sets. Since Linux
1013 3.8, all nonexistent capabilities (above CAP_LAST_CAP) are shown as
1014 disabled (0).
1015 The libcap package provides a suite of routines for setting and getting
1017 capabilities that is more comfortable and less likely to change than
1018 the interface provided by capset(2) and capget(2). This package also
1019 provides the setcap(8) and getcap(8) programs. It can be found at
1020 ⟨https://git.kernel.org/pub/scm/libs/libcap/libcap.git/refs/⟩.
1021 Before kernel 2.6.24, and from kernel 2.6.24 to kernel 2.6.32 if file
1023 capabilities are not enabled, a thread with the CAP_SETPCAP capability
1024 can manipulate the capabilities of threads other than itself. However,
1025 this is only theoretically possible, since no thread ever has CAP_SETP‐
1026 CAP in either of these cases:
1027 * In the pre-2.6.25 implementation the system-wide capability bounding
1029 set, /proc/sys/kernel/cap-bound, always masks out the CAP_SETPCAP ca‐
1030 pability, and this can not be changed without modifying the kernel
1031 source and rebuilding the kernel.
1032 * If file capabilities are disabled (i.e., the kernel CONFIG_SECU‐
1034 RITY_FILE_CAPABILITIES option is disabled), then init starts out with
1035 the CAP_SETPCAP capability removed from its per-process bounding set,
1036 and that bounding set is inherited by all other processes created on
1037 the system.
1038
1040 capsh(1), setpriv(1), prctl(2), setfsuid(2), cap_clear(3),
1041 cap_copy_ext(3), cap_from_text(3), cap_get_file(3), cap_get_proc(3),
1042 cap_init(3), capgetp(3), capsetp(3), libcap(3), proc(5), creden‐
1043 tials(7), pthreads(7), user_namespaces(7), captest(8), filecap(8), get‐
1044 cap(8), getpcaps(8), netcap(8), pscap(8), setcap(8)
1045 include/linux/capability.h in the Linux kernel source tree
1047
1049 This page is part of release 5.12 of the Linux man-pages project. A
1050 description of the project, information about reporting bugs, and the
1051 latest version of this page, can be found at
1052 https://www.kernel.org/doc/man-pages/.
1053Linux 2021-03-22 CAPABILITIES(7)