VNC Proxy User Guide
- Command line options
- Example usage
- Special keys
- Enabling Web-based Java Viewers
- Password Security
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
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:
where server is the name of
an X display or a host::port identifier.
- -l PORT Specifies
an alternate port to listen to for VNC viewers. The default port
is 5999 which corresponds to X server number 99. For example if -l 42 is specified, VNC viewers
would connect to host:42 or host::5942
- -t Prefer tight encoding when connecting to
- -x Prefer hextile encoding when connecting to
- -r Prefer raw encoding when connecting
to VNC servers.
- -4 Prefer
24-bit raw encoding when connecting to Chromium VNC SPU (not supported
by other VNC servers).
- -R Enable RFB
option causes incoming RFB messages to be saved in a cache. The
cached messages are sent to the VNC viewer whenever possible, to
avoid re-encoding image regions. Only RFB messages coming from VNC
SPUs are cached because of the Tight encoder in the VNC SPUs was
modified to support out-of-order decoding.
- -W Enable
this option, an effort is made to combine small write() calls
into fewer, larger calls.
- -F This option
updates to the VNC Proxy's internal framebuffer in order
to minimize the “tearing” effect which is otherwise seen in the
- -S k Set desktop scale
factor to 1/k for all clients. Instead of seeing a full-resolution
desktop, clients will see a 1/k resolution desktop.
- -p passwdfile
Specifies the name of a password file to control viewer access to the proxy.
The file should contain two plaintext passwords, one per line.
The first password is for normal viewer connections, the second is for
Passwords are limited in length to 8 characters.
- -H hostinfofile
Specifies the name of a host-info file.
This file contains a single line with two fields separated by a space:
a host/display name and a plaintext password.
The hostname specifies the VNC server to connect to and the password
is used if the VNC server requires a password. For example:
Note that the server command line argument is not needed (and
is ignored) when the -H option is used.
If the hostname names a DMX server and the back-end X servers require
VNC passwords, the password from the host info file will be used.
This means that all VNC servers in the DMX display must use the same
- -d N Enable
debug level N. For details, see the vncproxy source
To start the VNC Proxy, connecting to a display name
with hextile encoding:
To start the VNC Proxy, connecting to a display name
with tight encoding and RFB caching and frame synchronization:
-t -R -F mars:1
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.
- The web browser will connect to the VNC Proxy at the URL
- In response to the browser's initial GET request, the VNC Proxy
will send a simple html wrapper for the VNC viewer applet. Subsequent
GET requests will be used to transfer the viewer Java bytecode to the
- The Java viewer will start inside the browser and connect to the
VNC Proxy's primary port.
- At this point, the Java VNC viewer acts like any other VNC viewer.
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
which contains the Java class, jar and html file for the Java VNC
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
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
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.