Authentication methods initiate and maintain an active session. A successful authentication cookie must be returned by the system before other API calls are allowed.

To authenticate the session, use the following methods:

• aaaLogin—Initializes the session and returns an authentication cookie when successful. The cookie is valid for 600 seconds (10 minutes) and must be refreshed during the session period to prevent it from expiring. A maximum of 4 sessions to CIMC can be opened at any one time.

• aaaRefresh—Creates a new session in place of a previously active session. A new session is created and a new authentication cookie is returned.

• aaaKeepAlive—Maintains the session and keeps the authentication cookie active for another 600 seconds.

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

Operations are performed using the HTTP post method (CIMC supports both HTTP and HTTPS requests) over TCP. HTTP and HTTPS can be configured to use different port numbers, but TCP/80 (or TCP/443 for 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 query methods are supported:

• configResolveDn—Retrieves objects by DN.

• configResolveClass—Retrieves objects of a given class.

• configResolveChildren—Retrieves the child objects of an object.

• configResolveParent—Retrieves the parent object of an object.

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 CIMC 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 CIMC configuration. The resources required for CIMC to process the request can be high, causing CIMC 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	The inRecursive argument and query filters are not supported and are ignored if specified.

Note

Until a host is powered on at least once, CIMC may not have complete inventory and status information. For example, if CIMC 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.

The CIMC supports only a single method to make configuration changes to managed objects:

• configConfMo—Affects a single managed object (for example, a DN) in the management information tree.

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, CIMC starts sending all new events as they occur.

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 CIMC after 600 seconds of inactivity associated with the event channel session cookie. To prevent automatic closing of the event channel connection by CIMC, 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 CIMC using the same event channel session cookie.

Note	The Cisco CIMC XML API sends event notifications only for fault-related events.