What does it do?
Let's start with a short description of what the device does. It's designed to show current "health status" of ACI infrastructure. Using the API it "reads" the current "System Health" score of the fabric and displays it on a 4x8 LED multicolour display. The "size" and colour of the display will reflect the health score of the fabric. Let's look at some examples of what the device can display:
In the first example we see that if the health score is "100" all rows, starting from bottom lit up in green. As the health score decreases the number of lit up rows decreases at the same time the colour changes, by the time the health score reaches 25, only two rows lit up red and so on.
What are the use cases?
The device is a prof of concept. The "vision" for this device is to be installed in for example CTO's office, so that he/she can have a quick view of the organisation's datacenter network status without having to login to a computer/phone or any other device. Just a quick "glance" at the display will reveal the network status.
It's also a great example of the flexibility of API built into the ACI product. I personally use it as a demo device when presenting ACI to customers, it serves a "monitoring" function telling me if the fabric is "ready for another demo".
How it's done?
The device is based on "Raspberry Pi Zero" embedded linux computer. The computer uses a wi-fi dongle plugged via a USB hub to connect to wireless network. The "screen" is an of-the-shelf available module. Power is provided via a micro USB cable (either from a "phone" style charger or using a USB-A-to-micro-USB cable plugged to a computer).
The code that controls the gadget is written in python, you can download the code and detailed instruction how to build one of those gadgets from here:
How to configure one ?
If you have one of the "ACI-Health" gadgets given away at the November SEVT, here is what you need to do to get it working. The process much easier if you are able to plug a screen with HDMI input, mouse and keyboard to the device, but it's also possible to fully configure the device without using any additional hardware (SD card reader built into your computer is required).
The trickiest part of the setup is to get the device on a wireless network that has access to your APIC, you should try to avoid connecting to "blizzard" and where possible connect to lab wireless network. The "blizzard" requires providing you CEC credentials as part of the login process, and since the device doesn't have screen, those credentials have to be saved in a configuration file. The filesystem of our raspberry pi zero computer is not encrypted so although I will provide some instructions on how to hash the password inside the configuration file, this is not a secure method of storing those credentials.
Note: the wi-fi dongle provided with the device only supports 2.4GHz, so it's pointless to attempt the configuration in a room with 300 other engineers (like the SEVT conference) since it will constantly drop off the network
Setting up without external monitor and keyboard:
- Unplug the device from power.
- Remove the SD card, use the provided full size card adapter and insert the card to your computer.
- Once the card is in your computer, it will be listed as "boot" drive, open the content of the card and make a copy of the "wpa_supplicant_template.conf" file.
- Rename the copied file to "wpa_supplicant.conf" - this is the file that controls what wireless network the device connects to, when the device starts the file gets automatically copied to /var/wpa_supplicant inside the device.
- the file has two wireless networks configured, one is my lab test network with ssid: TP-LINK_9F5394 and password B39F5394, the other is configuration for "blizzard". If you are using your lab wireless network just replace the SSID and password parameters. For connection to "blizzard" you will need to provide your cec username (just replace my ksekula with yours) and your cec password, both of those parameters need to be in quotes (""). Save the file after editing.
- When your device gets online it will send you email with it's ip address, for this to work it needs to be able to access cisco's smtp server, additionally you need to provide your email address for this process to work.
- Open the mailmyip.sh file and reaplace my email address email@example.com with yours.
- Open monitor.py file and update the apic ip address and credentials.
- Eject the card from your computer and insert back to the device. Use the provided USB cable and plug the device to power (wall plug or your computer, not the device has two micro USB sockets, but to power it up you must plug the power to the bottom socket, see the picture above).
- Once powered, the a bootup script will move the wpa_supplicant.config file to it's default location in the linux operating system (/var/wpa_supplicant) and it will attempt to connect to the wireless networks listed in the configuration file in the order they appear.
- The main script (monitor.py) gets executed after boot.
- A the mailmyip.sh script gets executed 120s after boot (we delay the script to give the device chance to get online before we attempt to send the email out), and sends you email with ip address of the device.
- ssh to the device to further tweak and change configuration. The default username is "pi" the password are purposely made complex and will be provided to you via email.
- after you gain access to the device via ssh you should "hash" the cec password inside configuration file:
- generate the hash issuing the following command from your device issue:
echo -n 'your-cisco-pass-here' | iconv -t utf16le | openssl md4
if for example your password is C!sco!23 use the following command:
$ echo -n 'C!sco!23' | iconv -t utf16le | openssl md4
- the string after the = sign is the hash
- using vi or nano edit the wpa_supplicant.conf file:
"sudo nano /etc/wpa_supplicant/wpa_supplicant.conf"
- replace the password with hash so in my example:
- save the file and reboot.
- Important: the command used to generate the hash leaves your password in clear text in the commands history list, to clear the list issue the following two commands:
$ history -c
$ history -w
- your device is ready to use.
Feedback and further improvements.
A week has passed since we've given away the "ACI-Health" gadgets and there has been some feedback, here is the list of challenges and some fixed/improvements that I've now implemented:
1. "I followed the instructions, my device goes online, I see the score displayed but I don't get the email with ip address ?"
This issue has been related to the fact that some of the devices had a typo in the cron job, to fix you will have to log into the device (best with keyboard mouse and screen, if not you will need to ssh to the ip address that you can either get from your dhcp server - if you're on blizzard read the next point) and issue the following command:
rpi0-01:~ $ sudo crontab -e
this will open you cron editor, edit the text and make sure one of the lines reads:
@reboot sleep 120 && bash /home/mailmyip.sh
press CTRL+X to save and accept default name
rpi0-01:~ $ sudo reboot
after 120s you should receive email with the ip address (NOTE: remember this will only work on cisco corporate / or lab networks as it requires access to "outbound.cisco.com" if you're are not on cisco corporate network I have a different solution, read further)
2. I'm not on cisco corporate network so I don't get the email or I don't have access to the DHCP server, how can I find out my ip address?
I've updated the monitor.py script (new version is attached to this page), on boot the script now waits for ip address to be assigned to the device and after that it will display the ip address encoded in binary ! Fist column is the first octet, 2nd column is 2nd octet and so on. Best is to take a picture and decode later using google or calculator. To install the new code, simply download the monitor.py from here, copy it to the SD card of your device (you will have to overwrite the existing file)
See example below on how to decode the ip address from what is displayed:
3. I don't have wireless network I can use the device with.
You can plug a USB-to-Ethernet adapter to the back of the device and it will work (best is to remove the Wi-Fi dongle when using the adapter) ... I've tested with the white Apple mac USB-to-Ethernet adapter that we get with Macbooks and it works fine.