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 RequiredBrowser

Hostname/IP of Hyper-V Server

portNumber

5986

Integer RequiredBrowser

Port number

type

hyperv

System RequiredBrowser

Type of hypervisor servers

username

AD-BLUEMACHINESsarah…

String RequiredBrowser

Identity URI or username of Hyper-V Server

password

3UztAb4dt-??TyrX

String Browser

Password of Hyper-V Server

sslConnection

false (default)

Boolean Required? Browser

Use SSL

opProperties

{…, …}

Array RequiredBrowser

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 RequiredBrowser

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=...)
_images/refmanageprotection_hyperv_create01.png

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