User’s Guide for TurboVNC 1.0.1

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 packages include 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, 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 libjpeg-turbo, 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.

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 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 5 Megabit/second broadband connection at reduced (but usable) image quality.

TurboVNC is compatible with other VNC distributions. See Chapter 9 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
  • 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 (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
  • 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 X server configured to export True Color (24-bit or 32-bit) visuals

3.3 Solaris/SPARC

TurboVNC should (theoretically) build and run on SPARC with Solaris 10 or newer, but this configuration has not been tested. If you encounter any problems, then please contact us.

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

Font Dependencies

On some Linux distributions, most notably Fedora 10 and later, the basic X11 bitmap fonts are not installed by default. Thus, it is necessary to install the xorg-x11-fonts-misc package on these distributions prior to starting a TurboVNC session for the first time. Otherwise, TurboVNC will fail with the following error:

Fatal server error:
could not open default font 'fixed'

Installing TurboVNC

  1. Download the appropriate TurboVNC binary package for your system from the Files area of the VirtualGL SourceForge project page.
  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 (TurboVNC-{version}-x86.pkg.bz2 for 32-bit systems or TurboVNC-{version}-x64.pkg.bz2 for 64-bit systems) from the Files area of the VirtualGL SourceForge project page.
  2. Log in as root, cd to the directory where you downloaded the package, and issue the following commands:
    If TurboVNC 0.6 or older is installed
    pkgrm SUNWtvnc
    
    If TurboVNC 1.0 or newer is installed
    pkgrm TurboVNC
    
    (answer “Y” when prompted.)
    bzip2 -d TurboVNC*.pkg.bz2
    pkgadd -d TurboVNC*.pkg
    
    Select the TurboVNC package (usually option 1) from the menu.

4.3 Installing the TurboVNC Viewer on OS X

  1. Download the TurboVNC Mac disk image (TurboVNC-{version}.dmg) from the Files area of the VirtualGL SourceForge project page.
  2. Open the disk image, then open TurboVNC-{version}.pkg inside the disk image. Follow the instructions to install the Mac client.

4.4 Installing the TurboVNC Viewer on Windows

  1. Download the TurboVNC Windows installer package (TurboVNC-{version}.exe for 32-bit systems or TurboVNC64-{version}.exe for 64-bit systems) from the Files area of the VirtualGL SourceForge project page.
  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 project page, uncompress it, cd vnc/vnc_unixsrc, and read BUILDING.txt 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 TurboVNC

Answer “yes” when prompted.

OS X

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 are running Windows Vista), or select “Uninstall TurboVNC” in the “TurboVNC” Start Menu group.



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 machine:
    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 machine and {server} with the hostname or IP address of that machine.
  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, and if VNC password authentication is enabled for the session, then TurboVNC will prompt for a VNC 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 password (if standard VNC authentication is being used) or for the username and password (if Unix login authentication is being used.)

    Windows TurboVNC Viewer Linux/Mac/Solaris TurboVNC Viewer
    Standard VNC Authentication Dialog turbovnc3 turbovnc4
    Unix Login Authentication Dialog turbovnc5 turbovnc6

    Enter the VNC session password or the Unix username/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 machine.

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 machine (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 machine, 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.4.2 Automatic Lossless Refresh

Passing an argument of -alr {timeout} to vncserver will enable the automatic lossless refresh (ALR) feature for the TurboVNC session. ALR will monitor all of the VNC viewer connections, and if more than {timeout} seconds have elapsed since the last framebuffer update was sent to a given viewer, then the TurboVNC Server will send to that viewer a mathematically lossless copy of screen regions that have been affected by lossy compression.

The ALR feature is designed mainly for use by interactive visualization applications. The idea is that, on a low-bandwidth connection, low-quality JPEG can be used while the user is rotating/panning/zooming a 3D scene, but when the user stops manipulating the scene, then a fully lossless copy of the 3D image is sent for them to study in detail.

The default ALR behavior is to monitor and send lossless copies of only the screen regions which were drawn using X[Shm]PutImage(). When used with VirtualGL, this means that ALRs will mainly be sent for just the 3D screen regions. This should be fine for most 3D applications, since the 3D regions are the ones which are quality-critical. The default ALR behavior also prevents what might best be termed the “blinking cursor dilemma.” Certain ill-behaved window managers update a small region of the taskbar continuously, even though none of the pixels in that region have changed. Also, certain programs have a blinking cursor which may update more frequently than the ALR timeout. Since an ALR is triggered based on a period of inactivity relative to the last framebuffer update, these continuous updates prevent an ALR from ever being sent. Fortunately, these ill-behaved window managers and blinking cursors do not typically use X[Shm]PutImage() to perform their continuous updates, so the problem can be worked around by limiting the regions which are “eligible” for ALR to just the subset of regions which were drawn with the X[Shm]PutImage() functions.

You can override the default ALR behavior, thus making all screen regions eligible for ALR, by setting the TVNC_ALRALL environment variable to 1 on the TurboVNC server machine prior to starting a TurboVNC session.

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 machine, open a new SSH connection into the TurboVNC server machine 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 machine and {server} with the hostname or IP address of that machine. 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.)

The -via Command-Line Option

If you are using the Unix/Linux TurboVNC Viewer, then you can simplify the above by using the -via command-line option to vncviewer. For instance, running

/opt/TurboVNC/bin/vncviewer -via {user}@{server} localhost:{n}

is the equivalent of running

/usr/bin/ssh -L {5900+n}:localhost:{5900+n} {user}@{server}
/opt/TurboVNC/bin/vncviewer localhost:{n}

The command used to establish the SSH tunnel is configurable by way of environment variables. See the vncviewer man page for more details.

Forcing Secure Connections

Passing an argument of -localhost to vncserver will force the TurboVNC Server session to accept inbound connections only from the server machine. This effectively forces SSH tunneling to be used for remote connections. If the no-remote-connections directive is set in the TurboVNC authentication configuration file, then that has the effect of enabling the -localhost option for all new TurboVNC sessions that are started on the machine.

Passing an argument of -noreverse to vncserver will disable the ability to make outbound (reverse) connections from the TurboVNC Server session. If the no-reverse-connections directive is set in the TurboVNC authentication configuration file, then that has the effect of enabling the -noreverse option for all new TurboVNC sessions that are started on the machine.

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



6 TurboVNC Authentication Extensions

The TurboVNC Server supports four “authentication methods”, which are used to validate authentication credentials sent from a VNC viewer:

No Authentication
Any viewer may connect without sending any authentication credentials.
VNC Password Authentication
A valid VNC password must be sent from the VNC viewer using the “Standard VNC” authentication capability (see below) before it is allowed to connect. The VNC password is typically stored in a file under the user’s home directory on the server machine. It is separate from any other login credentials and thus represents less of a security threat if compromised (that is, assuming the VNC password and the Unix login password are not set to the same value.)
One-Time Password (OTP) Authentication
Using vncpasswd, a unique password is generated “on the fly” for the TurboVNC session and is printed on the server’s command line (see the man page for vncpasswd for more details.) The user enters this password in the VNC viewer as if it were a VNC password, and the viewer sends the OTP using the “Standard VNC” authentication capability (see below.) However, once the OTP has been used once to authenticate a viewer, it is forgotten and cannot be reused. OTP authentication can be used, for instance, to launch or connect to TurboVNC sessions from an automated web portal or from a job scheduler. OTP authentication is also useful for allowing temporary access to a TurboVNC session for collaboration purposes.
PAM User/Password Authentication
The TurboVNC Server uses Pluggable Authentication Modules (PAM) to validate a username and password received from a VNC viewer via the “Unix login” authentication capability (see below.) The username and password received from the VNC viewer need not necessarily be validated against Unix login credentials. Generally, the server can be configured to use any user/password authentication credentials that can be accessed through PAM. Since the “Unix login” authentication capability sends the password as plain text, it is strongly recommended that this authentication method be enabled only if the server is restricted to only allow loopback (SSH) connections and to disallow reverse connections (see Section 5.5.)

The TurboVNC Viewer supports three “authentication capabilities”, which are protocols used to validate authentication credentials with a VNC server:

None
No authentication credentials are sent to the server.
Standard VNC Authentication
A password is sent to the server using a DES-encrypted challenge-response scheme. The password can be up to 8 characters long, so the DES key length is 56 bits. This is not a particularly strong form of encryption by today’s standards (56-bit DES was broken by brute force attack in the late 90’s.)
Unix Login Authentication
Both the username and password are sent to the server as plain text. Thus, it is strongly recommended that this authentication capability be used only with an SSH-encrypted TurboVNC connection (see Section 5.5.)

6.1 Enabling Authentication Methods

The default behavior of the TurboVNC Server is for all authentication methods to be enabled and for VNC password authentication and OTP to be preferred over PAM user/password authentication. However, the system administrator can disable one or more of the authentication methods or set the preferred order of the authentication methods by editing the server’s authentication configuration file. See the Xvnc man page for more details.

If the server allows multiple authentication methods that support multiple authentication capabilities, then the client’s default authentication capability will be determined by the preferred authentication method on the server. In this case, the user can override the default by passing command-line arguments to vncviewer. If the server prefers an authentication method that supports standard VNC authentication, then the user can force the use of Unix login authentication by passing an argument of -user {user_name} to vncviewer when connecting to the TurboVNC session. Similarly, if the server prefers an authentication method that supports Unix login authentication, then the user can force the use of standard VNC authentication by passing an argument of -nounixlogin to vncviewer. Both of these command-line options work with both the Unix and Windows versions of vncviewer. Note that if using the Java TurboVNC Viewer, the same thing can be accomplished by setting the USER parameter or setting the No Unix Login parameter to Yes in /opt/TurboVNC/vnc/classes/index.vnc.

Because of the way that the Windows TurboVNC Viewer caches settings for each connection, the -user and -nounixlogin options may not work properly unless you also specify the connection name on the command line (example: vncviewer -nounixlogin my_server:1).

If the system administrator has not restricted any of the authentication methods on a system-wide basis, then the user can choose to disable some or all of them for a single TurboVNC session by passing command-line arguments to vncserver. See the vncserver man page for more details.

6.2 Further Reading

For more detailed information about the TurboVNC authentication extensions, refer to the TurboVNC man pages:

man -M /opt/TurboVNC/man {vncserver | Xvnc | vncviewer | vncpasswd}



7 Multithreading in TurboVNC

The TurboVNC Server can use multiple threads to perform image encoding and compression, thus allowing it to take advantage of multi-core or multi-processor systems. The server splits the screen vertically into N tiles, where N is the number of threads, and assigns each tile to a separate thread. The scalability of this algorithm is nearly linear when used with demanding 3D or video applications that fill most of the screen. However, whether or not multithreading improves the overall performance of TurboVNC depends largely on the performance of the client and the network. If either the client or the network are the primary performance bottlenecks, then multithreading the server will not help. It will almost certainly have no effect on networks slower than 100 Megabit Ethernet or when using the Java TurboVNC Viewer.

To enable server-side multithreading, set the TVNC_MT environment variable to 1 on the server prior to starting vncserver. The default behavior is to use as many threads as there are cores on the server machine, but you can set the TVNC_NTHREADS environment variable to override this.



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

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

8.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}
    



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

9.1 TightVNC or TigerVNC Servers

9.2 TightVNC or TigerVNC Viewers

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



10 Advanced Configuration

10.1 Server Settings

Environment Variable TVNC_ALRALL = 0 | 1
Summary Disable/Enable automatic lossless refresh for regions which were drawn using methods other than X[Shm]PutImage()
Platforms Unix
Default Value Disabled
Description
See Section 5.4.2
Environment Variable TVNC_MT = 0 | 1
Summary Disable/Enable multithreaded image encoding
Platforms Unix
Default Value Disabled
Description
See Chapter 7
Environment Variable VGL_NTHREADS = {n}
Summary Use {n} threads to perform image encoding
Platforms Unix
Default Value {n} = the number of CPU cores in the system
Description
See Chapter 7
Environment Variable TVNC_PROFILE = 0 | 1
Summary Disable/enable profiling output
Platforms Unix
Default Value Disabled
Description
If profiling output is enabled, then the TurboVNC Server will continuously benchmark itself and periodically print the throughput of various stages in its image pipeline to the Xvnc log file.

10.2 Client Settings

Environment Variable TVNC_PROFILE = 0 | 1
Summary Disable/enable profiling output
Platforms Unix
Default Value Disabled
Description
If profiling output is enabled, then the TurboVNC Viewer will continuously benchmark itself and periodically print the throughput of various stages in its image pipeline to the console.