462 lines
16 KiB
ReStructuredText
462 lines
16 KiB
ReStructuredText
.. _ansible.utils.cli_parse_module:
|
|
|
|
|
|
***********************
|
|
ansible.utils.cli_parse
|
|
***********************
|
|
|
|
**Parse cli output or text using a variety of parsers**
|
|
|
|
|
|
Version added: 1.0.0
|
|
|
|
.. contents::
|
|
:local:
|
|
:depth: 1
|
|
|
|
|
|
Synopsis
|
|
--------
|
|
- Parse cli output or text using a variety of parsers
|
|
|
|
|
|
|
|
|
|
Parameters
|
|
----------
|
|
|
|
.. raw:: html
|
|
|
|
<table border=0 cellpadding=0 class="documentation-table">
|
|
<tr>
|
|
<th colspan="2">Parameter</th>
|
|
<th>Choices/<font color="blue">Defaults</font></th>
|
|
<th width="100%">Comments</th>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>command</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
<div>The command to run on the host</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>parser</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">dictionary</span>
|
|
/ <span style="color: red">required</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
<div>Parser specific parameters</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"></td>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>command</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
<div>The command used to locate the parser's template</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"></td>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>name</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
/ <span style="color: red">required</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
<div>The name of the parser to use</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"></td>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>os</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
<div>Provide an operating system value to the parser</div>
|
|
<div>For `ntc_templates` parser, this should be in the supported `<vendor>_<os>` format.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"></td>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>template_path</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
<div>Path of the parser template on the Ansible controller</div>
|
|
<div>This can be a relative or an absolute path</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"></td>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>vars</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">dictionary</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
<div>Additional parser specific parameters</div>
|
|
<div>See the cli_parse user guide for examples of parser specific variables</div>
|
|
<div><a href='https://docs.ansible.com/ansible/latest/network/user_guide/cli_parsing.html'>https://docs.ansible.com/ansible/latest/network/user_guide/cli_parsing.html</a></div>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="2">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>set_fact</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
<div>Set the resulting parsed data as a fact</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>text</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
<div>Text to be parsed</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br/>
|
|
|
|
|
|
Notes
|
|
-----
|
|
|
|
.. note::
|
|
- The default search path for a parser template is templates/{{ short_os }}_{{ command }}.{{ extension }}
|
|
- => short_os derived from ansible_network_os or ansible_distribution and set to lower case
|
|
- => command is the command passed to the module with spaces replaced with _
|
|
- => extension is specific to the parser used (native=yaml, textfsm=textfsm, ttp=ttp)
|
|
- The default Ansible search path for the templates directory is used for parser templates as well
|
|
- Some parsers may have additional configuration options available. See the parsers/vars key and the parser's documentation
|
|
- Some parsers require third-party python libraries be installed on the Ansible control node and a specific python version
|
|
- example Pyats requires pyats and genie and requires Python 3
|
|
- example ntc_templates requires ntc_templates
|
|
- example textfsm requires textfsm
|
|
- example ttp requires ttp
|
|
- example xml requires xml_to_dict
|
|
- Support of 3rd party python libraries is limited to the use of their public APIs as documented
|
|
- Additional information and examples can be found in the parsing user guide:
|
|
- https://docs.ansible.com/ansible/latest/network/user_guide/cli_parsing.html
|
|
|
|
|
|
|
|
Examples
|
|
--------
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Using the native parser
|
|
|
|
# -------------
|
|
# templates/nxos_show_interface.yaml
|
|
# - example: Ethernet1/1 is up
|
|
# getval: '(?P<name>\S+) is (?P<oper_state>\S+)'
|
|
# result:
|
|
# "{{ name }}":
|
|
# name: "{{ name }}"
|
|
# state:
|
|
# operating: "{{ oper_state }}"
|
|
# shared: True
|
|
#
|
|
# - example: admin state is up, Dedicated Interface
|
|
# getval: 'admin state is (?P<admin_state>\S+)'
|
|
# result:
|
|
# "{{ name }}":
|
|
# name: "{{ name }}"
|
|
# state:
|
|
# admin: "{{ admin_state }}"
|
|
#
|
|
# - example: " Hardware: Ethernet, address: 0000.5E00.5301 (bia 0000.5E00.5301)"
|
|
# getval: '\s+Hardware: (?P<hardware>.*), address: (?P<mac>\S+)'
|
|
# result:
|
|
# "{{ name }}":
|
|
# hardware: "{{ hardware }}"
|
|
# mac_address: "{{ mac }}"
|
|
|
|
- name: Run command and parse with native
|
|
ansible.utils.cli_parse:
|
|
command: "show interface"
|
|
parser:
|
|
name: ansible.netcommon.native
|
|
set_fact: interfaces_fact
|
|
|
|
|
|
- name: Pass text and template_path
|
|
ansible.utils.cli_parse:
|
|
text: "{{ previous_command['stdout'] }}"
|
|
parser:
|
|
name: ansible.netcommon.native
|
|
template_path: "{{ role_path }}/templates/nxos_show_interface.yaml"
|
|
|
|
|
|
# Using the ntc_templates parser
|
|
|
|
# -------------
|
|
# The ntc_templates use 'vendor_platform' for the file name
|
|
# it will be derived from ansible_network_os if not provided
|
|
# example cisco.ios.ios => cisco_ios
|
|
|
|
- name: Run command and parse with ntc_templates
|
|
ansible.utils.cli_parse:
|
|
command: "show interface"
|
|
parser:
|
|
name: ansible.netcommon.ntc_templates
|
|
register: parser_output
|
|
|
|
- name: Pass text and command
|
|
ansible.utils.cli_parse:
|
|
text: "{{ previous_command['stdout'] }}"
|
|
parser:
|
|
name: ansible.netcommon.ntc_templates
|
|
command: show interface
|
|
register: parser_output
|
|
|
|
|
|
# Using the pyats parser
|
|
|
|
# -------------
|
|
# The pyats parser uses 'os' to locate the appropriate parser
|
|
# it will be derived from ansible_network_os if not provided
|
|
# in the case of pyats: cisco.ios.ios => iosxe
|
|
|
|
- name: Run command and parse with pyats
|
|
ansible.utils.cli_parse:
|
|
command: "show interface"
|
|
parser:
|
|
name: ansible.netcommon.pyats
|
|
register: parser_output
|
|
|
|
- name: Pass text and command
|
|
ansible.utils.cli_parse:
|
|
text: "{{ previous_command['stdout'] }}"
|
|
parser:
|
|
name: ansible.netcommon.pyats
|
|
command: show interface
|
|
register: parser_output
|
|
|
|
- name: Provide an OS to pyats to use an ios parser
|
|
ansible.utils.cli_parse:
|
|
text: "{{ previous_command['stdout'] }}"
|
|
parser:
|
|
name: ansible.netcommon.pyats
|
|
command: show interface
|
|
os: ios
|
|
register: parser_output
|
|
|
|
|
|
# Using the textfsm parser
|
|
|
|
# -------------
|
|
# templates/nxos_show_version.textfsm
|
|
#
|
|
# Value UPTIME ((\d+\s\w+.s.,?\s?){4})
|
|
# Value LAST_REBOOT_REASON (.+)
|
|
# Value OS (\d+.\d+(.+)?)
|
|
# Value BOOT_IMAGE (.*)
|
|
# Value PLATFORM (\w+)
|
|
#
|
|
# Start
|
|
# ^\s+(NXOS: version|system:\s+version)\s+${OS}\s*$$
|
|
# ^\s+(NXOS|kickstart)\s+image\s+file\s+is:\s+${BOOT_IMAGE}\s*$$
|
|
# ^\s+cisco\s+${PLATFORM}\s+[cC]hassis
|
|
# ^\s+cisco\s+Nexus\d+\s+${PLATFORM}
|
|
# # Cisco N5K platform
|
|
# ^\s+cisco\s+Nexus\s+${PLATFORM}\s+[cC]hassis
|
|
# ^\s+cisco\s+.+-${PLATFORM}\s*
|
|
# ^Kernel\s+uptime\s+is\s+${UPTIME}
|
|
# ^\s+Reason:\s${LAST_REBOOT_REASON} -> Record
|
|
|
|
- name: Run command and parse with textfsm
|
|
ansible.utils.cli_parse:
|
|
command: "show version"
|
|
parser:
|
|
name: ansible.utils.textfsm
|
|
register: parser_output
|
|
|
|
- name: Pass text and command
|
|
ansible.utils.cli_parse:
|
|
text: "{{ previous_command['stdout'] }}"
|
|
parser:
|
|
name: ansible.utils.textfsm
|
|
command: show version
|
|
register: parser_output
|
|
|
|
# Using the ttp parser
|
|
|
|
# -------------
|
|
# templates/nxos_show_interface.ttp
|
|
#
|
|
# {{ interface }} is {{ state }}
|
|
# admin state is {{ admin_state }}{{ ignore(".*") }}
|
|
|
|
- name: Run command and parse with ttp
|
|
ansible.utils.cli_parse:
|
|
command: "show interface"
|
|
parser:
|
|
name: ansible.utils.ttp
|
|
set_fact: new_fact_key
|
|
|
|
- name: Pass text and template_path
|
|
ansible.utils.cli_parse:
|
|
text: "{{ previous_command['stdout'] }}"
|
|
parser:
|
|
name: ansible.utils.ttp
|
|
template_path: "{{ role_path }}/templates/nxos_show_interface.ttp"
|
|
register: parser_output
|
|
|
|
# Using the XML parser
|
|
|
|
# -------------
|
|
- name: Run command and parse with xml
|
|
ansible.utils.cli_parse:
|
|
command: "show interface | xml"
|
|
parser:
|
|
name: ansible.utils.xml
|
|
register: parser_output
|
|
|
|
- name: Pass text and parse with xml
|
|
ansible.utils.cli_parse:
|
|
text: "{{ previous_command['stdout'] }}"
|
|
parser:
|
|
name: ansible.utils.xml
|
|
register: parser_output
|
|
|
|
|
|
|
|
Return Values
|
|
-------------
|
|
Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module:
|
|
|
|
.. raw:: html
|
|
|
|
<table border=0 cellpadding=0 class="documentation-table">
|
|
<tr>
|
|
<th colspan="1">Key</th>
|
|
<th>Returned</th>
|
|
<th width="100%">Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>parsed</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">dictionary</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>The structured data resulting from the parsing of the text</div>
|
|
<br/>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>stdout</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>when provided a command</td>
|
|
<td>
|
|
<div>The output from the command run</div>
|
|
<br/>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>stdout_lines</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">list</span>
|
|
/ <span style="color: purple">elements=string</span>
|
|
</div>
|
|
</td>
|
|
<td>when provided a command</td>
|
|
<td>
|
|
<div>The output of the command run split into lines</div>
|
|
<br/>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br/><br/>
|
|
|
|
|
|
Status
|
|
------
|
|
|
|
|
|
Authors
|
|
~~~~~~~
|
|
|
|
- Bradley Thornton (@cidrblock)
|