sergbgan / racc

[Ansible] Run Arbitrary CLI Commands on a variety of network devices

Run Arbitrary CLI Commands (racc)

This playbook runs arbitrary commands on a given node, stores the output in a flat text file, and archives the entire "run" in an archive file for easy copying to management stations via SCP. It is generally used for configuration backups, hardware inventory, and license information.

Contact information: Email: [email protected] Twitter: @nickrusso42518

• Supported platforms
• Variables
• Task summary
• Output files

Supported platforms

Any host with an Ansible *_command module can be supported, including non-Cisco devices. The playbook currently provides Ansible task files for Cisco IOS/IOS-XE, Cisco IOS-XE, and Cisco ASA device types. To add a new device type, create a new task file in the tasks/ folder along with a corresponding group_vars/ and inventory entry. These are all easy tasks given the abstract architecture of this playbook.

Testing was conducted on the following platforms and versions:

• Cisco CSR1000v, version 16.08.01a, running in AWS
• Cisco XRv9000, version 6.3.1, running in AWS
• Cisco ASAv, version 9.9.1, running in AWS

$ cat /etc/redhat-release
Red Hat Enterprise Linux Server release 7.4 (Maipo)

$ uname -a
Linux ip-10-125-0-100.ec2.internal 3.10.0-693.el7.x86_64 #1 SMP
  Thu Jul 6 19:56:57 EDT 2017 x86_64 x86_64 x86_64 GNU/Linux

$ ansible --version
ansible 2.4.3.0
  config file = /etc/ansible/ansible.cfg
  configured module search path = [u'/usr/share/my_modules']
  ansible python module location = /usr/lib/python2.7/site-packages/ansible
  executable location = /usr/bin/ansible
  python version = 2.7.5 (default, May  3 2017, 07:55:04)
    [GCC 4.8.5 20150623 (Red Hat 4.8.5-14)]

Variables

Nested inside the inventory file itself are several variables which are not often modified:

• remove_files: A boolean true/false question that governs whether items in the files/ folder are removed after a playbook run. Normally, this is set to true because the final archive is what really matter, and retaining all the uncompressed text files on the control machine is not a long-term solution. Setting this to false is useful for quick tests or troubleshooting.
• archive_format: Determines what kind of archive to create when the archive moduel is called. Any option supported by the version of Ansible in use can be used here. Some examples include zip, gz, bz2, xz, and tar as of Ansible 2.5. The zip format is usually appropriate when transferring to Windows-based SCP servers, and that is the default.
• scp: Nested dictionary containing two subkeys below.
  • user: The SCP username that can write files to the SCP server.
  • host: The SCP server FQDN/IP address. Under its root directory, a directory called racc/ should be created. This is where the archives generated by this playbook are copied.

There are three group_vars/ files for routers, switches, and firewalls. Each one has a key of command_list which specifies a list of dictionaries as shown below. The file_suffix value specifies what is written to the end of the file name, and the command value is the literal command to be issued to the device. CLI output redirection (pipes) are supported. It is recommended to type the entire command into the command value since these are printed to stdout during execution. Using abbreviated commands may confuse operators less familiar with some network CLIs.

Note that these are just examples and it is common to adjust the command_list on a per-run basis. For example, if collecting all routing tables is important to quickly troubleshoot a routing loop, simply add show ip route with a corresponding file suffix to the list, and run the playbook.

# group_vars/ios_router.yml
---
command_list:
  - file_suffix: "cfg"
    command: "show running-config"
  - file_suffix: "inv"
    command: "show inventory"
  - file_suffix: "lic"
    command: "show license all"
  - file_suffix: "ver"
    command: "show version"
...

Task summary

To make the playbook easier to read and troubleshoot, whenever a command is issued on a device, both the inventory hostname and the command being issued are printed to stdout. The example below shows a sample run with a variety of devices.

TASK [ASA >> Gather Cisco ASA information]
ok: [asav1] => (item=show running-config)
ok: [asav1] => (item=show inventory)
ok: [asav1] => (item=show version)

TASK [IOSXR >> Gather Cisco IOS-XR information]
ok: [xrv1] => (item=show running-config)
ok: [xrv1] => (item=show inventory)
ok: [xrv1] => (item=show license all)
ok: [xrv1] => (item=show version)

TASK [IOS >> Gather Cisco IOS/IOS-XE information]
ok: [csr1] => (item=show running-config)
ok: [csr2] => (item=show running-config)
ok: [csr1] => (item=show inventory)
ok: [csr2] => (item=show inventory)
ok: [csr1] => (item=show license all)
ok: [csr2] => (item=show license all)
ok: [csr1] => (item=show version)
ok: [csr2] => (item=show version)

Output files

At the end of the playbook, assuming that remove_files is set to false for the purpose of discussion, the following filesystem components are created.

For each host against which this playbook runs, N files are generated, where N is the number of elements in the relevant command_list. Ansible inventory hostname and the date/time group (DTG) in UTC are included in the file names for easy identification. All files are written to files/ directory and are ignored by git. The format of all text files is <hostname>_<dtg>_<file_suffix>.txt while the parent directory format is <hostname>_<dtg>/.

$ tree files/
files/
├── asav1_20180603T070140
│   ├── asav1_20180603T070140_cfg.txt
│   ├── asav1_20180603T070140_inv.txt
│   └── asav1_20180603T070140_ver.txt
├── csr1_20180603T070140
│   ├── csr1_20180603T070140_cfg.txt
│   ├── csr1_20180603T070140_inv.txt
│   ├── csr1_20180603T070140_lic.txt
│   └── csr1_20180603T070140_ver.txt
├── csr2_20180603T070140
│   ├── csr2_20180603T070140_cfg.txt
│   ├── csr2_20180603T070140_inv.txt
│   ├── csr2_20180603T070140_lic.txt
│   └── csr2_20180603T070140_ver.txt
└── xrv1_20180603T070140
    ├── xrv1_20180603T070140_cfg.txt
    ├── xrv1_20180603T070140_inv.txt
    ├── xrv1_20180603T070140_lic.txt
    └── xrv1_20180603T070140_ver.txt

The actual text output is shown below. The exclamation-mark delimeters are useful when concatenating multiple files together since determining where one output ends and another starts is difficult otherwise.

$ cat files/csr1_20180603T070140/*
[snip, running-config output omitted for brevity]
!!!
!!!   END OUTPUT FROM: show running-config
!!!
!!!
!!! BEGIN OUTPUT FROM: show inventory
!!!
NAME: "Chassis", DESCR: "Cisco CSR1000V Chassis"
PID: CSR1000V          , VID: V00  , SN: 9VCVGDCB4JW

NAME: "module R0", DESCR: "Cisco CSR1000V Route Processor"
PID: CSR1000V          , VID: V00  , SN: JAB1303001C

NAME: "module F0", DESCR: "Cisco CSR1000V Embedded Services Processor"
PID: CSR1000V          , VID:      , SN:
!!!
!!!   END OUTPUT FROM: show inventory
!!!
!!!
!!! BEGIN OUTPUT FROM: show license all
!!!
License Store: Primary License Storage
!!!
!!!   END OUTPUT FROM: show license all
!!!
!!!
!!! BEGIN OUTPUT FROM: show version
!!!
Cisco IOS XE Software, Version 16.08.01a
[snip, extra output omitted for brevity]

Finally, the playbook prints out a shell command that can be copy/pasted by the user to quickly SCP the archive to an SCP server, assuming an FQDN/IP has been specified for it. This is useful for those unfamiliar with the Linux scp command.

scp archives/commands_20180603T070140.zip [email protected]:/racc/