linux_capability_on_program_file

A program that needs one privileged operation, such as sending raw network packets, can get a Linux capability instead of running as root. linux_capability_on_program_file gives a program file Linux capabilities, through getcap and setcap on the node. The listed capabilities become permitted and effective. The required capabilities_not_listed says whether other capabilities are removed (remove) or kept with their flags (keep).

A service that needs a capability gets it more simply from its unit (AmbientCapabilities= in a drop-in that systemd_unit installs), which a package upgrade cannot remove. This module is for the other cases.

Set up

getcap and setcap are in the package libcap2-bin on Debian and Ubuntu, and libcap on the Red Hat family:

- when: {equals: ["{{ .node.package_manager }}", apt]}
  apt_package: {packages: [{name: libcap2-bin, version: newest_when_first_installed}]}
- when: {equals: ["{{ .node.package_manager }}", dnf]}
  dnf_package: {packages: [{name: libcap, version: newest_when_first_installed}]}

Inputs

  • path (string; required): absolute path of a regular file, not a symbolic link
  • capabilities (list; optional): names as capabilities(7) lists them, such as cap_net_raw; listed capabilities become permitted and effective; required unless state: absent
  • capabilities_not_listed (remove or keep; required): required unless state: absent; remove removes unlisted capabilities, keep preserves their existing flags. Linux stores one effective flag for the whole file, so when an unlisted capability lacks it, setcap refuses the result and the task fails with setcap's message
  • state (present or absent; default present): absent removes every capability and accepts only path

Outputs

The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.

  • status
  • change
  • value.capabilities_before
  • value.capabilities_after

What a dryrun reports

Supported; shows the capabilities before and after; fails if keep would leave an unlisted capability without the file-wide effective flag; not checked while the file or setcap is missing.

Retries and time limits

Bounded automatic retries by default; retry: false turns them off.

The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.

Examples

Let a program send raw network packets

- linux_capability_on_program_file:
    capabilities_not_listed: remove
    path: /usr/local/bin/pinger
    capabilities: [cap_net_raw]

On the node, MMX reads the capabilities of /usr/local/bin/pinger with getcap. When the capabilities of /usr/local/bin/pinger differ from cap_net_raw, permitted and effective, MMX sets the file's capabilities with setcap. The result shows value.capabilities_before and value.capabilities_after as getcap prints them, such as cap_net_raw=ep. A run where setcap fails shows no value, because the capabilities did not change, so a node task in on_failure can read what happened.

Remove every capability

- linux_capability_on_program_file:
    path: /usr/local/bin/pinger
    state: absent

state: absent takes only path and removes every capability of the file.

How it works

Installing a new version of the program replaces the file and drops its capabilities. The node task checks on every run and sets them again, so put it after the node task that installs the program, in the same node task block.

Linux stores one effective flag for the whole file, so when an unlisted capability lacks that flag, setcap refuses the result and the task fails with setcap's message. Dryrun reports this unsupported combination without running setcap.

MMX refuses a symbolic link at the path.

Errors and what they mean

The reason holds What the error means, and what to do
setcap is not installed; install the package libcap2-bin (Debian and Ubuntu) or libcap (Red Hat family) first Install the package in an earlier node task; see Set up. The same holds for getcap. A dryrun reports the node task not checked, because an earlier node task may install the package.
/usr/local/bin/pinger does not exist yet The program file is missing. A dryrun reports the node task not checked, because an earlier node task may install the program.
... is a symbolic link; give the path of the program file itself Write the path of the program file itself.

Tested on

Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10.

The suite tests/integration/access_control_lists_and_capabilities.py runs on Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, and AlmaLinux 10, in containers on the first four and in virtual machines on the last two. The validation record has the latest results.

Why it works this way

  • The task states what happens to unlisted capabilities. Requiring an explicit choice about unlisted capabilities follows the list-ownership rule, so adding one capability does not silently discard another.
  • The task checks on every run. A package upgrade replaces the program file and drops its capabilities, and the next run sets them again.

This page is docs/reference/modules/linux_capability_on_program_file.md in the MMX repository.