TurboVNC Reference

A P P E N D I X B

TurboVNC Reference

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

Common TurboVNC Scenarios

TurboVNC Connection Profiles and Dynamic Quality and Performance Tradeoff

Troubleshooting Common TurboVNC Server Startup Errors

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
Scenario	Command	Comment
Start a TurboVNC session with default settings.	`vncserver`	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
Scenario	UNIX, Mac OS X, and Windows Commands	Comment
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.

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

In the Windows TurboVNC Viewer, there are three buttons in the TurboVNC Connection dialog that enable you to easily select the connection profile. Click this dialog’s Options button to select the Image delivery and other attributes, as shown in FIGURE B-2.

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

In the Solaris, Linux, and Mac OS X TurboVNC Viewer, the High Quality profile is the default. You can use the -lowqual and -medqual command-line options of vncviewer to switch to the Low Quality or Medium Quality profile, respectively.

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.

To Perform a Lossless Refresh

Take one of the following actions:

In the Solaris, Linux, or Mac OS X TurboVNC Viewer, select Lossless Refresh from the F8 pop-up menu.

On a Windows TurboVNC viewer, either press Ctrl-Alt-Shift-L or click on the Lossless Refresh toolbar icon.

In the Java TurboVNC Viewer, click the Lossless Refresh button at the top of the browser window.

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.

To Configure the X Font Server to Start Automatically

As superuser, enter the command appropriate to the operating system.

On a Solaris 10 graphics server, enter:

# svcadm enable stfsloader xfs

On a Solaris graphics server running a version earlier than Solaris 10, enter:

# fsadmin -e

On a Linux system, to configure the X font server to start automatically with each boot, enter:

# chkconfig xfs on

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.