ansible.netcommon.cli_parse – Parse cli output or text using a variety of parsers
ansible.netcommon.cli_parse – Parse cli output or text using a variety of parsers
Note
This plugin is part of the ansible.netcommon collection (version 1.4.1).
To install it use: ansible-galaxy collection install ansible.netcommon
.
To use it in a playbook, specify: ansible.netcommon.cli_parse
.
New in version 1.2.0: of ansible.netcommon
Synopsis
- Parse cli output or text using a variety of parsers
Parameters
Parameter | Choices/Defaults | Comments | |
---|---|---|---|
command string |
The command to run on the host | ||
parser dictionary / required |
Parser specific parameters | ||
command string |
The command used to locate the parser's template | ||
name string / required |
The name of the parser to use | ||
os string |
Provide an operating system value to the parser For `ntc_templates` parser, this should be in the supported `_` format. | ||
template_path string |
Path of the parser template on the Ansible controller This can be a relative or an absolute path | ||
vars dictionary |
Additional parser specific parameters See the cli_parse user guide for examples of parser specific variables | ||
set_fact string |
Set the resulting parsed data as a fact | ||
text string |
Text to be parsed |
Notes
Note
- The default search path for a parser template is templates/Template:Short os_Template:Command.Template: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
- e.g. Pyats requires pyats and genie and requires Python 3
- e.g. ntc_templates requires ntc_templates
- e.g. textfsm requires textfsm
- e.g. ttp requires ttp
- e.g. 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
# 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.netcommon.cli_parse:
command: "show interface"
parser:
name: ansible.netcommon.native
set_fact: interfaces_fact
- name: Pass text and template_path
ansible.netcommon.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
# e.g. cisco.ios.ios => cisco_ios
- name: Run command and parse with ntc_templates
ansible.netcommon.cli_parse:
command: "show interface"
parser:
name: ansible.netcommon.ntc_templates
register: parser_output
- name: Pass text and command
ansible.netcommon.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.netcommon.cli_parse:
command: "show interface"
parser:
name: ansible.netcommon.pyats
register: parser_output
- name: Pass text and command
ansible.netcommon.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.netcommon.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.netcommon.cli_parse:
command: "show version"
parser:
name: ansible.netcommon.textfsm
register: parser_output
- name: Pass text and command
ansible.netcommon.cli_parse:
text: "{{ previous_command['stdout'] }}"
parser:
name: ansible.netcommon.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.netcommon.cli_parse:
command: "show interface"
parser:
name: ansible.netcommon.ttp
set_fact: new_fact_key
- name: Pass text and template_path
ansible.netcommon.cli_parse:
text: "{{ previous_command['stdout'] }}"
parser:
name: ansible.netcommon.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.netcommon.cli_parse:
command: "show interface | xml"
parser:
name: ansible.netcommon.xml
register: parser_output
- name: Pass text and parse with xml
ansible.netcommon.cli_parse:
text: "{{ previous_command['stdout'] }}"
parser:
name: ansible.netcommon.xml
register: parser_output
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description |
---|---|---|
parsed dictionary |
always |
The structured data resulting from the parsing of the text
|
stdout string |
when provided a command |
The output from the command run
|
stdout_lines list / elements=string |
when provided a command |
The output of the command run split into lines
|
Authors
- Bradley Thornton (@cidrblock)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.10/collections/ansible/netcommon/cli_parse_module.html