From 12f2d719502565e8eca74b2b42a44235cac9a1a2 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Tue, 24 Dec 2024 13:04:53 +0000 Subject: [PATCH] [PR #9338/2005125a backport][stable-10] u[a-s]*: normalize docs (#9361) u[a-s]*: normalize docs (#9338) * u[a-s]*: normalize docs * Update plugins/modules/udm_dns_record.py Co-authored-by: Felix Fontein * Update plugins/modules/udm_dns_record.py Co-authored-by: Felix Fontein * Update plugins/modules/udm_dns_record.py Co-authored-by: Felix Fontein * Update plugins/modules/udm_dns_zone.py Co-authored-by: Felix Fontein * Update plugins/modules/ufw.py Co-authored-by: Felix Fontein * Apply suggestions from code review Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit 2005125af4bfc7b45a729151f7a5e202d20369be) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/udm_dns_record.py | 99 +++-- plugins/modules/udm_dns_zone.py | 152 ++++--- plugins/modules/udm_group.py | 96 +++-- plugins/modules/udm_share.py | 630 +++++++++++++++--------------- plugins/modules/udm_user.py | 550 +++++++++++++------------- plugins/modules/ufw.py | 112 +++--- plugins/modules/uptimerobot.py | 57 ++- plugins/modules/urpmi.py | 25 +- plugins/modules/usb_facts.py | 13 +- 9 files changed, 846 insertions(+), 888 deletions(-) diff --git a/plugins/modules/udm_dns_record.py b/plugins/modules/udm_dns_record.py index 857792993d..a87ce5fede 100644 --- a/plugins/modules/udm_dns_record.py +++ b/plugins/modules/udm_dns_record.py @@ -10,63 +10,60 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: udm_dns_record author: - - Tobias Rüetschi (@keachi) + - Tobias Rüetschi (@keachi) short_description: Manage dns entries on a univention corporate server description: - - "This module allows to manage dns records on a univention corporate server (UCS). - It uses the python API of the UCS to create a new object or edit it." + - This module allows to manage dns records on a univention corporate server (UCS). It uses the Python API of the UCS to create a new object + or edit it. requirements: - - Univention - - ipaddress (for O(type=ptr_record)) + - Univention + - ipaddress (for O(type=ptr_record)) extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: partial + check_mode: + support: full + diff_mode: + support: partial options: - state: - type: str - default: "present" - choices: [ present, absent ] - description: - - Whether the dns record is present or not. - name: - type: str - required: true - description: - - "Name of the record, this is also the DNS record. E.g. www for - www.example.com." - - For PTR records this has to be the IP address. - zone: - type: str - required: true - description: - - Corresponding DNS zone for this record, e.g. example.com. - - For PTR records this has to be the full reverse zone (for example V(1.1.192.in-addr.arpa)). - type: - type: str - required: true - description: - - "Define the record type. V(host_record) is a A or AAAA record, - V(alias) is a CNAME, V(ptr_record) is a PTR record, V(srv_record) - is a SRV record and V(txt_record) is a TXT record." - - "The available choices are: V(host_record), V(alias), V(ptr_record), V(srv_record), V(txt_record)." - data: - type: dict - default: {} - description: - - "Additional data for this record, for example V({'a': '192.0.2.1'})." - - Required if O(state=present). -''' + state: + type: str + default: "present" + choices: [present, absent] + description: + - Whether the dns record is present or not. + name: + type: str + required: true + description: + - Name of the record, this is also the DNS record. For example V(www) for www.example.com. + - For PTR records this has to be the IP address. + zone: + type: str + required: true + description: + - Corresponding DNS zone for this record, for example V(example.com). + - For PTR records this has to be the full reverse zone (for example V(1.1.192.in-addr.arpa)). + type: + type: str + required: true + description: + - Define the record type. V(host_record) is a A or AAAA record, V(alias) is a CNAME, V(ptr_record) is a PTR record, V(srv_record) is a SRV + record and V(txt_record) is a TXT record. + - 'The available choices are: V(host_record), V(alias), V(ptr_record), V(srv_record), V(txt_record).' + data: + type: dict + default: {} + description: + - "Additional data for this record, for example V({'a': '192.0.2.1'})." + - Required if O(state=present). +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a DNS record on a UCS community.general.udm_dns_record: name: www @@ -74,8 +71,8 @@ EXAMPLES = ''' type: host_record data: a: - - 192.0.2.1 - - 2001:0db8::42 + - 192.0.2.1 + - 2001:0db8::42 - name: Create a DNS v4 PTR record on a UCS community.general.udm_dns_record: @@ -92,10 +89,10 @@ EXAMPLES = ''' type: ptr_record data: ptr_record: "www.example.com." -''' +""" -RETURN = '''#''' +RETURN = """#""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/udm_dns_zone.py b/plugins/modules/udm_dns_zone.py index 387d5cc45b..765f996aba 100644 --- a/plugins/modules/udm_dns_zone.py +++ b/plugins/modules/udm_dns_zone.py @@ -10,91 +10,87 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: udm_dns_zone author: - - Tobias Rüetschi (@keachi) + - Tobias Rüetschi (@keachi) short_description: Manage dns zones on a univention corporate server description: - - "This module allows to manage dns zones on a univention corporate server (UCS). - It uses the python API of the UCS to create a new object or edit it." + - This module allows to manage dns zones on a univention corporate server (UCS). It uses the Python API of the UCS to create a new object or + edit it. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: partial + check_mode: + support: full + diff_mode: + support: partial options: - state: - type: str - default: "present" - choices: [ present, absent ] - description: - - Whether the dns zone is present or not. - type: - type: str - required: true - description: - - Define if the zone is a forward or reverse DNS zone. - - "The available choices are: V(forward_zone), V(reverse_zone)." - zone: - type: str - required: true - description: - - DNS zone name, for example V(example.com). - aliases: [name] - nameserver: - type: list - elements: str - default: [] - description: - - List of appropriate name servers. Required if O(state=present). - interfaces: - type: list - elements: str - default: [] - description: - - List of interface IP addresses, on which the server should - response this zone. Required if O(state=present). - - refresh: - type: int - default: 3600 - description: - - Interval before the zone should be refreshed. - retry: - type: int - default: 1800 - description: - - Interval that should elapse before a failed refresh should be retried. - expire: - type: int - default: 604800 - description: - - Specifies the upper limit on the time interval that can elapse before the zone is no longer authoritative. - ttl: - type: int - default: 600 - description: - - Minimum TTL field that should be exported with any RR from this zone. - - contact: - type: str - default: '' - description: - - Contact person in the SOA record. - mx: - type: list - elements: str - default: [] - description: - - List of MX servers. (Must declared as A or AAAA records). -''' + state: + type: str + default: "present" + choices: [present, absent] + description: + - Whether the DNS zone is present or not. + type: + type: str + required: true + description: + - Define if the zone is a forward or reverse DNS zone. + - 'The available choices are: V(forward_zone), V(reverse_zone).' + zone: + type: str + required: true + description: + - DNS zone name, for example V(example.com). + aliases: [name] + nameserver: + type: list + elements: str + default: [] + description: + - List of appropriate name servers. Required if O(state=present). + interfaces: + type: list + elements: str + default: [] + description: + - List of interface IP addresses, on which the server should response this zone. Required if O(state=present). + refresh: + type: int + default: 3600 + description: + - Interval before the zone should be refreshed. + retry: + type: int + default: 1800 + description: + - Interval that should elapse before a failed refresh should be retried. + expire: + type: int + default: 604800 + description: + - Specifies the upper limit on the time interval that can elapse before the zone is no longer authoritative. + ttl: + type: int + default: 600 + description: + - Minimum TTL field that should be exported with any RR from this zone. + contact: + type: str + default: '' + description: + - Contact person in the SOA record. + mx: + type: list + elements: str + default: [] + description: + - List of MX servers. (Must declared as A or AAAA records). +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a DNS zone on a UCS community.general.udm_dns_zone: zone: example.com @@ -103,10 +99,10 @@ EXAMPLES = ''' - ucs.example.com interfaces: - 192.0.2.1 -''' +""" -RETURN = '''# ''' +RETURN = """# """ from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.univention_umc import ( diff --git a/plugins/modules/udm_group.py b/plugins/modules/udm_group.py index 5fe2422f8b..238b0182ed 100644 --- a/plugins/modules/udm_group.py +++ b/plugins/modules/udm_group.py @@ -10,63 +10,61 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: udm_group author: - - Tobias Rüetschi (@keachi) + - Tobias Rüetschi (@keachi) short_description: Manage of the posix group description: - - "This module allows to manage user groups on a univention corporate server (UCS). - It uses the python API of the UCS to create a new object or edit it." + - This module allows to manage user groups on a univention corporate server (UCS). It uses the Python API of the UCS to create a new object + or edit it. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: partial + check_mode: + support: full + diff_mode: + support: partial options: - state: - required: false - default: "present" - choices: [ present, absent ] - description: - - Whether the group is present or not. - type: str - name: - required: true - description: - - Name of the posix group. - type: str + state: + required: false + default: "present" + choices: [present, absent] description: - required: false - description: - - Group description. - type: str - position: - required: false - description: - - define the whole ldap position of the group, e.g. - C(cn=g123m-1A,cn=classes,cn=schueler,cn=groups,ou=schule,dc=example,dc=com). - type: str - default: '' - ou: - required: false - description: - - LDAP OU, e.g. school for LDAP OU C(ou=school,dc=example,dc=com). - type: str - default: '' - subpath: - required: false - description: - - Subpath inside the OU, e.g. C(cn=classes,cn=students,cn=groups). - type: str - default: "cn=groups" -''' + - Whether the group is present or not. + type: str + name: + required: true + description: + - Name of the POSIX group. + type: str + description: + required: false + description: + - Group description. + type: str + position: + required: false + description: + - Define the whole LDAP position of the group, for example V(cn=g123m-1A,cn=classes,cn=schueler,cn=groups,ou=schule,dc=example,dc=com). + type: str + default: '' + ou: + required: false + description: + - LDAP OU, for example V(school) for LDAP OU V(ou=school,dc=example,dc=com). + type: str + default: '' + subpath: + required: false + description: + - Subpath inside the OU, for example V(cn=classes,cn=students,cn=groups). + type: str + default: "cn=groups" +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a POSIX group community.general.udm_group: name: g123m-1A @@ -84,10 +82,10 @@ EXAMPLES = ''' community.general.udm_group: name: g123m-1A position: 'cn=classes,cn=students,cn=groups,ou=school,dc=school,dc=example,dc=com' -''' +""" -RETURN = '''# ''' +RETURN = """# """ from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.univention_umc import ( diff --git a/plugins/modules/udm_share.py b/plugins/modules/udm_share.py index 8ae243b3de..3489607b09 100644 --- a/plugins/modules/udm_share.py +++ b/plugins/modules/udm_share.py @@ -10,339 +10,337 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: udm_share author: - - Tobias Rüetschi (@keachi) + - Tobias Rüetschi (@keachi) short_description: Manage samba shares on a univention corporate server description: - - "This module allows to manage samba shares on a univention corporate - server (UCS). - It uses the python API of the UCS to create a new object or edit it." + - This module allows to manage samba shares on a univention corporate server (UCS). It uses the Python API of the UCS to create a new object + or edit it. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: partial + check_mode: + support: full + diff_mode: + support: partial options: - state: - default: "present" - choices: [ present, absent ] - description: - - Whether the share is present or not. - type: str - name: - required: true - description: - - Name - type: str - host: - required: false - description: - - Host FQDN (server which provides the share), for example V({{ ansible_fqdn }}). Required if O(state=present). - type: str - path: - required: false - description: - - Directory on the providing server, for example V(/home). Required if O(state=present). - type: path - sambaName: - required: false - description: - - Windows name. Required if O(state=present). - type: str - aliases: [ samba_name ] - ou: - required: true - description: - - Organisational unit, inside the LDAP Base DN. - type: str - owner: - default: '0' - description: - - Directory owner of the share's root directory. - type: str - group: - default: '0' - description: - - Directory owner group of the share's root directory. - type: str - directorymode: - default: '00755' - description: - - Permissions for the share's root directory. - type: str - root_squash: - default: true - description: - - Modify user ID for root user (root squashing). - type: bool - subtree_checking: - default: true - description: - - Subtree checking. - type: bool - sync: - default: 'sync' - description: - - NFS synchronisation. - type: str - writeable: - default: true - description: - - NFS write access. - type: bool - sambaBlockSize: - description: - - Blocking size. - type: str - aliases: [ samba_block_size ] - sambaBlockingLocks: - default: true - description: - - Blocking locks. - type: bool - aliases: [ samba_blocking_locks ] - sambaBrowseable: - description: - - Show in Windows network environment. - type: bool - default: true - aliases: [ samba_browsable ] - sambaCreateMode: - default: '0744' - description: - - File mode. - type: str - aliases: [ samba_create_mode ] - sambaCscPolicy: - default: 'manual' - description: - - Client-side caching policy. - type: str - aliases: [ samba_csc_policy ] - sambaCustomSettings: - default: [] - description: - - Option name in smb.conf and its value. - type: list - elements: dict - aliases: [ samba_custom_settings ] - sambaDirectoryMode: - default: '0755' - description: - - Directory mode. - type: str - aliases: [ samba_directory_mode ] - sambaDirectorySecurityMode: - default: '0777' - description: - - Directory security mode. - type: str - aliases: [ samba_directory_security_mode ] - sambaDosFilemode: - default: false - description: - - Users with write access may modify permissions. - type: bool - aliases: [ samba_dos_filemode ] - sambaFakeOplocks: - default: false - description: - - Fake oplocks. - type: bool - aliases: [ samba_fake_oplocks ] - sambaForceCreateMode: - default: false - description: - - Force file mode. - type: bool - aliases: [ samba_force_create_mode ] - sambaForceDirectoryMode: - default: false - description: - - Force directory mode. - type: bool - aliases: [ samba_force_directory_mode ] - sambaForceDirectorySecurityMode: - default: false - description: - - Force directory security mode. - type: bool - aliases: [ samba_force_directory_security_mode ] - sambaForceGroup: - description: - - Force group. - type: str - aliases: [ samba_force_group ] - sambaForceSecurityMode: - default: false - description: - - Force security mode. - type: bool - aliases: [ samba_force_security_mode ] - sambaForceUser: - description: - - Force user. - type: str - aliases: [ samba_force_user ] - sambaHideFiles: - description: - - Hide files. - type: str - aliases: [ samba_hide_files ] - sambaHideUnreadable: - default: false - description: - - Hide unreadable files/directories. - type: bool - aliases: [ samba_hide_unreadable ] - sambaHostsAllow: - default: [] - description: - - Allowed host/network. - type: list - elements: str - aliases: [ samba_hosts_allow ] - sambaHostsDeny: - default: [] - description: - - Denied host/network. - type: list - elements: str - aliases: [ samba_hosts_deny ] - sambaInheritAcls: - default: true - description: - - Inherit ACLs. - type: bool - aliases: [ samba_inherit_acls ] - sambaInheritOwner: - default: false - description: - - Create files/directories with the owner of the parent directory. - type: bool - aliases: [ samba_inherit_owner ] - sambaInheritPermissions: - default: false - description: - - Create files/directories with permissions of the parent directory. - type: bool - aliases: [ samba_inherit_permissions ] - sambaInvalidUsers: - description: - - Invalid users or groups. - type: str - aliases: [ samba_invalid_users ] - sambaLevel2Oplocks: - default: true - description: - - Level 2 oplocks. - type: bool - aliases: [ samba_level_2_oplocks ] - sambaLocking: - default: true - description: - - Locking. - type: bool - aliases: [ samba_locking ] - sambaMSDFSRoot: - default: false - description: - - MSDFS root. - type: bool - aliases: [ samba_msdfs_root ] - sambaNtAclSupport: - default: true - description: - - NT ACL support. - type: bool - aliases: [ samba_nt_acl_support ] - sambaOplocks: - default: true - description: - - Oplocks. - type: bool - aliases: [ samba_oplocks ] - sambaPostexec: - description: - - Postexec script. - type: str - aliases: [ samba_postexec ] - sambaPreexec: - description: - - Preexec script. - type: str - aliases: [ samba_preexec ] - sambaPublic: - default: false - description: - - Allow anonymous read-only access with a guest user. - type: bool - aliases: [ samba_public ] - sambaSecurityMode: - default: '0777' - description: - - Security mode. - type: str - aliases: [ samba_security_mode ] - sambaStrictLocking: - default: 'Auto' - description: - - Strict locking. - type: str - aliases: [ samba_strict_locking ] - sambaVFSObjects: - description: - - VFS objects. - type: str - aliases: [ samba_vfs_objects ] - sambaValidUsers: - description: - - Valid users or groups. - type: str - aliases: [ samba_valid_users ] - sambaWriteList: - description: - - Restrict write access to these users/groups. - type: str - aliases: [ samba_write_list ] - sambaWriteable: - default: true - description: - - Samba write access. - type: bool - aliases: [ samba_writeable ] - nfs_hosts: - default: [] - description: - - Only allow access for this host, IP address or network. - type: list - elements: str - nfsCustomSettings: - default: [] - description: - - Option name in exports file. - type: list - elements: str - aliases: [ nfs_custom_settings ] -''' + state: + default: "present" + choices: [present, absent] + description: + - Whether the share is present or not. + type: str + name: + required: true + description: + - Name. + type: str + host: + required: false + description: + - Host FQDN (server which provides the share), for example V({{ ansible_fqdn }}). Required if O(state=present). + type: str + path: + required: false + description: + - Directory on the providing server, for example V(/home). Required if O(state=present). + type: path + sambaName: + required: false + description: + - Windows name. Required if O(state=present). + type: str + aliases: [samba_name] + ou: + required: true + description: + - Organisational unit, inside the LDAP Base DN. + type: str + owner: + default: '0' + description: + - Directory owner of the share's root directory. + type: str + group: + default: '0' + description: + - Directory owner group of the share's root directory. + type: str + directorymode: + default: '00755' + description: + - Permissions for the share's root directory. + type: str + root_squash: + default: true + description: + - Modify user ID for root user (root squashing). + type: bool + subtree_checking: + default: true + description: + - Subtree checking. + type: bool + sync: + default: 'sync' + description: + - NFS synchronisation. + type: str + writeable: + default: true + description: + - NFS write access. + type: bool + sambaBlockSize: + description: + - Blocking size. + type: str + aliases: [samba_block_size] + sambaBlockingLocks: + default: true + description: + - Blocking locks. + type: bool + aliases: [samba_blocking_locks] + sambaBrowseable: + description: + - Show in Windows network environment. + type: bool + default: true + aliases: [samba_browsable] + sambaCreateMode: + default: '0744' + description: + - File mode. + type: str + aliases: [samba_create_mode] + sambaCscPolicy: + default: 'manual' + description: + - Client-side caching policy. + type: str + aliases: [samba_csc_policy] + sambaCustomSettings: + default: [] + description: + - Option name in smb.conf and its value. + type: list + elements: dict + aliases: [samba_custom_settings] + sambaDirectoryMode: + default: '0755' + description: + - Directory mode. + type: str + aliases: [samba_directory_mode] + sambaDirectorySecurityMode: + default: '0777' + description: + - Directory security mode. + type: str + aliases: [samba_directory_security_mode] + sambaDosFilemode: + default: false + description: + - Users with write access may modify permissions. + type: bool + aliases: [samba_dos_filemode] + sambaFakeOplocks: + default: false + description: + - Fake oplocks. + type: bool + aliases: [samba_fake_oplocks] + sambaForceCreateMode: + default: false + description: + - Force file mode. + type: bool + aliases: [samba_force_create_mode] + sambaForceDirectoryMode: + default: false + description: + - Force directory mode. + type: bool + aliases: [samba_force_directory_mode] + sambaForceDirectorySecurityMode: + default: false + description: + - Force directory security mode. + type: bool + aliases: [samba_force_directory_security_mode] + sambaForceGroup: + description: + - Force group. + type: str + aliases: [samba_force_group] + sambaForceSecurityMode: + default: false + description: + - Force security mode. + type: bool + aliases: [samba_force_security_mode] + sambaForceUser: + description: + - Force user. + type: str + aliases: [samba_force_user] + sambaHideFiles: + description: + - Hide files. + type: str + aliases: [samba_hide_files] + sambaHideUnreadable: + default: false + description: + - Hide unreadable files/directories. + type: bool + aliases: [samba_hide_unreadable] + sambaHostsAllow: + default: [] + description: + - Allowed host/network. + type: list + elements: str + aliases: [samba_hosts_allow] + sambaHostsDeny: + default: [] + description: + - Denied host/network. + type: list + elements: str + aliases: [samba_hosts_deny] + sambaInheritAcls: + default: true + description: + - Inherit ACLs. + type: bool + aliases: [samba_inherit_acls] + sambaInheritOwner: + default: false + description: + - Create files/directories with the owner of the parent directory. + type: bool + aliases: [samba_inherit_owner] + sambaInheritPermissions: + default: false + description: + - Create files/directories with permissions of the parent directory. + type: bool + aliases: [samba_inherit_permissions] + sambaInvalidUsers: + description: + - Invalid users or groups. + type: str + aliases: [samba_invalid_users] + sambaLevel2Oplocks: + default: true + description: + - Level 2 oplocks. + type: bool + aliases: [samba_level_2_oplocks] + sambaLocking: + default: true + description: + - Locking. + type: bool + aliases: [samba_locking] + sambaMSDFSRoot: + default: false + description: + - MSDFS root. + type: bool + aliases: [samba_msdfs_root] + sambaNtAclSupport: + default: true + description: + - NT ACL support. + type: bool + aliases: [samba_nt_acl_support] + sambaOplocks: + default: true + description: + - Oplocks. + type: bool + aliases: [samba_oplocks] + sambaPostexec: + description: + - Postexec script. + type: str + aliases: [samba_postexec] + sambaPreexec: + description: + - Preexec script. + type: str + aliases: [samba_preexec] + sambaPublic: + default: false + description: + - Allow anonymous read-only access with a guest user. + type: bool + aliases: [samba_public] + sambaSecurityMode: + default: '0777' + description: + - Security mode. + type: str + aliases: [samba_security_mode] + sambaStrictLocking: + default: 'Auto' + description: + - Strict locking. + type: str + aliases: [samba_strict_locking] + sambaVFSObjects: + description: + - VFS objects. + type: str + aliases: [samba_vfs_objects] + sambaValidUsers: + description: + - Valid users or groups. + type: str + aliases: [samba_valid_users] + sambaWriteList: + description: + - Restrict write access to these users/groups. + type: str + aliases: [samba_write_list] + sambaWriteable: + default: true + description: + - Samba write access. + type: bool + aliases: [samba_writeable] + nfs_hosts: + default: [] + description: + - Only allow access for this host, IP address or network. + type: list + elements: str + nfsCustomSettings: + default: [] + description: + - Option name in exports file. + type: list + elements: str + aliases: [nfs_custom_settings] +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a share named home on the server ucs.example.com with the path /home community.general.udm_share: name: home path: /home host: ucs.example.com sambaName: Home -''' +""" -RETURN = '''# ''' +RETURN = """# """ from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.univention_umc import ( diff --git a/plugins/modules/udm_user.py b/plugins/modules/udm_user.py index 5257a22028..bb431ca75f 100644 --- a/plugins/modules/udm_user.py +++ b/plugins/modules/udm_user.py @@ -10,297 +10,285 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: udm_user author: - - Tobias Rüetschi (@keachi) + - Tobias Rüetschi (@keachi) short_description: Manage posix users on a univention corporate server description: - - "This module allows to manage posix users on a univention corporate - server (UCS). - It uses the python API of the UCS to create a new object or edit it." + - This module allows to manage posix users on a univention corporate server (UCS). It uses the Python API of the UCS to create a new object + or edit it. notes: - - This module requires the deprecated L(crypt Python module, - https://docs.python.org/3.12/library/crypt.html) library which was removed from Python 3.13. - For Python 3.13 or newer, you need to install L(legacycrypt, https://pypi.org/project/legacycrypt/). + - This module requires the deprecated L(crypt Python module, https://docs.python.org/3.12/library/crypt.html) library which was removed from + Python 3.13. For Python 3.13 or newer, you need to install L(legacycrypt, https://pypi.org/project/legacycrypt/). requirements: - - legacycrypt (on Python 3.13 or newer) + - legacycrypt (on Python 3.13 or newer) extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: partial + check_mode: + support: full + diff_mode: + support: partial options: - state: - default: "present" - choices: [ present, absent ] - description: - - Whether the user is present or not. - type: str - username: - required: true - description: - - User name - aliases: ['name'] - type: str - firstname: - description: - - First name. Required if O(state=present). - type: str - lastname: - description: - - Last name. Required if O(state=present). - type: str - password: - description: - - Password. Required if O(state=present). - type: str - birthday: - description: - - Birthday - type: str - city: - description: - - City of users business address. - type: str - country: - description: - - Country of users business address. - type: str - department_number: - description: - - Department number of users business address. - aliases: [ departmentNumber ] - type: str + state: + default: "present" + choices: [present, absent] description: - description: - - Description (not gecos) - type: str - display_name: - description: - - Display name (not gecos) - aliases: [ displayName ] - type: str - email: - default: [''] - description: - - A list of e-mail addresses. - type: list - elements: str - employee_number: - description: - - Employee number - aliases: [ employeeNumber ] - type: str - employee_type: - description: - - Employee type - aliases: [ employeeType ] - type: str - gecos: - description: - - GECOS - type: str - groups: - default: [] - description: - - "POSIX groups, the LDAP DNs of the groups will be found with the - LDAP filter for each group as $GROUP: - V((&(objectClass=posixGroup\\)(cn=$GROUP\\)\\))." - type: list - elements: str - home_share: - description: - - "Home NFS share. Must be a LDAP DN, e.g. - V(cn=home,cn=shares,ou=school,dc=example,dc=com)." - aliases: [ homeShare ] - type: str - home_share_path: - description: - - Path to home NFS share, inside the homeShare. - aliases: [ homeSharePath ] - type: str - home_telephone_number: - default: [] - description: - - List of private telephone numbers. - aliases: [ homeTelephoneNumber ] - type: list - elements: str - homedrive: - description: - - Windows home drive, for example V("H:"). - type: str - mail_alternative_address: - default: [] - description: - - List of alternative e-mail addresses. - aliases: [ mailAlternativeAddress ] - type: list - elements: str - mail_home_server: - description: - - FQDN of mail server - aliases: [ mailHomeServer ] - type: str - mail_primary_address: - description: - - Primary e-mail address - aliases: [ mailPrimaryAddress ] - type: str - mobile_telephone_number: - default: [] - description: - - Mobile phone number - aliases: [ mobileTelephoneNumber ] - type: list - elements: str - organisation: - description: - - Organisation - aliases: [ organization ] - type: str - overridePWHistory: - type: bool - default: false - description: - - Override password history - aliases: [ override_pw_history ] - overridePWLength: - type: bool - default: false - description: - - Override password check - aliases: [ override_pw_length ] - pager_telephonenumber: - default: [] - description: - - List of pager telephone numbers. - aliases: [ pagerTelephonenumber ] - type: list - elements: str - phone: - description: - - List of telephone numbers. - type: list - elements: str - default: [] - postcode: - description: - - Postal code of users business address. - type: str - primary_group: - description: - - Primary group. This must be the group LDAP DN. - - If not specified, it defaults to V(cn=Domain Users,cn=groups,$LDAP_BASE_DN). - aliases: [ primaryGroup ] - type: str - profilepath: - description: - - Windows profile directory - type: str - pwd_change_next_login: - choices: [ '0', '1' ] - description: - - Change password on next login. - aliases: [ pwdChangeNextLogin ] - type: str - room_number: - description: - - Room number of users business address. - aliases: [ roomNumber ] - type: str - samba_privileges: - description: - - "Samba privilege, like allow printer administration, do domain - join." - aliases: [ sambaPrivileges ] - type: list - elements: str - default: [] - samba_user_workstations: - description: - - Allow the authentication only on this Microsoft Windows host. - aliases: [ sambaUserWorkstations ] - type: list - elements: str - default: [] - sambahome: - description: - - Windows home path, for example V('\\\\$FQDN\\$USERNAME'). - type: str - scriptpath: - description: - - Windows logon script. - type: str - secretary: - default: [] - description: - - A list of superiors as LDAP DNs. - type: list - elements: str - serviceprovider: - default: [''] - description: - - Enable user for the following service providers. - type: list - elements: str - shell: - default: '/bin/bash' - description: - - Login shell - type: str - street: - description: - - Street of users business address. - type: str - title: - description: - - Title, for example V(Prof.). - type: str - unixhome: - description: - - Unix home directory - - If not specified, it defaults to C(/home/$USERNAME). - type: str - userexpiry: - description: - - Account expiry date, for example V(1999-12-31). - - If not specified, it defaults to the current day plus one year. - type: str - position: - default: '' - description: - - "Define the whole position of users object inside the LDAP tree, - for example V(cn=employee,cn=users,ou=school,dc=example,dc=com)." - type: str - update_password: - default: always - choices: [ always, on_create ] - description: - - "V(always) will update passwords if they differ. - V(on_create) will only set the password for newly created users." - type: str - ou: - default: '' - description: - - "Organizational Unit inside the LDAP Base DN, for example V(school) for - LDAP OU C(ou=school,dc=example,dc=com)." - type: str - subpath: - default: 'cn=users' - description: - - "LDAP subpath inside the organizational unit, for example - V(cn=teachers,cn=users) for LDAP container - C(cn=teachers,cn=users,dc=example,dc=com)." - type: str -''' + - Whether the user is present or not. + type: str + username: + required: true + description: + - User name. + aliases: ['name'] + type: str + firstname: + description: + - First name. Required if O(state=present). + type: str + lastname: + description: + - Last name. Required if O(state=present). + type: str + password: + description: + - Password. Required if O(state=present). + type: str + birthday: + description: + - Birthday. + type: str + city: + description: + - City of users business address. + type: str + country: + description: + - Country of users business address. + type: str + department_number: + description: + - Department number of users business address. + aliases: [departmentNumber] + type: str + description: + description: + - Description (not gecos). + type: str + display_name: + description: + - Display name (not gecos). + aliases: [displayName] + type: str + email: + default: [''] + description: + - A list of e-mail addresses. + type: list + elements: str + employee_number: + description: + - Employee number. + aliases: [employeeNumber] + type: str + employee_type: + description: + - Employee type. + aliases: [employeeType] + type: str + gecos: + description: + - GECOS. + type: str + groups: + default: [] + description: + - 'POSIX groups, the LDAP DNs of the groups will be found with the LDAP filter for each group as $GROUP: V((&(objectClass=posixGroup\)(cn=$GROUP\)\)).' + type: list + elements: str + home_share: + description: + - Home NFS share. Must be a LDAP DN, for example V(cn=home,cn=shares,ou=school,dc=example,dc=com). + aliases: [homeShare] + type: str + home_share_path: + description: + - Path to home NFS share, inside the homeShare. + aliases: [homeSharePath] + type: str + home_telephone_number: + default: [] + description: + - List of private telephone numbers. + aliases: [homeTelephoneNumber] + type: list + elements: str + homedrive: + description: + - Windows home drive, for example V("H:"). + type: str + mail_alternative_address: + default: [] + description: + - List of alternative e-mail addresses. + aliases: [mailAlternativeAddress] + type: list + elements: str + mail_home_server: + description: + - FQDN of mail server. + aliases: [mailHomeServer] + type: str + mail_primary_address: + description: + - Primary e-mail address. + aliases: [mailPrimaryAddress] + type: str + mobile_telephone_number: + default: [] + description: + - Mobile phone number. + aliases: [mobileTelephoneNumber] + type: list + elements: str + organisation: + description: + - Organisation. + aliases: [organization] + type: str + overridePWHistory: + type: bool + default: false + description: + - Override password history. + aliases: [override_pw_history] + overridePWLength: + type: bool + default: false + description: + - Override password check. + aliases: [override_pw_length] + pager_telephonenumber: + default: [] + description: + - List of pager telephone numbers. + aliases: [pagerTelephonenumber] + type: list + elements: str + phone: + description: + - List of telephone numbers. + type: list + elements: str + default: [] + postcode: + description: + - Postal code of users business address. + type: str + primary_group: + description: + - Primary group. This must be the group LDAP DN. + - If not specified, it defaults to V(cn=Domain Users,cn=groups,$LDAP_BASE_DN). + aliases: [primaryGroup] + type: str + profilepath: + description: + - Windows profile directory. + type: str + pwd_change_next_login: + choices: ['0', '1'] + description: + - Change password on next login. + aliases: [pwdChangeNextLogin] + type: str + room_number: + description: + - Room number of users business address. + aliases: [roomNumber] + type: str + samba_privileges: + description: + - Samba privilege, like allow printer administration, do domain join. + aliases: [sambaPrivileges] + type: list + elements: str + default: [] + samba_user_workstations: + description: + - Allow the authentication only on this Microsoft Windows host. + aliases: [sambaUserWorkstations] + type: list + elements: str + default: [] + sambahome: + description: + - Windows home path, for example V('\\\\$FQDN\\$USERNAME'). + type: str + scriptpath: + description: + - Windows logon script. + type: str + secretary: + default: [] + description: + - A list of superiors as LDAP DNs. + type: list + elements: str + serviceprovider: + default: [''] + description: + - Enable user for the following service providers. + type: list + elements: str + shell: + default: '/bin/bash' + description: + - Login shell. + type: str + street: + description: + - Street of users business address. + type: str + title: + description: + - Title, for example V(Prof.). + type: str + unixhome: + description: + - Unix home directory. + - If not specified, it defaults to C(/home/$USERNAME). + type: str + userexpiry: + description: + - Account expiry date, for example V(1999-12-31). + - If not specified, it defaults to the current day plus one year. + type: str + position: + default: '' + description: + - Define the whole position of users object inside the LDAP tree, for example V(cn=employee,cn=users,ou=school,dc=example,dc=com). + type: str + update_password: + default: always + choices: [always, on_create] + description: + - V(always) will update passwords if they differ. V(on_create) will only set the password for newly created users. + type: str + ou: + default: '' + description: + - Organizational Unit inside the LDAP Base DN, for example V(school) for LDAP OU C(ou=school,dc=example,dc=com). + type: str + subpath: + default: 'cn=users' + description: + - LDAP subpath inside the organizational unit, for example V(cn=teachers,cn=users) for LDAP container C(cn=teachers,cn=users,dc=example,dc=com). + type: str +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a user on a UCS community.general.udm_user: name: FooBar @@ -325,10 +313,10 @@ EXAMPLES = ''' firstname: Foo lastname: Bar position: 'cn=teachers,cn=users,ou=school,dc=school,dc=example,dc=com' -''' +""" -RETURN = '''# ''' +RETURN = """# """ from datetime import date, timedelta import traceback diff --git a/plugins/modules/ufw.py b/plugins/modules/ufw.py index fba0ef5fe2..e0d765eeac 100644 --- a/plugins/modules/ufw.py +++ b/plugins/modules/ufw.py @@ -11,26 +11,24 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ufw short_description: Manage firewall with UFW description: - - Manage firewall with UFW. + - Manage firewall with UFW. author: - - Aleksey Ovcharenko (@ovcharenko) - - Jarno Keskikangas (@pyykkis) - - Ahti Kitsik (@ahtik) + - Aleksey Ovcharenko (@ovcharenko) + - Jarno Keskikangas (@pyykkis) + - Ahti Kitsik (@ahtik) notes: - - See C(man ufw) for more examples. - - > - B(Warning:) Whilst the module itself can be run using concurrent strategies, C(ufw) does not support concurrency, - as firewall rules are meant to be ordered and parallel executions do not guarantee order. - B(Do not use concurrency:) The results are unpredictable and the module may fail silently if you do. + - See C(man ufw) for more examples. + - "B(Warning:) Whilst the module itself can be run using concurrent strategies, C(ufw) does not support concurrency, as firewall rules are meant + to be ordered and parallel executions do not guarantee order. B(Do not use concurrency:) The results are unpredictable and the module may + fail silently if you do." requirements: - - C(ufw) package + - C(ufw) package extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: support: full @@ -44,59 +42,52 @@ options: - V(reloaded) reloads firewall. - V(reset) disables and resets firewall to installation defaults. type: str - choices: [ disabled, enabled, reloaded, reset ] + choices: [disabled, enabled, reloaded, reset] default: description: - Change the default policy for incoming or outgoing traffic. type: str - choices: [ allow, deny, reject ] - aliases: [ policy ] + choices: [allow, deny, reject] + aliases: [policy] direction: description: - - Select direction for a rule or default policy command. Mutually - exclusive with O(interface_in) and O(interface_out). + - Select direction for a rule or default policy command. Mutually exclusive with O(interface_in) and O(interface_out). type: str - choices: [ in, incoming, out, outgoing, routed ] + choices: [in, incoming, out, outgoing, routed] logging: description: - Toggles logging. Logged packets use the LOG_KERN syslog facility. type: str - choices: [ 'on', 'off', low, medium, high, full ] + choices: ['on', 'off', low, medium, high, full] insert: description: - Insert the corresponding rule as rule number NUM. - Note that ufw numbers rules starting with 1. - - If O(delete=true) and a value is provided for O(insert), - then O(insert) is ignored. + - If O(delete=true) and a value is provided for O(insert), then O(insert) is ignored. type: int insert_relative_to: description: - Allows to interpret the index in O(insert) relative to a position. - - V(zero) interprets the rule number as an absolute index (i.e. 1 is - the first rule). - - V(first-ipv4) interprets the rule number relative to the index of the - first IPv4 rule, or relative to the position where the first IPv4 rule + - V(zero) interprets the rule number as an absolute index (that is, 1 is the first rule). + - V(first-ipv4) interprets the rule number relative to the index of the first IPv4 rule, or relative to the position where the first IPv4 + rule would be if there is currently none. + - V(last-ipv4) interprets the rule number relative to the index of the last IPv4 rule, or relative to the position where the last IPv4 rule would be if there is currently none. - - V(last-ipv4) interprets the rule number relative to the index of the - last IPv4 rule, or relative to the position where the last IPv4 rule - would be if there is currently none. - - V(first-ipv6) interprets the rule number relative to the index of the - first IPv6 rule, or relative to the position where the first IPv6 rule - would be if there is currently none. - - V(last-ipv6) interprets the rule number relative to the index of the - last IPv6 rule, or relative to the position where the last IPv6 rule + - V(first-ipv6) interprets the rule number relative to the index of the first IPv6 rule, or relative to the position where the first IPv6 + rule would be if there is currently none. + - V(last-ipv6) interprets the rule number relative to the index of the last IPv6 rule, or relative to the position where the last IPv6 rule would be if there is currently none. type: str - choices: [ first-ipv4, first-ipv6, last-ipv4, last-ipv6, zero ] + choices: [first-ipv4, first-ipv6, last-ipv4, last-ipv6, zero] default: zero rule: description: - - Add firewall rule + - Add firewall rule. type: str - choices: [ allow, deny, limit, reject ] + choices: [allow, deny, limit, reject] log: description: - - Log new connections matched to this rule + - Log new connections matched to this rule. type: bool default: false from_ip: @@ -104,7 +95,7 @@ options: - Source IP address. type: str default: any - aliases: [ from, src ] + aliases: [from, src] from_port: description: - Source port. @@ -114,54 +105,49 @@ options: - Destination IP address. type: str default: any - aliases: [ dest, to] + aliases: [dest, to] to_port: description: - Destination port. type: str - aliases: [ port ] + aliases: [port] proto: description: - TCP/IP protocol. type: str - choices: [ any, tcp, udp, ipv6, esp, ah, gre, igmp ] - aliases: [ protocol ] + choices: [any, tcp, udp, ipv6, esp, ah, gre, igmp] + aliases: [protocol] name: description: - Use profile located in C(/etc/ufw/applications.d). type: str - aliases: [ app ] + aliases: [app] delete: description: - Delete rule. - - If O(delete=true) and a value is provided for O(insert), - then O(insert) is ignored. + - If O(delete=true) and a value is provided for O(insert), then O(insert) is ignored. type: bool default: false interface: description: - - Specify interface for the rule. The direction (in or out) used - for the interface depends on the value of O(direction). See - O(interface_in) and O(interface_out) for routed rules that needs - to supply both an input and output interface. Mutually - exclusive with O(interface_in) and O(interface_out). + - Specify interface for the rule. The direction (in or out) used for the interface depends on the value of O(direction). See O(interface_in) + and O(interface_out) for routed rules that needs to supply both an input and output interface. Mutually exclusive with O(interface_in) + and O(interface_out). type: str - aliases: [ if ] + aliases: [if] interface_in: description: - - Specify input interface for the rule. This is mutually - exclusive with O(direction) and O(interface). However, it is - compatible with O(interface_out) for routed rules. + - Specify input interface for the rule. This is mutually exclusive with O(direction) and O(interface). However, it is compatible with O(interface_out) + for routed rules. type: str - aliases: [ if_in ] + aliases: [if_in] version_added: '0.2.0' interface_out: description: - - Specify output interface for the rule. This is mutually - exclusive with O(direction) and O(interface). However, it is - compatible with O(interface_in) for routed rules. + - Specify output interface for the rule. This is mutually exclusive with O(direction) and O(interface). However, it is compatible with O(interface_in) + for routed rules. type: str - aliases: [ if_out ] + aliases: [if_out] version_added: '0.2.0' route: description: @@ -172,9 +158,9 @@ options: description: - Add a comment to the rule. Requires UFW version >=0.35. type: str -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Allow everything and enable UFW community.general.ufw: state: enabled @@ -299,7 +285,7 @@ EXAMPLES = r''' route: true src: 192.0.2.0/24 dest: 198.51.100.0/24 -''' +""" import re diff --git a/plugins/modules/uptimerobot.py b/plugins/modules/uptimerobot.py index c1894e90a0..ed6b6431f1 100644 --- a/plugins/modules/uptimerobot.py +++ b/plugins/modules/uptimerobot.py @@ -8,44 +8,43 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' - +DOCUMENTATION = r""" module: uptimerobot short_description: Pause and start Uptime Robot monitoring description: - - This module will let you start and pause Uptime Robot Monitoring + - This module will let you start and pause Uptime Robot Monitoring. author: "Nate Kingsley (@nate-kingsley)" requirements: - - Valid Uptime Robot API Key + - Valid Uptime Robot API Key extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - state: - type: str - description: - - Define whether or not the monitor should be running or paused. - required: true - choices: [ "started", "paused" ] - monitorid: - type: str - description: - - ID of the monitor to check. - required: true - apikey: - type: str - description: - - Uptime Robot API key. - required: true + state: + type: str + description: + - Define whether or not the monitor should be running or paused. + required: true + choices: ["started", "paused"] + monitorid: + type: str + description: + - ID of the monitor to check. + required: true + apikey: + type: str + description: + - Uptime Robot API key. + required: true notes: - - Support for adding and removing monitors and alert contacts has not yet been implemented. -''' + - Support for adding and removing monitors and alert contacts has not yet been implemented. +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Pause the monitor with an ID of 12345 community.general.uptimerobot: monitorid: 12345 @@ -57,7 +56,7 @@ EXAMPLES = ''' monitorid: 12345 apikey: 12345-1234512345 state: started -''' +""" import json diff --git a/plugins/modules/urpmi.py b/plugins/modules/urpmi.py index 75c0af90fc..9c08a22c21 100644 --- a/plugins/modules/urpmi.py +++ b/plugins/modules/urpmi.py @@ -11,12 +11,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: urpmi short_description: Urpmi manager description: - - Manages packages with C(urpmi) (such as for Mageia or Mandriva) + - Manages packages with C(urpmi) (such as for Mageia or Mandriva). extends_documentation_fragment: - community.general.attributes attributes: @@ -29,13 +28,13 @@ options: description: - A list of package names to install, upgrade or remove. required: true - aliases: [ package, pkg ] + aliases: [package, pkg] type: list elements: str state: description: - Indicates the desired package state. - choices: [ absent, present, installed, removed ] + choices: [absent, present, installed, removed] default: present type: str update_cache: @@ -50,21 +49,19 @@ options: default: true force: description: - - Assume "yes" is the answer to any question urpmi has to ask. - Corresponds to the C(--force) option for C(urpmi). + - Assume "yes" is the answer to any question urpmi has to ask. Corresponds to the C(--force) option for C(urpmi). type: bool default: true root: description: - - Specifies an alternative install root, relative to which all packages will be installed. - Corresponds to the C(--root) option for C(urpmi). - aliases: [ installroot ] + - Specifies an alternative install root, relative to which all packages will be installed. Corresponds to the C(--root) option for C(urpmi). + aliases: [installroot] type: str author: -- Philippe Makowski (@pmakowski) -''' + - Philippe Makowski (@pmakowski) +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Install package foo community.general.urpmi: pkg: foo @@ -85,7 +82,7 @@ EXAMPLES = ''' name: bar state: present update_cache: true -''' +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/usb_facts.py b/plugins/modules/usb_facts.py index 340c71ee54..4f0195bde3 100644 --- a/plugins/modules/usb_facts.py +++ b/plugins/modules/usb_facts.py @@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: usb_facts short_description: Allows listing information about USB devices version_added: 8.5.0 @@ -25,9 +24,9 @@ extends_documentation_fragment: - community.general.attributes.facts_module requirements: - lsusb binary on PATH (usually installed through the package usbutils and preinstalled on many systems) -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Get information about USB devices community.general.usb_facts: @@ -35,9 +34,9 @@ EXAMPLES = ''' ansible.builtin.debug: msg: "On bus {{ item.bus }} device {{ item.device }} with id {{ item.id }} is {{ item.name }}" loop: "{{ ansible_facts.usb_devices }}" -''' +""" -RETURN = r''' +RETURN = r""" ansible_facts: description: Dictionary containing details of connected USB devices. returned: always @@ -69,7 +68,7 @@ ansible_facts: returned: always type: str sample: Linux Foundation 2.0 root hub -''' +""" import re from ansible.module_utils.basic import AnsibleModule