man7/capabilities.7

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