The Unified Computing System (UCS) from Cisco has brought together in one management interface the ability to manage all the UCS components. This includes the switches, servers, LAN connections, SAN connections, authentication, authorization, monitoring, statistics and more. Management of the UCS can be done via the standard methods, command line interface (CLI) and graphical interface (GUI). These interfaces provide all the capability for manual administration of the UCS. To take administration to the next level and automate UCS operations use the UCS XML API.

The UCS XML API at its core is very straight forward in operation; the transport is HTTP/HTTPS utilizing the POST method. The body of the POST message is an XML document that defines the request being made of the UCS API. The request could be a login or logout, a query, a configuration, etc... When a properly formatted request in the form of an XML document is received by the UCS Manager it is acted upon and the result of that action sent back as the HTTP response.

Before I jump into an example there are things to know about the UCS Management software, the UCS Manager (UCSM). The UCSM graphical interface is built entirely upon the UCS API. The functionality of the UCSM GUI is designed to take the dialog box field entries, the points and clicks, the drop-down selections, etc... And turn those items into an XML document that defines the UCS object to be created, modified, or deleted. Every UCS component is represented as XML in the UCS Object Model. The UCS Object Model is a hierarchical structure that defines relationships and dependencies between UCS components. In this hierarchical model can be found the objects that represent the physical and logical components of the UCS, navigating the model in relationship to an object of interest allows for the discovery of children objects, parent objects, and sibling objects.

By default when a UCS is first configured the API interface is on and available over the default ports for HTTP/HTTPS, 80 and 443. An HTTP POST method request is just some appropriately formatted text with a few keywords and a body that contains the message. With this in mind any application that can open a TCP port and send text over that port can be used to interact with the UCS API. For example telnet, telnet opens a port and can send text over the port, wait for and print a response when it comes.

Staying true to the basics of programming here is the UCS API "Hello World" first program that introduces the concept of UCS API session management. There are three UCS API methods that control UCS sessions.

aaaLogin - Login to the UCS Manager and get an authentication cookie
aaaRefresh - Refresh the current authentication cookie
aaaLogout - Deactivate the current authentication cookie

Because you may not have at your disposal an HTTP client that you can feed the POST request to and have it execute, let us use telnet. In future posts I'll write about Java, Perl, PowerShell, python, Ruby, curl, xml, XSLT, you name it. If it is something I have done, seen done, others did and told me about, if it is interesting I'll write about it.

Back to "Hello World", we'll use telnet on port 80; construct a properly formatted HTTP POST method request to utilize the UCS API aaaLogin method to get an authentication cookie. In the example the UCS Manager IP address is 172.21.60.72 and the user credentials are admin/cisco123.

The Request

-bash-3.00$ telnet 172.21.60.72 80
Trying 172.21.60.72...
Connected to 172.21.60.72.
Escape character is '^]'.
POST /nuova HTTP/1.1
Host: 172.21.60.72
Content-Length: 51

<aaaLogin inName="admin" inPassword="cisco123" />

The response

HTTP/1.1 200 OK
Date: Wed, 24 Mar 2010 18:52:48 GMT
Server: Apache/2.2.2 (Unix) mod_ssl/2.2.2 OpenSSL/0.9.7c
Content-Length: 218
Content-Type: application/soap+xml

<aaaLogin cookie="" response="yes" outCookie="1269456768/54e06ba5-5dfd-467a-8fc4-6c9b97624088" outRefreshPeriod="600" outPriv="admin,read-only" outDomains="" outChannel="noencssl" outEvtChannel="noencssl"> </aaaLogin>

Let's break this response down

1. <aaaLogin cookie=""
2. response="yes"
3. outCookie="1269456768/54e06ba5-5dfd-467a-8fc4-6c9b97624088"
4. outRefreshPeriod="600"
5. outPriv="admin,read-only"
6. outDomains=""
7. outChannel="noencssl"
8. outEvtChannel="noencssl">
9. </aaaLogin>

1. Line 1 shows the element aaaLogin is the UCS API method used to login to the UCS. The UCS returns
   a response message with the result.
2. Line 2 confirms that this is a response from the API aaaLogin request.
3. Line 3 is the attribute outCookie having a value of
   1269456768/54e06ba5-5dfd-467a-8fc4-6c9b97624088. This attribute is the session cookie.
4. Line 4 is the attribute outRefreshPeriod with a value of 600 seconds (10 minutes). This is the
   recommended cookie refresh period. The default login session length is two hours.
5. Line 5 is the attribute outPriv which contains the privileges that the user account has been assigned.
6. Line 6 is the attribute outDomains with an empty value.
7. Line 7 is the attribute outChannel with the value noencssl. This indicates that this session is not using
   encryption over SSL.
8. Line 8 is the attribute outEvtChannel with the value noencssl. This indicates that any event subscriptions
   would not use encryption over SSL.
9. Line 9 is the closing tag for the root element aaaLogin.

We have an authentication cookie but this cookie will expire in two hours, the output from the aaaLogin recommends a cookie refresh every 10 minutes. To refresh the authentication cookie use the aaaRefresh method.

The Request

-bash-3.00$ telnet 172.21.60.72 80
Trying 172.21.60.72...
Connected to 172.21.60.72.
Escape character is '^]'.
POST /nuova HTTP/1.1
Host: 172.21.60.72
Content-Length: 113

<aaaRefresh inName="admin" inPassword="cisco123" inCookie="1269470029/ecaf27b7-0725-4ec8-8971-7a752be4b3f1" />

The Response

HTTP/1.1 200 OK
Date: Wed, 24 Mar 2010 22:36:38 GMT
Server: Apache/2.2.2 (Unix) mod_ssl/2.2.2 OpenSSL/0.9.7c
Content-Length: 222
Content-Type: application/soap+xml

<aaaRefresh cookie="" response="yes" outCookie="1269470204/e3dfe86b-86a9-4c75-84b7-059847583cd0" outRefreshPeriod="600" outPriv="admin,read-only" outDomains="" outChannel="noencssl" outEvtChannel="noencssl"> </aaaRefresh>

When using the aaaRefresh method the XML will have the same attributes as the aaaLogin method, plus an additional attribute inCookie; whose value will be the current valid cookie for the user value associated with the inName attribute.

A the end of a UCS API session deactivate the currently valid session cookie using the aaaLogout method. The aaaLogout method deactivates the session cookie and releases and UCS manager resources associated with the session.

The Request

-bash-3.00$ telnet 172.21.60.72 80
Trying 172.21.60.72...
Connected to 172.21.60.72.
Escape character is '^]'.
POST /nuova HTTP/1.1
Host: 172.21.60.72
Content-Length: 73

<aaaLogout inCookie="1269470204/e3dfe86b-86a9-4c75-84b7-059847583cd0" />

The Response

HTTP/1.1 200 OK
Date: Wed, 24 Mar 2010 22:46:41 GMT
Server: Apache/2.2.2 (Unix) mod_ssl/2.2.2 OpenSSL/0.9.7c
Content-Length: 70
Content-Type: application/soap+xml

<aaaLogout cookie="" response="yes" outStatus="success"> </aaaLogout>

Would an application utilizing the UCS API actually be wtitten using telnet? I don't think so but the idea I'm conveying here is the simplicity of interaction with the UCS API. An actual application would have used a programming/scripting language or an HTTP/HTTPS enabled utility.

Next time I'll discuss two utilities, curl to send the request and receive the response and xml to manipulate the response.

Also be sure to check the UCS documentation for additional information.

John McDonough
Cisco Advanced Services
UCS Compute and Virtualization Practice