acl – Set and retrieve file ACL information

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


acl – Set and retrieve file ACL information

Synopsis

  • Set and retrieve file ACL information.

Parameters

Parameter Choices/Defaults Comments

default

boolean

  • 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

-

  • 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

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

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

Incompatible with state=query.

state

-

  • 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

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

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