Adding VMWare vCenter Server or Hyper-V server¶
Register VMware vCenter Server or Hyper-V server with IBM Spectrum Protect Plus. A hypervisor inventory job will start automatically after a new vCenter Server is registered successfully.
See also
For more information about hypervisor inventory, see Running an inventory job for virtualized systems.
Method and URI¶
To register VMware vCenter Server or Hyper-V server with IBM Spectrum Protect Plus, use a POST method and a URI:
POST https://{hostname|IP}/ngp/hypervisor
Parameters¶
None.
Data¶
Data 1: hostAddress
The hostname or the IPv4 address of VMware vCenter server or Hyper-V server.
Example value: 10.0.0.10
Type: String. Required. Available in the web user interface.
Data 2: portNumber
The port number to connect to the VMware vCenter Server or Hyper-V server.
When you connect to Hyper-V server, typically, you will use Microsoft Windows Remote Management (WinRM) over HTTPS or HTTP. To connect to Hyper-V server without using the SSL, you must enable WinRM on the Hyper-V host system. For more information, see the IBM Spectrum Protect Plus Installation and User’s Guide”.
Example value: You can use the following typical values:
Virtualized system |
SSL |
Value |
---|---|---|
VMware vCenter |
x |
443 |
VMware vCenter |
80 |
|
Hyper-V server |
x |
5986 |
Hyper-V server |
5985 |
Type: Integer. Required. Available in the web user interface.
Data 3: type
The type of the virtualized system.
Value: Use one of the following values:
Virtualized system |
Value |
---|---|
VMware vCenter |
|
Hyper-V server |
|
Type: System string. Required. Available in the web user interface.
Data 4: username
The {identityUserHref}
of the existing user.
Tip
To get an {identityUserHref}
value based on the username, follow the instructions in Getting an {identityUserHref}.
Example value: https://10.0.0.100/api/identity/user/2139
Type: String. Required. Available in the web user interface.
Data 5: sslConnection
Indication of whether SSL is used for the connection.
Example value:
true
to enable SSL.Type: Boolean. Required. Available in the web user interface.
Data 6: opProperties
Optional properties.
Example value:
{
"snapshotConcurrency": 3
}
Type: JSON object. Required. Available in the web user interface.
Data 6: opProperties
> snapshotConcurrency
The maximum number of virtual machines to process cuncorrently per ESX server or Hyper-V server.
Example value: 3 (default)
Type: Integer. Required. Available in the web user interface.
Example 1: Register VMware vCenter server with IBM Spectrum Protect Plus¶
Assume that you want to register the following VMware vCenter Server with IBM Spectrum Protect Plus:
Hostname/IP: 10.0.0.10
Port: 443 (HTTPS)
Username: AD-BLUEMACHINESsarah.wiseman (
{identityUserHref}
https://10.0.0.100/api/identity/user/2138)Use SSL: Yes
Maximum number of VM’s to process concurrently per ESX server: 3
A Python snippet that is similar to the following example can be used to register VMware vCenter server with IBM Spectrum Protect Plus:
_data = f'''{{
"hostAddress": "10.0.0.10",
"portNumber": 443,
"username": "https://10.0.0.100/api/identity/user/2137",
"sslConnection": true,
"type": "vmware",
"opProperties": {{
"snapshotConcurrency":3
}}
}}'''
requests.post('https://' + spp_ipv4 + '/ngp/hypervisor',
headers={...}, params="", data=_data, verify=...)

Figure 23 The same action can be taken in the IBM Spectrum Protect Plus web user interface: In the VMware pane, click the Manage vCenter, fill in the required fields and click Save.¶
The request prompts a response that is structured as shown, with the HTTP status of 201 (Created).
{
"statusCode": 201,
"response": {
"links": {...},
"name": "10.0.0.10",
"hostAddress": "10.0.0.10",
"user": {
"href": "https://10.0.0.100:-1/api/identity/user/2137"
},
"sslConnection": true,
"portNumber": 443,
"type": "vmware",
"id": "1001",
"uniqueId": "fa8f1a0f-9d01-44e6-b281-6c577cd920ae",
"version": null,
"build": null,
"apiVersion": null,
"properties": {},
"logicalDelete": false,
"accountName": null,
"opProperties": {
"snapshotConcurrency": 2,
"veServerInfo": null
},
"rbacPath": "root:0/hypervisor.all:0/hypervisor.type:vmware/hypervisor:1
↪001",
"resourceType": "hypervisor"
}
}
If the connection with IBM Spectrum Protect Plus has failed, for example, when an incorrect host address or an unavailable port number was given, the request prompts a response that is structured as shown, with the HTTP status of 400 (Bad Request).
{
"statusCode": 400,
"response": {
"id": "HypervisorConnectionException",
"description": "Could not connect to server 10.0.0.200: Exception caught
↪ trying to invoke method RetrieveServiceContent; nested exception is: \n\tjava.
↪net.ConnectException: Connection refused (Connection refused)",
"title": "Error"
}
}
If you enter an invalid username and password, the request prompts a response that is structured as shown, with the HTTP status of 401 (Unauthorized).
{
"statusCode": 401,
"response": {
"id": "HypervisorConnectionAuthException",
"description": "Authentication failed. Ensure the username and password
↪are correct. User must have all vCenter VMware User privileges as document
↪ed.",
"title": "Error"
}
}
Example 2: Register a Hyper-V Server¶
Assume that you want to register the following Microsoft Hyper-V Server in IBM Spectrum Protect Plus:
Hostname/IP: hyperv.dallas.bluemachines.com.invalid
Port: 5986 (WinRT over HTTPS)
Username: AD-BLUEMACHINESsarah.wiseman (
{identityUserHref}
https://10.0.0.100/api/identity/user/2138)Use SSL: Yes
Maximum number of VM’s to process concurrently per Hyper-V Server: 3
A Python snippet that is similar to the following example can be used to register Hyper-V Server with IBM Spectrum Protect Plus:
_data = f'''{{
"hostAddress": "hyperv.dallas.bluemachines.com.invalid",
"portNumber": 5986,
"username": "AD-BLUEMACHINES\\\\sarah.wiseman",
"sslConnection": false,
"type": "hyperv",
"opProperties": {{"snapshotConcurrency":3}}
}}'''
requests.post('https://' + spp_ipv4 + '/ngp/hypervisor',
headers={...}, params="", data=_data, verify=...)

Figure 24 The same action can be taken in the IBM Spectrum Protect Plus web user interface: In the Hyper-V pane, click the Manage Hyper-V Server, fill in the required fields and click Save.¶
The request prompts a response that is structured as shown, with the HTTP status of 201 (Created).
{
"statusCode": 201,
"response": {
"links": {...}
},
"name": "hyperv.dallas.bluemachines.com.invalid",
"hostAddress": "hyperv.dallas.bluemachines.com.invalid",
"user": {
"href": "https://10.2.1.10:-1/api/identity/user/2138"
},
"sslConnection": false,
"portNumber": 5986,
"type": "hyperv",
"id": "1002",
"uniqueId": "2d60ba76-9161-3492-ae5d-80f0b067760a",
"version": null,
"build": null,
"apiVersion": null,
"properties": {},
"logicalDelete": false,
"accountName": null,
"opProperties": {
"snapshotConcurrency": 3,
"veServerInfo": null
},
"rbacPath": "root:0/hypervisor.all:0/hypervisor.type:hyperv/hypervisor:1
↪002",
"resourceType": "hypervisor"
}
}
If the connection with IBM Spectrum Protect Plus has failed, for example, when an incorrect host address or an unavailable port number was given, the request prompts a response that is structured as shown, with the HTTP status of 400 (Bad Request).
{
"statusCode": 400,
"response": {
"id": "HypervisorConnectionException",
"description": "Could not connect to server hyperv.dallas.bluemachines.c
↪om.invalid: Connect to Hyper-V Server hyperv.dallas.bluemachines.com.invalid fa
↪iled. Cause: intel.management.wsman.WsmanException: Connect to hyperv.dallas.bl
↪uemachines.com.invalid:1 [hyperv.dallas.bluemachines.com.invalid/10.2.1.10] fai
↪led: Connection refused (Connection refused)",
"title": "Error"
}
}
If you enter an invalid username and password, the request prompts a response that is structured as shown, with the HTTP status of 401 (Unauthorized).
{
"statusCode": 401,
"response": {
"id": "HypervisorAuthException",
"description": "Authentication failed. Ensure the username and password
↪are correct. The username must be a member of the local administrators group. F
↪or non-SSL connections, set the \"AllowUnencrypted\" permission to true by ente
↪ring the following command in a Windows command prompt running with elevated pr
↪ivileges (start the command prompt with the \"Run as administrator\" option):\n
↪\nwinrm set winrm/config/service @{AllowUnencrypted=\"true\"}\n\nIn cluster env
↪ironments, ensure all nodes meet the above requirements. Ensure you understand
↪the security risks associated with configuring WinRM to allow unencrypted netwo
↪rk traffic.",
"title": "Error"
}
}