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

x*: adjust docs (#9308) 

* adjust docs

* Update plugins/modules/xml.py

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

* fix capitalisation

* add markup to references of the xe command (xenserver)

* add missing markup

* Update plugins/modules/xml.py

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

---------

Co-authored-by: Felix Fontein <felix@fontein.de>
pull/9344/head
Alexei Znamensky 2024-12-24 06:58:02 +13:00 committed by GitHub
parent 005c8f50db
commit f9bfe4e4a6
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
11 changed files with 827 additions and 863 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
plugins/modules/xattr.py
View File

@ -8,14 +8,12 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: xattr module: xattr
short_description: Manage user defined extended attributes short_description: Manage user defined extended attributes
description: description:
- Manages filesystem user defined extended attributes. - Manages filesystem user defined extended attributes.
- Requires that extended attributes are enabled on the target filesystem - Requires that extended attributes are enabled on the target filesystem and that the C(setfattr)/C(getfattr) utilities are present.
and that the setfattr/getfattr utilities are present.
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
@ -29,7 +27,7 @@ options:
- The full path of the file/object to get the facts of. - The full path of the file/object to get the facts of.
type: path type: path
required: true required: true
aliases: [ name ] aliases: [name]
namespace: namespace:
description: description:
- Namespace of the named name/key. - Namespace of the named name/key.
@ -45,26 +43,25 @@ options:
type: str type: str
state: state:
description: description:
- defines which state you want to do. - Defines which state you want to do.
V(read) retrieves the current value for a O(key) (default) - V(read) retrieves the current value for a O(key).
V(present) sets O(path) to O(value), default if value is set - V(present) sets O(path) to O(value), default if value is set.
V(all) dumps all data - V(all) dumps all data.
V(keys) retrieves all keys - V(keys) retrieves all keys.
V(absent) deletes the key - V(absent) deletes the key.
type: str type: str
choices: [ absent, all, keys, present, read ] choices: [absent, all, keys, present, read]
default: read default: read
follow: follow:
description: description:
- If V(true), dereferences symlinks and sets/gets attributes on symlink target, - If V(true), dereferences symlinks and sets/gets attributes on symlink target, otherwise acts on symlink itself.
otherwise acts on symlink itself.
type: bool type: bool
default: true default: true
author: author:
- Brian Coca (@bcoca) - Brian Coca (@bcoca)
''' """
EXAMPLES = ''' EXAMPLES = r"""
- name: Obtain the extended attributes of /etc/foo.conf - name: Obtain the extended attributes of /etc/foo.conf
community.general.xattr: community.general.xattr:
path: /etc/foo.conf path: /etc/foo.conf
@ -94,7 +91,7 @@ EXAMPLES = '''
namespace: trusted namespace: trusted
key: glusterfs.volume-id key: glusterfs.volume-id
state: absent state: absent
''' """
import os import os

42
plugins/modules/xbps.py
View File

@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: xbps module: xbps
short_description: Manage packages with XBPS short_description: Manage packages with XBPS
description: description:
@ -30,7 +29,7 @@ options:
name: name:
description: description:
- Name of the package to install, upgrade, or remove. - Name of the package to install, upgrade, or remove.
aliases: [pkg,package] aliases: [pkg, package]
type: list type: list
elements: str elements: str
state: state:
@ -41,29 +40,24 @@ options:
type: str type: str
recurse: recurse:
description: description:
- When removing a package, also remove its dependencies, provided - When removing a package, also remove its dependencies, provided that they are not required by other packages and were not explicitly installed
that they are not required by other packages and were not by a user.
explicitly installed by a user.
type: bool type: bool
default: false default: false
update_cache: update_cache:
description: description:
- Whether or not to refresh the master package lists. This can be - Whether or not to refresh the master package lists. This can be run as part of a package installation or as a separate step.
run as part of a package installation or as a separate step.
type: bool type: bool
default: true default: true
upgrade: upgrade:
description: description:
- Whether or not to upgrade whole system - Whether or not to upgrade whole system.
type: bool type: bool
default: false default: false
upgrade_xbps: upgrade_xbps:
description: description:
- Whether or not to upgrade the xbps package when necessary. - Whether or not to upgrade the xbps package when necessary. Before installing new packages, xbps requires the user to update the xbps package
Before installing new packages, itself. Thus when this option is set to V(false), upgrades and installations will fail when xbps is not up to date.
xbps requires the user to update the xbps package itself.
Thus when this option is set to V(false),
upgrades and installations will fail when xbps is not up to date.
type: bool type: bool
default: true default: true
version_added: '0.2.0' version_added: '0.2.0'
@ -74,10 +68,8 @@ options:
version_added: '10.2.0' version_added: '10.2.0'
repositories: repositories:
description: description:
- Repository URL(s) to prepend to the repository list for the - Repository URL(s) to prepend to the repository list for the package installation. The URL can be a URL to a repository for remote repositories
package installation. or a path for local repositories.
The URL can be a URL to a repository for
remote repositories or a path for local repositories.
type: list type: list
elements: str elements: str
version_added: '10.2.0' version_added: '10.2.0'
@ -87,9 +79,9 @@ options:
type: bool type: bool
default: false default: false
version_added: '10.2.0' version_added: '10.2.0'
''' """
EXAMPLES = ''' EXAMPLES = r"""
- name: Install package foo (automatically updating the xbps package if needed) - name: Install package foo (automatically updating the xbps package if needed)
community.general.xbps: community.general.xbps:
name: foo name: foo
@ -151,20 +143,20 @@ EXAMPLES = '''
state: present state: present
repositories: https://repo-default.voidlinux.org/current repositories: https://repo-default.voidlinux.org/current
root: /mnt root: /mnt
''' """
RETURN = ''' RETURN = r"""
msg: msg:
description: Message about results description: Message about results.
returned: success returned: success
type: str type: str
sample: "System Upgraded" sample: "System Upgraded"
packages: packages:
description: Packages that are affected/would be affected description: Packages that are affected/would be affected.
type: list type: list
sample: ["ansible"] sample: ["ansible"]
returned: success returned: success
''' """
import os import os

49
plugins/modules/xcc_redfish_command.py
View File

@ -8,14 +8,13 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: xcc_redfish_command module: xcc_redfish_command
short_description: Manages Lenovo Out-Of-Band controllers using Redfish APIs short_description: Manages Lenovo Out-Of-Band controllers using Redfish APIs
version_added: 2.4.0 version_added: 2.4.0
description: description:
- Builds Redfish URIs locally and sends them to remote OOB controllers to - Builds Redfish URIs locally and sends them to remote OOB controllers to perform an action or get information back or update a configuration
perform an action or get information back or update a configuration attribute. attribute.
- Manages virtual media. - Manages virtual media.
- Supports getting information back via GET method. - Supports getting information back via GET method.
- Supports updating a configuration attribute via PATCH method. - Supports updating a configuration attribute via PATCH method.
@ -54,7 +53,7 @@ options:
type: str type: str
auth_token: auth_token:
description: description:
- Security token for authentication with OOB controller - Security token for authentication with OOB controller.
type: str type: str
timeout: timeout:
description: description:
@ -120,10 +119,10 @@ options:
type: dict type: dict
author: "Yuyan Pan (@panyy3)" author: "Yuyan Pan (@panyy3)"
''' """
EXAMPLES = ''' EXAMPLES = r"""
- name: Insert Virtual Media - name: Insert Virtual Media
community.general.xcc_redfish_command: community.general.xcc_redfish_command:
category: Manager category: Manager
command: VirtualMediaInsert command: VirtualMediaInsert
@ -137,7 +136,7 @@ EXAMPLES = '''
- DVD - DVD
resource_id: "1" resource_id: "1"
- name: Eject Virtual Media - name: Eject Virtual Media
community.general.xcc_redfish_command: community.general.xcc_redfish_command:
category: Manager category: Manager
command: VirtualMediaEject command: VirtualMediaEject
@ -148,7 +147,7 @@ EXAMPLES = '''
image_url: "http://example.com/images/SomeLinux-current.iso" image_url: "http://example.com/images/SomeLinux-current.iso"
resource_id: "1" resource_id: "1"
- name: Eject all Virtual Media - name: Eject all Virtual Media
community.general.xcc_redfish_command: community.general.xcc_redfish_command:
category: Manager category: Manager
command: VirtualMediaEject command: VirtualMediaEject
@ -157,7 +156,7 @@ EXAMPLES = '''
password: "{{ password }}" password: "{{ password }}"
resource_id: "1" resource_id: "1"
- name: Get ComputeSystem Oem property SystemStatus via GetResource command - name: Get ComputeSystem Oem property SystemStatus via GetResource command
community.general.xcc_redfish_command: community.general.xcc_redfish_command:
category: Raw category: Raw
command: GetResource command: GetResource
@ -166,10 +165,10 @@ EXAMPLES = '''
password: "{{ password }}" password: "{{ password }}"
resource_uri: "/redfish/v1/Systems/1" resource_uri: "/redfish/v1/Systems/1"
register: result register: result
- ansible.builtin.debug: - ansible.builtin.debug:
msg: "{{ result.redfish_facts.data.Oem.Lenovo.SystemStatus }}" msg: "{{ result.redfish_facts.data.Oem.Lenovo.SystemStatus }}"
- name: Get Oem DNS setting via GetResource command - name: Get Oem DNS setting via GetResource command
community.general.xcc_redfish_command: community.general.xcc_redfish_command:
category: Raw category: Raw
command: GetResource command: GetResource
@ -179,11 +178,11 @@ EXAMPLES = '''
resource_uri: "/redfish/v1/Managers/1/NetworkProtocol/Oem/Lenovo/DNS" resource_uri: "/redfish/v1/Managers/1/NetworkProtocol/Oem/Lenovo/DNS"
register: result register: result
- name: Print fetched information - name: Print fetched information
ansible.builtin.debug: ansible.builtin.debug:
msg: "{{ result.redfish_facts.data }}" msg: "{{ result.redfish_facts.data }}"
- name: Get Lenovo FoD key collection resource via GetCollectionResource command - name: Get Lenovo FoD key collection resource via GetCollectionResource command
community.general.xcc_redfish_command: community.general.xcc_redfish_command:
category: Raw category: Raw
command: GetCollectionResource command: GetCollectionResource
@ -193,11 +192,11 @@ EXAMPLES = '''
resource_uri: "/redfish/v1/Managers/1/Oem/Lenovo/FoD/Keys" resource_uri: "/redfish/v1/Managers/1/Oem/Lenovo/FoD/Keys"
register: result register: result
- name: Print fetched information - name: Print fetched information
ansible.builtin.debug: ansible.builtin.debug:
msg: "{{ result.redfish_facts.data_list }}" msg: "{{ result.redfish_facts.data_list }}"
- name: Update ComputeSystem property AssetTag via PatchResource command - name: Update ComputeSystem property AssetTag via PatchResource command
community.general.xcc_redfish_command: community.general.xcc_redfish_command:
category: Raw category: Raw
command: PatchResource command: PatchResource
@ -208,7 +207,7 @@ EXAMPLES = '''
request_body: request_body:
AssetTag: "new_asset_tag" AssetTag: "new_asset_tag"
- name: Perform BootToBIOSSetup action via PostResource command - name: Perform BootToBIOSSetup action via PostResource command
community.general.xcc_redfish_command: community.general.xcc_redfish_command:
category: Raw category: Raw
command: PostResource command: PostResource
@ -218,7 +217,7 @@ EXAMPLES = '''
resource_uri: "/redfish/v1/Systems/1/Actions/Oem/LenovoComputerSystem.BootToBIOSSetup" resource_uri: "/redfish/v1/Systems/1/Actions/Oem/LenovoComputerSystem.BootToBIOSSetup"
request_body: {} request_body: {}
- name: Perform SecureBoot.ResetKeys action via PostResource command - name: Perform SecureBoot.ResetKeys action via PostResource command
community.general.xcc_redfish_command: community.general.xcc_redfish_command:
category: Raw category: Raw
command: PostResource command: PostResource
@ -229,7 +228,7 @@ EXAMPLES = '''
request_body: request_body:
ResetKeysType: DeleteAllKeys ResetKeysType: DeleteAllKeys
- name: Create session - name: Create session
community.general.redfish_command: community.general.redfish_command:
category: Sessions category: Sessions
command: CreateSession command: CreateSession
@ -238,7 +237,7 @@ EXAMPLES = '''
password: "{{ password }}" password: "{{ password }}"
register: result register: result
- name: Update Manager DateTimeLocalOffset property using security token for auth - name: Update Manager DateTimeLocalOffset property using security token for auth
community.general.xcc_redfish_command: community.general.xcc_redfish_command:
category: Raw category: Raw
command: PatchResource command: PatchResource
@ -248,16 +247,16 @@ EXAMPLES = '''
request_body: request_body:
DateTimeLocalOffset: "+08:00" DateTimeLocalOffset: "+08:00"
- name: Delete session using security token created by CreateSesssion above - name: Delete session using security token created by CreateSesssion above
community.general.redfish_command: community.general.redfish_command:
category: Sessions category: Sessions
command: DeleteSession command: DeleteSession
baseuri: "{{ baseuri }}" baseuri: "{{ baseuri }}"
auth_token: "{{ result.session.token }}" auth_token: "{{ result.session.token }}"
session_uri: "{{ result.session.uri }}" session_uri: "{{ result.session.uri }}"
''' """
RETURN = ''' RETURN = r"""
msg: msg:
description: A message related to the performed action(s). description: A message related to the performed action(s).
returned: when failure or action/update success returned: when failure or action/update success
@ -294,7 +293,7 @@ redfish_facts:
"ret": true "ret": true
} }
}' }'
''' """
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.common.text.converters import to_native from ansible.module_utils.common.text.converters import to_native

11
plugins/modules/xenserver_facts.py
View File

@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: xenserver_facts module: xenserver_facts
short_description: Get facts reported on xenserver short_description: Get facts reported on xenserver
description: description:
- Reads data out of XenAPI, can be used instead of multiple xe commands. - Reads data out of XenAPI, can be used instead of multiple C(xe) commands.
author: author:
- Andy Hill (@andyhky) - Andy Hill (@andyhky)
- Tim Rupp (@caphrim007) - Tim Rupp (@caphrim007)
@ -28,9 +27,9 @@ attributes:
version_added: 3.3.0 version_added: 3.3.0
# This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
options: {} options: {}
''' """
EXAMPLES = ''' EXAMPLES = r"""
- name: Gather facts from xenserver - name: Gather facts from xenserver
community.general.xenserver_facts: community.general.xenserver_facts:
@ -48,7 +47,7 @@ EXAMPLES = '''
# "item": "Control domain on host: 10.0.13.22", # "item": "Control domain on host: 10.0.13.22",
# "msg": "Control domain on host: 10.0.13.22" # "msg": "Control domain on host: 10.0.13.22"
# } # }
''' """
HAVE_XENAPI = False HAVE_XENAPI = False

105
plugins/modules/xenserver_guest.py
View File

@ -8,43 +8,41 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r''' DOCUMENTATION = r"""
---
module: xenserver_guest module: xenserver_guest
short_description: Manages virtual machines running on Citrix Hypervisor/XenServer host or pool short_description: Manages virtual machines running on Citrix Hypervisor/XenServer host or pool
description: > description: >-
This module can be used to create new virtual machines from templates or other virtual machines, This module can be used to create new virtual machines from templates or other virtual machines, modify various virtual machine components like
modify various virtual machine components like network and disk, rename a virtual machine and network and disk, rename a virtual machine and remove a virtual machine with associated components.
remove a virtual machine with associated components.
author: author:
- Bojan Vitnik (@bvitnik) <bvitnik@mainstream.rs> - Bojan Vitnik (@bvitnik) <bvitnik@mainstream.rs>
notes: notes:
- Minimal supported version of XenServer is 5.6. - Minimal supported version of XenServer is 5.6.
- Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0. - Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0.
- 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside - 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside Citrix
Citrix Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the XenAPI.py file from the SDK to your Python site-packages on your Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the C(XenAPI.py) file from the SDK to your Python site-packages on your Ansible
Ansible Control Node to use it. Latest version of the library can also be acquired from GitHub: Control Node to use it. Latest version of the library can also be acquired from GitHub:
U(https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI/XenAPI.py)' U(https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI/XenAPI.py).'
- 'If no scheme is specified in O(hostname), module defaults to C(http://) because C(https://) is problematic in most setups. Make sure you are - 'If no scheme is specified in O(hostname), module defaults to C(http://) because C(https://) is problematic in most setups. Make sure you
accessing XenServer host in trusted environment or use C(https://) scheme explicitly.' are accessing XenServer host in trusted environment or use C(https://) scheme explicitly.'
- 'To use C(https://) scheme for O(hostname) you have to either import host certificate to your OS certificate store or use O(validate_certs=false) - 'To use C(https://) scheme for O(hostname) you have to either import host certificate to your OS certificate store or use O(validate_certs=false)
which requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.' which requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.'
- 'Network configuration inside a guest OS, by using O(networks[].type), O(networks[].ip), O(networks[].gateway) etc. parameters, is supported on - 'Network configuration inside a guest OS, by using O(networks[].type), O(networks[].ip), O(networks[].gateway) etc. parameters, is supported
XenServer 7.0 or newer for Windows guests by using official XenServer Guest agent support for network configuration. The module will try to on XenServer 7.0 or newer for Windows guests by using official XenServer Guest agent support for network configuration. The module will try
detect if such support is available and utilize it, else it will use a custom method of configuration via xenstore. Since XenServer Guest to detect if such support is available and utilize it, else it will use a custom method of configuration via xenstore. Since XenServer Guest
agent only support None and Static types of network configuration, where None means DHCP configured interface, O(networks[].type) and O(networks[].type6) agent only support None and Static types of network configuration, where None means DHCP configured interface, O(networks[].type) and O(networks[].type6)
values V(none) and V(dhcp) have same effect. More info here: values V(none) and V(dhcp) have same effect. More info here:
U(https://www.citrix.com/community/citrix-developer/citrix-hypervisor-developer/citrix-hypervisor-developing-products/citrix-hypervisor-staticip.html)' U(https://www.citrix.com/community/citrix-developer/citrix-hypervisor-developer/citrix-hypervisor-developing-products/citrix-hypervisor-staticip.html).'
- 'On platforms without official support for network configuration inside a guest OS, network parameters will be written to xenstore - 'On platforms without official support for network configuration inside a guest OS, network parameters will be written to xenstore
C(vm-data/networks/<vif_device>) key. Parameters can be inspected by using C(xenstore ls) and C(xenstore read) tools on \*nix guests or through C(vm-data/networks/<vif_device>) key. Parameters can be inspected by using C(xenstore ls) and C(xenstore read) tools on \*nix guests or through WMI
WMI interface on Windows guests. They can also be found in VM facts C(instance.xenstore_data) key as returned by the module. It is up to the user interface on Windows guests.
to implement a boot time scripts or custom agent that will read the parameters from xenstore and configure network with given parameters. They can also be found in VM facts C(instance.xenstore_data) key as returned by the module. It is up to the user to implement a boot time
Take note that for xenstore data to become available inside a guest, a VM restart is needed hence module will require VM restart if any scripts or custom agent that will read the parameters from xenstore and configure network with given parameters. Take note that for xenstore
parameter is changed. This is a limitation of XenAPI and xenstore. Considering these limitations, network configuration through xenstore is most data to become available inside a guest, a VM restart is needed hence module will require VM restart if any parameter is changed. This is
useful for bootstrapping newly deployed VMs, much less for reconfiguring existing ones. More info here: a limitation of XenAPI and xenstore. Considering these limitations, network configuration through xenstore is most useful for bootstrapping
U(https://support.citrix.com/article/CTX226713)' newly deployed VMs, much less for reconfiguring existing ones. More info here: U(https://support.citrix.com/article/CTX226713).'
requirements: requirements:
- XenAPI - XenAPI
attributes: attributes:
check_mode: check_mode:
support: full support: full
@ -60,7 +58,7 @@ options:
- If O(state) is set to V(poweredon) and VM does not exist, then VM is deployed with given parameters and powered on automatically. - If O(state) is set to V(poweredon) and VM does not exist, then VM is deployed with given parameters and powered on automatically.
type: str type: str
default: present default: present
choices: [ present, absent, poweredon ] choices: [present, absent, poweredon]
name: name:
description: description:
- Name of the VM to work with. - Name of the VM to work with.
@ -68,7 +66,7 @@ options:
- In case of multiple VMs with same name, use O(uuid) to uniquely specify VM to manage. - In case of multiple VMs with same name, use O(uuid) to uniquely specify VM to manage.
- This parameter is case sensitive. - This parameter is case sensitive.
type: str type: str
aliases: [ name_label ] aliases: [name_label]
name_desc: name_desc:
description: description:
- VM description. - VM description.
@ -82,12 +80,13 @@ options:
template: template:
description: description:
- Name of a template, an existing VM (must be shut down) or a snapshot that should be used to create VM. - Name of a template, an existing VM (must be shut down) or a snapshot that should be used to create VM.
- Templates/VMs/snapshots on XenServer do not necessarily have unique names. The module will fail if multiple templates with same name are found. - Templates/VMs/snapshots on XenServer do not necessarily have unique names. The module will fail if multiple templates with same name are
found.
- In case of multiple templates/VMs/snapshots with same name, use O(template_uuid) to uniquely specify source template. - In case of multiple templates/VMs/snapshots with same name, use O(template_uuid) to uniquely specify source template.
- If VM already exists, this setting will be ignored. - If VM already exists, this setting will be ignored.
- This parameter is case sensitive. - This parameter is case sensitive.
type: str type: str
aliases: [ template_src ] aliases: [template_src]
template_uuid: template_uuid:
description: description:
- UUID of a template, an existing VM or a snapshot that should be used to create VM. - UUID of a template, an existing VM or a snapshot that should be used to create VM.
@ -131,7 +130,7 @@ options:
- VM needs to be shut down to reconfigure disk size. - VM needs to be shut down to reconfigure disk size.
type: list type: list
elements: dict elements: dict
aliases: [ disk ] aliases: [disk]
suboptions: suboptions:
size: size:
description: description:
@ -162,7 +161,7 @@ options:
description: description:
- Disk name. - Disk name.
type: str type: str
aliases: [ name_label ] aliases: [name_label]
name_desc: name_desc:
description: description:
- Disk description. - Disk description.
@ -185,7 +184,7 @@ options:
description: description:
- The type of CD-ROM. With V(none) the CD-ROM device will be present but empty. - The type of CD-ROM. With V(none) the CD-ROM device will be present but empty.
type: str type: str
choices: [ none, iso ] choices: [none, iso]
iso_name: iso_name:
description: description:
- 'The file name of an ISO image from one of the XenServer ISO Libraries (implies O(cdrom.type=iso)).' - 'The file name of an ISO image from one of the XenServer ISO Libraries (implies O(cdrom.type=iso)).'
@ -198,13 +197,13 @@ options:
- Name is required for new NICs. Other parameters are optional in all cases. - Name is required for new NICs. Other parameters are optional in all cases.
type: list type: list
elements: dict elements: dict
aliases: [ network ] aliases: [network]
suboptions: suboptions:
name: name:
description: description:
- Name of a XenServer network to attach the network interface to. - Name of a XenServer network to attach the network interface to.
type: str type: str
aliases: [ name_label ] aliases: [name_label]
mac: mac:
description: description:
- Customize MAC address of the interface. - Customize MAC address of the interface.
@ -214,10 +213,11 @@ options:
- Type of IPv4 assignment. Value V(none) means whatever is default for OS. - Type of IPv4 assignment. Value V(none) means whatever is default for OS.
- On some operating systems it could be DHCP configured (e.g. Windows) or unconfigured interface (e.g. Linux). - On some operating systems it could be DHCP configured (e.g. Windows) or unconfigured interface (e.g. Linux).
type: str type: str
choices: [ none, dhcp, static ] choices: [none, dhcp, static]
ip: ip:
description: description:
- 'Static IPv4 address (implies O(networks[].type=static)). Can include prefix in format C(<IPv4 address>/<prefix>) instead of using C(netmask).' - Static IPv4 address (implies O(networks[].type=static)). Can include prefix in format C(<IPv4 address>/<prefix>) instead of using
C(netmask).
type: str type: str
netmask: netmask:
description: description:
@ -231,7 +231,7 @@ options:
description: description:
- Type of IPv6 assignment. Value V(none) means whatever is default for OS. - Type of IPv6 assignment. Value V(none) means whatever is default for OS.
type: str type: str
choices: [ none, dhcp, static ] choices: [none, dhcp, static]
ip6: ip6:
description: description:
- 'Static IPv6 address (implies O(networks[].type6=static)) with prefix in format C(<IPv6 address>/<prefix>).' - 'Static IPv6 address (implies O(networks[].type6=static)) with prefix in format C(<IPv6 address>/<prefix>).'
@ -248,7 +248,7 @@ options:
custom_params: custom_params:
description: description:
- Define a list of custom VM params to set on VM. - Define a list of custom VM params to set on VM.
- Useful for advanced users familiar with managing VM params through xe CLI. - Useful for advanced users familiar with managing VM params through C(xe) CLI.
- A custom value object takes two fields O(custom_params[].key) and O(custom_params[].value) (see example below). - A custom value object takes two fields O(custom_params[].key) and O(custom_params[].value) (see example below).
type: list type: list
elements: dict elements: dict
@ -289,12 +289,11 @@ options:
type: bool type: bool
default: false default: false
extends_documentation_fragment: extends_documentation_fragment:
- community.general.xenserver.documentation - community.general.xenserver.documentation
- community.general.attributes - community.general.attributes
"""
''' EXAMPLES = r"""
EXAMPLES = r'''
- name: Create a VM from a template - name: Create a VM from a template
community.general.xenserver_guest: community.general.xenserver_guest:
hostname: "{{ xenserver_hostname }}" hostname: "{{ xenserver_hostname }}"
@ -366,7 +365,7 @@ EXAMPLES = r'''
state: present state: present
custom_params: custom_params:
- key: HVM_boot_params - key: HVM_boot_params
value: { "order": "ndc" } value: {"order": "ndc"}
delegate_to: localhost delegate_to: localhost
- name: Customize network parameters - name: Customize network parameters
@ -381,11 +380,11 @@ EXAMPLES = r'''
gateway: 192.168.1.1 gateway: 192.168.1.1
- type: dhcp - type: dhcp
delegate_to: localhost delegate_to: localhost
''' """
RETURN = r''' RETURN = r"""
instance: instance:
description: Metadata about the VM description: Metadata about the VM.
returned: always returned: always
type: dict type: dict
sample: { sample: {
@ -471,7 +470,7 @@ instance:
} }
} }
changes: changes:
description: Detected or made changes to VM description: Detected or made changes to VM.
returned: always returned: always
type: list type: list
sample: [ sample: [
@ -523,7 +522,7 @@ changes:
}, },
"need_poweredoff" "need_poweredoff"
] ]
''' """
import re import re

48
plugins/modules/xenserver_guest_info.py
View File

@ -8,27 +8,25 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r''' DOCUMENTATION = r"""
---
module: xenserver_guest_info module: xenserver_guest_info
short_description: Gathers information for virtual machines running on Citrix Hypervisor/XenServer host or pool short_description: Gathers information for virtual machines running on Citrix Hypervisor/XenServer host or pool
description: > description: This module can be used to gather essential VM facts.
This module can be used to gather essential VM facts.
author: author:
- Bojan Vitnik (@bvitnik) <bvitnik@mainstream.rs> - Bojan Vitnik (@bvitnik) <bvitnik@mainstream.rs>
notes: notes:
- Minimal supported version of XenServer is 5.6. - Minimal supported version of XenServer is 5.6.
- Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0. - Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0.
- 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside - 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside Citrix
Citrix Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the XenAPI.py file from the SDK to your Python site-packages on your Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the C(XenAPI.py) file from the SDK to your Python site-packages on your Ansible
Ansible Control Node to use it. Latest version of the library can also be acquired from GitHub: Control Node to use it. Latest version of the library can also be acquired from GitHub:
U(https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI/XenAPI.py)' U(https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI/XenAPI.py)'
- 'If no scheme is specified in C(hostname), module defaults to C(http://) because C(https://) is problematic in most setups. Make sure you are - 'If no scheme is specified in C(hostname), module defaults to C(http://) because C(https://) is problematic in most setups. Make sure you
accessing XenServer host in trusted environment or use C(https://) scheme explicitly.' are accessing XenServer host in trusted environment or use C(https://) scheme explicitly.'
- 'To use C(https://) scheme for C(hostname) you have to either import host certificate to your OS certificate store or use C(validate_certs: no) - 'To use C(https://) scheme for C(hostname) you have to either import host certificate to your OS certificate store or use O(validate_certs=no) which
which requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.' requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.'
requirements: requirements:
- XenAPI - XenAPI
options: options:
name: name:
description: description:
@ -37,19 +35,19 @@ options:
- In case of multiple VMs with same name, use O(uuid) to uniquely specify VM to manage. - In case of multiple VMs with same name, use O(uuid) to uniquely specify VM to manage.
- This parameter is case sensitive. - This parameter is case sensitive.
type: str type: str
aliases: [ name_label ] aliases: [name_label]
uuid: uuid:
description: description:
- UUID of the VM to gather fact of. This is XenServer's unique identifier. - UUID of the VM to gather fact of. This is XenServer's unique identifier.
- It is required if name is not unique. - It is required if name is not unique.
type: str type: str
extends_documentation_fragment: extends_documentation_fragment:
- community.general.xenserver.documentation - community.general.xenserver.documentation
- community.general.attributes - community.general.attributes
- community.general.attributes.info_module - community.general.attributes.info_module
''' """
EXAMPLES = r''' EXAMPLES = r"""
- name: Gather facts - name: Gather facts
community.general.xenserver_guest_info: community.general.xenserver_guest_info:
hostname: "{{ xenserver_hostname }}" hostname: "{{ xenserver_hostname }}"
@ -58,11 +56,11 @@ EXAMPLES = r'''
name: testvm_11 name: testvm_11
delegate_to: localhost delegate_to: localhost
register: facts register: facts
''' """
RETURN = r''' RETURN = r"""
instance: instance:
description: Metadata about the VM description: Metadata about the VM.
returned: always returned: always
type: dict type: dict
sample: { sample: {
@ -147,7 +145,7 @@ instance:
"vm-data": "" "vm-data": ""
} }
} }
''' """
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule

51
plugins/modules/xenserver_guest_powerstate.py
View File

@ -8,27 +8,25 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r''' DOCUMENTATION = r"""
---
module: xenserver_guest_powerstate module: xenserver_guest_powerstate
short_description: Manages power states of virtual machines running on Citrix Hypervisor/XenServer host or pool short_description: Manages power states of virtual machines running on Citrix Hypervisor/XenServer host or pool
description: > description: This module can be used to power on, power off, restart or suspend virtual machine and gracefully reboot or shutdown guest OS of virtual machine.
This module can be used to power on, power off, restart or suspend virtual machine and gracefully reboot or shutdown guest OS of virtual machine.
author: author:
- Bojan Vitnik (@bvitnik) <bvitnik@mainstream.rs> - Bojan Vitnik (@bvitnik) <bvitnik@mainstream.rs>
notes: notes:
- Minimal supported version of XenServer is 5.6. - Minimal supported version of XenServer is 5.6.
- Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0. - Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0.
- 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside - 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside Citrix
Citrix Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the XenAPI.py file from the SDK to your Python site-packages on your Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the C(XenAPI.py) file from the SDK to your Python site-packages on your Ansible
Ansible Control Node to use it. Latest version of the library can also be acquired from GitHub: Control Node to use it. Latest version of the library can also be acquired from GitHub:
U(https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI/XenAPI.py)' U(https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI/XenAPI.py).'
- 'If no scheme is specified in C(hostname), module defaults to C(http://) because C(https://) is problematic in most setups. Make sure you are - 'If no scheme is specified in C(hostname), module defaults to C(http://) because C(https://) is problematic in most setups. Make sure you
accessing XenServer host in trusted environment or use C(https://) scheme explicitly.' are accessing XenServer host in trusted environment or use C(https://) scheme explicitly.'
- 'To use C(https://) scheme for C(hostname) you have to either import host certificate to your OS certificate store or use C(validate_certs: no) - 'To use C(https://) scheme for C(hostname) you have to either import host certificate to your OS certificate store or use C(validate_certs:
which requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.' no) which requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.'
requirements: requirements:
- XenAPI - XenAPI
attributes: attributes:
check_mode: check_mode:
support: full support: full
@ -42,7 +40,7 @@ options:
- If O(state) is set to V(present), then VM is just checked for existence and facts are returned. - If O(state) is set to V(present), then VM is just checked for existence and facts are returned.
type: str type: str
default: present default: present
choices: [ powered-on, powered-off, restarted, shutdown-guest, reboot-guest, suspended, present ] choices: [powered-on, powered-off, restarted, shutdown-guest, reboot-guest, suspended, present]
name: name:
description: description:
- Name of the VM to manage. - Name of the VM to manage.
@ -50,7 +48,7 @@ options:
- In case of multiple VMs with same name, use O(uuid) to uniquely specify VM to manage. - In case of multiple VMs with same name, use O(uuid) to uniquely specify VM to manage.
- This parameter is case sensitive. - This parameter is case sensitive.
type: str type: str
aliases: [ name_label ] aliases: [name_label]
uuid: uuid:
description: description:
- UUID of the VM to manage if known. This is XenServer's unique identifier. - UUID of the VM to manage if known. This is XenServer's unique identifier.
@ -70,12 +68,11 @@ options:
type: int type: int
default: 0 default: 0
extends_documentation_fragment: extends_documentation_fragment:
- community.general.xenserver.documentation - community.general.xenserver.documentation
- community.general.attributes - community.general.attributes
"""
''' EXAMPLES = r"""
EXAMPLES = r'''
- name: Power on VM - name: Power on VM
community.general.xenserver_guest_powerstate: community.general.xenserver_guest_powerstate:
hostname: "{{ xenserver_hostname }}" hostname: "{{ xenserver_hostname }}"
@ -85,11 +82,11 @@ EXAMPLES = r'''
state: powered-on state: powered-on
delegate_to: localhost delegate_to: localhost
register: facts register: facts
''' """
RETURN = r''' RETURN = r"""
instance: instance:
description: Metadata about the VM description: Metadata about the VM.
returned: always returned: always
type: dict type: dict
sample: { sample: {
@ -174,7 +171,7 @@ instance:
"vm-data": "" "vm-data": ""
} }
} }
''' """
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule

35
plugins/modules/xfconf.py
View File

@ -8,26 +8,25 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = """ DOCUMENTATION = r"""
---
module: xfconf module: xfconf
author: author:
- "Joseph Benden (@jbenden)" - "Joseph Benden (@jbenden)"
- "Alexei Znamensky (@russoz)" - "Alexei Znamensky (@russoz)"
short_description: Edit XFCE4 Configurations short_description: Edit XFCE4 Configurations
description: description:
- This module allows for the manipulation of Xfce 4 Configuration with the help of C(xfconf-query). - This module allows for the manipulation of Xfce 4 Configuration with the help of C(xfconf-query).
seealso: seealso:
- name: xfconf-query(1) man page - name: xfconf-query(1) man page
description: Manual page of the C(xfconf-query) tool at the XFCE documentation site. description: Manual page of the C(xfconf-query) tool at the XFCE documentation site.
link: 'https://docs.xfce.org/xfce/xfconf/xfconf-query' link: 'https://docs.xfce.org/xfce/xfconf/xfconf-query'
- name: xfconf - Configuration Storage System - name: xfconf - Configuration Storage System
description: XFCE documentation for the Xfconf configuration system. description: XFCE documentation for the Xfconf configuration system.
link: 'https://docs.xfce.org/xfce/xfconf/start' link: 'https://docs.xfce.org/xfce/xfconf/start'
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
@ -56,10 +55,10 @@ options:
description: description:
- The type of value being set. - The type of value being set.
- When providing more than one O(value_type), the length of the list must be equal to the length of O(value). - When providing more than one O(value_type), the length of the list must be equal to the length of O(value).
- If only one O(value_type) is provided, but O(value) contains more than on element, that O(value_type) will be applied to all elements of - If only one O(value_type) is provided, but O(value) contains more than on element, that O(value_type) will be applied to all elements
O(value). of O(value).
- If the O(property) being set is an array and it can possibly have only one element in the array, then O(force_array=true) must be used to - If the O(property) being set is an array and it can possibly have only one element in the array, then O(force_array=true) must be used
ensure that C(xfconf-query) will interpret the value as an array rather than a scalar. to ensure that C(xfconf-query) will interpret the value as an array rather than a scalar.
- Support for V(uchar), V(char), V(uint64), and V(int64) has been added in community.general 4.8.0. - Support for V(uchar), V(char), V(uint64), and V(int64) has been added in community.general 4.8.0.
type: list type: list
elements: str elements: str
@ -80,8 +79,7 @@ options:
version_added: 1.0.0 version_added: 1.0.0
""" """
EXAMPLES = """ EXAMPLES = r"""
---
- name: Change the DPI to "192" - name: Change the DPI to "192"
xfconf: xfconf:
channel: "xsettings" channel: "xsettings"
@ -105,15 +103,14 @@ EXAMPLES = """
force_array: true force_array: true
""" """
RETURN = """ RETURN = r"""
---
channel: channel:
description: The channel specified in the module parameters description: The channel specified in the module parameters.
returned: success returned: success
type: str type: str
sample: "xsettings" sample: "xsettings"
property: property:
description: The property specified in the module parameters description: The property specified in the module parameters.
returned: success returned: success
type: str type: str
sample: "/Xft/DPI" sample: "/Xft/DPI"
@ -130,7 +127,7 @@ value:
- This is a string or a list of strings. - This is a string or a list of strings.
returned: success returned: success
type: any type: any
sample: '"192" or ["orange", "yellow", "violet"]' sample: "'192' or ['orange', 'yellow', 'violet']"
previous_value: previous_value:
description: description:
- The value of the preference key before executing the module. Either a single string value or a list of strings for array types. - The value of the preference key before executing the module. Either a single string value or a list of strings for array types.

29
plugins/modules/xfconf_info.py
View File

@ -7,18 +7,17 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = """ DOCUMENTATION = r"""
---
module: xfconf_info module: xfconf_info
author: author:
- "Alexei Znamensky (@russoz)" - "Alexei Znamensky (@russoz)"
short_description: Retrieve XFCE4 configurations short_description: Retrieve XFCE4 configurations
version_added: 3.5.0 version_added: 3.5.0
description: description:
- This module allows retrieving Xfce 4 configurations with the help of C(xfconf-query). - This module allows retrieving Xfce 4 configurations with the help of C(xfconf-query).
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
- community.general.attributes.info_module - community.general.attributes.info_module
attributes: attributes:
check_mode: check_mode:
version_added: 3.3.0 version_added: 3.3.0
@ -26,26 +25,21 @@ attributes:
options: options:
channel: channel:
description: description:
- > - "A Xfconf preference channel is a top-level tree key, inside of the Xfconf repository that corresponds to the location for which all application
A Xfconf preference channel is a top-level tree key, inside of the properties/keys are stored."
Xfconf repository that corresponds to the location for which all
application properties/keys are stored.
- If not provided, the module will list all available channels. - If not provided, the module will list all available channels.
type: str type: str
property: property:
description: description:
- > - "A Xfce preference key is an element in the Xfconf repository that corresponds to an application preference."
A Xfce preference key is an element in the Xfconf repository
that corresponds to an application preference.
- If provided, then O(channel) is required. - If provided, then O(channel) is required.
- If not provided and a O(channel) is provided, then the module will list all available properties in that O(channel). - If not provided and a O(channel) is provided, then the module will list all available properties in that O(channel).
type: str type: str
notes: notes:
- See man xfconf-query(1) for more details. - See man xfconf-query(1) for more details.
""" """
EXAMPLES = """ EXAMPLES = r"""
---
- name: Get list of all available channels - name: Get list of all available channels
community.general.xfconf_info: {} community.general.xfconf_info: {}
register: result register: result
@ -68,8 +62,7 @@ EXAMPLES = """
register: result register: result
""" """
RETURN = """ RETURN = r"""
---
channels: channels:
description: description:
- List of available channels. - List of available channels.

14
plugins/modules/xfs_quota.py
View File

@ -12,7 +12,6 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r""" DOCUMENTATION = r"""
---
module: xfs_quota module: xfs_quota
short_description: Manage quotas on XFS filesystems short_description: Manage quotas on XFS filesystems
description: description:
@ -109,37 +108,36 @@ EXAMPLES = r"""
mountpoint: /home mountpoint: /home
isoft: 1024 isoft: 1024
ihard: 2048 ihard: 2048
""" """
RETURN = r""" RETURN = r"""
bhard: bhard:
description: the current bhard setting in bytes description: The current C(bhard) setting in bytes.
returned: always returned: always
type: int type: int
sample: 1024 sample: 1024
bsoft: bsoft:
description: the current bsoft setting in bytes description: The current C(bsoft) setting in bytes.
returned: always returned: always
type: int type: int
sample: 1024 sample: 1024
ihard: ihard:
description: the current ihard setting in bytes description: The current C(ihard) setting in bytes.
returned: always returned: always
type: int type: int
sample: 100 sample: 100
isoft: isoft:
description: the current isoft setting in bytes description: The current C(isoft) setting in bytes.
returned: always returned: always
type: int type: int
sample: 100 sample: 100
rtbhard: rtbhard:
description: the current rtbhard setting in bytes description: The current C(rtbhard) setting in bytes.
returned: always returned: always
type: int type: int
sample: 1024 sample: 1024
rtbsoft: rtbsoft:
description: the current rtbsoft setting in bytes description: The current C(rtbsoft) setting in bytes.
returned: always returned: always
type: int type: int
sample: 1024 sample: 1024

75
plugins/modules/xml.py
View File

@ -11,8 +11,7 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r''' DOCUMENTATION = r"""
---
module: xml module: xml
short_description: Manage bits and pieces of XML files or strings short_description: Manage bits and pieces of XML files or strings
description: description:
@ -31,7 +30,7 @@ options:
- This file must exist ahead of time. - This file must exist ahead of time.
- This parameter is required, unless O(xmlstring) is given. - This parameter is required, unless O(xmlstring) is given.
type: path type: path
aliases: [ dest, file ] aliases: [dest, file]
xmlstring: xmlstring:
description: description:
- A string containing XML on which to operate. - A string containing XML on which to operate.
@ -52,9 +51,9 @@ options:
description: description:
- Set or remove an xpath selection (node(s), attribute(s)). - Set or remove an xpath selection (node(s), attribute(s)).
type: str type: str
choices: [ absent, present ] choices: [absent, present]
default: present default: present
aliases: [ ensure ] aliases: [ensure]
attribute: attribute:
description: description:
- The attribute to select when using parameter O(value). - The attribute to select when using parameter O(value).
@ -70,9 +69,8 @@ options:
add_children: add_children:
description: description:
- Add additional child-element(s) to a selected element for a given O(xpath). - Add additional child-element(s) to a selected element for a given O(xpath).
- Child elements must be given in a list and each item may be either a string - Child elements must be given in a list and each item may be either a string (for example C(children=ansible) to add an empty C(<ansible/>)
(for example C(children=ansible) to add an empty C(<ansible/>) child element), child element), or a hash where the key is an element name and the value is the element value.
or a hash where the key is an element name and the value is the element value.
- This parameter requires O(xpath) to be set. - This parameter requires O(xpath) to be set.
type: list type: list
elements: raw elements: raw
@ -106,17 +104,16 @@ options:
- Search for a given O(xpath) and get content. - Search for a given O(xpath) and get content.
- This parameter requires O(xpath) to be set. - This parameter requires O(xpath) to be set.
type: str type: str
choices: [ attribute, text ] choices: [attribute, text]
input_type: input_type:
description: description:
- Type of input for O(add_children) and O(set_children). - Type of input for O(add_children) and O(set_children).
type: str type: str
choices: [ xml, yaml ] choices: [xml, yaml]
default: yaml default: yaml
backup: backup:
description: description:
- Create a backup file including the timestamp information so you can get - Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
the original file back if you somehow clobbered it incorrectly.
type: bool type: bool
default: false default: false
strip_cdata_tags: strip_cdata_tags:
@ -128,46 +125,44 @@ options:
insertbefore: insertbefore:
description: description:
- Add additional child-element(s) before the first selected element for a given O(xpath). - Add additional child-element(s) before the first selected element for a given O(xpath).
- Child elements must be given in a list and each item may be either a string - Child elements must be given in a list and each item may be either a string (for example C(children=ansible) to add an empty C(<ansible/>)
(for example C(children=ansible) to add an empty C(<ansible/>) child element), child element), or a hash where the key is an element name and the value is the element value.
or a hash where the key is an element name and the value is the element value.
- This parameter requires O(xpath) to be set. - This parameter requires O(xpath) to be set.
type: bool type: bool
default: false default: false
insertafter: insertafter:
description: description:
- Add additional child-element(s) after the last selected element for a given O(xpath). - Add additional child-element(s) after the last selected element for a given O(xpath).
- Child elements must be given in a list and each item may be either a string - Child elements must be given in a list and each item may be either a string (for example C(children=ansible) to add an empty C(<ansible/>)
(for example C(children=ansible) to add an empty C(<ansible/>) child element), child element), or a hash where the key is an element name and the value is the element value.
or a hash where the key is an element name and the value is the element value.
- This parameter requires O(xpath) to be set. - This parameter requires O(xpath) to be set.
type: bool type: bool
default: false default: false
requirements: requirements:
- lxml >= 2.3.0 - lxml >= 2.3.0
notes: notes:
- Use the C(--check) and C(--diff) options when testing your expressions. - Use the C(--check) and C(--diff) options when testing your expressions.
- The diff output is automatically pretty-printed, so may not reflect the actual file content, only the file structure. - The diff output is automatically pretty-printed, so may not reflect the actual file content, only the file structure.
- This module does not handle complicated xpath expressions, so limit xpath selectors to simple expressions. - This module does not handle complicated xpath expressions, so limit xpath selectors to simple expressions.
- Beware that in case your XML elements are namespaced, you need to use the O(namespaces) parameter, see the examples. - Beware that in case your XML elements are namespaced, you need to use the O(namespaces) parameter, see the examples.
- Namespaces prefix should be used for all children of an element where namespace is defined, unless another namespace is defined for them. - Namespaces prefix should be used for all children of an element where namespace is defined, unless another namespace is defined for them.
seealso: seealso:
- name: Xml module development community wiki - name: XML module development community wiki (archived)
description: More information related to the development of this xml module. description: More information related to the development of this xml module.
link: https://github.com/ansible/community/wiki/Module:-xml link: https://github.com/ansible/community/wiki/Module:-xml
- name: Introduction to XPath - name: Introduction to XPath
description: A brief tutorial on XPath (w3schools.com). description: A brief tutorial on XPath (w3schools.com).
link: https://www.w3schools.com/xml/xpath_intro.asp link: https://www.w3schools.com/xml/xpath_intro.asp
- name: XPath Reference document - name: XPath Reference document
description: The reference documentation on XSLT/XPath (developer.mozilla.org). description: The reference documentation on XSLT/XPath (developer.mozilla.org).
link: https://developer.mozilla.org/en-US/docs/Web/XPath link: https://developer.mozilla.org/en-US/docs/Web/XPath
author: author:
- Tim Bielawa (@tbielawa) - Tim Bielawa (@tbielawa)
- Magnus Hedemark (@magnus919) - Magnus Hedemark (@magnus919)
- Dag Wieers (@dagwieers) - Dag Wieers (@dagwieers)
''' """
EXAMPLES = r''' EXAMPLES = r"""
# Consider the following XML file: # Consider the following XML file:
# #
# <business type="bar"> # <business type="bar">
@ -327,28 +322,28 @@ EXAMPLES = r'''
path: bar.xml path: bar.xml
xpath: /config/element[@name='test1'] xpath: /config/element[@name='test1']
state: absent state: absent
''' """
RETURN = r''' RETURN = r"""
actions: actions:
description: A dictionary with the original xpath, namespaces and state. description: A dictionary with the original xpath, namespaces and state.
type: dict type: dict
returned: success returned: success
sample: {xpath: xpath, namespaces: [namespace1, namespace2], state=present} sample: {xpath: xpath, namespaces: [namespace1, namespace2], state: present}
backup_file: backup_file:
description: The name of the backup file that was created description: The name of the backup file that was created.
type: str type: str
returned: when O(backup=true) returned: when O(backup=true)
sample: /path/to/file.xml.1942.2017-08-24@14:16:01~ sample: /path/to/file.xml.1942.2017-08-24@14:16:01~
count: count:
description: The count of xpath matches. description: The count of xpath matches.
type: int type: int
returned: when parameter 'count' is set returned: when parameter O(count) is set
sample: 2 sample: 2
matches: matches:
description: The xpath matches found. description: The xpath matches found.
type: list type: list
returned: when parameter 'print_match' is set returned: when parameter O(print_match) is set
msg: msg:
description: A message related to the performed action(s). description: A message related to the performed action(s).
type: str type: str
@ -356,8 +351,8 @@ msg:
xmlstring: xmlstring:
description: An XML string of the resulting output. description: An XML string of the resulting output.
type: str type: str
returned: when parameter 'xmlstring' is set returned: when parameter O(xmlstring) is set
''' """
import copy import copy
import json import json