win_xml – Manages XML file content on Windows hosts
New in version 2.7.
Synopsis
- Manages XML nodes, attributes and text, using xpath to select which xml nodes need to be managed.
- XML fragments, formatted as strings, are used to specify the desired state of a part or parts of XML files on remote Windows servers.
- For non-Windows targets, use the xml module instead.
Parameters
Parameter | Choices/Defaults | Comments |
---|---|---|
attribute
string
|
The attribute name if the type is 'attribute'.
Required if
type=attribute .
|
|
backup
boolean
|
|
Determine whether a backup should be created.
When set to
yes , create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
|
count
boolean
added in 2.9
|
|
When set to
yes , return the number of nodes matched by
xpath.
|
fragment
string
|
The string representation of the XML fragment expected at xpath. Since ansible 2.9 not required when
state=absent, or when
count=yes.
aliases: xmlstring |
|
path
path /
required
|
Path to the file to operate on.
aliases: dest, file |
|
state
string
added in 2.9
|
|
Set or remove the nodes (or attributes) matched by
xpath.
|
type
string /
required
|
|
The type of XML node you are working with.
|
xpath
string /
required
|
Xpath to select the node or nodes to operate on.
|
Notes
Note
- Only supports operating on xml elements, attributes and text.
- Namespace, processing-instruction, command and document node types cannot be modified with this module.
See Also
See also
- xml – Manage bits and pieces of XML files or strings
- XML manipulation for Posix hosts.
- w3shools XPath tutorial
- A useful tutorial on XPath
Examples
- name: Apply our filter to Tomcat web.xml win_xml: path: C:\apache-tomcat\webapps\myapp\WEB-INF\web.xml fragment: '<filter><filter-name>MyFilter</filter-name><filter-class>com.example.MyFilter</filter-class></filter>' xpath: '/*' - name: Apply sslEnabledProtocols to Tomcat's server.xml win_xml: path: C:\Tomcat\conf\server.xml xpath: '//Server/Service[@name="Catalina"]/Connector[@port="9443"]' attribute: 'sslEnabledProtocols' fragment: 'TLSv1,TLSv1.1,TLSv1.2' type: attribute - name: remove debug configuration nodes from nlog.conf win_xml: path: C:\IISApplication\nlog.conf xpath: /nlog/rules/logger[@name="debug"]/descendant::* state: absent - name: count configured connectors in Tomcat's server.xml win_xml: path: C:\Tomcat\conf\server.xml xpath: //Server/Service/Connector count: yes register: connector_count - name: show connector count debug: msg="Connector count is {{connector_count.count}}" - name: ensure all lang=en attributes to lang=nl win_xml: path: C:\Data\Books.xml xpath: //@[lang="en"] attribute: lang fragment: nl type: attribute
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description |
---|---|---|
backup_file
string
|
if backup=yes |
Name of the backup file that was created.
Sample:
C:\Path\To\File.txt.11540.20150212-220915.bak
|
count
integer
|
if count=yes |
Number of nodes matched by xpath.
Sample:
33
|
err
list
|
always, for type element and -vvv or more |
XML comparison exceptions.
Sample:
attribute mismatch for actual=string
|
msg
string
|
always |
What was done.
Sample:
xml added
|
Status
- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]
Authors
- Richard Levenberg (@richardcs)
- Jon Hawkesworth (@jhawkesworth)
Hint
If you notice any issues in this documentation, you can edit this document to improve it.
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.9/modules/win_xml_module.html