Adding Netbox

roles/ansible-network.network-engine/docs/user_guide/textfsm_parser.md

@@ -0,0 +1,82 @@
+# textfsm_parser
+
+The [textfsm_parser](https://github.com/ansible-network/network-engine/blob/devel/library/textfsm_parser.py)
+module is based on [Google TextFSM](https://github.com/google/textfsm/wiki/TextFSM) definitions. 
+This module iterates over matching rules defined in TextFSM format, extracts data from structured ASCII text based on those rules,
+and returns Ansible facts in a JSON data structure that can be added to inventory host facts and/or consumed by Ansible tasks and templates.
+
+The `textfsm_parser` module requires two inputs:
+- the output of commands run on the network device, passed to the `content` parameter
+- the parser template that defines the rules for parsing the output, passed to either the `file` or the `src` parameter
+
+## content
+
+The `content` parameter for `textfsm_parser` must point to the ASCII text output of commands run on network devices. The text output can be in a variable or in a file.
+
+## file
+
+The `file` parameter for `textfsm_parser` must point to a parser template that contains a TextFSM rule for each data field you want to extract from your network devices. 
+
+Parser templates for the `textfsm_parser` module in the Network Engine role use TextFSM notation.
+
+### name
+
+The `name` parameter for `textfsm_parser` names the variable in which Ansible will store the JSON data structure. If name is not set, the JSON facts from parsing will not be displayed/exported.
+
+### src
+
+The `src` parameter for `textfsm_parser` loads your parser template from an external source, usually a URL.
+
+## Sample Parser Templates
+
+Here is a sample TextFSM parser template:
+
+`parser_templates/ios/show_interfaces`
+```
+
+Value Required name (\S+)
+Value type ([\w ]+)
+Value description (.*)
+Value mtu (\d+)
+
+Start
+  ^${name} is up
+  ^\s+Hardware is ${type} -> Continue
+  ^\s+Description: ${description}
+  ^\s+MTU ${mtu} bytes, -> Record
+
+```
+
+## Sample Playbooks
+
+To extract the data defined in your parser template, create a playbook that includes the Network Engine role and references the `content` and `file` parameters of the `command_parser` module. 
+
+The example playbook below runs a show command, imports the Network Engine role, extracts data from the text output of the command by matching it against the rules defined
+in your parser template, and stores the results in a variable. To view the content of that final variable, add it to the `name` parameter as shown in the example and run the playbook in `verbose` mode: `ansible-playbook -v`.
+
+Make sure the `hosts` definition in the playbook matches a host group in your inventory - in these examples, the playbook expects a group called `ios`.
+
+The example below parses the output of the `show interfaces` command on IOS and creates facts from that output:
+
+```yaml
+
+---
+
+# ~/my-playbooks/textfsm-gather-interface-info.yml
+
+- hosts: ios
+  connection: network_cli
+
+  tasks:
+  - name: Collect interface information from device
+    ios_command:
+      commands: "show interfaces"
+    register: ios_interface_output
+
+  - name: Generate interface facts as JSON
+    textfsm_parser:
+      file: "parser_templates/ios/show_interfaces"
+      content: "{{ ios_interface_output.stdout.0 }}"
+      name: interface_facts
+
+```