- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

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