VNC Proxy User Guide

  1. Overview
  2. Command line options
  3. Example usage
  4. Special keys
  5. Enabling Web-based Java Viewers
  6. Password Security
  7. Troubleshooting


The VNC Proxy provides a VNC interface to a graphics cluster.  Typically, this means that the VNC Proxy can provide access to a DMX display wall or parallel Chromium application to anyone with a VNC viewer.

In a DMX configuration, the VNC Proxy connects to the back-end DMX servers to get screen images.  Input events are sent to the DMX X server for processing.  Then, some number of VNC viewers can connect to the VNC Proxy to use the DMX display.

Technically, the VNC Proxy is both a VNC client and a VNC server.

Like the original VNC Reflector, the VNC Proxy can also be used to reduce the workload of a VNC server when servicing many VNC clients.

Command line options

The VNC Proxy is used as follows:

vncproxy [options] server

where server is the name of an X display or a host::port identifier.

Options include:

Example usage

To start the VNC Proxy, connecting to a display name mars:1 with hextile encoding:

vncproxy -x mars:1

To start the VNC Proxy, connecting to a display name mars:1 with tight encoding and RFB caching and frame synchronization:

vncproxy -t -R -F mars:1

Special keys

Under some circumstances, when OpenGL and Xlib rendering are mixed, the desktop may become garbled. To refresh the desktop image, press F9 in your VNC viewer.

Enabling Web-based Java Viewers

The VNC Proxy has minimal web serving capability in order to support Java VNC viewers running inside web browsers. This works as follows:
The Java viewer code must be installed on the VNC Proxy host.

Download the TightVNC Java viewer package and install it on the VNC Proxy host. The RealVNC Java viewer is quite similar, but the RealVNC viewer seems to be limited to 8-bit color. When complete, there should be a directory named /usr/share/vnc/classes/ which contains the Java class, jar and html file for the Java VNC viewer.

Password Security

By default, any VNC viewer can connect to the VNC Proxy without a password. By setting up a password file, clients can be required to provide a password in order to access the VNC Proxy.

When it's started, the VNC Proxy will look for a file named passwd in the current directory. This file may contain one or two plain-text passwords, one per line. The first password is used for “read/write clients” (those which can send mouse/keyboard events). The second password is used for “read-only” clients (those which can only view the screen and not interact). A password file with another name can be specified with the -p option to vncproxy.

If the password file exists, clients will be required to provide a password in order to connect. If the client provides the expected password it'll be granted access.

The VNC Proxy will report failed login attempts to stderr if the debug level is greater than or equal to two (set with the -d option to vncproxy).


If vncproxy complains that it cannot create a port when it starts, check that there are no other instances of vncproxy already running on the system, or use a different port number (-l option).

The vncproxy may complain about unsupported encodings when a VNC viewer attaches to it. These can generally be ignored.