updated all modules to work with Ansible 2.5 and moved old version to ansible-2.3 branch

Author: Adisorn Ermongkonchai

LICENSE

@@ -1,66 +1,318 @@
-Ansible Test Setup
-==================
+# Introduction to IOS-XR Ansible
 
-- Create 2 XRV9K (Sunstone) VMs and 1 Linux server on MB Cloud following
-  the instruction in the link below
-  * http://tc-midnight.cisco.com:8080/wiki/MB%20Cloud%20XR
+In the nutshell, Ansible is an automation tool for configuring system,
+deploying software, and orchestrating services. Unlike Puppet and Chef which
+is an agent-based architecture, Ansible does not require daemon running or
+agent pre-installed on the target nodes to interact with a server.
+Ansible could be specified to run either on a local server or on a remote
+node.
 
-  NOTE:
-    The nightly build images provided on the MB Cloud is based on xr-dev.
-    Unfortunately, the missing Python libraries were committed to r60y
-    (CSCux90222).  These missing libraries are required for Ansible to run
-    in "remote" mode.  The tests that were exercising here run on "local" mode
+The different between local and remote connection mode in Ansible is basically
+where the script (so-called Ansible module) is being run.  For the **remote**
+mode, Ansible automatically attempts to establish SSH connection to the remote
+node.  Once established, it transfers the script and runs it on the remote node.
+The script responds to the server in JSON formatted text. This mode requires
+setting up third-party namespace (TPNNS) on the IOS-XR node.
 
-- You will also need k9sec security package to be installed in your XRV9K VMs.
-  Using the following example command to install the k9sec pacakge.
-  * install update source tftp://192.168.1.1 xrv9k-iosxr-security-1.0.0.0-r60125I
-  * show install active
+As for the **local** mode, Ansible run the module script on the local server.
+The script has to establish a connection to the remote node itself. The
+local mode module uses Ansible network module to establish SSH connection
+to the IOS-XR console to run CLI command.
 
-- Pull YDK from the gitlab.cisco.com into the Linux server created
-  * git clone [email protected]:ydk-dev/ydk-py.git
+There are 6 different ways to access IOS-XR in local mode.
 
-- Pull Ansible Core modules
+1. **Console CLI** - connect to IOS-XR console through SSH port 22 and use
+                  CLI commands.
+2. **TPNNS CLI** - connect to IOS-XR Linux shell through SSH port 57722
+                  and use helper programs, /pkg/bin/xr_cli or /pkg/sbin/config.
+3. **Raw XML** - connect to IOS-XR console through SSH port 22 to exchange XML
+                  construct with IOS-XR xml agent.
+4. **Raw NETCONF 1.0** - connect to IOS-XR console through SSH port 22 to
+                  exchange NETCONF 1.0 XML construct with IOS-XR netconf agent.
+5. **Raw NETCONF 1.1** - connect to IOS-XR console through SSH port 830 to
+                  exchange NETCONF 1.1 XML construct with IOS-XR netconf-yang
+                  agent.
+6. **YDK NETCONF** - use the Cisco YDK API service to manage IOS-XR device
+                  through SSH port 830.
+
+Managing the IOS-XR device in the remote mode required TPNNS through SSH
+port 57722 with the helper programs, /pkg/bin/xr_cli and /pkg/sbin/config, to
+deliver CLI commands and configuration to the IOS-XR, respectively.  This
+remote mode connection is identical to TPNNS CLI running in local mode except
+for how the SSH connection is being established and where the script is run.
+
+# Understand connection variants
+With different variants for local and remote modes mentioned earlier, before
+implementing Ansible modules, one needs to be aware of their limitation.
+
+**Linux-based vs. QNX-based IOS-XR**
+
+  * QNX-based IOS-XR can only run in local mode
+  * Earlier version of Linux-based IOS-XR also can only run in local mode due
+    to incomplete Python libraries
+  * Linux-based IOS-XR (eXR 6.0.2 or later) can run both remote and local modes
+
+**CLI vs. XML/NETCONF**
+
+  * With CLI mode, you can do all CLI commands as you would do interactively.
+  * The XML/NETCONF mode allows you to use Cisco XML or NETCONF commands in XML
+    construct to configure IOS-XR.
+
+**Console CLI vs. TPNNS CLI**
+
+  * Console CLI allows you to do all CLI commands as you would do interactively.
+  * TPNNS CLI can either be implemented in local or remote mode.  It connects
+    to IOS-XR Linux shell and requires helper programs, /pkg/bin/xr_cli or
+    /pkg/sbin/config, to deliver CLI commands or configure IOS-XR, respectively.
+    Currently, "commit replace" is not supported by /pkg/sbin/config.
+
+**Raw XML/NETCONF vs. YDK NETCONF**
+
+  * Raw NETCONF mode allows you to configure IOS-XR using NETCONF commands in
+    RPC XML construct through standard SSH port 22 with termination sequence
+    **]]>]]>** and port 830 with **##** termination sequence.  The response is
+    also in RPC XML construct.
+  * Alternatively, you can use YDK python API to configure IOS-XR through SSH
+    port 830.  The API automatically generates the RPC XML construct based on
+    the YANG model provided.
+    
+**NOTE:** IOS-XR NETCONF 1.1 XML construct is based on Cisco IOS-XR YANG model 
+      which is currently limited, e.g. it doesn’t support SMU package 
+      installation.  Although limited, the Cisco IOS-XR YANG definitions will
+      continue to grow as more definitions are added and would be a preferred
+      method for accessing IOS-XR. 
+
+# Dependencies
+
+- manageability (mgbl) and security (k9sec) packages are required on IOS-XR.
+
+- Pull YDK from the github onto a Linux server
+  * git clone https://github.com/CiscoDevNet/ydk-py
+
+- Pull Ansible Core modules onto a Linux server
   * git clone git://github.com/ansible/ansible.git --recursive
 
-  Addition read on Ansible installation is here
+  Additional read on Ansible installation is here
   * http://docs.ansible.com/ansible/intro_installation.html#getting-ansible
 
-Running Ansible
-===============
+# Directories structure
 
-- Edit and source Ansible, YDK, and Python environment to point to your
-  installed applications
-  * cd iosxr/local
-  * vi ansible_env
-  * source ansible_env
+```
+iosxr-ansible
+├── config
+├── local
+│   ├── common
+│   ├── library
+│   └── samples
+│       ├── cli
+│       ├── tpnns
+│       ├── xml
+│       └── ydk
+└── remote
+    ├── library
+    └── samples
+        └── install
 
-- Edit "ansible_hosts" file to change "ss-xr" host IP to your 2 XRV9K VMs
+Directory               Description
+
+config                  Contains sample IOS-XR configuration files
+local/library           Contains Ansible modules for local mode
+local/samples/cli       Contains sample playbooks using Console CLI
+local/samples/tpnns     Contains sample playbooks using TPNNS access method
+local/samples/xml       Contains sample RPC XML used with iosxr_netconf_send
+local/samples/ydk       Contains sample playbooks using YDK API's
+local/common            Contains IOS-XR common Python functions
+remote/library          Contains Ansible modules for remote mode
+remote/samples          Contains sample playbooks using Namespace Shell CLI
+remote/samples/install  Contains additional playbooks showing direct access
+                        to IOS-XR using shell
+```
 
-- Create default crypto key in your XRV9K VMs (select default 1024 bits)
-  * crypto key generate rsa 
-  * show crypto key mypubkey rsa
+# IOS-XR setup
 
+NOTE: Some of these instruction may require root access for setting IOS-XR.
+
+- Create default crypto key on your XRV9K VMs (select default 2048 bits)
+
+```
+  RP/0/RP0/CPU0:ios# crypto key generate rsa 
+  RP/0/RP0/CPU0:ios# show crypto key mypubkey rsa
+```
 - Configure IOS-XR as shown in ss1.cfg and ss2.cfg for both XRV9K VMs.
   Make any necessary changes, such as, management IP address and hostname
   Here are required configuration
-  * ssh server v2
-  * ssh server netconf vrf default
-  * ssh server logging
-  * xml agent ssl
-  * netconf agent tty
-  * netconf-yang agent ssh
-
-- Make sure you can connect to both XRV9K VMs management port
-  * ssh [email protected]
-  * ssh [email protected] "show run"
-
-  NOTE:
-    Currently, crypto key import is not working (CSCuy80921) so when
-    using Ansible playbook, password is required.
-
-Additional Notes
-================
-
-- How to GitLab?
-  * https://cisco.jiveon.com/docs/DOC-42998
+  
+```
+  RP/0/RP0/CPU0:ios# conf t
+  RP/0/RP0/CPU0:ios(config)# ssh server v2
+  RP/0/RP0/CPU0:ios(config)# ssh server netconf vrf default
+  RP/0/RP0/CPU0:ios(config)# ssh server logging
+  RP/0/RP0/CPU0:ios(config)# xml agent ssl
+  RP/0/RP0/CPU0:ios(config)# xml agent tty
+  RP/0/RP0/CPU0:ios(config)# netconf agent tty
+  RP/0/RP0/CPU0:ios(config)# netconf-yang agent ssh
+  RP/0/RP0/CPU0:ios(config)# commit
+```
+- Optional SSH key setup allows user to connect to IOS-XR without password.
+  First, generate base64 SSH key file on Ansible Server and copy it to your
+  tftpboot directory.
+
+```
+  cut -d" " -f2 ~/.ssh/id_rsa.pub | base64 -d > ~/.ssh/id_rsa_pub.b64
+  cp ~/.ssh/id_rsa_pub.b64 /tftpboot
+```
+- After IOS-XR is ready, at IOS-XR console prompt, import SSH key as followed
+
+```
+  RP/0/RP0/CPU0:ios# crypto key import authentication rsa tftp://192.168.1.1/id_rsa_pub.b64
+  RP/0/RP0/CPU0:ios# show crypto key authentication rsa
+```
+- Now make sure you can connect to both XRV9K VMs management port from Linux host
+
+```
+  ssh [email protected]
+  ssh [email protected] "show run"
+```
+
+- Setup the third party namespace (TPNNS) access on IOS-XR.  Please refer to the
+  following link for instruction and make sure you can SSH to the IOS-XR
+  through port **57722**.
+  
+    http://www.cisco.com/c/en/us/td/docs/iosxr/ncs5500/app-hosting/b-application-hosting-configuration-guide-ncs5500/b-application-hosting-configuration-guide-ncs5500_chapter_00.html
+
+    NOTE: Newer version of IOS-XR has renamed tpnns to operns resulting in filename changed, e.g. sshd_tpnns to sshd_operns
+    
+    ```
+    RP/0/RP0/CPU0:aermongk-ss1# run
+    [xr-vm_node0_RP0_CPU0:~]$ . /etc/init.d/operns-functions
+    [xr-vm_node0_RP0_CPU0:~]$ operns_wait_until_ready
+    [xr-vm_node0_RP0_CPU0:~]$ service sshd_operns start
+    ```
+    
+    To access IOS-XR without password, you will also need to add your 
+    Linux server SSH public key (~/.ssh/id_rsa.pub) to your IOS-XR
+    \<your_xr_home\>/.ssh/authorized_key file by using **ssh-copy-id**
+    command, for example,
+
+```
+  ssh-copy-id -i ~/.ssh/id_rsa.pub -p 57722 [email protected]
+```
+
+- If your Linux server support HTTPS and you want a secure communication during
+  SMU package installation, you can import your certificate from Linux to
+  IOS-XR. The IOS-XR certificate store is in /etc/ssl/certs/ca-certificates.crt.
+  Basically, you just need to cut and paste your certificate text to this file.
+  
+# Local mode setup and test
+
+- Edit and source Ansible, YDK, and Python environment to point to your
+  installed applications
+
+```
+  cd iosxr-ansible/local
+  vi ansible_env
+  source ansible_env
+```
+- Edit "ansible_hosts" file to change "ss-xr" host IP to your 2 XRV9K VMs
+
+```
+  [ss-xr]
+  192.168.1.120 ansible_ssh_user=cisco
+  192.168.1.121 ansible_ssh_user=cisco
+```
+- Run sample playbooks
+    * Some of sample playbooks will require changes to fit your need
+      e.g. edit iosxr_install_package.yml to change location of your package.
+
+```
+  cd samples
+  ansible-playbook iosxr_get_config.yml
+  ansible-playbook iosxr_clear_log.yml
+  ansible-playbook iosxr_cli.yml -e 'cmd="show interface brief"'
+  ansible-playbook iosxr_netconf_send.yml -e "xml_file=xml/nc11_show_install_active.xml"
+```
+# Remote mode setup and test
+
+- Configure Ansible configuration to use port 57722 by editing your ansible
+  config file (default is /etc/ansible/ansible.cfg) with following values
+    
+```
+    [defaults]
+    remote_port = 57722
+```
+- Edit Ansible and Python environment as needed in ansible_env and source it
+
+```
+  cd iosxr-ansible/remote
+  vi ansible_env
+  source ansible_env
+```
+- Edit "ansible_hosts" file to change "ss-xr" host IP to your 2 XRV9K VMs
+
+```
+  [ss-xr]
+  192.168.1.120 ansible_ssh_user=cisco
+  192.168.1.121 ansible_ssh_user=cisco
+```
+- Run sample playbooks
+    * Some of sample playbooks will require changes to fit your need
+      e.g. edit iosxr_install_package.yml to change location of your package.
+
+```
+  cd samples
+  ansible-playbook iosxr_get_config.yml
+  ansible-playbook iosxr_cli.yml -e 'cmd="show interface brief"'
+```
+# Local Mode Modules Description
+
+  * iosxr_clear_config - Clear all configurations on IOS-XR device
+  * iosxr_clear_log - Clear system log
+  * iosxr_cli - Run a command on IOS-XR device
+  * iosxr_diff_config - Compare a given configuration file with the running configuration
+  * iosxr_get_config - Show running configuration on IOS-XR device
+  * iosxr_get_facts - Get status and information from IOS-XR device
+  * iosxr_install_config - Commit a configuration file on IOS-XR device
+  * iosxr_install_key - Install BASE64 crypto key on IOS-XR device
+  * iosxr_install_package - Install SMU package on IOS-XR device
+  * iosxr_nc10_send - Send NETCONF 1.0 XML file to IOS-XR device
+  * iosxr_nc11_send - Send NETCONF-YANG 1.1 XML file to IOS-XR device
+  * iosxr_reload - Reload IOS-XR device
+  * iosxr_rollback - Rollback configuration on IOS-XR device
+  * iosxr_upgrade_package - Upgrade packages on IOS-XR device
+  * iosxr_xml_send - Performs Cisco XML request to IOS-XR device
+  * xr32_install_package - Run install commands on IOS-XR device
+
+  **Sample Modules using Cisco YDK services**
+
+  * iosxr_show_install_active - show active package
+  * iosxr_show_install_committed - show committed package
+  * iosxr_show_install_inactive - show inactive package in the repository
+  * iosxr_show_install_last_log - show installation log
+  * iosxr_show_install_log - show installation log
+  * iosxr_show_install_request - show current install request
+  * iosxr_show_install_version - show current software install version
+
+# Remote Mode Modules Description
+
+  * iosxr_clear_log - Clear system log
+  * iosxr_cli - Run a command on IOS-XR device
+  * iosxr_get_config - Show running configuration on IOS-XR device
+  * iosxr_get_facts - Get status and information from IOS-XR device
+  * iosxr_install_config - Commit configuration file on IOS-XR device
+  * iosxr_install_package - Install SMU package on IOS-XR device
+  * iosxr_reload - Reload IOS-XR device
+  * iosxr_rollback - Rollback configuration on IOS-XR device
+
+# IOS-XR platforms tested
+
+- XRv9K (sunstone)
+- ASR9K (classic 32-bit QNX IOS-XR)
+- NCS1K (rosco)
+- NCS5500 (fretta)
+
+# Ansible Test Setup
+
+  * 1 or more IOS-XR device(s)
+  * 1 Linux server (ubuntu 15.10)
+  * Create network connection between IOS-XR device and Linux server