Welcome to part 4 of the "APIC-EM API productivity series" for network engineers getting started in API and scripting.
Earlier blogs on APIC-EM covered
- /network-device – all attributes of network-devices (blog1)
- /interface/network-device – all interfaces (and hosts) on a network-device e.g. a switch (blog2)
- /license-info - all licencing information for a network-device (blog3)
By this stage of the blog series, I am going to assume you are familiar with swagger (API documentation tool) and the location of the github repository where I have shared the code samples.
#4 find my host
As mentioned earlier, the controller has a table of all hosts that are connected to network-devices. This information is kept updated when link up/down traps are enabled on switches and wireless Lan controllers (WLC). See the configuration guide for the commands to enable this on the network-devices.
This means that I can use the controller as an accurate source of information about hosts connected to the network and locate them. This example allows a search by host mac address or ip address.
Swagger
Navigate to the "/host" URL as in blog#2. In this case you are going to use the "hostIp" parameter. From blog #2, you know there is a host with IP address of "212.1.10.20". Enter this in, along with scope.
You will get the following output, showing the network-device and the interface this host is connected to.
You can also do a lookup by MAC address. Use the "hostMac" parameter and set it to "e8:9a:8f:7a:22:99". You will get the same output as before.
Script
The script "04_find_host.py" allows a search for a host via either MAC address or IP address. The three examples below illustrate the ways this can be done:
- 1) This example shows a lookup by MAC address. You can see the host IP|MAC as well as the ip address of the network-device (212.1.10.1) and the interface (GigabitEthernet1/0/47) and the vlan (200)
- 2) The second example is the same as the first, just a lookup by hostip. As expected it shows the same information as the previous call.
- 3) This example is for a wireless client. It shows the Controller the host is connected to as well (along with model and software version) as well as the AP the host is connected to.
$ ./04_find_host.py --mac e8:9a:8f:7a:22:99
212.1.10.20|e8:9a:8f:7a:22:99 wired -> 212.1.10.1|GigabitEthernet1/0/47 vlan:200
$ ./04_find_host.py --ip 212.1.10.20
212.1.10.20|e8:9a:8f:7a:22:99 wired -> 212.1.10.1|GigabitEthernet1/0/47 vlan:200
$ ./04_find_host.py --mac 00:24:d7:43:59:d8
65.1.1.86|00:24:d7:43:59:d8 wireless -> Campus-WLC-5508 55.1.1.2 AIR-CT5508-K9(8.1.14.16) -> AP7081.059f.19ca vlan:600
|
Looking at the code
There are three API calls used in this code.
- "host?hostIp=%s" which does a lookup by hostIp address. This is used when an IP address is supplied
- "host?hostMac=%s" which is a lookup by MAC address
- "network-device/%s" we have seen before. This is looking up a network-device by UUID, in this case to get some extra information about the Wireless LAN Controller the host is connected to.
def get_host(ip=None, mac=None):
if ip is not None:
url = "host?hostIp=%s" % ip
elif mac is not None:
url = "host?hostMac=%s" % mac
return get_url(url)
def get_wlc(id):
return get_url("network-device/%s" % id)
The other concept this code shows is the use of argument parsing to allow the "—mac" and "—ip" options to be used. Argparse is a python package for argument parsing (https://pypi.python.org/pypi/argparse ).
parser = ArgumentParser(description='Select options.')
parser.add_argument('--ip', type=str,help="ip address")
parser.add_argument('--mac', type=str,help="mac address")
parser.add_argument('-v', action='store_true',help="verbose")
args = parser.parse_args()
This is a very simple tool you can use for troubleshooting. Some improvements could include:
- Change the script so that it takes a single argument that is either a MAC or IP address and intelligently (based on syntax of the argument) determine if a MAC search or IP search is required.
- Embed this into a python web framework like Flask to turn this into a web page. Happy to provide an example of this, if people are interested.
- Provide a "refresh" option where the script will refresh the location every 5mins to track a host connectivity status.
What Next?
This blog covered the forth of the useful API /host . The final blog in the series will look /flow-analysis, an API to do a path trace between hosts on the network. It also provides stats on interfaces, QoS, Perfmon and ACL trace.
In the meantime, if you would like to learn more about APIC-EM, you could visit Cisco Devnet. All of the code samples can be found in this Github repository.
Thanks for reading
@adamradford123