acl – Set and retrieve file ACL information

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
-
The 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
-
    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
-
The 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.
Incompatible with state=query.
state
-
    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
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 /etc/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.