Authentication methods authenticate and maintain the session. For example:

• aaaLogin—Initial method for logging in.

• aaaRefresh—Refreshes the current authentication cookie.

• aaaLogout—Exits the current session and deactivates the corresponding authentication cookie.

Use the aaaLogin method to get a valid cookie. Use aaaRefresh to maintain the session and keep the cookie active. Use the aaaLogout method to terminate the session (also invalidates the cookie). A maximum of 256 sessions to the Cisco UCS can be opened at any one time.

Operations are performed using the HTTP post method (Cisco UCS supports both HTTP and HTTPS requests) over TCP. HTTP and HTTPS can be configured to use different port numbers, but TCP/443 (or TCP/80 for non-secure connections) is used by default. The HTTP envelope contains the XML configuration.

Tip	In CIMC, HTTP to HTTPS redirection is enabled by default. To capture HTTP packets between the client application and CIMC, disable redirection in the CIMC GUI or CLI.

Query methods obtain information on the current configuration state of an object. The following are query examples:

• configResolveDn—Retrieves objects by DN.

• configResolveDns—Retrieves objects by a set of DNs.

• configResolveClass—Retrieves objects of a given class.

• configResolveClasses—Retrieves objects of multiple classes.

• configFindDnsByClassId—Retrieves the DNs of a specified class.

• configResolveChildren—Retrieves the child objects of an object.

• configResolveParent—Retrieves the parent object of an object.

• configScope—Performs class queries on a DN in the management information tree.

Most query methods have the argument inHierarchical (Boolean true/yes or false/no). If true, the inHierarchical argument returns all child objects.

<configResolveDn … inHierarchical="false"></>
<configResolveDn … inHierarchical="true"></>

Because the amount of data returned from Cisco UCS can be quite large, the inHierarchical argument should be used with care. For example, if the query method is used on a class or DN that refers to a managed object (MO) that is located high on the management information tree and inHierarchical is set to true, the response can contain almost the entire Cisco UCS configuration. The resources required for Cisco UCS to process the request can be high, causing Cisco UCS to take an extended amount of time to respond. To avoid delays, the query method should be performed on a smaller scale involving fewer MOs.

Tip	If a query method does not respond or is taking a long time to respond, increase the timeout period on the client application or adjust the query method to involve fewer MOs.

The query API methods might also have an inRecursive argument to specify whether the call should be recursive (for example, follow objects that point back to other objects or the parent object).

The API also provides a set of filters to increase the usefulness of the query methods. These filters can be passed as part of a query and are used to identify the wanted result set.

Note

Until a host is powered on at least once, Cisco UCS may not have complete inventory and status information. For example, if Cisco UCS is reset, it will not have detailed CPU, memory, or adapter inventory information until the next time the host is powered on. If a query method is performed on a MO corresponding to the unavailable data, the response will be blank.

There are several methods to make configuration changes to managed objects. These changes can be applied to the whole tree, a subtree, or an individual object. The following are examples of configuration methods:

• configConfMo—Affects a single managed object (for example, a DN).

• configConfMos—Affects multiple subtrees (for example, several DNs).

• configConfMoGroup—Makes the same configuration changes to multiple subtree structures (DNs) or managed objects.

Most configuration methods use the argument inHierarchical (Boolean true/yes or false/no). These values do not play a significant role during configuration because child objects are included in the XML document and the DME operates in the forgiving mode.

Applications get state change information by regular polling or event subscription. For more efficient use of resources, event subscription is the preferred method of notification. Polling should be used only under very limited circumstances.

Use eventSubscribe to register for events, as shown the following example:

<eventSubscribe 
    cookie="<real_cookie>">
</eventSubscribe>

To receive notifications, open an HTTP or HTTPS session over TCP and keep the session open. On receiving eventSubscribe, Cisco UCS starts sending all new events as they occur. You can unsubscribe from these events using the eventUnsubscribe method.

Each event has a unique event ID. Event IDs operate as counters and are included in all method responses. When an event is generated, the event ID counter increments and is assigned as the new event ID. This sequential numbering enables tracking of events and ensures that no event is missed.

An event channel connection opened by a user will be closed automatically by Cisco UCS after 600 seconds of inactivity associated with the event channel session cookie. To prevent automatic closing of the event channel connection by Cisco UCS, the user must either send the aaaKeepAlive request for the same event channel session cookie within 600 seconds or send any other XML API method to Cisco UCS using the same event channel session cookie.

Interchange is stored in a log file such as C:\Documents and Settings\username\Application Data\Sun\Java\Deployment\log\.ucsm. Due to internal security requirements, this information is not always complete. However, you can use a commercial packet analyzer application to observe sent XML.