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

vmware

Hyper-V server

hyperv

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

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

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