acl – Set and retrieve file ACL information

Synopsis
Parameters
Notes
Examples
Return Values
Status

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

This module is guaranteed to have no backward incompatible 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.

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