HMC registration

Edit online

The HMC Registration API lets you register Hardware Management Consoles (HMCs) with PowerVC and lets you work with managed HMCs. The capabilities include adding new HMCs, removing HMCs, updating the registration information for existing HMCs, or retrieving the information about the HMCs that are currently managed. You must register an HMC before you can register hosts to be managed.

HMC registration options

Table 1. Options for HMC Registration API
Method URI Description

POST

/v2.1/{tenant_id}/ibm-hmcs

Registers or adds an HMC.

GET

/v2.1/{tenant_id}/ibm-hmcs

Lists all HMCs that are managed.

GET

/v2.1/{tenant_id}/ibm-hmcs/detail

Shows details of all managed HMCs

GET

/v2.1/{tenant_id}/ibm-hmcs/{hmc_uuid}

Shows details of a managed HMC.

PUT

/v2.1/{tenant_id}/ibm-hmcs/{hmc_uuid}

Updates or edits a managed HMC.

DELETE

/v2.1/{tenant_id}/ibm-hmcs/{hmc_uuid}

Unregisters or removes a managed HMC.

GET

/v2.1/{tenant_id}/ibm-hmcs/{hmc_uuid}/hosts

Lists hosts that an HMC is managing.

Register an HMC

Registers or adds an HMC to the list managed by PowerVC. This API takes the IP address and credentials for the HMC in the request body as input, and registers the HMC with PowerVC. For details, see these sections:
Response codes
  • Normal Response Code: OK (200)
  • Error Response Codes: Bad Request (400), Server Error (500)
Request parameters
Table 2. Parameters in the request body for registering an HMC
Name Style Type Description

access_ip

body

string

IP address or the host name to connect to the HMC.

user_id

body

string

User ID for connecting to the HMC.

password

body

string

Password for connecting to the HMC.

hmc_display_name

body

string

Optional. User-specified name to give to the HMC. The value defaults to the host name on HMC.

auto_add_certificate

body

Boolean

Optional value. Whether to auto-accept or add the X.509 Certificate for the system (if the fingerprint is not yet trusted or is different from the previously trusted fingerprint) or to fail with a 403 response code so that the certificate can be verified.

Possible values are True (default) and False.

PowerVC validates the HMC certificate against the system trust store. For certificates signed by internal CA, ensure that the CA root and intermediate certificates are present in the system trust store to proceed with successful certificate validation.
Example:
{"hmc": { 
 "registration": { 
   "access_ip": "1.2.3.4", 
   "user_id": "hscroot",
   "password": "passw0rd", 
   "hmc_display_name": "My HMC 1"
  }
  }
}
Response body
Table 3. Parameters in the response for registering an HMC
Name Style Type Description

access_ip

body

string

IP address or the host name that is used to connect to the HMC.

user_id

body

string

User ID that is used for connecting to the HMC.

hmc_display_name

body

string

User-specified name given to the HMC.

hmc_uuid

body

string

Internally generated UUID to lookup the HMC.

registered_at

body

string

The date and time when the HMC was registered in PowerVC.

auto_add_certificate

body

Boolean

Optional value. Whether to auto-accept or add the X.509 Certificate for the system (if the fingerprint is not yet trusted or is different from the previously trusted fingerprint). Whether to fail with a 403 response code so that the certificate can be verified.

Possible values are True (default) and False.

PowerVC validates the HMC certificate against the system trust store. For certificates signed by internal CA, ensure that the CA root and intermediate certificates are present in the system trust store to proceed with successful certificate validation.
Example:
{"hmc": { 
 "registration": { 
   "hmc_uuid": "34ab41180-...", 
   "access_ip": "1.2.3.4",  
   "user_id": "hscroot", 
   "hmc_display_name": "My HMC 1",
   "registered_at": "2013-06-18T13:24:21Z"
  }
 }
}

List all HMCs that are managed

Lists basic information about all the HMCs that are managed by PowerVC. The API takes no input in the request body and returns the UUID and display name for each of the HMCs that are managed in the response body.

Response codes
  • Normal Response Code: OK (200)
  • Error Response Codes: Server Error (500)
Response body
Table 4. Parameters in request and response for storage connectivity groups
Name Style Type Description

hmc_uuid

body

string

Internally generated UUID to lookup the HMC.

hmc_display_name

body

string

User-specified name that is given to the HMC.

 
{"hmcs": [ 
  {"hmc_uuid": "34ab41180-...", "hmc_display_name": "My HMC 1"}, 
  {"hmc_uuid": "2c8de8322-...", "hmc_display_name": "myhostname2"},]
}

Shows details of all managed HMCs

Shows detailed information about all the HMCs that are managed by PowerVC. This API takes no input in request body and returns the IP address, credentials, and health status information about the HMCs in the response body.

Response codes
  • Normal Response Code: OK (200)
  • Error Response Codes: Server Error (500)
Request parameter
Table 5. Request URI and Header
Name Style Type Description

include_available_hosts

query

Boolean

Whether to include the available_hosts attribute in the response body. Default is False, not to include it.
Response body
Table 6. Parameters in the response body viewing details of all managed HMCs
Name Style Type Description

access_ip

body

string

IP address or the host name that is used to connect to the HMC.

user_id

body

string

User ID that is used for connecting to the HMC.

hmc_display_name

body

string

User-specified name that is given to the HMC.

hmc_uuid

body

string

Internally generated UUID to lookup the HMC.

registered_at

body

string

The date and time when the HMC was registered in PowerVC.

managed_hosts

body

list of strings

List of the hosts that are registered.

health_status

body

object

Health of connectivity to the HMC.

available_hosts

body

list of strings

A list of all available hosts that are being managed by the given HMC.
Example:
{"hmcs": [ 
 {
  "hmc_uuid": "34ab41180-...", 
  "hmc_display_name": "My HMC 1", 
  "access_ip": "1.2.3.4", 
  "user_id": "hscroot",
  "registered_at": "2013-06-18T13:24:21Z",
  "managed_hosts": [ "8246L2D_1234567", "8246..." ],
  "health_status": { "health_value": "OK" },
  "available_hosts": [ "8246L2D_1234567", "8246L2D_3456789" ]
 }, 
 {
  "hmc_uuid": "2c8de8322-...",  
  "hmc_display_name": "myhostname2, .... 
 }
}

Show details of a managed HMC

Shows detailed information about one of the HMCs that is managed by PowerVC. This API takes the UUID of the HMC in the URI as input and takes no request body. The API returns the IP address, credentials, and health status information about the HMC in the response body.

Response codes
  • Normal Response Code: OK (200)
  • Error Response Codes: Not Found (404), Server Error (500)
Request parameter
Table 7. Request URI and Header
Name Style Type Description

include_available_hosts

query

Boolean

Whether to include the available_hosts attribute in the response body. Default is False, not to include it.
Response body
Table 8. Parameters in the response body for viewing details of a managed HMC
Name Style Type Description

access_ip

body

string

IP address or the host name that is used to connect to the HMC.

user_id

body

string

User ID that is used for connecting to the HMC.

hmc_display_name

body

string

User-specified name that is given to the HMC.

hmc_uuid

body

string

Internally generated UUID to lookup the HMC.

registered_at

body

string

The date and time when the HMC was registered in PowerVC.

managed_hosts

body

list of strings

List of the hosts that are registered.

health_status

body

object

Health of connectivity to the HMC.

available_hosts

body

list of strings

A list of all available hosts that are being managed by the given HMC.
Example:
{"hmc": { 
 "registration": { 
  "hmc_uuid": "34ab41180-...", 
  "hmc_display_name": "My HMC 1", 
  "access_ip": "1.2.3.4",
  "user_id": "hscroot",
  "registered_at": "2013-06-18T13:24:21Z", 
  "managed_hosts": [ "8246L2D_1234567", "8246..." ],
  "health_status": { "health_value": "OK" },
  "available_hosts": [ "8246L2D_1234567", "8246L2D_3456789" ]
  }
 }
}

Unregister a managed HMC

Removes a managed HMC and all the hosts that managed by that HMC, so that they are no longer managed by PowerVC. This API takes the UUID of the HMC in the URI as input, and takes no request body. The API also returns no response body if successful.

Response codes
  • Normal Response Code: No Content (204)
  • Error Response Codes: Bad Request (400), Not Found (404), Server Error (500)

Update a managed HMC

Edits the registration information for an HMC that is managed by PowerVC. This API takes the UUID of the HMC in the URI and in the body takes the attributes that you want to change as input. The response body contains the attributes that are updated by the request. For details, see these sections:
Response codes
  • Normal Response Code: OK (200)
  • Error Response Codes: Bad Request (400), Not Found (404), Server Error (500)

Request parameters

Table 9. Parameters in the request body for updating a managed HMC
Name Style Type Description

access_ip

body

string

IP address or the host name to connect to the HMC.

user_id

body

string

User ID for connecting to the HMC.

password

body

string

Password for connecting to the HMC.

hmc_display_name

body

string

Optional. User-specified name to give to the HMC. The value defaults to host name on HMC.

auto_add_certificate

body

Boolean

Optional value. Whether to auto-accept or add the X.509 Certificate for the system (if the fingerprint is not yet trusted or is different from the previously trusted fingerprint) or to fail with a 403 response code so that the certificate can be verified. Default value is True.

All the attributes in the request body are optional.

Example:
{"registration": { 
 "access_ip": "1.2.3.4",
 "user_id": "hscroot", 
 "password": "passw0rd",
 "hmc_display_name": "My HMC 1"
 }
}
Response body
Table 10. Parameters in the response body for updating a managed HMC
Name Style Type Description

access_ip

body

string

IP address or the host name that is used to connect to the HMC.

user_id

body

string

User ID that is used for connecting to the HMC.

hmc_display_name

body

string

User-specified name that is given to the HMC.

auto_add_certificate

body

Boolean

Optional value. Whether to auto-accept or add the X.509 Certificate for the system (if the fingerprint is not yet trusted or is different from the previously trusted fingerprint) or to fail with a 403 response code so that the certificate can be verified. Default value is True.
Example:
{"hmc": "34ab41180-...", 
 "registration": { 
   "access_ip": "1.2.3.4",
   "user_id": "hscroot", 
   "hmc_display_name": "My HMC 1"
 }
}

List hosts that an HMC is managing

Lists all the hosts that an HMC is managing independent of whether PowerVC is managing the host. This API takes the UUID of the HMC in the URI as input and takes no request body. The API returns the list of hosts that are managed by the HMC including the name of the host, the number of virtual machines on the host, and whether the host is managed by PowerVC in the response body.

Response codes
  • Normal Response Code: OK (200)
  • Error Response Codes: Not Found (404), Server Error (500)
Response body
Table 11. Parameters in the response body for viewing all hosts that an HMC is managing
Name Style Type Description

host_name

body

string

Internally generated name to register the host.

host_mtms

body

string

Machine type, model, and serial number of the host.

host_vms

body

integer

The number of LPARs that exist on the HMC.

hmc_uuids

body

list of strings

List of UUIDs of the HMCs managing the host in the order of registration.

primary_hmc_uuid

body

string

Primary HMC UUID of the host.
secondary_hmc_uuids

body

list of strings

List of UUIDs of the secondary HMCs managing the host. Only one is supported for failover, based on the order of registration.

host_uuid

body

string

Internally generated UUID to identify the host.
Example:
{
  "hosts": [{
    "host_display_name": "My_Host",
    "primary_hmc_uuid": "30f23783-ed4d-.......",
    "hmc_uuids": ["30f23783-ed4d-....", "29aba615-c036-....."],
    "secondary_hmc_uuids": ["29aba615-c036-......."],
    "host_vms": 3,
    "host_mtms": "8247-42L 212139A",
    "manager_type": "hmc",
    "host_name": "824742L_212139A",
    "is_master": true,
    "host_uuid": "2a0c9288-2c62-.....",
    "master_manager_type": "hmc"
  }