diff --git a/plugins/modules/xattr.py b/plugins/modules/xattr.py index 7a5f3b431f3..11b036ff66b 100644 --- a/plugins/modules/xattr.py +++ b/plugins/modules/xattr.py @@ -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 @@ - 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 @@ 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 @@ namespace: trusted key: glusterfs.volume-id state: absent -''' +""" import os diff --git a/plugins/modules/xbps.py b/plugins/modules/xbps.py index cd34029ebae..9f6cb59d985 100644 --- a/plugins/modules/xbps.py +++ b/plugins/modules/xbps.py @@ -10,86 +10,78 @@ __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' -''' - -EXAMPLES = ''' + 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 = r""" - name: Install package foo (automatically updating the xbps package if needed) community.general.xbps: name: foo @@ -151,20 +143,20 @@ 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 diff --git a/plugins/modules/xcc_redfish_command.py b/plugins/modules/xcc_redfish_command.py index 1e77d0f8db4..a5b2ff57c2d 100644 --- a/plugins/modules/xcc_redfish_command.py +++ b/plugins/modules/xcc_redfish_command.py @@ -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 @@ 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 @@ 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" - - - 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: 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: 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: 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: 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: 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: 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 = ''' +""" + +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 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 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: 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: 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 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: 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 }}" +""" + +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 diff --git a/plugins/modules/xenserver_facts.py b/plugins/modules/xenserver_facts.py index 685522f4991..a3840e0e572 100644 --- a/plugins/modules/xenserver_facts.py +++ b/plugins/modules/xenserver_facts.py @@ -9,12 +9,11 @@ __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 @@ 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 @@ # "item": "Control domain on host: 10.0.13.22", # "msg": "Control domain on host: 10.0.13.22" # } -''' +""" HAVE_XENAPI = False diff --git a/plugins/modules/xenserver_guest.py b/plugins/modules/xenserver_guest.py index 110bc887513..16d928874c5 100644 --- a/plugins/modules/xenserver_guest.py +++ b/plugins/modules/xenserver_guest.py @@ -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) + - Bojan Vitnik (@bvitnik) 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/) 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/) 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 @@ 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(/) 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(/) 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(/).' - 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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: [ - { - "hardware": [ - "num_cpus" - ] - }, - { - "disks_changed": [ - [], - [ - "size" - ] - ] - }, - { - "disks_new": [ - { - "name": "new-disk", - "name_desc": "", - "position": 2, - "size_gb": "4", - "vbd_userdevice": "2" - } - ] - }, + description: Detected or made changes to VM. + returned: always + type: list + sample: [ + { + "hardware": [ + "num_cpus" + ] + }, + { + "disks_changed": [ + [], + [ + "size" + ] + ] + }, + { + "disks_new": [ { - "cdrom": [ - "type", - "iso_name" - ] - }, - { - "networks_changed": [ - [ - "mac" - ], - ] - }, + "name": "new-disk", + "name_desc": "", + "position": 2, + "size_gb": "4", + "vbd_userdevice": "2" + } + ] + }, + { + "cdrom": [ + "type", + "iso_name" + ] + }, + { + "networks_changed": [ + [ + "mac" + ], + ] + }, + { + "networks_new": [ { - "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 diff --git a/plugins/modules/xenserver_guest_info.py b/plugins/modules/xenserver_guest_info.py index 68050f95098..10cd11839c1 100644 --- a/plugins/modules/xenserver_guest_info.py +++ b/plugins/modules/xenserver_guest_info.py @@ -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) + - Bojan Vitnik (@bvitnik) 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 @@ 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 @@ "vm-data": "" } } -''' +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/xenserver_guest_powerstate.py b/plugins/modules/xenserver_guest_powerstate.py index c4e4f5976fa..86a21b56dc8 100644 --- a/plugins/modules/xenserver_guest_powerstate.py +++ b/plugins/modules/xenserver_guest_powerstate.py @@ -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) + - Bojan Vitnik (@bvitnik) 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 @@ 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 @@ 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 @@ "vm-data": "" } } -''' +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/xfconf.py b/plugins/modules/xfconf.py index 8bb0abc2733..b925e624c8c 100644 --- a/plugins/modules/xfconf.py +++ b/plugins/modules/xfconf.py @@ -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 @@ 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 @@ 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 diff --git a/plugins/modules/xfconf_info.py b/plugins/modules/xfconf_info.py index aba0d912ff6..d8e6acc50d9 100644 --- a/plugins/modules/xfconf_info.py +++ b/plugins/modules/xfconf_info.py @@ -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 @@ 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 @@ 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 diff --git a/plugins/modules/xfs_quota.py b/plugins/modules/xfs_quota.py index 6d05219905b..3b0b2bd19ee 100644 --- a/plugins/modules/xfs_quota.py +++ b/plugins/modules/xfs_quota.py @@ -12,7 +12,6 @@ __metaclass__ = type DOCUMENTATION = r""" ---- module: xfs_quota short_description: Manage quotas on XFS filesystems description: @@ -85,7 +84,7 @@ - absent requirements: - - xfsprogs + - xfsprogs """ EXAMPLES = r""" @@ -109,40 +108,39 @@ 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 diff --git a/plugins/modules/xml.py b/plugins/modules/xml.py index f5cdbeac389..b06b8051a22 100644 --- a/plugins/modules/xml.py +++ b/plugins/modules/xml.py @@ -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 @@ 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() 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() + 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 @@ 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() 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() + 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() 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() + 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: # # @@ -219,9 +214,9 @@ 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 @@ 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 @@ 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 @@ 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