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 Image Encoding Protocols and Dynamic Quality/Performance Tradeoff

Troubleshooting Common TurboVNC Session 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 session uses the user’s VNC startup file. If the file does not exist, the TurboVNC session creates one. This startup file is named $HOME/.vnc/xstartup.turbovnc on release 1.1.1 and $HOME/.vnc/xstartup on previous releases. The xstartup file that TurboVNC creates uses 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 image encoding protocol and related parameters. These are further described inTurboVNC Image Encoding Protocols and Dynamic Quality/Performance Tradeoff

TABLE B-2 describes different scenarios for starting a TurboVNC viewer from a command line. Options that would be used on UNIX and on Windows are provided.

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:2:2 subsampling, `4x` for 4:2:0 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 (on UNIX or Mac OS X).
Minimize bandwidth consumption at the expense of image quality.	`vncviewer` `-lowqual` host`[:`display`]`	Use Low Quality connection profile (on UNIX or Mac OS X).
Connect to the VNC server session running on machine host and listening on port port.	`vncviewer` host`::`port	Note the double colons.

TurboVNC Image Encoding Protocols and Dynamic Quality/Performance Tradeoff

TurboVNC allows user control to balance the (often conflicting) goals of high image quality and high performance. First we describe the options that control TurboVNC’s compression of images in TABLE B-3. Then we describe predefined option combinations in Useful Combinations of TurboVNC Quality and Performance Options.

TABLE B-3 TurboVNC Quality and Performance Options
TurboVNC Option Name	vncviewer Command-Line Override	vncviewer Option Description	Default Value
Allow JPEG compression	`-nojpeg`	By default, TurboVNC will use JPEG compression for all image tiles with more than 24 unique colors and paletted encoding for all other image tiles. With `-nojpeg`, TurboVNC will select between paletted or raw encoding depending on the size of the image tile and its color count.	Allow JPEG
JPEG image quality (an integer between 1 and 100, inclusive)	`-quality [1-100]`	This setting enables you to specify the quality of the JPEG compression. Lower is faster but also grainier. The default setting should produce visually lossless performance. 100 is is mathematically lossless except for round-off errors. If image quality is of paramount concern, consider setting the JPEG quality to 100 or using RGB encoding.	95
JPEG chrominance subsampling	`-samp [1x\| 2x\|4x\|8x\|16x\|grey]`	Subsamples chrominance (color) to improve performance at the expense of quality. `1x` - Full YUV color resolution (4:4:4). `2x` - Full resolution in Y, subsamples U and V by 2 in X (4:2:2). `4x` - Subsamples U and V by 2 in X and Y (4:2:0). `8x` - Subsamples U and V by 4 in X, 2 in Y (4:1:0). `16x` - Subsamples U and V by 4 in X and Y (4:4). gray - Discards all chrominance (color) components.	1x
`Zlib` compression level		If Zlib compression is enabled, then paletted and raw-encoded image tiles will be compressed with Zlib prior to transmission. This decreases network bandwidth usage at the expense of increased server CPU usage. If JPEG compression is enabled, then Zlib compression is always used with non-JPEG image tiles.	`1`

TABLE B-4 lists the most useful combinations of the compression options above. These are called the “Image Encoding Protocol” in release 1.1.1. In previous releases, these were known as Connection Profiles (with a slightly different set of options). “Tight” refers to the image encoding used by TightVNC, on which TurboVNC is based.

TABLE B-4 Useful Combinations of TurboVNC Quality and Performance Options
Image Encoding Protocol Name and UNIX Command-line option	Allow JPEG?	JPEG Image Quality	JPEG Chrominance Subsampling	Zlib Compression Level	Protocol Description
Tight + Perceptually Lossless JPEG (UNIX default)	Yes	95	1x	N/A	This protocol should be perceptually lossless; that is, any image compression artifacts it produces should be imperceptible to the human eye under most viewing conditions. This protocol requires a great deal of network bandwidth, however, and is generally not recommended except on 50 Megabit/second and faster networks.
Tight + Medium Quality JPEG `-medqual`	Yes	80	2x	N/A	For image tiles with a high number of unique colors, this protocol produces some minor, but generally not very noticeable, image compression artifacts. All else being equal, this protocol typically uses about twice the network bandwidth of the “Low Quality” protocol and about half the bandwidth of the “Perceptually Lossless” protocol, making it appropriate for medium-speed networks such as 10 Megabit ethernet.
Tight + Low Quality JPEG `-lowqual`	Yes	30	4x	N/A	For image tiles with a high number of unique colors, this protocol produces very noticeable image compression artifacts. However, it performs optimally on low-bandwidth connections. If image quality is more critical than performance, then use one of the other encoding protocols or take advantage of the “Lossless Refresh” feature. See Lossless Refresh.
Lossless Tight `-lossless`	No	N/A	N/A	0	This protocol uses paletted encoding for image tiles with a low number of unique colors but otherwise does not perform any image compression at all. It is thus suitable only for gigabit and faster networks. This protocol uses significantly less CPU time than any of the JPEG-based protocols.
Lossless Tight + Zlib `-losslesswan`	No	N/A	N/A	1	This protocol uses paletted encoding for image tiles with a low number of unique colors and raw encoding for image tiles with a high number of unique colors. It compresses all image tiles using Zlib with compression level 1. For certain types of applications (CAD applications, in particular), this protocol uses less network bandwidth than the “Perceptually Lossless” protocol, but it also uses significantly more CPU time on the server than any of the JPEG-based protocols.

To Select the Image Encoding Protocol

This selection can be made statically for your viewer session or changed dynamically “on-the-fly” as you use your viewer session. Selecting the Image Encoding depends on your viewer.

For the Java viewer, click on the Options button at the top of the “TurboVNC Connection” dialog box. Then select the desired image encoding protocol (see FIGURE B-1).

For dynamic control of the protocol, after connecting to your server, click the Options button at the top of the browser window to obtain the same dialog.

FIGURE B-1 WebVNC Options Dialog

In the Windows TurboVNC Viewer, click on the Options button in the TurboVNC Connection dialog. Then select the Image delivery and other attributes, as shown in FIGURE B-2. (If you do not choose settings, the Windows viewer stores the last settings that were used with a particular VNC server host:display and tries to use those settings whenever you connect to the same display again.)

For dynamic control of the protocol, after connecting to the server, click on the Connection Options button in the toolbar to obtain the same dialog.

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

In the Solaris, Linux, and Mac OS X TurboVNC Viewer, the “Tight + Perceptually Lossless JPEG” encoding is the default. You can use vncviewer’s command-line options, given in Useful Combinations of TurboVNC Quality and Performance Options to select a nondefault image encoding protocol from that table.

For dynamic control of the protocol, you can press the F8 key after connecting to display a menu (see FIGURE B-3) from which you can dynamically control the image encoding protocol and parameters.

FIGURE B-3 TurboVNC’s Configuration Dialog (Defaults for Perceptually Lossless JPEG Are Shown)

Lossless Refresh

TurboVNC can optionally compress images losslessly, 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 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, depending on your viewer:

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 Session Startup Errors

X Font Server Issues

On some systems, when you start the TurboVNC server session, 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 session 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. This issue is unlikely to occur with TurboVNC 0.5 (in Sun Shared Visualization 1.1.1) or later releases, because it attempts to find the fonts it needs without depending on the font server. If you encounter font server issues, 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 session 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

Upon startup, the TurboVNC server session uses the user’s VNC startup file. If the file does not exist, the TurboVNC session creates one. This startup file is named $HOME/.vnc/xstartup.turbovnc on release 1.1.1. On previous releases, it was named $HOME/.vnc/xstartup and could contain contents from a different VNC server, which was incompatible with TurboVNC.

The startup file that TurboVNC creates uses operating system specific techniques to launch the user’s most recently used window manager. If necessary, you can edit the startup file created by TurboVNC.