acl - Sets and retrieves file ACL information.

New in version 1.4.

Synopsis

  • Sets and retrieves file ACL information.

Options

parameter required default choices comments
default
(added in 1.5)
 no
  • yes
  • no
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)
 no
actual user or group that the ACL applies to when matching entity types user or group are selected.
entry
 no
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)
 no
  • user
  • group
  • mask
  • other
the entity type of the ACL to apply, see setfacl documentation for more info.
follow
 no True
  • yes
  • no
whether to follow symlinks on the path if a symlink is encountered.
path
 yes
The full path of the file or object.
aliases: name
permissions
(added in 1.5)
 no
Permissions to apply/remove can be any combination of r, w and x (read, write and execute respectively)
recursive
(added in 2.0)
 no
  • yes
  • no
Recursively sets the specified ACL (added in Ansible 2.0). Incompatible with state=query.
state
 no query
  • query
  • present
  • absent
defines whether the ACL should be present or not. The query state gets the current acl without changing it, for use in 'register' operations.

Examples

# Grant user Joe read access to a file
- acl:
    path: /etc/foo.conf
    entity: joe
    etype: user
    permissions: r
    state: present

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

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

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

# Obtain the acl for a specific file
- acl:
    path: /etc/foo.conf
  register: acl_info

Return Values

Common return values are documented here Return Values, the following are the fields unique to this module:

name description returned type sample
acl
Current acl on provided path (after changes, if any)
 success list ['user::rwx', 'group::rwx', 'other::rwx']

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.

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 Info

For more information about Red Hat’s this support of this module, please refer to this knowledge base article<https://access.redhat.com/articles/rhel-top-support-policies>

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

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