ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-07-28 07:31:23 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 11

Docs: Clean up of 'acl' module docs (#46329)

Browse source 
* Docs: Clean up of 'acl' module docs

This is part of a series of module doc cleanups.

* Changes influenced by review coments

* Changes based on review
This commit is contained in:
Dag Wieers 2018-11-02 21:57:59 +01:00 • committed by ansibot
commit ff8181fe29
1 changed files with 50 additions and 53 deletions
Download patch file Download diff file Expand all files Collapse all files

93
lib/ansible/modules/files/acl.py
View file

@ -1,5 +1,6 @@
#!/usr/bin/python #!/usr/bin/python
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
# Copyright: (c) 2017, Ansible Project # Copyright: (c) 2017, Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
@ -10,87 +11,83 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['stableinterface'], 'status': ['stableinterface'],
'supported_by': 'core'} 'supported_by': 'core'}
DOCUMENTATION = r'''
DOCUMENTATION = '''
--- ---
module: acl module: acl
version_added: "1.4" version_added: '1.4'
short_description: Sets and retrieves file ACL information. short_description: Set and retrieve file ACL information.
description: description:
- Sets and retrieves file ACL information. - Set and retrieve file ACL information.
options: options:
path: path:
description: description:
- The full path of the file or object. - The full path of the file or object.
aliases: [ name ] aliases: [ name ]
required: true required: yes
state: state:
description: description:
- defines whether the ACL should be present or not. The C(query) state gets the current acl without changing it, for use in 'register' operations. - Define whether the ACL should be present or not.
- The C(query) state gets the current ACL without changing it, for use in C(register) operations.
choices: [ absent, present, query ] choices: [ absent, present, query ]
default: query default: query
follow: follow:
description: description:
- whether to follow symlinks on the path if a symlink is encountered. - Whether to follow symlinks on the path if a symlink is encountered.
type: bool type: bool
default: 'yes' default: yes
default: default:
description: description:
- 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 - If the target is a directory, setting this to C(yes) will make it the default ACL for entities created inside the directory.
path is a file. - Setting C(default) to C(yes) causes an error if the path is a file.
type: bool type: bool
default: 'no' default: no
version_added: "1.5" version_added: '1.5'
entity: entity:
description: description:
- actual user or group that the ACL applies to when matching entity types user or group are selected. - The actual user or group that the ACL applies to when matching entity types user or group are selected.
version_added: "1.5" version_added: '1.5'
etype: etype:
description: description:
- the entity type of the ACL to apply, see setfacl documentation for more info. - The entity type of the ACL to apply, see C(setfacl) documentation for more info.
choices: [ group, mask, other, user ] choices: [ group, mask, other, user ]
version_added: "1.5" version_added: '1.5'
permissions: permissions:
description: description:
- Permissions to apply/remove can be any combination of r, w and x (read, write and execute respectively) - The permissions to apply/remove can be any combination of C(r), C(w) and C(x) (read, write and execute respectively)
version_added: "1.5" version_added: '1.5'
entry: entry:
description: description:
- 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 - DEPRECATED.
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 - The ACL to set or remove.
superseded by entity, type and permissions fields. - This must always be quoted in the form of C(<etype>:<qualifier>:<perms>).
- 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.
recursive: recursive:
description: description:
- Recursively sets the specified ACL (added in Ansible 2.0). Incompatible with C(state=query). - Recursively sets the specified ACL.
- Incompatible with C(state=query).
type: bool type: bool
default: 'no' default: no
version_added: "2.0" version_added: '2.0'
recalculate_mask: recalculate_mask:
description: description:
- Select if and when to recalculate the effective right masks of the files, see setfacl documentation for more info. Incompatible with C(state=query). - Select if and when to recalculate the effective right masks of the files.
- See C(setfacl) documentation for more info.
- Incompatible with C(state=query).
choices: [ default, mask, no_mask ] choices: [ default, mask, no_mask ]
default: 'default' default: default
version_added: "2.7" version_added: '2.7'
author: author:
- Brian Coca (@bcoca) - Brian Coca (@bcoca)
- Jérémie Astori (@astorije) - Jérémie Astori (@astorije)
notes: notes:
- The "acl" module requires that acls are enabled on the target filesystem and that the setfacl and getfacl binaries are installed. - The C(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.0, this module only supports Linux distributions.
- As of Ansible 2.3, the I(name) option has been changed to I(path) as default, but I(name) still works as well. - As of Ansible 2.3, the I(name) option has been changed to I(path) as default, but I(name) still works as well.
''' '''
EXAMPLES = ''' EXAMPLES = r'''
- name: Grant user Joe read access to a file - name: Grant user Joe read access to a file
acl: acl:
path: /etc/foo.conf path: /etc/foo.conf
@ -99,16 +96,16 @@ EXAMPLES = '''
permissions: r permissions: r
state: present state: present
- name: Removes the acl for Joe on a specific file - name: Removes the ACL for Joe on a specific file
acl: acl:
path: /etc/foo.conf path: /etc/foo.conf
entity: joe entity: joe
etype: user etype: user
state: absent state: absent
- name: Sets default acl for joe on foo.d - name: Sets default ACL for joe on /etc/foo.d/
acl: acl:
path: /etc/foo.d path: /etc/foo.d/
entity: joe entity: joe
etype: user etype: user
permissions: rw permissions: rw
@ -117,19 +114,19 @@ EXAMPLES = '''
- name: Same as previous but using entry shorthand - name: Same as previous but using entry shorthand
acl: acl:
path: /etc/foo.d path: /etc/foo.d/
entry: "default:user:joe:rw-" entry: default:user:joe:rw-
state: present state: present
- name: Obtain the acl for a specific file - name: Obtain the ACL for a specific file
acl: acl:
path: /etc/foo.conf path: /etc/foo.conf
register: acl_info register: acl_info
''' '''
RETURN = ''' RETURN = r'''
acl: acl:
description: Current acl on provided path (after changes, if any) description: Current ACL on provided path (after changes, if any)
returned: success returned: success
type: list type: list
sample: [ "user::rwx", "group::rwx", "other::rwx" ] sample: [ "user::rwx", "group::rwx", "other::rwx" ]