HMC registration

HMC registration options

Register an HMC

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.

Example:

{"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

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"
  }