Parse Genie

WARNING!!! - If you experience issues with commands that do not parse correctly, there may be a bug in the parsing library maintained by Cisco. You can report these issues here.

The Parse Genie tool processes unstructured output from Cisco network commands and converts it into organized data. It uses Cisco's robust Genie library, which has over 1200 parsers for different commands, mapping the output to standard data models.

Genie can also interpret various outputs from different vendors if you create custom parsers. However, this feature is not included in this release. It only supports the parsers provided by the installed Genie version.

For a list of supported operating systems, commands, and their data formats, refer to the following link:

https://pubhub.devnetcloud.com/media/genie-feature-browser/docs/#/parsers

Requirements

To use this plugin, you will need:

1. Python version 3.4 or higher.
2. pyATS and Genie packages.
3. Ansible version 2.7 or higher (it may work with older versions if the other requirements are met).

Installation

Follow these steps to set up the filter plugin for your playbooks:

1. Create a directory for your playbook and navigate to it: mkdir network_ops && cd network_ops
2. Set up a virtual environment: python3 -m venv .venv
3. Activate the virtual environment: source .venv/bin/activate
4. Install Ansible: pip install ansible
5. Install Genie and pyATS: pip install genie
6. Install the parse_genie role from Ansible Galaxy: ansible-galaxy install clay584.parse_genie

Ansible to Genie OS Mappings

Here are the mappings from Ansible's ansible_network_os to Genie's os:

Ansible Network OS	Genie OS
ios	ios, iosxe
nxos	nxos
iosxr	iosxr
junos	junos

When using IOS or IOS-XE, specify the exact OS; otherwise, parsing may fail. If ansible_network_os is set to ios, the parser will first try ios, and if that fails, iosxe.

Usage

Include the parse_genie role in your playbook before using it:

  tasks:
    - name: Read in parse_genie role
      include_role:
        name: clay584.parse_genie

Simple Example

To convert the output from a command like show version on a Cisco IOS-XE device:

{{ cli_output | parse_genie(command='show version', os='iosxe') }}

You can also specify the platform:

{{ cli_output | parse_genie(command='show version', os='iosxe', platform='asr1k') }}

This would return structured data similar to:

{
    "version": {
        "chassis": "CSR1000V",
        "chassis_sn": "9TKUWGKX5MO",
        ...
    }
}

Full Example

Here’s a complete playbook example:

---
- hosts: localhost
  connection: local
  vars:
    show_version_output: |
      Cisco IOS XE Software, Version 16.05.01b
      ...
  tasks:
    - name: Read in parse_genie role
      include_role:
        name: clay584.parse_genie

    - name: Debug Genie Filter
      debug:
        msg: "{{ show_version_output | parse_genie(command='show version', os='iosxe') }}"
      delegate_to: localhost

The output would contain structured data extracted from the show version command.

Development

To set up a development environment:

1. Clone the repository: git clone https://github.com/clay584/parse_genie.git && cd parse_genie
2. Create a virtual environment: python3 -m venv .venv
3. Activate the environment: source .venv/bin/activate
4. Install necessary packages: pip install ansible genie yamllint

Testing

Run the following commands to test locally:

1. Check YAML files: yamllint -c yamllint_config.yml *
2. Execute the test playbook: ansible-playbook tests/test.yml --connection=local -i tests/inventory

Publishing Changes

Ansible Galaxy uses tags for versioning:

1. Commit your changes: git commit -m "Your message"
2. Tag the release: git tag -a X.X.X (replace X.X.X with the version number)
3. Push your changes: git push origin master
4. Push the tag: git push X.X.X