initial commit of role

.gitignore

@@ -0,0 +1 @@
+*.pyc

.travis.yml

@@ -0,0 +1,29 @@
+---
+language: python
+python: "2.7"
+
+# Use the new container infrastructure
+sudo: false
+
+# Install ansible
+addons:
+  apt:
+    packages:
+    - python-pip
+
+install:
+  # Install ansible
+  - pip install ansible
+
+  # Check ansible version
+  - ansible --version
+
+  # Create ansible.cfg with correct roles_path
+  - printf '[defaults]\nroles_path=../' >ansible.cfg
+
+script:
+  # Basic role syntax check
+  - ansible-playbook tests/test.yml -i tests/inventory --syntax-check
+
+notifications:
+  webhooks: https://galaxy.ansible.com/api/v1/notifications/

CHANGELOG.rst

@@ -0,0 +1,21 @@
+===============================
+cisco_ios
+===============================
+
+devel
+=====
+
+New Functions
+-------------
+
+- NEW `get_facts` for collecting facts from nxos devices
+- NEW `get_config` facts to return the active configuration as parsed facts
+- NEW `load_config` loads configuration onto remote device
+
+
+Major Changes
+-------------
+
+- Initial release of the `cisco_ios` role.
+- NEW facts subset `system`
+- NEW facts subset `hostname`

README.md

@@ -0,0 +1,32 @@
+# cisco_ios
+
+This Ansible Network role provides a set of platform dependent fuctions that
+are designed to work with Cisco IOS network devices.  The functions included
+int his role inlcuding both configuration and fact collection.
+
+## Requirements
+
+* Ansible 2.6 or later
+* Ansible Network Engine Role 2.6.0 or later
+
+## Functions
+
+This section provides a list of the availabe functions that are including
+in this role.  Any of the provided functions can be implemented in Ansible
+playbooks to perform automation activities on Cisco IOS devices.
+
+Please see the documentation link for each function for details on how to use
+the function in an Ansible playbook.
+
+* get_facts [[source]](https://github.com/ansible-network/cisco_ios/blob/devel/tasks/get_facts.yaml) [[docs]](https://github.com/ansible-network/cisco_ios/blob/devel/docs/get_facts.md)
+* get_config [[source]](https://github.com/ansible-network/cisco_ios/blob/devel/tasks/get_config.yaml) [[docs]](https://github.com/ansible-network/cisco_ios/blob/devel/docs/get_config.md)
+* load_config [[source]](https://github.com/ansible-network/cisco_ios/blob/devel/tasks/load_config.yaml) [[docs]](https://github.com/ansible-network/cisco_ios/blob/devel/docs/load_config.md)
+
+
+## License
+
+GPLv3
+
+## Author Information
+
+Ansible Network Community

defaults/main.yml

@@ -0,0 +1,17 @@
+---
+# defaults file for ansible-network.cisco_ios
+#
+ios_working_dir: ~/.ansible/ios
+
+ios_config_file: "{{ config_file | default(None) }}"
+ios_config_text: "{{ config_text | default(None) }}"
+ios_config_replace: "{{ replace | default(False) }}"
+ios_config_working_dir: ~/.ansible/ios
+ios_config_temp_config_file: "tmp_{{ inventory_hostname_short }}"
+ios_config_checkpoint_filename: chk_ansible
+ios_config_remove_temp_files: "{{ remove_temp_files | default(True) }}"
+ios_config_rollback_enabled: "{{ rollback | default(True) }}"
+
+ios_config_source:
+  running: show running-config
+  startup: show startup-config

docs/get_config.md

@@ -0,0 +1,78 @@
+# Get configuration from device
+The `get_config` function will return the either the current active or current
+saved configuration from an Cisco IOS devices.  This function is only
+supported over `network_cli` connections.
+
+The `get_config` function will also parse the device active configuration into
+a set of host facts during its execution.  All of the parsed facts are stored
+in the ``cisco_ios.config`` top level facts key.
+
+## How to get the device configuration
+Retrieving the configuration from the device involves just calling the
+`get_config` function from the role.  By default, the `get_config` role will
+return the device active (running) configuraiton.  The text configuration will
+be returned as a fact for the host.  The configuration text is stored in the
+`configuration` fact.
+
+Below is an example of calling the `get_config` function from the playbook.
+
+```
+- hosts: cisco_ios
+
+  roles:
+    - name ansible-network.cisco_ios
+      function: get_config
+```
+
+The above playbook will return the current running config from each host listed
+in the `cisco_ios` group in inventory.
+
+### Get the current startup config
+By default the `get_config` function will return the device running
+configuration.  If you want to retrieve the device startup configuration, set
+the value of `source` to `startup`.
+
+```
+- hosts: cisco_ios
+
+  roles:
+    - name ansible-network.cisco_ios
+      function: get_config
+      source: startup
+```
+
+### Implement using tasks
+The `get_config` function can also be implemented in the `tasks` during the
+playbook run using either the `include_role` or `import_role` modules as shown
+below.
+
+```
+- hosts: cisco_ios
+
+  tasks:
+    - name: collect facts from cisco ios devices
+      import_role:
+        name: ansible-network.cisco_ios
+        tasks_from: get_config
+```
+
+## How to add additional parsers
+
+The configuration facts are returned by this function are parsed using the
+parsers in the `parser_templates/config' folder.  To add a new parser, simply
+create a PR and add the new parser to the folder.  Once merged, the
+`get_config` function will automatically use the new parser.
+
+## Arguments
+
+### source
+
+Defines the configuration source to return from the device.  This argument
+accepts one of `running` or `startup`.  When the value is set to `running`
+(default), the current active configuration is returned.  When the value is set
+to `sartup`, the device saved configuration is returned.
+
+The default value is `running`
+
+## Notes
+None

docs/get_facts.md

@@ -0,0 +1,102 @@
+# 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 and set one or more sub 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: 
+        - interfaces
+        - 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 to the role to make it easy to return
+structed facts from network devices.  To add a new parser to this role, simply
+submit a pull request with the following changes:
+
+1) New /updated parser in `parse_templates/cli`
+
+2) Update `vars/get_facts.yaml` and add the new parser and cooresponding `show` command
+
+Once added, the command will be executed and the parsed results returned as
+Ansible facts.
+
+## Arguments
+
+### 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 `all`
+
+#### Current supported values for subset are
+
+* system
+* hostname
+
+
+## Notes
+
+None
+
+