ansible.posix.acl module – Set and retrieve file ACL information.

Note

This module is part of the ansible.posix collection (version 1.6.2).

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 ansible.posix.

To use it in a playbook, specify: ansible.posix.acl.

New in ansible.posix 1.0.0

Synopsis

  • Set and retrieve file ACL information.

Parameters

Parameter

Comments

default

boolean

If path is a directory, setting this to true will make it the default ACL for entities created inside the directory.

Setting default=true causes an error if path is a file.

Choices:

  • false ← (default)

  • true

entity

string

The actual user or group that the ACL applies to when matching entity types user or group are selected.

Default: ""

entry

string

DEPRECATED.

The ACL to set or remove.

This must always be quoted in the form of <etype>:<qualifier>:<perms>.

The qualifier may be empty for some types, but the type and perms are always required.

- can be used as placeholder when you do not care about permissions.

This is now superseded by entity, type and permissions fields.

etype

string

The entity type of the ACL to apply, see setfacl documentation for more info.

Choices:

  • "group"

  • "mask"

  • "other"

  • "user"

follow

boolean

Whether to follow symlinks on the path if a symlink is encountered.

Choices:

  • false

  • true ← (default)

path

aliases: name

path / required

The full path of the file or object.

permissions

string

The permissions to apply/remove can be any combination of r, w, x (read, write and execute respectively), and X (execute permission if the file is a directory or already has execute permission for some user)

recalculate_mask

string

Select if and when to recalculate the effective right masks of the files.

See setfacl documentation for more info.

Incompatible with state=query.

Choices:

  • "default" ← (default)

  • "mask"

  • "no_mask"

recursive

aliases: recurse

boolean

Recursively sets the specified ACL.

Incompatible with state=query.

Alias recurse added in version 1.3.0.

Choices:

  • false ← (default)

  • true

state

string

Define whether the ACL should be present or not.

The query state gets the current ACL without changing it, for use in register operations.

Choices:

  • "absent"

  • "present"

  • "query" ← (default)

use_nfsv4_acls

boolean

Use NFSv4 ACLs instead of POSIX ACLs.

This feature uses nfs4_setfacl and nfs4_getfacl. The behavior depends on those implementation. And currently it only supports A in ACE, so D must be replaced with the appropriate A.

Permission is set as optimised ACLs by the system. You can check the actual ACLs that has been set using the return value.

More info man nfs4_setfacl

Choices:

  • false ← (default)

  • true

Notes

Note

  • The ansible.posix.acl module requires that ACLs are enabled on the target filesystem and that the setfacl and getfacl binaries are installed.

  • As of Ansible 2.0, this module only supports Linux distributions.

  • As of Ansible 2.3, the name option has been changed to path as default, but name still works as well.

Examples

- name: Grant user Joe read access to a file
  ansible.posix.acl:
    path: /etc/foo.conf
    entity: joe
    etype: user
    permissions: r
    state: present

- name: Removes the ACL for Joe on a specific file
  ansible.posix.acl:
    path: /etc/foo.conf
    entity: joe
    etype: user
    state: absent

- name: Sets default ACL for joe on /etc/foo.d/
  ansible.posix.acl:
    path: /etc/foo.d/
    entity: joe
    etype: user
    permissions: rw
    default: true
    state: present

- name: Same as previous but using entry shorthand
  ansible.posix.acl:
    path: /etc/foo.d/
    entry: default:user:joe:rw-
    state: present

- name: Obtain the ACL for a specific file
  ansible.posix.acl:
    path: /etc/foo.conf
  register: acl_info

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

acl

list / elements=string

Current ACL on provided path (after changes, if any)

Returned: success

Sample: ["user::rwx", "group::rwx", "other::rwx"]

Authors

  • Brian Coca (@bcoca)

  • Jérémie Astori (@astorije)