diff --git a/plugins/modules/ip_netns.py b/plugins/modules/ip_netns.py index 69534c810d..6bcae8e5f2 100644 --- a/plugins/modules/ip_netns.py +++ b/plugins/modules/ip_netns.py @@ -7,37 +7,36 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: ip_netns author: "Arie Bregman (@bregman-arie)" short_description: Manage network namespaces -requirements: [ ip ] +requirements: [ip] description: - - Create or delete network namespaces using the ip command. + - Create or delete network namespaces using the C(ip) command. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: none + check_mode: + support: full + diff_mode: + support: none options: - name: - required: false - description: - - Name of the namespace - type: str - state: - required: false - default: "present" - choices: [ present, absent ] - description: - - Whether the namespace should exist - type: str -''' + name: + required: false + description: + - Name of the namespace. + type: str + state: + required: false + default: "present" + choices: [present, absent] + description: + - Whether the namespace should exist. + type: str +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a namespace named mario community.general.ip_netns: name: mario @@ -47,11 +46,11 @@ EXAMPLES = ''' community.general.ip_netns: name: luigi state: absent -''' +""" -RETURN = ''' +RETURN = r""" # Default return values -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.common.text.converters import to_text diff --git a/plugins/modules/ipa_config.py b/plugins/modules/ipa_config.py index 871643fd7b..ea08f8f8ba 100644 --- a/plugins/modules/ipa_config.py +++ b/plugins/modules/ipa_config.py @@ -7,8 +7,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ipa_config author: Fran Fitzpatrick (@fxfitz) short_description: Manage Global FreeIPA Configuration Settings @@ -115,10 +114,9 @@ options: extends_documentation_fragment: - community.general.ipa.documentation - community.general.attributes +""" -''' - -EXAMPLES = r''' +EXAMPLES = r""" - name: Ensure password plugin features DC:Disable Last Success and KDC:Disable Lockout are enabled community.general.ipa_config: ipaconfigstring: ["KDC:Disable Last Success", "KDC:Disable Lockout"] @@ -221,14 +219,14 @@ EXAMPLES = r''' ipa_host: localhost ipa_user: admin ipa_pass: supersecret -''' +""" -RETURN = r''' +RETURN = r""" config: description: Configuration as returned by IPA API. returned: always type: dict -''' +""" import traceback diff --git a/plugins/modules/ipa_dnsrecord.py b/plugins/modules/ipa_dnsrecord.py index 1dad138377..d92e2c4f66 100644 --- a/plugins/modules/ipa_dnsrecord.py +++ b/plugins/modules/ipa_dnsrecord.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ipa_dnsrecord author: Abhijeet Kasurde (@Akasurde) short_description: Manage FreeIPA DNS records @@ -23,64 +22,66 @@ attributes: options: zone_name: description: - - The DNS zone name to which DNS record needs to be managed. + - The DNS zone name to which DNS record needs to be managed. required: true type: str record_name: description: - - The DNS record name to manage. + - The DNS record name to manage. required: true aliases: ["name"] type: str record_type: description: - - The type of DNS record name. - - Support for V(NS) was added in comunity.general 8.2.0. - - Support for V(SSHFP) was added in community.general 9.1.0. + - The type of DNS record name. + - Support for V(NS) was added in comunity.general 8.2.0. + - Support for V(SSHFP) was added in community.general 9.1.0. required: false default: 'A' choices: ['A', 'AAAA', 'A6', 'CNAME', 'DNAME', 'MX', 'NS', 'PTR', 'SRV', 'TXT', 'SSHFP'] type: str record_value: description: - - Manage DNS record name with this value. - - Mutually exclusive with O(record_values), and exactly one of O(record_value) and O(record_values) has to be specified. - - Use O(record_values) if you need to specify multiple values. - - In the case of V(A) or V(AAAA) record types, this will be the IP address. - - In the case of V(A6) record type, this will be the A6 Record data. - - In the case of V(CNAME) record type, this will be the hostname. - - In the case of V(DNAME) record type, this will be the DNAME target. - - In the case of V(NS) record type, this will be the name server hostname. Hostname must already have a valid A or AAAA record. - - In the case of V(PTR) record type, this will be the hostname. - - In the case of V(TXT) record type, this will be a text. - - In the case of V(SRV) record type, this will be a service record. - - In the case of V(MX) record type, this will be a mail exchanger record. - - In the case of V(SSHFP) record type, this will be an SSH fingerprint record. + - Manage DNS record name with this value. + - Mutually exclusive with O(record_values), and exactly one of O(record_value) and O(record_values) has to be specified. + - Use O(record_values) if you need to specify multiple values. + - In the case of V(A) or V(AAAA) record types, this will be the IP address. + - In the case of V(A6) record type, this will be the A6 Record data. + - In the case of V(CNAME) record type, this will be the hostname. + - In the case of V(DNAME) record type, this will be the DNAME target. + - In the case of V(NS) record type, this will be the name server hostname. Hostname must already have a valid A or AAAA + record. + - In the case of V(PTR) record type, this will be the hostname. + - In the case of V(TXT) record type, this will be a text. + - In the case of V(SRV) record type, this will be a service record. + - In the case of V(MX) record type, this will be a mail exchanger record. + - In the case of V(SSHFP) record type, this will be an SSH fingerprint record. type: str record_values: description: - - Manage DNS record name with this value. - - Mutually exclusive with O(record_value), and exactly one of O(record_value) and O(record_values) has to be specified. - - In the case of V(A) or V(AAAA) record types, this will be the IP address. - - In the case of V(A6) record type, this will be the A6 Record data. - - In the case of V(CNAME) record type, this will be the hostname. - - In the case of V(DNAME) record type, this will be the DNAME target. - - In the case of V(NS) record type, this will be the name server hostname. Hostname must already have a valid A or AAAA record. - - In the case of V(PTR) record type, this will be the hostname. - - In the case of V(TXT) record type, this will be a text. - - In the case of V(SRV) record type, this will be a service record. - - In the case of V(MX) record type, this will be a mail exchanger record. - - In the case of V(SSHFP) record type, this will be an SSH fingerprint record. + - Manage DNS record name with this value. + - Mutually exclusive with O(record_value), and exactly one of O(record_value) and O(record_values) has to be specified. + - In the case of V(A) or V(AAAA) record types, this will be the IP address. + - In the case of V(A6) record type, this will be the A6 Record data. + - In the case of V(CNAME) record type, this will be the hostname. + - In the case of V(DNAME) record type, this will be the DNAME target. + - In the case of V(NS) record type, this will be the name server hostname. Hostname must already have a valid A or AAAA + record. + - In the case of V(PTR) record type, this will be the hostname. + - In the case of V(TXT) record type, this will be a text. + - In the case of V(SRV) record type, this will be a service record. + - In the case of V(MX) record type, this will be a mail exchanger record. + - In the case of V(SSHFP) record type, this will be an SSH fingerprint record. type: list elements: str record_ttl: description: - - Set the TTL for the record. - - Applies only when adding a new or changing the value of O(record_value) or O(record_values). + - Set the TTL for the record. + - Applies only when adding a new or changing the value of O(record_value) or O(record_values). required: false type: int state: - description: State to ensure + description: State to ensure. required: false default: present choices: ["absent", "present"] @@ -88,10 +89,9 @@ options: extends_documentation_fragment: - community.general.ipa.documentation - community.general.attributes +""" -''' - -EXAMPLES = r''' +EXAMPLES = r""" - name: Ensure dns record is present community.general.ipa_dnsrecord: ipa_host: spider.example.com @@ -189,14 +189,14 @@ EXAMPLES = r''' ipa_host: ipa.example.com ipa_user: admin ipa_pass: ChangeMe! -''' +""" -RETURN = r''' +RETURN = r""" dnsrecord: description: DNS record as returned by IPA API. returned: always type: dict -''' +""" import traceback diff --git a/plugins/modules/ipa_dnszone.py b/plugins/modules/ipa_dnszone.py index 6699b0525b..b536c258d2 100644 --- a/plugins/modules/ipa_dnszone.py +++ b/plugins/modules/ipa_dnszone.py @@ -8,13 +8,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ipa_dnszone author: Fran Fitzpatrick (@fxfitz) short_description: Manage FreeIPA DNS Zones description: - - Add and delete an IPA DNS Zones using IPA API + - Add and delete an IPA DNS Zones using IPA API. attributes: check_mode: support: full @@ -23,11 +22,11 @@ attributes: options: zone_name: description: - - The DNS zone name to which needs to be managed. + - The DNS zone name to which needs to be managed. required: true type: str state: - description: State to ensure + description: State to ensure. required: false default: present choices: ["absent", "present"] @@ -44,10 +43,9 @@ options: extends_documentation_fragment: - community.general.ipa.documentation - community.general.attributes +""" -''' - -EXAMPLES = r''' +EXAMPLES = r""" - name: Ensure dns zone is present community.general.ipa_dnszone: ipa_host: spider.example.com @@ -78,14 +76,14 @@ EXAMPLES = r''' state: present zone_name: example.com allowsyncptr: true -''' +""" -RETURN = r''' +RETURN = r""" zone: description: DNS zone as returned by IPA API. returned: always type: dict -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.ipa import IPAClient, ipa_argument_spec diff --git a/plugins/modules/ipa_getkeytab.py b/plugins/modules/ipa_getkeytab.py index 643e18cf62..dfd612564b 100644 --- a/plugins/modules/ipa_getkeytab.py +++ b/plugins/modules/ipa_getkeytab.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ipa_getkeytab short_description: Manage keytab file in FreeIPA version_added: 9.5.0 @@ -82,7 +81,8 @@ options: state: description: - The state of the keytab file. - - V(present) only check for existence of a file, if you want to recreate keytab with other parameters you should set O(force=true). + - V(present) only check for existence of a file, if you want to recreate keytab with other parameters you should set + O(force=true). type: str default: present choices: ["present", "absent"] @@ -95,9 +95,9 @@ requirements: - Managed host is FreeIPA client extends_documentation_fragment: - community.general.attributes -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Get Kerberos ticket using default principal community.general.krb_ticket: password: "{{ aldpro_admin_password }}" @@ -121,7 +121,7 @@ EXAMPLES = r''' principal: HTTP/freeipa-dc02.ipa.test ipa_host: freeipa-dc01.ipa.test force: true -''' +""" import os diff --git a/plugins/modules/ipa_group.py b/plugins/modules/ipa_group.py index 92470606fc..60077a2c6a 100644 --- a/plugins/modules/ipa_group.py +++ b/plugins/modules/ipa_group.py @@ -7,13 +7,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ipa_group author: Thomas Krahn (@Nosmoht) short_description: Manage FreeIPA group description: - - Add, modify and delete group within IPA server + - Add, modify and delete group within IPA server. attributes: check_mode: support: full @@ -22,77 +21,76 @@ attributes: options: append: description: - - If V(true), add the listed O(user) and O(group) to the group members. - - If V(false), only the listed O(user) and O(group) will be group members, removing any other members. + - If V(true), add the listed O(user) and O(group) to the group members. + - If V(false), only the listed O(user) and O(group) will be group members, removing any other members. default: false type: bool version_added: 4.0.0 cn: description: - - Canonical name. - - Can not be changed as it is the unique identifier. + - Canonical name. + - Can not be changed as it is the unique identifier. required: true aliases: ['name'] type: str description: description: - - Description of the group. + - Description of the group. type: str external: description: - - Allow adding external non-IPA members from trusted domains. + - Allow adding external non-IPA members from trusted domains. type: bool gidnumber: description: - - GID (use this option to set it manually). + - GID (use this option to set it manually). aliases: ['gid'] type: str group: description: - - List of group names assigned to this group. - - If O(append=false) and an empty list is passed all groups will be removed from this group. - - Groups that are already assigned but not passed will be removed. - - If O(append=true) the listed groups will be assigned without removing other groups. - - If option is omitted assigned groups will not be checked or changed. + - List of group names assigned to this group. + - If O(append=false) and an empty list is passed all groups will be removed from this group. + - Groups that are already assigned but not passed will be removed. + - If O(append=true) the listed groups will be assigned without removing other groups. + - If option is omitted assigned groups will not be checked or changed. type: list elements: str nonposix: description: - - Create as a non-POSIX group. + - Create as a non-POSIX group. type: bool user: description: - - List of user names assigned to this group. - - If O(append=false) and an empty list is passed all users will be removed from this group. - - Users that are already assigned but not passed will be removed. - - If O(append=true) the listed users will be assigned without removing other users. - - If option is omitted assigned users will not be checked or changed. + - List of user names assigned to this group. + - If O(append=false) and an empty list is passed all users will be removed from this group. + - Users that are already assigned but not passed will be removed. + - If O(append=true) the listed users will be assigned without removing other users. + - If option is omitted assigned users will not be checked or changed. type: list elements: str external_user: description: - - List of external users assigned to this group. - - Behaves identically to O(user) with respect to O(append) attribute. - - List entries can be in V(DOMAIN\\\\username) or SID format. - - Unless SIDs are provided, the module will always attempt to make changes even if the group already has all the users. - This is because only SIDs are returned by IPA query. - - O(external=true) is needed for this option to work. + - List of external users assigned to this group. + - Behaves identically to O(user) with respect to O(append) attribute. + - List entries can be in V(DOMAIN\\\\username) or SID format. + - Unless SIDs are provided, the module will always attempt to make changes even if the group already has all the users. + This is because only SIDs are returned by IPA query. + - O(external=true) is needed for this option to work. type: list elements: str version_added: 6.3.0 state: description: - - State to ensure + - State to ensure. default: "present" choices: ["absent", "present"] type: str extends_documentation_fragment: - community.general.ipa.documentation - community.general.attributes +""" -''' - -EXAMPLES = r''' +EXAMPLES = r""" - name: Ensure group is present community.general.ipa_group: name: oinstall @@ -106,8 +104,8 @@ EXAMPLES = r''' community.general.ipa_group: name: ops group: - - sysops - - appops + - sysops + - appops ipa_host: ipa.example.com ipa_user: admin ipa_pass: topsecret @@ -116,8 +114,8 @@ EXAMPLES = r''' community.general.ipa_group: name: sysops user: - - linus - - larry + - linus + - larry ipa_host: ipa.example.com ipa_user: admin ipa_pass: topsecret @@ -126,7 +124,7 @@ EXAMPLES = r''' community.general.ipa_group: name: developers user: - - john + - john append: true state: present ipa_host: ipa.example.com @@ -135,25 +133,25 @@ EXAMPLES = r''' - name: Add external user to a group community.general.ipa_group: - name: developers - external: true - append: true - external_user: - - S-1-5-21-123-1234-12345-63421 - ipa_host: ipa.example.com - ipa_user: admin - ipa_pass: topsecret + name: developers + external: true + append: true + external_user: + - S-1-5-21-123-1234-12345-63421 + ipa_host: ipa.example.com + ipa_user: admin + ipa_pass: topsecret - name: Add a user from MYDOMAIN community.general.ipa_group: - name: developers - external: true - append: true - external_user: - - MYDOMAIN\\john - ipa_host: ipa.example.com - ipa_user: admin - ipa_pass: topsecret + name: developers + external: true + append: true + external_user: + - MYDOMAIN\\john + ipa_host: ipa.example.com + ipa_user: admin + ipa_pass: topsecret - name: Ensure group is absent community.general.ipa_group: @@ -162,14 +160,14 @@ EXAMPLES = r''' ipa_host: ipa.example.com ipa_user: admin ipa_pass: topsecret -''' +""" -RETURN = r''' +RETURN = r""" group: - description: Group as returned by IPA API + description: Group as returned by IPA API. returned: always type: dict -''' +""" import traceback diff --git a/plugins/modules/ipa_hbacrule.py b/plugins/modules/ipa_hbacrule.py index 77a4d0d487..d168a3a7e0 100644 --- a/plugins/modules/ipa_hbacrule.py +++ b/plugins/modules/ipa_hbacrule.py @@ -7,8 +7,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ipa_hbacrule author: Thomas Krahn (@Nosmoht) short_description: Manage FreeIPA HBAC rule @@ -22,99 +21,98 @@ attributes: options: cn: description: - - Canonical name. - - Can not be changed as it is the unique identifier. + - Canonical name. + - Can not be changed as it is the unique identifier. required: true aliases: ["name"] type: str description: - description: Description + description: Description. type: str host: description: - - List of host names to assign. - - If an empty list is passed all hosts will be removed from the rule. - - If option is omitted hosts will not be checked or changed. + - List of host names to assign. + - If an empty list is passed all hosts will be removed from the rule. + - If option is omitted hosts will not be checked or changed. required: false type: list elements: str hostcategory: - description: Host category + description: Host category. choices: ['all'] type: str hostgroup: description: - - List of hostgroup names to assign. - - If an empty list is passed all hostgroups will be removed. from the rule - - If option is omitted hostgroups will not be checked or changed. + - List of hostgroup names to assign. + - If an empty list is passed all hostgroups will be removed from the rule. + - If option is omitted hostgroups will not be checked or changed. type: list elements: str service: description: - - List of service names to assign. - - If an empty list is passed all services will be removed from the rule. - - If option is omitted services will not be checked or changed. + - List of service names to assign. + - If an empty list is passed all services will be removed from the rule. + - If option is omitted services will not be checked or changed. type: list elements: str servicecategory: - description: Service category + description: Service category. choices: ['all'] type: str servicegroup: description: - - List of service group names to assign. - - If an empty list is passed all assigned service groups will be removed from the rule. - - If option is omitted service groups will not be checked or changed. + - List of service group names to assign. + - If an empty list is passed all assigned service groups will be removed from the rule. + - If option is omitted service groups will not be checked or changed. type: list elements: str sourcehost: description: - - List of source host names to assign. - - If an empty list if passed all assigned source hosts will be removed from the rule. - - If option is omitted source hosts will not be checked or changed. + - List of source host names to assign. + - If an empty list if passed all assigned source hosts will be removed from the rule. + - If option is omitted source hosts will not be checked or changed. type: list elements: str sourcehostcategory: - description: Source host category + description: Source host category. choices: ['all'] type: str sourcehostgroup: description: - - List of source host group names to assign. - - If an empty list if passed all assigned source host groups will be removed from the rule. - - If option is omitted source host groups will not be checked or changed. + - List of source host group names to assign. + - If an empty list if passed all assigned source host groups will be removed from the rule. + - If option is omitted source host groups will not be checked or changed. type: list elements: str state: - description: State to ensure + description: State to ensure. default: "present" - choices: ["absent", "disabled", "enabled","present"] + choices: ["absent", "disabled", "enabled", "present"] type: str user: description: - - List of user names to assign. - - If an empty list if passed all assigned users will be removed from the rule. - - If option is omitted users will not be checked or changed. + - List of user names to assign. + - If an empty list if passed all assigned users will be removed from the rule. + - If option is omitted users will not be checked or changed. type: list elements: str usercategory: - description: User category + description: User category. choices: ['all'] type: str usergroup: description: - - List of user group names to assign. - - If an empty list if passed all assigned user groups will be removed from the rule. - - If option is omitted user groups will not be checked or changed. + - List of user group names to assign. + - If an empty list if passed all assigned user groups will be removed from the rule. + - If option is omitted user groups will not be checked or changed. type: list elements: str extends_documentation_fragment: - community.general.ipa.documentation - community.general.attributes +""" -''' - -EXAMPLES = r''' +EXAMPLES = r""" - name: Ensure rule to allow all users to access any host from any host community.general.ipa_hbacrule: name: allow_all @@ -132,9 +130,9 @@ EXAMPLES = r''' name: allow_all_developers_access_to_db description: Allow all developers to access any database from any host hostgroup: - - db-server + - db-server usergroup: - - developers + - developers state: present ipa_host: ipa.example.com ipa_user: admin @@ -147,14 +145,14 @@ EXAMPLES = r''' ipa_host: ipa.example.com ipa_user: admin ipa_pass: topsecret -''' +""" -RETURN = r''' +RETURN = r""" hbacrule: description: HBAC rule as returned by IPA API. returned: always type: dict -''' +""" import traceback diff --git a/plugins/modules/ipa_host.py b/plugins/modules/ipa_host.py index 791cee91f3..b2f76ac8f3 100644 --- a/plugins/modules/ipa_host.py +++ b/plugins/modules/ipa_host.py @@ -7,8 +7,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ipa_host author: Thomas Krahn (@Nosmoht) short_description: Manage FreeIPA host @@ -22,73 +21,73 @@ attributes: options: fqdn: description: - - Full qualified domain name. - - Can not be changed as it is the unique identifier. + - Full qualified domain name. + - Can not be changed as it is the unique identifier. required: true aliases: ["name"] type: str description: description: - - A description of this host. + - A description of this host. type: str force: description: - - Force host name even if not in DNS. + - Force host name even if not in DNS. required: false type: bool ip_address: description: - - Add the host to DNS with this IP address. + - Add the host to DNS with this IP address. type: str mac_address: description: - - List of Hardware MAC address(es) off this host. - - If option is omitted MAC addresses will not be checked or changed. - - If an empty list is passed all assigned MAC addresses will be removed. - - MAC addresses that are already assigned but not passed will be removed. + - List of Hardware MAC address(es) off this host. + - If option is omitted MAC addresses will not be checked or changed. + - If an empty list is passed all assigned MAC addresses will be removed. + - MAC addresses that are already assigned but not passed will be removed. aliases: ["macaddress"] type: list elements: str ns_host_location: description: - - Host location (e.g. "Lab 2") + - Host location (for example V(Lab 2)). aliases: ["nshostlocation"] type: str ns_hardware_platform: description: - - Host hardware platform (e.g. "Lenovo T61") + - Host hardware platform (for example V(Lenovo T61")). aliases: ["nshardwareplatform"] type: str ns_os_version: description: - - Host operating system and version (e.g. "Fedora 9") + - Host operating system and version (for example V(Fedora 9)). aliases: ["nsosversion"] type: str user_certificate: description: - - List of Base-64 encoded server certificates. - - If option is omitted certificates will not be checked or changed. - - If an empty list is passed all assigned certificates will be removed. - - Certificates already assigned but not passed will be removed. + - List of Base-64 encoded server certificates. + - If option is omitted certificates will not be checked or changed. + - If an empty list is passed all assigned certificates will be removed. + - Certificates already assigned but not passed will be removed. aliases: ["usercertificate"] type: list elements: str state: description: - - State to ensure. + - State to ensure. default: present choices: ["absent", "disabled", "enabled", "present"] type: str force_creation: description: - - Create host if O(state=disabled) or O(state=enabled) but not present. + - Create host if O(state=disabled) or O(state=enabled) but not present. default: true type: bool version_added: 9.5.0 update_dns: description: - - If set V(true) with O(state=absent), then removes DNS records of the host managed by FreeIPA DNS. - - This option has no effect for states other than "absent". + - If set V(true) with O(state=absent), then removes DNS records of the host managed by FreeIPA DNS. + - This option has no effect for states other than V(absent). type: bool random_password: description: Generate a random password to be used in bulk enrollment. @@ -96,10 +95,9 @@ options: extends_documentation_fragment: - community.general.ipa.documentation - community.general.attributes +""" -''' - -EXAMPLES = r''' +EXAMPLES = r""" - name: Ensure host is present community.general.ipa_host: name: host01.example.com @@ -109,8 +107,8 @@ EXAMPLES = r''' ns_os_version: CentOS 7 ns_hardware_platform: Lenovo T61 mac_address: - - "08:00:27:E3:B1:2D" - - "52:54:00:BD:97:1E" + - "08:00:27:E3:B1:2D" + - "52:54:00:BD:97:1E" state: present ipa_host: ipa.example.com ipa_user: admin @@ -159,18 +157,18 @@ EXAMPLES = r''' ipa_user: admin ipa_pass: topsecret update_dns: true -''' +""" -RETURN = r''' +RETURN = r""" host: description: Host as returned by IPA API. returned: always type: dict host_diff: - description: List of options that differ and would be changed + description: List of options that differ and would be changed. returned: if check mode and a difference is found type: list -''' +""" import traceback diff --git a/plugins/modules/ipa_hostgroup.py b/plugins/modules/ipa_hostgroup.py index 9e6abf32aa..c1e7d3ad56 100644 --- a/plugins/modules/ipa_hostgroup.py +++ b/plugins/modules/ipa_hostgroup.py @@ -7,8 +7,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ipa_hostgroup author: Thomas Krahn (@Nosmoht) short_description: Manage FreeIPA host-group @@ -22,61 +21,61 @@ attributes: options: append: description: - - If V(true), add the listed O(host) to the O(hostgroup). - - If V(false), only the listed O(host) will be in O(hostgroup), removing any other hosts. + - If V(true), add the listed O(host) to the O(hostgroup). + - If V(false), only the listed O(host) will be in O(hostgroup), removing any other hosts. default: false type: bool version_added: 6.6.0 cn: description: - - Name of host-group. - - Can not be changed as it is the unique identifier. + - Name of host-group. + - Can not be changed as it is the unique identifier. required: true aliases: ["name"] type: str description: description: - - Description. + - Description. type: str host: description: - - List of hosts that belong to the host-group. - - If an empty list is passed all hosts will be removed from the group. - - If option is omitted hosts will not be checked or changed. - - If option is passed all assigned hosts that are not passed will be unassigned from the group. + - List of hosts that belong to the host-group. + - If an empty list is passed all hosts will be removed from the group. + - If option is omitted hosts will not be checked or changed. + - If option is passed all assigned hosts that are not passed will be unassigned from the group. type: list elements: str hostgroup: description: - - List of host-groups than belong to that host-group. - - If an empty list is passed all host-groups will be removed from the group. - - If option is omitted host-groups will not be checked or changed. - - If option is passed all assigned hostgroups that are not passed will be unassigned from the group. + - List of host-groups than belong to that host-group. + - If an empty list is passed all host-groups will be removed from the group. + - If option is omitted host-groups will not be checked or changed. + - If option is passed all assigned hostgroups that are not passed will be unassigned from the group. type: list elements: str state: description: - - State to ensure. - - V("absent") and V("disabled") give the same results. - - V("present") and V("enabled") give the same results. + - State to ensure. + - V("absent") and V("disabled") give the same results. + - V("present") and V("enabled") give the same results. default: "present" choices: ["absent", "disabled", "enabled", "present"] type: str extends_documentation_fragment: - community.general.ipa.documentation - community.general.attributes -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Ensure host-group databases is present community.general.ipa_hostgroup: name: databases state: present host: - - db.example.com + - db.example.com hostgroup: - - mysql-server - - oracle-server + - mysql-server + - oracle-server ipa_host: ipa.example.com ipa_user: admin ipa_pass: topsecret @@ -88,14 +87,14 @@ EXAMPLES = r''' ipa_host: ipa.example.com ipa_user: admin ipa_pass: topsecret -''' +""" -RETURN = r''' +RETURN = r""" hostgroup: description: Hostgroup as returned by IPA API. returned: always type: dict -''' +""" import traceback diff --git a/plugins/modules/ipa_otpconfig.py b/plugins/modules/ipa_otpconfig.py index e2d8f0cd52..3c07c7eda3 100644 --- a/plugins/modules/ipa_otpconfig.py +++ b/plugins/modules/ipa_otpconfig.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ipa_otpconfig author: justchris1 (@justchris1) short_description: Manage FreeIPA OTP Configuration Settings @@ -41,10 +40,9 @@ options: extends_documentation_fragment: - community.general.ipa.documentation - community.general.attributes +""" -''' - -EXAMPLES = r''' +EXAMPLES = r""" - name: Ensure the TOTP authentication window is set to 300 seconds community.general.ipa_otpconfig: ipatokentotpauthwindow: '300' @@ -72,14 +70,14 @@ EXAMPLES = r''' ipa_host: localhost ipa_user: admin ipa_pass: supersecret -''' +""" -RETURN = r''' +RETURN = r""" otpconfig: description: OTP configuration as returned by IPA API. returned: always type: dict -''' +""" import traceback diff --git a/plugins/modules/ipa_otptoken.py b/plugins/modules/ipa_otptoken.py index d8a5b3cf1d..5aba671edf 100644 --- a/plugins/modules/ipa_otptoken.py +++ b/plugins/modules/ipa_otptoken.py @@ -7,8 +7,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ipa_otptoken author: justchris1 (@justchris1) short_description: Manage FreeIPA OTPs @@ -31,21 +30,21 @@ options: type: str otptype: description: - - Type of OTP. - - "B(Note:) Cannot be modified after OTP is created." + - Type of OTP. + - B(Note:) Cannot be modified after OTP is created. type: str - choices: [ totp, hotp ] + choices: [totp, hotp] secretkey: description: - - Token secret (Base64). - - If OTP is created and this is not specified, a random secret will be generated by IPA. - - "B(Note:) Cannot be modified after OTP is created." + - Token secret (Base64). + - If OTP is created and this is not specified, a random secret will be generated by IPA. + - B(Note:) Cannot be modified after OTP is created. type: str description: description: Description of the token (informational only). type: str owner: - description: Assigned user of the token. + description: Assigned user of the token. type: str enabled: description: Mark the token as enabled (default V(true)). @@ -53,15 +52,15 @@ options: type: bool notbefore: description: - - First date/time the token can be used. - - In the format C(YYYYMMddHHmmss). - - For example, C(20180121182022) will allow the token to be used starting on 21 January 2018 at 18:20:22. + - First date/time the token can be used. + - In the format C(YYYYMMddHHmmss). + - For example, V(20180121182022) will allow the token to be used starting on 21 January 2018 at 18:20:22. type: str notafter: description: - - Last date/time the token can be used. - - In the format C(YYYYMMddHHmmss). - - For example, C(20200121182022) will allow the token to be used until 21 January 2020 at 18:20:22. + - Last date/time the token can be used. + - In the format C(YYYYMMddHHmmss). + - For example, V(20200121182022) will allow the token to be used until 21 January 2020 at 18:20:22. type: str vendor: description: Token vendor name (informational only). @@ -79,37 +78,37 @@ options: type: str algorithm: description: - - Token hash algorithm. - - "B(Note:) Cannot be modified after OTP is created." + - Token hash algorithm. + - B(Note:) Cannot be modified after OTP is created. choices: ['sha1', 'sha256', 'sha384', 'sha512'] type: str digits: description: - - Number of digits each token code will have. - - "B(Note:) Cannot be modified after OTP is created." - choices: [ 6, 8 ] + - Number of digits each token code will have. + - B(Note:) Cannot be modified after OTP is created. + choices: [6, 8] type: int offset: description: - - TOTP token / IPA server time difference. - - "B(Note:) Cannot be modified after OTP is created." + - TOTP token / IPA server time difference. + - B(Note:) Cannot be modified after OTP is created. type: int interval: description: - - Length of TOTP token code validity in seconds. - - "B(Note:) Cannot be modified after OTP is created." + - Length of TOTP token code validity in seconds. + - B(Note:) Cannot be modified after OTP is created. type: int counter: description: - - Initial counter for the HOTP token. - - "B(Note:) Cannot be modified after OTP is created." + - Initial counter for the HOTP token. + - B(Note:) Cannot be modified after OTP is created. type: int extends_documentation_fragment: - community.general.ipa.documentation - community.general.attributes -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Create a totp for pinky, allowing the IPA server to generate using defaults community.general.ipa_otptoken: uniqueid: Token123 @@ -161,14 +160,14 @@ EXAMPLES = r''' ipa_host: ipa.example.com ipa_user: admin ipa_pass: topsecret -''' +""" -RETURN = r''' +RETURN = r""" otptoken: - description: OTP Token as returned by IPA API + description: OTP Token as returned by IPA API. returned: always type: dict -''' +""" import base64 import traceback diff --git a/plugins/modules/ipa_pwpolicy.py b/plugins/modules/ipa_pwpolicy.py index ba7d702916..5b41651e09 100644 --- a/plugins/modules/ipa_pwpolicy.py +++ b/plugins/modules/ipa_pwpolicy.py @@ -7,152 +7,153 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ipa_pwpolicy author: Adralioh (@adralioh) short_description: Manage FreeIPA password policies description: -- Add, modify, or delete a password policy using the IPA API. + - Add, modify, or delete a password policy using the IPA API. version_added: 2.0.0 attributes: - check_mode: - support: full - diff_mode: - support: none + check_mode: + support: full + diff_mode: + support: none options: - group: - description: - - Name of the group that the policy applies to. - - If omitted, the global policy is used. - aliases: ["name"] - type: str - state: - description: State to ensure. - default: "present" - choices: ["absent", "present"] - type: str - maxpwdlife: - description: Maximum password lifetime (in days). - type: str - minpwdlife: - description: Minimum password lifetime (in hours). - type: str - historylength: - description: - - Number of previous passwords that are remembered. - - Users cannot reuse remembered passwords. - type: str - minclasses: - description: Minimum number of character classes. - type: str - minlength: - description: Minimum password length. - type: str - priority: - description: - - Priority of the policy. - - High number means lower priority. - - Required when C(cn) is not the global policy. - type: str - maxfailcount: - description: Maximum number of consecutive failures before lockout. - type: str - failinterval: - description: Period (in seconds) after which the number of failed login attempts is reset. - type: str - lockouttime: - description: Period (in seconds) for which users are locked out. - type: str - gracelimit: - description: Maximum number of LDAP logins after password expiration. - type: int - version_added: 8.2.0 - maxrepeat: - description: Maximum number of allowed same consecutive characters in the new password. - type: int - version_added: 8.2.0 - maxsequence: - description: Maximum length of monotonic character sequences in the new password. An example of a monotonic sequence of length 5 is V(12345). - type: int - version_added: 8.2.0 - dictcheck: - description: Check whether the password (with possible modifications) matches a word in a dictionary (using cracklib). - type: bool - version_added: 8.2.0 - usercheck: - description: Check whether the password (with possible modifications) contains the user name in some form (if the name has > 3 characters). - type: bool - version_added: 8.2.0 + group: + description: + - Name of the group that the policy applies to. + - If omitted, the global policy is used. + aliases: ["name"] + type: str + state: + description: State to ensure. + default: "present" + choices: ["absent", "present"] + type: str + maxpwdlife: + description: Maximum password lifetime (in days). + type: str + minpwdlife: + description: Minimum password lifetime (in hours). + type: str + historylength: + description: + - Number of previous passwords that are remembered. + - Users cannot reuse remembered passwords. + type: str + minclasses: + description: Minimum number of character classes. + type: str + minlength: + description: Minimum password length. + type: str + priority: + description: + - Priority of the policy. + - High number means lower priority. + - Required when C(cn) is not the global policy. + type: str + maxfailcount: + description: Maximum number of consecutive failures before lockout. + type: str + failinterval: + description: Period (in seconds) after which the number of failed login attempts is reset. + type: str + lockouttime: + description: Period (in seconds) for which users are locked out. + type: str + gracelimit: + description: Maximum number of LDAP logins after password expiration. + type: int + version_added: 8.2.0 + maxrepeat: + description: Maximum number of allowed same consecutive characters in the new password. + type: int + version_added: 8.2.0 + maxsequence: + description: Maximum length of monotonic character sequences in the new password. An example of a monotonic sequence of + length 5 is V(12345). + type: int + version_added: 8.2.0 + dictcheck: + description: Check whether the password (with possible modifications) matches a word in a dictionary (using cracklib). + type: bool + version_added: 8.2.0 + usercheck: + description: Check whether the password (with possible modifications) contains the user name in some form (if the name + has > 3 characters). + type: bool + version_added: 8.2.0 extends_documentation_fragment: - community.general.ipa.documentation - community.general.attributes -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Modify the global password policy community.general.ipa_pwpolicy: - maxpwdlife: '90' - minpwdlife: '1' - historylength: '8' - minclasses: '3' - minlength: '16' - maxfailcount: '6' - failinterval: '60' - lockouttime: '600' - ipa_host: ipa.example.com - ipa_user: admin - ipa_pass: topsecret + maxpwdlife: '90' + minpwdlife: '1' + historylength: '8' + minclasses: '3' + minlength: '16' + maxfailcount: '6' + failinterval: '60' + lockouttime: '600' + ipa_host: ipa.example.com + ipa_user: admin + ipa_pass: topsecret - name: Ensure the password policy for the group admins is present community.general.ipa_pwpolicy: - group: admins - state: present - maxpwdlife: '60' - minpwdlife: '24' - historylength: '16' - minclasses: '4' - priority: '10' - minlength: '6' - maxfailcount: '4' - failinterval: '600' - lockouttime: '1200' - gracelimit: 3 - maxrepeat: 3 - maxsequence: 3 - dictcheck: true - usercheck: true - ipa_host: ipa.example.com - ipa_user: admin - ipa_pass: topsecret + group: admins + state: present + maxpwdlife: '60' + minpwdlife: '24' + historylength: '16' + minclasses: '4' + priority: '10' + minlength: '6' + maxfailcount: '4' + failinterval: '600' + lockouttime: '1200' + gracelimit: 3 + maxrepeat: 3 + maxsequence: 3 + dictcheck: true + usercheck: true + ipa_host: ipa.example.com + ipa_user: admin + ipa_pass: topsecret - name: Ensure that the group sysops does not have a unique password policy community.general.ipa_pwpolicy: - group: sysops - state: absent - ipa_host: ipa.example.com - ipa_user: admin - ipa_pass: topsecret -''' + group: sysops + state: absent + ipa_host: ipa.example.com + ipa_user: admin + ipa_pass: topsecret +""" -RETURN = r''' +RETURN = r""" pwpolicy: - description: Password policy as returned by IPA API. - returned: always - type: dict - sample: - cn: ['admins'] - cospriority: ['10'] - dn: 'cn=admins,cn=EXAMPLE.COM,cn=kerberos,dc=example,dc=com' - krbmaxpwdlife: ['60'] - krbminpwdlife: ['24'] - krbpwdfailurecountinterval: ['600'] - krbpwdhistorylength: ['16'] - krbpwdlockoutduration: ['1200'] - krbpwdmaxfailure: ['4'] - krbpwdmindiffchars: ['4'] - objectclass: ['top', 'nscontainer', 'krbpwdpolicy'] -''' + description: Password policy as returned by IPA API. + returned: always + type: dict + sample: + cn: ['admins'] + cospriority: ['10'] + dn: 'cn=admins,cn=EXAMPLE.COM,cn=kerberos,dc=example,dc=com' + krbmaxpwdlife: ['60'] + krbminpwdlife: ['24'] + krbpwdfailurecountinterval: ['600'] + krbpwdhistorylength: ['16'] + krbpwdlockoutduration: ['1200'] + krbpwdmaxfailure: ['4'] + krbpwdmindiffchars: ['4'] + objectclass: ['top', 'nscontainer', 'krbpwdpolicy'] +""" import traceback diff --git a/plugins/modules/ipa_role.py b/plugins/modules/ipa_role.py index fce315b662..e77b732cb2 100644 --- a/plugins/modules/ipa_role.py +++ b/plugins/modules/ipa_role.py @@ -7,13 +7,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ipa_role author: Thomas Krahn (@Nosmoht) short_description: Manage FreeIPA role description: -- Add, modify and delete a role within FreeIPA server using FreeIPA API. + - Add, modify and delete a role within FreeIPA server using FreeIPA API. attributes: check_mode: support: full @@ -22,53 +21,53 @@ attributes: options: cn: description: - - Role name. - - Can not be changed as it is the unique identifier. + - Role name. + - Can not be changed as it is the unique identifier. required: true aliases: ['name'] type: str description: description: - - A description of this role-group. + - A description of this role-group. type: str group: description: - - List of group names assign to this role. - - If an empty list is passed all assigned groups will be unassigned from the role. - - If option is omitted groups will not be checked or changed. - - If option is passed all assigned groups that are not passed will be unassigned from the role. + - List of group names assign to this role. + - If an empty list is passed all assigned groups will be unassigned from the role. + - If option is omitted groups will not be checked or changed. + - If option is passed all assigned groups that are not passed will be unassigned from the role. type: list elements: str host: description: - - List of host names to assign. - - If an empty list is passed all assigned hosts will be unassigned from the role. - - If option is omitted hosts will not be checked or changed. - - If option is passed all assigned hosts that are not passed will be unassigned from the role. + - List of host names to assign. + - If an empty list is passed all assigned hosts will be unassigned from the role. + - If option is omitted hosts will not be checked or changed. + - If option is passed all assigned hosts that are not passed will be unassigned from the role. type: list elements: str hostgroup: description: - - List of host group names to assign. - - If an empty list is passed all assigned host groups will be removed from the role. - - If option is omitted host groups will not be checked or changed. - - If option is passed all assigned hostgroups that are not passed will be unassigned from the role. + - List of host group names to assign. + - If an empty list is passed all assigned host groups will be removed from the role. + - If option is omitted host groups will not be checked or changed. + - If option is passed all assigned hostgroups that are not passed will be unassigned from the role. type: list elements: str privilege: description: - - List of privileges granted to the role. - - If an empty list is passed all assigned privileges will be removed. - - If option is omitted privileges will not be checked or changed. - - If option is passed all assigned privileges that are not passed will be removed. + - List of privileges granted to the role. + - If an empty list is passed all assigned privileges will be removed. + - If option is omitted privileges will not be checked or changed. + - If option is passed all assigned privileges that are not passed will be removed. type: list elements: str service: description: - - List of service names to assign. - - If an empty list is passed all assigned services will be removed from the role. - - If option is omitted services will not be checked or changed. - - If option is passed all assigned services that are not passed will be removed from the role. + - List of service names to assign. + - If an empty list is passed all assigned services will be removed from the role. + - If option is omitted services will not be checked or changed. + - If option is passed all assigned services that are not passed will be removed from the role. type: list elements: str state: @@ -78,26 +77,25 @@ options: type: str user: description: - - List of user names to assign. - - If an empty list is passed all assigned users will be removed from the role. - - If option is omitted users will not be checked or changed. + - List of user names to assign. + - If an empty list is passed all assigned users will be removed from the role. + - If option is omitted users will not be checked or changed. type: list elements: str extends_documentation_fragment: - community.general.ipa.documentation - community.general.attributes +""" -''' - -EXAMPLES = r''' +EXAMPLES = r""" - name: Ensure role is present community.general.ipa_role: name: dba description: Database Administrators state: present user: - - pinky - - brain + - pinky + - brain ipa_host: ipa.example.com ipa_user: admin ipa_pass: topsecret @@ -107,16 +105,16 @@ EXAMPLES = r''' name: another-role description: Just another role group: - - editors + - editors host: - - host01.example.com + - host01.example.com hostgroup: - - hostgroup01 + - hostgroup01 privilege: - - Group Administrators - - User Administrators + - Group Administrators + - User Administrators service: - - service01 + - service01 - name: Ensure role is absent community.general.ipa_role: @@ -125,14 +123,14 @@ EXAMPLES = r''' ipa_host: ipa.example.com ipa_user: admin ipa_pass: topsecret -''' +""" -RETURN = r''' +RETURN = r""" role: description: Role as returned by IPA API. returned: always type: dict -''' +""" import traceback diff --git a/plugins/modules/ipa_service.py b/plugins/modules/ipa_service.py index d9541674f2..54c5575950 100644 --- a/plugins/modules/ipa_service.py +++ b/plugins/modules/ipa_service.py @@ -7,13 +7,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ipa_service author: Cédric Parent (@cprh) short_description: Manage FreeIPA service description: -- Add and delete an IPA service using IPA API. + - Add and delete an IPA service using IPA API. attributes: check_mode: support: full @@ -22,26 +21,26 @@ attributes: options: krbcanonicalname: description: - - Principal of the service. - - Can not be changed as it is the unique identifier. + - Principal of the service. + - Can not be changed as it is the unique identifier. required: true aliases: ["name"] type: str hosts: description: - - Defines the list of 'ManagedBy' hosts. + - Defines the list of C(ManagedBy) hosts. required: false type: list elements: str force: description: - - Force principal name even if host is not in DNS. + - Force principal name even if host is not in DNS. required: false type: bool skip_host_check: description: - - Force service to be created even when host object does not exist to manage it. - - This is only used on creation, not for updating existing services. + - Force service to be created even when host object does not exist to manage it. + - This is only used on creation, not for updating existing services. required: false type: bool default: false @@ -55,10 +54,9 @@ options: extends_documentation_fragment: - community.general.ipa.documentation - community.general.attributes +""" -''' - -EXAMPLES = r''' +EXAMPLES = r""" - name: Ensure service is present community.general.ipa_service: name: http/host01.example.com @@ -79,19 +77,19 @@ EXAMPLES = r''' community.general.ipa_service: name: http/host01.example.com hosts: - - host01.example.com - - host02.example.com + - host01.example.com + - host02.example.com ipa_host: ipa.example.com ipa_user: admin ipa_pass: topsecret -''' +""" -RETURN = r''' +RETURN = r""" service: description: Service as returned by IPA API. returned: always type: dict -''' +""" import traceback diff --git a/plugins/modules/ipa_subca.py b/plugins/modules/ipa_subca.py index 882b1ac396..ddb551689d 100644 --- a/plugins/modules/ipa_subca.py +++ b/plugins/modules/ipa_subca.py @@ -7,13 +7,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ipa_subca author: Abhijeet Kasurde (@Akasurde) short_description: Manage FreeIPA Lightweight Sub Certificate Authorities description: -- Add, modify, enable, disable and delete an IPA Lightweight Sub Certificate Authorities using IPA API. + - Add, modify, enable, disable and delete an IPA Lightweight Sub Certificate Authorities using IPA API. attributes: check_mode: support: full @@ -22,23 +21,23 @@ attributes: options: subca_name: description: - - The Sub Certificate Authority name which needs to be managed. + - The Sub Certificate Authority name which needs to be managed. required: true aliases: ["name"] type: str subca_subject: description: - - The Sub Certificate Authority's Subject. e.g., 'CN=SampleSubCA1,O=testrelm.test'. + - The Sub Certificate Authority's Subject, for example V(CN=SampleSubCA1,O=testrelm.test). required: true type: str subca_desc: description: - - The Sub Certificate Authority's description. + - The Sub Certificate Authority's description. type: str state: description: - - State to ensure. - - State 'disable' and 'enable' is available for FreeIPA 4.4.2 version and onwards. + - State to ensure. + - States V(disable) and V(enable) are available for FreeIPA 4.4.2 version and onwards. required: false default: present choices: ["absent", "disabled", "enabled", "present"] @@ -46,10 +45,9 @@ options: extends_documentation_fragment: - community.general.ipa.documentation - community.general.attributes +""" -''' - -EXAMPLES = ''' +EXAMPLES = r""" - name: Ensure IPA Sub CA is present community.general.ipa_subca: ipa_host: spider.example.com @@ -72,14 +70,14 @@ EXAMPLES = ''' ipa_pass: Passw0rd! state: disable subca_name: AnsibleSubCA1 -''' +""" -RETURN = r''' +RETURN = r""" subca: description: IPA Sub CA record as returned by IPA API. returned: always type: dict -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.ipa import IPAClient, ipa_argument_spec diff --git a/plugins/modules/ipa_sudocmd.py b/plugins/modules/ipa_sudocmd.py index d3139ba1c3..f52d3e9e6d 100644 --- a/plugins/modules/ipa_sudocmd.py +++ b/plugins/modules/ipa_sudocmd.py @@ -7,13 +7,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ipa_sudocmd author: Thomas Krahn (@Nosmoht) short_description: Manage FreeIPA sudo command description: -- Add, modify or delete sudo command within FreeIPA server using FreeIPA API. + - Add, modify or delete sudo command within FreeIPA server using FreeIPA API. attributes: check_mode: support: full @@ -22,13 +21,13 @@ attributes: options: sudocmd: description: - - Sudo command. + - Sudo command. aliases: ['name'] required: true type: str description: description: - - A description of this command. + - A description of this command. type: str state: description: State to ensure. @@ -38,10 +37,9 @@ options: extends_documentation_fragment: - community.general.ipa.documentation - community.general.attributes +""" -''' - -EXAMPLES = r''' +EXAMPLES = r""" - name: Ensure sudo command exists community.general.ipa_sudocmd: name: su @@ -57,14 +55,14 @@ EXAMPLES = r''' ipa_host: ipa.example.com ipa_user: admin ipa_pass: topsecret -''' +""" -RETURN = r''' +RETURN = r""" sudocmd: - description: Sudo command as return from IPA API + description: Sudo command as return from IPA API. returned: always type: dict -''' +""" import traceback diff --git a/plugins/modules/ipa_sudocmdgroup.py b/plugins/modules/ipa_sudocmdgroup.py index a768e74a1a..c7ab798f4c 100644 --- a/plugins/modules/ipa_sudocmdgroup.py +++ b/plugins/modules/ipa_sudocmdgroup.py @@ -7,13 +7,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ipa_sudocmdgroup author: Thomas Krahn (@Nosmoht) short_description: Manage FreeIPA sudo command group description: -- Add, modify or delete sudo command group within IPA server using IPA API. + - Add, modify or delete sudo command group within IPA server using IPA API. attributes: check_mode: support: full @@ -22,13 +21,13 @@ attributes: options: cn: description: - - Sudo Command Group. + - Sudo Command Group. aliases: ['name'] required: true type: str description: description: - - Group description. + - Group description. type: str state: description: State to ensure. @@ -37,24 +36,23 @@ options: type: str sudocmd: description: - - List of sudo commands to assign to the group. - - If an empty list is passed all assigned commands will be removed from the group. - - If option is omitted sudo commands will not be checked or changed. + - List of sudo commands to assign to the group. + - If an empty list is passed all assigned commands will be removed from the group. + - If option is omitted sudo commands will not be checked or changed. type: list elements: str extends_documentation_fragment: - community.general.ipa.documentation - community.general.attributes +""" -''' - -EXAMPLES = r''' +EXAMPLES = r""" - name: Ensure sudo command group exists community.general.ipa_sudocmdgroup: name: group01 description: Group of important commands sudocmd: - - su + - su ipa_host: ipa.example.com ipa_user: admin ipa_pass: topsecret @@ -66,14 +64,14 @@ EXAMPLES = r''' ipa_host: ipa.example.com ipa_user: admin ipa_pass: topsecret -''' +""" -RETURN = r''' +RETURN = r""" sudocmdgroup: - description: Sudo command group as returned by IPA API + description: Sudo command group as returned by IPA API. returned: always type: dict -''' +""" import traceback diff --git a/plugins/modules/ipa_sudorule.py b/plugins/modules/ipa_sudorule.py index 223f6b6de7..1670a52035 100644 --- a/plugins/modules/ipa_sudorule.py +++ b/plugins/modules/ipa_sudorule.py @@ -7,13 +7,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ipa_sudorule author: Thomas Krahn (@Nosmoht) short_description: Manage FreeIPA sudo rule description: -- Add, modify or delete sudo rule within IPA server using IPA API. + - Add, modify or delete sudo rule within IPA server using IPA API. attributes: check_mode: support: full @@ -22,83 +21,83 @@ attributes: options: cn: description: - - Canonical name. - - Can not be changed as it is the unique identifier. + - Canonical name. + - Can not be changed as it is the unique identifier. required: true aliases: ['name'] type: str cmdcategory: description: - - Command category the rule applies to. + - Command category the rule applies to. choices: ['all'] type: str cmd: description: - - List of commands assigned to the rule. - - If an empty list is passed all commands will be removed from the rule. - - If option is omitted commands will not be checked or changed. + - List of commands assigned to the rule. + - If an empty list is passed all commands will be removed from the rule. + - If option is omitted commands will not be checked or changed. type: list elements: str cmdgroup: description: - - List of command groups assigned to the rule. - - If an empty list is passed all command groups will be removed from the rule. - - If option is omitted command groups will not be checked or changed. + - List of command groups assigned to the rule. + - If an empty list is passed all command groups will be removed from the rule. + - If option is omitted command groups will not be checked or changed. type: list elements: str version_added: 2.0.0 deny_cmd: description: - - List of denied commands assigned to the rule. - - If an empty list is passed all commands will be removed from the rule. - - If option is omitted commands will not be checked or changed. + - List of denied commands assigned to the rule. + - If an empty list is passed all commands will be removed from the rule. + - If option is omitted commands will not be checked or changed. type: list elements: str version_added: 8.1.0 deny_cmdgroup: description: - - List of denied command groups assigned to the rule. - - If an empty list is passed all command groups will be removed from the rule. - - If option is omitted command groups will not be checked or changed. + - List of denied command groups assigned to the rule. + - If an empty list is passed all command groups will be removed from the rule. + - If option is omitted command groups will not be checked or changed. type: list elements: str version_added: 8.1.0 description: description: - - Description of the sudo rule. + - Description of the sudo rule. type: str host: description: - - List of hosts assigned to the rule. - - If an empty list is passed all hosts will be removed from the rule. - - If option is omitted hosts will not be checked or changed. - - Option O(hostcategory) must be omitted to assign hosts. + - List of hosts assigned to the rule. + - If an empty list is passed all hosts will be removed from the rule. + - If option is omitted hosts will not be checked or changed. + - Option O(hostcategory) must be omitted to assign hosts. type: list elements: str hostcategory: description: - - Host category the rule applies to. - - If V(all) is passed one must omit O(host) and O(hostgroup). - - Option O(host) and O(hostgroup) must be omitted to assign V(all). + - Host category the rule applies to. + - If V(all) is passed one must omit O(host) and O(hostgroup). + - Option O(host) and O(hostgroup) must be omitted to assign V(all). choices: ['all'] type: str hostgroup: description: - - List of host groups assigned to the rule. - - If an empty list is passed all host groups will be removed from the rule. - - If option is omitted host groups will not be checked or changed. - - Option O(hostcategory) must be omitted to assign host groups. + - List of host groups assigned to the rule. + - If an empty list is passed all host groups will be removed from the rule. + - If option is omitted host groups will not be checked or changed. + - Option O(hostcategory) must be omitted to assign host groups. type: list elements: str runasextusers: description: - - List of external RunAs users + - List of external RunAs users. type: list elements: str version_added: 2.3.0 runasusercategory: description: - - RunAs User category the rule applies to. + - RunAs User category the rule applies to. choices: ['all'] type: str runasgroupcategory: @@ -113,21 +112,21 @@ options: elements: str user: description: - - List of users assigned to the rule. - - If an empty list is passed all users will be removed from the rule. - - If option is omitted users will not be checked or changed. + - List of users assigned to the rule. + - If an empty list is passed all users will be removed from the rule. + - If option is omitted users will not be checked or changed. type: list elements: str usercategory: description: - - User category the rule applies to. + - User category the rule applies to. choices: ['all'] type: str usergroup: description: - - List of user groups assigned to the rule. - - If an empty list is passed all user groups will be removed from the rule. - - If option is omitted user groups will not be checked or changed. + - List of user groups assigned to the rule. + - If an empty list is passed all user groups will be removed from the rule. + - If option is omitted user groups will not be checked or changed. type: list elements: str state: @@ -138,18 +137,18 @@ options: extends_documentation_fragment: - community.general.ipa.documentation - community.general.attributes +""" -''' - -EXAMPLES = r''' -- name: Ensure sudo rule is present that's allows all every body to execute any command on any host without being asked for a password. +EXAMPLES = r""" +- name: Ensure sudo rule is present that's allows all every body to execute any command on any host without being asked + for a password. community.general.ipa_sudorule: name: sudo_all_nopasswd cmdcategory: all description: Allow to run every command with sudo without password hostcategory: all sudoopt: - - '!authenticate' + - '!authenticate' usercategory: all ipa_host: ipa.example.com ipa_user: admin @@ -161,13 +160,13 @@ EXAMPLES = r''' description: Allow developers to run every command with sudo on all database server cmdcategory: all host: - - db01.example.com + - db01.example.com hostgroup: - - db-server + - db-server sudoopt: - - '!authenticate' + - '!authenticate' usergroup: - - developers + - developers ipa_host: ipa.example.com ipa_user: admin ipa_pass: topsecret @@ -177,25 +176,25 @@ EXAMPLES = r''' name: sudo_operations_all description: Allow operators to run any commands that is part of operations-cmdgroup on any host as user root. cmdgroup: - - operations-cmdgroup + - operations-cmdgroup hostcategory: all runasextusers: - - root + - root sudoopt: - - '!authenticate' + - '!authenticate' usergroup: - - operators + - operators ipa_host: ipa.example.com ipa_user: admin ipa_pass: topsecret -''' +""" -RETURN = r''' +RETURN = r""" sudorule: - description: Sudorule as returned by IPA + description: Sudorule as returned by IPA. returned: always type: dict -''' +""" import traceback diff --git a/plugins/modules/ipa_user.py b/plugins/modules/ipa_user.py index e8a1858d0b..039cf3cb70 100644 --- a/plugins/modules/ipa_user.py +++ b/plugins/modules/ipa_user.py @@ -7,13 +7,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ipa_user author: Thomas Krahn (@Nosmoht) short_description: Manage FreeIPA users description: -- Add, modify and delete user within IPA server. + - Add, modify and delete user within IPA server. attributes: check_mode: support: full @@ -25,46 +24,46 @@ options: type: str update_password: description: - - Set password for a user. + - Set password for a user. type: str default: 'always' - choices: [ always, on_create ] + choices: [always, on_create] givenname: description: - - First name. - - If user does not exist and O(state=present), the usage of O(givenname) is required. + - First name. + - If user does not exist and O(state=present), the usage of O(givenname) is required. type: str krbpasswordexpiration: description: - - Date at which the user password will expire. - - In the format YYYYMMddHHmmss. - - e.g. 20180121182022 will expire on 21 January 2018 at 18:20:22. + - Date at which the user password will expire. + - In the format YYYYMMddHHmmss. + - For example V(20180121182022) will expire on 21 January 2018 at 18:20:22. type: str loginshell: description: Login shell. type: str mail: description: - - List of mail addresses assigned to the user. - - If an empty list is passed all assigned email addresses will be deleted. - - If None is passed email addresses will not be checked or changed. + - List of mail addresses assigned to the user. + - If an empty list is passed all assigned email addresses will be deleted. + - If None is passed email addresses will not be checked or changed. type: list elements: str password: description: - - Password for a user. - - Will not be set for an existing user unless O(update_password=always), which is the default. + - Password for a user. + - Will not be set for an existing user unless O(update_password=always), which is the default. type: str sn: description: - - Surname. - - If user does not exist and O(state=present), the usage of O(sn) is required. + - Surname. + - If user does not exist and O(state=present), the usage of O(sn) is required. type: str sshpubkey: description: - - List of public SSH key. - - If an empty list is passed all assigned public keys will be deleted. - - If None is passed SSH public keys will not be checked or changed. + - List of public SSH key. + - If an empty list is passed all assigned public keys will be deleted. + - If None is passed SSH public keys will not be checked or changed. type: list elements: str state: @@ -74,37 +73,37 @@ options: type: str telephonenumber: description: - - List of telephone numbers assigned to the user. - - If an empty list is passed all assigned telephone numbers will be deleted. - - If None is passed telephone numbers will not be checked or changed. + - List of telephone numbers assigned to the user. + - If an empty list is passed all assigned telephone numbers will be deleted. + - If None is passed telephone numbers will not be checked or changed. type: list elements: str title: description: Title. type: str uid: - description: uid of the user. + description: Uid of the user. required: true aliases: ["name"] type: str uidnumber: description: - - Account Settings UID/Posix User ID number. + - Account Settings UID/Posix User ID number. type: str gidnumber: description: - - Posix Group ID. + - Posix Group ID. type: str homedirectory: description: - - Default home directory of the user. + - Default home directory of the user. type: str version_added: '0.2.0' userauthtype: description: - - The authentication type to use for the user. - - To remove all authentication types from the user, use an empty list V([]). - - The choice V(idp) and V(passkey) has been added in community.general 8.1.0. + - The authentication type to use for the user. + - To remove all authentication types from the user, use an empty list V([]). + - The choice V(idp) and V(passkey) has been added in community.general 8.1.0. choices: ["password", "radius", "otp", "pkinit", "hardened", "idp", "passkey"] type: list elements: str @@ -114,11 +113,11 @@ extends_documentation_fragment: - community.general.attributes requirements: -- base64 -- hashlib -''' + - base64 + - hashlib +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Ensure pinky is present and always reset password community.general.ipa_user: name: pinky @@ -127,12 +126,12 @@ EXAMPLES = r''' givenname: Pinky sn: Acme mail: - - pinky@acme.com + - pinky@acme.com telephonenumber: - - '+555123456' + - '+555123456' sshpubkey: - - ssh-rsa .... - - ssh-dsa .... + - ssh-rsa .... + - ssh-dsa .... uidnumber: '1001' gidnumber: '100' homedirectory: /home/pinky @@ -170,14 +169,14 @@ EXAMPLES = r''' ipa_host: ipa.example.com ipa_user: admin ipa_pass: topsecret -''' +""" -RETURN = r''' +RETURN = r""" user: - description: User as returned by IPA API + description: User as returned by IPA API. returned: always type: dict -''' +""" import base64 import hashlib diff --git a/plugins/modules/ipa_vault.py b/plugins/modules/ipa_vault.py index 88947e470e..23002b7ce0 100644 --- a/plugins/modules/ipa_vault.py +++ b/plugins/modules/ipa_vault.py @@ -7,84 +7,82 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ipa_vault author: Juan Manuel Parrilla (@jparrill) short_description: Manage FreeIPA vaults description: -- Add, modify and delete vaults and secret vaults. -- KRA service should be enabled to use this module. + - Add, modify and delete vaults and secret vaults. + - KRA service should be enabled to use this module. attributes: - check_mode: - support: full - diff_mode: - support: none + check_mode: + support: full + diff_mode: + support: none options: - cn: - description: - - Vault name. - - Can not be changed as it is the unique identifier. - required: true - aliases: ["name"] - type: str + cn: description: - description: - - Description. - type: str - ipavaulttype: - description: - - Vault types are based on security level. - default: "symmetric" - choices: ["asymmetric", "standard", "symmetric"] - aliases: ["vault_type"] - type: str - ipavaultpublickey: - description: - - Public key. - aliases: ["vault_public_key"] - type: str - ipavaultsalt: - description: - - Vault Salt. - aliases: ["vault_salt"] - type: str - username: - description: - - Any user can own one or more user vaults. - - Mutually exclusive with service. - aliases: ["user"] - type: list - elements: str - service: - description: - - Any service can own one or more service vaults. - - Mutually exclusive with user. - type: str - state: - description: - - State to ensure. - default: "present" - choices: ["absent", "present"] - type: str - replace: - description: - - Force replace the existent vault on IPA server. - type: bool - default: false - choices: ["True", "False"] - validate_certs: - description: - - Validate IPA server certificates. - type: bool - default: true + - Vault name. + - Can not be changed as it is the unique identifier. + required: true + aliases: ["name"] + type: str + description: + description: + - Description. + type: str + ipavaulttype: + description: + - Vault types are based on security level. + default: "symmetric" + choices: ["asymmetric", "standard", "symmetric"] + aliases: ["vault_type"] + type: str + ipavaultpublickey: + description: + - Public key. + aliases: ["vault_public_key"] + type: str + ipavaultsalt: + description: + - Vault Salt. + aliases: ["vault_salt"] + type: str + username: + description: + - Any user can own one or more user vaults. + - Mutually exclusive with O(service). + aliases: ["user"] + type: list + elements: str + service: + description: + - Any service can own one or more service vaults. + - Mutually exclusive with O(user). + type: str + state: + description: + - State to ensure. + default: "present" + choices: ["absent", "present"] + type: str + replace: + description: + - Force replace the existent vault on IPA server. + type: bool + default: false + choices: ["True", "False"] + validate_certs: + description: + - Validate IPA server certificates. + type: bool + default: true extends_documentation_fragment: - community.general.ipa.documentation - community.general.attributes +""" -''' - -EXAMPLES = r''' +EXAMPLES = r""" - name: Ensure vault is present community.general.ipa_vault: name: vault01 @@ -128,14 +126,14 @@ EXAMPLES = r''' ipa_host: ipa.example.com ipa_user: admin ipa_pass: topsecret -''' +""" -RETURN = r''' +RETURN = r""" vault: - description: Vault as returned by IPA API + description: Vault as returned by IPA API. returned: always type: dict -''' +""" import traceback diff --git a/plugins/modules/ipbase_info.py b/plugins/modules/ipbase_info.py index c6a5511b73..3c7d3d26c1 100644 --- a/plugins/modules/ipbase_info.py +++ b/plugins/modules/ipbase_info.py @@ -8,13 +8,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: "ipbase_info" version_added: "7.0.0" short_description: "Retrieve IP geolocation and other facts of a host's IP address using the ipbase.com API" description: - - "Retrieve IP geolocation and other facts of a host's IP address using the ipbase.com API" + - Retrieve IP geolocation and other facts of a host's IP address using the ipbase.com API. author: "Dominik Kukacka (@dominikkukacka)" extends_documentation_fragment: - "community.general.attributes" @@ -22,31 +21,31 @@ extends_documentation_fragment: options: ip: description: - - "The IP you want to get the info for. If not specified the API will detect the IP automatically." + - The IP you want to get the info for. If not specified the API will detect the IP automatically. required: false type: str apikey: description: - - "The API key for the request if you need more requests." + - The API key for the request if you need more requests. required: false type: str hostname: description: - - "If the O(hostname) parameter is set to V(true), the API response will contain the hostname of the IP." + - If the O(hostname) parameter is set to V(true), the API response will contain the hostname of the IP. required: false type: bool default: false language: description: - - "An ISO Alpha 2 Language Code for localizing the IP data" + - An ISO Alpha 2 Language Code for localizing the IP data. required: false type: str default: "en" notes: - - "Check U(https://ipbase.com/) for more information." -''' + - Check U(https://ipbase.com/) for more information. +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: "Get IP geolocation information of the primary outgoing IP" community.general.ipbase_info: register: my_ip_info @@ -64,12 +63,12 @@ EXAMPLES = ''' hostname: true language: "de" register: my_ip_info +""" -''' - -RETURN = ''' +RETURN = r""" data: - description: "JSON parsed response from ipbase.com. Please refer to U(https://ipbase.com/docs/info) for the detailed structure of the response." + description: "JSON parsed response from ipbase.com. Please refer to U(https://ipbase.com/docs/info) for the detailed structure + of the response." returned: success type: dict sample: { @@ -213,7 +212,7 @@ data: ] } } -''' +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/ipify_facts.py b/plugins/modules/ipify_facts.py index ff17d7e543..7767c8d0ff 100644 --- a/plugins/modules/ipify_facts.py +++ b/plugins/modules/ipify_facts.py @@ -9,14 +9,13 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ipify_facts short_description: Retrieve the public IP of your internet gateway description: - If behind NAT and need to know the public IP of your internet gateway. author: -- René Moser (@resmo) + - René Moser (@resmo) extends_documentation_fragment: - community.general.attributes - community.general.attributes.facts @@ -40,9 +39,9 @@ options: default: true notes: - Visit https://www.ipify.org to get more information. -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" # Gather IP facts from ipify.org - name: Get my public IP community.general.ipify_facts: @@ -52,16 +51,15 @@ EXAMPLES = r''' community.general.ipify_facts: api_url: http://api.example.com/ipify timeout: 20 -''' +""" -RETURN = r''' ---- +RETURN = r""" ipify_public_ip: description: Public IP of the internet gateway. returned: success type: str sample: 1.2.3.4 -''' +""" import json diff --git a/plugins/modules/ipinfoio_facts.py b/plugins/modules/ipinfoio_facts.py index f29b3cbf4c..45c86e0491 100644 --- a/plugins/modules/ipinfoio_facts.py +++ b/plugins/modules/ipinfoio_facts.py @@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: ipinfoio_facts short_description: Retrieve IP geolocation facts of a host's IP address description: - - "Gather IP geolocation facts of a host's IP address using ipinfo.io API" + - Gather IP geolocation facts of a host's IP address using ipinfo.io API. author: "Aleksei Kostiuk (@akostyuk)" extends_documentation_fragment: - community.general.attributes @@ -23,65 +22,65 @@ extends_documentation_fragment: options: timeout: description: - - HTTP connection timeout in seconds + - HTTP connection timeout in seconds. required: false default: 10 type: int http_agent: description: - - Set http user agent + - Set http user agent. required: false default: "ansible-ipinfoio-module/0.0.1" type: str notes: - - "Check http://ipinfo.io/ for more information" -''' + - Check http://ipinfo.io/ for more information. +""" -EXAMPLES = ''' +EXAMPLES = r""" # Retrieve geolocation data of a host's IP address - name: Get IP geolocation data community.general.ipinfoio_facts: -''' +""" -RETURN = ''' +RETURN = r""" ansible_facts: - description: "Dictionary of ip geolocation facts for a host's IP address" + description: "Dictionary of ip geolocation facts for a host's IP address." returned: changed type: complex contains: ip: - description: "Public IP address of a host" + description: "Public IP address of a host." type: str sample: "8.8.8.8" hostname: - description: Domain name + description: Domain name. type: str sample: "google-public-dns-a.google.com" country: - description: ISO 3166-1 alpha-2 country code + description: ISO 3166-1 alpha-2 country code. type: str sample: "US" region: - description: State or province name + description: State or province name. type: str sample: "California" city: - description: City name + description: City name. type: str sample: "Mountain View" loc: - description: Latitude and Longitude of the location + description: Latitude and Longitude of the location. type: str sample: "37.3860,-122.0838" org: - description: "organization's name" + description: "Organization's name." type: str sample: "AS3356 Level 3 Communications, Inc." postal: - description: Postal code + description: Postal code. type: str sample: "94035" -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.urls import fetch_url diff --git a/plugins/modules/ipmi_boot.py b/plugins/modules/ipmi_boot.py index 9f0016560e..e4fb5544d6 100644 --- a/plugins/modules/ipmi_boot.py +++ b/plugins/modules/ipmi_boot.py @@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: ipmi_boot short_description: Management of order of boot devices description: - - Use this module to manage order of boot devices + - Use this module to manage order of boot devices. extends_documentation_fragment: - community.general.attributes attributes: @@ -52,14 +51,14 @@ options: bootdev: description: - Set boot device to use on next reboot - - "The choices for the device are: - - network -- Request network boot - - floppy -- Boot from floppy - - hd -- Boot from hard drive - - safe -- Boot from hard drive, requesting 'safe mode' - - optical -- boot from CD/DVD/BD drive - - setup -- Boot into setup utility - - default -- remove any IPMI directed boot device request" + - "The choices for the device are:" + - V(network) -- Request network boot + - V(floppy) -- Boot from floppy + - V(hd) -- Boot from hard drive + - "V(safe) -- Boot from hard drive, requesting 'safe mode'" + - V(optical) -- boot from CD/DVD/BD drive + - V(setup) -- Boot into setup utility + - V(default) -- remove any IPMI directed boot device request required: true choices: - network @@ -73,49 +72,46 @@ options: state: description: - Whether to ensure that boot devices is desired. - - "The choices for the state are: - - present -- Request system turn on - - absent -- Request system turn on" + - 'The choices for the state are: - present -- Request system turn on - absent -- Request system turn on.' default: present - choices: [ present, absent ] + choices: [present, absent] type: str persistent: description: - - If set, ask that system firmware uses this device beyond next boot. - Be aware many systems do not honor this. + - If set, ask that system firmware uses this device beyond next boot. Be aware many systems do not honor this. type: bool default: false uefiboot: description: - - If set, request UEFI boot explicitly. - Strictly speaking, the spec suggests that if not set, the system should BIOS boot and offers no "don't care" option. - In practice, this flag not being set does not preclude UEFI boot on any system I've encountered. + - If set, request UEFI boot explicitly. Strictly speaking, the spec suggests that if not set, the system should BIOS + boot and offers no "do not care" option. In practice, this flag not being set does not preclude UEFI boot on any system + I have encountered. type: bool default: false requirements: - pyghmi author: "Bulat Gaifullin (@bgaifullin) " -''' +""" -RETURN = ''' +RETURN = r""" bootdev: - description: The boot device name which will be used beyond next boot. - returned: success - type: str - sample: default + description: The boot device name which will be used beyond next boot. + returned: success + type: str + sample: default persistent: - description: If True, system firmware will use this device beyond next boot. - returned: success - type: bool - sample: false + description: If True, system firmware will use this device beyond next boot. + returned: success + type: bool + sample: false uefimode: - description: If True, system firmware will use UEFI boot explicitly beyond next boot. - returned: success - type: bool - sample: false -''' + description: If True, system firmware will use UEFI boot explicitly beyond next boot. + returned: success + type: bool + sample: false +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Ensure bootdevice is HD community.general.ipmi_boot: name: test.testdomain.com @@ -131,7 +127,7 @@ EXAMPLES = ''' key: 1234567890AABBCCDEFF000000EEEE12 bootdev: network state: absent -''' +""" import traceback import binascii diff --git a/plugins/modules/ipmi_power.py b/plugins/modules/ipmi_power.py index 587cee06f3..3cb6d501ea 100644 --- a/plugins/modules/ipmi_power.py +++ b/plugins/modules/ipmi_power.py @@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: ipmi_power short_description: Power management for machine description: - - Use this module for power management + - Use this module for power management. extends_documentation_fragment: - community.general.attributes attributes: @@ -52,12 +51,12 @@ options: state: description: - Whether to ensure that the machine in desired state. - - "The choices for state are: - - on -- Request system turn on - - off -- Request system turn off without waiting for OS to shutdown - - shutdown -- Have system request OS proper shutdown - - reset -- Request system reset without waiting for OS - - boot -- If system is off, then 'on', else 'reset'" + - "The choices for state are:" + - V(on) -- Request system turn on + - V(off) -- Request system turn off without waiting for OS to shutdown + - V(shutdown) -- Have system request OS proper shutdown + - V(reset) -- Request system reset without waiting for OS + - "V(boot) -- If system is off, then V(on), else V(reset)" - Either this option or O(machine) is required. choices: ['on', 'off', shutdown, reset, boot] type: str @@ -68,8 +67,7 @@ options: type: int machine: description: - - Provide a list of the remote target address for the bridge IPMI request, - and the power status. + - Provide a list of the remote target address for the bridge IPMI request, and the power status. - Either this option or O(state) is required. required: false type: list @@ -92,40 +90,31 @@ options: requirements: - pyghmi author: "Bulat Gaifullin (@bgaifullin) " -''' +""" -RETURN = ''' +RETURN = r""" powerstate: - description: The current power state of the machine. - returned: success and O(machine) is not provided - type: str - sample: 'on' + description: The current power state of the machine. + returned: success and O(machine) is not provided + type: str + sample: 'on' status: - description: The current power state of the machine when the machine option is set. - returned: success and O(machine) is provided - type: list - elements: dict - version_added: 4.3.0 - contains: - powerstate: - description: The current power state of the machine specified by RV(status[].targetAddress). - type: str - targetAddress: - description: The remote target address. - type: int - sample: [ - { - "powerstate": "on", - "targetAddress": 48, - }, - { - "powerstate": "on", - "targetAddress": 50, - }, - ] -''' + description: The current power state of the machine when the machine option is set. + returned: success and O(machine) is provided + type: list + elements: dict + version_added: 4.3.0 + contains: + powerstate: + description: The current power state of the machine specified by RV(status[].targetAddress). + type: str + targetAddress: + description: The remote target address. + type: int + sample: [{"powerstate": "on", "targetAddress": 48}, {"powerstate": "on", "targetAddress": 50}] +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Ensure machine is powered on community.general.ipmi_power: name: test.testdomain.com @@ -153,7 +142,7 @@ EXAMPLES = ''' state: 'on' - targetAddress: 50 state: 'off' -''' +""" import traceback import binascii diff --git a/plugins/modules/iptables_state.py b/plugins/modules/iptables_state.py index c97b5694c9..6f3fa19042 100644 --- a/plugins/modules/iptables_state.py +++ b/plugins/modules/iptables_state.py @@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: iptables_state short_description: Save iptables state into a file or restore it from a file version_added: '1.1.0' @@ -19,26 +18,17 @@ extends_documentation_fragment: - community.general.attributes - community.general.attributes.flow description: - - C(iptables) is used to set up, maintain, and inspect the tables of IP - packet filter rules in the Linux kernel. - - This module handles the saving and/or loading of rules. This is the same - as the behaviour of the C(iptables-save) and C(iptables-restore) (or - C(ip6tables-save) and C(ip6tables-restore) for IPv6) commands which this - module uses internally. - - Modifying the state of the firewall remotely may lead to loose access to - the host in case of mistake in new ruleset. This module embeds a rollback - feature to avoid this, by telling the host to restore previous rules if a - cookie is still there after a given delay, and all this time telling the - controller to try to remove this cookie on the host through a new - connection. + - C(iptables) is used to set up, maintain, and inspect the tables of IP packet filter rules in the Linux kernel. + - This module handles the saving and/or loading of rules. This is the same as the behaviour of the C(iptables-save) and + C(iptables-restore) (or C(ip6tables-save) and C(ip6tables-restore) for IPv6) commands which this module uses internally. + - Modifying the state of the firewall remotely may lead to loose access to the host in case of mistake in new ruleset. This + module embeds a rollback feature to avoid this, by telling the host to restore previous rules if a cookie is still there + after a given delay, and all this time telling the controller to try to remove this cookie on the host through a new connection. notes: - - The rollback feature is not a module option and depends on task's - attributes. To enable it, the module must be played asynchronously, i.e. - by setting task attributes C(poll) to V(0), and C(async) to a value less - or equal to C(ANSIBLE_TIMEOUT). If C(async) is greater, the rollback will - still happen if it shall happen, but you will experience a connection - timeout instead of more relevant info returned by the module after its - failure. + - The rollback feature is not a module option and depends on task's attributes. To enable it, the module must be played + asynchronously, in other words by setting task attributes C(poll) to V(0), and C(async) to a value less or equal to C(ANSIBLE_TIMEOUT). + If C(async) is greater, the rollback will still happen if it shall happen, but you will experience a connection timeout + instead of more relevant info returned by the module after its failure. attributes: check_mode: support: full @@ -59,22 +49,18 @@ options: description: - Which version of the IP protocol this module should apply to. type: str - choices: [ ipv4, ipv6 ] + choices: [ipv4, ipv6] default: ipv4 modprobe: description: - - Specify the path to the C(modprobe) program internally used by iptables - related commands to load kernel modules. - - By default, V(/proc/sys/kernel/modprobe) is inspected to determine the - executable's path. + - Specify the path to the C(modprobe) program internally used by iptables related commands to load kernel modules. + - By default, V(/proc/sys/kernel/modprobe) is inspected to determine the executable's path. type: path noflush: description: - For O(state=restored), ignored otherwise. - - If V(false), restoring iptables rules from a file flushes (deletes) - all previous contents of the respective table(s). If V(true), the - previous rules are left untouched (but policies are updated anyway, - for all built-in chains). + - If V(false), restoring iptables rules from a file flushes (deletes) all previous contents of the respective table(s). + If V(true), the previous rules are left untouched (but policies are updated anyway, for all built-in chains). type: bool default: false path: @@ -85,29 +71,26 @@ options: required: true state: description: - - Whether the firewall state should be saved (into a file) or restored - (from a file). + - Whether the firewall state should be saved (into a file) or restored (from a file). type: str - choices: [ saved, restored ] + choices: [saved, restored] required: true table: description: - - When O(state=restored), restore only the named table even if the input - file contains other tables. Fail if the named table is not declared in - the file. - - When O(state=saved), restrict output to the specified table. If not - specified, output includes all active tables. + - When O(state=restored), restore only the named table even if the input file contains other tables. Fail if the named + table is not declared in the file. + - When O(state=saved), restrict output to the specified table. If not specified, output includes all active tables. type: str - choices: [ filter, nat, mangle, raw, security ] + choices: [filter, nat, mangle, raw, security] wait: description: - - Wait N seconds for the xtables lock to prevent instant failure in case - multiple instances of the program are running concurrently. + - Wait N seconds for the xtables lock to prevent instant failure in case multiple instances of the program are running + concurrently. type: int requirements: [iptables, ip6tables] -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" # This will apply to all loaded/active IPv4 tables. - name: Save current state of the firewall in system file community.general.iptables_state: @@ -151,9 +134,9 @@ EXAMPLES = r''' - name: show current state of the firewall ansible.builtin.debug: var: iptables_state.initial_state -''' +""" -RETURN = r''' +RETURN = r""" applied: description: Whether or not the wanted state has been successfully restored. type: bool @@ -235,7 +218,7 @@ tables: ] } returned: always -''' +""" import re diff --git a/plugins/modules/ipwcli_dns.py b/plugins/modules/ipwcli_dns.py index 3ffad79fb6..118f59e8d9 100644 --- a/plugins/modules/ipwcli_dns.py +++ b/plugins/modules/ipwcli_dns.py @@ -8,127 +8,124 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: ipwcli_dns -short_description: Manage DNS Records for Ericsson IPWorks via ipwcli +short_description: Manage DNS Records for Ericsson IPWorks using C(ipwcli) version_added: '0.2.0' description: - - "Manage DNS records for the Ericsson IPWorks DNS server. The module will use the ipwcli to deploy the DNS records." - + - Manage DNS records for the Ericsson IPWorks DNS server. The module will use the C(ipwcli) to deploy the DNS records. requirements: - - ipwcli (installed on Ericsson IPWorks) + - ipwcli (installed on Ericsson IPWorks) notes: - - To make the DNS record changes effective, you need to run C(update dnsserver) on the ipwcli. - + - To make the DNS record changes effective, you need to run C(update dnsserver) on the ipwcli. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: none + check_mode: + support: full + diff_mode: + support: none options: - dnsname: - description: - - Name of the record. - required: true - type: str - type: - description: - - Type of the record. - required: true - type: str - choices: [ NAPTR, SRV, A, AAAA ] - container: - description: - - Sets the container zone for the record. - required: true - type: str - address: - description: - - The IP address for the A or AAAA record. - - Required for O(type=A) or O(type=AAAA). - type: str - ttl: - description: - - Sets the TTL of the record. - type: int - default: 3600 - state: - description: - - Whether the record should exist or not. - type: str - choices: [ absent, present ] - default: present - priority: - description: - - Sets the priority of the SRV record. - type: int - default: 10 - weight: - description: - - Sets the weight of the SRV record. - type: int - default: 10 - port: - description: - - Sets the port of the SRV record. - - Required for O(type=SRV). - type: int - target: - description: - - Sets the target of the SRV record. - - Required for O(type=SRV). - type: str - order: - description: - - Sets the order of the NAPTR record. - - Required for O(type=NAPTR). - type: int - preference: - description: - - Sets the preference of the NAPTR record. - - Required for O(type=NAPTR). - type: int - flags: - description: - - Sets one of the possible flags of NAPTR record. - - Required for O(type=NAPTR). - type: str - choices: ['S', 'A', 'U', 'P'] - service: - description: - - Sets the service of the NAPTR record. - - Required for O(type=NAPTR). - type: str - replacement: - description: - - Sets the replacement of the NAPTR record. - - Required for O(type=NAPTR). - type: str - username: - description: - - Username to login on ipwcli. - type: str - required: true - password: - description: - - Password to login on ipwcli. - type: str - required: true + dnsname: + description: + - Name of the record. + required: true + type: str + type: + description: + - Type of the record. + required: true + type: str + choices: [NAPTR, SRV, A, AAAA] + container: + description: + - Sets the container zone for the record. + required: true + type: str + address: + description: + - The IP address for the A or AAAA record. + - Required for O(type=A) or O(type=AAAA). + type: str + ttl: + description: + - Sets the TTL of the record. + type: int + default: 3600 + state: + description: + - Whether the record should exist or not. + type: str + choices: [absent, present] + default: present + priority: + description: + - Sets the priority of the SRV record. + type: int + default: 10 + weight: + description: + - Sets the weight of the SRV record. + type: int + default: 10 + port: + description: + - Sets the port of the SRV record. + - Required for O(type=SRV). + type: int + target: + description: + - Sets the target of the SRV record. + - Required for O(type=SRV). + type: str + order: + description: + - Sets the order of the NAPTR record. + - Required for O(type=NAPTR). + type: int + preference: + description: + - Sets the preference of the NAPTR record. + - Required for O(type=NAPTR). + type: int + flags: + description: + - Sets one of the possible flags of NAPTR record. + - Required for O(type=NAPTR). + type: str + choices: ['S', 'A', 'U', 'P'] + service: + description: + - Sets the service of the NAPTR record. + - Required for O(type=NAPTR). + type: str + replacement: + description: + - Sets the replacement of the NAPTR record. + - Required for O(type=NAPTR). + type: str + username: + description: + - Username to login on ipwcli. + type: str + required: true + password: + description: + - Password to login on ipwcli. + type: str + required: true author: - - Christian Wollinger (@cwollinger) -''' + - Christian Wollinger (@cwollinger) +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create A record community.general.ipwcli_dns: dnsname: example.com @@ -157,14 +154,14 @@ EXAMPLES = ''' service: 'SIP+D2T' replacement: '_sip._tcp.test.example.com.' flags: S -''' +""" -RETURN = ''' +RETURN = r""" record: - description: The created record from the input params - type: str - returned: always -''' + description: The created record from the input params. + type: str + returned: always +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/irc.py b/plugins/modules/irc.py index 748479e87b..cbeb3fafa0 100644 --- a/plugins/modules/irc.py +++ b/plugins/modules/irc.py @@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: irc short_description: Send a message to an IRC channel or a nick description: @@ -26,12 +25,12 @@ options: server: type: str description: - - IRC server name/address + - IRC server name/address. default: localhost port: type: int description: - - IRC server port number + - IRC server port number. default: 6667 nick: type: str @@ -46,45 +45,44 @@ options: topic: type: str description: - - Set the channel topic + - Set the channel topic. color: type: str description: - Text color for the message. default: "none" - choices: [ "none", "white", "black", "blue", "green", "red", "brown", "purple", "orange", "yellow", "light_green", "teal", "light_cyan", - "light_blue", "pink", "gray", "light_gray"] + choices: ["none", "white", "black", "blue", "green", "red", "brown", "purple", "orange", "yellow", "light_green", "teal", + "light_cyan", "light_blue", "pink", "gray", "light_gray"] aliases: [colour] channel: type: str description: - - Channel name. One of nick_to or channel needs to be set. When both are set, the message will be sent to both of them. + - Channel name. One of nick_to or channel needs to be set. When both are set, the message will be sent to both of them. nick_to: type: list elements: str description: - - A list of nicknames to send the message to. One of nick_to or channel needs to be set. When both are defined, the message will be sent to both of them. + - A list of nicknames to send the message to. One of nick_to or channel needs to be set. When both are defined, the + message will be sent to both of them. key: type: str description: - - Channel key + - Channel key. passwd: type: str description: - - Server password + - Server password. timeout: type: int description: - - Timeout to use while waiting for successful registration and join - messages, this is to prevent an endless loop + - Timeout to use while waiting for successful registration and join messages, this is to prevent an endless loop. default: 30 use_tls: description: - - Designates whether TLS/SSL should be used when connecting to the IRC server - - O(use_tls) is available since community.general 8.1.0, before the option - was exlusively called O(use_ssl). The latter is now an alias of O(use_tls). - - B(Note:) for security reasons, you should always set O(use_tls=true) and - O(validate_certs=true) whenever possible. + - Designates whether TLS/SSL should be used when connecting to the IRC server. + - O(use_tls) is available since community.general 8.1.0, before the option was exlusively called O(use_ssl). The latter + is now an alias of O(use_tls). + - B(Note:) for security reasons, you should always set O(use_tls=true) and O(validate_certs=true) whenever possible. - The default of this option changed to V(true) in community.general 10.0.0. type: bool default: true @@ -92,36 +90,35 @@ options: - use_ssl part: description: - - Designates whether user should part from channel after sending message or not. - Useful for when using a faux bot and not wanting join/parts between messages. + - Designates whether user should part from channel after sending message or not. Useful for when using a mock bot and + not wanting join/parts between messages. type: bool default: true style: type: str description: - - Text style for the message. Note italic does not work on some clients - choices: [ "bold", "underline", "reverse", "italic", "none" ] + - Text style for the message. Note italic does not work on some clients. + choices: ["bold", "underline", "reverse", "italic", "none"] default: none validate_certs: description: - If set to V(false), the SSL certificates will not be validated. - - This should always be set to V(true). Using V(false) is unsafe and should only be done - if the network between between Ansible and the IRC server is known to be safe. - - B(Note:) for security reasons, you should always set O(use_tls=true) and - O(validate_certs=true) whenever possible. + - This should always be set to V(true). Using V(false) is unsafe and should only be done if the network between between + Ansible and the IRC server is known to be safe. + - B(Note:) for security reasons, you should always set O(use_tls=true) and O(validate_certs=true) whenever possible. - The default of this option changed to V(true) in community.general 10.0.0. type: bool default: true version_added: 8.1.0 # informational: requirements for nodes -requirements: [ socket ] +requirements: [socket] author: - - "Jan-Piet Mens (@jpmens)" - - "Matt Martz (@sivel)" -''' + - "Jan-Piet Mens (@jpmens)" + - "Matt Martz (@sivel)" +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Send a message to an IRC channel from nick ansible community.general.irc: server: irc.example.net @@ -156,7 +153,7 @@ EXAMPLES = ''' msg: 'All finished at {{ ansible_date_time.iso8601 }}' color: red nick: ansibleIRC -''' +""" # =========================================== # IRC module support methods. diff --git a/plugins/modules/iso_create.py b/plugins/modules/iso_create.py index c39c710d53..008cb271bb 100644 --- a/plugins/modules/iso_create.py +++ b/plugins/modules/iso_create.py @@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: iso_create short_description: Generate ISO file with specified files or folders description: @@ -31,60 +30,60 @@ attributes: support: none options: - src_files: - description: - - This is a list of absolute paths of source files or folders which will be contained in the new generated ISO file. - - Will fail if specified file or folder in O(src_files) does not exist on local machine. - - 'Note: With all ISO9660 levels from 1 to 3, all file names are restricted to uppercase letters, numbers and - underscores (_). File names are limited to 31 characters, directory nesting is limited to 8 levels, and path - names are limited to 255 characters.' - type: list - required: true - elements: path - dest_iso: - description: - - The absolute path with file name of the new generated ISO file on local machine. - - Will create intermediate folders when they does not exist. - type: path - required: true - interchange_level: - description: - - The ISO9660 interchange level to use, it dictates the rules on the names of files. - - Levels and valid values V(1), V(2), V(3), V(4) are supported. - - The default value is level V(1), which is the most conservative, level V(3) is recommended. - - ISO9660 file names at interchange level V(1) cannot have more than 8 characters or 3 characters in the extension. - type: int - default: 1 - choices: [1, 2, 3, 4] - vol_ident: - description: - - The volume identification string to use on the new generated ISO image. - type: str - rock_ridge: - description: - - Whether to make this ISO have the Rock Ridge extensions or not. - - Valid values are V(1.09), V(1.10) or V(1.12), means adding the specified Rock Ridge version to the ISO. - - If unsure, set V(1.09) to ensure maximum compatibility. - - If not specified, then not add Rock Ridge extension to the ISO. - type: str - choices: ['1.09', '1.10', '1.12'] - joliet: - description: - - Support levels and valid values are V(1), V(2), or V(3). - - Level V(3) is by far the most common. - - If not specified, then no Joliet support is added. - type: int - choices: [1, 2, 3] - udf: - description: - - Whether to add UDF support to this ISO. - - If set to V(true), then version 2.60 of the UDF spec is used. - - If not specified or set to V(false), then no UDF support is added. - type: bool - default: false -''' + src_files: + description: + - This is a list of absolute paths of source files or folders which will be contained in the new generated ISO file. + - Will fail if specified file or folder in O(src_files) does not exist on local machine. + - 'Note: With all ISO9660 levels from 1 to 3, all file names are restricted to uppercase letters, numbers and underscores + (_). File names are limited to 31 characters, directory nesting is limited to 8 levels, and path names are limited + to 255 characters.' + type: list + required: true + elements: path + dest_iso: + description: + - The absolute path with file name of the new generated ISO file on local machine. + - Will create intermediate folders when they does not exist. + type: path + required: true + interchange_level: + description: + - The ISO9660 interchange level to use, it dictates the rules on the names of files. + - Levels and valid values V(1), V(2), V(3), V(4) are supported. + - The default value is level V(1), which is the most conservative, level V(3) is recommended. + - ISO9660 file names at interchange level V(1) cannot have more than 8 characters or 3 characters in the extension. + type: int + default: 1 + choices: [1, 2, 3, 4] + vol_ident: + description: + - The volume identification string to use on the new generated ISO image. + type: str + rock_ridge: + description: + - Whether to make this ISO have the Rock Ridge extensions or not. + - Valid values are V(1.09), V(1.10) or V(1.12), means adding the specified Rock Ridge version to the ISO. + - If unsure, set V(1.09) to ensure maximum compatibility. + - If not specified, then not add Rock Ridge extension to the ISO. + type: str + choices: ['1.09', '1.10', '1.12'] + joliet: + description: + - Support levels and valid values are V(1), V(2), or V(3). + - Level V(3) is by far the most common. + - If not specified, then no Joliet support is added. + type: int + choices: [1, 2, 3] + udf: + description: + - Whether to add UDF support to this ISO. + - If set to V(true), then version 2.60 of the UDF spec is used. + - If not specified or set to V(false), then no UDF support is added. + type: bool + default: false +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Create an ISO file community.general.iso_create: src_files: @@ -109,46 +108,46 @@ EXAMPLES = r''' interchange_level: 3 joliet: 3 vol_ident: WIN_AUTOINSTALL -''' +""" -RETURN = r''' +RETURN = r""" source_file: - description: Configured source files or directories list. - returned: on success - type: list - elements: path - sample: ["/path/to/file.txt", "/path/to/folder"] + description: Configured source files or directories list. + returned: on success + type: list + elements: path + sample: ["/path/to/file.txt", "/path/to/folder"] created_iso: - description: Created iso file path. - returned: on success - type: str - sample: "/path/to/test.iso" + description: Created iso file path. + returned: on success + type: str + sample: "/path/to/test.iso" interchange_level: - description: Configured interchange level. - returned: on success - type: int - sample: 3 + description: Configured interchange level. + returned: on success + type: int + sample: 3 vol_ident: - description: Configured volume identification string. - returned: on success - type: str - sample: "OEMDRV" + description: Configured volume identification string. + returned: on success + type: str + sample: "OEMDRV" joliet: - description: Configured Joliet support level. - returned: on success - type: int - sample: 3 + description: Configured Joliet support level. + returned: on success + type: int + sample: 3 rock_ridge: - description: Configured Rock Ridge version. - returned: on success - type: str - sample: "1.09" + description: Configured Rock Ridge version. + returned: on success + type: str + sample: "1.09" udf: - description: Configured UDF support. - returned: on success - type: bool - sample: false -''' + description: Configured UDF support. + returned: on success + type: bool + sample: false +""" import os import traceback diff --git a/plugins/modules/iso_customize.py b/plugins/modules/iso_customize.py index 543faaa5ef..feac8417b8 100644 --- a/plugins/modules/iso_customize.py +++ b/plugins/modules/iso_customize.py @@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: iso_customize short_description: Add/remove/change files in ISO file description: @@ -34,25 +33,25 @@ attributes: options: src_iso: description: - - This is the path of source ISO file. + - This is the path of source ISO file. type: path required: true dest_iso: description: - - The path of the customized ISO file. + - The path of the customized ISO file. type: path required: true delete_files: description: - - Absolute paths for files inside the ISO file that should be removed. + - Absolute paths for files inside the ISO file that should be removed. type: list required: false elements: str default: [] add_files: description: - - Allows to add and replace files in the ISO file. - - Will create intermediate folders inside the ISO file when they do not exist. + - Allows to add and replace files in the ISO file. + - Will create intermediate folders inside the ISO file when they do not exist. type: list required: false elements: dict @@ -60,23 +59,22 @@ options: suboptions: src_file: description: - - The path with file name on the machine the module is executed on. + - The path with file name on the machine the module is executed on. type: path required: true dest_file: description: - - The absolute path of the file inside the ISO file. + - The absolute path of the file inside the ISO file. type: str required: true notes: -- The C(pycdlib) library states it supports Python 2.7 and 3.4+. -- > - The function C(add_file) in pycdlib will overwrite the existing file in ISO with type ISO9660 / Rock Ridge 1.12 / Joliet / UDF. - But it will not overwrite the existing file in ISO with Rock Ridge 1.09 / 1.10. - So we take workaround "delete the existing file and then add file for ISO with Rock Ridge". -''' + - The C(pycdlib) library states it supports Python 2.7 and 3.4+. + - The function C(add_file) in pycdlib will overwrite the existing file in ISO with type ISO9660 / Rock Ridge 1.12 / Joliet + / UDF. But it will not overwrite the existing file in ISO with Rock Ridge 1.09 / 1.10. So we take workaround "delete the + existing file and then add file for ISO with Rock Ridge". +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: "Customize ISO file" community.general.iso_customize: src_iso: "/path/to/ubuntu-22.04-desktop-amd64.iso" @@ -89,9 +87,9 @@ EXAMPLES = r''' - src_file: "/path/to/ubuntu.seed" dest_file: "/preseed/ubuntu.seed" register: customize_iso_result -''' +""" -RETURN = r''' +RETURN = r""" src_iso: description: Path of source ISO file. returned: on success @@ -102,7 +100,7 @@ dest_iso: returned: on success type: str sample: "/path/to/customized.iso" -''' +""" import os diff --git a/plugins/modules/iso_extract.py b/plugins/modules/iso_extract.py index 9ef046ede4..8cda967b64 100644 --- a/plugins/modules/iso_extract.py +++ b/plugins/modules/iso_extract.py @@ -11,8 +11,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" author: - Jeroen Hoekx (@jhoekx) - Matt Robinson (@ribbons) @@ -21,12 +20,10 @@ module: iso_extract short_description: Extract files from an ISO image description: - This module has two possible ways of operation. - - If 7zip is installed on the system, this module extracts files from an ISO - into a temporary directory and copies files to a given destination, - if needed. - - If the user has mount-capabilities (CAP_SYS_ADMIN on Linux) this module - mounts the ISO image to a temporary location, and copies files to a given - destination, if needed. + - If 7zip is installed on the system, this module extracts files from an ISO into a temporary directory and copies files + to a given destination, if needed. + - If the user has mount-capabilities (CAP_SYS_ADMIN on Linux) this module mounts the ISO image to a temporary location, + and copies files to a given destination, if needed. requirements: - Either 7z (from C(7zip) or C(p7zip) package) - Or mount capabilities (root-access, or CAP_SYS_ADMIN capability on Linux) @@ -40,60 +37,59 @@ attributes: options: image: description: - - The ISO image to extract files from. + - The ISO image to extract files from. type: path required: true - aliases: [ path, src ] + aliases: [path, src] dest: description: - - The destination directory to extract files to. + - The destination directory to extract files to. type: path required: true files: description: - - A list of files to extract from the image. - - Extracting directories does not work. + - A list of files to extract from the image. + - Extracting directories does not work. type: list elements: str required: true force: description: - - If V(true), which will replace the remote file when contents are different than the source. - - If V(false), the file will only be extracted and copied if the destination does not already exist. + - If V(true), which will replace the remote file when contents are different than the source. + - If V(false), the file will only be extracted and copied if the destination does not already exist. type: bool default: true executable: description: - - The path to the C(7z) executable to use for extracting files from the ISO. - - If not provided, it will assume the value V(7z). + - The path to the C(7z) executable to use for extracting files from the ISO. + - If not provided, it will assume the value V(7z). type: path password: description: - - Password used to decrypt files from the ISO. - - Will only be used if 7z is used. - - The password is used as a command line argument to 7z. This is a B(potential security risk) that - allows passwords to be revealed if someone else can list running processes on the same machine - in the right moment. + - Password used to decrypt files from the ISO. + - Will only be used if 7z is used. + - The password is used as a command line argument to 7z. This is a B(potential security risk) that allows passwords + to be revealed if someone else can list running processes on the same machine in the right moment. type: str version_added: 10.1.0 notes: -- Only the file checksum (content) is taken into account when extracting files - from the ISO image. If O(force=false), only checks the presence of the file. -''' + - Only the file checksum (content) is taken into account when extracting files from the ISO image. If O(force=false), only + checks the presence of the file. +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Extract kernel and ramdisk from a LiveCD community.general.iso_extract: image: /tmp/rear-test.iso dest: /tmp/virt-rear/ files: - - isolinux/kernel - - isolinux/initrd.cgz -''' + - isolinux/kernel + - isolinux/initrd.cgz +""" -RETURN = r''' +RETURN = r""" # -''' +""" import os.path import shutil diff --git a/plugins/modules/jabber.py b/plugins/modules/jabber.py index 650b29957d..01a34ff9f5 100644 --- a/plugins/modules/jabber.py +++ b/plugins/modules/jabber.py @@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: jabber short_description: Send a message to jabber user or chat room description: - - Send a message to jabber + - Send a message to jabber. extends_documentation_fragment: - community.general.attributes attributes: @@ -26,17 +25,17 @@ options: user: type: str description: - - User as which to connect + - User as which to connect. required: true password: type: str description: - - password for user to connect + - Password for user to connect. required: true to: type: str description: - - user ID or name of the room, when using room use a slash to indicate your nick. + - User ID or name of the room, when using room use a slash to indicate your nick. required: true msg: type: str @@ -46,24 +45,22 @@ options: host: type: str description: - - host to connect, overrides user info + - Host to connect, overrides user info. port: type: int description: - - port to connect to, overrides default + - Port to connect to, overrides default. default: 5222 encoding: type: str description: - - message encoding - -# informational: requirements for nodes + - Message encoding. requirements: - - python xmpp (xmpppy) + - python xmpp (xmpppy) author: "Brian Coca (@bcoca)" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Send a message to a user community.general.jabber: user: mybot@example.net @@ -86,7 +83,7 @@ EXAMPLES = ''' password: secret to: mychaps@example.net msg: Ansible task finished -''' +""" import time import traceback diff --git a/plugins/modules/java_cert.py b/plugins/modules/java_cert.py index e2d04b71e2..a205ecc789 100644 --- a/plugins/modules/java_cert.py +++ b/plugins/modules/java_cert.py @@ -8,14 +8,13 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: java_cert short_description: Uses keytool to import/remove certificate to/from java keystore (cacerts) description: - - This is a wrapper module around keytool, which can be used to import certificates - and optionally private keys to a given java keystore, or remove them from it. + - This is a wrapper module around keytool, which can be used to import certificates and optionally private keys to a given + java keystore, or remove them from it. extends_documentation_fragment: - community.general.attributes - ansible.builtin.files @@ -61,9 +60,8 @@ options: pkcs12_path: description: - Local path to load PKCS12 keystore from. - - Unlike O(cert_url), O(cert_path) and O(cert_content), the PKCS12 keystore embeds the private key matching - the certificate, and is used to import both the certificate and its private key into the - java keystore. + - Unlike O(cert_url), O(cert_path) and O(cert_content), the PKCS12 keystore embeds the private key matching the certificate, + and is used to import both the certificate and its private key into the java keystore. - Exactly one of O(cert_url), O(cert_path), O(cert_content), or O(pkcs12_path) is required to load certificate. type: path pkcs12_password: @@ -100,10 +98,10 @@ options: state: description: - Defines action which can be either certificate import or removal. - - When state is present, the certificate will always idempotently be inserted - into the keystore, even if there already exists a cert alias that is different. + - When state is present, the certificate will always idempotently be inserted into the keystore, even if there already + exists a cert alias that is different. type: str - choices: [ absent, present ] + choices: [absent, present] default: present mode: version_added: 8.5.0 @@ -125,10 +123,10 @@ options: version_added: 8.5.0 requirements: [openssl, keytool] author: -- Adam Hamsik (@haad) -''' + - Adam Hamsik (@haad) +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Import SSL certificate from google.com to a given cacerts keystore community.general.java_cert: cert_url: google.com @@ -196,9 +194,9 @@ EXAMPLES = r''' keystore_pass: changeit keystore_create: true state: present -''' +""" -RETURN = r''' +RETURN = r""" msg: description: Output from stdout of keytool command after execution of given command. returned: success @@ -216,7 +214,7 @@ cmd: returned: success type: str sample: "keytool -importcert -noprompt -keystore" -''' +""" import os import tempfile diff --git a/plugins/modules/java_keystore.py b/plugins/modules/java_keystore.py index 0a8e3398d5..df7e71abbe 100644 --- a/plugins/modules/java_keystore.py +++ b/plugins/modules/java_keystore.py @@ -10,8 +10,7 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: java_keystore short_description: Create a Java keystore in JKS format description: @@ -25,25 +24,22 @@ options: name: description: - Name of the certificate in the keystore. - - If the provided name does not exist in the keystore, the module - will re-create the keystore. This behavior changed in community.general 3.0.0, - before that the module would fail when the name did not match. + - If the provided name does not exist in the keystore, the module will re-create the keystore. This behavior changed + in community.general 3.0.0, before that the module would fail when the name did not match. type: str required: true certificate: description: - Content of the certificate used to create the keystore. - - If the fingerprint of the provided certificate does not match the - fingerprint of the certificate bundled in the keystore, the keystore - is regenerated with the provided certificate. + - If the fingerprint of the provided certificate does not match the fingerprint of the certificate bundled in the keystore, + the keystore is regenerated with the provided certificate. - Exactly one of O(certificate) or O(certificate_path) is required. type: str certificate_path: description: - Location of the certificate used to create the keystore. - - If the fingerprint of the provided certificate does not match the - fingerprint of the certificate bundled in the keystore, the keystore - is regenerated with the provided certificate. + - If the fingerprint of the provided certificate does not match the fingerprint of the certificate bundled in the keystore, + the keystore is regenerated with the provided certificate. - Exactly one of O(certificate) or O(certificate_path) is required. type: path version_added: '3.0.0' @@ -66,10 +62,8 @@ options: password: description: - Password that should be used to secure the keystore. - - If the provided password fails to unlock the keystore, the module - will re-create the keystore with the new passphrase. This behavior - changed in community.general 3.0.0, before that the module would fail - when the password did not match. + - If the provided password fails to unlock the keystore, the module will re-create the keystore with the new passphrase. + This behavior changed in community.general 3.0.0, before that the module would fail when the password did not match. type: str required: true dest: @@ -106,16 +100,13 @@ options: keystore_type: description: - Type of the Java keystore. - - When this option is omitted and the keystore doesn't already exist, the - behavior follows C(keytool)'s default store type which depends on - Java version; V(pkcs12) since Java 9 and V(jks) prior (may also - be V(pkcs12) if new default has been backported to this version). - - When this option is omitted and the keystore already exists, the current - type is left untouched, unless another option leads to overwrite the - keystore (in that case, this option behaves like for keystore creation). - - When O(keystore_type) is set, the keystore is created with this type if - it does not already exist, or is overwritten to match the given type in - case of mismatch. + - When this option is omitted and the keystore does not already exist, the behavior follows C(keytool)'s default store + type which depends on Java version; V(pkcs12) since Java 9 and V(jks) prior (may also be V(pkcs12) if new default + has been backported to this version). + - When this option is omitted and the keystore already exists, the current type is left untouched, unless another option + leads to overwrite the keystore (in that case, this option behaves like for keystore creation). + - When O(keystore_type) is set, the keystore is created with this type if it does not already exist, or is overwritten + to match the given type in case of mismatch. type: str choices: - jks @@ -135,16 +126,14 @@ seealso: - module: community.crypto.openssl_pkcs12 - module: community.general.java_cert notes: - - O(certificate) and O(private_key) require that their contents are available - on the controller (either inline in a playbook, or with the P(ansible.builtin.file#lookup) lookup), - while O(certificate_path) and O(private_key_path) require that the files are - available on the target host. - - By design, any change of a value of options O(keystore_type), O(name) or - O(password), as well as changes of key or certificate materials will cause - the existing O(dest) to be overwritten. -''' + - O(certificate) and O(private_key) require that their contents are available on the controller (either inline in a playbook, + or with the P(ansible.builtin.file#lookup) lookup), while O(certificate_path) and O(private_key_path) require that the + files are available on the target host. + - By design, any change of a value of options O(keystore_type), O(name) or O(password), as well as changes of key or certificate + materials will cause the existing O(dest) to be overwritten. +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a keystore for the given certificate/private key pair (inline) community.general.java_keystore: name: example @@ -174,9 +163,9 @@ EXAMPLES = ''' private_key_path: /etc/ssl/private/ssl-cert-snakeoil.key password: changeit dest: /etc/security/keystore.jks -''' +""" -RETURN = ''' +RETURN = r""" msg: description: Output from stdout of keytool/openssl command after execution of given command or an error. returned: changed and failure @@ -190,17 +179,17 @@ err: sample: "Keystore password is too short - must be at least 6 characters\n" rc: - description: keytool/openssl command execution return value + description: Keytool/openssl command execution return value. returned: changed and failure type: int sample: "0" cmd: - description: Executed command to get action done + description: Executed command to get action done. returned: changed and failure type: str sample: "/usr/bin/openssl x509 -noout -in /tmp/user/1000/tmp8jd_lh23 -fingerprint -sha256" -''' +""" import os diff --git a/plugins/modules/jboss.py b/plugins/modules/jboss.py index 3d07a38d63..2d4f4b9bad 100644 --- a/plugins/modules/jboss.py +++ b/plugins/modules/jboss.py @@ -9,7 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' +DOCUMENTATION = r""" module: jboss short_description: Deploy applications to JBoss description: @@ -39,23 +39,23 @@ options: - The location in the filesystem where the deployment scanner listens. type: path state: - choices: [ present, absent ] + choices: [present, absent] default: "present" description: - Whether the application should be deployed or undeployed. type: str notes: - - The JBoss standalone deployment-scanner has to be enabled in standalone.xml - - The module can wait until O(deployment) file is deployed/undeployed by deployment-scanner. - Duration of waiting time depends on scan-interval parameter from standalone.xml. - - Ensure no identically named application is deployed through the JBoss CLI + - The JBoss standalone deployment-scanner has to be enabled in C(standalone.xml). + - The module can wait until O(deployment) file is deployed/undeployed by deployment-scanner. Duration of waiting time depends + on scan-interval parameter from C(standalone.xml). + - Ensure no identically named application is deployed through the JBoss CLI. seealso: -- name: WildFly reference - description: Complete reference of the WildFly documentation. - link: https://docs.wildfly.org + - name: WildFly reference + description: Complete reference of the WildFly documentation. + link: https://docs.wildfly.org author: - Jeroen Hoekx (@jhoekx) -''' +""" EXAMPLES = r""" - name: Deploy a hello world application to the default deploy_path diff --git a/plugins/modules/jenkins_build.py b/plugins/modules/jenkins_build.py index 6d830849e7..a909eab690 100644 --- a/plugins/modules/jenkins_build.py +++ b/plugins/modules/jenkins_build.py @@ -8,13 +8,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: jenkins_build short_description: Manage jenkins builds version_added: 2.2.0 description: - - Manage Jenkins builds with Jenkins REST API. + - Manage Jenkins builds with Jenkins REST API. requirements: - "python-jenkins >= 0.4.12" author: @@ -64,7 +63,7 @@ options: type: str user: description: - - User to authenticate with the Jenkins server. + - User to authenticate with the Jenkins server. type: str detach: description: @@ -79,9 +78,9 @@ options: default: 10 type: int version_added: 7.4.0 -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a jenkins build using basic authentication community.general.jenkins_build: name: "test-check" @@ -108,10 +107,9 @@ EXAMPLES = ''' user: Jenkins token: abcdefghijklmnopqrstuvwxyz123456 url: http://localhost:8080 -''' +""" -RETURN = ''' ---- +RETURN = r""" name: description: Name of the jenkins job. returned: success @@ -136,7 +134,7 @@ build_info: description: Build info of the jenkins job. returned: success type: dict -''' +""" import traceback from time import sleep diff --git a/plugins/modules/jenkins_build_info.py b/plugins/modules/jenkins_build_info.py index eae6eb9374..f252eb504a 100644 --- a/plugins/modules/jenkins_build_info.py +++ b/plugins/modules/jenkins_build_info.py @@ -8,13 +8,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: jenkins_build_info short_description: Get information about Jenkins builds version_added: 7.4.0 description: - - Get information about Jenkins builds with Jenkins REST API. + - Get information about Jenkins builds with Jenkins REST API. requirements: - "python-jenkins >= 0.4.12" author: @@ -48,11 +47,11 @@ options: type: str user: description: - - User to authenticate with the Jenkins server. + - User to authenticate with the Jenkins server. type: str -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Get information about a jenkins build using basic authentication community.general.jenkins_build_info: name: "test-check" @@ -74,10 +73,9 @@ EXAMPLES = ''' user: Jenkins token: abcdefghijklmnopqrstuvwxyz123456 url: http://localhost:8080 -''' +""" -RETURN = ''' ---- +RETURN = r""" name: description: Name of the jenkins job. returned: success @@ -102,7 +100,7 @@ build_info: description: Build info of the jenkins job. returned: success type: dict -''' +""" import traceback diff --git a/plugins/modules/jenkins_job.py b/plugins/modules/jenkins_job.py index e8301041f2..f539e569e8 100644 --- a/plugins/modules/jenkins_job.py +++ b/plugins/modules/jenkins_job.py @@ -8,12 +8,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: jenkins_job short_description: Manage jenkins jobs description: - - Manage Jenkins jobs by using Jenkins REST API. + - Manage Jenkins jobs by using Jenkins REST API. requirements: - "python-jenkins >= 0.4.12" author: "Sergio Millan Rodriguez (@sermilrod)" @@ -28,7 +27,7 @@ options: config: type: str description: - - config in XML format. + - Config in XML format. - Required if job does not yet exist. - Mutually exclusive with O(enabled). - Considered if O(state=present). @@ -71,20 +70,19 @@ options: user: type: str description: - - User to authenticate with the Jenkins server. + - User to authenticate with the Jenkins server. required: false validate_certs: type: bool default: true description: - - If set to V(false), the SSL certificates will not be validated. - This should only set to V(false) used on personally controlled sites - using self-signed certificates as it avoids verifying the source site. + - If set to V(false), the SSL certificates will not be validated. This should only set to V(false) used on personally + controlled sites using self-signed certificates as it avoids verifying the source site. - The C(python-jenkins) library only handles this by using the environment variable E(PYTHONHTTPSVERIFY). version_added: 2.3.0 -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a jenkins job using basic authentication community.general.jenkins_job: config: "{{ lookup('file', 'templates/test.xml') }}" @@ -132,10 +130,9 @@ EXAMPLES = ''' enabled: false url: http://localhost:8080 user: admin -''' +""" -RETURN = ''' ---- +RETURN = r""" name: description: Name of the jenkins job. returned: success @@ -161,7 +158,7 @@ url: returned: success type: str sample: https://jenkins.mydomain.com -''' +""" import os import traceback diff --git a/plugins/modules/jenkins_job_info.py b/plugins/modules/jenkins_job_info.py index 40e1d7aea3..40aa416968 100644 --- a/plugins/modules/jenkins_job_info.py +++ b/plugins/modules/jenkins_job_info.py @@ -9,8 +9,7 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: jenkins_job_info short_description: Get information about Jenkins jobs description: @@ -51,18 +50,18 @@ options: user: type: str description: - - User to authenticate with the Jenkins server. + - User to authenticate with the Jenkins server. validate_certs: description: - - If set to V(false), the SSL certificates will not be validated. - - This should only set to V(false) used on personally controlled sites using self-signed certificates. + - If set to V(false), the SSL certificates will not be validated. + - This should only set to V(false) used on personally controlled sites using self-signed certificates. default: true type: bool author: - "Chris St. Pierre (@stpierre)" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" # Get all Jenkins jobs anonymously - community.general.jenkins_job_info: user: admin @@ -122,24 +121,23 @@ EXAMPLES = ''' token: 126df5c60d66c66e3b75b11104a16a8a url: https://jenkins.example.com register: my_jenkins_job_info -''' +""" -RETURN = ''' ---- +RETURN = r""" jobs: - description: All jobs found matching the specified criteria + description: All jobs found matching the specified criteria. returned: success type: list sample: [ - { - "name": "test-job", - "fullname": "test-folder/test-job", - "url": "http://localhost:8080/job/test-job/", - "color": "blue" - }, + { + "name": "test-job", + "fullname": "test-folder/test-job", + "url": "http://localhost:8080/job/test-job/", + "color": "blue" + }, ] -''' +""" import ssl import fnmatch diff --git a/plugins/modules/jenkins_node.py b/plugins/modules/jenkins_node.py index 9406eab4c5..affd462659 100644 --- a/plugins/modules/jenkins_node.py +++ b/plugins/modules/jenkins_node.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: jenkins_node short_description: Manage Jenkins nodes version_added: 10.0.0 @@ -25,8 +24,7 @@ attributes: check_mode: support: partial details: - - Check mode is unable to show configuration changes for a node that is not yet - present. + - Check mode is unable to show configuration changes for a node that is not yet present. diff_mode: support: none options: @@ -50,8 +48,8 @@ options: type: str state: description: - - Specifies whether the Jenkins node should be V(present) (created), V(absent) - (deleted), V(enabled) (online) or V(disabled) (offline). + - Specifies whether the Jenkins node should be V(present) (created), V(absent) (deleted), V(enabled) (online) or V(disabled) + (offline). default: present choices: ['enabled', 'disabled', 'present', 'absent'] type: str @@ -66,18 +64,15 @@ options: elements: str offline_message: description: - - Specifies the offline reason message to be set when configuring the Jenkins node - state. - - If O(offline_message) is given and requested O(state) is not V(disabled), an - error will be raised. - - Internally O(offline_message) is set via the V(toggleOffline) API, so updating - the message when the node is already offline (current state V(disabled)) is not - possible. In this case, a warning will be issued. + - Specifies the offline reason message to be set when configuring the Jenkins node state. + - If O(offline_message) is given and requested O(state) is not V(disabled), an error will be raised. + - Internally O(offline_message) is set using the V(toggleOffline) API, so updating the message when the node is already + offline (current state V(disabled)) is not possible. In this case, a warning will be issued. type: str version_added: 10.0.0 -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a Jenkins node using token authentication community.general.jenkins_node: url: http://localhost:8080 @@ -105,12 +100,11 @@ EXAMPLES = ''' community.general.jenkins_node: name: my-node state: disabled - offline_message: > + offline_message: >- This node is offline for some reason. -''' +""" -RETURN = ''' ---- +RETURN = r""" url: description: URL used to connect to the Jenkins server. returned: success @@ -151,7 +145,7 @@ configured: description: Whether or not the Jenkins node was configured by the task. returned: success type: bool -''' +""" import sys import traceback diff --git a/plugins/modules/jenkins_plugin.py b/plugins/modules/jenkins_plugin.py index 8834e0a2b2..2663b4fe35 100644 --- a/plugins/modules/jenkins_plugin.py +++ b/plugins/modules/jenkins_plugin.py @@ -9,14 +9,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: jenkins_plugin author: Jiri Tyr (@jtyr) short_description: Add or remove Jenkins plugin description: - Ansible module which helps to manage Jenkins plugins. - attributes: check_mode: support: full @@ -53,8 +51,7 @@ options: type: str description: - Desired plugin state. - - If set to V(latest), the check for new version will be performed - every time. This is suitable to keep the plugin up-to-date. + - If set to V(latest), the check for new version will be performed every time. This is suitable to keep the plugin up-to-date. choices: [absent, present, pinned, unpinned, enabled, disabled, latest] default: present timeout: @@ -65,12 +62,10 @@ options: updates_expiration: type: int description: - - Number of seconds after which a new copy of the C(update-center.json) - file is downloaded. This is used to avoid the need to download the - plugin to calculate its checksum when O(state=latest) is specified. - - Set it to V(0) if no cache file should be used. In that case, the - plugin file will always be downloaded to calculate its checksum when - O(state=latest) is specified. + - Number of seconds after which a new copy of the C(update-center.json) file is downloaded. This is used to avoid the + need to download the plugin to calculate its checksum when O(state=latest) is specified. + - Set it to V(0) if no cache file should be used. In that case, the plugin file will always be downloaded to calculate + its checksum when O(state=latest) is specified. default: 86400 updates_url: type: list @@ -109,12 +104,11 @@ options: type: str description: - Plugin version number. - - If this option is specified, all plugin dependencies must be installed - manually. - - It might take longer to verify that the correct version is installed. - This is especially true if a specific version number is specified. - - Quote the version to prevent the value to be interpreted as float. For - example if V(1.20) would be unquoted, it would become V(1.2). + - If this option is specified, all plugin dependencies must be installed manually. + - It might take longer to verify that the correct version is installed. This is especially true if a specific version + number is specified. + - Quote the version to prevent the value to be interpreted as float. For example if V(1.20) would be unquoted, it would + become V(1.2). with_dependencies: description: - Defines whether to install plugin dependencies. @@ -123,24 +117,20 @@ options: default: true notes: - - Plugin installation should be run under root or the same user which owns - the plugin files on the disk. Only if the plugin is not installed yet and - no version is specified, the API installation is performed which requires - only the Web UI credentials. - - It is necessary to notify the handler or call the M(ansible.builtin.service) module to - restart the Jenkins service after a new plugin was installed. - - Pinning works only if the plugin is installed and Jenkins service was - successfully restarted after the plugin installation. - - It is not possible to run the module remotely by changing the O(url) - parameter to point to the Jenkins server. The module must be used on the - host where Jenkins runs as it needs direct access to the plugin files. + - Plugin installation should be run under root or the same user which owns the plugin files on the disk. Only if the plugin + is not installed yet and no version is specified, the API installation is performed which requires only the Web UI credentials. + - It is necessary to notify the handler or call the M(ansible.builtin.service) module to restart the Jenkins service after + a new plugin was installed. + - Pinning works only if the plugin is installed and Jenkins service was successfully restarted after the plugin installation. + - It is not possible to run the module remotely by changing the O(url) parameter to point to the Jenkins server. The module + must be used on the host where Jenkins runs as it needs direct access to the plugin files. extends_documentation_fragment: - ansible.builtin.url - ansible.builtin.files - community.general.attributes -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Install plugin community.general.jenkins_plugin: name: build-pipeline-plugin @@ -281,8 +271,8 @@ EXAMPLES = ''' retries: 60 delay: 5 until: > - 'status' in jenkins_service_status and - jenkins_service_status['status'] == 200 + 'status' in jenkins_service_status and + jenkins_service_status['status'] == 200 when: jenkins_restart_required - name: Reset the fact @@ -305,20 +295,20 @@ EXAMPLES = ''' when: > 'enabled' in item.value with_dict: "{{ my_jenkins_plugins }}" -''' +""" -RETURN = ''' +RETURN = r""" plugin: - description: plugin name - returned: success - type: str - sample: build-pipeline-plugin + description: Plugin name. + returned: success + type: str + sample: build-pipeline-plugin state: - description: state of the target, after execution - returned: success - type: str - sample: "present" -''' + description: State of the target, after execution. + returned: success + type: str + sample: "present" +""" import hashlib import io diff --git a/plugins/modules/jenkins_script.py b/plugins/modules/jenkins_script.py index 030c8e6fa3..0f6064eeca 100644 --- a/plugins/modules/jenkins_script.py +++ b/plugins/modules/jenkins_script.py @@ -9,17 +9,15 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" author: James Hogarth (@hogarthj) module: jenkins_script short_description: Executes a groovy script in the jenkins instance description: - - The C(jenkins_script) module takes a script plus a dict of values - to use within the script and returns the result of the script being run. - + - The C(jenkins_script) module takes a script plus a dict of values to use within the script and returns the result of the + script being run. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: @@ -31,20 +29,18 @@ options: script: type: str description: - - The groovy script to be executed. - This gets passed as a string Template if args is defined. + - The groovy script to be executed. This gets passed as a string Template if args is defined. required: true url: type: str description: - - The jenkins server to execute the script against. The default is a local - jenkins instance that is not being proxied through a webserver. + - The jenkins server to execute the script against. The default is a local jenkins instance that is not being proxied + through a webserver. default: http://localhost:8080 validate_certs: description: - - If set to V(false), the SSL certificates will not be validated. - This should only set to V(false) used on personally controlled sites - using self-signed certificates as it avoids verifying the source site. + - If set to V(false), the SSL certificates will not be validated. This should only set to V(false) used on personally + controlled sites using self-signed certificates as it avoids verifying the source site. type: bool default: true user: @@ -58,21 +54,18 @@ options: timeout: type: int description: - - The request timeout in seconds + - The request timeout in seconds. default: 10 args: type: dict description: - A dict of key-value pairs used in formatting the script using string.Template (see https://docs.python.org/2/library/string.html#template-strings). - notes: - - Since the script can do anything this does not report on changes. - Knowing the script is being run it's important to set changed_when - for the ansible output to be clear on any alterations made. + - Since the script can do anything this does not report on changes. Knowing the script is being run it's important to set + changed_when for the ansible output to be clear on any alterations made. +""" -''' - -EXAMPLES = ''' +EXAMPLES = r""" - name: Obtaining a list of plugins community.general.jenkins_script: script: 'println(Jenkins.instance.pluginManager.plugins)' @@ -82,10 +75,10 @@ EXAMPLES = ''' - name: Setting master using a variable to hold a more complicate script ansible.builtin.set_fact: setmaster_mode: | - import jenkins.model.* - instance = Jenkins.getInstance() - instance.setMode(${jenkins_mode}) - instance.save() + import jenkins.model.* + instance = Jenkins.getInstance() + instance.setMode(${jenkins_mode}) + instance.save() - name: Use the variable as the script community.general.jenkins_script: @@ -99,16 +92,16 @@ EXAMPLES = ''' user: admin password: admin url: https://localhost - validate_certs: false # only do this when you trust the network! -''' + validate_certs: false # only do this when you trust the network! +""" -RETURN = ''' +RETURN = r""" output: - description: Result of script - returned: success - type: str - sample: 'Result: true' -''' + description: Result of script. + returned: success + type: str + sample: 'Result: true' +""" import json diff --git a/plugins/modules/jira.py b/plugins/modules/jira.py index 64aed7e149..cc3136c3bf 100644 --- a/plugins/modules/jira.py +++ b/plugins/modules/jira.py @@ -20,7 +20,6 @@ module: jira short_description: Create and modify issues in a JIRA instance description: - Create and modify issues in a JIRA instance. - extends_documentation_fragment: - community.general.attributes @@ -36,28 +35,24 @@ options: required: true description: - Base URI for the JIRA instance. - operation: type: str required: true - aliases: [ command ] - choices: [ attach, comment, create, edit, fetch, link, search, transition, update, worklog ] + aliases: [command] + choices: [attach, comment, create, edit, fetch, link, search, transition, update, worklog] description: - The operation to perform. - V(worklog) was added in community.general 6.5.0. - username: type: str description: - The username to log-in with. - Must be used with O(password). Mutually exclusive with O(token). - password: type: str description: - The password to log-in with. - - Must be used with O(username). Mutually exclusive with O(token). - + - Must be used with O(username). Mutually exclusive with O(token). token: type: str description: @@ -70,56 +65,54 @@ options: required: false description: - The project for this operation. Required for issue creation. - summary: type: str required: false description: - - The issue summary, where appropriate. - - Note that JIRA may not allow changing field values on specific transitions or states. - + - The issue summary, where appropriate. + - Note that JIRA may not allow changing field values on specific transitions or states. description: type: str required: false description: - - The issue description, where appropriate. - - Note that JIRA may not allow changing field values on specific transitions or states. - + - The issue description, where appropriate. + - Note that JIRA may not allow changing field values on specific transitions or states. issuetype: type: str required: false description: - - The issue type, for issue creation. - + - The issue type, for issue creation. issue: type: str required: false description: - - An existing issue key to operate on. + - An existing issue key to operate on. aliases: ['ticket'] comment: type: str required: false description: - - The comment text to add. - - Note that JIRA may not allow changing field values on specific transitions or states. - + - The comment text to add. + - Note that JIRA may not allow changing field values on specific transitions or states. comment_visibility: type: dict description: - - Used to specify comment comment visibility. - - See U(https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issue-comments/#api-rest-api-2-issue-issueidorkey-comment-post) for details. + - Used to specify comment comment visibility. + - See + U(https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issue-comments/#api-rest-api-2-issue-issueidorkey-comment-post) + for details. suboptions: type: description: - - Use type to specify which of the JIRA visibility restriction types will be used. + - Use type to specify which of the JIRA visibility restriction types will be used. type: str required: true choices: [group, role] value: description: - - Use value to specify value corresponding to the type of visibility restriction. For example name of the group or role. + - Use value to specify value corresponding to the type of visibility restriction. For example name of the group + or role. type: str required: true version_added: '3.2.0' @@ -128,63 +121,59 @@ options: type: str required: false description: - - Only used when O(operation) is V(transition), and a bit of a misnomer, it actually refers to the transition name. - + - Only used when O(operation) is V(transition), and a bit of a misnomer, it actually refers to the transition name. assignee: type: str required: false description: - - Sets the the assignee when O(operation) is V(create), V(transition), or V(edit). - - Recent versions of JIRA no longer accept a user name as a user identifier. In that case, use O(account_id) instead. - - Note that JIRA may not allow changing field values on specific transitions or states. - + - Sets the the assignee when O(operation) is V(create), V(transition), or V(edit). + - Recent versions of JIRA no longer accept a user name as a user identifier. In that case, use O(account_id) instead. + - Note that JIRA may not allow changing field values on specific transitions or states. account_id: type: str description: - - Sets the account identifier for the assignee when O(operation) is V(create), V(transition), or V(edit). - - Note that JIRA may not allow changing field values on specific transitions or states. + - Sets the account identifier for the assignee when O(operation) is V(create), V(transition), or V(edit). + - Note that JIRA may not allow changing field values on specific transitions or states. version_added: 2.5.0 linktype: type: str required: false description: - - Set type of link, when action 'link' selected. - + - Set type of link, when action 'link' selected. inwardissue: type: str required: false description: - - Set issue from which link will be created. - + - Set issue from which link will be created. outwardissue: type: str required: false description: - - Set issue to which link will be created. - + - Set issue to which link will be created. fields: type: dict required: false description: - - This is a free-form data structure that can contain arbitrary data. This is passed directly to the JIRA REST API - (possibly after merging with other required data, as when passed to create). See examples for more information, - and the JIRA REST API for the structure required for various fields. - - When passed to comment, the data structure is merged at the first level since community.general 4.6.0. Useful to add JIRA properties for example. - - Note that JIRA may not allow changing field values on specific transitions or states. + - This is a free-form data structure that can contain arbitrary data. This is passed directly to the JIRA REST API (possibly + after merging with other required data, as when passed to create). See examples for more information, and the JIRA + REST API for the structure required for various fields. + - When passed to comment, the data structure is merged at the first level since community.general 4.6.0. Useful to add + JIRA properties for example. + - Note that JIRA may not allow changing field values on specific transitions or states. default: {} jql: required: false description: - - Query JIRA in JQL Syntax, e.g. 'CMDB Hostname'='test.example.com'. + - Query JIRA in JQL Syntax, for example V("CMDB Hostname" = test.example.com). type: str version_added: '0.2.0' maxresults: required: false description: - - Limit the result of O(operation=search). If no value is specified, the default jira limit will be used. - - Used when O(operation=search) only, ignored otherwise. + - Limit the result of O(operation=search). If no value is specified, the default jira limit will be used. + - Used when O(operation=search) only, ignored otherwise. type: int version_added: '0.2.0' @@ -198,7 +187,7 @@ options: validate_certs: required: false description: - - Require valid SSL certificates (set to V(false) if you would like to use self-signed certificates) + - Require valid SSL certificates (set to V(false) if you would like to use self-signed certificates). default: true type: bool @@ -212,27 +201,24 @@ options: required: true type: path description: - - The path to the file to upload (from the remote node) or, if O(attachment.content) is specified, - the filename to use for the attachment. + - The path to the file to upload (from the remote node) or, if O(attachment.content) is specified, the filename + to use for the attachment. content: type: str description: - - The Base64 encoded contents of the file to attach. If not specified, the contents of O(attachment.filename) will be - used instead. + - The Base64 encoded contents of the file to attach. If not specified, the contents of O(attachment.filename) will + be used instead. mimetype: type: str description: - - The MIME type to supply for the upload. If not specified, best-effort detection will be - done. - + - The MIME type to supply for the upload. If not specified, best-effort detection will be done. notes: - - "Currently this only works with basic-auth, or tokens." - - "To use with JIRA Cloud, pass the login e-mail as the O(username) and the API token as O(password)." - + - Currently this only works with basic-auth, or tokens. + - To use with JIRA Cloud, pass the login e-mail as the O(username) and the API token as O(password). author: -- "Steve Smith (@tarka)" -- "Per Abildgaard Toft (@pertoft)" -- "Brandon McNama (@DWSR)" + - "Steve Smith (@tarka)" + - "Per Abildgaard Toft (@pertoft)" + - "Brandon McNama (@DWSR)" """ EXAMPLES = r""" @@ -249,8 +235,8 @@ EXAMPLES = r""" issuetype: Task args: fields: - customfield_13225: "test" - customfield_12931: {"value": "Test"} + customfield_13225: "test" + customfield_12931: {"value": "Test"} register: issue - name: Comment on issue @@ -362,9 +348,9 @@ EXAMPLES = r""" operation: edit args: fields: - labels: - - autocreated - - ansible + labels: + - autocreated + - ansible # Updating a field using operations: add, set & remove - name: Change the value of a Select dropdown @@ -376,8 +362,8 @@ EXAMPLES = r""" operation: update args: fields: - customfield_12931: [ {'set': {'value': 'Virtual'}} ] - customfield_13820: [ {'set': {'value':'Manually'}} ] + customfield_12931: ['set': {'value': 'Virtual'}] + customfield_13820: ['set': {'value': 'Manually'}] register: cmdb_issue delegate_to: localhost @@ -406,7 +392,7 @@ EXAMPLES = r""" jql: project=cmdb AND cf[13225]="test" args: fields: - lastViewed: null + lastViewed: register: issue - name: Create a unix account for the reporter