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

• This module is guaranteed to have backward compatible interface changes going forward. [stableinterface]
• This module is maintained by the Ansible Core Team. [core]

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.