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