← Full reference

capabilities: getcap and setcap

Give a program a single root privilege without setuid — setcap cap_net_bind_service=ep, getcap -r, setcap -r

Root's powers in Linux are split into separate capabilities: open a port below 1024 (cap_net_bind_service), read any file (cap_dac_override), send raw packets (cap_net_raw), and so on. You can write them right into an executable — then the program, started by a regular user, gets only that privilege, not all of root's powers as with setuid. setcap writes them, getcap shows them (package libcap2-bin). They're stored in the security.capability extended attribute.

Syntax

setcap 'cap_name[,cap_name…]=flags' file    # set
setcap -r file                              # remove
getcap file…                                # show
getcap -r directory                         # find all files with capabilities

Flags

FlagSetMeaning
ppermittedthe process is allowed to use the privilege
eeffectivethe privilege is enabled right away at startup; without e the program has to enable it itself
iinheritablecan be passed on through exec (rarely needed)

You almost always write =ep: "allow and enable right away". Operators: = — set exactly these flags, + — add, - — remove. cap_net_raw+ep and cap_net_raw=ep on a file with none give the same result.

Options

CommandWhat it does
setcap -r fileremove all capabilities from the file
setcap -v 'caps' fileverify the capabilities match; file: OK and code 0, otherwise code 1
setcap -q …don't print messages
setcap - fileread capabilities from stdin (until an empty line)
getcap -r directoryrecursive search; files without capabilities aren't printed
getcap -v filealso print files without capabilities
getcap -n fileshow the rootid if the capability is set for a user namespace

Common capabilities

CapabilityWhat it allows
cap_net_bind_servicelisten on ports below 1024 (a web server on 80/443 without root)
cap_net_rawraw sockets: ping, tcpdump, arping
cap_net_adminconfigure networking: interfaces, routes, iptables
cap_dac_overrideignore rwx permissions on files and directories
cap_dac_read_searchread any file and traverse any directory
cap_chown / cap_fownerchange the owner of any file / act as the file's owner
cap_killsend signals to other users' processes
cap_setuid / cap_setgidchange the process UID/GID — effectively root
cap_sys_admin"almost root": mount and a lot more
cap_sys_ptracedebug other processes (strace -p)
cap_sys_niceraise priority (nice below zero)
cap_sys_timechange the system time

Full list — man 7 capabilities. To decode a mask from /proc/PID/status: capsh --decode=0000000000000400.

Reading the output

/usr/bin/ping cap_net_raw=ep
/usr/local/bin/app cap_net_bind_service,cap_net_raw=ep

The path, then the list of capabilities and flags. If a file has none, getcap prints nothing and returns 0. Capabilities are not visible in ls -l — unlike setuid (s) and ACLs (+).

A process's capabilities: the CapPrm/CapEff lines in /proc/PID/status (a hex mask), or capsh --print for the current shell.

Examples

# ping already has a capability — that's why it works without root
getcap /usr/bin/ping

# all files with capabilities on the system (security audit)
getcap -r / 2>/dev/null

# let your server listen on port 80 without root
setcap 'cap_net_bind_service=ep' /usr/local/bin/myserver
getcap /usr/local/bin/myserver

# several capabilities at once
setcap 'cap_net_bind_service,cap_net_raw=ep' /usr/local/bin/myserver

# check in a script that the capability is in place
setcap -v 'cap_net_bind_service=ep' /usr/local/bin/myserver && echo ok

# remove it
setcap -r /usr/local/bin/myserver

# for an interpreter — only on the real file, not on a symbolic link
setcap 'cap_net_bind_service=ep' "$(readlink -f /usr/bin/python3)"

# which capabilities a running process has
grep Cap /proc/$$/status
capsh --decode=$(awk '/CapEff/{print $2}' /proc/$$/status)

Pitfalls

  • setcap replaces the whole set. setcap cap_net_raw+ep file on a file with cap_net_bind_service,cap_net_raw=ep leaves only cap_net_raw. List all the capabilities you need in one command.
  • Without e the privilege isn't enabled for an ordinary program: with =p the file gets the right, but cat or python won't activate it and get "Permission denied". Write =ep.
  • Regular files only. On a symbolic link setcap answers "Invalid file … for capability operation" — use readlink -f.
  • Scripts don't work. Capabilities on a script.sh with #!/bin/bash are ignored: the interpreter runs, and it doesn't have them. Give them to a binary (or to the interpreter — but then any script in that language gets the privilege).
  • Capabilities get lost on chown, on any write to the file (a package upgrade, cp over it), and a plain cp doesn't copy them. cp -a/--preserve=xattr and rsync -X keep them (rsync -a without -X doesn't); tar only with --xattrs when creating and --xattrs --xattrs-include='*' when extracting. After upgrading a program, set them again.
  • Bounding set limit. If a capability isn't in the process's bounding set (normal in a container, e.g. cap_dac_read_search, cap_sys_admin), a file with it won't start at all: "Operation not permitted". Check CapBnd in /proc/self/status.
  • In a Docker container ports below 1024 and ping are available to a regular user anyway: Docker sets net.ipv4.ip_unprivileged_port_start=0 and a wide ping_group_range. Test the effect of cap_net_bind_service on a regular machine, or use a different capability, e.g. cap_dac_override.
  • Only root can set capabilities (it needs cap_setfcap), otherwise "unable to set CAP_SETFCAP effective capability".
  • cap_setuid, cap_sys_admin, cap_dac_override on an interpreter or an editor are equivalent to handing out root — exactly what an audit with getcap -r / looks for.

See also

chmod · acl · sudo · proc · ping · ss