The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
This chapter includes the following sections:
Authentication allows XML API interaction with the CIMC. 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. |
To log in, the XML API client establishes a TCP connection to the CIMC HTTP (or HTTPS) server and posts an XML document containing the aaaLogin method.
In the following example, the Telnet utility is used to establish a TCP connection to port 80 of the CIMC with IP address 192.0.20.72. The path used is /nuova.
$ telnet 192.0.20.72 80 POST /nuova HTTP/1.1 USER-Agent: lwp-request/2.06 HOST: 192.0.20.72 Content-Length: 62 Content-Type: application/x-www-form-urlencoded
Next, the client specifies the aaaLogin method and provides a user name and password:
<aaaLogin inName='admin' inPassword='password'> </aaaLogin>
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, CIMC reads the request and performs the actions as provided in the method. CIMC 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="admin"> 6 </aaaLogin>
Each line in the response should be interpreted as follows:
Alternatively, you can use the cURL utility to log in to the XML API, as shown in the following example:
curl -d "<aaaLogin inName='admin' inPassword='password'></aaaLogin>" http://192.0.20.72/nuova
If HTTPS is enabled, you must use HTTPS in the cURL command, as shown in the following example:
curl -d "<aaaLogin inName='admin' inPassword='password'></aaaLogin>" https://192.0.20.72/nuova
Sessions are refreshed with the aaaRefresh method, using the 47-character cookie obtained either from the aaaLogin response or a previous refresh.
<aaaRefresh cookie="<real_cookie>" inCookie="<real_cookie>" inName='admin' inPassword='password'> </aaaRefresh>
Use the following method to log out of a session:
<aaaLogout cookie="<real_cookie>" inCookie="<real_cookie>" </aaaLogout>
Failed login:
<aaaLogin cookie="" response="yes" errorCode="551" invocationResult="unidentified-fail" errorDescr="Authentication failed"> </aaaLogin>
Nonexistent object (blank return indicates no object with the specified DN):
<configResolveDn cookie="<real_cookie>" response="yes" dn="sys/rack-unit-1/adaptor-9999"> <outConfig> </outConfig> </configResolveDn>
Bad request:
<configConfMo cookie="<real_cookie>" response="yes" dn="sys/rack-unit-1/adaptor-1/ext-eth-0"> errorCode="103“ invocationResult="unidentified-fail“ errorDescr="can't create; object already exists."> </configConfMo>
Query Methods
When resolving children of objects in the MIT, note the following:
See the example request/response in configResolveChildren.
When resolving a class, note the following:
Result sets can be large. Be precise when defining result sets. For example, to obtain only a list of adapters, use adaptorUnit as the attribute value for classId in the query. This example queries for all instances of the adaptorUnit class:
<configResolveClass
cookie="real_cookie"
inHierarchical="false"
classId="adaptorUnit"/>
See the example request/response in configResolveClass.
When resolving a DN, note the following:
See the example request/response in configResolveDn.
When resolving the parent object of an object, note the following:
See the example request/response in configResolveParent.