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
boolean
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
boolean
    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)
recalculate_mask
-
added in 2.7
    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
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
boolean
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

Red Hat Support

More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.

Authors

  • 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.