Native HTML5 consoles for VMware

This is a proposal to add support for the native HTML5 console available in vSphere 5.5 and later (referred as WebMKS console). This will solve some of the current problems that we have with VNC consoles with respect to deployment, scalability and security. The existing support for VNC consoles will remain but users will be encouraged to use WebMKS when possible.

Problem description

There are number of problems with the current approach which provides VNC consoles to instances running on VMware hypervisors:

  • Deployment - cloud operators need to open a huge range of ports (5900-6105) in the firewall configuration on each ESXi host. Additionally, they need to create and install a special VIB package for the firewall modifications to persist after reboot. The whole thing creates a huge security risk because we rely only on the fact that all ESXi hosts will run on a private network that will be inaccessible to the cloud users.

  • Scalability - the Nova driver needs to allocate a unique VNC port for each instance and this is done by querying all allocated ports on the vCenter while holding a lock in the driver. Needless to say, this doesn’t scale well.

  • Security - we can prevent race conditions for port allocations occurring on the same nova-compute but there is no way to do this between several nova-computes. This creates a possibility for allocating the same VNC port to different instances and if these instances end up on the same ESXi host somehow, one user can hijack the console of another user.

All of the above problems don’t stand with WebMKS consoles.

Use Cases

Deployers will be able to deploy OpenStack on top of vSphere much more easily because they won’t need to modify firewall configurations on the ESXi hosts.

Spawning many instances at the same time will be faster for End Users because no ports will be allocated in the driver and thus no locks will be held.

Project Priority


Proposed change

The proposal is to add a new API that will return WebMKS connect information similar to how we return connect information for other types of consoles like VNC and RDP. The WebMKS connect information for a given instance is the following:

  • host - the hostname of the corresponding vCenter

  • port - 7331 or 7343 depending on the type of the web socket (ws or wss)

  • vmId - the Managed Object ID of the virtual machine

  • vmName - the name of the virtual machine

  • vcFQDN - the vCenter Server advanced setting “VirtualCenter.FQDN”

  • sessionTicket - session ticket obtained with the AcquireCloneTicket API

  • thumbprint - the vCenter Server SHA1 SSL thumbprint


There is already an existing alternative for instances running on VMware which is VNC consoles. We will continue to support this.

Data model impact


REST API impact

We will leverage the new v2.1 API for getting console access:

Sample request:

POST /servers/<uuid>/console
    "protocol": "mks"
    "type": "webmks"

Sample response:

200 OK
    "protocol": "mks",
    "url": ""

The updated JSON schema is as follows:

    'type': 'object',
    'properties': {
        'protocol': {
            'enum': ['vnc', 'spice', 'rdp', 'serial', 'mks'],
        'type': {
            'enum': ['novnc', 'xvpvnc', 'rdp-html5',
                     'spice-html5', 'serial', 'webmks'],
    'required': ['protocol', 'type'],
    'additionalProperties': False,

The URL in the response points to a WebMKS proxy which authorizes the given token by calling nova-consoleauth and then starts proxying between the client and the corresponding vCenter server where the instance runs.

Security impact

We will use the same security model as for the other types of consoles which is leveraging nova-consoleauth to authorize tokens generated by the compute node.

Notifications impact


Other end user impact


Performance Impact

If the VMware driver is configured to provide only WebMKS consoles it will perform better because it won’t need to allocate any VNC ports (allocating a VNC port requires a vCenter query while holding a lock).

Other deployer impact

WebMKS consoles will require deploying WebMKS proxy (similar to nova-novncproxy) that will connect compute service users to the corresponsing vCenter which provides console access to the given virtual machine.

There will be a new configuration option that will specify the base URL for the WebMKS proxy (e.g. webmks_proxy_base_url).

Developer impact




Primary assignee:


Work Items

The implementation can be split in two parts:

  • add the new API to the compute manager and the virt driver interface

  • implement the new API in the VMware driver


blueprint: consolidate-console-api


Since this is a VMware specific feature, VMware NSX CI will be updated to run tests that exercise this functionality.

Documentation Impact

The Nova documentation for VMware needs to be updated to say that two types of consoles are supported (VNC and WebMKS) and there is no need to modify firewall configurations if deployers want to provide only WebMKS.