UCS XML API "curl and xml"

[cdnadmin]

This blog was generated from CDN blog

Created by: John McDonough on 15-04-2010 11:18:43 PM
Last time I wrote about using telnet to connect to the UCS Manager 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 xml (xmlstarlet). 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, 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:

<aaaLogin cookie="" response="yes" outCookie="1271964448/5cc25d00-3d0d-4f64-87b2-a57fddd4e992" outRefreshPeriod="600" outPriv="read-only" outDomains="" outChannel="noencssl" outEvtChannel="noencssl"> </aaaLogin>


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:

1271964448/5cc25d00-3d0d-4f64-87b2-a57fddd4e992


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

<?xml version="1.0"?>
<configResolveClass cookie="1271964448/5cc25d00-3d0d-4f64-87b2-a57fddd4e992" response="yes" classId="computeBlade">
  <outConfigs>
    <computeBlade adminPower="policy" adminState="in-service" assignedToDn="org-root/ls-blade-2" association="associated" availability="unavailable" availableMemory="12288" chassisId="1" checkPoint="discovered" connPath="A,B" connStatus="A,B" descr="" discovery="complete" dn="sys/chassis-1/blade-2" fltAggr="0" fsmDescr="" fsmFlags="" fsmPrev="TurnupSuccess" fsmProgr="100" fsmRmtInvErrCode="none" fsmRmtInvErrDescr="" fsmRmtInvRslt="" fsmStageDescr="" fsmStamp="2010-03-25T11:36:10.629" fsmStatus="nop" fsmTry="0" intId="41578" lc="discovered" lcTs="1969-12-31T16:00:00.000" managingInst="B" model="N20-B6620-1" name="" numOfAdaptors="1" numOfCores="8" numOfCpus="2" numOfEthHostIfs="2" numOfFcHostIfs="0" numOfThreads="16" operPower="on" operQualifier="" operState="ok" operability="operable" originalUuid="00000000-0000-0000-1234-00000000001e" presence="equipped" revision="0" serial="QCI1252000G" slotId="2" totalMemory="12288" uuid="00000000-0000-0000-1234-00000000001e" vendor="Cisco Systems Inc"/>
    <computeBlade adminPower="policy" adminState="in-service" assignedToDn="" association="none" availability="available" availableMemory="49152" chassisId="1" checkPoint="discovered" connPath="A,B" connStatus="A,B" descr="" discovery="complete" dn="sys/chassis-1/blade-6" fltAggr="0" fsmDescr="" fsmFlags="" fsmPrev="DiscoverSuccess" fsmProgr="100" fsmRmtInvErrCode="none" fsmRmtInvErrDescr="" fsmRmtInvRslt="" fsmStageDescr="" fsmStamp="2010-03-24T16:49:29.204" fsmStatus="nop" fsmTry="0" intId="41873" lc="discovered" lcTs="1969-12-31T16:00:00.000" managingInst="A" model="N20-B6620-1" name="" numOfAdaptors="1" numOfCores="8" numOfCpus="2" numOfEthHostIfs="2" numOfFcHostIfs="2" numOfThreads="16" operPower="off" operQualifier="" operState="unassociated" operability="operable" originalUuid="8780cc22-d312-11dd-a185-000bab01bfd6" presence="equipped" revision="0" serial="QCI125200H6" slotId="6" totalMemory="49152" uuid="8780cc22-d312-11dd-a185-000bab01bfd6" vendor="Cisco Systems Inc"/>
    <computeBlade adminPower="policy" adminState="in-service" assignedToDn="org-root/ls-blade-8" association="associated" availability="unavailable" availableMemory="49152" chassisId="1" checkPoint="discovered" connPath="A,B" connStatus="A,B" descr="" discovery="complete" dn="sys/chassis-1/blade-8" fltAggr="12" fsmDescr="" fsmFlags="" fsmPrev="TurnupSuccess" fsmProgr="100" fsmRmtInvErrCode="none" fsmRmtInvErrDescr="" fsmRmtInvRslt="" fsmStageDescr="" fsmStamp="2010-03-24T16:49:31.233" fsmStatus="nop" fsmTry="0" intId="41889" lc="discovered" lcTs="1969-12-31T16:00:00.000" managingInst="B" model="N20-B6620-1" name="" numOfAdaptors="1" numOfCores="8" numOfCpus="2" numOfEthHostIfs="2" numOfFcHostIfs="2" numOfThreads="16" operPower="on" operQualifier="" operState="ok" operability="operable" originalUuid="55c6b2a1-d3a6-11dd-a23a-000bab01bfd6" presence="equipped" revision="0" serial="QCI125200GR" slotId="8" totalMemory="49152" uuid="55c6b2a1-d3a6-11dd-a23a-000bab01bfd6" vendor="Cisco Systems Inc"/>
    <computeBlade adminPower="policy" adminState="in-service" assignedToDn="org-root/ls-blade-4" association="associated" availability="unavailable" availableMemory="12288" chassisId="1" checkPoint="discovered" connPath="A,B" connStatus="A,B" descr="" discovery="complete" dn="sys/chassis-1/blade-4" fltAggr="0" fsmDescr="" fsmFlags="" fsmPrev="TurnupSuccess" fsmProgr="100" fsmRmtInvErrCode="none" fsmRmtInvErrDescr="" fsmRmtInvRslt="" fsmStageDescr="" fsmStamp="2010-03-24T16:49:31.215" fsmStatus="nop" fsmTry="0" intId="82152" lc="discovered" lcTs="1969-12-31T16:00:00.000" managingInst="A" model="N20-B6620-1" name="" numOfAdaptors="1" numOfCores="8" numOfCpus="2" numOfEthHostIfs="2" numOfFcHostIfs="0" numOfThreads="16" operPower="on" operQualifier="" operState="ok" operability="operable" originalUuid="7d307221-d187-11dd-a6f6-000bab01bfd6" presence="equipped" revision="0" serial="QCI12520020" slotId="4" totalMemory="12288" uuid="6d2f53f6-d496-11de-0000-000000000004" vendor="Cisco Systems Inc"/>
  </outConfigs>
</configResolveClass>


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


The output

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.

John McDonough
Cisco Advanced Services
UCS Compute and Virtualization Practice