community.general.capabilities module – Manage Linux capabilities

Note

This module is part of the community.general collection (version 14.0.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.capabilities.

Synopsis

  • This module manipulates files privileges using the Linux capabilities(7) system.

Parameters

Parameter

Comments

capability

aliases: cap

string / required

Desired capability to set (with operator and flags, if state=present) or remove (if state=absent).

The value is passed to setcap as is, so it accepts the same syntax, including setting several capabilities at once (for example cap_chown,cap_fowner+ep).

path

aliases: key

string / required

Specifies the path to the file to be managed.

state

string

Whether the entry should be present or absent in the file’s capabilities.

Choices:

  • "absent"

  • "present" ← (default)

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Returns details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Notes

Note

  • Whether a change is required is determined with setcap --verify, so a task is reported as changed only when the capabilities on path actually differ from the request, regardless of how the local libcap version normalizes operators and flags (some versions turn cap_foo+ep into cap_foo=ep).

  • When state=present, capabilities already set on path that are not listed in capability are left untouched.

Examples

- name: Set cap_sys_chroot+ep on /foo
  community.general.capabilities:
    path: /foo
    capability: cap_sys_chroot+ep
    state: present

- name: Remove cap_net_bind_service from /bar
  community.general.capabilities:
    path: /bar
    capability: cap_net_bind_service
    state: absent

Authors

  • Nate Coraor (@natefoo)