acl – Sets and retrieves file ACL information.

From Get docs
Ansible/docs/2.7/modules/acl module


acl – Sets and retrieves file ACL information.

New in version 1.4.


Synopsis

  • Sets and retrieves file ACL information.

Parameters

Parameter Choices/Defaults Comments

default

boolean

added in 1.5

  • no

  • yes

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

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 '::'. 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

  • group
  • mask
  • other
  • user

the entity type of the ACL to apply, see setfacl documentation for more info.

follow

boolean

  • no
  • yes

whether to follow symlinks on the path if a symlink is encountered.

path

- / required

The full path of the file or object.


aliases: name

permissions

-

added in 1.5

Permissions to apply/remove can be any combination of r, w and x (read, write and execute respectively)

recalculate_mask

-

added in 2.7

  • 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

  • no

  • yes

Recursively sets the specified ACL (added in Ansible 2.0). Incompatible with state=query.

state

-

  • absent
  • present
  • query

defines 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

  • 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 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

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.7/modules/acl_module.html