Registering Hyper-V Server¶
Register Hyper-V Server with IBM Spectrum Protect Plus.
Method and URI¶
To register Microsoft Hyper-V Server, use a POST method and a URI:
POST https://{hostname|IP}/ngp/hypervisor
Parameters¶
None.
Data¶
Key |
Value (example) |
Type |
Description |
---|---|---|---|
hostAddress |
hyperv.dallas.blue… |
String |
Hostname/IP of Hyper-V Server |
portNumber |
5986 |
Integer |
Port number |
type |
hyperv |
System |
Type of hypervisor servers |
username |
AD-BLUEMACHINESsarah… |
String |
Identity URI or username of Hyper-V Server |
password |
3UztAb4dt-??TyrX |
String |
Password of Hyper-V Server |
sslConnection |
false (default) |
Boolean |
Use SSL |
opProperties |
{…, …} |
Array |
Optional properties |
portNumber:
Usually, you will use either port for Microsoft Windows Remote Management (WinRM) over HTTP(S): 5986 (with SSL) or 5985 (without SSL).
username:
You may use either an existing user (identity) or a new pair of a user name and a password.
An existing user can be defined by the identity URI of the corresponding user; and in this case, you do not have to enter the same password. The identity URI has the following syntax:
https://{hostname|IP}/api/identity/user/{identityUserId}
Here is an example:
https://10.0.0.100/api/identity/user/2101
Alternatively, you can enter a new username such as sarah.wiseman@bluemachines.com.invalid
and the password of it such as 3UztAb4dt-??TyrX
.
opProperties
.
Key |
Value |
Type |
Description |
---|---|---|---|
snapshotConcurrency |
3 (default) |
Integer |
Maximum number of VM’s to proceed concurrently per Hyper-V Server |
Example: 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
Password: 3UztAb4dt-??TyrX
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",
"password": "3UztAb4dt-??TyrX"
"sslConnection": false,
"type": "hyperv",
"opProperties": {{"snapshotConcurrency":3}}
}}'''
requests.post('https://' + spp_ipv4 + '/ngp/hypervisor',
headers={...}, params="", data=_data, verify=...)

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/2104"
},
"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"
}
}