Documentation

PLEASE NOTE: This document applies to latest version and not to the latest stable release v2.21

Documentation for other releases can be found by using the version selector in the top right of any doc page.

acl

Manage file Access Control Lists (ACLs).

ACLs provide fine-grained permission control beyond standard Unix permissions. They allow per-user and per-group permissions on files and directories. Useful for containers, IoT devices, and multi-user file sharing scenarios.

Attributes

check_mode:
  support: full

Parameters

Parameter	Required	Type	Values	Description
path	true	string		The full path to the file or directory.
user		string		The user to set ACL for (e.g. “nginx”).
group		string		The group to set ACL for (e.g. “developers”).
mode		string		The permissions mode (e.g. “r”, “rw”, “rwx”, “rX”). Required when state=present.
state		string	present absent query	Whether the ACL should exist or not. Use query to retrieve current ACLs without changes. [default: `"present"`]
default		boolean		Set default ACL (inherited by new files in directory). [default: `false`]
recurse		boolean		Apply ACLs recursively to directory contents. [default: `false`]

Examples

- name: Give user nginx read access to a file
  acl:
    path: /etc/app/config.json
    user: nginx
    mode: "r"

- name: Give group developers read-write access
  acl:
    path: /data/project
    group: developers
    mode: "rw"

- name: Set default ACL for directory (inherited by new files)
  acl:
    path: /data/shared
    user: appuser
    mode: "rwx"
    default: true

- name: Remove user ACL entry
  acl:
    path: /data/file.txt
    user: olduser
    state: absent

- name: Query current ACLs
  acl:
    path: /etc/app/config.json
    state: query
  register: file_acls

- name: Apply ACLs recursively
  acl:
    path: /data/project
    user: nginx
    mode: "rX"
    recurse: true