ansible.utils.cli_parse module – Parse cli output or text using a variety of parsers

Note

This module is part of the ansible.utils collection (version 2.12.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install ansible.utils.

To use it in a playbook, specify: ansible.utils.cli_parse.

New in ansible.utils 1.0.0

Synopsis

  • Parse cli output or text using a variety of parsers

Note

This module has a corresponding action plugin.

Parameters

Parameter

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 `<vendor>_<os>` 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

https://docs.ansible.com/ansible/latest/network/user_guide/cli_parsing.html

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/{{ 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

# 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, the following are the fields unique to this module:

Key

Description

parsed

dictionary

The structured data resulting from the parsing of the text

Returned: always

stdout

string

The output from the command run

Returned: when provided a command

stdout_lines

list / elements=string

The output of the command run split into lines

Returned: when provided a command

Authors

  • Bradley Thornton (@cidrblock)