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