VNC Proxy User Guide

Contents

Overview
Command line options
Example usage
Special keys
Enabling Web-based Java Viewers
Password Security
Troubleshooting

Overview

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:

-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 VNC servers.
-x Prefer hextile encoding when connecting to VNC servers.
-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 caching. This 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 write-coalescing. With this option, an effort is made to combine small write() calls into fewer, larger calls.
-F This option synchronizes updates to the VNC Proxy's internal framebuffer in order to minimize the “tearing” effect which is otherwise seen in the VNC Viewer.
-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 view-only connections. 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:
```
   vizserver:1 rosebud
```
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 password.

-d N Enable debug level N. For details, see the vncproxy source code.

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 web browser will connect to the VNC Proxy at the URL http://hostname:5800/
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 web browser.
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.

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).

Troubleshooting

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.