Adding Netbox

roles/ansible-network.cisco_ios/docs/get_facts.md

@@ -0,0 +1,166 @@
+# Get facts from device
+
+The `get_facts` function can be used to collect facts from an Cisco IOS
+devices.  This function is only supported over `network_cli` connection
+type and requires the `ansible_network_os` value set to `ios`.
+
+## How to get facts from the device
+
+To collect facts from the device, simply include this function in the playbook
+using either the `roles` directive or the `tasks` directive.  If no other
+options are provided, then all of the available facts will be collected for the
+device.
+
+Below is an example of how to use the `roles` directive to collect all facts
+from the IOS device.
+
+```
+- hosts: cisco_ios
+
+  roles:
+    - name ansible-network.cisco_ios
+      function: get_facts
+```
+
+The above playbook will return the facts for the host under the `cisco_ios`
+top level key.  
+
+### Filter the subset of facts returned
+
+By default all available facts will be returned by the `get_facts` function.
+If you only want to return a subset of the facts, you can specify the `subset`
+variable as a list of keys to return. 
+
+For instance, the below will return only `interfaces` and `system` facts.
+
+```
+- hosts: cisco_ios
+
+  roles:
+    - name ansible-network.cisco_ios
+      function: get_facts
+      subset: 
+        - system
+```
+
+### Implement using tasks
+
+The `get_facts` function can also be implemented using the `tasks` directive
+instead of the `roles` directive.  By using the `tasks` directive, you can
+control when the fact collection is run. 
+
+Below is an example of how to use the `get_facts` function with `tasks`.
+
+```
+- hosts: cisco_ios
+
+  tasks:
+    - name: collect facts from cisco ios devices
+      import_role:
+        name: ansible-network.cisco_ios
+        tasks_from: get_facts
+      vars:
+        subset:
+          - system
+          - interfaces
+```
+
+## Adding new parsers
+
+Over time new parsers can be added (or updated) to the role to add additional
+or enhanced functionality.  To add or update parsers perform the following
+steps:
+
+* Add (or update) command parser located ino `parse_templates/cli`
+
+* Update the `vars/get_facts_command_map.yaml` file to map the CLI command 
+to the parser
+
+The `get_facts_command_map.yaml` file provides a mapping between CLI command 
+and parser used to transform the output into Ansible facts. 
+
+### Understanding the mapping file
+
+The command map file provides the mapping between show command and parser file.
+The format of the file is a list of objects.  Each object supports a set of
+keys that can be configured to provide granular control over how each command
+is implemented.
+
+Command map entries support the following keys:
+
+#### command
+
+The `command` key is required and specifies the actual CLI command to execute
+on the target device.  The output from the command is then passed to the parser
+for further processing.
+
+#### parser
+
+The `parser` key provides the name of the parser used to accept the output from
+the command.  The parser value shoule be the command parser filename either
+relative to `parser_templates/cli` or absolute path.  This value is required.
+
+#### engine
+
+This key accepts one of two values, either `command_parser` or `textfsm_parser`. 
+This value instructs the the parsing function as to which parsing engine to 
+use to parse the output from the CLI command.
+
+This key is not required and, if not provided, the engine will assumed to be
+`command_parser`
+
+#### groups
+
+Commands can be contained in one (or more) groups to make it easy for playbook
+designers to filter specific facts to retreive from the network device.  The
+`groups` key must be a list and contain the groups the this command should be
+associated with.
+
+#### pre_hook
+
+The `pre_hook` key provides the path to the set of tasks to include prior
+to running the command on the CLI.  This is useful if there is a need to check
+if a command is available or supported on a particular version.
+
+#### post_hook
+
+The `post_hook` key provides the path to the set of tasks to include after the
+command has been run on the target device and its results have been parsed by
+the parser. 
+
+## Arguments
+
+### ios_get_facts_subset 
+
+Defines the subset of facts to collection when the `get_facts` function is
+called.  This value must be a list value and contain only the sub keys for the
+facts you wish to return.
+
+The default value is `default`
+
+#### Aliases
+
+* subset
+
+#### Current supported values for subset are
+
+* default
+* all
+* interfaces
+* bgp
+* lldp
+
+### ios_get_facts_command_map
+
+Defines the command / parser mapping file to use when the call to `get_facts`
+is made by the playbook.  Normally this value does not need to be modified but
+can be used to pass a custom command map to the function.
+
+The default value is `vars/get_facts_command_map.yaml`
+
+
+## Notes
+
+None
+
+