Powered by Genie
And the pyATS framework
Featuring
Welcome!
Magic Carpet is an infrastructure as code and network automation tool that transforms CLI command and REST API data, using the Cisco Genie parsers, the Cisco pyATS Python library, and Python to automatically generate, at scale, better documentation from the output; send #chatbots; #voicebots; even #phonebots!
A Nice JSON file (command_output.json)
A Nice YAML file (command_output.yaml)
A CSV spreadsheet (command_output.csv)
A Markdown file (command_output.md)
An HTML page (comand_output.html)
An interactive HTML Mind Map (command_output_mind_map.html)
Instant messages to WebEx, Slack, Discord, and others
Text-to-Speech, in over 200 languages, creating customized MP3 audio files in a human voice
Phone calls to any phone number in the world
Instantly. With the push of a button.
The main Genie documentation guide:
https://developer.cisco.com/docs/genie-docs/
The main pyATS documentation guide:
https://developer.cisco.com/docs/pyats/
The Cisco's Test Automation Solution
The Cisco Test Automation GitHub repository
https://github.com/CiscoTestAutomation
Here are the pyATS documentation guides on Testbed files and Device Connectivity:
Testbed and Topology Information: https://pubhub.devnetcloud.com/media/pyats/docs/topology/index.html
Device Connection: https://pubhub.devnetcloud.com/media/pyats-getting-started/docs/quickstart/manageconnections.html
Testbed File Example: https://pubhub.devnetcloud.com/media/pyats/docs/topology/example.html
Device Connections: https://developer.cisco.com/docs/pyats/#!connection-to-devices
Secret Strings (how I encrypted the enable secret in my testbed file): https://pubhub.devnetcloud.com/media/pyats/docs/utilities/secret_strings.html
Requirements (instructions below)
Virtual Environment
We recommend running Magic Carpet in a Python virtual environment while testing or developing. This will help keep your host system clean and allow you to have multiple environments to try new things. If you are not using a virtual environment, start at the download/clone step below.
You will also need Python 3, pip, and venv installed on your host system.
In your project directory, create your virtual environment
python3 -m venv envActivate (use) your new virtual environment (Linux):
source env/bin/activateDownload or clone the Magic Carpet repository:
git clone https://github.com/automateyournetwork/magic_carpetInstall pyATS, Rich, and markmap into your environment:
pip install pyats[full]pip install richsudo apt update
sudo apt install npm
sudo npm install markmap-cli -gIf you run into any installation issues with pyATS, please see the installation guide here: https://pubhub.devnetcloud.com/media/pyats-getting-started/docs/install/installpyATS.html
You're now ready to fly!
When you are finished with your pyATS session, enter the deactivate command to exit the python virtual environment.
How to update the appropriate testbed/testbed_*.yaml file to reflect your device inventory and configuration:
Devices:
4500: <-- Update to your router hostname (MUST MATCH HOSTNAME)
alias: <-- Update your alias; this can be the hostname or any friendly name you want
type: <-- This should be "router" for L3 routers with ARP tables and VRFs and such
platform: <-- Your Catalyst IOS-XE Platform
username: <-- Your Cisco device username
password: <-- Your Enable Secret; It is strongly recommended to follow the "Secret Strings" link to encrypt your secrets
ip: <-- The management IP address of your router
Copy & Paste and make each device unique to scale this up to many routers
Devices:
3850: <-- Update to your switch hostname (MUST MATCH HOSTNAME)
9300: <-- Update to your switch hostname (MUST MATCH HOSTNAME)
alias: <-- Update your alias; this can be the hostname or any friendly name you want
type: <-- This should be "switch" for L2 switches without ARP tables or VRFs but features like PoE
platform: <-- Your Catalyst IOS-XE Platform
username: <-- Your Cisco device username
password: <-- Your Enable Secret; It is strongly recommended to follow the "Secret Strings" link to encrypt your secrets
ip: <-- The management IP address of your router
Copy & Paste and make each device unique to scale this up to many routers
Magic Carpet now connects to the following Cisco.com APIs:
-
Recommended Software Release (using the real version of software from your devices)
-
Serial Number 2 Infomation (using the real serial numbers, for every part, from your devices)
-
Product Security Incident Response Team (PSIRT) (using the real version of software from your device)
Take Magic Carpet to the Cloud
You can create a testbed file using an Excel spreadsheet (see testbed/SampleTestbedFile.xlsx), this is useful if you are not familiar with YAML and/or have a long list of devices where copying and pasting in Excel would be easier.
- Edit the relevant fields in the sample file.
- Run the following command:
pyats create testbed file --path SampleTestbedFile.xlsx --output my_testbed.yaml- That's it. You're good to go!
Ensure SSH connectivity at from your host's CLI, and run the pyATS job:
Cisco IOS-XE:
pyats run job IOS_XE_magic_carpet_job.py --testbed-file testbed/testbed_ios_xe.yamlCisco DevNet Sandbox for CSR1000v (see more here)
pyats run job DevNet_Sandbox_CSR_magic_carpet_job.py --testbed-file testbed/testbed_DevNet_CSR1000v_Sandbox.yamlJunOS 17 / 18 / 19:
pyats run job JUNOS_magic_carpet_job.py --testbed-file testbed/testbed_juniper.yamlF5 BIG-IP:
python3 F5_magic_carpet.pyFirst - you will get onto the Magic Carpet
Next - Genie Magic
Finally - We escape the Cave of Wonders with the network data
cd Cave_of_Wonders
ls To view the pyATS log in a web browser Locally
pyats logs viewTo view the pyATS log in a web browser remotely
pyats logs view --host 0.0.0.0 --port 8080 -v
Here is an example of just one of the Wonders you will find: the show ip route command!
Here is what a Global Routing Table looks like in JSON:
The same routing table, but in YAML:
The JSON and YAML outputs are incredible representations of the routing table and can be used for further pyATS testing or data modeling.
"Business-ready" documentation includes the incredibly powerful and versatile Comma-Separated Values (csv) spreadsheet format.
Markdown, the format this README file is written in, can also be used to express the data in a lightweight format that renders nicely in modern browsers.
What about a full-blown HTML webpage? Magic Carpet also creates at least one of these per command.
Which renders nicely like this in your browser:
Another HTML page, an interactive mindmap, is also created from the Markdown file!
To launch a Python web server and make the Cave of Wonders available in a browser, where you can view the HTML pages:
Launch a local web server available on the same host:
cd Cave_of_Wonders
pushd; python3 -m http.server --bind 127.0.0.1 8888; popd;Launch your web browser and visit
Launch a local web server available to remote hosts:
cd Cave_of_Wonders
pushd; python3 -m http.server --bind 0.0.0.0 8888; popd;Launch your web browser and visit
http://{{ your server IP }}:8888/
Test Magic Carpet using the Cisco DevNet Sandbox
Cisco IOS-XE:
show access lists
show access session
show access session interface {{ interface }} detail
show authentication sessions
show authentication session interface {{ interface }} detail
show cdp neighbors details
show environment all
show etherchannel summary
show interfaces
show interfaces status
show interfaces trunk
show inventory
show ip arp
show ip arp vrf {{ vrf }}
show ip interface brief
show ip ospf
show ip ospf database
show ip ospf interface
show ip ospf neighbor
show ip ospf neighbor detail
show ip route
show ip route vrf {{ vrf }}
show issu state detail
* 4500X IOS-XE in VSS
show mac address-table
show ntp associations
show power inline
show version
show vlan
show vrf
JunOS:
show chassis hardware
show system information
F5 BIG-IP
mgmt/tm/ltm/virtual
Tested on:
Cisco:
Cisco Catalyst 4500X-16 03.11.03a.E
Cisco Catalyst 9300-48UXM Gibraltar
Cisco Catalyst 9200-24P 16.12.03 and 17.03.02a
Cisco Catalyst 3850-12X48U Gibraltar 16.12.04
Cisco CSR1000v
Cisco IOSv
Juniper:
JunOS 17, 18, 19
F5:
i2600 REST API
