original/man7/capabilities.7

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