New module: cnos_showrun (#21752)

* initial commit of cnos_showrun

* Move roles to integration/roles directory and remove aliases file.

* update module short description

* Change module directory name to Lenovo

* change import cnos statement

lib/ansible/modules/network/lenovo/cnos_showrun.py

@@ -0,0 +1,139 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2017 Lenovo, Inc.
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+#
+# Module to display running config of Switches
+# Lenovo Networking
+#
+
+ANSIBLE_METADATA = {'status': ['preview'],
+                    'supported_by': 'community',
+                    'version': '1.0'}
+
+DOCUMENTATION = '''
+---
+module: cnos_showrun
+short_description: Collect the current running configuration on devices running Lenovo CNOS
+description:
+    - This module allows you to view the switch running configuration. It executes the display running-config CLI
+     command on a switch and returns a file containing the current running configuration of the target network
+     device. This module uses SSH to manage network device configuration.
+     The results of the operation will be placed in a directory named 'results'
+     that must be created by the user in their local directory to where the playbook is run.
+     For more information about this module from Lenovo and customizing it usage for your
+     use cases, please visit our [User Guide](http://systemx.lenovofiles.com/help/index.jsp?topic=%2Fcom.lenovo.switchmgt.ansible.doc%2Fcnos_showrun.html)
+version_added: "2.3"
+extends_documentation_fragment: cnos
+options: {}
+
+'''
+EXAMPLES = '''
+Tasks : The following are examples of using the module cnos_showrun. These are written in the main.yml file of the tasks directory.
+---
+- name: Run show running-config
+  cnos_showrun:
+      host: "{{ inventory_hostname }}"
+      username: "{{ hostvars[inventory_hostname]['username'] }}"
+      password: "{{ hostvars[inventory_hostname]['password'] }}"
+      deviceType: "{{ hostvars[inventory_hostname]['deviceType'] }}"
+      enablePassword: "{{ hostvars[inventory_hostname]['enablePassword'] }}"
+      outputfile: "./results/test_showrun_{{ inventory_hostname }}_output.txt"
+
+'''
+RETURN = '''
+  return value: |
+    On successful execution, the method returns a message in JSON format
+    [Running Configuration saved in file]
+    Upon any failure, the method returns an error display string.
+
+'''
+import sys
+import paramiko
+import time
+import argparse
+import socket
+import array
+import json
+import time
+import re
+try:
+    from ansible.module_utils import cnos
+    HAS_LIB = True
+except:
+    HAS_LIB = False
+from ansible.module_utils.basic import AnsibleModule
+from collections import defaultdict
+
+
+def main():
+    module = AnsibleModule(
+        argument_spec=dict(
+            outputfile=dict(required=True),
+            host=dict(required=True),
+            username=dict(required=True),
+            password=dict(required=True, no_log=True),
+            enablePassword=dict(required=False, no_log=True),),
+        supports_check_mode=False)
+
+    username = module.params['username']
+    password = module.params['password']
+    enablePassword = module.params['enablePassword']
+    cliCommand = "display running-config"
+    outputfile = module.params['outputfile']
+    hostIP = module.params['host']
+    output = ""
+
+    # Create instance of SSHClient object
+    remote_conn_pre = paramiko.SSHClient()
+
+    # Automatically add untrusted hosts (make sure okay for security policy in your environment)
+    remote_conn_pre.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+
+    # initiate SSH connection with the switch
+    remote_conn_pre.connect(hostIP, username=username, password=password)
+    time.sleep(2)
+
+    # Use invoke_shell to establish an 'interactive session'
+    remote_conn = remote_conn_pre.invoke_shell()
+    time.sleep(2)
+
+    # Enable and enter configure terminal then send command
+    output = output + cnos.waitForDeviceResponse("\n", ">", 2, remote_conn)
+
+    output = output + cnos.enterEnableModeForDevice(enablePassword, 3, remote_conn)
+
+    # Make terminal length = 0
+    output = output + cnos.waitForDeviceResponse("terminal length 0\n", "#", 2, remote_conn)
+
+    # Send the CLi command
+    output = output + cnos.waitForDeviceResponse(cliCommand + "\n", "#", 2, remote_conn)
+
+    # Save it into the file
+    file = open(outputfile, "a")
+    file.write(output)
+    file.close()
+
+    errorMsg = cnos.checkOutputForError(output)
+    if(errorMsg is None):
+        module.exit_json(changed=True, msg="Running Configuration saved in file ")
+    else:
+        module.fail_json(msg=errorMsg)
+
+if __name__ == '__main__':
+    main()

test/integration/roles/cnos_showrun/README.md

@@ -0,0 +1,94 @@
+# Ansible Role: cnos_showrun_sample - Displays Running Configuration inforamtion
+---
+<add role description below>
+
+This role is an example of using the *cnos_showrun.py* Lenovo module in the context of CNOS switch configuration. This module allows you to view the switch information. It executes the **display running-config** CLI command on a switch and returns a file containing all the system information of the target network device.
+
+The results of the operation can be viewed in results directory.
+
+For more details, see [Lenovo modules for Ansible: cnos_showrun](http://systemx.lenovofiles.com/help/index.jsp?topic=%2Fcom.lenovo.switchmgt.ansible.doc%2Fcnos_showrun.html&cp=0_3_1_0_4_0).
+
+
+## Requirements
+---
+<add role requirements information below>
+
+- Ansible version 2.2 or later ([Ansible installation documentation](http://docs.ansible.com/ansible/intro_installation.html))
+- Lenovo switches running CNOS version 10.2.1.0 or later
+- an SSH connection to the Lenovo switch (SSH must be enabled on the network device)
+
+
+## Role Variables
+---
+<add role variables information below>
+
+Available variables are listed below, along with description.
+
+The following are mandatory inventory variables:
+
+Variable | Description
+--- | ---
+`username` | Specifies the username used to log into the switch
+`password` | Specifies the password used to log into the switch
+`enablePassword` | Configures the password used to enter Global Configuration command mode on the switch (this is an optional parameter)
+`hostname` | Searches the hosts file at */etc/ansible/hosts* and identifies the IP address of the switch on which the role is going to be applied
+`deviceType` | Specifies the type of device from where the configuration will be backed up (**g8272_cnos** - G8272, **g8296_cnos** - G8296)
+
+
+## Dependencies
+---
+<add dependencies information below>
+
+- username.iptables - Configures the firewall and blocks all ports except those needed for web server and SSH access.
+- username.common - Performs common server configuration.
+- cnos_showrun.py - This modules needs to be present in the *library* directory of the role.
+- cnos.py - This module needs to be present in the PYTHONPATH environment variable set in the Ansible system.
+- /etc/ansible/hosts - You must edit the */etc/ansible/hosts* file with the device information of the switches designated as leaf switches. You may refer to *cnos_showrun_sample_hosts* for a sample configuration.
+
+Ansible keeps track of all network elements that it manages through a hosts file. Before the execution of a playbook, the hosts file must be set up.
+
+Open the */etc/ansible/hosts* file with root privileges. Most of the file is commented out by using **#**. You can also comment out the entries you will be adding by using **#**. You need to copy the content of the hosts file for the role into the */etc/ansible/hosts* file. The hosts file for the role is located in the main directory of the role.
+
+```
+[cnos_showrun_sample]
+10.241.107.39   username=<username> password=<password> deviceType=g8272_cnos
+10.241.107.40   username=<username> password=<password> deviceType=g8272_cnos
+```
+    
+**Note:** You need to change the IP addresses to fit your specific topology. You also need to change the `<username>` and `<password>` to the appropriate values used to log into the specific Lenovo network devices.
+
+
+## Example Playbook
+---
+<add playbook samples below>
+
+To execute an Ansible playbook, use the following command:
+
+```
+ansible-playbook cnos_showrun_sample.yml -vvv
+```
+
+`-vvv` is an optional verbos command that helps identify what is happening during playbook execution. The playbook for each role is located in the main directory of the solution.
+
+```
+ - name: Module to do Show Sys Info
+   hosts: cnos_showrun_sample
+   gather_facts: no
+   connection: local
+   roles:
+    - cnos_showrun_sample
+```
+
+
+## License
+---
+<add license information below>
+Copyright (C) 2017 Lenovo, Inc.
+
+This file is part of Ansible
+
+Ansible is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+
+Ansible is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with Ansible.  If not, see <http://www.gnu.org/licenses/>.

test/integration/roles/cnos_showrun/cnos_showrun_sample_hosts

@@ -0,0 +1,15 @@
+# You have to paste this dummy information  in /etc/ansible/hosts
+#    Notes:
+#    - Comments begin with the '#' character
+#    - Blank lines are ignored
+#    - Groups of hosts are delimited by [header] elements
+#    - You can enter hostnames or ip addresses
+#    - A hostname/ip can be a member of multiple groups
+#
+# In the /etc/ansible/hosts file u have to enter [cnos_facts_sample] tag
+# Following you should specify IP Adresses details 
+# Please change <username> and <password> with appropriate value for your switch.
+
+[cnos_showrun_sample]
+10.241.107.39   username=<username> password=<password> deviceType=g8272_cnos
+

test/integration/roles/cnos_showrun/tasks/main.yml

@@ -0,0 +1,6 @@
+# This contain sample show rnunning config tasks
+---
+- name: Test Running Configurations
+  cnos_showrun: host={{ inventory_hostname }} username={{ hostvars[inventory_hostname]['username']}}  password={{ hostvars[inventory_hostname]['password']}} enablePassword='{{item.enablePassword}}' outputfile=./results/cnos_showrun_{{ inventory_hostname }}_output.txt
+  with_items: "{{test_showrun_data}}"
+# Completed file

test/integration/roles/cnos_showrun/vars/main.yml

@@ -0,0 +1,3 @@
+---
+test_showrun_data:
+  - {enablePassword: "anil"}