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

33
plugins/modules/xattr.py
View File

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

158
plugins/modules/xbps.py
View File

@ -10,86 +10,78 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: xbps
short_description: Manage packages with XBPS
description:
- Manage packages with the XBPS package manager.
- Manage packages with the XBPS package manager.
author:
- "Dino Occhialini (@dinoocch)"
- "Michael Aldridge (@the-maldridge)"
- "Dino Occhialini (@dinoocch)"
- "Michael Aldridge (@the-maldridge)"
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:
description:
- Name of the package to install, upgrade, or remove.
aliases: [pkg,package]
type: list
elements: str
state:
description:
- Desired state of the package.
default: "present"
choices: ["present", "absent", "latest", "installed", "removed"]
type: str
recurse:
description:
- When removing a package, also remove its dependencies, provided
that they are not required by other packages and were not
explicitly installed by a user.
type: bool
default: false
update_cache:
description:
- Whether or not to refresh the master package lists. This can be
run as part of a package installation or as a separate step.
type: bool
default: true
upgrade:
description:
- Whether or not to upgrade whole system
type: bool
default: false
upgrade_xbps:
description:
- Whether or not to upgrade the xbps package when necessary.
Before installing new packages,
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
default: true
version_added: '0.2.0'
root:
description:
- The full path for the target root directory.
type: path
version_added: '10.2.0'
repositories:
description:
- 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 or a path for local repositories.
type: list
elements: str
version_added: '10.2.0'
accept_pubkey:
description:
- Whether or not repository signing keys should be automatically accepted.
type: bool
default: false
version_added: '10.2.0'
'''
name:
description:
- Name of the package to install, upgrade, or remove.
aliases: [pkg, package]
type: list
elements: str
state:
description:
- Desired state of the package.
default: "present"
choices: ["present", "absent", "latest", "installed", "removed"]
type: str
recurse:
description:
- When removing a package, also remove its dependencies, provided that they are not required by other packages and were not explicitly installed
by a user.
type: bool
default: false
update_cache:
description:
- Whether or not to refresh the master package lists. This can be run as part of a package installation or as a separate step.
type: bool
default: true
upgrade:
description:
- Whether or not to upgrade whole system.
type: bool
default: false
upgrade_xbps:
description:
- Whether or not to upgrade the xbps package when necessary. Before installing new packages, 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
default: true
version_added: '0.2.0'
root:
description:
- The full path for the target root directory.
type: path
version_added: '10.2.0'
repositories:
description:
- 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
or a path for local repositories.
type: list
elements: str
version_added: '10.2.0'
accept_pubkey:
description:
- Whether or not repository signing keys should be automatically accepted.
type: bool
default: false
version_added: '10.2.0'
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Install package foo (automatically updating the xbps package if needed)
community.general.xbps:
name: foo
@ -151,20 +143,20 @@ EXAMPLES = '''
state: present
repositories: https://repo-default.voidlinux.org/current
root: /mnt
'''
"""
RETURN = '''
RETURN = r"""
msg:
description: Message about results
returned: success
type: str
sample: "System Upgraded"
description: Message about results.
returned: success
type: str
sample: "System Upgraded"
packages:
description: Packages that are affected/would be affected
type: list
sample: ["ansible"]
returned: success
'''
description: Packages that are affected/would be affected.
type: list
sample: ["ansible"]
returned: success
"""
import os

325
plugins/modules/xcc_redfish_command.py
View File

@ -8,14 +8,13 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: xcc_redfish_command
short_description: Manages Lenovo Out-Of-Band controllers using Redfish APIs
version_added: 2.4.0
description:
- Builds Redfish URIs locally and sends them to remote OOB controllers to
perform an action or get information back or update a configuration attribute.
- Builds Redfish URIs locally and sends them to remote OOB controllers to perform an action or get information back or update a configuration
attribute.
- Manages virtual media.
- Supports getting information back via GET method.
- Supports updating a configuration attribute via PATCH method.
@ -54,7 +53,7 @@ options:
type: str
auth_token:
description:
- Security token for authentication with OOB controller
- Security token for authentication with OOB controller.
type: str
timeout:
description:
@ -120,181 +119,181 @@ options:
type: dict
author: "Yuyan Pan (@panyy3)"
'''
"""
EXAMPLES = '''
- name: Insert Virtual Media
community.general.xcc_redfish_command:
category: Manager
command: VirtualMediaInsert
baseuri: "{{ baseuri }}"
username: "{{ username }}"
password: "{{ password }}"
virtual_media:
image_url: "http://example.com/images/SomeLinux-current.iso"
media_types:
- CD
- DVD
resource_id: "1"
EXAMPLES = r"""
- name: Insert Virtual Media
community.general.xcc_redfish_command:
category: Manager
command: VirtualMediaInsert
baseuri: "{{ baseuri }}"
username: "{{ username }}"
password: "{{ password }}"
virtual_media:
image_url: "http://example.com/images/SomeLinux-current.iso"
media_types:
- CD
- DVD
resource_id: "1"
- name: Eject Virtual Media
community.general.xcc_redfish_command:
category: Manager
command: VirtualMediaEject
baseuri: "{{ baseuri }}"
username: "{{ username }}"
password: "{{ password }}"
virtual_media:
image_url: "http://example.com/images/SomeLinux-current.iso"
resource_id: "1"
- name: Eject Virtual Media
community.general.xcc_redfish_command:
category: Manager
command: VirtualMediaEject
baseuri: "{{ baseuri }}"
username: "{{ username }}"
password: "{{ password }}"
virtual_media:
image_url: "http://example.com/images/SomeLinux-current.iso"
resource_id: "1"
- name: Eject all Virtual Media
community.general.xcc_redfish_command:
category: Manager
command: VirtualMediaEject
baseuri: "{{ baseuri }}"
username: "{{ username }}"
password: "{{ password }}"
resource_id: "1"
- name: Eject all Virtual Media
community.general.xcc_redfish_command:
category: Manager
command: VirtualMediaEject
baseuri: "{{ baseuri }}"
username: "{{ username }}"
password: "{{ password }}"
resource_id: "1"
- name: Get ComputeSystem Oem property SystemStatus via GetResource command
community.general.xcc_redfish_command:
category: Raw
command: GetResource
baseuri: "{{ baseuri }}"
username: "{{ username }}"
password: "{{ password }}"
resource_uri: "/redfish/v1/Systems/1"
register: result
- ansible.builtin.debug:
msg: "{{ result.redfish_facts.data.Oem.Lenovo.SystemStatus }}"
- name: Get ComputeSystem Oem property SystemStatus via GetResource command
community.general.xcc_redfish_command:
category: Raw
command: GetResource
baseuri: "{{ baseuri }}"
username: "{{ username }}"
password: "{{ password }}"
resource_uri: "/redfish/v1/Systems/1"
register: result
- ansible.builtin.debug:
msg: "{{ result.redfish_facts.data.Oem.Lenovo.SystemStatus }}"
- name: Get Oem DNS setting via GetResource command
community.general.xcc_redfish_command:
category: Raw
command: GetResource
baseuri: "{{ baseuri }}"
username: "{{ username }}"
password: "{{ password }}"
resource_uri: "/redfish/v1/Managers/1/NetworkProtocol/Oem/Lenovo/DNS"
register: result
- name: Get Oem DNS setting via GetResource command
community.general.xcc_redfish_command:
category: Raw
command: GetResource
baseuri: "{{ baseuri }}"
username: "{{ username }}"
password: "{{ password }}"
resource_uri: "/redfish/v1/Managers/1/NetworkProtocol/Oem/Lenovo/DNS"
register: result
- name: Print fetched information
ansible.builtin.debug:
msg: "{{ result.redfish_facts.data }}"
- name: Print fetched information
ansible.builtin.debug:
msg: "{{ result.redfish_facts.data }}"
- name: Get Lenovo FoD key collection resource via GetCollectionResource command
community.general.xcc_redfish_command:
category: Raw
command: GetCollectionResource
baseuri: "{{ baseuri }}"
username: "{{ username }}"
password: "{{ password }}"
resource_uri: "/redfish/v1/Managers/1/Oem/Lenovo/FoD/Keys"
register: result
- name: Get Lenovo FoD key collection resource via GetCollectionResource command
community.general.xcc_redfish_command:
category: Raw
command: GetCollectionResource
baseuri: "{{ baseuri }}"
username: "{{ username }}"
password: "{{ password }}"
resource_uri: "/redfish/v1/Managers/1/Oem/Lenovo/FoD/Keys"
register: result
- name: Print fetched information
ansible.builtin.debug:
msg: "{{ result.redfish_facts.data_list }}"
- name: Print fetched information
ansible.builtin.debug:
msg: "{{ result.redfish_facts.data_list }}"
- name: Update ComputeSystem property AssetTag via PatchResource command
community.general.xcc_redfish_command:
category: Raw
command: PatchResource
baseuri: "{{ baseuri }}"
username: "{{ username }}"
password: "{{ password }}"
resource_uri: "/redfish/v1/Systems/1"
request_body:
AssetTag: "new_asset_tag"
- name: Update ComputeSystem property AssetTag via PatchResource command
community.general.xcc_redfish_command:
category: Raw
command: PatchResource
baseuri: "{{ baseuri }}"
username: "{{ username }}"
password: "{{ password }}"
resource_uri: "/redfish/v1/Systems/1"
request_body:
AssetTag: "new_asset_tag"
- name: Perform BootToBIOSSetup action via PostResource command
community.general.xcc_redfish_command:
category: Raw
command: PostResource
baseuri: "{{ baseuri }}"
username: "{{ username }}"
password: "{{ password }}"
resource_uri: "/redfish/v1/Systems/1/Actions/Oem/LenovoComputerSystem.BootToBIOSSetup"
request_body: {}
- name: Perform BootToBIOSSetup action via PostResource command
community.general.xcc_redfish_command:
category: Raw
command: PostResource
baseuri: "{{ baseuri }}"
username: "{{ username }}"
password: "{{ password }}"
resource_uri: "/redfish/v1/Systems/1/Actions/Oem/LenovoComputerSystem.BootToBIOSSetup"
request_body: {}
- name: Perform SecureBoot.ResetKeys action via PostResource command
community.general.xcc_redfish_command:
category: Raw
command: PostResource
baseuri: "{{ baseuri }}"
username: "{{ username }}"
password: "{{ password }}"
resource_uri: "/redfish/v1/Systems/1/SecureBoot/Actions/SecureBoot.ResetKeys"
request_body:
ResetKeysType: DeleteAllKeys
- name: Perform SecureBoot.ResetKeys action via PostResource command
community.general.xcc_redfish_command:
category: Raw
command: PostResource
baseuri: "{{ baseuri }}"
username: "{{ username }}"
password: "{{ password }}"
resource_uri: "/redfish/v1/Systems/1/SecureBoot/Actions/SecureBoot.ResetKeys"
request_body:
ResetKeysType: DeleteAllKeys
- name: Create session
community.general.redfish_command:
category: Sessions
command: CreateSession
baseuri: "{{ baseuri }}"
username: "{{ username }}"
password: "{{ password }}"
register: result
- name: Create session
community.general.redfish_command:
category: Sessions
command: CreateSession
baseuri: "{{ baseuri }}"
username: "{{ username }}"
password: "{{ password }}"
register: result
- name: Update Manager DateTimeLocalOffset property using security token for auth
community.general.xcc_redfish_command:
category: Raw
command: PatchResource
baseuri: "{{ baseuri }}"
auth_token: "{{ result.session.token }}"
resource_uri: "/redfish/v1/Managers/1"
request_body:
DateTimeLocalOffset: "+08:00"
- name: Update Manager DateTimeLocalOffset property using security token for auth
community.general.xcc_redfish_command:
category: Raw
command: PatchResource
baseuri: "{{ baseuri }}"
auth_token: "{{ result.session.token }}"
resource_uri: "/redfish/v1/Managers/1"
request_body:
DateTimeLocalOffset: "+08:00"
- name: Delete session using security token created by CreateSesssion above
community.general.redfish_command:
category: Sessions
command: DeleteSession
baseuri: "{{ baseuri }}"
auth_token: "{{ result.session.token }}"
session_uri: "{{ result.session.uri }}"
'''
- name: Delete session using security token created by CreateSesssion above
community.general.redfish_command:
category: Sessions
command: DeleteSession
baseuri: "{{ baseuri }}"
auth_token: "{{ result.session.token }}"
session_uri: "{{ result.session.uri }}"
"""
RETURN = '''
RETURN = r"""
msg:
description: A message related to the performed action(s).
returned: when failure or action/update success
type: str
sample: "Action was successful"
description: A message related to the performed action(s).
returned: when failure or action/update success
type: str
sample: "Action was successful"
redfish_facts:
description: Resource content.
returned: when command == GetResource or command == GetCollectionResource
type: dict
sample: '{
"redfish_facts": {
"data": {
"@odata.etag": "\"3179bf00d69f25a8b3c\"",
"@odata.id": "/redfish/v1/Managers/1/NetworkProtocol/Oem/Lenovo/DNS",
"@odata.type": "#LenovoDNS.v1_0_0.LenovoDNS",
"DDNS": [
{
"DDNSEnable": true,
"DomainName": "",
"DomainNameSource": "DHCP"
}
],
"DNSEnable": true,
"Description": "This resource is used to represent a DNS resource for a Redfish implementation.",
"IPv4Address1": "10.103.62.178",
"IPv4Address2": "0.0.0.0",
"IPv4Address3": "0.0.0.0",
"IPv6Address1": "::",
"IPv6Address2": "::",
"IPv6Address3": "::",
"Id": "LenovoDNS",
"PreferredAddresstype": "IPv4"
},
"ret": true
}
}'
'''
description: Resource content.
returned: when command == GetResource or command == GetCollectionResource
type: dict
sample: '{
"redfish_facts": {
"data": {
"@odata.etag": "\"3179bf00d69f25a8b3c\"",
"@odata.id": "/redfish/v1/Managers/1/NetworkProtocol/Oem/Lenovo/DNS",
"@odata.type": "#LenovoDNS.v1_0_0.LenovoDNS",
"DDNS": [
{
"DDNSEnable": true,
"DomainName": "",
"DomainNameSource": "DHCP"
}
],
"DNSEnable": true,
"Description": "This resource is used to represent a DNS resource for a Redfish implementation.",
"IPv4Address1": "10.103.62.178",
"IPv4Address2": "0.0.0.0",
"IPv4Address3": "0.0.0.0",
"IPv6Address1": "::",
"IPv6Address2": "::",
"IPv6Address3": "::",
"Id": "LenovoDNS",
"PreferredAddresstype": "IPv4"
},
"ret": true
}
}'
"""
from ansible.module_utils.basic import AnsibleModule
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
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: xenserver_facts
short_description: Get facts reported on xenserver
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:
- Andy Hill (@andyhky)
- Tim Rupp (@caphrim007)
@ -28,9 +27,9 @@ attributes:
version_added: 3.3.0
# This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
options: {}
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Gather facts from xenserver
community.general.xenserver_facts:
@ -48,7 +47,7 @@ EXAMPLES = '''
# "item": "Control domain on host: 10.0.13.22",
# "msg": "Control domain on host: 10.0.13.22"
# }
'''
"""
HAVE_XENAPI = False

585
plugins/modules/xenserver_guest.py
View File

@ -8,43 +8,41 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: xenserver_guest
short_description: Manages virtual machines running on Citrix Hypervisor/XenServer host or pool
description: >
This module can be used to create new virtual machines from templates or other virtual machines,
modify various virtual machine components like network and disk, rename a virtual machine and
remove a virtual machine with associated components.
description: >-
This module can be used to create new virtual machines from templates or other virtual machines, modify various virtual machine components like
network and disk, rename a virtual machine and remove a virtual machine with associated components.
author:
- Bojan Vitnik (@bvitnik) <bvitnik@mainstream.rs>
- Bojan Vitnik (@bvitnik) <bvitnik@mainstream.rs>
notes:
- 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.
- 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside
Citrix Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the XenAPI.py file from the SDK to your Python site-packages on your
Ansible 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)'
- '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
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)
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
XenServer 7.0 or newer for Windows guests by using official XenServer Guest agent support for network configuration. The module will try 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)
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)'
- '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
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
to implement a boot time scripts or custom agent that will read the parameters from xenstore and configure network with given parameters.
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
parameter is changed. This is a limitation of XenAPI and xenstore. Considering these limitations, network configuration through xenstore is most
useful for bootstrapping newly deployed VMs, much less for reconfiguring existing ones. More info here:
U(https://support.citrix.com/article/CTX226713)'
- 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.
- 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside Citrix
Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the C(XenAPI.py) file from the SDK to your Python site-packages on your Ansible
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).'
- '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 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)
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 XenServer 7.0 or newer for Windows guests by using official XenServer Guest agent support for network configuration. The module will try
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)
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).'
- '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 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 to implement a boot time
scripts or custom agent that will read the parameters from xenstore and configure network with given parameters. 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 parameter is changed. This is
a limitation of XenAPI and xenstore. Considering these limitations, network configuration through xenstore is most useful for bootstrapping
newly deployed VMs, much less for reconfiguring existing ones. More info here: U(https://support.citrix.com/article/CTX226713).'
requirements:
- XenAPI
- XenAPI
attributes:
check_mode:
support: full
@ -53,248 +51,249 @@ attributes:
options:
state:
description:
- Specify the state VM should be in.
- If O(state) is set to V(present) and VM exists, ensure the VM configuration conforms to given parameters.
- If O(state) is set to V(present) and VM does not exist, then VM is deployed with given parameters.
- If O(state) is set to V(absent) and VM exists, then VM is removed with its associated components.
- If O(state) is set to V(poweredon) and VM does not exist, then VM is deployed with given parameters and powered on automatically.
- Specify the state VM should be in.
- If O(state) is set to V(present) and VM exists, ensure the VM configuration conforms to given parameters.
- If O(state) is set to V(present) and VM does not exist, then VM is deployed with given parameters.
- If O(state) is set to V(absent) and VM exists, then VM is removed with its associated components.
- 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
default: present
choices: [ present, absent, poweredon ]
choices: [present, absent, poweredon]
name:
description:
- Name of the VM to work with.
- VMs running on XenServer do not necessarily have unique names. The module will fail if multiple VMs with same name are found.
- In case of multiple VMs with same name, use O(uuid) to uniquely specify VM to manage.
- This parameter is case sensitive.
- Name of the VM to work with.
- VMs running on XenServer do not necessarily have unique names. The module will fail if multiple VMs with same name are found.
- In case of multiple VMs with same name, use O(uuid) to uniquely specify VM to manage.
- This parameter is case sensitive.
type: str
aliases: [ name_label ]
aliases: [name_label]
name_desc:
description:
- VM description.
- VM description.
type: str
uuid:
description:
- UUID of the VM to manage if known. This is XenServer's unique identifier.
- It is required if name is not unique.
- Please note that a supplied UUID will be ignored on VM creation, as XenServer creates the UUID internally.
- UUID of the VM to manage if known. This is XenServer's unique identifier.
- It is required if name is not unique.
- Please note that a supplied UUID will be ignored on VM creation, as XenServer creates the UUID internally.
type: str
template:
description:
- 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.
- 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.
- This parameter is case sensitive.
- 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.
- 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.
- This parameter is case sensitive.
type: str
aliases: [ template_src ]
aliases: [template_src]
template_uuid:
description:
- UUID of a template, an existing VM or a snapshot that should be used to create VM.
- It is required if template name is not unique.
- UUID of a template, an existing VM or a snapshot that should be used to create VM.
- It is required if template name is not unique.
type: str
is_template:
description:
- Convert VM to template.
- Convert VM to template.
type: bool
default: false
folder:
description:
- Destination folder for VM.
- This parameter is case sensitive.
- 'Example:'
- ' folder: /folder1/folder2'
- Destination folder for VM.
- This parameter is case sensitive.
- 'Example:'
- ' folder: /folder1/folder2'
type: str
hardware:
description:
- Manage VM's hardware parameters. VM needs to be shut down to reconfigure these parameters.
- Manage VM's hardware parameters. VM needs to be shut down to reconfigure these parameters.
type: dict
suboptions:
num_cpus:
description:
- Number of CPUs.
- Number of CPUs.
type: int
num_cpu_cores_per_socket:
description:
- Number of Cores Per Socket. O(hardware.num_cpus) has to be a multiple of O(hardware.num_cpu_cores_per_socket).
- Number of Cores Per Socket. O(hardware.num_cpus) has to be a multiple of O(hardware.num_cpu_cores_per_socket).
type: int
memory_mb:
description:
- Amount of memory in MB.
- Amount of memory in MB.
type: int
disks:
description:
- A list of disks to add to VM.
- All parameters are case sensitive.
- Removing or detaching existing disks of VM is not supported.
- New disks are required to have either a O(disks[].size) or one of O(ignore:disks[].size_[tb,gb,mb,kb,b]) parameters specified.
- VM needs to be shut down to reconfigure disk size.
- A list of disks to add to VM.
- All parameters are case sensitive.
- Removing or detaching existing disks of VM is not supported.
- New disks are required to have either a O(disks[].size) or one of O(ignore:disks[].size_[tb,gb,mb,kb,b]) parameters specified.
- VM needs to be shut down to reconfigure disk size.
type: list
elements: dict
aliases: [ disk ]
aliases: [disk]
suboptions:
size:
description:
- 'Disk size with unit. Unit must be: V(b), V(kb), V(mb), V(gb), V(tb). VM needs to be shut down to reconfigure this parameter.'
- If no unit is specified, size is assumed to be in bytes.
- 'Disk size with unit. Unit must be: V(b), V(kb), V(mb), V(gb), V(tb). VM needs to be shut down to reconfigure this parameter.'
- If no unit is specified, size is assumed to be in bytes.
type: str
size_b:
description:
- Disk size in bytes.
- Disk size in bytes.
type: str
size_kb:
description:
- Disk size in kilobytes.
- Disk size in kilobytes.
type: str
size_mb:
description:
- Disk size in megabytes.
- Disk size in megabytes.
type: str
size_gb:
description:
- Disk size in gigabytes.
- Disk size in gigabytes.
type: str
size_tb:
description:
- Disk size in terabytes.
- Disk size in terabytes.
type: str
name:
description:
- Disk name.
- Disk name.
type: str
aliases: [ name_label ]
aliases: [name_label]
name_desc:
description:
- Disk description.
- Disk description.
type: str
sr:
description:
- Storage Repository to create disk on. If not specified, will use default SR. Cannot be used for moving disk to other SR.
- Storage Repository to create disk on. If not specified, will use default SR. Cannot be used for moving disk to other SR.
type: str
sr_uuid:
description:
- UUID of a SR to create disk on. Use if SR name is not unique.
- UUID of a SR to create disk on. Use if SR name is not unique.
type: str
cdrom:
description:
- A CD-ROM configuration for the VM.
- All parameters are case sensitive.
- A CD-ROM configuration for the VM.
- All parameters are case sensitive.
type: dict
suboptions:
type:
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
choices: [ none, iso ]
choices: [none, iso]
iso_name:
description:
- 'The file name of an ISO image from one of the XenServer ISO Libraries (implies O(cdrom.type=iso)).'
- Required if O(cdrom.type) is set to V(iso).
- 'The file name of an ISO image from one of the XenServer ISO Libraries (implies O(cdrom.type=iso)).'
- Required if O(cdrom.type) is set to V(iso).
type: str
networks:
description:
- A list of networks (in the order of the NICs).
- All parameters are case sensitive.
- Name is required for new NICs. Other parameters are optional in all cases.
- A list of networks (in the order of the NICs).
- All parameters are case sensitive.
- Name is required for new NICs. Other parameters are optional in all cases.
type: list
elements: dict
aliases: [ network ]
aliases: [network]
suboptions:
name:
description:
name:
description:
- Name of a XenServer network to attach the network interface to.
type: str
aliases: [ name_label ]
mac:
description:
type: str
aliases: [name_label]
mac:
description:
- Customize MAC address of the interface.
type: str
type:
description:
- 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).
type: str
choices: [ none, dhcp, static ]
ip:
description:
- 'Static IPv4 address (implies O(networks[].type=static)). Can include prefix in format C(<IPv4 address>/<prefix>) instead of using C(netmask).'
type: str
netmask:
description:
type: str
type:
description:
- 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).
type: str
choices: [none, dhcp, static]
ip:
description:
- Static IPv4 address (implies O(networks[].type=static)). Can include prefix in format C(<IPv4 address>/<prefix>) instead of using
C(netmask).
type: str
netmask:
description:
- Static IPv4 netmask required for O(networks[].ip) if prefix is not specified.
type: str
gateway:
description:
type: str
gateway:
description:
- Static IPv4 gateway.
type: str
type6:
description:
type: str
type6:
description:
- Type of IPv6 assignment. Value V(none) means whatever is default for OS.
type: str
choices: [ none, dhcp, static ]
ip6:
description:
type: str
choices: [none, dhcp, static]
ip6:
description:
- 'Static IPv6 address (implies O(networks[].type6=static)) with prefix in format C(<IPv6 address>/<prefix>).'
type: str
gateway6:
description:
type: str
gateway6:
description:
- Static IPv6 gateway.
type: str
type: str
home_server:
description:
- Name of a XenServer host that will be a Home Server for the VM.
- This parameter is case sensitive.
- Name of a XenServer host that will be a Home Server for the VM.
- This parameter is case sensitive.
type: str
custom_params:
description:
- Define a list of custom VM params to set on VM.
- Useful for advanced users familiar with managing VM params through xe CLI.
- A custom value object takes two fields O(custom_params[].key) and O(custom_params[].value) (see example below).
- Define a list of custom VM params to set on VM.
- 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).
type: list
elements: dict
suboptions:
key:
description:
- VM param name.
- VM param name.
type: str
required: true
value:
description:
- VM param value.
- VM param value.
type: raw
required: true
wait_for_ip_address:
description:
- Wait until XenServer detects an IP address for the VM. If O(state) is set to V(absent), this parameter is ignored.
- This requires XenServer Tools to be preinstalled on the VM to work properly.
- Wait until XenServer detects an IP address for the VM. If O(state) is set to V(absent), this parameter is ignored.
- This requires XenServer Tools to be preinstalled on the VM to work properly.
type: bool
default: false
state_change_timeout:
description:
- 'By default, module will wait indefinitely for VM to acquire an IP address if O(wait_for_ip_address=true).'
- If this parameter is set to positive value, the module will instead wait specified number of seconds for the state change.
- In case of timeout, module will generate an error message.
- 'By default, module will wait indefinitely for VM to acquire an IP address if O(wait_for_ip_address=true).'
- If this parameter is set to positive value, the module will instead wait specified number of seconds for the state change.
- In case of timeout, module will generate an error message.
type: int
default: 0
linked_clone:
description:
- Whether to create a Linked Clone from the template, existing VM or snapshot. If no, will create a full copy.
- This is equivalent to C(Use storage-level fast disk clone) option in XenCenter.
- Whether to create a Linked Clone from the template, existing VM or snapshot. If no, will create a full copy.
- This is equivalent to C(Use storage-level fast disk clone) option in XenCenter.
type: bool
default: false
force:
description:
- Ignore warnings and complete the actions.
- This parameter is useful for removing VM in running state or reconfiguring VM params that require VM to be shut down.
- Ignore warnings and complete the actions.
- This parameter is useful for removing VM in running state or reconfiguring VM params that require VM to be shut down.
type: bool
default: false
extends_documentation_fragment:
- community.general.xenserver.documentation
- community.general.attributes
- community.general.xenserver.documentation
- community.general.attributes
"""
'''
EXAMPLES = r'''
EXAMPLES = r"""
- name: Create a VM from a template
community.general.xenserver_guest:
hostname: "{{ xenserver_hostname }}"
@ -305,8 +304,8 @@ EXAMPLES = r'''
state: poweredon
template: CentOS 7
disks:
- size_gb: 10
sr: my_sr
- size_gb: 10
sr: my_sr
hardware:
num_cpus: 6
num_cpu_cores_per_socket: 3
@ -315,8 +314,8 @@ EXAMPLES = r'''
type: iso
iso_name: guest-tools.iso
networks:
- name: VM Network
mac: aa:bb:dd:aa:00:14
- name: VM Network
mac: aa:bb:dd:aa:00:14
wait_for_ip_address: true
delegate_to: localhost
register: deploy
@ -330,8 +329,8 @@ EXAMPLES = r'''
name: testvm_6
is_template: true
disk:
- size_gb: 10
sr: my_sr
- size_gb: 10
sr: my_sr
hardware:
memory_mb: 512
num_cpus: 1
@ -365,8 +364,8 @@ EXAMPLES = r'''
name: testvm_8
state: present
custom_params:
- key: HVM_boot_params
value: { "order": "ndc" }
- key: HVM_boot_params
value: {"order": "ndc"}
delegate_to: localhost
- name: Customize network parameters
@ -376,154 +375,154 @@ EXAMPLES = r'''
password: "{{ xenserver_password }}"
name: testvm_10
networks:
- name: VM Network
ip: 192.168.1.100/24
gateway: 192.168.1.1
- type: dhcp
- name: VM Network
ip: 192.168.1.100/24
gateway: 192.168.1.1
- type: dhcp
delegate_to: localhost
'''
"""
RETURN = r'''
RETURN = r"""
instance:
description: Metadata about the VM
returned: always
type: dict
sample: {
"cdrom": {
"type": "none"
},
"customization_agent": "native",
"disks": [
{
"name": "testvm_11-0",
"name_desc": "",
"os_device": "xvda",
"size": 42949672960,
"sr": "Local storage",
"sr_uuid": "0af1245e-bdb0-ba33-1446-57a962ec4075",
"vbd_userdevice": "0"
},
{
"name": "testvm_11-1",
"name_desc": "",
"os_device": "xvdb",
"size": 42949672960,
"sr": "Local storage",
"sr_uuid": "0af1245e-bdb0-ba33-1446-57a962ec4075",
"vbd_userdevice": "1"
}
],
"domid": "56",
"folder": "",
"hardware": {
"memory_mb": 8192,
"num_cpu_cores_per_socket": 2,
"num_cpus": 4
},
"home_server": "",
"is_template": false,
"name": "testvm_11",
description: Metadata about the VM.
returned: always
type: dict
sample: {
"cdrom": {
"type": "none"
},
"customization_agent": "native",
"disks": [
{
"name": "testvm_11-0",
"name_desc": "",
"networks": [
{
"gateway": "192.168.0.254",
"gateway6": "fc00::fffe",
"ip": "192.168.0.200",
"ip6": [
"fe80:0000:0000:0000:e9cb:625a:32c5:c291",
"fc00:0000:0000:0000:0000:0000:0000:0001"
],
"mac": "ba:91:3a:48:20:76",
"mtu": "1500",
"name": "Pool-wide network associated with eth1",
"netmask": "255.255.255.128",
"prefix": "25",
"prefix6": "64",
"vif_device": "0"
}
"os_device": "xvda",
"size": 42949672960,
"sr": "Local storage",
"sr_uuid": "0af1245e-bdb0-ba33-1446-57a962ec4075",
"vbd_userdevice": "0"
},
{
"name": "testvm_11-1",
"name_desc": "",
"os_device": "xvdb",
"size": 42949672960,
"sr": "Local storage",
"sr_uuid": "0af1245e-bdb0-ba33-1446-57a962ec4075",
"vbd_userdevice": "1"
}
],
"domid": "56",
"folder": "",
"hardware": {
"memory_mb": 8192,
"num_cpu_cores_per_socket": 2,
"num_cpus": 4
},
"home_server": "",
"is_template": false,
"name": "testvm_11",
"name_desc": "",
"networks": [
{
"gateway": "192.168.0.254",
"gateway6": "fc00::fffe",
"ip": "192.168.0.200",
"ip6": [
"fe80:0000:0000:0000:e9cb:625a:32c5:c291",
"fc00:0000:0000:0000:0000:0000:0000:0001"
],
"other_config": {
"base_template_name": "Windows Server 2016 (64-bit)",
"import_task": "OpaqueRef:e43eb71c-45d6-5351-09ff-96e4fb7d0fa5",
"install-methods": "cdrom",
"instant": "true",
"mac_seed": "f83e8d8a-cfdc-b105-b054-ef5cb416b77e"
},
"platform": {
"acpi": "1",
"apic": "true",
"cores-per-socket": "2",
"device_id": "0002",
"hpet": "true",
"nx": "true",
"pae": "true",
"timeoffset": "-25200",
"vga": "std",
"videoram": "8",
"viridian": "true",
"viridian_reference_tsc": "true",
"viridian_time_ref_count": "true"
},
"state": "poweredon",
"uuid": "e3c0b2d5-5f05-424e-479c-d3df8b3e7cda",
"xenstore_data": {
"vm-data": ""
}
"mac": "ba:91:3a:48:20:76",
"mtu": "1500",
"name": "Pool-wide network associated with eth1",
"netmask": "255.255.255.128",
"prefix": "25",
"prefix6": "64",
"vif_device": "0"
}
],
"other_config": {
"base_template_name": "Windows Server 2016 (64-bit)",
"import_task": "OpaqueRef:e43eb71c-45d6-5351-09ff-96e4fb7d0fa5",
"install-methods": "cdrom",
"instant": "true",
"mac_seed": "f83e8d8a-cfdc-b105-b054-ef5cb416b77e"
},
"platform": {
"acpi": "1",
"apic": "true",
"cores-per-socket": "2",
"device_id": "0002",
"hpet": "true",
"nx": "true",
"pae": "true",
"timeoffset": "-25200",
"vga": "std",
"videoram": "8",
"viridian": "true",
"viridian_reference_tsc": "true",
"viridian_time_ref_count": "true"
},
"state": "poweredon",
"uuid": "e3c0b2d5-5f05-424e-479c-d3df8b3e7cda",
"xenstore_data": {
"vm-data": ""
}
}
changes:
description: Detected or made changes to VM
returned: always
type: list
sample: [
description: Detected or made changes to VM.
returned: always
type: list
sample: [
{
"hardware": [
"num_cpus"
]
},
{
"disks_changed": [
[],
[
"size"
]
]
},
{
"disks_new": [
{
"hardware": [
"num_cpus"
]
},
"name": "new-disk",
"name_desc": "",
"position": 2,
"size_gb": "4",
"vbd_userdevice": "2"
}
]
},
{
"cdrom": [
"type",
"iso_name"
]
},
{
"networks_changed": [
[
"mac"
],
]
},
{
"networks_new": [
{
"disks_changed": [
[],
[
"size"
]
]
},
{
"disks_new": [
{
"name": "new-disk",
"name_desc": "",
"position": 2,
"size_gb": "4",
"vbd_userdevice": "2"
}
]
},
{
"cdrom": [
"type",
"iso_name"
]
},
{
"networks_changed": [
[
"mac"
],
]
},
{
"networks_new": [
{
"name": "Pool-wide network associated with eth2",
"position": 1,
"vif_device": "1"
}
]
},
"need_poweredoff"
]
'''
"name": "Pool-wide network associated with eth2",
"position": 1,
"vif_device": "1"
}
]
},
"need_poweredoff"
]
"""
import re

62
plugins/modules/xenserver_guest_info.py
View File

@ -8,48 +8,46 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: xenserver_guest_info
short_description: Gathers information for virtual machines running on Citrix Hypervisor/XenServer host or pool
description: >
This module can be used to gather essential VM facts.
description: This module can be used to gather essential VM facts.
author:
- Bojan Vitnik (@bvitnik) <bvitnik@mainstream.rs>
- Bojan Vitnik (@bvitnik) <bvitnik@mainstream.rs>
notes:
- 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.
- 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside
Citrix Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the XenAPI.py file from the SDK to your Python site-packages on your
Ansible 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)'
- '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
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)
which requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.'
- 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.
- 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside Citrix
Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the C(XenAPI.py) file from the SDK to your Python site-packages on your Ansible
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)'
- '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 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 O(validate_certs=no) which
requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.'
requirements:
- XenAPI
- XenAPI
options:
name:
description:
- Name of the VM to gather facts from.
- VMs running on XenServer do not necessarily have unique names. The module will fail if multiple VMs with same name are found.
- In case of multiple VMs with same name, use O(uuid) to uniquely specify VM to manage.
- This parameter is case sensitive.
- Name of the VM to gather facts from.
- VMs running on XenServer do not necessarily have unique names. The module will fail if multiple VMs with same name are found.
- In case of multiple VMs with same name, use O(uuid) to uniquely specify VM to manage.
- This parameter is case sensitive.
type: str
aliases: [ name_label ]
aliases: [name_label]
uuid:
description:
- UUID of the VM to gather fact of. This is XenServer's unique identifier.
- It is required if name is not unique.
- UUID of the VM to gather fact of. This is XenServer's unique identifier.
- It is required if name is not unique.
type: str
extends_documentation_fragment:
- community.general.xenserver.documentation
- community.general.attributes
- community.general.attributes.info_module
'''
- community.general.xenserver.documentation
- community.general.attributes
- community.general.attributes.info_module
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Gather facts
community.general.xenserver_guest_info:
hostname: "{{ xenserver_hostname }}"
@ -58,11 +56,11 @@ EXAMPLES = r'''
name: testvm_11
delegate_to: localhost
register: facts
'''
"""
RETURN = r'''
RETURN = r"""
instance:
description: Metadata about the VM
description: Metadata about the VM.
returned: always
type: dict
sample: {
@ -147,7 +145,7 @@ instance:
"vm-data": ""
}
}
'''
"""
from ansible.module_utils.basic import AnsibleModule

79
plugins/modules/xenserver_guest_powerstate.py
View File

@ -8,27 +8,25 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: xenserver_guest_powerstate
short_description: Manages power states of virtual machines running on Citrix Hypervisor/XenServer host or pool
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.
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.
author:
- Bojan Vitnik (@bvitnik) <bvitnik@mainstream.rs>
- Bojan Vitnik (@bvitnik) <bvitnik@mainstream.rs>
notes:
- 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.
- 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside
Citrix Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the XenAPI.py file from the SDK to your Python site-packages on your
Ansible 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)'
- '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
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)
which requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.'
- 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.
- 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside Citrix
Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the C(XenAPI.py) file from the SDK to your Python site-packages on your Ansible
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).'
- '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 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) which requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.'
requirements:
- XenAPI
- XenAPI
attributes:
check_mode:
support: full
@ -37,45 +35,44 @@ attributes:
options:
state:
description:
- Specify the state VM should be in.
- If O(state) is set to value other than V(present), then VM is transitioned into required state and facts are returned.
- If O(state) is set to V(present), then VM is just checked for existence and facts are returned.
- Specify the state VM should be in.
- If O(state) is set to value other than V(present), then VM is transitioned into required state 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
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:
description:
- Name of the VM to manage.
- VMs running on XenServer do not necessarily have unique names. The module will fail if multiple VMs with same name are found.
- In case of multiple VMs with same name, use O(uuid) to uniquely specify VM to manage.
- This parameter is case sensitive.
- Name of the VM to manage.
- VMs running on XenServer do not necessarily have unique names. The module will fail if multiple VMs with same name are found.
- In case of multiple VMs with same name, use O(uuid) to uniquely specify VM to manage.
- This parameter is case sensitive.
type: str
aliases: [ name_label ]
aliases: [name_label]
uuid:
description:
- UUID of the VM to manage if known. This is XenServer's unique identifier.
- It is required if name is not unique.
- UUID of the VM to manage if known. This is XenServer's unique identifier.
- It is required if name is not unique.
type: str
wait_for_ip_address:
description:
- Wait until XenServer detects an IP address for the VM.
- This requires XenServer Tools to be preinstalled on the VM to work properly.
- Wait until XenServer detects an IP address for the VM.
- This requires XenServer Tools to be preinstalled on the VM to work properly.
type: bool
default: false
state_change_timeout:
description:
- 'By default, module will wait indefinitely for VM to change state or acquire an IP address if O(wait_for_ip_address=true).'
- If this parameter is set to positive value, the module will instead wait specified number of seconds for the state change.
- In case of timeout, module will generate an error message.
- 'By default, module will wait indefinitely for VM to change state or acquire an IP address if O(wait_for_ip_address=true).'
- If this parameter is set to positive value, the module will instead wait specified number of seconds for the state change.
- In case of timeout, module will generate an error message.
type: int
default: 0
extends_documentation_fragment:
- community.general.xenserver.documentation
- community.general.attributes
- community.general.xenserver.documentation
- community.general.attributes
"""
'''
EXAMPLES = r'''
EXAMPLES = r"""
- name: Power on VM
community.general.xenserver_guest_powerstate:
hostname: "{{ xenserver_hostname }}"
@ -85,11 +82,11 @@ EXAMPLES = r'''
state: powered-on
delegate_to: localhost
register: facts
'''
"""
RETURN = r'''
RETURN = r"""
instance:
description: Metadata about the VM
description: Metadata about the VM.
returned: always
type: dict
sample: {
@ -174,7 +171,7 @@ instance:
"vm-data": ""
}
}
'''
"""
from ansible.module_utils.basic import AnsibleModule

97
plugins/modules/xfconf.py
View File

@ -8,26 +8,25 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = """
---
DOCUMENTATION = r"""
module: xfconf
author:
- "Joseph Benden (@jbenden)"
- "Alexei Znamensky (@russoz)"
- "Joseph Benden (@jbenden)"
- "Alexei Znamensky (@russoz)"
short_description: Edit XFCE4 Configurations
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:
- name: xfconf-query(1) man page
description: Manual page of the C(xfconf-query) tool at the XFCE documentation site.
link: 'https://docs.xfce.org/xfce/xfconf/xfconf-query'
- name: xfconf-query(1) man page
description: Manual page of the C(xfconf-query) tool at the XFCE documentation site.
link: 'https://docs.xfce.org/xfce/xfconf/xfconf-query'
- name: xfconf - Configuration Storage System
description: XFCE documentation for the Xfconf configuration system.
link: 'https://docs.xfce.org/xfce/xfconf/start'
- name: xfconf - Configuration Storage System
description: XFCE documentation for the Xfconf configuration system.
link: 'https://docs.xfce.org/xfce/xfconf/start'
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes
attributes:
check_mode:
@ -38,50 +37,49 @@ attributes:
options:
channel:
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
properties/keys are stored. See man xfconf-query(1).
- A Xfconf preference channel is a top-level tree key, inside of the Xfconf repository that corresponds to the location for which all application
properties/keys are stored. See man xfconf-query(1).
required: true
type: str
property:
description:
- A Xfce preference key is an element in the Xfconf repository that corresponds to an application preference. See man xfconf-query(1).
- A Xfce preference key is an element in the Xfconf repository that corresponds to an application preference. See man xfconf-query(1).
required: true
type: str
value:
description:
- Preference properties typically have simple values such as strings, integers, or lists of strings and integers. See man xfconf-query(1).
- Preference properties typically have simple values such as strings, integers, or lists of strings and integers. See man xfconf-query(1).
type: list
elements: raw
value_type:
description:
- 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).
- 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
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
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.
- 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).
- 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 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 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.
type: list
elements: str
choices: [string, int, double, bool, uint, uchar, char, uint64, int64, float]
state:
type: str
description:
- The action to take upon the property/value.
- The state V(get) has been removed in community.general 5.0.0. Please use the module M(community.general.xfconf_info) instead.
- The action to take upon the property/value.
- The state V(get) has been removed in community.general 5.0.0. Please use the module M(community.general.xfconf_info) instead.
choices: [present, absent]
default: "present"
force_array:
description:
- Force array even if only one element.
- Force array even if only one element.
type: bool
default: false
aliases: ['array']
version_added: 1.0.0
"""
EXAMPLES = """
---
EXAMPLES = r"""
- name: Change the DPI to "192"
xfconf:
channel: "xsettings"
@ -105,57 +103,56 @@ EXAMPLES = """
force_array: true
"""
RETURN = """
---
RETURN = r"""
channel:
description: The channel specified in the module parameters
description: The channel specified in the module parameters.
returned: success
type: str
sample: "xsettings"
property:
description: The property specified in the module parameters
description: The property specified in the module parameters.
returned: success
type: str
sample: "/Xft/DPI"
value_type:
description:
- The type of the value that was changed (V(none) for O(state=reset)). Either a single string value or a list of strings for array types.
- This is a string or a list of strings.
- The type of the value that was changed (V(none) for O(state=reset)). Either a single string value or a list of strings for array types.
- This is a string or a list of strings.
returned: success
type: any
sample: '"int" or ["str", "str", "str"]'
value:
description:
- The value of the preference key after executing the module. Either a single string value or a list of strings for array types.
- This is a string or a list of strings.
- The value of the preference key after executing the module. Either a single string value or a list of strings for array types.
- This is a string or a list of strings.
returned: success
type: any
sample: '"192" or ["orange", "yellow", "violet"]'
sample: "'192' or ['orange', 'yellow', 'violet']"
previous_value:
description:
- The value of the preference key before executing the module. Either a single string value or a list of strings for array types.
- This is a string or a list of strings.
- The value of the preference key before executing the module. Either a single string value or a list of strings for array types.
- This is a string or a list of strings.
returned: success
type: any
sample: '"96" or ["red", "blue", "green"]'
cmd:
description:
- A list with the resulting C(xfconf-query) command executed by the module.
- A list with the resulting C(xfconf-query) command executed by the module.
returned: success
type: list
elements: str
version_added: 5.4.0
sample:
- /usr/bin/xfconf-query
- --channel
- xfce4-panel
- --property
- /plugins/plugin-19/timezone
- --create
- --type
- string
- --set
- Pacific/Auckland
- /usr/bin/xfconf-query
- --channel
- xfce4-panel
- --property
- /plugins/plugin-19/timezone
- --create
- --type
- string
- --set
- Pacific/Auckland
"""
from ansible_collections.community.general.plugins.module_utils.module_helper import StateModuleHelper

91
plugins/modules/xfconf_info.py
View File

@ -7,18 +7,17 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = """
---
DOCUMENTATION = r"""
module: xfconf_info
author:
- "Alexei Znamensky (@russoz)"
- "Alexei Znamensky (@russoz)"
short_description: Retrieve XFCE4 configurations
version_added: 3.5.0
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:
- community.general.attributes
- community.general.attributes.info_module
- community.general.attributes
- community.general.attributes.info_module
attributes:
check_mode:
version_added: 3.3.0
@ -26,26 +25,21 @@ attributes:
options:
channel:
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 properties/keys are stored.
- If not provided, the module will list all available channels.
- "A Xfconf preference channel is a top-level tree key, inside of the 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.
type: str
property:
description:
- >
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 not provided and a O(channel) is provided, then the module will list all available properties in that O(channel).
- "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 not provided and a O(channel) is provided, then the module will list all available properties in that O(channel).
type: str
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
community.general.xfconf_info: {}
register: result
@ -68,63 +62,62 @@ EXAMPLES = """
register: result
"""
RETURN = """
---
RETURN = r"""
channels:
description:
- List of available channels.
- Returned when the module receives no parameter at all.
- List of available channels.
- Returned when the module receives no parameter at all.
returned: success
type: list
elements: str
sample:
- xfce4-desktop
- displays
- xsettings
- xfwm4
- xfce4-desktop
- displays
- xsettings
- xfwm4
properties:
description:
- List of available properties for a specific channel.
- Returned by passing only the O(channel) parameter to the module.
- List of available properties for a specific channel.
- Returned by passing only the O(channel) parameter to the module.
returned: success
type: list
elements: str
sample:
- /Gdk/WindowScalingFactor
- /Gtk/ButtonImages
- /Gtk/CursorThemeSize
- /Gtk/DecorationLayout
- /Gtk/FontName
- /Gtk/MenuImages
- /Gtk/MonospaceFontName
- /Net/DoubleClickTime
- /Net/IconThemeName
- /Net/ThemeName
- /Xft/Antialias
- /Xft/Hinting
- /Xft/HintStyle
- /Xft/RGBA
- /Gdk/WindowScalingFactor
- /Gtk/ButtonImages
- /Gtk/CursorThemeSize
- /Gtk/DecorationLayout
- /Gtk/FontName
- /Gtk/MenuImages
- /Gtk/MonospaceFontName
- /Net/DoubleClickTime
- /Net/IconThemeName
- /Net/ThemeName
- /Xft/Antialias
- /Xft/Hinting
- /Xft/HintStyle
- /Xft/RGBA
is_array:
description:
- Flag indicating whether the property is an array or not.
- Flag indicating whether the property is an array or not.
returned: success
type: bool
value:
description:
- The value of the property. Empty if the property is of array type.
- The value of the property. Empty if the property is of array type.
returned: success
type: str
sample: Monospace 10
value_array:
description:
- The array value of the property. Empty if the property is not of array type.
- The array value of the property. Empty if the property is not of array type.
returned: success
type: list
elements: str
sample:
- Main
- Work
- Tmp
- Main
- Work
- Tmp
"""
from ansible_collections.community.general.plugins.module_utils.module_helper import ModuleHelper

52
plugins/modules/xfs_quota.py
View File

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

197
plugins/modules/xml.py
View File

@ -11,8 +11,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: xml
short_description: Manage bits and pieces of XML files or strings
description:
@ -27,96 +26,94 @@ attributes:
options:
path:
description:
- Path to the file to operate on.
- This file must exist ahead of time.
- This parameter is required, unless O(xmlstring) is given.
- Path to the file to operate on.
- This file must exist ahead of time.
- This parameter is required, unless O(xmlstring) is given.
type: path
aliases: [ dest, file ]
aliases: [dest, file]
xmlstring:
description:
- A string containing XML on which to operate.
- This parameter is required, unless O(path) is given.
- A string containing XML on which to operate.
- This parameter is required, unless O(path) is given.
type: str
xpath:
description:
- A valid XPath expression describing the item(s) you want to manipulate.
- Operates on the document root, V(/), by default.
- A valid XPath expression describing the item(s) you want to manipulate.
- Operates on the document root, V(/), by default.
type: str
namespaces:
description:
- The namespace C(prefix:uri) mapping for the XPath expression.
- Needs to be a C(dict), not a C(list) of items.
- The namespace C(prefix:uri) mapping for the XPath expression.
- Needs to be a C(dict), not a C(list) of items.
type: dict
default: {}
state:
description:
- Set or remove an xpath selection (node(s), attribute(s)).
- Set or remove an xpath selection (node(s), attribute(s)).
type: str
choices: [ absent, present ]
choices: [absent, present]
default: present
aliases: [ ensure ]
aliases: [ensure]
attribute:
description:
- The attribute to select when using parameter O(value).
- This is a string, not prepended with V(@).
- The attribute to select when using parameter O(value).
- This is a string, not prepended with V(@).
type: raw
value:
description:
- Desired state of the selected attribute.
- Either a string, or to unset a value, the Python V(None) keyword (YAML Equivalent, V(null)).
- Elements default to no value (but present).
- Attributes default to an empty string.
- Desired state of the selected attribute.
- Either a string, or to unset a value, the Python V(None) keyword (YAML Equivalent, V(null)).
- Elements default to no value (but present).
- Attributes default to an empty string.
type: raw
add_children:
description:
- 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
(for example C(children=ansible) to add an empty C(<ansible/>) child element),
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.
- 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 (for example C(children=ansible) to add an empty C(<ansible/>)
child element), 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.
type: list
elements: raw
set_children:
description:
- Set the child-element(s) of a selected element for a given O(xpath).
- Removes any existing children.
- Child elements must be specified as in O(add_children).
- This parameter requires O(xpath) to be set.
- Set the child-element(s) of a selected element for a given O(xpath).
- Removes any existing children.
- Child elements must be specified as in O(add_children).
- This parameter requires O(xpath) to be set.
type: list
elements: raw
count:
description:
- Search for a given O(xpath) and provide the count of any matches.
- This parameter requires O(xpath) to be set.
- Search for a given O(xpath) and provide the count of any matches.
- This parameter requires O(xpath) to be set.
type: bool
default: false
print_match:
description:
- Search for a given O(xpath) and print out any matches.
- This parameter requires O(xpath) to be set.
- Search for a given O(xpath) and print out any matches.
- This parameter requires O(xpath) to be set.
type: bool
default: false
pretty_print:
description:
- Pretty print XML output.
- Pretty print XML output.
type: bool
default: false
content:
description:
- Search for a given O(xpath) and get content.
- This parameter requires O(xpath) to be set.
- Search for a given O(xpath) and get content.
- This parameter requires O(xpath) to be set.
type: str
choices: [ attribute, text ]
choices: [attribute, text]
input_type:
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
choices: [ xml, yaml ]
choices: [xml, yaml]
default: yaml
backup:
description:
- Create a backup file including the timestamp information so you can get
the original file back if you somehow clobbered it incorrectly.
- Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
type: bool
default: false
strip_cdata_tags:
@ -128,46 +125,44 @@ options:
insertbefore:
description:
- 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
(for example C(children=ansible) to add an empty C(<ansible/>) child element),
or a hash where the key is an element name and the value is the element value.
- 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/>)
child element), 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.
type: bool
default: false
insertafter:
description:
- 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
(for example C(children=ansible) to add an empty C(<ansible/>) child element),
or a hash where the key is an element name and the value is the element value.
- 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/>)
child element), 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.
type: bool
default: false
requirements:
- lxml >= 2.3.0
- lxml >= 2.3.0
notes:
- 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.
- 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.
- Namespaces prefix should be used for all children of an element where namespace is defined, unless another namespace is defined for them.
- 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.
- 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.
- Namespaces prefix should be used for all children of an element where namespace is defined, unless another namespace is defined for them.
seealso:
- name: Xml module development community wiki
description: More information related to the development of this xml module.
link: https://github.com/ansible/community/wiki/Module:-xml
- name: Introduction to XPath
description: A brief tutorial on XPath (w3schools.com).
link: https://www.w3schools.com/xml/xpath_intro.asp
- name: XPath Reference document
description: The reference documentation on XSLT/XPath (developer.mozilla.org).
link: https://developer.mozilla.org/en-US/docs/Web/XPath
- name: XML module development community wiki (archived)
description: More information related to the development of this xml module.
link: https://github.com/ansible/community/wiki/Module:-xml
- name: Introduction to XPath
description: A brief tutorial on XPath (w3schools.com).
link: https://www.w3schools.com/xml/xpath_intro.asp
- name: XPath Reference document
description: The reference documentation on XSLT/XPath (developer.mozilla.org).
link: https://developer.mozilla.org/en-US/docs/Web/XPath
author:
- Tim Bielawa (@tbielawa)
- Magnus Hedemark (@magnus919)
- Dag Wieers (@dagwieers)
'''
- Tim Bielawa (@tbielawa)
- Magnus Hedemark (@magnus919)
- Dag Wieers (@dagwieers)
"""
EXAMPLES = r'''
EXAMPLES = r"""
# Consider the following XML file:
#
# <business type="bar">
@ -219,9 +214,9 @@ EXAMPLES = r'''
path: /foo/bar.xml
xpath: /business/beers
add_children:
- beer: Old Rasputin
- beer: Old Motor Oil
- beer: Old Curmudgeon
- beer: Old Rasputin
- beer: Old Motor Oil
- beer: Old Curmudgeon
- name: Add several more beers to the 'beers' element and add them before the 'Rochefort 10' element
community.general.xml:
@ -229,9 +224,9 @@ EXAMPLES = r'''
xpath: '/business/beers/beer[text()="Rochefort 10"]'
insertbefore: true
add_children:
- beer: Old Rasputin
- beer: Old Motor Oil
- beer: Old Curmudgeon
- beer: Old Rasputin
- beer: Old Motor Oil
- beer: Old Curmudgeon
# NOTE: The 'state' defaults to 'present' and 'value' defaults to 'null' for elements
- name: Add a 'validxhtml' element to the 'website' element
@ -301,14 +296,14 @@ EXAMPLES = r'''
xpath: /business
add_children:
- building:
# Attributes
# Attributes
name: Scumm bar
location: Monkey island
# Subnodes
# Subnodes
_:
- floor: Pirate hall
- floor: Grog storage
- construction_date: "1990" # Only strings are valid
- construction_date: "1990" # Only strings are valid
- building: Grog factory
# Consider this XML for following example -
@ -327,37 +322,37 @@ EXAMPLES = r'''
path: bar.xml
xpath: /config/element[@name='test1']
state: absent
'''
"""
RETURN = r'''
RETURN = r"""
actions:
description: A dictionary with the original xpath, namespaces and state.
type: dict
returned: success
sample: {xpath: xpath, namespaces: [namespace1, namespace2], state=present}
description: A dictionary with the original xpath, namespaces and state.
type: dict
returned: success
sample: {xpath: xpath, namespaces: [namespace1, namespace2], state: present}
backup_file:
description: The name of the backup file that was created
type: str
returned: when O(backup=true)
sample: /path/to/file.xml.1942.2017-08-24@14:16:01~
description: The name of the backup file that was created.
type: str
returned: when O(backup=true)
sample: /path/to/file.xml.1942.2017-08-24@14:16:01~
count:
description: The count of xpath matches.
type: int
returned: when parameter 'count' is set
sample: 2
description: The count of xpath matches.
type: int
returned: when parameter O(count) is set
sample: 2
matches:
description: The xpath matches found.
type: list
returned: when parameter 'print_match' is set
description: The xpath matches found.
type: list
returned: when parameter O(print_match) is set
msg:
description: A message related to the performed action(s).
type: str
returned: always
description: A message related to the performed action(s).
type: str
returned: always
xmlstring:
description: An XML string of the resulting output.
type: str
returned: when parameter 'xmlstring' is set
'''
description: An XML string of the resulting output.
type: str
returned: when parameter O(xmlstring) is set
"""
import copy
import json