acl - Sets and retrieves file ACL information.

New in version 1.4.

Synopsis

  • Sets and retrieves file ACL information.

Parameters

Parameter Choices/Defaults Comments
default
bool

(added in 1.5)
    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. It causes an error if path is a file.
entity
(added in 1.5)
actual user or group that the ACL applies to when matching entity types user or group are selected.
entry
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
(added in 1.5)
    Choices:
  • group
  • mask
  • other
  • user
the entity type of the ACL to apply, see setfacl documentation for more info.
follow
bool
    Choices:
  • no
  • yes ←
whether to follow symlinks on the path if a symlink is encountered.
path
required
The full path of the file or object.

aliases: name
permissions
(added in 1.5)
Permissions to apply/remove can be any combination of r, w and x (read, write and execute respectively)
recursive
bool

(added in 2.0)
    Choices:
  • no ←
  • yes
Recursively sets the specified ACL (added in Ansible 2.0). Incompatible with state=query.
state
    Choices:
  • absent
  • present
  • query ←
defines 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
bool

(added in 2.2)
    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
  acl:
    path: /etc/foo.conf
    entity: joe
    etype: user
    permissions: r
    state: present

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

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

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

- name: Obtain the acl for a specific file
  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
 success
Current acl on provided path (after changes, if any)

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


Status

This module is flagged as stableinterface which means that the maintainers for this module guarantee that no backward incompatible interface changes will be made.

Maintenance

This module is flagged as core which means that it is maintained by the Ansible Core Team. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Core Team, see here.

Support

For more information about Red Hat’s support of this module, please refer to this Knowledge Base article

Author

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

Hint

If you notice any issues in this documentation you can edit this document to improve it.

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