A P P E N D I X  B

TurboVNC Reference

This appendix provides basic reference information about TurboVNC. Topics include:

For instructions in using the TurboVNC server, see Manually Using TurboVNC. The TurboVNC commands are not normally in your PATH. Either add their location /opt/TurboVNC/bin to your PATH or enter full pathnames to the following commands.

Common TurboVNC Scenarios

TurboVNC Server Scenarios

TABLE B-1 describes different scenarios for the TurboVNC server, the vncserver command, and respective comments.

TABLE B-1 Common TurboVNC Server Scenarios




Start a TurboVNC session with default settings.


The X display number of a TurboVNC session is printed out whenever you start the session.

Start a TurboVNC session with a given virtual desktop size.

vncserver -geometry w x h

Where the desktop is w x h pixels in size. Default is 1240x900 pixels.

List all your TurboVNC sessions.

vncserver -list

Lists all the TurboVNC sessions of the current user on this host.

Kill the TurboVNC session of X display number display.

vncserver -kill :display

TurboVNC sessions can only be killed by the user that started the session.

Upon startup, the TurboVNC server uses $HOME/.vnc/xstartup if the file exists. If the file does not exist, the TurboVNC server creates one. The TurboVNC server attempts to use operating system specific techniques to launch the user’s most recently used window manager.

TurboVNC Viewer Scenarios

On a Windows host, start a TurboVNC viewer by selecting TurboVNC Viewer in the TurboVNC Start Menu group. A small GUI (shown in TurboVNC Connection Dialog on a Windows Client) appears to allow selection of a Connection profile. The TurboVNC connection profiles are further described inTurboVNC Connection Profiles and Dynamic Quality and Performance Tradeoff

TABLE B-2 describes different scenarios for starting a TurboVNC viewer from a command line.

TABLE B-2 Common TurboVNC Viewer Scenarios


UNIX, Mac OS X, and Windows Commands


Connect to the VNC server session running on machine host that has an X display number of display.

vncviewer host[:display]

Note the single colon, as is standard for an X display name.

Similar to previous scenario, but do not allow others to view or share your session.

vncviewer -noshared host[:display]

vncviewer /noshared host[:display]

The default is to allow any user who correctly enters your VNC password to view your session.

Set the JPEG quality to q.

vncviewer -quality q host[:display]

vncviewer /quality q host[:display]

Where q is a number between 1 and 100 (default is 95). Once connected, you can change this dynamically using the F8 menu.

Set the JPEG chrominance subsampling to s.

vncviewer -samp s host[:display]

vncviewer /samp s host[:display]

Where s is 1x for no subsampling (4:4:4), 2x for 4:1:1 subsampling, 4x for 4:2:2 subsampling, or gray for no chominance. Default is 1x.

Once connected, you can change this setting dynamically using the F8 menu. See Chrominance Subsampling for more information.

Improve performance, at the expense of image quality.

vncviewer -medqual host[:display]

Use Medium Quality connection profile.

Minimize bandwidth consumption at the expense of image quality.

vncviewer -lowqual host[:display]

Use Low Quality connection profile.

Connect to the VNC server session running on machine host and listening on port port.

vncviewer host::port

Note the double colons.

TurboVNC Connection Profiles and Dynamic Quality and Performance Tradeoff

TABLE B-3 describes the three predefined connection profiles, which are alternative tradeoffs of quality versus performance, intended to be chosen based on your network bandwidth. The High Quality profile is the default.

TABLE B-3 TurboVNC Connection Profiles

Connection Profile Name

Equivalent Options

Network and Bandwidth Consumption

Quality Description

High Quality

-samp 2X -quality 80.

Local area network (LAN, 50 Megabit/second or faster).

Perceptually lossless. This profile should produce no noticeable image compression artifacts for most applications.

Medium Quality

-samp 2X -quality 80

Medium-speed networks such as 10 Megabit/second Ethernet. This profile uses about half the network bandwidth of the default profile.

Some image compression artifacts, but they are generally minor and not very noticeable.

Low Quality

-samp 4X -quality 30

Minimize bandwidth consumption at the expense of image quality. This profile uses about half the network bandwidth of the medium quality profile.

This profile provides optimal performance on low-bandwidth connections, such as broadband. The image quality has very visible artifacts but is still usable.

You might want to take advantage of TurboVNC’s Lossless Refresh feature. See Lossless Refresh.

procedure icon  To Select the Connection Profile

1. In the Java viewer, click the Options button at the top of the browser window.

2. Select the desired connection profile (see FIGURE B-1).

FIGURE B-1 WebVNC Options Dialog


Or, after connecting to the server, click on the Connection Options button in the toolbar to obtain the same dialog. This functionality enables you to reconfigure visual quality and performance attributes on-the-fly.

FIGURE B-2 TurboVNC Viewer Options Dialog on a Windows Client


You can also press the F8 key after connecting to pop-up a menu (see FIGURE B-3) from which you can select a different connection profile. This functionality enables you to reconfigure visual quality and performance on-the-fly.

FIGURE B-3 TurboVNC’s Configuration Dialog (Defaults for High Quality Are Shown)


TurboVNC’s Solaris, Linux, and Mac OS X viewer supports image compression types JPEG or None (RGB). None (RGB) turns off image compression altogether, which is useful when connecting to a TurboVNC server running on the same machine as the viewer, or to a TurboVNC server located across a gigabit or faster network. Disabling image compression greatly reduces the CPU usage on the server and client, at the expense of greatly increasing the network usage.

Lossless Refresh

TurboVNC can optionally encode images as RGB, which is fully lossless and uncompressed, but this mode does not perform well except on extremely fast networks. Another option for quality-critical applications is the Lossless Refresh feature. Lossless Refresh causes the server to send a mathematically lossless (Zlib-compressed RGB) copy of the current screen to the viewer. So, for instance, you can rotate, pan, or zoom an object in your application using a very lossy quality setting. Then, when you are ready to interpret or analyze the object closely, you can request a lossless refresh of the screen.

procedure icon  To Perform a Lossless Refresh

single-step bullet  Take one of the following actions:

Troubleshooting Common TurboVNC Server Startup Errors

X Font Server Issues

On some systems, when you start the TurboVNC server this message appears:

Couldn’t start Xvnc; trying default font path.
Please set correct fontPath in the vncserver script
or make sure that the X Font Server (xfs) is running.

Usually after this message is displayed, the TurboVNC server starts, but without all the fonts that would be available if the font server were running.

This message is normally caused by the X font server not running. To avoid this problem, you can, as superuser, configure the X font server to start automatically.

procedure icon  To Configure the X Font Server to Start Automatically

single-step bullet  As superuser, enter the command appropriate to the operating system.

On many Linux systems, you also can start the X font server immediately. Enter:

# /etc/init.d/xfs restart

X Authentication Issues

TurboVNC relies on xauth, the X authentication control program. Your script that starts up vncserver might not find xauth unless it is included in your PATH. When xauth is not found, the TurboVNC server might fail to start or might start an X server that cannot be connected to by your X clients (such as windows or a window manager).

To avoid this problem, make sure that xauth is included in your PATH. Also, when you invoke the TurboVNC server, avoid unintentionally invoking a vncserver command that shares the X directory. This might happen if the X directories are listed prior to /opt/TurboVNC/bin in your PATH.

For more information on this issue, see CR 6710919 at http://sunsolve.sun.com.

xstartup Issues

If a $HOME/.vnc/xstartup file exists, the TurboVNC server uses it when starting up. If that file does not exist, one is created by the TurboVNC server. The TurvoVNC server attempts to use techniques specific to the operating system to launch the window manger that was used most recently by the user.

If the user had run a VNC server other than TurboVNC, the existing $HOME/.vnc/xstartup file might be insufficient for TurboVNC. In that case, you can first remove the existing file or move it to another location, and the TurboVNC server will create an appropriate new file. Or, if necessary, you can edit the existing $HOME/.vnc/xstartup file.