Table Of Contents

Using the Cisco UCS XML API Methods

Authentication Methods

Login

Refreshing the Session

Logging Out of the Session

Unsuccessful Responses

Query Methods

Using configFindDnsByClassId

Using configResolveChildren

Using configResolveClass

Using configResolveClasses

Using configResolveDn

Using configResolveDns

Using configResolveParent

Using configScope

Querying the MAC Pool

Using Query Methods for Statistics

Querying Faults

Using Filters

Simple Filters

Property Filters

Equality Filter

Not Equal Filter

Greater Than Filter

Greater Than or Equal to Filter

Less Than Filter

Less Than or Equal to Filter

Wildcard Filter

Any Bits Filter

All Bits Filter

Componsite Filters

AND Filter

OR Filter

Between Filter

AND, OR, NOT Composite Filter

Modifier Filter

NOT Filter

Using the Cisco UCS XML API Methods

---

This chapter includes the following sections:

•Authentication Methods

•Query Methods

•Using Query Methods for Statistics

•Querying Faults

•Using Filters

Authentication Methods

Authentication allows API interaction with the Cisco UCS. It provides a way to set permissions and control the operations that can be performed.

---

Note Most code examples in this guide substitute the term <real_cookie> for an actual cookie (such as 1217377205/85f7ff49-e4ec-42fc-9437-da77a1a2c4bf). The Cisco UCS cookie is a 47-character string; it is not the type of cookie that web browsers store locally to maintain session information.

---

This section contains the following topics:

•Login

•Refreshing the Session

•Logging Out of the Session

•Unsuccessful Responses

Login

The LogIn method uses a standard Telnet client to log in and be authenticated. A TCP session is established on port 80 and aaaLogin is called by posting a document that encapsulates the XML document in an HTTP message. The /path is always /cisco. To log in, establish a TCP connection as follows:

bash> telnet 172.21.60.72 80

POST /cisco HTTP/1.1

Host: 172.21.60.72

Content-Length: 52

Next call the aaaLogin method and provide a user name and password:

<aaaLogin 

	inName="admin" 

	inPassword="cisco@123"/> 

---

Note Do not include XML version or DOCTYPE lines in the XML API document. The inName and inPassword attributes are parameters.

---

Each XML API document represents an operation to be performed. When the request is received as an XML API document, Cisco UCS reads the request and performs the actions as provided in the method. Cisco UCS responds with a message in XML document format and indicates success or failure of the request.

The following is a typical successful response:

(1)		<aaaLogin 

(2)			response="yes" 

(3)			outCookie="<real_cookie>" 

(4)				outRefreshPeriod="600"

(5)				outPriv="aaa,ext-lan-policy,ext-lan-qos,ext-san-policy,operations, 

					pod-policy,pod-qos,read-only" 

(6)				outDomains="mgmt02-dummy" 

(7)				outChannel="noencssl" 

(8)				outEvtChannel="noencssl"> 

(9)		</aaaLogin> 

(1) The method used to login.

(2) Confirms this is a response.

(3) This is the session cookie.

(4) The recommended cookie refresh period. The default login session length is two hours.

(5) The privileges assigned to the user account.

(6) The outDomains value is mgmt02-dummy.

(7) The outChannel value is noencssl (this session is not using encryption over SSL).

(8) The outEvtChannel value is noencssl (any event subscriptions would not use encryption over SSL).

(9) Closing tag.

Refreshing the Session

Sessions are refreshed with aaaRefresh method, using the 47-character cookie obtained either from the aaaLogin response or a previous refresh.

<aaaRefresh 

	inName="admin" 

	inPassword="mypasword" 

	inCookie="real_cookie"/>

Logging Out of the Session

Use the following method to log out of a session:

<aaaLogout 

	inCookie="<real_cookie>" />

Unsuccessful Responses

Failed login:

<aaaLogin

	response="yes"

	cookie="<real_cookie>"

	errorCode="551"

	invocationResult="unidentified-fail"

	errorDescr="Authentication failed">

</aaaLogin> 

Nonexistent object: (blank return indicates no object with the specified DN)

<configResolveDn

	dn="sys-machine/chassis-1/blade-4711"

	cookie="<real_cookie>"

	response="yes">

	<outConfig> </outConfig>

</configResolveDn> 

Bad request:

<configConfMo

	dn="fabric/server"

	cookie="<real_cookie>"

	response="yes"

	errorCode="103"

	invocationResult="unidentified-fail"

	errorDescr="can't create; object already exists.">

</configConfMo

Query Methods

Query methods obtain information (for example, hierarchy, state, and scope)

This section contains the following topics:

•Using configFindDnsByClassId

•Using configResolveChildren

•Using configResolveClass

•Using configResolveClasses

•Using configResolveDn

•Using configResolveDns

•Using configResolveParent

•Using configScope

•Querying the MAC Pool

Using configFindDnsByClassId

When finding distinguished names of a specified class, note the following:

•This method retrieves the DNs of a specified class.

•classId specifies the object type to retrieve (required).

•Authentication cookie (from aaaLogin or aaaRefresh) is required.

•Enumerated values, classIds, and bit masks are displayed as strings.

See the example request/response in the "configFindDnsByClassId" section on page 3-30.

Using configResolveChildren

When resolving children of objects in the management information tree, note the following:

•This method obtains all child objects of a named object that are instances of the named class. If a class name is omitted, all child objects of the named object are returned.

•inDn attribute specifies the named object from which the child objects are retrieved (required).

•classId attribute specifies the name of the child object class to return (optional).

•Authentication cookie (from aaaLogin or aaaRefresh) is required.

•inHierarchical attribute (default = false) if true, specifies that results are hierarchical.

•Enumerated values, classIds, and bit masks are displayed as strings.

See the example request/response in the "configResolveChildren" section on page 3-33.

Using configResolveClass

When resolving a class, note the following:

•All objects of the specified class type are retrieved.

•classId specifies the object class name to return (required).

•Authentication cookie (from aaaLogin or aaaRefresh) is required.

•inHierarchical attribute (default = false) if true, specifies that results are hierarchical.

•Enumerated values, classIds, and bit masks are displayed as strings.

Result sets can be large. Be precise when defining result sets. For example, to obtain only a list of servers, use computeItem as the attribute value for classId in the query. To get all instances of equipment, query the equipmentItem class. This example queries for all instances of the equipmentItem class:

<configResolveClass 

	cookie="real_cookie" 

	inHierarchical="false" 

	classId="equipmentItem"/> 

See the example request/response in the "configResolveClass" section on page 3-34.

Using configResolveClasses

When resolving multiple classes, note the following:

•This method retrieves all the objects of the specified class types.

•classId attribute specifies the name of the object class to return (required).

•Authentication cookie (from aaaLogin or aaaRefresh) is required.

•inHierarchical attribute (default = false) if true, specifies that results are hierarchical.

•Enumerated values, classIds, and bit masks are displayed as strings.

If an invalid class name is specified in the inId attribute, an XML parsing error is generated and the query cannot execute.

See the example request/response in "configResolveClasses" section on page 3-35.

Using configResolveDn

When resolving a DN, note the following:

•The object specified by the DN is retrieved.

•Specified DN identifies the object instance to be resolved (required).

•Authentication cookie (from aaaLogin or aaaRefresh) is required.

•inHierarchical attribute (default = false) if true, specifies that results are hierarchical.

•Enumerated values, classIds, and bit masks are displayed as strings.

See the example request/response in "configResolveDn" section on page 3-37.

Using configResolveDns

When resolving multiple DNs, note the following:

•The objects specified by the DNs are retrieved.

•Specified DN identifies the object instance to be resolved (required).

•Authentication cookie (from aaaLogin or aaaRefresh) is required.

•inHierarchical attribute (default = false) if true, specifies that results are hierarchical.

•Enumerated values, classIds, and bit masks are displayed as strings.

•Order of a request does not determine the order of the response.

•Unknown DNs are returned as part of the outUnresolved element.

See the example request/response in "configResolveDns" section on page 3-38.

Using configResolveParent

When resolving the parent object of an object, note the following:

•This method retrieves the parent object of a specified DN.

•dn attribute is the DN of the child object (required).

•Authentication cookie (from aaaLogin or aaaRefresh) is required.

•inHierarchical attribute (default = false) if true, specifies that results are hierarchical.

•Enumerated values, classIds, and bit masks are displayed as strings.

See the example request/response in "configResolveParent" section on page 3-40.

Using configScope

Limiting the scope of a query allows for a finer grained, less resource-intensive request. The query can be anchored at a point in the management information tree other than the root. When setting the query scope, note the following:

•This method sets the root (scope) of the query to a specified DN and returns objects of the specified class type.

•dn is the named object from which the query is scoped (required).

•inClass attribute specifies the name of the object class to return (optional; when a class is not specified, the query acts the same as configResolveDn).

•Authentication cookie (from aaaLogin or aaaRefresh) is required.

•inHierarchical attribute (default = false) if true, specifies that results are hierarchical.

•Enumerated values, classIds, and bit masks are displayed as strings.

The following example is a query for the Ethernet interfaces on the blades in chassis 1:

<configScope 

	dn="sys/chassis-1" 

	inClass="adaptorExtEthIf" 

	cookie="<real_cookie>" 

	inHierarchical="false"/>

Also see the example request/response in "configScope" section on page 3-42.

Querying the MAC Pool

To obtain a list of all MAC addresses, query for macpoolAddr. These are children of the (system-created) macpoolUniverse. The request is as follows:

<configScope 

	cookie="<real_cookie>" 

	inHierarchical="false" 

	dn="mac" inClass="macpoolAddr"/> 

The response is as follows:

<?xml version="1.0" encoding="UTF-8"?>

<configScope 

	cookie="<real_cookie>" 

	dn="mac" response="yes">

	<outConfigs>

		<macpoolAddr

			assigned="no"

			assignedToDn=""

			dn="mac/00:00:00:00:FF:0F"

			id="00:00:00:00:FF:0F"

			owner="pool">

		</macpoolAddr>

		<macpoolAddr

			assigned="no"

			assignedToDn=""

			dn="mac/00:00:00:00:FF:0E"

			id="00:00:00:00:FF:0E"

			owner="pool">

		</macpoolAddr>

		.

		.

		.

	<\outconfig

<\configScope 

Because the objects of the macpoolAddr class can exist only as children of the MAC pool universe, a simpler query follows:

<configResolveClass 

	cookie="<real_cookie>" 

	inHierarchical="false" 

	classId="macpoolAddr"/>

To determine which computeItem (blade or rack mount server) is assigned a particular MAC address, specify the MAC address in the query and look at the assignedToDn field in the response. For example, a request with a specified MAC address follows:

<configResolveDn 

	cookie="<real_cookie>" 

	inHierarchical="false" 

	dn="mac/10:00:00:00:00:03"/> 

The response is as follows:

<configResolveDn 

	dn="mac/10:00:00:00:00:03" 

	cookie="real_cookie" 

	response="yes">

	<outConfig>

		<macpoolAddr assigned="yes" 

			assignedToDn="org-root/ls-BOB/ether-eth1"

			dn="mac/10:00:00:00:00:03" id="10:00:00:00:00:03" 

			owner="pool" />

	</outConfig>

</configResolveDn>

Using Query Methods for Statistics

Statistics are available on a wide range of objects. Querying all statistics at once is resource intensive. Instead, identify the type of statistic and the object on which it reports; for example, getting the compCpuStats object for sys/chassis-1/blade-1/board/cpu-2, query for all children of sys/chassis-1/blade-1/board/cpu-2. The request is as follows:

<configScope 

	cookie="real_cookie" 

	inHierarchical="false" 

	dn="sys/chassis-1/blade-1/board/cpu-2" 

	inClass="processorEnvStats" /> 

The system response is as follows:

<configScope 

	dn="sys/chassis-1/blade-5/board/cpu-2" 

	cookie="<real_cookie>" 

	response="yes">

	<outConfigs>

		<processorEnvStats  

			dn="sys/chassis-1/blade-5/board/cpu-2/env-stats"

			inputVoltage="0.058200"

			inputVoltageAvg="0.062080"

			inputVoltageMax="0.077600"

			inputVoltageMin="0.058200"

			intervals="58982460"

			suspect="no"

			temperature="23.000000"

			temperatureAvg="23.000000"

			temperatureMax="23.000000"

			temperatureMin="23.000000"

			thresholded=""

			timeCollected="2009-09-23T12:40:55"

			update="327680"/>

	</outConfigs>

</configScope> 

A query by the DN is more efficient:

<configResolveDn

	inHierarchical="false"

	cookie="<real_cookie>"

	dn="sys/chassis-1/blade-1/board/cpu-2/processorEnvStats">

</configResolveDn> 

With the statistic object's DN, query for historical statistics on the children of the object using a hierarchical query. To get the statistic object and historical statistics, change inHierarchical to true:

<configResolveDn

	inHierarchical="true"

	cookie="<real_cookie>"

	dn="sys/chassis-1/blade-1/board/cpu-2/processorEnvStats">

</configResolveDn>

Querying Faults

The following example obtains a list of major faults:

<configResolveClass 

	cookie="real_cookie" 

	inHierarchical="false" 

	classId="faultInst"/>

The following example (which contains the filter <inFilter>eq class= "faultInst") obtains a list of all major or critical faults:

<configResolveClass 

	cookie="<real_cookie>" 

	inHierarchical="false" 

	classId="faultInst">

	<inFilter>

		<eq class="faultInst" 

			property="highestSeverity" 

			value="major" />

	</inFilter>

</configResolveClass>

Using Filters

Use filters to create specific and targeted queries.

This section contains the following topics:

•Simple Filters

•Property Filters

•Componsite Filters

•Modifier Filter

Simple Filters

Simple filters use true and false conditions of properties to select results.

False example

<configResolveClass

	cookie="<real_cookie>"

	classId="topSystem"

	inHierarchical="false">

    <inFilter>

    </inFilter>

</configResolveClass>

True example

<configResolveClass 

	cookie="<real_cookie>"

	classId="topSystem"

	inHierarchical="true">

	<inFilter>

	</inFilter>

</configResolveClass>

Property Filters

This section contains the following topics:

•Equality Filter

•Not Equal Filter

•Greater Than Filter

•Greater Than or Equal to Filter

•Less Than Filter

•Less Than or Equal to Filter

•Wildcard Filter

•Any Bits Filter

•All Bits Filter

Equality Filter

The example shows a query for all associated servers. The equality filter is framed as follows:

<configResolveClass 

	cookie="<real_cookie>" 

	inHierarchical="false" 

	classId="lsServer">

	<inFilter>

		<eq class="lsServer" 

			property="assocState" 

			value="associated" />

	</inFilter>

</configResolveClass>

Not Equal Filter

The example finds all unassigned servers (assignment state property is not equal to "assigned"). The filter is framed as follows:

<configResolveClass 

	cookie="<real_cookie>" 

	inHierarchical="false" 

	classId="lsServer">

	<inFilter>

		<ne class="lsServer" 

			property="assignState" 

			value="assigned" />

	</inFilter>

</configResolveClass>

Greater Than Filter

The example finds the memory arrays with more than 1024 MB capacity. The filter is framed as follows:

<configResolveClass 

	cookie="<real_cookie>" 

	inHierarchical="false" 

	classId="memoryArray">

	<inFilter>

		<gt class="memoryArray" 

			property="currCapacity" 

			value="1024" />

	</inFilter> 

</configResolveClass>

Greater Than or Equal to Filter

The example finds the memory arrays with 2048 MB capacity or more. The filter is framed as follows:

<configResolveClass 

	cookie="<real_cookie>" 

	inHierarchical="false" 

	classId="memoryArray">

	<inFilter>

		<ge class="memoryArray" 

			property="currCapacity" 

			value="2048" />

	</inFilter>

</configResolveClass>

Less Than Filter

The example finds memory arrays with less than 1024 MB capacity. The filter is framed as follows:

<configResolveClass 

	cookie="<real_cookie>" 

	inHierarchical="false" 

	classId="memoryArray">

	<inFilter>

		<lt class="memoryArray" 

			property="currCapacity" 

			value="1024" />

	</inFilter>

</configResolveClass>

Less Than or Equal to Filter

The example finds memory arrays with 2048 MB capacity or less. The filter is framed as follows:

<configResolveClass 

	cookie="<real_cookie>" 

	inHierarchical="false" 

	classId="memoryArray">

	<inFilter>

		<le class="memoryArray" 

			property="currCapacity" 

			value="2048" />

	</inFilter>

</configResolveClass>

Wildcard Filter

The wildcard filter uses standard regular expression syntax. The example finds any adapter unit whose serial number begins with the prefix "QCI1":

<configResolveClass 

	cookie="<real_cookie>" 

	inHierarchical="false" 

	classId="adaptorUnit">

	<inFilter>

		<wcard class="adaptorUnit" 

			property="serial" 

			value="QCI1*" />

	</inFilter>

</configResolveClass>

Any Bits Filter

This example finds all servers that have a connStatus of either A or B (the property connStatus is a bit mask). The filter is framed as follows:

<configResolveClass 

	cookie="null" 

	inHierarchical="false" 

	classId="computeItem">

	<inFilter>

		<anybit class="computeItem" 

			property="connStatus" 

			value="A,B" />

	</inFilter>

</configResolveClass>

All Bits Filter

The example finds all service profiles with the configQualifier bit mask set to both vnic-capacity and vhba-capacity. The filter is framed as follows:

<configResolveClass 

	cookie="<real_cookie>" 

	inHierarchical="false" 

	classId="lsServer">

	<inFilter>

		<allbits class="lsServer" 

			property="configQualifier"

			value="vnic-capacity,vhba-capacity" />

	</inFilter>

</configResolveClass>

Componsite Filters

This section includes the following topics:

•AND Filter

•OR Filter

•Between Filter

•AND, OR, NOT Composite Filter

AND Filter

To determine all UUIDs assigned and owned by pools, run the following query. The filter is framed as follows:

<configResolveClass 

	cookie="<real_cookie>" 

	inHierarchical="false" 

	classId="uuidpoolAddr">

	<inFilter>

		<and>

			<eq class="uuidpoolAddr" 

				property="owner" 

				value="pool" />

			<eq class="uuidpoolAddr" 

				property="assigned" 

				value="yes" />

		</and>

	</inFilter>

</configResolveClass>  

The response is as follows:

<configResolveClass 

	classId="uuidpoolAddr" 

	cookie="<real_cookie>" 

	response="yes">

	<outConfigs>

		<uuidpoolAddr

			assigned="yes"

			assignedToDn="org-root/ls-foo"

			dn="uuid/F000-00000000000F"

			id="F000-00000000000F"

			owner="pool">

		</uuidpoolAddr>

	</outConfigs>

</configResolveClass> 

In the example, the AND filter finds the chassis with vendor "Cisco Systems Inc" and serial number "CHS A04":

<configResolveClass 

	cookie="<real_cookie>" 

	inHierarchical="false" 

	classId="equipmentChassis">

	<inFilter>

		<and>

			<eq property="vendor" 

				value="Cisco Systems Inc" 

				class="equipmentChassis"/>

			<eq class="equipmentChassis" 

				property="serial" 

				value="CHS A04"/>

		</and>

	</inFilter>

</configResolveClass>

OR Filter

The example returns all objects of type computeItem that are located in slot one or slot eight from all chassis.

<configResolveClass 

	inHierarchical="false" 

	cookie="<real_cookie>" 

	classId="compute">

	<inFilter>

		<or>

			<eq class="computeItem" 

				property="slotId" 

				value="1"/>

			<eq class="computeItem" 

				property="slotId" 

				value="8"/>

		</or>

	</inFilter>

</configResolveClass>

Between Filter

The example finds the memory arrays with slots 1, 2, 3, 4, or 5 populated (note that the between range is inclusive). The filter is framed as follows:

<configResolveClass 

	cookie="<real_cookie>" 

	inHierarchical="false" 

	classId="memoryarray">

	<inFilter>

		<bw class="memoryArray" 

			property="populated" 

			firstValue="1" 

			secondValue="5"/>

	</inFilter>

</configResolveClass>

AND, OR, NOT Composite Filter

The example is an AND, OR, NOT combination. It returns all objects of the computeItem type that are located in slot one or slot eight from all chassis, except chassis five.

<configResolveClass 

	inHierarchical="false" 

	cookie="<real_cookie>" 

	classId="computeItem">

	<inFilter>

		<and>

			<or>

				<eq class="computeItem" property="slotId" value="1"/>

				<eq class="computeItem" property="slotId" value="8"/>

			</or>

			<not>

				<eq class="computeItem" property="chassisId" value="5"/>

			</not>

		</and>

	</inFilter>

</configResolveClass>

Modifier Filter

This section includes the following topic:

•NOT Filter

NOT Filter

The NOT filter can negate a contained filter. The filter is framed as follows. The example queries for servers that do not have a connStatus of unknown (the property connStatus is a bit mask).

<configResolveClass 

	cookie="null" 

	inHierarchical="false" 

	classId="computeItem">

	<inFilter>

		<not>

			<anybit class="computeItem" 

				property="connStatus" 

				value="unknown" />

		</not>

	</inFilter>

</configResolveClass>