Debian Codegraph @

upstream/debian-unstable/man7/capabilities.7

raw
1 .\" Copyright 2002, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH Capabilities 7 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 capabilities \- overview of Linux capabilities
9 .SH DESCRIPTION
10 For the purpose of performing permission checks,
11 traditional UNIX implementations distinguish two categories of processes:
12 .I privileged
13 processes (whose effective user ID is 0, referred to as superuser or root),
14 and
15 .I unprivileged
16 processes (whose effective UID is nonzero).
17 Privileged processes bypass all kernel permission checks,
18 while unprivileged processes are subject to full permission
19 checking based on the process's credentials
20 (usually: effective UID, effective GID, and supplementary group list).
21 .P
22 Starting with Linux 2.2, Linux divides the privileges traditionally
23 associated with superuser into distinct units, known as
24 .IR capabilities ,
25 which can be independently enabled and disabled.
26 Capabilities are a per-thread attribute.
27 .\"
28 .SS Capabilities list
29 The following list shows the capabilities implemented on Linux,
30 and the operations or behaviors that each capability permits:
31 .TP
32 .BR CAP_AUDIT_CONTROL " (since Linux 2.6.11)"
33 Enable and disable kernel auditing;
34 change auditing filter rules;
35 retrieve auditing status and filtering rules.
36 .TP
37 .BR CAP_AUDIT_READ " (since Linux 3.16)"
38 .\" commit a29b694aa1739f9d76538e34ae25524f9c549d59
39 .\" commit 3a101b8de0d39403b2c7e5c23fd0b005668acf48
40 Allow reading the audit log via a multicast netlink socket.
41 .TP
42 .BR CAP_AUDIT_WRITE " (since Linux 2.6.11)"
43 Write records to kernel auditing log.
44 .\" FIXME Add FAN_ENABLE_AUDIT
45 .TP
46 .BR CAP_BLOCK_SUSPEND " (since Linux 3.5)"
47 Employ features that can block system suspend
48 .RB ( epoll (7)
49 .BR EPOLLWAKEUP ,
50 .IR /proc/sys/wake_lock ).
51 .TP
52 .BR CAP_BPF " (since Linux 5.8)"
53 Employ privileged BPF operations;
54 see
55 .BR bpf (2)
56 and
57 .BR bpf\-helpers (7).
58 .IP
59 This capability was added in Linux 5.8 to separate out
60 BPF functionality from the overloaded
61 .B CAP_SYS_ADMIN
62 capability.
63 .TP
64 .BR CAP_CHECKPOINT_RESTORE " (since Linux 5.9)"
65 .\" commit 124ea650d3072b005457faed69909221c2905a1f
66 .PD 0
67 .RS
68 .IP \[bu] 3
69 Update
70 .I /proc/sys/kernel/ns_last_pid
71 (see
72 .BR pid_namespaces (7));
73 .IP \[bu]
74 employ the
75 .I set_tid
76 feature of
77 .BR clone3 (2);
78 .\" FIXME There is also some use case relating to
79 .\" prctl_set_mm_exe_file(); in the 5.9 sources, see
80 .\" prctl_set_mm_map().
81 .IP \[bu]
82 read the contents of the symbolic links in
83 .IR /proc/ pid /map_files
84 for other processes.
85 .RE
86 .PD
87 .IP
88 This capability was added in Linux 5.9 to separate out
89 checkpoint/restore functionality from the overloaded
90 .B CAP_SYS_ADMIN
91 capability.
92 .TP
93 .B CAP_CHOWN
94 Make arbitrary changes to file UIDs and GIDs (see
95 .BR chown (2)).
96 .TP
97 .B CAP_DAC_OVERRIDE
98 Bypass file read, write, and execute permission checks.
99 (DAC is an abbreviation of "discretionary access control".)
100 .TP
101 .B CAP_DAC_READ_SEARCH
102 .PD 0
103 .RS
104 .IP \[bu] 3
105 Bypass file read permission checks and
106 directory read and execute permission checks;
107 .IP \[bu]
108 invoke
109 .BR open_by_handle_at (2);
110 .IP \[bu]
111 use the
112 .BR linkat (2)
113 .B AT_EMPTY_PATH
114 flag to create a link to a file referred to by a file descriptor.
115 .RE
116 .PD
117 .TP
118 .B CAP_FOWNER
119 .PD 0
120 .RS
121 .IP \[bu] 3
122 Bypass permission checks on operations that normally
123 require the filesystem UID of the process to match the UID of
124 the file (e.g.,
125 .BR chmod (2),
126 .BR utime (2)),
127 excluding those operations covered by
128 .B CAP_DAC_OVERRIDE
129 and
130 .BR CAP_DAC_READ_SEARCH ;
131 .IP \[bu]
132 set inode flags (see
133 .BR FS_IOC_SETFLAGS (2const))
134 on arbitrary files;
135 .IP \[bu]
136 set Access Control Lists (ACLs) on arbitrary files;
137 .IP \[bu]
138 ignore directory sticky bit on file deletion;
139 .IP \[bu]
140 modify
141 .I user
142 extended attributes on sticky directory owned by any user;
143 .IP \[bu]
144 specify
145 .B O_NOATIME
146 for arbitrary files in
147 .BR open (2)
148 and
149 .BR fcntl (2).
150 .RE
151 .PD
152 .TP
153 .B CAP_FSETID
154 .PD 0
155 .RS
156 .IP \[bu] 3
157 Don't clear set-user-ID and set-group-ID mode
158 bits when a file is modified;
159 .IP \[bu]
160 set the set-group-ID bit for a file whose GID does not match
161 the filesystem or any of the supplementary GIDs of the calling process.
162 .RE
163 .PD
164 .TP
165 .B CAP_IPC_LOCK
166 .\" FIXME . As at Linux 3.2, there are some strange uses of this capability
167 .\" in other places; they probably should be replaced with something else.
168 .PD 0
169 .RS
170 .IP \[bu] 3
171 Lock memory
172 .RB ( mlock (2),
173 .BR mlockall (2),
174 .BR mmap (2),
175 .BR shmctl (2));
176 .IP \[bu]
177 Allocate memory using huge pages
178 .RB ( memfd_create (2),
179 .BR mmap (2),
180 .BR shmctl (2)).
181 .RE
182 .PD
183 .TP
184 .B CAP_IPC_OWNER
185 Bypass permission checks for operations on System V IPC objects.
186 .TP
187 .B CAP_KILL
188 Bypass permission checks for sending signals (see
189 .BR kill (2)).
190 This includes use of the
191 .BR ioctl (2)
192 .B KDSIGACCEPT
193 operation.
194 .\" FIXME . CAP_KILL also has an effect for threads + setting child
195 .\" termination signal to other than SIGCHLD: without this
196 .\" capability, the termination signal reverts to SIGCHLD
197 .\" if the child does an exec(). What is the rationale
198 .\" for this?
199 .TP
200 .BR CAP_LEASE " (since Linux 2.4)"
201 Establish leases on arbitrary files (see
202 .BR fcntl (2)).
203 .TP
204 .B CAP_LINUX_IMMUTABLE
205 Set the
206 .B FS_APPEND_FL
207 and
208 .B FS_IMMUTABLE_FL
209 inode flags (see
210 .BR FS_IOC_SETFLAGS (2const)).
211 .TP
212 .BR CAP_MAC_ADMIN " (since Linux 2.6.25)"
213 Allow MAC configuration or state changes.
214 Implemented for the Smack Linux Security Module (LSM).
215 .TP
216 .BR CAP_MAC_OVERRIDE " (since Linux 2.6.25)"
217 Override Mandatory Access Control (MAC).
218 Implemented for the Smack LSM.
219 .TP
220 .BR CAP_MKNOD " (since Linux 2.4)"
221 Create special files using
222 .BR mknod (2).
223 .TP
224 .B CAP_NET_ADMIN
225 Perform various network-related operations:
226 .PD 0
227 .RS
228 .IP \[bu] 3
229 interface configuration;
230 .IP \[bu]
231 administration of IP firewall, masquerading, and accounting;
232 .IP \[bu]
233 modify routing tables;
234 .IP \[bu]
235 bind to any address for transparent proxying;
236 .IP \[bu]
237 set type-of-service (TOS);
238 .IP \[bu]
239 clear driver statistics;
240 .IP \[bu]
241 set promiscuous mode;
242 .IP \[bu]
243 enabling multicasting;
244 .IP \[bu]
245 use
246 .BR setsockopt (2)
247 to set the following socket options:
248 .BR SO_DEBUG ,
249 .BR SO_MARK ,
250 .B SO_PRIORITY
251 (for a priority outside the range 0 to 6),
252 .BR SO_RCVBUFFORCE ,
253 and
254 .BR SO_SNDBUFFORCE .
255 .RE
256 .PD
257 .TP
258 .B CAP_NET_BIND_SERVICE
259 Bind a socket to Internet domain privileged ports
260 (port numbers less than 1024).
261 .TP
262 .B CAP_NET_BROADCAST
263 (Unused) Make socket broadcasts, and listen to multicasts.
264 .\" FIXME Since Linux 4.2, there are use cases for netlink sockets
265 .\" commit 59324cf35aba5336b611074028777838a963d03b
266 .TP
267 .B CAP_NET_RAW
268 .PD 0
269 .RS
270 .IP \[bu] 3
271 Use RAW and PACKET sockets;
272 .IP \[bu]
273 bind to any address for transparent proxying.
274 .RE
275 .PD
276 .\" Also various IP options and setsockopt(SO_BINDTODEVICE)
277 .TP
278 .BR CAP_PERFMON " (since Linux 5.8)"
279 Employ various performance-monitoring mechanisms, including:
280 .RS
281 .IP \[bu] 3
282 .PD 0
283 call
284 .BR perf_event_open (2);
285 .IP \[bu]
286 employ various BPF operations that have performance implications.
287 .RE
288 .PD
289 .IP
290 This capability was added in Linux 5.8 to separate out
291 performance monitoring functionality from the overloaded
292 .B CAP_SYS_ADMIN
293 capability.
294 See also the kernel source file
295 .IR Documentation/admin\-guide/perf\-security.rst .
296 .TP
297 .B CAP_SETGID
298 .RS
299 .PD 0
300 .IP \[bu] 3
301 Make arbitrary manipulations of process GIDs and supplementary GID list;
302 .IP \[bu]
303 forge GID when passing socket credentials via UNIX domain sockets;
304 .IP \[bu]
305 write a group ID mapping in a user namespace (see
306 .BR user_namespaces (7)).
307 .PD
308 .RE
309 .TP
310 .BR CAP_SETFCAP " (since Linux 2.6.24)"
311 Set arbitrary capabilities on a file.
312 .IP
313 .\" commit db2e718a47984b9d71ed890eb2ea36ecf150de18
314 Since Linux 5.12,
315 this capability is also needed
316 to map user ID 0 in a new user namespace;
317 see
318 .BR user_namespaces (7)
319 for details.
320 .TP
321 .B CAP_SETPCAP
322 If file capabilities are supported (i.e., since Linux 2.6.24):
323 add any capability from the calling thread's bounding set
324 to its inheritable set;
325 drop capabilities from the bounding set (via
326 .BR prctl (2)
327 .BR PR_CAPBSET_DROP );
328 make changes to the
329 .I securebits
330 flags.
331 .IP
332 If file capabilities are not supported (i.e., before Linux 2.6.24):
333 grant or remove any capability in the
334 caller's permitted capability set to or from any other process.
335 (This property of
336 .B CAP_SETPCAP
337 is not available when the kernel is configured to support
338 file capabilities, since
339 .B CAP_SETPCAP
340 has entirely different semantics for such kernels.)
341 .TP
342 .B CAP_SETUID
343 .RS
344 .PD 0
345 .IP \[bu] 3
346 Make arbitrary manipulations of process UIDs
347 .RB ( setuid (2),
348 .BR setreuid (2),
349 .BR setresuid (2),
350 .BR setfsuid (2));
351 .IP \[bu]
352 forge UID when passing socket credentials via UNIX domain sockets;
353 .IP \[bu]
354 write a user ID mapping in a user namespace (see
355 .BR user_namespaces (7)).
356 .PD
357 .RE
358 .\" FIXME CAP_SETUID also an effect in exec(); document this.
359 .TP
360 .B CAP_SYS_ADMIN
361 .IR Note :
362 this capability is overloaded;
363 see
364 .I Notes to kernel developers
365 below.
366 .IP
367 .PD 0
368 .RS
369 .IP \[bu] 3
370 Perform a range of system administration operations including:
371 .BR quotactl (2),
372 .BR mount (2),
373 .BR umount (2),
374 .BR pivot_root (2),
375 .BR swapon (2),
376 .BR swapoff (2),
377 .BR sethostname (2),
378 and
379 .BR setdomainname (2);
380 .IP \[bu]
381 perform privileged
382 .BR syslog (2)
383 operations (since Linux 2.6.37,
384 .B CAP_SYSLOG
385 should be used to permit such operations);
386 .IP \[bu]
387 perform
388 .B VM86_REQUEST_IRQ
389 .BR vm86 (2)
390 command;
391 .IP \[bu]
392 access the same checkpoint/restore functionality that is governed by
393 .B CAP_CHECKPOINT_RESTORE
394 (but the latter, weaker capability is preferred for accessing
395 that functionality).
396 .IP \[bu]
397 perform the same BPF operations as are governed by
398 .B CAP_BPF
399 (but the latter, weaker capability is preferred for accessing
400 that functionality).
401 .IP \[bu]
402 employ the same performance monitoring mechanisms as are governed by
403 .B CAP_PERFMON
404 (but the latter, weaker capability is preferred for accessing
405 that functionality).
406 .IP \[bu]
407 perform
408 .B IPC_SET
409 and
410 .B IPC_RMID
411 operations on arbitrary System V IPC objects;
412 .IP \[bu]
413 override
414 .B RLIMIT_NPROC
415 resource limit;
416 .IP \[bu]
417 perform operations on
418 .I trusted
419 and
420 .I security
421 extended attributes (see
422 .BR xattr (7));
423 .IP \[bu]
424 use
425 .BR lookup_dcookie (2);
426 .IP \[bu]
427 use
428 .BR ioprio_set (2)
429 to assign
430 .B IOPRIO_CLASS_RT
431 and (before Linux 2.6.25)
432 .B IOPRIO_CLASS_IDLE
433 I/O scheduling classes;
434 .IP \[bu]
435 forge PID when passing socket credentials via UNIX domain sockets;
436 .IP \[bu]
437 exceed
438 .IR /proc/sys/fs/file\-max ,
439 the system-wide limit on the number of open files,
440 in system calls that open files (e.g.,
441 .BR accept (2),
442 .BR execve (2),
443 .BR open (2),
444 .BR pipe (2));
445 .IP \[bu]
446 employ
447 .B CLONE_*
448 flags that create new namespaces with
449 .BR clone (2)
450 and
451 .BR unshare (2)
452 (but, since Linux 3.8,
453 creating user namespaces does not require any capability);
454 .IP \[bu]
455 access privileged
456 .I perf
457 event information;
458 .IP \[bu]
459 call
460 .BR setns (2)
461 (requires
462 .B CAP_SYS_ADMIN
463 in the
464 .I target
465 namespace);
466 .IP \[bu]
467 call
468 .BR fanotify_init (2);
469 .IP \[bu]
470 perform privileged
471 .B KEYCTL_CHOWN
472 and
473 .B KEYCTL_SETPERM
474 .BR keyctl (2)
475 operations;
476 .IP \[bu]
477 perform
478 .BR madvise (2)
479 .B MADV_HWPOISON
480 operation;
481 .IP \[bu]
482 employ the
483 .B TIOCSTI
484 .BR ioctl (2)
485 to insert characters into the input queue of a terminal other than
486 the caller's controlling terminal;
487 .IP \[bu]
488 employ the obsolete
489 .BR nfsservctl (2)
490 system call;
491 .IP \[bu]
492 employ the obsolete
493 .BR bdflush (2)
494 system call;
495 .IP \[bu]
496 perform various privileged block-device
497 .BR ioctl (2)
498 operations;
499 .IP \[bu]
500 perform various privileged filesystem
501 .BR ioctl (2)
502 operations;
503 .IP \[bu]
504 perform privileged
505 .BR ioctl (2)
506 operations on the
507 .I /dev/random
508 device (see
509 .BR random (4));
510 .IP \[bu]
511 install a
512 .BR seccomp (2)
513 filter without first having to set the
514 .I no_new_privs
515 thread attribute;
516 .IP \[bu]
517 modify allow/deny rules for device control groups;
518 .IP \[bu]
519 employ the
520 .BR ptrace (2)
521 .B PTRACE_SECCOMP_GET_FILTER
522 operation to dump tracee's seccomp filters;
523 .IP \[bu]
524 employ the
525 .BR ptrace (2)
526 .B PTRACE_SETOPTIONS
527 operation to suspend the tracee's seccomp protections (i.e., the
528 .B PTRACE_O_SUSPEND_SECCOMP
529 flag);
530 .IP \[bu]
531 perform administrative operations on many device drivers;
532 .IP \[bu]
533 modify autogroup nice values by writing to
534 .IR /proc/ pid /autogroup
535 (see
536 .BR sched (7)).
537 .RE
538 .PD
539 .TP
540 .B CAP_SYS_BOOT
541 Use
542 .BR reboot (2)
543 and
544 .BR kexec_load (2).
545 .TP
546 .B CAP_SYS_CHROOT
547 .RS
548 .PD 0
549 .IP \[bu] 3
550 Use
551 .BR chroot (2);
552 .IP \[bu]
553 change mount namespaces using
554 .BR setns (2).
555 .PD
556 .RE
557 .TP
558 .B CAP_SYS_MODULE
559 .RS
560 .PD 0
561 .IP \[bu] 3
562 Load and unload kernel modules
563 (see
564 .BR init_module (2)
565 and
566 .BR delete_module (2));
567 .IP \[bu]
568 before Linux 2.6.25:
569 drop capabilities from the system-wide capability bounding set.
570 .PD
571 .RE
572 .TP
573 .B CAP_SYS_NICE
574 .PD 0
575 .RS
576 .IP \[bu] 3
577 Lower the process nice value
578 .RB ( nice (2),
579 .BR setpriority (2))
580 and change the nice value for arbitrary processes;
581 .IP \[bu]
582 set real-time scheduling policies for calling process,
583 and set scheduling policies and priorities for arbitrary processes
584 .RB ( sched_setscheduler (2),
585 .BR sched_setparam (2),
586 .BR sched_setattr (2));
587 .IP \[bu]
588 set CPU affinity for arbitrary processes
589 .RB ( sched_setaffinity (2));
590 .IP \[bu]
591 set I/O scheduling class and priority for arbitrary processes
592 .RB ( ioprio_set (2));
593 .IP \[bu]
594 apply
595 .BR migrate_pages (2)
596 to arbitrary processes and allow processes
597 to be migrated to arbitrary nodes;
598 .\" FIXME CAP_SYS_NICE also has the following effect for
599 .\" migrate_pages(2):
600 .\" do_migrate_pages(mm, &old, &new,
601 .\" capable(CAP_SYS_NICE) ? MPOL_MF_MOVE_ALL : MPOL_MF_MOVE);
602 .\"
603 .\" Document this.
604 .IP \[bu]
605 apply
606 .BR move_pages (2)
607 to arbitrary processes;
608 .IP \[bu]
609 use the
610 .B MPOL_MF_MOVE_ALL
611 flag with
612 .BR mbind (2)
613 and
614 .BR move_pages (2).
615 .RE
616 .PD
617 .TP
618 .B CAP_SYS_PACCT
619 Use
620 .BR acct (2).
621 .TP
622 .B CAP_SYS_PTRACE
623 .PD 0
624 .RS
625 .IP \[bu] 3
626 Trace arbitrary processes using
627 .BR ptrace (2);
628 .IP \[bu]
629 inspect sensitive information of other processes via
630 .I /proc
631 (e.g., reading
632 .IR /proc/ pid /maps ,
633 .IR /proc/ pid /mem ,
634 or reading symbolic links
635 .IR /proc/ pid /exe ,
636 .IR /proc/ pid /fd/* );
637 .IP \[bu]
638 apply
639 .BR get_robust_list (2)
640 to arbitrary processes;
641 .IP \[bu]
642 transfer data to or from the memory of arbitrary processes using
643 .BR process_vm_readv (2)
644 and
645 .BR process_vm_writev (2);
646 .IP \[bu]
647 inspect processes using
648 .BR kcmp (2);
649 .IP \[bu]
650 perform other privileged process-inspection and debugging operations.
651 (See uses of the
652 .IR ptrace_may_access ()
653 kernel function.)
654 .RE
655 .PD
656 .TP
657 .B CAP_SYS_RAWIO
658 .PD 0
659 .RS
660 .IP \[bu] 3
661 Perform I/O port operations
662 .RB ( iopl (2)
663 and
664 .BR ioperm (2));
665 .IP \[bu]
666 access
667 .IR /proc/kcore ;
668 .IP \[bu]
669 employ the
670 .B FIBMAP
671 .BR ioctl (2)
672 operation;
673 .IP \[bu]
674 open devices for accessing x86 model-specific registers (MSRs, see
675 .BR msr (4));
676 .IP \[bu]
677 update
678 .IR /proc/sys/vm/mmap_min_addr ;
679 .IP \[bu]
680 create memory mappings at addresses below the value specified by
681 .IR /proc/sys/vm/mmap_min_addr ;
682 .IP \[bu]
683 map files in
684 .IR /proc/bus/pci ;
685 .IP \[bu]
686 open
687 .I /dev/mem
688 and
689 .IR /dev/kmem ;
690 .IP \[bu]
691 perform various SCSI device commands;
692 .IP \[bu]
693 perform certain operations on
694 .BR hpsa (4)
695 and
696 .BR cciss (4)
697 devices;
698 .IP \[bu]
699 perform a range of device-specific operations on other devices.
700 .RE
701 .PD
702 .TP
703 .B CAP_SYS_RESOURCE
704 .PD 0
705 .RS
706 .IP \[bu] 3
707 Use reserved space on ext2 filesystems;
708 .IP \[bu]
709 make
710 .BR ioctl (2)
711 calls controlling ext3 journaling;
712 .IP \[bu]
713 override disk quota limits;
714 .IP \[bu]
715 increase resource limits (see
716 .BR setrlimit (2));
717 .IP \[bu]
718 override
719 .B RLIMIT_NPROC
720 resource limit;
721 .IP \[bu]
722 override maximum number of consoles on console allocation;
723 .IP \[bu]
724 override maximum number of keymaps;
725 .IP \[bu]
726 allow more than 64hz interrupts from the real-time clock;
727 .IP \[bu]
728 raise
729 .I msg_qbytes
730 limit for a System V message queue above the limit in
731 .I /proc/sys/kernel/msgmnb
732 (see
733 .BR msgop (2)
734 and
735 .BR msgctl (2));
736 .IP \[bu]
737 allow the
738 .B RLIMIT_NOFILE
739 resource limit on the number of "in-flight" file descriptors
740 to be bypassed when passing file descriptors to another process
741 via a UNIX domain socket (see
742 .BR unix (7));
743 .IP \[bu]
744 override the
745 .I /proc/sys/fs/pipe\-size\-max
746 limit when setting the capacity of a pipe using the
747 .B F_SETPIPE_SZ
748 .BR fcntl (2)
749 command;
750 .IP \[bu]
751 use
752 .B F_SETPIPE_SZ
753 to increase the capacity of a pipe above the limit specified by
754 .IR /proc/sys/fs/pipe\-max\-size ;
755 .IP \[bu]
756 override
757 .IR /proc/sys/fs/mqueue/queues_max ,
758 .IR /proc/sys/fs/mqueue/msg_max ,
759 and
760 .I /proc/sys/fs/mqueue/msgsize_max
761 limits when creating POSIX message queues (see
762 .BR mq_overview (7));
763 .IP \[bu]
764 employ the
765 .BR prctl (2)
766 .B PR_SET_MM
767 operation;
768 .IP \[bu]
769 set
770 .IR /proc/ pid /oom_score_adj
771 to a value lower than the value last set by a process with
772 .BR CAP_SYS_RESOURCE .
773 .RE
774 .PD
775 .TP
776 .B CAP_SYS_TIME
777 Set system clock
778 .RB ( settimeofday (2),
779 .BR stime (2),
780 .BR adjtimex (2));
781 set real-time (hardware) clock.
782 .TP
783 .B CAP_SYS_TTY_CONFIG
784 Use
785 .BR vhangup (2);
786 employ various privileged
787 .BR ioctl (2)
788 operations on virtual terminals.
789 .TP
790 .BR CAP_SYSLOG " (since Linux 2.6.37)"
791 .RS
792 .PD 0
793 .IP \[bu] 3
794 Perform privileged
795 .BR syslog (2)
796 operations.
797 See
798 .BR syslog (2)
799 for information on which operations require privilege.
800 .IP \[bu]
801 View kernel addresses exposed via
802 .I /proc
803 and other interfaces when
804 .I /proc/sys/kernel/kptr_restrict
805 has the value 1.
806 (See the discussion of the
807 .I kptr_restrict
808 in
809 .BR proc (5).)
810 .PD
811 .RE
812 .TP
813 .BR CAP_WAKE_ALARM " (since Linux 3.0)"
814 Trigger something that will wake up the system (set
815 .B CLOCK_REALTIME_ALARM
816 and
817 .B CLOCK_BOOTTIME_ALARM
818 timers).
819 .\"
820 .SS Past and current implementation
821 A full implementation of capabilities requires that:
822 .IP \[bu] 3
823 For all privileged operations,
824 the kernel must check whether the thread has the required
825 capability in its effective set.
826 .IP \[bu]
827 The kernel must provide system calls allowing a thread's capability sets to
828 be changed and retrieved.
829 .IP \[bu]
830 The filesystem must support attaching capabilities to an executable file,
831 so that a process gains those capabilities when the file is executed.
832 .P
833 Before Linux 2.6.24, only the first two of these requirements are met;
834 since Linux 2.6.24, all three requirements are met.
835 .\"
836 .SS Notes to kernel developers
837 When adding a new kernel feature that should be governed by a capability,
838 consider the following points.
839 .IP \[bu] 3
840 The goal of capabilities is divide the power of superuser into pieces,
841 such that if a program that has one or more capabilities is compromised,
842 its power to do damage to the system would be less than the same program
843 running with root privilege.
844 .IP \[bu]
845 You have the choice of either creating a new capability for your new feature,
846 or associating the feature with one of the existing capabilities.
847 In order to keep the set of capabilities to a manageable size,
848 the latter option is preferable,
849 unless there are compelling reasons to take the former option.
850 (There is also a technical limit:
851 the size of capability sets is currently limited to 64 bits.)
852 .IP \[bu]
853 To determine which existing capability might best be associated
854 with your new feature, review the list of capabilities above in order
855 to find a "silo" into which your new feature best fits.
856 One approach to take is to determine if there are other features
857 requiring capabilities that will always be used along with the new feature.
858 If the new feature is useless without these other features,
859 you should use the same capability as the other features.
860 .IP \[bu]
861 .I Don't
862 choose
863 .B CAP_SYS_ADMIN
864 if you can possibly avoid it!
865 A vast proportion of existing capability checks are associated
866 with this capability (see the partial list above).
867 It can plausibly be called "the new root",
868 since on the one hand, it confers a wide range of powers,
869 and on the other hand,
870 its broad scope means that this is the capability
871 that is required by many privileged programs.
872 Don't make the problem worse.
873 The only new features that should be associated with
874 .B CAP_SYS_ADMIN
875 are ones that
876 .I closely
877 match existing uses in that silo.
878 .IP \[bu]
879 If you have determined that it really is necessary to create
880 a new capability for your feature,
881 don't make or name it as a "single-use" capability.
882 Thus, for example, the addition of the highly specific
883 .B CAP_SYS_PACCT
884 was probably a mistake.
885 Instead, try to identify and name your new capability as a broader
886 silo into which other related future use cases might fit.
887 .\"
888 .SS Thread capability sets
889 Each thread has the following capability sets containing zero or more
890 of the above capabilities:
891 .TP
892 .I Permitted
893 This is a limiting superset for the effective
894 capabilities that the thread may assume.
895 It is also a limiting superset for the capabilities that
896 may be added to the inheritable set by a thread that does not have the
897 .B CAP_SETPCAP
898 capability in its effective set.
899 .IP
900 If a thread drops a capability from its permitted set,
901 it can never reacquire that capability (unless it
902 .BR execve (2)s
903 either a set-user-ID-root program, or
904 a program whose associated file capabilities grant that capability).
905 .TP
906 .I Inheritable
907 This is a set of capabilities preserved across an
908 .BR execve (2).
909 Inheritable capabilities remain inheritable when executing any program,
910 and inheritable capabilities are added to the permitted set when executing
911 a program that has the corresponding bits set in the file inheritable set.
912 .IP
913 Because inheritable capabilities are not generally preserved across
914 .BR execve (2)
915 when running as a non-root user, applications that wish to run helper
916 programs with elevated capabilities should consider using
917 ambient capabilities, described below.
918 .TP
919 .I Effective
920 This is the set of capabilities used by the kernel to
921 perform permission checks for the thread.
922 .TP
923 .IR Bounding " (per-thread since Linux 2.6.25)"
924 The capability bounding set is a mechanism that can be used
925 to limit the capabilities that are gained during
926 .BR execve (2).
927 .IP
928 Since Linux 2.6.25, this is a per-thread capability set.
929 In older kernels, the capability bounding set was a system wide attribute
930 shared by all threads on the system.
931 .IP
932 For more details, see
933 .I Capability bounding set
934 below.
935 .TP
936 .IR Ambient " (since Linux 4.3)"
937 .\" commit 58319057b7847667f0c9585b9de0e8932b0fdb08
938 This is a set of capabilities that are preserved across an
939 .BR execve (2)
940 of a program that is not privileged.
941 The ambient capability set obeys the invariant that no capability
942 can ever be ambient if it is not both permitted and inheritable.
943 .IP
944 The ambient capability set can be directly modified using
945 .BR prctl (2).
946 Ambient capabilities are automatically lowered if either of
947 the corresponding permitted or inheritable capabilities is lowered.
948 .IP
949 Executing a program that changes UID or GID due to the
950 set-user-ID or set-group-ID bits or executing a program that has
951 any file capabilities set will clear the ambient set.
952 Ambient capabilities are added to the permitted set and
953 assigned to the effective set when
954 .BR execve (2)
955 is called.
956 If ambient capabilities cause a process's permitted and effective
957 capabilities to increase during an
958 .BR execve (2),
959 this does not trigger the secure-execution mode described in
960 .BR ld.so (8).
961 .P
962 A child created via
963 .BR fork (2)
964 inherits copies of its parent's capability sets.
965 For details on how
966 .BR execve (2)
967 affects capabilities, see
968 .I Transformation of capabilities during execve()
969 below.
970 .P
971 Using
972 .BR capset (2),
973 a thread may manipulate its own capability sets;
974 see
975 .I Programmatically adjusting capability sets
976 below.
977 .P
978 Since Linux 3.2, the file
979 .I /proc/sys/kernel/cap_last_cap
980 .\" commit 73efc0394e148d0e15583e13712637831f926720
981 exposes the numerical value of the highest capability
982 supported by the running kernel;
983 this can be used to determine the highest bit
984 that may be set in a capability set.
985 .\"
986 .SS File capabilities
987 Since Linux 2.6.24, the kernel supports
988 associating capability sets with an executable file using
989 .BR setcap (8).
990 The file capability sets are stored in an extended attribute (see
991 .BR setxattr (2)
992 and
993 .BR xattr (7))
994 named
995 .IR "security.capability" .
996 Writing to this extended attribute requires the
997 .B CAP_SETFCAP
998 capability.
999 The file capability sets,
1000 in conjunction with the capability sets of the thread,
1001 determine the capabilities of a thread after an
1002 .BR execve (2).
1003 .P
1004 The three file capability sets are:
1005 .TP
1006 .IR Permitted " (formerly known as " forced ):
1007 These capabilities are automatically permitted to the thread,
1008 regardless of the thread's inheritable capabilities.
1009 .TP
1010 .IR Inheritable " (formerly known as " allowed ):
1011 This set is ANDed with the thread's inheritable set to determine which
1012 inheritable capabilities are enabled in the permitted set of
1013 the thread after the
1014 .BR execve (2).
1015 .TP
1016 .IR Effective :
1017 This is not a set, but rather just a single bit.
1018 If this bit is set, then during an
1019 .BR execve (2)
1020 all of the new permitted capabilities for the thread are
1021 also raised in the effective set.
1022 If this bit is not set, then after an
1023 .BR execve (2),
1024 none of the new permitted capabilities is in the new effective set.
1025 .IP
1026 Enabling the file effective capability bit implies
1027 that any file permitted or inheritable capability that causes a
1028 thread to acquire the corresponding permitted capability during an
1029 .BR execve (2)
1030 (see
1031 .I Transformation of capabilities during execve()
1032 below) will also acquire that
1033 capability in its effective set.
1034 Therefore, when assigning capabilities to a file
1035 .RB ( setcap (8),
1036 .BR cap_set_file (3),
1037 .BR cap_set_fd (3)),
1038 if we specify the effective flag as being enabled for any capability,
1039 then the effective flag must also be specified as enabled
1040 for all other capabilities for which the corresponding permitted or
1041 inheritable flag is enabled.
1042 .\"
1043 .SS File capability extended attribute versioning
1044 To allow extensibility,
1045 the kernel supports a scheme to encode a version number inside the
1046 .I security.capability
1047 extended attribute that is used to implement file capabilities.
1048 These version numbers are internal to the implementation,
1049 and not directly visible to user-space applications.
1050 To date, the following versions are supported:
1051 .TP
1052 .B VFS_CAP_REVISION_1
1053 This was the original file capability implementation,
1054 which supported 32-bit masks for file capabilities.
1055 .TP
1056 .BR VFS_CAP_REVISION_2 " (since Linux 2.6.25)"
1057 .\" commit e338d263a76af78fe8f38a72131188b58fceb591
1058 This version allows for file capability masks that are 64 bits in size,
1059 and was necessary as the number of supported capabilities grew beyond 32.
1060 The kernel transparently continues to support the execution of files
1061 that have 32-bit version 1 capability masks,
1062 but when adding capabilities to files that did not previously
1063 have capabilities, or modifying the capabilities of existing files,
1064 it automatically uses the version 2 scheme
1065 (or possibly the version 3 scheme, as described below).
1066 .TP
1067 .BR VFS_CAP_REVISION_3 " (since Linux 4.14)"
1068 .\" commit 8db6c34f1dbc8e06aa016a9b829b06902c3e1340
1069 Version 3 file capabilities are provided
1070 to support namespaced file capabilities (described below).
1071 .IP
1072 As with version 2 file capabilities,
1073 version 3 capability masks are 64 bits in size.
1074 But in addition, the root user ID of namespace is encoded in the
1075 .I security.capability
1076 extended attribute.
1077 (A namespace's root user ID is the value that user ID 0
1078 inside that namespace maps to in the initial user namespace.)
1079 .IP
1080 Version 3 file capabilities are designed to coexist
1081 with version 2 capabilities;
1082 that is, on a modern Linux system,
1083 there may be some files with version 2 capabilities
1084 while others have version 3 capabilities.
1085 .P
1086 Before Linux 4.14,
1087 the only kind of file capability extended attribute
1088 that could be attached to a file was a
1089 .B VFS_CAP_REVISION_2
1090 attribute.
1091 Since Linux 4.14,
1092 the version of the
1093 .I security.capability
1094 extended attribute that is attached to a file
1095 depends on the circumstances in which the attribute was created.
1096 .P
1097 Starting with Linux 4.14, a
1098 .I security.capability
1099 extended attribute is automatically created as (or converted to)
1100 a version 3
1101 .RB ( VFS_CAP_REVISION_3 )
1102 attribute if both of the following are true:
1103 .IP \[bu] 3
1104 The thread writing the attribute resides in a noninitial user namespace.
1105 (More precisely: the thread resides in a user namespace other
1106 than the one from which the underlying filesystem was mounted.)
1107 .IP \[bu]
1108 The thread has the
1109 .B CAP_SETFCAP
1110 capability over the file inode,
1111 meaning that (a) the thread has the
1112 .B CAP_SETFCAP
1113 capability in its own user namespace;
1114 and (b) the UID and GID of the file inode have mappings in
1115 the writer's user namespace.
1116 .P
1117 When a
1118 .B VFS_CAP_REVISION_3
1119 .I security.capability
1120 extended attribute is created, the root user ID of the creating thread's
1121 user namespace is saved in the extended attribute.
1122 .P
1123 By contrast, creating or modifying a
1124 .I security.capability
1125 extended attribute from a privileged
1126 .RB ( CAP_SETFCAP )
1127 thread that resides in the
1128 namespace where the underlying filesystem was mounted
1129 (this normally means the initial user namespace)
1130 automatically results in the creation of a version 2
1131 .RB ( VFS_CAP_REVISION_2 )
1132 attribute.
1133 .P
1134 Note that the creation of a version 3
1135 .I security.capability
1136 extended attribute is automatic.
1137 That is to say, when a user-space application writes
1138 .RB ( setxattr (2))
1139 a
1140 .I security.capability
1141 attribute in the version 2 format,
1142 the kernel will automatically create a version 3 attribute
1143 if the attribute is created in the circumstances described above.
1144 Correspondingly, when a version 3
1145 .I security.capability
1146 attribute is retrieved
1147 .RB ( getxattr (2))
1148 by a process that resides inside a user namespace that was created by the
1149 root user ID (or a descendant of that user namespace),
1150 the returned attribute is (automatically)
1151 simplified to appear as a version 2 attribute
1152 (i.e., the returned value is the size of a version 2 attribute and does
1153 not include the root user ID).
1154 These automatic translations mean that no changes are required to
1155 user-space tools (e.g.,
1156 .BR setcap (1)
1157 and
1158 .BR getcap (1))
1159 in order for those tools to be used to create and retrieve version 3
1160 .I security.capability
1161 attributes.
1162 .P
1163 Note that a file can have either a version 2 or a version 3
1164 .I security.capability
1165 extended attribute associated with it, but not both:
1166 creation or modification of the
1167 .I security.capability
1168 extended attribute will automatically modify the version
1169 according to the circumstances in which the extended attribute is
1170 created or modified.
1171 .\"
1172 .SS Transformation of capabilities during execve()
1173 During an
1174 .BR execve (2),
1175 the kernel calculates the new capabilities of
1176 the process using the following algorithm:
1177 .P
1178 .in +4n
1179 .EX
1180 P'(ambient) = (file is privileged) ? 0 : P(ambient)
1181 \&
1182 P'(permitted) = (P(inheritable) & F(inheritable)) |
1183 (F(permitted) & P(bounding)) | P'(ambient)
1184 \&
1185 P'(effective) = F(effective) ? P'(permitted) : P'(ambient)
1186 \&
1187 P'(inheritable) = P(inheritable) [i.e., unchanged]
1188 \&
1189 P'(bounding) = P(bounding) [i.e., unchanged]
1190 .EE
1191 .in
1192 .P
1193 where:
1194 .RS 4
1195 .TP
1196 P()
1197 denotes the value of a thread capability set before the
1198 .BR execve (2)
1199 .TP
1200 P'()
1201 denotes the value of a thread capability set after the
1202 .BR execve (2)
1203 .TP
1204 F()
1205 denotes a file capability set
1206 .RE
1207 .P
1208 Note the following details relating to the above capability
1209 transformation rules:
1210 .IP \[bu] 3
1211 The ambient capability set is present only since Linux 4.3.
1212 When determining the transformation of the ambient set during
1213 .BR execve (2),
1214 a privileged file is one that has capabilities or
1215 has the set-user-ID or set-group-ID bit set.
1216 .IP \[bu]
1217 Prior to Linux 2.6.25,
1218 the bounding set was a system-wide attribute shared by all threads.
1219 That system-wide value was employed to calculate the new permitted set during
1220 .BR execve (2)
1221 in the same manner as shown above for
1222 .IR P(bounding) .
1223 .P
1224 .IR Note :
1225 during the capability transitions described above,
1226 file capabilities may be ignored (treated as empty)
1227 for the same reasons that the set-user-ID and set-group-ID bits are ignored;
1228 see
1229 .BR execve (2).
1230 File capabilities are similarly ignored if the kernel was booted with the
1231 .I no_file_caps
1232 option.
1233 .P
1234 .IR Note :
1235 according to the rules above,
1236 if a process with nonzero user IDs performs an
1237 .BR execve (2)
1238 then any capabilities that are present in
1239 its permitted and effective sets will be cleared.
1240 For the treatment of capabilities when a process with a
1241 user ID of zero performs an
1242 .BR execve (2),
1243 see
1244 .I Capabilities and execution of programs by root
1245 below.
1246 .\"
1247 .SS Safety checking for capability-dumb binaries
1248 A capability-dumb binary is an application that has been
1249 marked to have file capabilities, but has not been converted to use the
1250 .BR libcap (3)
1251 API to manipulate its capabilities.
1252 (In other words, this is a traditional set-user-ID-root program
1253 that has been switched to use file capabilities,
1254 but whose code has not been modified to understand capabilities.)
1255 For such applications,
1256 the effective capability bit is set on the file,
1257 so that the file permitted capabilities are automatically
1258 enabled in the process effective set when executing the file.
1259 The kernel recognizes a file which has the effective capability bit set
1260 as capability-dumb for the purpose of the check described here.
1261 .P
1262 When executing a capability-dumb binary,
1263 the kernel checks if the process obtained all permitted capabilities
1264 that were specified in the file permitted set,
1265 after the capability transformations described above have been performed.
1266 (The typical reason why this might
1267 .I not
1268 occur is that the capability bounding set masked out some
1269 of the capabilities in the file permitted set.)
1270 If the process did not obtain the full set of
1271 file permitted capabilities, then
1272 .BR execve (2)
1273 fails with the error
1274 .BR EPERM .
1275 This prevents possible security risks that could arise when
1276 a capability-dumb application is executed with less privilege than it needs.
1277 Note that, by definition,
1278 the application could not itself recognize this problem,
1279 since it does not employ the
1280 .BR libcap (3)
1281 API.
1282 .\"
1283 .SS Capabilities and execution of programs by root
1284 .\" See cap_bprm_set_creds(), bprm_caps_from_vfs_cap() and
1285 .\" handle_privileged_root() in security/commoncap.c (Linux 5.0 source)
1286 In order to mirror traditional UNIX semantics,
1287 the kernel performs special treatment of file capabilities when
1288 a process with UID 0 (root) executes a program and
1289 when a set-user-ID-root program is executed.
1290 .P
1291 After having performed any changes to the process effective ID that
1292 were triggered by the set-user-ID mode bit of the binary\[em]e.g.,
1293 switching the effective user ID to 0 (root) because
1294 a set-user-ID-root program was executed\[em]the
1295 kernel calculates the file capability sets as follows:
1296 .IP (1) 5
1297 If the real or effective user ID of the process is 0 (root),
1298 then the file inheritable and permitted sets are ignored;
1299 instead they are notionally considered to be all ones
1300 (i.e., all capabilities enabled).
1301 (There is one exception to this behavior, described in
1302 .I Set-user-ID-root programs that have file capabilities
1303 below.)
1304 .IP (2)
1305 If the effective user ID of the process is 0 (root) or
1306 the file effective bit is in fact enabled,
1307 then the file effective bit is notionally defined to be one (enabled).
1308 .P
1309 These notional values for the file's capability sets are then used
1310 as described above to calculate the transformation of the process's
1311 capabilities during
1312 .BR execve (2).
1313 .P
1314 Thus, when a process with nonzero UIDs
1315 .BR execve (2)s
1316 a set-user-ID-root program that does not have capabilities attached,
1317 or when a process whose real and effective UIDs are zero
1318 .BR execve (2)s
1319 a program, the calculation of the process's new
1320 permitted capabilities simplifies to:
1321 .P
1322 .in +4n
1323 .EX
1324 P'(permitted) = P(inheritable) | P(bounding)
1325 \&
1326 P'(effective) = P'(permitted)
1327 .EE
1328 .in
1329 .P
1330 Consequently, the process gains all capabilities in its permitted and
1331 effective capability sets,
1332 except those masked out by the capability bounding set.
1333 (In the calculation of P'(permitted),
1334 the P'(ambient) term can be simplified away because it is by
1335 definition a proper subset of P(inheritable).)
1336 .P
1337 The special treatments of user ID 0 (root) described in this subsection
1338 can be disabled using the securebits mechanism described below.
1339 .\"
1340 .\"
1341 .SS Set-user-ID-root programs that have file capabilities
1342 There is one exception to the behavior described in
1343 .I Capabilities and execution of programs by root
1344 above.
1345 If (a) the binary that is being executed has capabilities attached and
1346 (b) the real user ID of the process is
1347 .I not
1348 0 (root) and
1349 (c) the effective user ID of the process
1350 .I is
1351 0 (root), then the file capability bits are honored
1352 (i.e., they are not notionally considered to be all ones).
1353 The usual way in which this situation can arise is when executing
1354 a set-UID-root program that also has file capabilities.
1355 When such a program is executed,
1356 the process gains just the capabilities granted by the program
1357 (i.e., not all capabilities,
1358 as would occur when executing a set-user-ID-root program
1359 that does not have any associated file capabilities).
1360 .P
1361 Note that one can assign empty capability sets to a program file,
1362 and thus it is possible to create a set-user-ID-root program that
1363 changes the effective and saved set-user-ID of the process
1364 that executes the program to 0,
1365 but confers no capabilities to that process.
1366 .\"
1367 .SS Capability bounding set
1368 The capability bounding set is a security mechanism that can be used
1369 to limit the capabilities that can be gained during an
1370 .BR execve (2).
1371 The bounding set is used in the following ways:
1372 .IP \[bu] 3
1373 During an
1374 .BR execve (2),
1375 the capability bounding set is ANDed with the file permitted
1376 capability set, and the result of this operation is assigned to the
1377 thread's permitted capability set.
1378 The capability bounding set thus places a limit on the permitted
1379 capabilities that may be granted by an executable file.
1380 .IP \[bu]
1381 (Since Linux 2.6.25)
1382 The capability bounding set acts as a limiting superset for
1383 the capabilities that a thread can add to its inheritable set using
1384 .BR capset (2).
1385 This means that if a capability is not in the bounding set,
1386 then a thread can't add this capability to its
1387 inheritable set, even if it was in its permitted capabilities,
1388 and thereby cannot have this capability preserved in its
1389 permitted set when it
1390 .BR execve (2)s
1391 a file that has the capability in its inheritable set.
1392 .P
1393 Note that the bounding set masks the file permitted capabilities,
1394 but not the inheritable capabilities.
1395 If a thread maintains a capability in its inheritable set
1396 that is not in its bounding set,
1397 then it can still gain that capability in its permitted set
1398 by executing a file that has the capability in its inheritable set.
1399 .P
1400 Depending on the kernel version, the capability bounding set is either
1401 a system-wide attribute, or a per-process attribute.
1402 .P
1403 .B "Capability bounding set from Linux 2.6.25 onward"
1404 .P
1405 From Linux 2.6.25, the
1406 .I "capability bounding set"
1407 is a per-thread attribute.
1408 (The system-wide capability bounding set described below no longer exists.)
1409 .P
1410 The bounding set is inherited at
1411 .BR fork (2)
1412 from the thread's parent, and is preserved across an
1413 .BR execve (2).
1414 .P
1415 A thread may remove capabilities from its capability bounding set using the
1416 .BR prctl (2)
1417 .B PR_CAPBSET_DROP
1418 operation, provided it has the
1419 .B CAP_SETPCAP
1420 capability.
1421 Once a capability has been dropped from the bounding set,
1422 it cannot be restored to that set.
1423 A thread can determine if a capability is in its bounding set using the
1424 .BR prctl (2)
1425 .B PR_CAPBSET_READ
1426 operation.
1427 .P
1428 Removing capabilities from the bounding set is supported only if file
1429 capabilities are compiled into the kernel.
1430 Before Linux 2.6.33,
1431 file capabilities were an optional feature configurable via the
1432 .B CONFIG_SECURITY_FILE_CAPABILITIES
1433 option.
1434 Since Linux 2.6.33,
1435 .\" commit b3a222e52e4d4be77cc4520a57af1a4a0d8222d1
1436 the configuration option has been removed
1437 and file capabilities are always part of the kernel.
1438 When file capabilities are compiled into the kernel, the
1439 .B init
1440 process (the ancestor of all processes) begins with a full bounding set.
1441 If file capabilities are not compiled into the kernel, then
1442 .B init
1443 begins with a full bounding set minus
1444 .BR CAP_SETPCAP ,
1445 because this capability has a different meaning when there are
1446 no file capabilities.
1447 .P
1448 Removing a capability from the bounding set does not remove it
1449 from the thread's inheritable set.
1450 However it does prevent the capability from being added
1451 back into the thread's inheritable set in the future.
1452 .P
1453 .B "Capability bounding set prior to Linux 2.6.25"
1454 .P
1455 Before Linux 2.6.25, the capability bounding set is a system-wide
1456 attribute that affects all threads on the system.
1457 The bounding set is accessible via the file
1458 .IR /proc/sys/kernel/cap\-bound .
1459 (Confusingly, this bit mask parameter is expressed as a
1460 signed decimal number in
1461 .IR /proc/sys/kernel/cap\-bound .)
1462 .P
1463 Only the
1464 .B init
1465 process may set capabilities in the capability bounding set;
1466 other than that, the superuser (more precisely: a process with the
1467 .B CAP_SYS_MODULE
1468 capability) may only clear capabilities from this set.
1469 .P
1470 On a standard system the capability bounding set always masks out the
1471 .B CAP_SETPCAP
1472 capability.
1473 To remove this restriction (dangerous!), modify the definition of
1474 .B CAP_INIT_EFF_SET
1475 in
1476 .I include/linux/capability.h
1477 and rebuild the kernel.
1478 .P
1479 The system-wide capability bounding set feature was added
1480 to Linux 2.2.11.
1481 .\"
1482 .\"
1483 .\"
1484 .SS Effect of user ID changes on capabilities
1485 To preserve the traditional semantics for transitions between
1486 0 and nonzero user IDs,
1487 the kernel makes the following changes to a thread's capability
1488 sets on changes to the thread's real, effective, saved set,
1489 and filesystem user IDs (using
1490 .BR setuid (2),
1491 .BR setresuid (2),
1492 or similar):
1493 .IP \[bu] 3
1494 If one or more of the real, effective, or saved set user IDs
1495 was previously 0, and as a result of the UID changes all of these IDs
1496 have a nonzero value,
1497 then all capabilities are cleared from the permitted, effective, and ambient
1498 capability sets.
1499 .IP \[bu]
1500 If the effective user ID is changed from 0 to nonzero,
1501 then all capabilities are cleared from the effective set.
1502 .IP \[bu]
1503 If the effective user ID is changed from nonzero to 0,
1504 then the permitted set is copied to the effective set.
1505 .IP \[bu]
1506 If the filesystem user ID is changed from 0 to nonzero (see
1507 .BR setfsuid (2)),
1508 then the following capabilities are cleared from the effective set:
1509 .BR CAP_CHOWN ,
1510 .BR CAP_DAC_OVERRIDE ,
1511 .BR CAP_DAC_READ_SEARCH ,
1512 .BR CAP_FOWNER ,
1513 .BR CAP_FSETID ,
1514 .B CAP_LINUX_IMMUTABLE
1515 (since Linux 2.6.30),
1516 .BR CAP_MAC_OVERRIDE ,
1517 and
1518 .B CAP_MKNOD
1519 (since Linux 2.6.30).
1520 If the filesystem UID is changed from nonzero to 0,
1521 then any of these capabilities that are enabled in the permitted set
1522 are enabled in the effective set.
1523 .P
1524 If a thread that has a 0 value for one or more of its user IDs wants
1525 to prevent its permitted capability set being cleared when it resets
1526 all of its user IDs to nonzero values, it can do so using the
1527 .B SECBIT_KEEP_CAPS
1528 securebits flag described below.
1529 .\"
1530 .SS Programmatically adjusting capability sets
1531 A thread can retrieve and change its permitted, effective, and inheritable
1532 capability sets using the
1533 .BR capget (2)
1534 and
1535 .BR capset (2)
1536 system calls.
1537 However, the use of
1538 .BR cap_get_proc (3)
1539 and
1540 .BR cap_set_proc (3),
1541 both provided in the
1542 .I libcap
1543 package,
1544 is preferred for this purpose.
1545 The following rules govern changes to the thread capability sets:
1546 .IP \[bu] 3
1547 If the caller does not have the
1548 .B CAP_SETPCAP
1549 capability,
1550 the new inheritable set must be a subset of the combination
1551 of the existing inheritable and permitted sets.
1552 .IP \[bu]
1553 (Since Linux 2.6.25)
1554 The new inheritable set must be a subset of the combination of the
1555 existing inheritable set and the capability bounding set.
1556 .IP \[bu]
1557 The new permitted set must be a subset of the existing permitted set
1558 (i.e., it is not possible to acquire permitted capabilities
1559 that the thread does not currently have).
1560 .IP \[bu]
1561 The new effective set must be a subset of the new permitted set.
1562 .SS The securebits flags: establishing a capabilities-only environment
1563 .\" For some background:
1564 .\" see http://lwn.net/Articles/280279/ and
1565 .\" http://article.gmane.org/gmane.linux.kernel.lsm/5476/
1566 Starting with Linux 2.6.26,
1567 and with a kernel in which file capabilities are enabled,
1568 Linux implements a set of per-thread
1569 .I securebits
1570 flags that can be used to disable special handling of capabilities for UID 0
1571 .RI ( root ).
1572 These flags are as follows:
1573 .TP
1574 .B SECBIT_KEEP_CAPS
1575 Setting this flag allows a thread that has one or more 0 UIDs to retain
1576 capabilities in its permitted set
1577 when it switches all of its UIDs to nonzero values.
1578 If this flag is not set,
1579 then such a UID switch causes the thread to lose all permitted capabilities.
1580 This flag is always cleared on an
1581 .BR execve (2).
1582 .IP
1583 Note that even with the
1584 .B SECBIT_KEEP_CAPS
1585 flag set, the effective capabilities of a thread are cleared when it
1586 switches its effective UID to a nonzero value.
1587 However,
1588 if the thread has set this flag and its effective UID is already nonzero,
1589 and the thread subsequently switches all other UIDs to nonzero values,
1590 then the effective capabilities will not be cleared.
1591 .IP
1592 The setting of the
1593 .B SECBIT_KEEP_CAPS
1594 flag is ignored if the
1595 .B SECBIT_NO_SETUID_FIXUP
1596 flag is set.
1597 (The latter flag provides a superset of the effect of the former flag.)
1598 .IP
1599 This flag provides the same functionality as the older
1600 .BR prctl (2)
1601 .B PR_SET_KEEPCAPS
1602 operation.
1603 .TP
1604 .B SECBIT_NO_SETUID_FIXUP
1605 Setting this flag stops the kernel from adjusting the process's
1606 permitted, effective, and ambient capability sets when
1607 the thread's effective and filesystem UIDs are switched between
1608 zero and nonzero values.
1609 See
1610 .I Effect of user ID changes on capabilities
1611 above.
1612 .TP
1613 .B SECBIT_NOROOT
1614 If this bit is set, then the kernel does not grant capabilities
1615 when a set-user-ID-root program is executed, or when a process with
1616 an effective or real UID of 0 calls
1617 .BR execve (2).
1618 (See
1619 .I Capabilities and execution of programs by root
1620 above.)
1621 .TP
1622 .B SECBIT_NO_CAP_AMBIENT_RAISE
1623 Setting this flag disallows raising ambient capabilities via the
1624 .BR prctl (2)
1625 .B PR_CAP_AMBIENT_RAISE
1626 operation.
1627 .P
1628 Each of the above "base" flags has a companion "locked" flag.
1629 Setting any of the "locked" flags is irreversible,
1630 and has the effect of preventing further changes to the
1631 corresponding "base" flag.
1632 The locked flags are:
1633 .BR SECBIT_KEEP_CAPS_LOCKED ,
1634 .BR SECBIT_NO_SETUID_FIXUP_LOCKED ,
1635 .BR SECBIT_NOROOT_LOCKED ,
1636 and
1637 .BR SECBIT_NO_CAP_AMBIENT_RAISE_LOCKED .
1638 .P
1639 The
1640 .I securebits
1641 flags can be modified and retrieved using the
1642 .BR prctl (2)
1643 .B PR_SET_SECUREBITS
1644 and
1645 .B PR_GET_SECUREBITS
1646 operations.
1647 The
1648 .B CAP_SETPCAP
1649 capability is required to modify the flags.
1650 Note that the
1651 .B SECBIT_*
1652 constants are available only after including the
1653 .I <linux/securebits.h>
1654 header file.
1655 .P
1656 The
1657 .I securebits
1658 flags are inherited by child processes.
1659 During an
1660 .BR execve (2),
1661 all of the flags are preserved, except
1662 .B SECBIT_KEEP_CAPS
1663 which is always cleared.
1664 .P
1665 An application can use the following call to lock itself,
1666 and all of its descendants,
1667 into an environment where the only way of gaining capabilities
1668 is by executing a program with associated file capabilities:
1669 .P
1670 .in +4n
1671 .EX
1672 prctl(PR_SET_SECUREBITS,
1673 /* SECBIT_KEEP_CAPS off */
1674 SECBIT_KEEP_CAPS_LOCKED |
1675 SECBIT_NO_SETUID_FIXUP |
1676 SECBIT_NO_SETUID_FIXUP_LOCKED |
1677 SECBIT_NOROOT |
1678 SECBIT_NOROOT_LOCKED);
1679 /* Setting/locking SECBIT_NO_CAP_AMBIENT_RAISE
1680 is not required */
1681 .EE
1682 .in
1683 .\"
1684 .\"
1685 .SS Per-user-namespace \[dq]set-user-ID-root\[dq] programs
1686 A set-user-ID program whose UID matches the UID that
1687 created a user namespace will confer capabilities
1688 in the process's permitted and effective sets
1689 when executed by any process inside that namespace
1690 or any descendant user namespace.
1691 .P
1692 The rules about the transformation of the process's capabilities during the
1693 .BR execve (2)
1694 are exactly as described in
1695 .I Transformation of capabilities during execve()
1696 and
1697 .I Capabilities and execution of programs by root
1698 above,
1699 with the difference that, in the latter subsection, "root"
1700 is the UID of the creator of the user namespace.
1701 .\"
1702 .\"
1703 .SS Namespaced file capabilities
1704 .\" commit 8db6c34f1dbc8e06aa016a9b829b06902c3e1340
1705 Traditional (i.e., version 2) file capabilities associate
1706 only a set of capability masks with a binary executable file.
1707 When a process executes a binary with such capabilities,
1708 it gains the associated capabilities (within its user namespace)
1709 as per the rules described in
1710 .I Transformation of capabilities during execve()
1711 above.
1712 .P
1713 Because version 2 file capabilities confer capabilities to
1714 the executing process regardless of which user namespace it resides in,
1715 only privileged processes are permitted to associate capabilities with a file.
1716 Here, "privileged" means a process that has the
1717 .B CAP_SETFCAP
1718 capability in the user namespace where the filesystem was mounted
1719 (normally the initial user namespace).
1720 This limitation renders file capabilities useless for certain use cases.
1721 For example, in user-namespaced containers,
1722 it can be desirable to be able to create a binary that
1723 confers capabilities only to processes executed inside that container,
1724 but not to processes that are executed outside the container.
1725 .P
1726 Linux 4.14 added so-called namespaced file capabilities
1727 to support such use cases.
1728 Namespaced file capabilities are recorded as version 3 (i.e.,
1729 .BR VFS_CAP_REVISION_3 )
1730 .I security.capability
1731 extended attributes.
1732 Such an attribute is automatically created in the circumstances described
1733 in
1734 .I File capability extended attribute versioning
1735 above.
1736 When a version 3
1737 .I security.capability
1738 extended attribute is created,
1739 the kernel records not just the capability masks in the extended attribute,
1740 but also the namespace root user ID.
1741 .P
1742 As with a binary that has
1743 .B VFS_CAP_REVISION_2
1744 file capabilities, a binary with
1745 .B VFS_CAP_REVISION_3
1746 file capabilities confers capabilities to a process during
1747 .BR execve ().
1748 However, capabilities are conferred only if the binary is executed by
1749 a process that resides in a user namespace whose
1750 UID 0 maps to the root user ID that is saved in the extended attribute,
1751 or when executed by a process that resides in a descendant of such a namespace.
1752 .\"
1753 .\"
1754 .SS Interaction with user namespaces
1755 For further information on the interaction of
1756 capabilities and user namespaces, see
1757 .BR user_namespaces (7).
1758 .SH STANDARDS
1759 No standards govern capabilities, but the Linux capability implementation
1760 is based on the withdrawn
1761 .UR https:\://archive.org\:/details\:/posix_1003.1e\-990310
1762 POSIX.1e draft standard
1763 .UE .
1764 .SH NOTES
1765 When attempting to
1766 .BR strace (1)
1767 binaries that have capabilities (or set-user-ID-root binaries),
1768 you may find the
1769 .I \-u <username>
1770 option useful.
1771 Something like:
1772 .P
1773 .in +4n
1774 .EX
1775 .RB $ " sudo strace \-o trace.log \-u ceci ./myprivprog"
1776 .EE
1777 .in
1778 .P
1779 From Linux 2.5.27 to Linux 2.6.26,
1780 .\" commit 5915eb53861c5776cfec33ca4fcc1fd20d66dd27 removed
1781 .\" CONFIG_SECURITY_CAPABILITIES
1782 capabilities were an optional kernel component,
1783 and could be enabled/disabled via the
1784 .B CONFIG_SECURITY_CAPABILITIES
1785 kernel configuration option.
1786 .P
1787 The
1788 .IR /proc/ pid /task/TID/status
1789 file can be used to view the capability sets of a thread.
1790 The
1791 .IR /proc/ pid /status
1792 file shows the capability sets of a process's main thread.
1793 Before Linux 3.8, nonexistent capabilities were shown as being
1794 enabled (1) in these sets.
1795 Since Linux 3.8,
1796 .\" 7b9a7ec565505699f503b4fcf61500dceb36e744
1797 all nonexistent capabilities (above
1798 .BR CAP_LAST_CAP )
1799 are shown as disabled (0).
1800 .P
1801 The
1802 .I libcap
1803 package provides a suite of routines for setting and
1804 getting capabilities that is more comfortable and less likely
1805 to change than the interface provided by
1806 .BR capset (2)
1807 and
1808 .BR capget (2).
1809 This package also provides the
1810 .BR setcap (8)
1811 and
1812 .BR getcap (8)
1813 programs.
1814 It can be found at
1815 .br
1816 .UR https:\://git.kernel.org\:/pub\:/scm\:/libs\:/libcap\:/libcap.git\:/refs/
1817 .UE .
1818 .P
1819 Before Linux 2.6.24, and from Linux 2.6.24 to Linux 2.6.32 if
1820 file capabilities are not enabled, a thread with the
1821 .B CAP_SETPCAP
1822 capability can manipulate the capabilities of threads other than itself.
1823 However, this is only theoretically possible,
1824 since no thread ever has
1825 .B CAP_SETPCAP
1826 in either of these cases:
1827 .IP \[bu] 3
1828 In the pre-2.6.25 implementation the system-wide capability bounding set,
1829 .IR /proc/sys/kernel/cap\-bound ,
1830 always masks out the
1831 .B CAP_SETPCAP
1832 capability, and this can not be changed
1833 without modifying the kernel source and rebuilding the kernel.
1834 .IP \[bu]
1835 If file capabilities are disabled (i.e., the kernel
1836 .B CONFIG_SECURITY_FILE_CAPABILITIES
1837 option is disabled), then
1838 .B init
1839 starts out with the
1840 .B CAP_SETPCAP
1841 capability removed from its per-process bounding
1842 set, and that bounding set is inherited by all other processes
1843 created on the system.
1844 .SH SEE ALSO
1845 .BR capsh (1),
1846 .BR setpriv (1),
1847 .BR prctl (2),
1848 .BR setfsuid (2),
1849 .BR cap_clear (3),
1850 .BR cap_copy_ext (3),
1851 .BR cap_from_text (3),
1852 .BR cap_get_file (3),
1853 .BR cap_get_proc (3),
1854 .BR cap_init (3),
1855 .BR capgetp (3),
1856 .BR capsetp (3),
1857 .BR libcap (3),
1858 .BR proc (5),
1859 .BR credentials (7),
1860 .BR pthreads (7),
1861 .BR user_namespaces (7),
1862 .BR captest (8), \" from libcap-ng
1863 .BR filecap (8), \" from libcap-ng
1864 .BR getcap (8),
1865 .BR getpcaps (8),
1866 .BR netcap (8), \" from libcap-ng
1867 .BR pscap (8), \" from libcap-ng
1868 .BR setcap (8)
1869 .P
1870 .I include/linux/capability.h
1871 in the Linux kernel source tree