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