Documentation

acl - Sets and retrieves file ACL information.

New in version 1.4.

Synopsis

Sets and retrieves file ACL information.

Options

parameter required default choices comments
default
(added in 1.5)
no
  • yes
  • no
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 name is a file.
entity
(added in 1.5)
no
    actual user or group that the ACL applies to when matching entity types user or group are selected.
    entry
    no
      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 requried. '-' 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)
      no
      • user
      • group
      • mask
      • other
      the entity type of the ACL to apply, see setfacl documentation for more info.
      follow
      no True
      • yes
      • no
      whether to follow symlinks on the path if a symlink is encountered.
      name
      yes
        The full path of the file or object.

        aliases: path
        permissions
        (added in 1.5)
        no
          Permissions to apply/remove can be any combination of r, w and x (read, write and execute respectively)
          recursive
          (added in 2.0)
          no
          • yes
          • no
          Recursively sets the specified ACL (added in Ansible 2.0). Incompatible with state=query.
          state
          no query
          • query
          • present
          • absent
          defines whether the ACL should be present or not. The query state gets the current acl without changing it, for use in 'register' operations.

          Examples

          # Grant user Joe read access to a file
          - acl: name=/etc/foo.conf entity=joe etype=user permissions="r" state=present
          
          # Removes the acl for Joe on a specific file
          - acl: name=/etc/foo.conf entity=joe etype=user state=absent
          
          # Sets default acl for joe on foo.d
          - acl: name=/etc/foo.d entity=joe etype=user permissions=rw default=yes state=present
          
          # Same as previous but using entry shorthand
          - acl: name=/etc/foo.d entry="default:user:joe:rw-" state=present
          
          # Obtain the acl for a specific file
          - acl: name=/etc/foo.conf
            register: acl_info
          

          Return Values

          Common return values are documented here Common Return Values, the following are the fields unique to this module:

          name description returned type sample
          acl Current acl on provided path (after changes, if any) success list ['user::rwx', 'group::rwx', 'other::rwx']


          Notes

          Note

          The “acl” module requires that acls are enabled on the target filesystem and that the setfacl and getfacl binaries are installed.

          Note

          As of Ansible 2.0, this module only supports Linux distributions.

          This is a Core Module

          For more information on what this means please read Core Modules

          For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Helping Testing PRs and Developing Modules.