original/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 2015-02-01 "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
  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 .TP
  86 .BR CAP_BLOCK_SUSPEND " (since Linux 3.5)"
  87 Employ features that can block system suspend
  88 .RB ( epoll (7)
  89 .BR EPOLLWAKEUP ,
  90 .IR /proc/sys/wake_lock ).
  91 .TP
  92 .B CAP_CHOWN
  93 Make arbitrary changes to file UIDs and GIDs (see
  94 .BR chown (2)).
  95 .TP
  96 .B CAP_DAC_OVERRIDE
  97 Bypass file read, write, and execute permission checks.
  98 (DAC is an abbreviation of "discretionary access control".)
  99 .TP
 100 .B CAP_DAC_READ_SEARCH
 101 .PD 0
 102 .RS
 103 .IP * 2
 104 Bypass file read permission checks and
 105 directory read and execute permission checks;
 106 .IP *
 107 Invoke
 108 .BR open_by_handle_at (2).
 109 .RE
 110 .PD
 111
 112 .TP
 113 .B CAP_FOWNER
 114 .PD 0
 115 .RS
 116 .IP * 2
 117 Bypass permission checks on operations that normally
 118 require the filesystem UID of the process to match the UID of
 119 the file (e.g.,
 120 .BR chmod (2),
 121 .BR utime (2)),
 122 excluding those operations covered by
 123 .B CAP_DAC_OVERRIDE
 124 and
 125 .BR CAP_DAC_READ_SEARCH ;
 126 .IP *
 127 set extended file attributes (see
 128 .BR chattr (1))
 129 on arbitrary files;
 130 .IP *
 131 set Access Control Lists (ACLs) on arbitrary files;
 132 .IP *
 133 ignore directory sticky bit on file deletion;
 134 .IP *
 135 specify
 136 .B O_NOATIME
 137 for arbitrary files in
 138 .BR open (2)
 139 and
 140 .BR fcntl (2).
 141 .RE
 142 .PD
 143 .TP
 144 .B CAP_FSETID
 145 Don't clear set-user-ID and set-group-ID permission
 146 bits when a file is modified;
 147 set the set-group-ID bit for a file whose GID does not match
 148 the filesystem or any of the supplementary GIDs of the calling process.
 149 .TP
 150 .B CAP_IPC_LOCK
 151 .\" FIXME . As at Linux 3.2, there are some strange uses of this capability
 152 .\" in other places; they probably should be replaced with something else.
 153 Lock memory
 154 .RB ( mlock (2),
 155 .BR mlockall (2),
 156 .BR mmap (2),
 157 .BR shmctl (2)).
 158 .TP
 159 .B CAP_IPC_OWNER
 160 Bypass permission checks for operations on System V IPC objects.
 161 .TP
 162 .B CAP_KILL
 163 Bypass permission checks for sending signals (see
 164 .BR kill (2)).
 165 This includes use of the
 166 .BR ioctl (2)
 167 .B KDSIGACCEPT
 168 operation.
 169 .\" FIXME . CAP_KILL also has an effect for threads + setting child
 170 .\"       termination signal to other than SIGCHLD: without this
 171 .\"       capability, the termination signal reverts to SIGCHLD
 172 .\"       if the child does an exec().  What is the rationale
 173 .\"       for this?
 174 .TP
 175 .BR CAP_LEASE " (since Linux 2.4)"
 176 Establish leases on arbitrary files (see
 177 .BR fcntl (2)).
 178 .TP
 179 .B CAP_LINUX_IMMUTABLE
 180 Set the
 181 .B FS_APPEND_FL
 182 and
 183 .B FS_IMMUTABLE_FL
 184 .\" These attributes are now available on ext2, ext3, Reiserfs, XFS, JFS
 185 inode flags (see
 186 .BR chattr (1)).
 187 .TP
 188 .BR CAP_MAC_ADMIN " (since Linux 2.6.25)"
 189 Override Mandatory Access Control (MAC).
 190 Implemented for the Smack Linux Security Module (LSM).
 191 .TP
 192 .BR CAP_MAC_OVERRIDE " (since Linux 2.6.25)"
 193 Allow MAC configuration or state changes.
 194 Implemented for the Smack LSM.
 195 .TP
 196 .BR CAP_MKNOD " (since Linux 2.4)"
 197 Create special files using
 198 .BR mknod (2).
 199 .TP
 200 .B CAP_NET_ADMIN
 201 Perform various network-related operations:
 202 .PD 0
 203 .RS
 204 .IP * 2
 205 interface configuration;
 206 .IP *
 207 administration of IP firewall, masquerading, and accounting;
 208 .IP *
 209 modify routing tables;
 210 .IP *
 211 bind to any address for transparent proxying;
 212 .IP *
 213 set type-of-service (TOS)
 214 .IP *
 215 clear driver statistics;
 216 .IP *
 217 set promiscuous mode;
 218 .IP *
 219 enabling multicasting;
 220 .IP *
 221 use
 222 .BR setsockopt (2)
 223 to set the following socket options:
 224 .BR SO_DEBUG ,
 225 .BR SO_MARK ,
 226 .BR SO_PRIORITY
 227 (for a priority outside the range 0 to 6),
 228 .BR SO_RCVBUFFORCE ,
 229 and
 230 .BR SO_SNDBUFFORCE .
 231 .RE
 232 .PD
 233 .TP
 234 .B CAP_NET_BIND_SERVICE
 235 Bind a socket to Internet domain privileged ports
 236 (port numbers less than 1024).
 237 .TP
 238 .B CAP_NET_BROADCAST
 239 (Unused)  Make socket broadcasts, and listen to multicasts.
 240 .TP
 241 .B CAP_NET_RAW
 242 .PD 0
 243 .RS
 244 .IP * 2
 245 use RAW and PACKET sockets;
 246 .IP *
 247 bind to any address for transparent proxying.
 248 .RE
 249 .PD
 250 .\" Also various IP options and setsockopt(SO_BINDTODEVICE)
 251 .TP
 252 .B CAP_SETGID
 253 Make arbitrary manipulations of process GIDs and supplementary GID list;
 254 forge GID when passing socket credentials via UNIX domain sockets;
 255 write a group ID mapping in a user namespace (see
 256 .BR user_namespaces (7)).
 257 .TP
 258 .BR CAP_SETFCAP " (since Linux 2.6.24)"
 259 Set file capabilities.
 260 .TP
 261 .B CAP_SETPCAP
 262 If file capabilities are not supported:
 263 grant or remove any capability in the
 264 caller's permitted capability set to or from any other process.
 265 (This property of
 266 .B CAP_SETPCAP
 267 is not available when the kernel is configured to support
 268 file capabilities, since
 269 .B CAP_SETPCAP
 270 has entirely different semantics for such kernels.)
 271
 272 If file capabilities are supported:
 273 add any capability from the calling thread's bounding set
 274 to its inheritable set;
 275 drop capabilities from the bounding set (via
 276 .BR prctl (2)
 277 .BR PR_CAPBSET_DROP );
 278 make changes to the
 279 .I securebits
 280 flags.
 281 .TP
 282 .B CAP_SETUID
 283 Make arbitrary manipulations of process UIDs
 284 .RB ( setuid (2),
 285 .BR setreuid (2),
 286 .BR setresuid (2),
 287 .BR setfsuid (2));
 288 forge UID when passing socket credentials via UNIX domain sockets;
 289 write a user ID mapping in a user namespace (see
 290 .BR user_namespaces (7)).
 291 .\" FIXME CAP_SETUID also an effect in exec(); document this.
 292 .TP
 293 .B CAP_SYS_ADMIN
 294 .PD 0
 295 .RS
 296 .IP * 2
 297 Perform a range of system administration operations including:
 298 .BR quotactl (2),
 299 .BR mount (2),
 300 .BR umount (2),
 301 .BR swapon (2),
 302 .BR swapoff (2),
 303 .BR sethostname (2),
 304 and
 305 .BR setdomainname (2);
 306 .IP *
 307 perform privileged
 308 .BR syslog (2)
 309 operations (since Linux 2.6.37,
 310 .BR CAP_SYSLOG
 311 should be used to permit such operations);
 312 .IP *
 313 perform
 314 .B VM86_REQUEST_IRQ
 315 .BR vm86 (2)
 316 command;
 317 .IP *
 318 perform
 319 .B IPC_SET
 320 and
 321 .B IPC_RMID
 322 operations on arbitrary System V IPC objects;
 323 .IP *
 324 override
 325 .B RLIMIT_NPROC
 326 resource limit;
 327 .IP *
 328 perform operations on
 329 .I trusted
 330 and
 331 .I security
 332 Extended Attributes (see
 333 .BR attr (5));
 334 .IP *
 335 use
 336 .BR lookup_dcookie (2);
 337 .IP *
 338 use
 339 .BR ioprio_set (2)
 340 to assign
 341 .B IOPRIO_CLASS_RT
 342 and (before Linux 2.6.25)
 343 .B IOPRIO_CLASS_IDLE
 344 I/O scheduling classes;
 345 .IP *
 346 forge PID when passing socket credentials via UNIX domain sockets;
 347 .IP *
 348 exceed
 349 .IR /proc/sys/fs/file-max ,
 350 the system-wide limit on the number of open files,
 351 in system calls that open files (e.g.,
 352 .BR accept (2),
 353 .BR execve (2),
 354 .BR open (2),
 355 .BR pipe (2));
 356 .IP *
 357 employ
 358 .B CLONE_*
 359 flags that create new namespaces with
 360 .BR clone (2)
 361 and
 362 .BR unshare (2)
 363 (but, since Linux 3.8,
 364 creating user namespaces does not require any capability);
 365 .IP *
 366 call
 367 .BR perf_event_open (2);
 368 .IP *
 369 access privileged
 370 .I perf
 371 event information;
 372 .IP *
 373 call
 374 .BR setns (2)
 375 (requires
 376 .B CAP_SYS_ADMIN
 377 in the
 378 .I target
 379 namespace);
 380 .IP *
 381 call
 382 .BR fanotify_init (2);
 383 .IP *
 384 perform
 385 .B KEYCTL_CHOWN
 386 and
 387 .B KEYCTL_SETPERM
 388 .BR keyctl (2)
 389 operations;
 390 .IP *
 391 perform
 392 .BR madvise (2)
 393 .B MADV_HWPOISON
 394 operation;
 395 .IP *
 396 employ the
 397 .B TIOCSTI
 398 .BR ioctl (2)
 399 to insert characters into the input queue of a terminal other than
 400 the caller's controlling terminal;
 401 .IP *
 402 employ the obsolete
 403 .BR nfsservctl (2)
 404 system call;
 405 .IP *
 406 employ the obsolete
 407 .BR bdflush (2)
 408 system call;
 409 .IP *
 410 perform various privileged block-device
 411 .BR ioctl (2)
 412 operations;
 413 .IP *
 414 perform various privileged filesystem
 415 .BR ioctl (2)
 416 operations;
 417 .IP *
 418 perform administrative operations on many device drivers.
 419 .RE
 420 .PD
 421 .TP
 422 .B CAP_SYS_BOOT
 423 Use
 424 .BR reboot (2)
 425 and
 426 .BR kexec_load (2).
 427 .TP
 428 .B CAP_SYS_CHROOT
 429 Use
 430 .BR chroot (2).
 431 .TP
 432 .B CAP_SYS_MODULE
 433 Load and unload kernel modules
 434 (see
 435 .BR init_module (2)
 436 and
 437 .BR delete_module (2));
 438 in kernels before 2.6.25:
 439 drop capabilities from the system-wide capability bounding set.
 440 .TP
 441 .B CAP_SYS_NICE
 442 .PD 0
 443 .RS
 444 .IP * 2
 445 Raise process nice value
 446 .RB ( nice (2),
 447 .BR setpriority (2))
 448 and change the nice value for arbitrary processes;
 449 .IP *
 450 set real-time scheduling policies for calling process,
 451 and set scheduling policies and priorities for arbitrary processes
 452 .RB ( sched_setscheduler (2),
 453 .BR sched_setparam (2),
 454 .BR shed_setattr (2));
 455 .IP *
 456 set CPU affinity for arbitrary processes
 457 .RB ( sched_setaffinity (2));
 458 .IP *
 459 set I/O scheduling class and priority for arbitrary processes
 460 .RB ( ioprio_set (2));
 461 .IP *
 462 apply
 463 .BR migrate_pages (2)
 464 to arbitrary processes and allow processes
 465 to be migrated to arbitrary nodes;
 466 .\" FIXME CAP_SYS_NICE also has the following effect for
 467 .\" migrate_pages(2):
 468 .\"     do_migrate_pages(mm, &old, &new,
 469 .\"         capable(CAP_SYS_NICE) ? MPOL_MF_MOVE_ALL : MPOL_MF_MOVE);
 470 .\" Document this.
 471 .IP *
 472 apply
 473 .BR move_pages (2)
 474 to arbitrary processes;
 475 .IP *
 476 use the
 477 .B MPOL_MF_MOVE_ALL
 478 flag with
 479 .BR mbind (2)
 480 and
 481 .BR move_pages (2).
 482 .RE
 483 .PD
 484 .TP
 485 .B CAP_SYS_PACCT
 486 Use
 487 .BR acct (2).
 488 .TP
 489 .B CAP_SYS_PTRACE
 490 .PD 0
 491 .RS
 492 .IP * 3
 493 Trace arbitrary processes using
 494 .BR ptrace (2);
 495 .IP *
 496 apply
 497 .BR get_robust_list (2)
 498 to arbitrary processes;
 499 .IP *
 500 transfer data to or from the memory of arbitrary processes using
 501 .BR process_vm_readv (2)
 502 and
 503 .BR process_vm_writev (2).
 504 .IP *
 505 inspect processes using
 506 .BR kcmp (2).
 507 .RE
 508 .PD
 509 .TP
 510 .B CAP_SYS_RAWIO
 511 .PD 0
 512 .RS
 513 .IP * 2
 514 Perform I/O port operations
 515 .RB ( iopl (2)
 516 and
 517 .BR ioperm (2));
 518 .IP *
 519 access
 520 .IR /proc/kcore ;
 521 .IP *
 522 employ the
 523 .B FIBMAP
 524 .BR ioctl (2)
 525 operation;
 526 .IP *
 527 open devices for accessing x86 model-specific registers (MSRs, see
 528 .BR msr (4))
 529 .IP *
 530 update
 531 .IR /proc/sys/vm/mmap_min_addr ;
 532 .IP *
 533 create memory mappings at addresses below the value specified by
 534 .IR /proc/sys/vm/mmap_min_addr ;
 535 .IP *
 536 map files in
 537 .IR /proc/bus/pci ;
 538 .IP *
 539 open
 540 .IR /dev/mem
 541 and
 542 .IR /dev/kmem ;
 543 .IP *
 544 perform various SCSI device commands;
 545 .IP *
 546 perform certain operations on
 547 .BR hpsa (4)
 548 and
 549 .BR cciss (4)
 550 devices;
 551 .IP *
 552 perform a range of device-specific operations on other devices.
 553 .RE
 554 .PD
 555 .TP
 556 .B CAP_SYS_RESOURCE
 557 .PD 0
 558 .RS
 559 .IP * 2
 560 Use reserved space on ext2 filesystems;
 561 .IP *
 562 make
 563 .BR ioctl (2)
 564 calls controlling ext3 journaling;
 565 .IP *
 566 override disk quota limits;
 567 .IP *
 568 increase resource limits (see
 569 .BR setrlimit (2));
 570 .IP *
 571 override
 572 .B RLIMIT_NPROC
 573 resource limit;
 574 .IP *
 575 override maximum number of consoles on console allocation;
 576 .IP *
 577 override maximum number of keymaps;
 578 .IP *
 579 allow more than 64hz interrupts from the real-time clock;
 580 .IP *
 581 raise
 582 .I msg_qbytes
 583 limit for a System V message queue above the limit in
 584 .I /proc/sys/kernel/msgmnb
 585 (see
 586 .BR msgop (2)
 587 and
 588 .BR msgctl (2));
 589 .IP *
 590 override the
 591 .I /proc/sys/fs/pipe-size-max
 592 limit when setting the capacity of a pipe using the
 593 .B F_SETPIPE_SZ
 594 .BR fcntl (2)
 595 command.
 596 .IP *
 597 use
 598 .BR F_SETPIPE_SZ
 599 to increase the capacity of a pipe above the limit specified by
 600 .IR /proc/sys/fs/pipe-max-size ;
 601 .IP *
 602 override
 603 .I /proc/sys/fs/mqueue/queues_max
 604 limit when creating POSIX message queues (see
 605 .BR mq_overview (7));
 606 .IP *
 607 employ
 608 .BR prctl (2)
 609 .B PR_SET_MM
 610 operation;
 611 .IP *
 612 set
 613 .IR /proc/PID/oom_score_adj
 614 to a value lower than the value last set by a process with
 615 .BR CAP_SYS_RESOURCE .
 616 .RE
 617 .PD
 618 .TP
 619 .B CAP_SYS_TIME
 620 Set system clock
 621 .RB ( settimeofday (2),
 622 .BR stime (2),
 623 .BR adjtimex (2));
 624 set real-time (hardware) clock.
 625 .TP
 626 .B CAP_SYS_TTY_CONFIG
 627 Use
 628 .BR vhangup (2);
 629 employ various privileged
 630 .BR ioctl (2)
 631 operations on virtual terminals.
 632 .TP
 633 .BR CAP_SYSLOG " (since Linux 2.6.37)"
 634 .RS
 635 .PD 0
 636 .IP * 3
 637 Perform privileged
 638 .BR syslog (2)
 639 operations.
 640 See
 641 .BR syslog (2)
 642 for information on which operations require privilege.
 643 .IP *
 644 View kernel addresses exposed via
 645 .I /proc
 646 and other interfaces when
 647 .IR /proc/sys/kernel/kptr_restrict
 648 has the value 1.
 649 (See the discussion of the
 650 .I kptr_restrict
 651 in
 652 .BR proc (5).)
 653 .PD
 654 .RE
 655 .TP
 656 .BR CAP_WAKE_ALARM " (since Linux 3.0)"
 657 Trigger something that will wake up the system (set
 658 .B CLOCK_REALTIME_ALARM
 659 and
 660 .B CLOCK_BOOTTIME_ALARM
 661 timers).
 662 .\"
 663 .SS Past and current implementation
 664 A full implementation of capabilities requires that:
 665 .IP 1. 3
 666 For all privileged operations,
 667 the kernel must check whether the thread has the required
 668 capability in its effective set.
 669 .IP 2.
 670 The kernel must provide system calls allowing a thread's capability sets to
 671 be changed and retrieved.
 672 .IP 3.
 673 The filesystem must support attaching capabilities to an executable file,
 674 so that a process gains those capabilities when the file is executed.
 675 .PP
 676 Before kernel 2.6.24, only the first two of these requirements are met;
 677 since kernel 2.6.24, all three requirements are met.
 678 .\"
 679 .SS Thread capability sets
 680 Each thread has three capability sets containing zero or more
 681 of the above capabilities:
 682 .TP
 683 .IR Permitted :
 684 This is a limiting superset for the effective
 685 capabilities that the thread may assume.
 686 It is also a limiting superset for the capabilities that
 687 may be added to the inheritable set by a thread that does not have the
 688 .B CAP_SETPCAP
 689 capability in its effective set.
 690
 691 If a thread drops a capability from its permitted set,
 692 it can never reacquire that capability (unless it
 693 .BR execve (2)s
 694 either a set-user-ID-root program, or
 695 a program whose associated file capabilities grant that capability).
 696 .TP
 697 .IR Inheritable :
 698 This is a set of capabilities preserved across an
 699 .BR execve (2).
 700 It provides a mechanism for a process to assign capabilities
 701 to the permitted set of the new program during an
 702 .BR execve (2).
 703 .TP
 704 .IR Effective :
 705 This is the set of capabilities used by the kernel to
 706 perform permission checks for the thread.
 707 .PP
 708 A child created via
 709 .BR fork (2)
 710 inherits copies of its parent's capability sets.
 711 See below for a discussion of the treatment of capabilities during
 712 .BR execve (2).
 713 .PP
 714 Using
 715 .BR capset (2),
 716 a thread may manipulate its own capability sets (see below).
 717 .PP
 718 Since Linux 3.2, the file
 719 .I /proc/sys/kernel/cap_last_cap
 720 .\" commit 73efc0394e148d0e15583e13712637831f926720
 721 exposes the numerical value of the highest capability
 722 supported by the running kernel;
 723 this can be used to determine the highest bit
 724 that may be set in a capability set.
 725 .\"
 726 .SS File capabilities
 727 Since kernel 2.6.24, the kernel supports
 728 associating capability sets with an executable file using
 729 .BR setcap (8).
 730 The file capability sets are stored in an extended attribute (see
 731 .BR setxattr (2))
 732 named
 733 .IR "security.capability" .
 734 Writing to this extended attribute requires the
 735 .BR CAP_SETFCAP
 736 capability.
 737 The file capability sets,
 738 in conjunction with the capability sets of the thread,
 739 determine the capabilities of a thread after an
 740 .BR execve (2).
 741
 742 The three file capability sets are:
 743 .TP
 744 .IR Permitted " (formerly known as " forced ):
 745 These capabilities are automatically permitted to the thread,
 746 regardless of the thread's inheritable capabilities.
 747 .TP
 748 .IR Inheritable " (formerly known as " allowed ):
 749 This set is ANDed with the thread's inheritable set to determine which
 750 inheritable capabilities are enabled in the permitted set of
 751 the thread after the
 752 .BR execve (2).
 753 .TP
 754 .IR Effective :
 755 This is not a set, but rather just a single bit.
 756 If this bit is set, then during an
 757 .BR execve (2)
 758 all of the new permitted capabilities for the thread are
 759 also raised in the effective set.
 760 If this bit is not set, then after an
 761 .BR execve (2),
 762 none of the new permitted capabilities is in the new effective set.
 763
 764 Enabling the file effective capability bit implies
 765 that any file permitted or inheritable capability that causes a
 766 thread to acquire the corresponding permitted capability during an
 767 .BR execve (2)
 768 (see the transformation rules described below) will also acquire that
 769 capability in its effective set.
 770 Therefore, when assigning capabilities to a file
 771 .RB ( setcap (8),
 772 .BR cap_set_file (3),
 773 .BR cap_set_fd (3)),
 774 if we specify the effective flag as being enabled for any capability,
 775 then the effective flag must also be specified as enabled
 776 for all other capabilities for which the corresponding permitted or
 777 inheritable flags is enabled.
 778 .\"
 779 .SS Transformation of capabilities during execve()
 780 .PP
 781 During an
 782 .BR execve (2),
 783 the kernel calculates the new capabilities of
 784 the process using the following algorithm:
 785 .in +4n
 786 .nf
 787
 788 P'(permitted) = (P(inheritable) & F(inheritable)) |
 789                 (F(permitted) & cap_bset)
 790
 791 P'(effective) = F(effective) ? P'(permitted) : 0
 792
 793 P'(inheritable) = P(inheritable)    [i.e., unchanged]
 794
 795 .fi
 796 .in
 797 where:
 798 .RS 4
 799 .IP P 10
 800 denotes the value of a thread capability set before the
 801 .BR execve (2)
 802 .IP P'
 803 denotes the value of a capability set after the
 804 .BR execve (2)
 805 .IP F
 806 denotes a file capability set
 807 .IP cap_bset
 808 is the value of the capability bounding set (described below).
 809 .RE
 810 .\"
 811 .SS Capabilities and execution of programs by root
 812 In order to provide an all-powerful
 813 .I root
 814 using capability sets, during an
 815 .BR execve (2):
 816 .IP 1. 3
 817 If a set-user-ID-root program is being executed,
 818 or the real user ID of the process is 0 (root)
 819 then the file inheritable and permitted sets are defined to be all ones
 820 (i.e., all capabilities enabled).
 821 .IP 2.
 822 If a set-user-ID-root program is being executed,
 823 then the file effective bit is defined to be one (enabled).
 824 .PP
 825 The upshot of the above rules,
 826 combined with the capabilities transformations described above,
 827 is that when a process
 828 .BR execve (2)s
 829 a set-user-ID-root program, or when a process with an effective UID of 0
 830 .BR execve (2)s
 831 a program,
 832 it gains all capabilities in its permitted and effective capability sets,
 833 except those masked out by the capability bounding set.
 834 .\" If a process with real UID 0, and nonzero effective UID does an
 835 .\" exec(), then it gets all capabilities in its
 836 .\" permitted set, and no effective capabilities
 837 This provides semantics that are the same as those provided by
 838 traditional UNIX systems.
 839 .SS Capability bounding set
 840 The capability bounding set is a security mechanism that can be used
 841 to limit the capabilities that can be gained during an
 842 .BR execve (2).
 843 The bounding set is used in the following ways:
 844 .IP * 2
 845 During an
 846 .BR execve (2),
 847 the capability bounding set is ANDed with the file permitted
 848 capability set, and the result of this operation is assigned to the
 849 thread's permitted capability set.
 850 The capability bounding set thus places a limit on the permitted
 851 capabilities that may be granted by an executable file.
 852 .IP *
 853 (Since Linux 2.6.25)
 854 The capability bounding set acts as a limiting superset for
 855 the capabilities that a thread can add to its inheritable set using
 856 .BR capset (2).
 857 This means that if a capability is not in the bounding set,
 858 then a thread can't add this capability to its
 859 inheritable set, even if it was in its permitted capabilities,
 860 and thereby cannot have this capability preserved in its
 861 permitted set when it
 862 .BR execve (2)s
 863 a file that has the capability in its inheritable set.
 864 .PP
 865 Note that the bounding set masks the file permitted capabilities,
 866 but not the inherited capabilities.
 867 If a thread maintains a capability in its inherited set
 868 that is not in its bounding set,
 869 then it can still gain that capability in its permitted set
 870 by executing a file that has the capability in its inherited set.
 871 .PP
 872 Depending on the kernel version, the capability bounding set is either
 873 a system-wide attribute, or a per-process attribute.
 874 .PP
 875 .B "Capability bounding set prior to Linux 2.6.25"
 876 .PP
 877 In kernels before 2.6.25, the capability bounding set is a system-wide
 878 attribute that affects all threads on the system.
 879 The bounding set is accessible via the file
 880 .IR /proc/sys/kernel/cap-bound .
 881 (Confusingly, this bit mask parameter is expressed as a
 882 signed decimal number in
 883 .IR /proc/sys/kernel/cap-bound .)
 884
 885 Only the
 886 .B init
 887 process may set capabilities in the capability bounding set;
 888 other than that, the superuser (more precisely: programs with the
 889 .B CAP_SYS_MODULE
 890 capability) may only clear capabilities from this set.
 891
 892 On a standard system the capability bounding set always masks out the
 893 .B CAP_SETPCAP
 894 capability.
 895 To remove this restriction (dangerous!), modify the definition of
 896 .B CAP_INIT_EFF_SET
 897 in
 898 .I include/linux/capability.h
 899 and rebuild the kernel.
 900
 901 The system-wide capability bounding set feature was added
 902 to Linux starting with kernel version 2.2.11.
 903 .\"
 904 .PP
 905 .B "Capability bounding set from Linux 2.6.25 onward"
 906 .PP
 907 From Linux 2.6.25, the
 908 .I "capability bounding set"
 909 is a per-thread attribute.
 910 (There is no longer a system-wide capability bounding set.)
 911
 912 The bounding set is inherited at
 913 .BR fork (2)
 914 from the thread's parent, and is preserved across an
 915 .BR execve (2).
 916
 917 A thread may remove capabilities from its capability bounding set using the
 918 .BR prctl (2)
 919 .B PR_CAPBSET_DROP
 920 operation, provided it has the
 921 .B CAP_SETPCAP
 922 capability.
 923 Once a capability has been dropped from the bounding set,
 924 it cannot be restored to that set.
 925 A thread can determine if a capability is in its bounding set using the
 926 .BR prctl (2)
 927 .B PR_CAPBSET_READ
 928 operation.
 929
 930 Removing capabilities from the bounding set is supported only if file
 931 capabilities are compiled into the kernel.
 932 In kernels before Linux 2.6.33,
 933 file capabilities were an optional feature configurable via the
 934 .B CONFIG_SECURITY_FILE_CAPABILITIES
 935 option.
 936 Since Linux 2.6.33, the configuration option has been removed
 937 and file capabilities are always part of the kernel.
 938 When file capabilities are compiled into the kernel, the
 939 .B init
 940 process (the ancestor of all processes) begins with a full bounding set.
 941 If file capabilities are not compiled into the kernel, then
 942 .B init
 943 begins with a full bounding set minus
 944 .BR CAP_SETPCAP ,
 945 because this capability has a different meaning when there are
 946 no file capabilities.
 947
 948 Removing a capability from the bounding set does not remove it
 949 from the thread's inherited set.
 950 However it does prevent the capability from being added
 951 back into the thread's inherited set in the future.
 952 .\"
 953 .\"
 954 .SS Effect of user ID changes on capabilities
 955 To preserve the traditional semantics for transitions between
 956 0 and nonzero user IDs,
 957 the kernel makes the following changes to a thread's capability
 958 sets on changes to the thread's real, effective, saved set,
 959 and filesystem user IDs (using
 960 .BR setuid (2),
 961 .BR setresuid (2),
 962 or similar):
 963 .IP 1. 3
 964 If one or more of the real, effective or saved set user IDs
 965 was previously 0, and as a result of the UID changes all of these IDs
 966 have a nonzero value,
 967 then all capabilities are cleared from the permitted and effective
 968 capability sets.
 969 .IP 2.
 970 If the effective user ID is changed from 0 to nonzero,
 971 then all capabilities are cleared from the effective set.
 972 .IP 3.
 973 If the effective user ID is changed from nonzero to 0,
 974 then the permitted set is copied to the effective set.
 975 .IP 4.
 976 If the filesystem user ID is changed from 0 to nonzero (see
 977 .BR setfsuid (2)),
 978 then the following capabilities are cleared from the effective set:
 979 .BR CAP_CHOWN ,
 980 .BR CAP_DAC_OVERRIDE ,
 981 .BR CAP_DAC_READ_SEARCH ,
 982 .BR CAP_FOWNER ,
 983 .BR CAP_FSETID ,
 984 .B CAP_LINUX_IMMUTABLE
 985 (since Linux 2.6.30),
 986 .BR CAP_MAC_OVERRIDE ,
 987 and
 988 .B CAP_MKNOD
 989 (since Linux 2.6.30).
 990 If the filesystem UID is changed from nonzero to 0,
 991 then any of these capabilities that are enabled in the permitted set
 992 are enabled in the effective set.
 993 .PP
 994 If a thread that has a 0 value for one or more of its user IDs wants
 995 to prevent its permitted capability set being cleared when it resets
 996 all of its user IDs to nonzero values, it can do so using the
 997 .BR prctl (2)
 998 .B PR_SET_KEEPCAPS
 999 operation.
1000 .\"
1001 .SS Programmatically adjusting capability sets
1002 A thread can retrieve and change its capability sets using the
1003 .BR capget (2)
1004 and
1005 .BR capset (2)
1006 system calls.
1007 However, the use of
1008 .BR cap_get_proc (3)
1009 and
1010 .BR cap_set_proc (3),
1011 both provided in the
1012 .I libcap
1013 package,
1014 is preferred for this purpose.
1015 The following rules govern changes to the thread capability sets:
1016 .IP 1. 3
1017 If the caller does not have the
1018 .B CAP_SETPCAP
1019 capability,
1020 the new inheritable set must be a subset of the combination
1021 of the existing inheritable and permitted sets.
1022 .IP 2.
1023 (Since Linux 2.6.25)
1024 The new inheritable set must be a subset of the combination of the
1025 existing inheritable set and the capability bounding set.
1026 .IP 3.
1027 The new permitted set must be a subset of the existing permitted set
1028 (i.e., it is not possible to acquire permitted capabilities
1029 that the thread does not currently have).
1030 .IP 4.
1031 The new effective set must be a subset of the new permitted set.
1032 .SS The securebits flags: establishing a capabilities-only environment
1033 .\" For some background:
1034 .\"       see http://lwn.net/Articles/280279/ and
1035 .\"       http://article.gmane.org/gmane.linux.kernel.lsm/5476/
1036 Starting with kernel 2.6.26,
1037 and with a kernel in which file capabilities are enabled,
1038 Linux implements a set of per-thread
1039 .I securebits
1040 flags that can be used to disable special handling of capabilities for UID 0
1041 .RI ( root ).
1042 These flags are as follows:
1043 .TP
1044 .B SECBIT_KEEP_CAPS
1045 Setting this flag allows a thread that has one or more 0 UIDs to retain
1046 its capabilities when it switches all of its UIDs to a nonzero value.
1047 If this flag is not set,
1048 then such a UID switch causes the thread to lose all capabilities.
1049 This flag is always cleared on an
1050 .BR execve (2).
1051 (This flag provides the same functionality as the older
1052 .BR prctl (2)
1053 .B PR_SET_KEEPCAPS
1054 operation.)
1055 .TP
1056 .B SECBIT_NO_SETUID_FIXUP
1057 Setting this flag stops the kernel from adjusting capability sets when
1058 the threads's effective and filesystem UIDs are switched between
1059 zero and nonzero values.
1060 (See the subsection
1061 .IR "Effect of User ID Changes on Capabilities" .)
1062 .TP
1063 .B SECBIT_NOROOT
1064 If this bit is set, then the kernel does not grant capabilities
1065 when a set-user-ID-root program is executed, or when a process with
1066 an effective or real UID of 0 calls
1067 .BR execve (2).
1068 (See the subsection
1069 .IR "Capabilities and execution of programs by root" .)
1070 .PP
1071 Each of the above "base" flags has a companion "locked" flag.
1072 Setting any of the "locked" flags is irreversible,
1073 and has the effect of preventing further changes to the
1074 corresponding "base" flag.
1075 The locked flags are:
1076 .BR SECBIT_KEEP_CAPS_LOCKED ,
1077 .BR SECBIT_NO_SETUID_FIXUP_LOCKED ,
1078 and
1079 .BR SECBIT_NOROOT_LOCKED .
1080 .PP
1081 The
1082 .I securebits
1083 flags can be modified and retrieved using the
1084 .BR prctl (2)
1085 .B PR_SET_SECUREBITS
1086 and
1087 .B PR_GET_SECUREBITS
1088 operations.
1089 The
1090 .B CAP_SETPCAP
1091 capability is required to modify the flags.
1092
1093 The
1094 .I securebits
1095 flags are inherited by child processes.
1096 During an
1097 .BR execve (2),
1098 all of the flags are preserved, except
1099 .B SECBIT_KEEP_CAPS
1100 which is always cleared.
1101
1102 An application can use the following call to lock itself,
1103 and all of its descendants,
1104 into an environment where the only way of gaining capabilities
1105 is by executing a program with associated file capabilities:
1106 .in +4n
1107 .nf
1108
1109 prctl(PR_SET_SECUREBITS,
1110         SECBIT_KEEP_CAPS_LOCKED |
1111         SECBIT_NO_SETUID_FIXUP |
1112         SECBIT_NO_SETUID_FIXUP_LOCKED |
1113         SECBIT_NOROOT |
1114         SECBIT_NOROOT_LOCKED);
1115 .fi
1116 .in
1117 .SS Interaction with user namespaces
1118 For a discussion of the interaction of capabilities and user namespaces, see
1119 .BR user_namespaces (7).
1120 .SH CONFORMING TO
1121 .PP
1122 No standards govern capabilities, but the Linux capability implementation
1123 is based on the withdrawn POSIX.1e draft standard; see
1124 .UR http://wt.tuxomania.net\:/publications\:/posix.1e/
1125 .UE .
1126 .SH NOTES
1127 Since kernel 2.5.27, capabilities are an optional kernel component,
1128 and can be enabled/disabled via the
1129 .B CONFIG_SECURITY_CAPABILITIES
1130 kernel configuration option.
1131
1132 The
1133 .I /proc/PID/task/TID/status
1134 file can be used to view the capability sets of a thread.
1135 The
1136 .I /proc/PID/status
1137 file shows the capability sets of a process's main thread.
1138 Before Linux 3.8, nonexistent capabilities were shown as being
1139 enabled (1) in these sets.
1140 Since Linux 3.8,
1141 .\" 7b9a7ec565505699f503b4fcf61500dceb36e744
1142 all nonexistent capabilities (above
1143 .BR CAP_LAST_CAP )
1144 are shown as disabled (0).
1145
1146 The
1147 .I libcap
1148 package provides a suite of routines for setting and
1149 getting capabilities that is more comfortable and less likely
1150 to change than the interface provided by
1151 .BR capset (2)
1152 and
1153 .BR capget (2).
1154 This package also provides the
1155 .BR setcap (8)
1156 and
1157 .BR getcap (8)
1158 programs.
1159 It can be found at
1160 .br
1161 .UR http://www.kernel.org\:/pub\:/linux\:/libs\:/security\:/linux-privs
1162 .UE .
1163
1164 Before kernel 2.6.24, and since kernel 2.6.24 if
1165 file capabilities are not enabled, a thread with the
1166 .B CAP_SETPCAP
1167 capability can manipulate the capabilities of threads other than itself.
1168 However, this is only theoretically possible,
1169 since no thread ever has
1170 .BR CAP_SETPCAP
1171 in either of these cases:
1172 .IP * 2
1173 In the pre-2.6.25 implementation the system-wide capability bounding set,
1174 .IR /proc/sys/kernel/cap-bound ,
1175 always masks out this capability, and this can not be changed
1176 without modifying the kernel source and rebuilding.
1177 .IP *
1178 If file capabilities are disabled in the current implementation, then
1179 .B init
1180 starts out with this capability removed from its per-process bounding
1181 set, and that bounding set is inherited by all other processes
1182 created on the system.
1183 .SH SEE ALSO
1184 .BR capsh (1),
1185 .BR setpriv (2),
1186 .BR prctl (2),
1187 .BR setfsuid (2),
1188 .BR cap_clear (3),
1189 .BR cap_copy_ext (3),
1190 .BR cap_from_text (3),
1191 .BR cap_get_file (3),
1192 .BR cap_get_proc (3),
1193 .BR cap_init (3),
1194 .BR capgetp (3),
1195 .BR capsetp (3),
1196 .BR libcap (3),
1197 .BR credentials (7),
1198 .BR user_namespaces (7),
1199 .BR pthreads (7),
1200 .BR getcap (8),
1201 .BR setcap (8)
1202 .PP
1203 .I include/linux/capability.h
1204 in the Linux kernel source tree
1205 .SH COLOPHON
1206 This page is part of release 3.79 of the Linux
1207 .I man-pages
1208 project.
1209 A description of the project,
1210 information about reporting bugs,
1211 and the latest version of this page,
1212 can be found at
1213 \%http://www.kernel.org/doc/man\-pages/.