dropdown menu

HMC API:

API (Application Programming Interface) is an interface (a code or a program) which receives requests and sends responses. For example a weather application on a smartphone sends a request to a remote server and the API (on the remote server) sends back the current temperature. On HMC these things are managed by a web server and they are communicating via HTTP requests. The HMC API provides an additional tool for deploying, managing LPARs, VIOS etc.

It operates on HTTP port 12443 (it is using TLS). In the HTTP requests we need to specify on which element (Managed System, LPAR, VIO, SSP, vSCSI adapter...) which task (GET, PUT, POST and DELETE) is needed. To achieve this a complex URL is used with additional xml files.


Tasks that can be achieved:
GET: list details of a specific resource
PUT: usually used to create a new resource
POST: usually used to modify an already existing resource
DELETE: deletes a resource


The structure of the URL looks like this:
/rest/api/uom/{R}/operations                   <--get the defined job operations for {R}
/rest/api/uom/{R}/{UUID}/do/{OP}               <--get a template for job of type {OP}

/rest/api/uom/{R}/{UUID}/{C}/operations        <--get the defined job operations for {C}
/rest/api/uom/{R}/{UUID}/{C}/{UUID}/do/{OP}    <--get a template for job of type {OP}

{R} - is a Root object (like a Managed System)
{C} - is a Child object of a Root object (like an LPAR on a Managed System)
{UUID} - identifies a specific object (like a specific LPAR, it has this syntax: 31a90881-7523-3f1d-a4bf-6ddf3b8ab7c3)
{OP} - operation we want to do on the specific object (like Power On a Managed System)

for example to power off a Managed System:
/rest/api/uom/ManagedSystem/31a90881-7523-3f1d-a4bf-6ddf3b8ab7c3/do/PowerOff

Checking this pdf will show what should be the correct syntax:
http://ftpmirror.your.org/pub/misc/ftp.software.ibm.com/systems/power/docs/hw/p9/p9ehl.pdf

For every request API sends back a status code. Status codes show the results of the requests:
200 (OK): the request is succeeded and a response is provided
204 (No Content): the request is succeeded and no additional response is provided
400 (Bad Request): there is an error in the requests (probably a syntax error)
403 (Forbidden): not authorized for that specific request
404 (Not Found): the URL resource does not exists or use has no permission to access it
...
...

Steps needed to use HMC API:
1. Authenticate with HMC
2. Sending requests to HMC API

All actions can be done using Python, Java, PHP, C++ etc., but it also works with curl, which is good if someone doesn't want to use programming language environments. In below examples will use curl.

When referring to HMC in curl command it is possible to use:
https://<HMC_IP>/rest/api...
https://<HMC_NAME>/rest/api...
https://<HMC_NAME>:12443/rest/api...

----------------------------------

Authentication with HMC

Authenticating with HMC is the first step. A login.xml file needs to be created (with user and password), which will be used at the first login. If it is successful a trusted session is established and a cookies.txt (jar file) is generated which will be re-used for later requests. (the Logoff request disconnects or closes a session)

1.Create a login.xml file:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<LogonRequest xmlns="http://www.ibm.com/xmlns/systems/power/firmware/web/mc/2012_10/" schemaVersion="V1_0">
  <UserID>hscroot</UserID>
  <Password>abcd1234</Password>
</LogonRequest>

2.Authenticate with HMC
# curl -k -c cookies.txt -i -X PUT -H "Content-Type: application/vnd.ibm.powervm.web+xml; type=LogonRequest" -H "Accept: application/vnd.ibm.powervm.web+xml; type=LogonResponse" -H "X-Audit-Memento: hmc_test" -d @login.xml https://ls-hmc02.mycompany.vmta/rest/api/web/Logon

-k : “insecure” mode. It permits the use of the self signed certificate used by the HMC.
-c cookies.txt : setup the cookies jar where authentication session informations will be kept.
-X PUT : use PUT request method. Requested by the HMC API.
-d @login.xml : will use content of login.xml.
-H : http headers added to the request.
-i : show the http headers of the answer. Useful for debugging.

Content-Type: application/vnd.ibm.powervm.web+xml; type=LogonRequest    <---specifies the request content format
Accept: application/vnd.ibm.powervm.web+xml; type=LogonResponse :       <---specifies the expected response content format
“X-Audit-Memento: hmc_test”                                             <---a simple comment

Response should look like:
HTTP/1.1 200 OK
Date: Thu, 09 Apr 2020 09:26:12 GMT
Server: Apache
X-Frame-Options: SAMEORIGIN
X-Powered-By: Servlet/3.0
X-Transaction-ID: XT10000003
Content-Type: application/vnd.ibm.powervm.web+xml; type=LogonResponse
Content-Language: en-US
Content-Length: 576
Expires: Thu, 01 Dec 1994 16:00:00 GMT
Cache-Control: no-cache="set-cookie, set-cookie2"
Set-Cookie: JSESSIONID=0000HWdO8vEpjtW6ctYAt1rDxlh:08d79c41-17cd-461b-bb48-079a931706b4; Path=/; Secure; HttpOnly
Set-Cookie: CCFWSESSION=0376B4771B26DE69F149E573A4E37751; Path=/; Secure; HttpOnly
Vary: User-Agent
X-XSS-Protection: 1; mode=block

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<LogonResponse xmlns="http://www.ibm.com/xmlns/systems/power/firmware/web/mc/2012_10/" xmlns:ns2="http://www.w3.org/XML/1998/namespace/k2" schemaVersion="V1_7_0">
    <Metadata>
        <Atom/>
    </Metadata>
    <X-API-Session kxe="false" kb="ROR">P-2YNulbgJ-N-Jk9kUKBdtEEcSmny-ah_YJ818uqby0-444kYl0-SD1wdy4TXDWCtR4ToGuZrqMvX3i1q4F_x3LplU5MQdYQFZhQNuTUylJ806tBmgNmHaFlFZkTs4wL-X3bUeywm8SVMkWb-2rZbxPx8vrMeuotorfK2rUMVCDCVbc-k83qlQeKM19p2azo4yNXb8GCG-uEQ1j0G0oazBIjNtFP6gKB1wz-D70sq5o=</X-API-Session>
</LogonResponse>


If authentication is successful we receive a 200 return code and cookies.txt is generated.

----------------------------------

Sending requests to HMC API

After successful authentication API requests can be sent.

List details of resources:
(These examples will list UUID of the spcified resource and beside that version,name etc. is also listed.)
# curl -k -c cookies.txt -b cookies.txt -H "Accept: application/atom+xml; charset=UTF-8" https://myhmc.com/rest/api/uom/ManagementConsole
# curl -k -c cookies.txt -b cookies.txt -H "Accept: application/atom+xml; charset=UTF-8" https://myhmc.com/rest/api/uom/ManagedSystem
# curl -k -c cookies.txt -b cookies.txt -H "Accept: application/atom+xml; charset=UTF-8" https://myhmc.com/rest/api/uom/LogicalPartition

-b cookies.txt: use the appropriate cookies during the session.
-H “Accept: application/atom+xml; charset=UTF-8” : the expected response should be a atom feed.


List possible operations for the specified object (here ManagementConsole):
# curl -k -c cookies.txt -b cookies.txt -H "Accept: application/atom+xml; charset=UTF-8" https://myhmc.com/rest/api/uom/ManagementConsole/operations


To get info from a specific LPAR:
# curl -k -c cookies.txt -b cookies.txt -i -H "Accept: application/atom+xml; charset=UTF-8" https://myhmc.com/rest/api/uom/LogicalPartition/search/\(PartitionName\=\=ld-aix01\)


----------------------------------

Modify a resources

Always perform GET on the resource, copy the output to an xml file, modify the content as desired and then perform POST operation.

For example to change the name of an LPAR:
1. Perform GET: # curl -k -c cookies.txt -b cookies.txt -i -H "Content-Type: application/vnd.ibm.powervm.uom+xml; Type=LogicalPartition" -H "Accept: application/atom+xml; charset=UTF-8" -X GET https://myhmc.com/rest/api/uom/LogicalPartition/{UUID}
2. Copy the output from <LogicalPartition:LogicalPartition> until to </LogicalPartition:LogicalPartition> and save it as an xml file (for example lpar.xml)
3. Edit the xml to modify the <PartitionName> attribute with desired name
4. Perform POST using that xml file: # curl -k -c cookies.txt -b cookies.txt -i -H "Content-Type: application/vnd.ibm.powervm.uom+xml; Type=LogicalPartition" -H "Accept: application/atom+xml; charset=UTF-8" -X POST -H "Expect:" -d @lpar.xml https://myhmc.com/rest/api/uom/LogicalPartition/{UUID}

----------------------------------

Create an LPAR

1. Perform a GET on an existing LPAR:
# curl -k -c cookies.txt -b cookies.txt -i -H "Content-Type: application/vnd.ibm.powervm.uom+xml; Type=LogicalPartition" -H "Accept: application/atom+xml; charset=UTF-8" -X GET https://myhmc.com/rest/api/uom/LogicalPartition/{UUID}

2. Save the output to an xml file (modify values as needed)
<LogicalPartition:LogicalPartition xmlns:LogicalPartition=" http://www.ibm.com/xmlns/systems/power/firmware/uom/mc/2012_10 "http://www.ibm.com/xmlns/systems/power/firmware/uom/mc/2012_10/" />" xmlns:ns2=" http://www.w3.org/XML/1998/namespace/k2 " schemaVersion="V1_8_0">

<PartitionID kb="COD" kxe="false">29</PartitionID>
<PartitionMemoryConfiguration kb="CUD" kxe="false" schemaVersion="V1_8_0">
<Metadata>
<Atom/>
</Metadata>
<DesiredMemory kb="CUD" kxe="false">512</DesiredMemory>
<MaximumMemory kb="CUD" kxe="false">1024</MaximumMemory>
<MinimumMemory kb="CUD" kxe="false">256</MinimumMemory>
</PartitionMemoryConfiguration>
<PartitionName kxe="false" kb="CUR">lpar5</PartitionName>
<PartitionProcessorConfiguration kb="CUD" kxe="false" schemaVersion="V1_8_0">
<Metadata>
<Atom/>
</Metadata>
<DedicatedProcessorConfiguration kb="CUD" kxe="false" schemaVersion="V1_8_0">
<Metadata>
<Atom/>
</Metadata>
<DesiredProcessors kb="CUD" kxe="false">2</DesiredProcessors>
<MaximumProcessors kxe="false" kb="CUD">2</MaximumProcessors>
<MinimumProcessors kb="CUD" kxe="false">2</MinimumProcessors>
</DedicatedProcessorConfiguration>
<HasDedicatedProcessors kxe="false" kb="CUD">true</HasDedicatedProcessors>
<SharingMode kxe="false" kb="CUD">sre idle proces</SharingMode>
</PartitionProcessorConfiguration>
<PartitionType kxe="false" kb="COD">AIX/Linux</PartitionType>
</LogicalPartition:LogicalPartition>


3. Perform PUT with xml file
# curl -k -c cookies.txt -b cookies.txt -i -H "Content-Type: application/vnd.ibm.powervm.uom+xml; Type=LogicalPartition" -H "Accept: application/atom+xml; charset=UTF-8" -X PUT -H "Expect:" -d @newlpar.xml https://myhmc.com/rest/api/uom/ManagedSystem/<ManagedSystem_UUID>/LogicalPartition


----------------------------------

Deleting an LPAR

# curl -k -c cookies.txt -b cookies.txt -i -H "Content-Type: application/vnd.ibm.powervm.web+xml; type=LogicalPartitionProfile" -H "Accept: application/atom+xml; charset=UTF-8" -X DELETE -H "Expect:" https://myhmc.com:12443/rest/api/uom/LogicalPartition/<LPAR_UUID>

----------------------------------

CLIRunner

CLIRunner is an API function which runs HMC commnads using API. Not all commands possible to use to use, some of them are: chhmcusr, lshmc, lshmcusr, hmcshutdown, migrlpar, viosvrcmd ... (viosvrcmd is very useful if we want to run VIOS commands from the HMC)


In below example I will change HMC user description from aaaaa to bbbbb
# lshmcusr --filter "names=sysadmin"
name=sysadmin,taskrole=hmcsuperadmin,description=aaaaa,...


1. create an xml file for CLIRunner (format templates can be found in HMC REST APIs pdf):
<?xml version="1.0" encoding="UTF-8"?>
<JobRequest:JobRequest xmlns:JobRequest="http://www.ibm.com/xmlns/systems/power/firmware/web/mc/2012_10/" xmlns="http://www.ibm.com/xmlns/systems/power/firmware/web/mc/2012_10/" xmlns:ns2="http://www.w3.org/XML/1998/namespace/k2" schemaVersion="V1_2_0">
   <Metadata>
      <Atom />
   </Metadata>
   <RequestedOperation kxe="false" kb="CUR" schemaVersion="V1_2_0">
      <Metadata>
         <Atom />
      </Metadata>
      <OperationName kxe="false" kb="ROR">CLIRunner</OperationName>
      <GroupName kxe="false" kb="ROR">ManagementConsole</GroupName>
   </RequestedOperation>
   <JobParameters kxe="false" kb="CUR" schemaVersion="V1_2_0">
      <Metadata>
         <Atom />
      </Metadata>
      <JobParameter schemaVersion="V1_0">
         <Metadata>
            <Atom />
         </Metadata>
         <ParameterName kxe="false" kb="ROR">cmd</ParameterName>
         <ParameterValue kxe="false" kb="CUR">chhmcusr -u sysadmin -t desc -v bbbbb</ParameterValue>
      </JobParameter>
      <JobParameter schemaVersion="V1_0">
         <Metadata>
            <Atom />
         </Metadata>
         <ParameterName kxe="false" kb="ROR">acknowledgeThisAPIMayGoAwayInTheFuture</ParameterName>
         <ParameterValue kxe="false" kb="CUR">true</ParameterValue>
      </JobParameter>
   </JobParameters>
</JobRequest:JobRequest>

(I had to change schemaversion from V1_2 to V1_2_0 otherwise I recived HTTP 400 Bad Request)

2. run CLIRunner:
curl -k -c cookies.txt -b cookies.txt -i -H "Content-Type: application/vnd.ibm.powervm.web+xml; Type=JobRequest" -H "Accept: application/atom+xml; charset=UTF-8" -X PUT -H "Expect:" -d @chhmcusr.xml https://192.168.0.9/rest/api/uom/ManagementConsole/31a90881-7523-3f1d-a4bf-6ddf3b8ab7c3/do/CLIRunner

HMC UUID: the unique identifier of HMC is shown if we list details of the ManagementConsole (curl ... https://myhmc.com/rest/api/uom/ManagementConsole)
@chhmcusr.xml: this is the file above we saved with the chhmcusr command


After successful run:
# lshmcusr --filter "names=sysadmin"
name=sysadmin,taskrole=hmcsuperadmin,description=bbbbb

----------------------------------

Additional reading: https://www.djouxtech.net/posts/hmc-v8-rest-api-part-1-curl/




No comments:

Post a Comment