Skip to content

Latest commit

 

History

History
283 lines (225 loc) · 15.4 KB

README.md

File metadata and controls

283 lines (225 loc) · 15.4 KB
Raw

nxapi-netbox

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.

Data Flow

Data Flow

  1. Read environment variables to access vault
  2. From vault, read Netbox url/token and NX-OS username/password
  3. From Netbox, convert device names to mgmt_ip address (Netbox can provide much more over time using e.g. roles, tags, etc)
  4. Interact with NX-OS devices over NXAPI

Script Inventory

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)

Dependency details

Either Hashicorp Vault or Ansible Vault

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.

1. The following environment variables need to be set and exported

PYTHONPATH
export PYTHONPATH=$PYTHONPATH:/path/to/nxapi-netbox/lib
If using Hashicorp Vault
export VAULT_ADDR=<vault url>
export VAULT_TOKEN=<vault token>
If using Ansible Vault
export ANSIBLE_VAULT_PATH=<path to ansible vault file>

2. Verify the above are present

If using Hashicorp Vault
% env | grep VAULT_ADDR
VAULT_ADDR=http://127.0.0.1:8200
% env | grep VAULT_TOKEN
VAULT_TOKEN=hvs.SiVa7BDO92FfETBLdQuMxSCq
If using Ansible Vault
% env | grep ANSIBLE_VAULT_PATH
ANSIBLE_VAULT_PATH=/Users/me/repos/nxapi-netbox/lib/nxapi_netbox/config/secrets

3. HashiCorp Vault

A 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.

To install HashiCorp Vault

Install HashiCorp Vault

To create the vault endpoint
vault secrets enable kv
Verify the endpoint with
vault secrets list

The 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.com

The 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)
Verify the expected key/values are present in Hashicorp 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.

4. Ansible Vault

Install Ansible Vault
pip install ansible

Then, if not familiar with it, read ansible-vault

Set the environment variable that points to the vault file
export ANSIBLE_VAULT_PATH=/path/to/ansible/vault/file
Populate the expected key/value pairs into Ansible Vault
ansible-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/file
Verify 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'