User’s Guide for TurboVNC 0.6

Intended audience: System Administrators, Researchers, and others with knowledge of the Linux or Solaris operating systems and X windows.

Table of Contents



1 Legal Information

somerights20

This document and all associated illustrations are licensed under the Creative Commons Attribution 2.5 License. Any works which contain material derived from this document must cite The VirtualGL Project as the source of the material and list the current URL for the VirtualGL web site.

The TurboVNC Windows package includes PuTTY, which is released under this license.

TurboVNC is licensed under the GNU General Public License, v2.



2 Overview

TurboVNC is an optimized version of VNC (more specifically, of TightVNC 1.3.x.) On the surface, TurboVNC behaves very similarly to its parent project, but TurboVNC has been tuned to provide interactive performance for full-screen video and 3D workloads. On these types of image workloads, TurboVNC performs as much as an order of magnitude faster than TightVNC 1.3.x, uses more than an order of magnitude less CPU time to compress each frame, and it produces generally better compression ratios. As with TightVNC, TurboVNC uses JPEG compression for image tiles with a high number of unique colors and paletted encoding for image tiles with a low number of unique colors. Part of TurboVNC’s speedup comes from the use of TurboJPEG, the same high-speed vector-optimized JPEG codec used by VirtualGL. However, TurboVNC also bypasses the CPU-hungry smoothness detection routines that TightVNC uses to determine whether a tile is a good candidate for JPEG compression. Furthermore, TurboVNC eliminates buffer copies, it maximizes network efficiency by using the largest tile sizes supported by the TightVNC protocol, and it never uses a Zlib compression level higher than 1. In the aggregate, TurboVNC compresses 2D application workloads less efficiently than TightVNC, but it generally does a better job than TightVNC of compressing 3D application workloads. Also, TurboVNC is much faster across the board than TightVNC 1.3.x.

TurboVNC is the product of extensive research, in which the TightVNC encoder was benchmarked under a variety of different real-world application workloads and a variety of different configurations. This research revealed several fundamental performance bottlenecks in TightVNC, and these were removed or accelerated to form TurboVNC.

In addition, TurboVNC provides the following features:

TurboVNC, when used with VirtualGL, provides a highly performant and robust solution for remotely displaying 3D applications over all types of networks.

TurboVNC is capable of sending over 30 Megapixels/second of image data over a 100 Megabit/second local area network with perceptually lossless image quality. TurboVNC can deliver between 10 and 12 Megapixels/second of image data over a 3 Megabit/second broadband connection at reduced (but usable) image quality.

TurboVNC is compatible with other VNC distributions. See Chapter 7 for more information. TurboVNC can be installed onto the same system as other VNC distributions without interference.



3 System Requirements

3.1 Linux/x86

Server (x86) Server (x86-64) Client
Recommended CPU Pentium 4, 1.7 GHz or faster (or equivalent)
  • For optimal performance, the processor should support SSE2 extensions.
  • Dual processors or dual cores recommended
Pentium 4/Xeon with EM64T, or…
AMD Opteron or Athlon64, 1.8 GHz or faster
  • For optimal performance with 64-bit TurboVNC, the processor should support SSE3 extensions. AMD 64-bit processors manufactured prior to 2005 do not support SSE3.
  • Dual processors or dual cores recommended
Pentium III or Pentium 4, 1.0 GHz or faster (or equivalent)
Recommended O/S
  • Any distribution in the RedHat or SuSE families which contains GLIBC 2.3.2 or later (including Fedora, CentOS 3 and later, and White Box)
  • Ubuntu Linux v6.0 or later
Other Software X server configured to export True Color (24-bit or 32-bit) visuals

3.2 Solaris/x86

Server Client
Recommended CPU Pentium 4/Xeon with EM64T, or…
AMD Opteron or Athlon64, 1.8 GHz or faster
  • Dual processors or dual cores recommended
Pentium III or Pentium 4, 1.0 GHz or faster (or equivalent)
O/S
  • Solaris 10 Update 1 or newer (Update 3 or newer recommended)
  • OpenSolaris 2008.11 (or newer)
Other Software
  • Sun mediaLib (v2.5 or higher recommended *)
  • X server configured to export True Color (24-bit or 32-bit) visuals

* mediaLib 2.5 is included in Solaris 10 update 4 and newer. If you are running an older version of Solaris, it is recommended that you download and install the mediaLib 2.5 upgrade from the link above. mediaLib 2.5 improves the performance of TurboVNC significantly on Solaris/x86 systems, when compared to mediaLib 2.4.

3.3 Solaris/SPARC

Server Client
Recommended CPU UltraSPARC III 900 MHz or faster
  • Dual processors or dual cores recommended
UltraSPARC III 900 MHz or faster
O/S
  • Solaris 8 (or newer)
  • OpenSolaris 2008.11 (or newer)
Other Software Sun mediaLib (pre-installed on Solaris 10 and higher)
  • Sun mediaLib (pre-installed on Solaris 10 and higher)
  • If your system does not ship with SSh pre-installed (older Solaris 8 and 9 systems don’t), then download and install an OpenSSH package from Blastwave or http://www.sunfreeware.com/.
  • X server configured to export True Color (24-bit or 32-bit) visuals

3.4 Mac/x86

Client
Recommended CPU Any Intel-based Mac
O/S OS X 10.4 (“Tiger”) or later
Other Software Mac X11 application (in the “Optional Installs” package on the OS X install discs)

3.5 Windows

Client
Recommended CPU Pentium III or Pentium 4, 1.0 GHz or faster (or equivalent)
O/S Windows 2000 or later
Other For best performance, client display should have a 24-bit or 32-bit (True Color) color depth.



4 Obtaining and Installing TurboVNC

4.1 Installing TurboVNC on Linux

Installing TurboJPEG

  1. Download the appropriate TurboJPEG binary package (v1.11 or later) for your system from the Files area of the VirtualGL SourceForge web-site.

    The “i386” RPM and DEB packages are for 32-bit-only systems. The “x86_64” RPM and “amd64” DEB packages are for 64-bit systems. The 64-bit packages contain both 32-bit and 64-bit libraries.

  2. Log in as root, cd to the directory where you downloaded the binary package, and issue one of the following commands:
    RPM-based systems
    rpm -U turbojpeg*.rpm
    
    Debian-based systems
    dpkg -i turbojpeg*.deb
    

Installing TurboVNC

  1. Download the appropriate TurboVNC binary package for your system from the Files area of the VirtualGL SourceForge web-site.
  2. Log in as root, cd to the directory where you downloaded the binary package, and issue one of the following commands:
    RPM-based systems
    rpm -U turbovnc*.rpm
    
    Debian-based systems
    dpkg -i turbovnc*.deb
    

4.2 Installing TurboVNC on Solaris

  1. Download the TurboVNC Solaris package (SUNWtvnc-{version}.pkg.bz2 for SPARC or SUNWtvnc-{version}-x86.pkg.bz2 for x86) from the Files area of the VirtualGL SourceForge web-site.
  2. Log in as root, cd to the directory where you downloaded the package, and issue the following commands:
    pkgrm SUNWvgl
    
    (answer “Y” when prompted.)
    bzip2 -d SUNWtvnc-{version}.pkg.bz2
    pkgadd -d SUNWtvnc-{version}.pkg
    
    Select the SUNWtvnc package (usually option 1) from the menu.

TurboVNC for Solaris installs into /opt/SUNWtvnc.

4.3 Installing TurboVNC on Mac (Client Only)

  1. Download the TurboVNC Mac disk image (TurboVNC-{version}.dmg) from the Files area of the VirtualGL SourceForge web-site.
  2. Open the disk image, then open TurboVNC-{version}.pkg inside the disk image. Follow the instructions to install the Mac client. The Mac package installs files in the same locations as the Linux packages.

4.4 Installing TurboVNC on Windows (Client Only)

  1. Download the TurboVNC Windows installer package (TurboVNC-{version}.exe) from the Files area of the VirtualGL SourceForge web-site.
  2. Run the TurboVNC installer. The installation of TurboVNC should be self-explanatory. The only configuration option is the directory into which you want the files to be installed.

4.5 Installing TurboVNC from Source

If you are using a Unix platform for which there is not a pre-built TurboVNC binary package available, then log in as root, download the TurboVNC source tarball (turbovnc-{version}.tar.gz) from the Files area of the VirtualGL SourceForge web-site, uncompress it, cd vnc/vnc_unixsrc, and read the README file for further instructions on how to build TurboVNC from source.

4.6 Uninstalling TurboVNC

Linux

As root, issue one of the following commands:

RPM-based systems
rpm -e turbovnc
Debian-based systems
dpkg -r turbovnc

Solaris

As root, issue the following command:

pkgrm SUNWtvnc

Answer “yes” when prompted.

Mac

Use the “Uninstall TurboVNC” application provided in the TurboVNC disk image, or issue the following command from the Terminal:

sudo /opt/TurboVNC/bin/uninstall

Windows

Use the “Add or Remove Programs” applet in the Control Panel (or the “Programs and Features” applet if you’re running Vista.)



5 Using TurboVNC

5.1 Starting and Connecting to a TurboVNC Session

Procedure

  1. Mac clients: Start the Mac X11 application.
  2. Open a new Command Prompt/terminal window on your client machine. (Mac clients: in the X11 application, start a new xterm [Command-N] if one isn’t already started.)
  3. In the new Command Prompt/terminal/xterm window, open a Secure Shell (SSh) session into the TurboVNC server:
    Linux/Mac/Solaris clients
    ssh {user}@{server}
    
    Windows clients
    "c:\program files\turbovnc\putty" {user}@{server}
    
    Replace {user} with your user account name on the TurboVNC server and {server} with the hostname or IP address of that server.
  4. In the SSh session, start a TurboVNC session:
    /opt/TurboVNC/bin/vncserver
    
  5. Make a note of the X display number that the TurboVNC session is occupying, for instance:

    New 'X' desktop is my_server:1

    If this is the first time that a TurboVNC session has ever been run under this user account, TurboVNC will prompt for a VNC session password.
  6. The SSh session can now be exited, if desired.
  7. On the client machine, start the TurboVNC viewer.
    Linux/Mac/Solaris clients
    Open a new terminal/xterm and type
    /opt/TurboVNC/bin/vncviewer
    
    Windows clients
    Select TurboVNC Viewer in the TurboVNC Start Menu group.
  8. A small dialog box will appear.

    Windows TurboVNC viewer Linux/Mac/Solaris TurboVNC viewer
    turbovnc1 turbovnc2

    Enter the X display name (hostname/IP address and display number) of the TurboVNC session in the “VNC Server” field, then click “Connect” (Windows) or press Enter (Linux/Mac/Solaris.)
  9. Another dialog box appears, prompting for the VNC session password.

    Windows TurboVNC viewer Linux/Mac/Solaris TurboVNC viewer
    turbovnc3 turbovnc4

    Enter the VNC session password and click “OK” (Windows) or press Enter (Linux/Mac/Solaris.)

    A TurboVNC desktop window should appear on your client machine. This window contains a virtual X server with which you can interact to launch X-Windows applications on the TurboVNC server.

5.2 Disconnecting and Killing a TurboVNC Session

Closing the TurboVNC viewer disconnects from the TurboVNC session, but the TurboVNC session will remain running on the TurboVNC server (as will any applications that you may have started in the session), and you can reconnect to the session at any time.

To kill a TurboVNC session:

  1. Using SSh (c:\Program Files\TurboVNC\putty.exe on Windows clients), log into the server that is running the TurboVNC session that you wish to kill.
    … or …
    Using the TurboVNC viewer, connect to the TurboVNC session that you wish to kill, and open a new terminal in that TurboVNC session.
  2. Type the following command:
    /opt/TurboVNC/bin/vncserver -kill :{n}
    
    Replace {n} with the X display number of the TurboVNC session you wish to kill.

To list the X display numbers and process ID’s of all TurboVNC sessions that are currently running under your user account on a particular machine, type the following command:

/opt/TurboVNC/bin/vncserver -list

5.3 Using TurboVNC in a Web Browser

When a TurboVNC session is created, it automatically launches a miniature web server that serves up a Java TurboVNC viewer applet. This Java TurboVNC viewer can be used to connect to the TurboVNC session from a machine that does not have a native TurboVNC viewer installed (or a machine for which no native TurboVNC viewer is available.) The Java viewer is significantly slower than the native viewer on high-speed networks, but on low-speed networks the Java viewer and native viewers have comparable performance. The Java viewer does not currently support double buffering.

To use the Java TurboVNC viewer, point your web browser to:

http://{turbovnc_server}:{5800+n}

where {turbovnc_server} is the hostname or IP address of the TurboVNC server, and n is the X display number of the TurboVNC session to which you want to connect.

Example: If the TurboVNC session is occupying X display my_server:1, then point your web browser to:

http://my_server:5801

5.4 Optimizing TurboVNC’s Performance for Different Network Types

The level of image compression in TurboVNC can be adjusted to balance the (sometimes conflicting) goals of high image quality and high performance. There are four options which control the manner in which TurboVNC compresses images:

Allow JPEG compression
If this option is enabled, then TurboVNC will use JPEG compression for all image tiles with more than 24 unique colors and paletted encoding for all other image tiles. If this option is disabled, then TurboVNC will select between paletted or raw encoding depending on the size of the image tile and its color count.
JPEG image quality
Lower quality levels produce grainier JPEG images with more noticeable compression artifacts, but lower quality levels also use less network bandwidth and CPU time.
JPEG chrominance subsampling
After converting the image from RGB to YUV, chrominance subsampling discards some of the U and V (chrominance) components to save space. 1x subsampling retains the chrominance components for all pixels, 2x subsampling retains the chrominance components for every other pixel, 4x subsampling retains the chrominance components for every fourth pixel, and grayscale throws out all of the chrominance components. 1x subsampling uses the most network bandwidth and CPU time, whereas grayscale uses the least.
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.

In the Windows TurboVNC viewer, these parameters can be adjusted by accessing the Options dialog box (click on the “Options” button in the “TurboVNC Connection” dialog box or, after connecting to the server, click on the Connection Options button in the toolbar.) In the Unix TurboVNC viewer, press F8 after connecting to bring up the options menu. In the Java viewer, click on the Options button at the top of the browser window.

The TurboVNC viewer provides five image encoding protocols, corresponding to the most useful combinations of the image compression options described above:

Image encoding protocol Allow JPEG JPEG image quality JPEG chrominance subsampling Zlib compression level Notes
“Tight + Perceptually Lossless JPEG” 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” 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 JPEG” protocol and about half the bandwidth of the “Perceptually Lossless JPEG” protocol, making it appropriate for medium-speed networks such as 10 Megabit ethernet.
“Tight + Low Quality JPEG” 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 connection protocols or take advantage of the “Lossless Refresh” feature.
“Lossless Tight” 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” 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 JPEG” protocol, but it also uses significantly more CPU time on the server than any of the JPEG-based protocols.

In the Windows TurboVNC viewer, the image encoding protocol can be set using the Options dialog box (click on the “Options” button in the “TurboVNC Connection” dialog box or, after connecting to the server, click on the Connection Options button in the toolbar.) In the Java viewer, the same thing is accomplished by clicking on the “Options” button at the top of the browser window. With the Linux/Mac/Solaris TurboVNC viewer, the “Perceptually Lossless” protocol is the default, and you can use the following command line switches to select another protocol:

-medqual = select the “Tight + Medium Quality JPEG” protocol
-lowqual = select the “Tight + Low Quality JPEG” protocol
-lossless = select the “Lossless Tight” protocol
-losslesswan = select the “Lossless Tight + Zlib” protocol

You can also press the F8 key after connecting to pop up a menu from which you can select a different protocol.

5.4.1 Lossless Refresh

Since both of TurboVNC’s mathematically lossless protocols have performance drawbacks, another option for image-quality-critical applications is the “Lossless Refresh” feature. When a lossless refresh is requested by a TurboVNC viewer, the server will send a mathematically lossless image of the current TurboVNC desktop to the requesting viewer. So, for instance, a user can rotate/pan/zoom an object in their 3D application using a very low-quality JPEG setting, then when that user is ready to interpret or analyze the object, they can request a lossless refresh of TurboVNC’s virtual screen.

To perform a lossless refresh in the Windows or Unix TurboVNC viewers, press CTRL-ALT-SHIFT-L (in the Windows TurboVNC viewer, you can also click on the Lossless Refresh toolbar icon.) In the Java TurboVNC viewer, click on the “Lossless Refresh” button at the top of the browser window.

5.5 Securing a TurboVNC Connection

Normally, the connection between the TurboVNC server and the TurboVNC viewer is completely unencrypted, but securing that connection can be easily accomplished by using the port forwarding feature of Secure Shell (SSh.) After you have started a TurboVNC session on the TurboVNC server, open a new SSh connection into the TurboVNC server using the following command line:

Linux/Mac/Solaris clients
ssh -L {5900+n}:localhost:{5900+n} {user}@{server}
Windows clients
"c:\program files\turbovnc\putty" -L {5900+n}:localhost:{5900+n} {user}@{server}

Replace {user} with your user account name on the TurboVNC server and {server} with the hostname or IP address of that server. Replace n with the X display number of the TurboVNC session to which you want to connect.

For instance, if you wish to connect to display :1 on server my_server using user account my_user, you would type:

Linux/Mac/Solaris clients
ssh -L 5901:localhost:5901 my_user@my_server
Windows clients
"c:\program files\turbovnc\putty" -L 5901:localhost:5901 my_user@my_server

After the SSh connection has been established, you can then launch the TurboVNC viewer and point it to localhost:{n} (localhost:1 in the above example.)

Performance Notes

For LAN connections and other high-speed networks, tunneling the TurboVNC connection over SSh will reduce performance by as much as 20-40%. For wide-area networks, however, there is no performance penalty for using SSh tunneling with TurboVNC.

5.6 Further Reading

For more detailed instructions on the usage of TurboVNC:

Linux/Mac/Solaris
Refer to the TurboVNC man pages:
man -M /opt/TurboVNC/man {vncserver | Xvnc | vncviewer | vncconnect | vncpasswd}
Windows
Use the embedded help feature (the question mark button in the upper right of the TurboVNC viewer window.)

The TightVNC documentation:

http://www.tightvnc.com/docs.html

might also be helpful, since TurboVNC is based on TightVNC and shares many of its features.



6 Using TurboVNC with VirtualGL

Referring to the VirtualGL User’s Guide, VirtualGL’s X11 Transport draws 3D images onto an X display using standard X11 drawing commands. Since this results in the images being sent uncompressed to the X server, the X11 Transport is designed to be used with an “X Proxy.” An X proxy acts as a virtual X server, receiving X11 commands from the application (and from VirtualGL), rendering the X11 commands into images, compressing the resulting images, and sending the compressed images over the network to a client or clients.

Since VirtualGL is sending rendered 3D images to the X proxy at a very fast rate, the proxy must be able to compress the images very quickly in order to keep up. Unfortunately, however, most X proxies can’t. They simply aren’t designed to compress, with any degree of performance, the large and complex images generated by 3D applications.

Enter TurboVNC. Although TurboVNC can be used with all types of applications, it was initially designed as a fast X proxy for VirtualGL. TurboVNC provides an alternate means of delivering rendered 3D images from VirtualGL to a client machine without using VirtualGL’s embedded VGL Transport.

Advantages of TurboVNC (when compared to the VGL Transport)

Disadvantages of TurboVNC (when compared to the VGL transport)

6.1 Using TurboVNC and VirtualGL on the Same Server

The most common (and optimal) way to use TurboVNC is to set it up on the same server that is running VirtualGL. This allows VirtualGL to send its rendered 3D images to TurboVNC through shared memory rather than sending them over a network.

x11transport

The following procedure describes how to launch a 3D application using this configuration.

Procedure

  1. Follow the procedure described in Chapter 5 for starting a TurboVNC session and connecting to it.
  2. Open a new terminal inside the TurboVNC desktop.
  3. In the terminal, start a 3D application using VirtualGL:
    /opt/VirtualGL/bin/vglrun [vglrun options] {application_executable_or_script} {arguments}
    
    The TurboVNC startup script sets the VGL_COMPRESS environment variable to 0, which will automatically enable the X11 Transport within VirtualGL.

6.2 Using TurboVNC When VirtualGL Is Running on a Different Machine

vgltransportservernetwork

If TurboVNC and VirtualGL are running on different servers, then it is desirable to use the VGL Transport to send images from the VirtualGL server to the TurboVNC server. It is also desirable to disable image compression in the VGL Transport. Otherwise, the images would have to be compressed by the VirtualGL server, decompressed by the VirtualGL Client, then recompressed by the TurboVNC server, which is a waste of CPU resources. However, sending images uncompressed over a network requires a fast network (generally, Gigabit Ethernet or faster), so there needs to be a fast link between the VirtualGL server and the TurboVNC server for this procedure to perform well.

Procedure

  1. Follow the procedure described in Chapter 5 for starting a TurboVNC session and connecting to it.
  2. Open a new terminal inside the TurboVNC desktop.
  3. In the same terminal window, open a Secure Shell (SSh) session into the VirtualGL server:
    /opt/VirtualGL/bin/vglconnect {user}@{server}
    
    Replace {user} with your user account name on the VirtualGL server and {server} with the hostname or IP address of that server. Refer to the VirtualGL User’s Guide for additional vglconnect options.
  4. In the SSh session, set the VGL_COMPRESS environment variable to rgb

    Passing an argument of -c rgb to vglrun achieves the same effect.

  5. In the SSh session, start a 3D application using VirtualGL:
    /opt/VirtualGL/bin/vglrun [vglrun options] {application_executable_or_script} {arguments}
    



7 Compatibility Guide

In order to realize the full performance benefits of TurboVNC, it is necessary to use a TurboVNC server and a TurboVNC viewer in concert. However, TurboVNC is fully backward compatible with TightVNC, RealVNC, and other VNC flavors, as well as fully forward compatible with TigerVNC. You can use the TurboVNC viewer to connect to a non-TurboVNC server (or vice versa), although this will result in some decrease in performance.

The following sections list additional things to bear in mind when mixing TurboVNC with other VNC flavors.

7.1 TightVNC or TigerVNC Servers

7.2 TightVNC or TigerVNC Viewers

7.3 RealVNC

The TurboVNC server and viewer both support the Hextile and Raw protocols, which are compatible with RealVNC. Neither of these protocols can be selected from the TurboVNC Viewer GUI, but Hextile will be selected automatically when connecting to a RealVNC server. Raw will be automatically selected when connecting to a VNC server running on the same machine as the viewer. Both Raw and Hextile can also be manually selected from the vncviewer command line.

The Raw protocol can perform well on gigabit links. The Hextile protocol, however, uses very small tiles, and thus it incurs a large amount of overhead, even on the fastest of networks. Thus, neither protocol should be used unless absolutely necessary. One interesting note, however, is that many of the TurboVNC viewer enhancements (including optimized blitting, hiding network latency, and double buffering) are available even when using these legacy protocols. Thus, in some cases, the TurboVNC viewer may actually perform better than the RealVNC viewer when connecting to RealVNC servers.