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

Note

This plugin is part of the ansible.posix collection (version 1.1.1).

To install it use: ansible-galaxy collection install ansible.posix.

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

New in version 1.0.0: of ansible.posix

Synopsis

  • Set and retrieve file ACL information.

Parameters

Parameter Choices/Defaults Comments
default
boolean
    Choices:
  • no ←
  • yes
If the target is a directory, setting this to yes will make it the default ACL for entities created inside the directory.
Setting default to yes causes an error if the path is a file.
entity
string
The actual user or group that the ACL applies to when matching entity types user or group are selected.
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
    Choices:
  • group
  • mask
  • other
  • user
The entity type of the ACL to apply, see setfacl documentation for more info.
follow
boolean
    Choices:
  • no
  • yes ←
Whether to follow symlinks on the path if a symlink is encountered.
path
path / required
The full path of the file or object.

aliases: name
permissions
string
The permissions to apply/remove can be any combination of r, w and x (read, write and execute respectively)
recalculate_mask
string
    Choices:
  • default ←
  • mask
  • no_mask
Select if and when to recalculate the effective right masks of the files.
See setfacl documentation for more info.
Incompatible with state=query.
recursive
boolean
    Choices:
  • no ←
  • yes
Recursively sets the specified ACL.
Incompatible with state=query.
state
string
    Choices:
  • absent
  • present
  • query ←
Define whether the ACL should be present or not.
The query state gets the current ACL without changing it, for use in register operations.
use_nfsv4_acls
boolean
    Choices:
  • no ←
  • yes
Use NFSv4 ACLs instead of POSIX ACLs.

Notes

Note

  • The 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: yes
    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 Returned Description
acl
list / elements=string
success
Current ACL on provided path (after changes, if any)

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


Authors

  • Brian Coca (@bcoca)
  • Jérémie Astori (@astorije)

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.10/collections/ansible/posix/acl_module.html