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