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.