From 2d5908255a26d90b4ddec1235f064662462c0dd1 Mon Sep 17 00:00:00 2001
From: Peter Sprygada <privateip@users.noreply.github.com>
Date: Mon, 7 Aug 2017 07:19:31 -0400
Subject: [PATCH] add parse_cli and parse_cli_textfsm to documentation (#27755)
* add parse_cli and parse_cli_textfsm to documentation
* Minor edits.
---
docs/docsite/rst/playbooks_filters.rst | 45 ++++++++++++++++++++++++++
1 file changed, 45 insertions(+)
diff --git a/docs/docsite/rst/playbooks_filters.rst b/docs/docsite/rst/playbooks_filters.rst
index 143ec8d69ed..98a2f2b68bb 100644
--- a/docs/docsite/rst/playbooks_filters.rst
+++ b/docs/docsite/rst/playbooks_filters.rst
@@ -318,6 +318,51 @@ address. For example, to get the IP address itself from a CIDR, you can use::
More information about ``ipaddr`` filter and complete usage guide can be found
in :doc:`playbooks_filters_ipaddr`.
+.. _network_filters:
+
+Network CLI filters
+```````````````````
+
+.. versionadded:: 2.4
+
+To convert the output of a network device CLI command into structured JSON
+output, use the ``parse_cli`` filter::
+
+ {{ output | parse_cli('path/to/spec') }}
+
+The ``parse_cli`` filter will load the spec file and pass the command output
+through, it returning JSON output. The spec file is a YAML yaml that defines
+how to parse the CLI output.
+
+The spec file should be valid formatted YAML. It defines how to parse the CLI
+output and return JSON data. Below is an example of a valid spec file that
+will parse the output from the ``show vlan`` command.::
+
+ ---
+ vlan:
+ vlan_id: "{{ item.vlan_id }}"
+ name: "{{ item.name }}"
+ enabled: "{{ item.state != 'act/lshut' }}"
+ state: "{{ item.state }}"
+
+ attributes:
+ vlans:
+ type: list
+ value: "{{ vlan }}"
+ items: "^(?P<vlan_id>\\d+)\\s+(?P<name>\\w+)\\s+(?P<state>active|act/lshut|suspended)"
+ state_static:
+ value: present
+
+The spec file above will return a JSON data structure that is a list of hashs
+with the parsed VLAN information.
+
+The network filters also support parsing the output of a CLI command using the
+TextFSM library. To parse the CLI output with TextFSM use the following
+filter::
+
+ {{ output | parse_cli_textfsm('path/to/fsm') }}
+
+Use of the TextFSM filter requires the TextFSM library to be installed.
.. _hash_filters: