This repo contains scripts and libraries to interact with Cisco NX-OS switches over NXAPI. NX-OS and Netbox Credentials are obtained through either Hashicorp Vault or Ansible Vault. Device names are resolved to IP addresses using Netbox. In the future, we hope to add more functionality using e.g. Netbox Roles and/or Tags. For example, display nve neighbors for all devices with Role == Leaf and tag == fabric1.
- Read environment variables to access vault
- From vault, read Netbox url/token and NX-OS username/password
- From Netbox, convert device names to mgmt_ip address (Netbox can provide much more over time using e.g. roles, tags, etc)
- Interact with NX-OS devices over NXAPI
| Script | Description |
|---|---|
| acl_utilization | NXAPI display acl tcam utilization |
| arp_summary | NXAPI: display ip arp summary |
| bfd_neighbor_info | NXAPI: display bfd neighbors detail information |
| bfd_neighbor_state | NXAPI: display bfd neighbor state for all neighbors |
| bgp_l2vpn_evpn_summary | NXAPI: display bgp l2vpn evpn summary |
| bgp_neighbor_l2vpn_evpn_prefix_received | NXAPI: display bgp l2vpn evpn summary info |
| bgp_neighbor_prefix_received | NXAPI: display bgp neighbor summary info |
| bgp_neighbor_state | NXAPI: display bgp neighbor state for all neighbors |
| bgp_neighbors | NXAPI: display detailed bgp neighbor information |
| bgp_neighbors_l2vpn_evpn | NXAPI: display bgp l2vpn evpn neighbor info |
| forwarding_consistency | NXAPI: start and display results for forwarding consistency checker |
| forwarding_route_ipv4 | NXAPI: Display ipv4 prefix information from FIB related to --module --vrf --prefix |
| forwarding_route_summary_ipv4 | NXAPI: display forwarding ipv4 route summary |
| forwarding_route_summary_ipv6 | NXAPI: display forwarding ipv6 route summary |
| interface_beacon_status | NXAPI: display interface beacon status |
| interface_egress_queuing | NXAPI: display interface egress queing information (not very well tested yet...) |
| interface_errors | NXAPI: display non-zero interface error counters |
| interface_find_transceiver | NXAPI: Find transceivers across one or more switches, using a variety of search terms |
| interface_info | NXAPI: display info from "show interface" cli |
| interface_last_flapped | NXAPI: display interface last flapped/cleared timers, and reset info |
| interface_link_not_connected | NXAPI: display interfaces in notconnect state (Link not connected) |
| interface_packet_rates | NXAPI: display interface input/output packet rates for a set of interfaces |
| inventory | NXAPI: display "show inventory" info |
| inventory_find_serial_numbers | NXAPI: find one or more serial numbers across a set of NXOS switches |
| inventory_module_info | NXAPI: display model, hw, sw versions for --module |
| inventory_switch_serial_numbers | NXAPI: display all serial numbers |
| ipv6_nd | NXAPI: display ipv6 neighbor info |
| ipv6_neighbor_summary | NXAPI: display ipv6 neighbor summary |
| license_hostid | NXAPI: display license host_id |
| lldp_neighbors | NXAPI: display lldp neighbor info |
| locator_led_status | NXAPI: display locator-led status for chassis, modules, fans |
| mac_address_count | NXAPI: display mac address-table count |
| nve_interface | NXAPI: display nve interface |
| nve_peers | NXAPI: display nve peers |
| rib_summary | NXAPI: display ipv4/ipv6 RIB summary |
| switch_bootvar | NXAPI: display current bootvar info |
| switch_find_files | NXAPI: find files whose name contains --find on --target across the set of switches --devices |
| switch_reload | NXAPI: reload (or install reset) one or more NX-OS devices |
| switch_reset_reason | NXAPI: display NXOS reset reason and time last reset |
| switch_version | NXAPI: display NXOS version information |
| system_mode | NXAPI: display system mode |
| system_process_memory | NXAPI: display memory usage of system processes |
| test_vault_ansible | Verify that Ansible Vault is working and contains the keys required by scripts in this repo |
| test_vault_hashicorp | Verify that HashiCorp Vault is working and contains the keys required by scripts in this repo |
| virtual_service_status | NXAPI: display all virtual-service names and status |
| vpc_consistency | NXAPI: display inconsistent vpc parameters |
| vpc_status | NXAPI: display vpc parameters |
| vrf | NXAPI: display vrfs |
The scripts use Netbox (currently only for name resolution, but likely for more later...).
The scripts also access a vault for usernames, passwords, tokens, and urls. You can choose on the command line between Hashicorp Vault, or Ansible Vault. If you want to remove these dependencies, the scripts are easily modified to hardcode these things (or use some other method to retrieve them), since the calls to each of the NXAPI objects take username, password, IP/Hostname, and a logging instance as parameters. An example call is shown below.
arp = NxapiArpSummary(vault.nxos_username, vault.nxos_password, ip, log)You could change this to the below, and strip out all the vault/argparse/netbox code:
arp = NxapiArpSummary('admin', 'mypassword', '192.168.1.1', log)These scripts use either Ansible Vault or Hashicorp Vault for
retrieving usernames, passwords, tokens, and urls. You control
which vault is used with the --vault argument to each script.
export PYTHONPATH=$PYTHONPATH:/path/to/nxapi-netbox/libexport VAULT_ADDR=<vault url>
export VAULT_TOKEN=<vault token>export ANSIBLE_VAULT_PATH=<path to ansible vault file>% env | grep VAULT_ADDR
VAULT_ADDR=http://127.0.0.1:8200
% env | grep VAULT_TOKEN
VAULT_TOKEN=hvs.SiVa7BDO92FfETBLdQuMxSCq% env | grep ANSIBLE_VAULT_PATH
ANSIBLE_VAULT_PATH=/Users/me/repos/nxapi-netbox/lib/nxapi_netbox/config/secretsA HashiCorp Vault installation/setup cheat-sheet is available in this repo at HashiCorp_Vault_Cheat_Sheet.md
Below are general steps which assume you already have a vault up and running.
If using --vault hashicorp, a running unsealed HashiCorp Vault with endpoint ('/v1/kv/nxapi' by default) should be reachable.
vault secrets enable kvvault secrets listThe vault endpoint (/v1/kv/nxapi by default) should be populated as follows. Note the endpoint is specified differently when using the vault cli, versus using in a REST call e.g. REST /v1/kv/nxapi becomes CLI kv/nxapi.
vault kv put kv/nxapi nxos_username=admin nxos_password=mypassword netbox_token=21716fi7k4ac9a8a51d99c5fab025e207b741fe netbox_url=http://mynetbox.foo.comThe keys we expect in the vault are shown below.
netbox_token=<netbox token>
netbox_url=<netbox url>
nxos_username=<nxos username>
nxos_password=<nxos password>If using an endpoint other than /v1/kv/nxapi, you'll need to modify the scripts to set the new endpoint. Like this:
vault = get_vault(cfg.vault)
vault.endpoint = '/v1/kv/my_new_endpoint' # <<<< add this line
vault.fetch_data()
nb = netbox(vault)Change your endpoint below, if it's not kv/nxapi.
% vault kv get -format="json" kv/nxapi
{
"request_id": "cc330dc0-b84b-e1b6-27bd-98bfc860344a",
"lease_id": "",
"lease_duration": 2764800,
"renewable": false,
"data": {
"netbox_token": "21716fi7k4ac9a8a51d99c5fab025e207b741fe",
"netbox_url": "http://mynetbox.foo.com",
"nxos_password": "ax84fs00fs",
"nxos_username": "admin"
},
"warnings": null
}See test_vault_hashicorp.py in this directory, which you can use to verify your Hashicorp Vault setup.
pip install ansibleThen, if not familiar with it, read ansible-vault
export ANSIBLE_VAULT_PATH=/path/to/ansible/vault/fileansible-vault encrypt_string 'admin' --name 'nxos_username' >> /path/to/ansible/vault/file
ansible-vault encrypt_string 'ax84fs00fs' --name 'nxos_password' >> /path/to/ansible/vault/file
ansible-vault encrypt_string '21716fi7k4ac9a8a51d99c5fab025e207b741fe' --name 'netbox_token' >> /path/to/ansible/vault/file
ansible-vault encrypt_string 'http://mynetbox.foo.com' --name 'netbox_url' >> /path/to/ansible/vault/fileVerify the expected key/value pairs are present, and the environment variable is set, using the script test_vault_ansible.py in this repo.
% ./test_vault_ansible.py
Vault password:
nxos_username: admin
nxos_password: ax84fs00fs
netbox_token: 21716fi7k4ac9a8a51d99c5fab025e207b741fe
netbox_url: http://mynetbox.foo.com'