a-c-m
/
community.general
mirror of https://github.com/ansible-collections/community.general.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[ip ... j]*.py: normalize docs (#9392) 

* [ip ... j]*.py: normalize docs

* Update plugins/modules/ip_netns.py

Co-authored-by: Felix Fontein <felix@fontein.de>

---------

Co-authored-by: Felix Fontein <felix@fontein.de>
pull/8676/merge
Alexei Znamensky 2024-12-27 01:40:05 +13:00 committed by GitHub
parent cea6eeef37
commit a99f72fc36
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
43 changed files with 1290 additions and 1429 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
plugins/modules/ip_netns.py
View File

@ -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

14
plugins/modules/ipa_config.py
View File

@ -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

82
plugins/modules/ipa_dnsrecord.py
View File

@ -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

20
plugins/modules/ipa_dnszone.py
View File

@ -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

12
plugins/modules/ipa_getkeytab.py
View File

@ -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

110
plugins/modules/ipa_group.py
View File

@ -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

84
plugins/modules/ipa_hbacrule.py
View File

@ -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

60
plugins/modules/ipa_host.py
View File

@ -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

51
plugins/modules/ipa_hostgroup.py
View File

@ -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

14
plugins/modules/ipa_otpconfig.py
View File

@ -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

63
plugins/modules/ipa_otptoken.py
View File

@ -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

251
plugins/modules/ipa_pwpolicy.py
View File

@ -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

84
plugins/modules/ipa_role.py
View File

@ -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

32
plugins/modules/ipa_service.py
View File

@ -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

26
plugins/modules/ipa_subca.py
View File

@ -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

22
plugins/modules/ipa_sudocmd.py
View File

@ -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

30
plugins/modules/ipa_sudocmdgroup.py
View File

@ -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

111
plugins/modules/ipa_sudorule.py
View File

@ -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

83
plugins/modules/ipa_user.py
View File

@ -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

140
plugins/modules/ipa_vault.py
View File

@ -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

29
plugins/modules/ipbase_info.py
View File

@ -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

16
plugins/modules/ipify_facts.py
View File

@ -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

39
plugins/modules/ipinfoio_facts.py
View File

@ -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

70
plugins/modules/ipmi_boot.py
View File

@ -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) <gaifullinbf@gmail.com>"
'''
"""
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

73
plugins/modules/ipmi_power.py
View File

@ -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) <gaifullinbf@gmail.com>"
'''
"""
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

75
plugins/modules/iptables_state.py
View File

@ -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

217
plugins/modules/ipwcli_dns.py
View File

@ -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

61
plugins/modules/irc.py
View File

@ -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.

173
plugins/modules/iso_create.py
View File

@ -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

36
plugins/modules/iso_customize.py
View File

@ -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

58
plugins/modules/iso_extract.py
View File

@ -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

27
plugins/modules/jabber.py
View File

@ -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

30
plugins/modules/java_cert.py
View File

@ -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

67
plugins/modules/java_keystore.py
View File

@ -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

20
plugins/modules/jboss.py
View File

@ -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

18
plugins/modules/jenkins_build.py
View File

@ -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

18
plugins/modules/jenkins_build_info.py
View File

@ -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

25
plugins/modules/jenkins_job.py
View File

@ -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

34
plugins/modules/jenkins_job_info.py
View File

@ -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

34
plugins/modules/jenkins_node.py
View File

@ -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

76
plugins/modules/jenkins_plugin.py
View File

@ -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

59
plugins/modules/jenkins_script.py
View File

@ -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

124
plugins/modules/jira.py
View File

@ -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