diff --git a/plugins/modules/zfs.py b/plugins/modules/zfs.py index f23cc4580d4..dca4f28b5fe 100644 --- a/plugins/modules/zfs.py +++ b/plugins/modules/zfs.py @@ -9,23 +9,20 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: zfs short_description: Manage zfs description: - - Manages ZFS file systems, volumes, clones and snapshots + - Manages ZFS file systems, volumes, clones and snapshots. extends_documentation_fragment: - community.general.attributes attributes: check_mode: support: partial details: - - In certain situations it may report a task as changed that will not be reported - as changed when C(check_mode) is disabled. - - For example, this might occur when the zpool C(altroot) option is set or when - a size is written using human-readable notation, such as V(1M) or V(1024K), - instead of as an unqualified byte count, such as V(1048576). + - In certain situations it may report a task as changed that will not be reported as changed when C(check_mode) is disabled. + - For example, this might occur when the zpool C(altroot) option is set or when a size is written using human-readable notation, such as + V(1M) or V(1024K), instead of as an unqualified byte count, such as V(1048576). diff_mode: support: full options: @@ -36,10 +33,9 @@ type: str state: description: - - Whether to create (V(present)), or remove (V(absent)) a - file system, snapshot or volume. All parents/children - will be created/destroyed as needed to reach the desired state. - choices: [ absent, present ] + - Whether to create (V(present)), or remove (V(absent)) a file system, snapshot or volume. All parents/children will be created/destroyed + as needed to reach the desired state. + choices: [absent, present] required: true type: str origin: @@ -53,47 +49,47 @@ type: dict default: {} author: -- Johan Wiren (@johanwiren) -''' - -EXAMPLES = ''' -- name: Create a new file system called myfs in pool rpool with the setuid property turned off - community.general.zfs: - name: rpool/myfs - state: present - extra_zfs_properties: - setuid: 'off' - -- name: Create a new volume called myvol in pool rpool. - community.general.zfs: - name: rpool/myvol - state: present - extra_zfs_properties: - volsize: 10M - -- name: Create a snapshot of rpool/myfs file system. - community.general.zfs: - name: rpool/myfs@mysnapshot - state: present - -- name: Create a new file system called myfs2 with snapdir enabled - community.general.zfs: - name: rpool/myfs2 - state: present - extra_zfs_properties: - snapdir: enabled - -- name: Create a new file system by cloning a snapshot - community.general.zfs: - name: rpool/cloned_fs - state: present - origin: rpool/myfs@mysnapshot - -- name: Destroy a filesystem - community.general.zfs: - name: rpool/myfs - state: absent -''' + - Johan Wiren (@johanwiren) +""" + +EXAMPLES = r""" + - name: Create a new file system called myfs in pool rpool with the setuid property turned off + community.general.zfs: + name: rpool/myfs + state: present + extra_zfs_properties: + setuid: 'off' + + - name: Create a new volume called myvol in pool rpool. + community.general.zfs: + name: rpool/myvol + state: present + extra_zfs_properties: + volsize: 10M + + - name: Create a snapshot of rpool/myfs file system. + community.general.zfs: + name: rpool/myfs@mysnapshot + state: present + + - name: Create a new file system called myfs2 with snapdir enabled + community.general.zfs: + name: rpool/myfs2 + state: present + extra_zfs_properties: + snapdir: enabled + + - name: Create a new file system by cloning a snapshot + community.general.zfs: + name: rpool/cloned_fs + state: present + origin: rpool/myfs@mysnapshot + + - name: Destroy a filesystem + community.general.zfs: + name: rpool/myfs + state: absent +""" import os diff --git a/plugins/modules/zfs_delegate_admin.py b/plugins/modules/zfs_delegate_admin.py index 24f7422206d..661f807105f 100644 --- a/plugins/modules/zfs_delegate_admin.py +++ b/plugins/modules/zfs_delegate_admin.py @@ -8,18 +8,17 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: zfs_delegate_admin short_description: Manage ZFS delegated administration (user admin privileges) description: - - Manages ZFS file system delegated administration permissions, which allow unprivileged users to perform ZFS - operations normally restricted to the superuser. + - Manages ZFS file system delegated administration permissions, which allow unprivileged users to perform ZFS operations normally restricted + to the superuser. - See the C(zfs allow) section of V(zfs(1M\)) for detailed explanations of options. - This module attempts to adhere to the behavior of the command line tool as much as possible. requirements: - - "A ZFS/OpenZFS implementation that supports delegation with C(zfs allow), including: Solaris >= 10, illumos (all - versions), FreeBSD >= 8.0R, ZFS on Linux >= 0.7.0." + - "A ZFS/OpenZFS implementation that supports delegation with C(zfs allow), including: Solaris >= 10, illumos (all versions), FreeBSD >= 8.0R, + ZFS on Linux >= 0.7.0." extends_documentation_fragment: - community.general.attributes attributes: @@ -38,7 +37,7 @@ - Whether to allow (V(present)), or unallow (V(absent)) a permission. - When set to V(present), at least one "entity" param of O(users), O(groups), or O(everyone) are required. - When set to V(absent), removes permissions from the specified entities, or removes all permissions if no entity params are specified. - choices: [ absent, present ] + choices: [absent, present] default: present type: str users: @@ -59,8 +58,8 @@ permissions: description: - The list of permission(s) to delegate (required if O(state=present)). - - Supported permissions depend on the ZFS version in use. See for example - U(https://openzfs.github.io/openzfs-docs/man/8/zfs-allow.8.html) for OpenZFS. + - Supported permissions depend on the ZFS version in use. See for example U(https://openzfs.github.io/openzfs-docs/man/8/zfs-allow.8.html) + for OpenZFS. type: list elements: str local: @@ -77,41 +76,41 @@ type: bool default: false author: -- Nate Coraor (@natefoo) -''' + - Nate Coraor (@natefoo) +""" -EXAMPLES = r''' -- name: Grant `zfs allow` and `unallow` permission to the `adm` user with the default local+descendents scope - community.general.zfs_delegate_admin: - name: rpool/myfs - users: adm - permissions: allow,unallow +EXAMPLES = r""" + - name: Grant `zfs allow` and `unallow` permission to the `adm` user with the default local+descendents scope + community.general.zfs_delegate_admin: + name: rpool/myfs + users: adm + permissions: allow,unallow -- name: Grant `zfs send` to everyone, plus the group `backup` - community.general.zfs_delegate_admin: - name: rpool/myvol - groups: backup - everyone: true - permissions: send + - name: Grant `zfs send` to everyone, plus the group `backup` + community.general.zfs_delegate_admin: + name: rpool/myvol + groups: backup + everyone: true + permissions: send -- name: Grant `zfs send,receive` to users `foo` and `bar` with local scope only - community.general.zfs_delegate_admin: - name: rpool/myfs - users: foo,bar - permissions: send,receive - local: true + - name: Grant `zfs send,receive` to users `foo` and `bar` with local scope only + community.general.zfs_delegate_admin: + name: rpool/myfs + users: foo,bar + permissions: send,receive + local: true -- name: Revoke all permissions from everyone (permissions specifically assigned to users and groups remain) - community.general.zfs_delegate_admin: - name: rpool/myfs - everyone: true - state: absent -''' + - name: Revoke all permissions from everyone (permissions specifically assigned to users and groups remain) + community.general.zfs_delegate_admin: + name: rpool/myfs + everyone: true + state: absent +""" # This module does not return anything other than the standard # changed/state/msg/stdout -RETURN = ''' -''' +RETURN = r""" +""" from itertools import product diff --git a/plugins/modules/zfs_facts.py b/plugins/modules/zfs_facts.py index bb4530c4737..443077a3191 100644 --- a/plugins/modules/zfs_facts.py +++ b/plugins/modules/zfs_facts.py @@ -9,8 +9,7 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: zfs_facts short_description: Gather facts about ZFS datasets description: @@ -21,140 +20,137 @@ - community.general.attributes.facts - community.general.attributes.facts_module options: - name: - description: - - ZFS dataset name. - required: true - aliases: [ "ds", "dataset" ] - type: str - recurse: - description: - - Specifies if properties for any children should be recursively - displayed. - type: bool - default: false - parsable: - description: - - Specifies if property values should be displayed in machine - friendly format. - type: bool - default: false - properties: - description: - - Specifies which dataset properties should be queried in comma-separated format. - For more information about dataset properties, check zfs(1M) man page. - default: all - type: str - type: - description: - - Specifies which datasets types to display. Multiple values have to be - provided in comma-separated form. - choices: [ 'all', 'filesystem', 'volume', 'snapshot', 'bookmark' ] - default: all - type: str - depth: - description: - - Specifies recursion depth. - type: int - default: 0 -''' - -EXAMPLES = ''' -- name: Gather facts about ZFS dataset rpool/export/home - community.general.zfs_facts: - dataset: rpool/export/home - -- name: Report space usage on ZFS filesystems under data/home - community.general.zfs_facts: - name: data/home - recurse: true - type: filesystem - -- ansible.builtin.debug: - msg: 'ZFS dataset {{ item.name }} consumes {{ item.used }} of disk space.' - with_items: '{{ ansible_zfs_datasets }}' -''' - -RETURN = ''' -name: - description: ZFS dataset name - returned: always + name: + description: + - ZFS dataset name. + required: true + aliases: ["ds", "dataset"] type: str - sample: rpool/var/spool -parsable: - description: if parsable output should be provided in machine friendly format. - returned: if 'parsable' is set to True + recurse: + description: + - Specifies if properties for any children should be recursively displayed. type: bool - sample: true -recurse: - description: if we should recurse over ZFS dataset - returned: if 'recurse' is set to True + default: false + parsable: + description: + - Specifies if property values should be displayed in machine friendly format. type: bool - sample: true -zfs_datasets: - description: ZFS dataset facts - returned: always + default: false + properties: + description: + - Specifies which dataset properties should be queried in comma-separated format. For more information about dataset properties, check zfs(1M) + man page. + default: all + type: str + type: + description: + - Specifies which datasets types to display. Multiple values have to be provided in comma-separated form. + choices: ['all', 'filesystem', 'volume', 'snapshot', 'bookmark'] + default: all type: str - sample: - { - "aclinherit": "restricted", - "aclmode": "discard", - "atime": "on", - "available": "43.8G", - "canmount": "on", - "casesensitivity": "sensitive", - "checksum": "on", - "compression": "off", - "compressratio": "1.00x", - "copies": "1", - "creation": "Thu Jun 16 11:37 2016", - "dedup": "off", - "devices": "on", - "exec": "on", - "filesystem_count": "none", - "filesystem_limit": "none", - "logbias": "latency", - "logicalreferenced": "18.5K", - "logicalused": "3.45G", - "mlslabel": "none", - "mounted": "yes", - "mountpoint": "/rpool", - "name": "rpool", - "nbmand": "off", - "normalization": "none", - "org.openindiana.caiman:install": "ready", - "primarycache": "all", - "quota": "none", - "readonly": "off", - "recordsize": "128K", - "redundant_metadata": "all", - "refcompressratio": "1.00x", - "referenced": "29.5K", - "refquota": "none", - "refreservation": "none", - "reservation": "none", - "secondarycache": "all", - "setuid": "on", - "sharenfs": "off", - "sharesmb": "off", - "snapdir": "hidden", - "snapshot_count": "none", - "snapshot_limit": "none", - "sync": "standard", - "type": "filesystem", - "used": "4.41G", - "usedbychildren": "4.41G", - "usedbydataset": "29.5K", - "usedbyrefreservation": "0", - "usedbysnapshots": "0", - "utf8only": "off", - "version": "5", - "vscan": "off", - "written": "29.5K", - "xattr": "on", - "zoned": "off" - } -''' + depth: + description: + - Specifies recursion depth. + type: int + default: 0 +""" + +EXAMPLES = r""" + - name: Gather facts about ZFS dataset rpool/export/home + community.general.zfs_facts: + dataset: rpool/export/home + + - name: Report space usage on ZFS filesystems under data/home + community.general.zfs_facts: + name: data/home + recurse: true + type: filesystem + + - ansible.builtin.debug: + msg: 'ZFS dataset {{ item.name }} consumes {{ item.used }} of disk space.' + with_items: '{{ ansible_zfs_datasets }}' +""" + +RETURN = r""" +name: + description: ZFS dataset name + returned: always + type: str + sample: rpool/var/spool +parsable: + description: if parsable output should be provided in machine friendly format. + returned: if 'parsable' is set to True + type: bool + sample: true +recurse: + description: if we should recurse over ZFS dataset + returned: if 'recurse' is set to True + type: bool + sample: true +zfs_datasets: + description: ZFS dataset facts + returned: always + type: str + sample: + { + "aclinherit": "restricted", + "aclmode": "discard", + "atime": "on", + "available": "43.8G", + "canmount": "on", + "casesensitivity": "sensitive", + "checksum": "on", + "compression": "off", + "compressratio": "1.00x", + "copies": "1", + "creation": "Thu Jun 16 11:37 2016", + "dedup": "off", + "devices": "on", + "exec": "on", + "filesystem_count": "none", + "filesystem_limit": "none", + "logbias": "latency", + "logicalreferenced": "18.5K", + "logicalused": "3.45G", + "mlslabel": "none", + "mounted": "yes", + "mountpoint": "/rpool", + "name": "rpool", + "nbmand": "off", + "normalization": "none", + "org.openindiana.caiman:install": "ready", + "primarycache": "all", + "quota": "none", + "readonly": "off", + "recordsize": "128K", + "redundant_metadata": "all", + "refcompressratio": "1.00x", + "referenced": "29.5K", + "refquota": "none", + "refreservation": "none", + "reservation": "none", + "secondarycache": "all", + "setuid": "on", + "sharenfs": "off", + "sharesmb": "off", + "snapdir": "hidden", + "snapshot_count": "none", + "snapshot_limit": "none", + "sync": "standard", + "type": "filesystem", + "used": "4.41G", + "usedbychildren": "4.41G", + "usedbydataset": "29.5K", + "usedbyrefreservation": "0", + "usedbysnapshots": "0", + "utf8only": "off", + "version": "5", + "vscan": "off", + "written": "29.5K", + "xattr": "on", + "zoned": "off" + } +""" from collections import defaultdict