Cisco Unified Computing XML API with Curl and xmlstarlet
One of my favorite books is The Pillars of the Earth by Ken Follet, I’ve read it and reread it many times and each time I read it I get something new out of it. With so many good books out there it seems silly to reread a book, especially a very long book. I think what it is, is that the story is so good, the characters so compelling that I don’t want to leave them and when I’m finished with the book I miss them. Fortunately the book was made into a mini-series that I enjoyed and brought a nice visualization of the story. I also think the mini-series may have attracted a new set of readers in the viewing audience.
New audiences come with new methods of distribution for the same, similar or different presentation of an already published work. With the intent to reach a new audience I am republishing a UCS XML API focused blog from another blog site on Cisco Developer Network UCS Section. I wrote this blog in April 2010, but the methods utilized seemed to flow from my prior entries on this site.The previously published blog has references to other blogs on the on the Cisco Developer Network site in the Cisco UCS section.
The previous blog…
Last time I wrote about using telnet to connect to the UCS Manager XML API as a way to introduce the API and show it’s lack of complexity. Now I don’t expect anyone to write an application that uses telnet to manage a UCS system, I just wanted to get across that if text, XML structured text, can be pushed across an open port to the listening API process on the UCS then it doesn’t matter how the push is done.
However telnet is not very practical, so I thought I would write about curl and xmlstarlet (xmlstarlet referred to as xml in this entry). curl is used to handle the request and response cycle with the UCS and xml is used to process the XML response. In some of my early scripts I used sed and awk to “parse” the output. I say parse but it was more pattern matching; by the way sed and awk are great tools, but maybe I’m partial to them because I’ve been around for a while. The reason I started with curl, sed and awk was not because I lacked XML experience but because I wanted to appeal to the administrators out there and show that XML experience, while beneficial, is not specifically needed.
As a testament to the viability of sed and awk, some of those early tools are still in circulation among my team members and come in quite handy as part of a Cisco UCS AS Advanced Services engagement. However using curl in conjunction with xml makes much more sense and can get you to your UCS management goals all the quicker.
I’ll start at the same place as my previous post with how to get an authentication cookie. Then move to a query. xml is used to extract the cookie from the aaaLogin response as well as format the response from the query.
Lets start, curl lets you create an HTTP Post request to the UCS Manger API without having to write an HTTP client. A few command line switches with curl and we’re good.
curl -H "Content-Type: text/xml" -N -s -d '<aaaLogin inName="ucsrouser" inPassword="cisco@123" />' http://10.10.10.10/nuova
- -H is the header to pass
- -N disables buffering
- -s is silent mode, still displays the output from UCS just does not display curl output
- -d the HTTP Post data
When sending data to the UCS Manager API the URL path needs to be nuova. The output from the curl command above is:
<cookie="" response="yes" outCookie="1271964448/5cc25d00-3d0d-4f64-87b2-a57fddd4e992" outRefreshPeriod="600" outPriv="read-only" outDomains="" outChannel="noencssl" outEvtChannel="noencssl"/>
To extract the cookie from the UCS response I’ll pipe it through xml like this
curl -H "Content-Type: text/xml" -N -s -d '<aaaLogin inName="ucsrouser" inPassword="cisco@123" />' http://10.10.10.10/nuova | xml sel -t -m //aaaLogin -v @outCookie
- sel means select data or query XML
- -t specifies the template to use, no template means use the default template
- -m indicates the XPATH expression to match
- -v prints out the value of the item specified, in this case the outCookie attribute
This time the output is:
Now that we have a cookie we can interact with the UCS Manager. The cookie indicates to the UCS Manager what level of privileges that the user has. The UCS uses Role Based Authorization Control, the user can have multiple roles while each role can have one or more privileges associated with it. All API interactions, other than the aaaLogin, with the UCS need an authentication cookie.
We’ll use the cookie in an Object Class query. The following query retrieves all the UCS compute blades (servers) that are contained in all the chassis.
<configResolveClass classId="computeBlade" cookie="1271964448/5cc25d00-3d0d-4f64-87b2-a57fddd4e992" inHierarchical="false" />
There are several things to explain in the query above, the configResolveClass method is a query method that retrieves objects of the class type specified as the value of the classId attribute. In the query, classId is set to computeBlade, computeBlade is the UCS object that represents the server hardware that resides in a UCS chassis slot. The cookie attribute is set to the value of the outCookie attribute that was part of the aaaLogin response. Finally the inHierarchical attribute indicates whether or not to return just the top level computeBlade objects (false) or to return the computeBlade objects and all the children objects of the computeBlade and the children’s children (true).
The computeBlade object represents the server hardware while the lsServer object represents the Service Profile object that can be associated to a computeBlade. More on lsServer in another note.
Let’s curl and pipe the response through xml with a format option.
curl -H "Content-Type: text/xml" -N -s -d '<configResolveClass classId="computeBlade" cookie="1271964448/5cc25d00-3d0d-4f64-87b2-a57fddd4e992" inHierarchical="false" />' http://10.10.10.10/nuova | xml fo
The response is shown below I have bolded the beginning of each computeBlade object, the bold would not be part of the normal output
Let’s curl again and this time use xml to extract the computeBlade attributes, vendor, model, serial, chassisId, slotId, numOfCpus, numOfCores, and totalMemory. Using the concat function to put spaces between the values and a -n to add a newline between each computeBlade object.
curl -H "Content-Type: text/xml" -N -s -d '<configResolveClass classId="computeBlade" cookie="1271964448/5cc25d00-3d0d-4f64-87b2-a57fddd4e992" inHierarchical="false" />' http://10.10.10.10/nuova | xml sel -t -m //computeBlade -v "concat(@vendor,' ',@model,' ',@serial,' ',@chassisId,' ',@slotId,' ',@numOfCpus,' ',@numOfCores,' ',@totalMemory)" -n
Cisco Systems Inc N20-B6620-1 QCI1252000G 1 2 2 8 12288
Cisco Systems Inc N20-B6620-1 QCI125200H6 1 6 2 8 49152
Cisco Systems Inc N20-B6620-1 QCI125200GR 1 8 2 8 49152
Cisco Systems Inc N20-B6620-1 QCI12520020 1 4 2 8 12288
If you take to long between curl commands, like two hours, you may need to login again. However keep your cookie fresh with the aaaRefresh method, to get a new cookie that is valid for two more hours. Request and response shown below.
<aaaRefresh inName="ucsrouser" inPassword="cisco@123" inCookie="1271964448/5cc25d00-3d0d-4f64-87b2-a57fddd4e992" />
<aaaRefresh cookie="" response="yes" outCookie="1271977662/fdebc85f-68b0-4c58-85a7-345d106a76d7" outRefreshPeriod="600" outPriv="read-only" outDomains="" outChannel="noencssl" outEvtChannel="noencssl"> </aaaRefresh>
When you’re done don’t forget to logout. Request and response shown below using the current cookie from the aaaRefresh method.
<aaaLogout inCookie="1271977662/fdebc85f-68b0-4c58-85a7-345d106a76d7" />
<aaaLogout cookie="" response="yes" outStatus="success"> </aaaLogout>
Give it a try, next time I’ll discuss query methods and touch on query filters.
End Previous blog
As an update to the blog I’ve added this presentation to show additional uses of curl and xml