Overview of VNC Proxy

The VNC Proxy is an OpenStack component that allows users of the Compute service to access their instances through VNC clients. In Essex and beyond, there is support for for both libvirt and XenServer using both Java and websocket cleints.

The VNC console connection works as follows:

User connects to API and gets an access_url like http://ip:port/?token=xyz.
User pastes URL in browser or as client parameter.
Browser/Client connects to proxy.
Proxy talks to nova-consoleauth to authorize the user's token, and then maps the token to the private host and port of an instance's VNC server. The compute host specifies the what address the proxy should use to connect via the nova.conf option vncserver_proxyclient_address. In this way, the vnc proxy works as a bridge between the public network, and the private host network.
Proxy initiates connection to VNC server, and continues proxying until the session ends.

The proxy also performs the required function of tunneling the VNC protocol over Websockets so that the noVNC client has a way to talk VNC. Note that in general, the VNC proxy performs multiple functions:

Bridges between public network (where clients live) and private network (where vncservers live).
Mediates token authentication.
Transparently deals with hypervisor-specific connection details to provide a uniform client experience.

About nova-consoleauth

Both client proxies leverage a shared service to manage token auth called nova-consoleauth. This service must be running in order for for either proxy to work. Many proxies of either type can be run against a single nova-consoleauth service in a cluster configuration.

nova-consoleauth should not be confused with nova-console, which is a Xen-specific service that is not used by the most recent VNC proxy architecture.

Typical Deployment

A typical deployment will consist of the following components:

One nova-consoleauth process. Typically this runs on the controller host.
One or more nova-novncproxy services. This supports browser-based novnc clients. For simple deployments, this service typically will run on the same machine as nova-api, since it proxies between the public network and the private compute host network.
One or more nova-xvpvncproxy services. This supports the special Java client discussed in this document. For simple deployments, this service typically will run on the same machine as nova-api, since it proxies between the public network and the private compute host network.
One or more compute hosts. These compute hosts must have correctly configured configuration options, as described below.

Getting an Access URL

Nova provides the ability to create access_urls through the os-consoles extension. Support for accessing this URL is provided by novaclient:

$ nova get-vnc-console [server_id] [novnc|xvpvnc]

Specify 'novnc' to retrieve a URL suitable for pasting into a web browser. Specify 'xvpvnc' for a URL suitable for pasting into the Java client.

So to request a web browser URL:

$ nova get-vnc-console [server_id] novnc

Important nova-compute Options

To enable vncproxy in your cloud, in addition to running one or both of the proxies and nova-consoleauth, you need to configure the following options in nova.conf on your compute hosts.

[no]vnc_enabled - Defaults to enabled. If this option is disabled your instances will launch without VNC support.
vncserver_listen - Defaults to 127.0.0.1. This is the address that vncservers will bind, and should be overridden in production deployments as a private address. Applies to libvirt only. For multi-host libvirt deployments this should be set to a host management IP on the same network as the proxies.
vncserver_proxyclient_address - Defaults to 127.0.0.1. This is the address of the compute host that nova will instruct proxies to use when connecting to instance vncservers. For all-in-one xen server domU deployments this can be set to 169.254.0.1. For multi-host xen server domU deployments this can be set to a dom0 management ip on the same network as the proxies. For multi-host libvirt deployments this can be set to a host management IP on the same network as the proxies.
novncproxy_base_url=[base url for client connections] - This is the public base URL to which clients will connect. "?token=abc" will be added to this URL for the purposes of auth. When using the system as described in this document, an appropriate value is "http://$SERVICE_HOST:6080/vnc_auto.html" where SERVICE_HOST is a public hostname.
xvpvncproxy_base_url=[base url for client connections] - This is the public base URL to which clients will connect. "?token=abc" will be added to this URL for the purposes of auth. When using the system as described in this document, an appropriate value is "http://$SERVICE_HOST:6081/console" where SERVICE_HOST is a public hostname.

Accessing VNC Consoles with a Java client

To enable support for the OpenStack Java VNC client in Compute, we provide the nova-xvpvncproxy service, which you should run to enable this feature.

xvpvncproxy_port=[port] - port to bind (defaults to 6081)
xvpvncproxy_host=[host] - host to bind (defaults to 0.0.0.0)

As a client, you will need a special Java client, which is a version of TightVNC slightly modified to support our token auth:

$ git clone https://github.com/cloudbuilders/nova-xvpvncviewer
$ cd nova-xvpvncviewer
$ make

Then, to create a session, first request an access URL using python-novaclient and then run the client like so. To retrieve access URL:


$ nova get-vnc-console [server_id] xvpvnc

To run client:

$ java -jar VncViewer.jar [access_url]

nova-novncproxy (novnc)

You will need the novnc package installed, which contains the nova-novncproxy service. As root:

# apt-get install novnc

The service should start automatically on install. To restart it:

# service novnc restart

The configuration option parameter should point to your nova.conf configuration file that includes the message queue server address and credentials.

By default, nova-novncproxy binds 0.0.0.0:6080. This can be configured in nova.conf with:

novncproxy_port=[port]
novncproxy_host=[host]

Tthe previous vnc proxy implementation, called nova-vncproxy, has been deprecated

Accessing a VNC console through a web browser

Retrieving an access_url for a web browser is similar to the flow for the Java client. To retrieve the access URL:

$ nova get-vnc-console [server_id] novnc

Then, paste the URL into your web browser.

Additionally, you can use the OpenStack Dashboard (codenamed Horizon), to access browser-based VNC consoles for instances.

Frequently asked questions about VNC access to VMs

Q: What has changed since Diablo?

A: Previously, VNC support was done differently for libvirt and xen. Now, there is unified multi-hypervisor support. To support this change, configuration options have been added and changed. Also, a new required service called nova-consoleauth has been added. If you are upgrading from Diablo, you will have to take these changes into consideration when upgrading.

If you are using Diablo, please see the documentation that shipped with your code, as this information will not be relevant.

Q: What happened to Diablo's nova-vncproxy?

A: nova-vncproxy was removed from the nova source tree. The Essex analog for this process is nova-novncproxy, which is provided by an external project.

Q: Why is nova-vncproxy no longer part of nova?

A: In Diablo, we shipped a websocket proxy (nova-vncproxy) with nova, but it had poor browser support. This nova-vncproxy code was dependent on external noVNC code, so changes to that system involved updating 2 projects. Due to the rapid evolution of websocket tech, and the tight dependence of the websocket proxy on javscript and html components, we decided to keep that code all in one place.

Q: What is the difference between nova-xvpvncproxy and nova-novncproxy?

A: nova-xvpvncproxy which ships with nova, is a new proxy that supports a simple Java client. nova-novncproxy uses noVNC to provide vnc support through a web browser.

Q: I want VNC support in the Dashboard. What services do I need?

A: You need nova-novncproxy, nova-consoleauth, and correctly configured compute hosts.

Q: When I use nova get-vnc-console or click on the VNC tab of the Dashboard, it hangs. Why?

A: Make sure you are running nova-consoleauth (in addition to nova-novncproxy). The proxies rely on nova-consoleauth to validate tokens, and will wait for a reply from them until a timeout is reached.

Q: My vnc proxy worked fine during my All-In-One test, but now it doesn't work on multi host. Why?

A: The default options work for an All-In-One install, but changes must be made on your compute hosts once you start to build a cluster. As an example, suppose you have two servers:

PROXYSERVER (public_ip=172.24.1.1, management_ip=192.168.1.1)
COMPUTESERVER (management_ip=192.168.1.2)

Your nova-compute configuration file would need the following values:

# These flags help construct a connection data structure
vncserver_proxyclient_address=192.168.1.2
novncproxy_base_url=http://172.24.1.1:6080/vnc_auto.html
xvpvncproxy_base_url=http://172.24.1.1:6081/console

# This is the address where the underlying vncserver (not the proxy)
# will listen for connections.
vncserver_listen=192.168.1.2

Note that novncproxy_base_url and novncproxy_base_url use a public ip; this is the url that is ultimately returned to clients, who generally will not have access to your private network. Your PROXYSERVER must be able to reach vncserver_proxyclient_address, as that is the address over which the vnc connection will be proxied.

See "Important nova-compute Options" for more information.

Q: My noVNC does not work with recent versions of web browsers. Why?

A: Make sure you have python-numpy installed, which is required to support a newer version of the WebSocket protocol (HyBi-07+). Also, if you are using Diablo's nova-vncproxy, note that support for this protocol is not provided.

Q: How do I adjust the dimensions of the VNC window image in horizon?

A: These values are hard-coded in a Django HTML template. To alter them, you must edit the template file _detail_vnc.html. The location of this file will vary based on Linux distribution. On Ubuntu 12.04, the file can be found at /usr/share/pyshared/horizon/dashboards/nova/templates/nova/instances_and_volumes/instances/_detail_vnc.html.

Modify the width and height parameters:

  <iframe src="{{ vnc_url }}" width="720" height="430"></iframe>