Skip to content

acl

Collection Note

This module is part of the ansible.posix collection. To install the collection, use:

ansible-galaxy collection install ansible.posix
Added in version 1.0.0.

Synopsis

  • Set and retrieve file ACL information.

Parameters

Parameter Defaults / Choices Comments
default
bool		 If O(path) is a directory, setting this to V(true) will make it the default ACL for entities created inside the directory.
Setting O(default=true) causes an error if O(path) is a file.
entity
str		 The actual user or group that the ACL applies to when matching entity types user or group are selected.
entry
str		 DEPRECATED.
The ACL to set or remove.
This must always be quoted in the form of C(::).
The qualifier may be empty for some types, but the type and perms are always required.
C(-) can be used as placeholder when you do not care about permissions.
This is now superseded by entity, type and permissions fields.
etype
str		 Choices: group, mask, other, user The entity type of the ACL to apply, see C(setfacl) documentation for more info.
follow
bool		 Default: True
 Whether to follow symlinks on the path if a symlink is encountered.
path
path
required		 The full path of the file or object.
permissions
str		 The permissions to apply/remove can be any combination of C(r), C(w), C(x) (read, write and execute respectively), and C(X) (execute permission if the file is a directory or already has execute permission for some user)
recalculate_mask
str		 Default: default
Choices: default, mask, no_mask		 Select if and when to recalculate the effective right masks of the files.
See C(setfacl) documentation for more info.
Incompatible with O(state=query).
recursive
bool		 Recursively sets the specified ACL.
Incompatible with O(state=query).
Alias O(recurse) added in version 1.3.0.
state
str		 Default: query
Choices: absent, present, query		 Define whether the ACL should be present or not.
The V(query) state gets the current ACL without changing it, for use in C(register) operations.
use_nfsv4_acls
bool		 Use NFSv4 ACLs instead of POSIX ACLs.
This feature uses C(nfs4_setfacl) and C(nfs4_getfacl). The behavior depends on those implementation. And currently it only supports C(A) in ACE, so C(D) must be replaced with the appropriate C(A).
Permission is set as optimised ACLs by the system. You can check the actual ACLs that has been set using the return value.
More info C(man nfs4_setfacl)

Notes

Note

  • The M(ansible.posix.acl) module requires that ACLs are enabled on the target filesystem and that the C(setfacl) and C(getfacl) binaries are installed.
  • As of Ansible 2.0, this module only supports Linux distributions.
  • As of Ansible 2.3, the O(name) option has been changed to O(path) as default, but O(name) still works as well.

Examples

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

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

- name: Sets default ACL for joe on /etc/foo.d/
  ansible.posix.acl:
    path: /etc/foo.d/
    entity: joe
    etype: user
    permissions: rw
    default: true
    state: present

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

- name: Obtain the ACL for a specific file
  ansible.posix.acl:
    path: /etc/foo.conf
  register: acl_info

Return Values

Key Data Type Description Returned
acl list Current ACL on provided path (after changes, if any) success

Authors

  • Brian Coca (@bcoca)
  • Jérémie Astori (@astorije)