Date: 2013-11-22T12:16:17

User’s Guide for TurboVNC 1.2.1

# 1 Legal Information

This document and all associated illustrations are licensed under the Creative Commons Attribution 2.5 License. Any works that 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 official TurboVNC binaries contain libjpeg-turbo, which is based in part on the work of the Independent JPEG Group.

The TurboVNC Windows packages include PuTTY, which is released under this license.

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

# 2 Conventions Used in This Document

This document assumes that TurboVNC will be installed in the default directory (`/opt/TurboVNC` on Un*x and Mac systems and `c:\Program Files\TurboVNC` on Windows systems.) If your installation of TurboVNC resides in a different directory, then adjust the instructions accordingly.

# 3 Overview

TurboVNC is a derivative of VNC (Virtual Network Computing) that is tuned to provide peak performance for 3D and video workloads. TurboVNC was originally based on the TightVNC 1.3.x and xf4vnc code bases, and on the surface, it behaves similarly to its parents. However, TurboVNC compresses 3D and video workloads significantly better than the “tightest” compression mode in TightVNC 1.3.x while using only typically 15-20% of the CPU time of the latter. Using non-default settings, TurboVNC can also match the best compression ratios produced by TightVNC 1.3.x for 2D workloads (see Section 7.2.)

All VNC implementations, including TurboVNC, use the RFB (remote framebuffer) protocol to send “framebuffer updates” from the VNC server to any connected “viewers.” Each framebuffer update can contain multiple “rectangles” (regions that have changed since the last update.) As with TightVNC, TurboVNC analyzes each rectangle, splits it into multiple “subrectangles”, and attempts to encode each subrectangle using the “subencoding type” that will provide the most efficient compression, given the number of unique colors in the subrectangle. The process by which TurboVNC does this is referred to as an “encoding method.” A rectangle is first analyzed to determine if any significant portion of it is solid, and if so, that portion is encoded as a bounding box and a fill color (“Solid subencoding.”) Of the remaining subrectangles, those with only two colors are encoded as a 1-bit-per-pixel bitmap with a 2-color palette (“Mono subencoding”), those with low numbers of unique colors are encoded as a color palette and an 8-bit-per-pixel bitmap (“Indexed color subencoding”), and subrectangles with high numbers of unique colors are encoded using either JPEG or arrays of RGB pixels (“Raw subencoding”), depending on the encoding method. zlib can optionally be used to compress the indexed color, mono and raw subrectangles.

Part of TurboVNC’s speedup comes from the use of libjpeg-turbo, the same high-speed SIMD-optimized JPEG codec used by VirtualGL. However, TurboVNC also eliminates the CPU-hungry smoothness detection routines that TightVNC uses to determine whether a subrectangle is a good candidate for JPEG compression, and TurboVNC’s encoding methods tend to favor the use of JPEG more, since it is now generally the fastest subencoding type. Furthermore, TurboVNC eliminates buffer copies, it maximizes network efficiency by splitting framebuffer updates into relatively large subrectangles, and it uses only the zlib compression levels that can be shown to have a measurable performance benefit.

TurboVNC is the product of extensive research, in which many different permutations of the TightVNC encoder were benchmarked at the low level against a variety of captured RFB sessions that simulate real-world application workloads, both 2D and 3D. For more information on the research leading to TurboVNC’s encoder design, see this report.

In addition to high performance, other notable features of TurboVNC include:

- Fine-grained control over the JPEG image quality and the level of chrominance subsampling
- Double buffering on the client side to reduce tearing artifacts in 3D and video applications
- Flexible and configurable full-screen/multi-screen support
- Full support for IPv6
- Advanced flow control and continuous updates. This allows clients to receive framebuffer updates without specifically requesting them, which can improve performance dramatically on high-latency connections.
- Authentication with one-time passwords or Unix login credentials. Access control lists can be used to share VNC sessions with only certain users.
- TurboVNC allows security/authentication policies to be set globally for a particular server machine.
- Multithreaded Tight encoding
- “Lossless refresh” allows a viewer to request a lossless copy of the current screen image. This is useful in situations in which image quality is critical but the network is too slow to support sending a high-quality image for every frame. Lossless refreshes can be performed manually when a certain hotkey is pressed, or the TurboVNC Server can be configured to send a lossless refresh automatically if the user stops interacting with the application for a certain period of time.
- High-performance Java viewer, deployable using Java Web Start. By calling libjpeg-turbo through JNI, the Java TurboVNC Viewer achieves similar levels of performance to the native TurboVNC Viewer.

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

On “modern” hardware, TurboVNC is capable of streaming 50+ Megapixels/second over a 100 Megabit/second local area network with perceptually lossless image quality. TurboVNC can stream between 10 and 12 Megapixels/second over a 5 Megabit/second broadband connection at reduced (but usable) image quality.

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

# 4 System Requirements

## 4.1 Linux/x86 and Other x86 Un*x Operating Systems

| Server (x86) | Server (x86-64) | Client
--- | --- | --- | ---
Recommended CPU | For optimal performance, the CPU should support SSE2 extensions. Dual processors or dual cores recommended | Dual processors or dual cores recommended | For optimal performance, the CPU should support SSE2 extensions.
Other |  |  | For optimal performance, the X server should be configured to export True Color (24-bit or 32-bit) visuals.

## 4.2 Mac/x86

| Client
--- | ---
Recommended CPU | Any Intel-based Mac
O/S | OS X 10.4 (“Tiger”) or later
Other Software | Java 1.5 or later (Java 1.6 recommended)

## 4.3 Windows

| Client
--- | ---
Recommended CPU | For optimal performance, the CPU should support SSE2 extensions.
O/S | Windows 2000 SP1 or later
Other | For optimal performance, the client display should have a 24-bit or 32-bit (True Color) color depth.

# 5 Obtaining and Installing TurboVNC

## 5.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. Packages are provided for Linux distributions in the Red Hat, SuSE, or Debian families that contain GLIBC 2.3.2 or later (including Fedora, CentOS 3 or later, Oracle Linux, and Ubuntu Linux v6.0 or later.)
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

## 5.2 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.pkg` inside the disk image. Follow the instructions to install the Mac TurboVNC Viewer.

## 5.3 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.

## 5.4 Installing TurboVNC from Source

If you are using a Un*x 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 turbovnc-``{version}`, and read `BUILDING.txt` for further instructions on how to build TurboVNC from source.

## 5.5 Uninstalling TurboVNC

### Linux

As root, issue one of the following commands:

RPM-based systems

      rpm -e turbovnc

Debian-based systems

      dpkg -r turbovnc

### OS X

Open the “Uninstall TurboVNC” application, located in the “TurboVNC” Applications folder. You can also open a terminal and execute:

    sudo /opt/TurboVNC/bin/uninstall

### Windows

Use the “Programs and Features” applet in the Control Panel (or the “Add or Remove Programs” applet if you are running Windows XP), or select “Uninstall TurboVNC” in the “TurboVNC” Start Menu group.

# 6 Using TurboVNC

## 6.1 Starting and Connecting to a TurboVNC Session

### Procedure

1. Open a new Command Prompt/terminal window on your client machine.
2. In the new Command Prompt/terminal window, open a Secure Shell (SSH) session into the TurboVNC server machine:
   Linux/Unix/Mac clients

         ssh {user}@{server}

   Windows clients

         "c:\program files\turbovnc\putty" {user}@{server}

     Replace `{user}` with your username on the TurboVNC server machine and `{server}` with the hostname or IP address of that machine.
3. In the SSH session, start a TurboVNC session:

       /opt/TurboVNC/bin/vncserver

4. Make a note of the X display number that the TurboVNC session is occupying, for instance:
   `Desktop 'TurboVNC: my_server:1 (my_user)' started on display 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.
5. The SSH session can now be exited, if desired.
6. On the client machine, start the TurboVNC Viewer.
   X11 TurboVNC Viewer
     Open a new terminal/xterm and type

         /opt/TurboVNC/bin/vncviewer

   Mac TurboVNC Viewer
     Open the “TurboVNC Viewer” application, located in the “TurboVNC” Applications folder.
   Windows TurboVNC Viewer
     Select “TurboVNC Viewer” in the “TurboVNC” Start Menu group.
7. A small dialog box will appear.

   Windows TurboVNC Viewer | X11 TurboVNC Viewer | Mac TurboVNC Viewer
   --- | --- | ---

   Enter the X display name (hostname/IP address and display number) of the TurboVNC session in the “VNC server” field, then click “Connect” (Windows/Mac) or press Enter (X11.)
8. 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 | X11 TurboVNC Viewer | Mac TurboVNC Viewer
   --- | --- | --- | ---
   Standard VNC Authentication Dialog |  |  |
   Unix Login Authentication Dialog |  |  |

   Enter the VNC session password or the Unix username/password and click “OK” (Windows) or press Enter (X11/Mac.)
   A TurboVNC desktop window should appear on your client machine. This window contains a virtual desktop with which you can interact to launch X-Windows applications on the TurboVNC server machine.

## 6.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 within 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 machine that is running the TurboVNC session you want to kill.
   … or …
   Using the TurboVNC Viewer, connect to the TurboVNC session that you want 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 want to kill.

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

    /opt/TurboVNC/bin/vncserver -list

## 6.3 Using TurboVNC in a Web Browser

When a TurboVNC session is created, it automatically launches a miniature web server that serves up the Java TurboVNC Viewer as an applet. The 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 TurboVNC Viewer, when run as an applet, 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.

To use the Java TurboVNC Viewer in a web browser, 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`

## 6.4 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/Unix/Mac 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 username 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 want to connect to display `:1` on server `my_server` using user account `my_user`, you would type:

Linux/Unix/Mac 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.)

You can force PuTTY to use an IPv6 interface for the local end of the tunnel by replacing `-L` with `-L6` in the above command line.

### The `-via` and `-tunnel` Command-Line Options

If you are using the X11 and Mac TurboVNC Viewers, then you can simplify the above by using the `-via` and `-tunnel` command-line options to `vncviewer`. For instance, running

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

or

    /opt/TurboVNC/bin/vncviewer -tunnel {user}@{server}

is the equivalent of running

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

where `{fp}` is a free TCP port on the client machine (this is automatically determined by `vncviewer`.)

`-tunnel` can be used as a shortcut whenever the SSH and VNC servers are the same machine. `-via` is more flexible, since it allows you to specify the VNC server to which to connect. The VNC server is specified from the point of view of the SSH server, which is why we used `localhost` in the above example.

With the X11 TurboVNC Viewer, the command used to establish the SSH tunnel is configurable by way of environment variables. See the `vncviewer` man page for more details.

NOTE: Since the Java TurboVNC Viewer contains an embedded SSH client, the `-via` and `-tunnel` parameters can also be used when the viewer is run as an applet or deployed using Java Web Start.

### 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 through 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.

## 6.5 Further Reading

For more detailed instructions on the usage of TurboVNC:

TurboVNC Server
  Refer to the TurboVNC man pages:

      man -M /opt/TurboVNC/man vncserver
      man -M /opt/TurboVNC/man Xvnc
      man -M /opt/TurboVNC/man vncconnect
      man -M /opt/TurboVNC/man vncpasswd

X11 TurboVNC Viewer
  Refer to the `vncviewer` man page:

      man -M /opt/TurboVNC/man vncviewer

Windows TurboVNC Viewer
  Use the embedded help feature (the question mark button in the upper right of the TurboVNC Viewer dialogs.) You can also run `vncviewer.exe /?` from a command prompt to get a full list of supported command-line options and their descriptions.
Mac TurboVNC Viewer
  Run

      /opt/TurboVNC/bin/vncviewer -?

  to display a full list of supported command-line options/parameters and their descriptions.

# 7 Performance and Image Quality

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 that control the manner in which TurboVNC compresses images:

Allow JPEG compression
  If this option is enabled, then TurboVNC will use JPEG compression for subrectangles that have a high number of unique colors, and it will use indexed color subencoding for subrectangles that have a low number of unique colors. If this option is disabled, then TurboVNC will select between indexed color or raw subencoding, depending on the size of the subrectangle 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
  When compressing an image using JPEG, the RGB pixels are first converted to the YCbCr colorspace, a colorspace in which each pixel is represented as a brightness (Y, or “luminance”) value and a pair of color (Cb & Cr, or “chrominance”) values. After this colorspace conversion, chrominance subsampling can be used to discard some of the chrominance components in order to save bandwidth. This works because the human eye is more sensitive to changes in brightness than to changes in color. 1X subsampling (the default in TurboVNC) retains the chrominance components for all pixels, and thus it provides the best image quality but also uses the most network bandwidth and CPU time. 2X subsampling retains the chrominance components for every other pixel, and 4X subsampling retains the chrominance components for every fourth pixel (this is typically implemented as 2X subsampling in both X and Y directions.) Grayscale throws out all of the chrominance components, leaving only luminance. 2X and 4X subsampling will typically produce noticeable blurring of lines and other sharp features, but with photographic or other “smooth” image content, it may be difficult to detect any difference between 1X, 2X, and 4X.
Zlib compression level
  If zlib compression is enabled, then indexed color, mono, and raw-encoded subrectangles will be compressed using zlib prior to transmission. This decreases network bandwidth usage at the expense of increased CPU usage. If JPEG compression is enabled, then zlib compression is always used with non-JPEG subrectangles.

In the Windows and Mac/Java TurboVNC Viewers, these parameters can be adjusted by accessing the TurboVNC Viewer 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 X11 TurboVNC Viewer, press F8 after connecting to bring up the TurboVNC Viewer Options menu.

The TurboVNC Viewer provides five preset “encoding methods”, corresponding to the most useful combinations of the image compression options described above:

Table 7.1: TurboVNC Encoding Methods
Encoding method | Allow JPEG | JPEG image quality | JPEG chrominance subsampling | Zlib compression level | Notes
--- | --- | --- | --- | --- | ---
“Tight + Perceptually Lossless JPEG” | Yes | 95 | 1x | 1 | This encoding method should be perceptually lossless (that is, any image compression artifacts it produces should be imperceptible to human vision) under most viewing conditions. This encoding method 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 | 1 | For subrectangles that have a high number of unique colors, this encoding method produces some minor, but generally not very noticeable, image compression artifacts. All else being equal, this encoding method typically uses about twice the network bandwidth of the “Tight + Low-Quality JPEG” encoding method and about half the bandwidth of the “Tight + Perceptually Lossless JPEG” encoding method, making it appropriate for medium-speed networks such as 10 Megabit Ethernet.
“Tight + Low-Quality JPEG” | Yes | 30 | 4x | 1 | For subrectangles that have a high number of unique colors, this encoding method 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 methods or take advantage of the Lossless Refresh feature.
“Lossless Tight” | No | N/A | N/A | None | This encoding method uses indexed color subencoding for subrectangles that have a low number of unique colors, but it otherwise does not perform any image compression at all. Lossless Tight is thus suitable only for gigabit and faster networks. This encoding method uses significantly less CPU time than any of the JPEG-based encoding methods. Lossless Tight requires an RFB protocol extension that is, as of this writing, only supported by the TurboVNC Viewer.
“Lossless Tight + Zlib” | No | N/A | N/A | 1 | This encoding method uses indexed color subencoding for subrectangles that have a low number of unique colors and raw subencoding for subrectangles that have a high number of unique colors. It compresses all subrectangles using zlib with zlib compression level 1. For certain types of low-color workloads (CAD applications, in particular), this encoding method may use less network bandwidth than the “Tight + Perceptually Lossless JPEG” encoding method, but it also uses significantly more CPU time than any of the JPEG-based encoding methods.

In the Windows and Java/Mac TurboVNC Viewers, the encoding method can be set in the TurboVNC Viewer 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.)

With the X11 TurboVNC Viewer, the “Perceptually Lossless” encoding method is the default (unless it has been overridden using a resource file), but the following command-line switches can be used to specify the encoding method:

`-highqual` = select the “Tight + Perceptually Lossless Quality JPEG” encoding method
`-medqual` = select the “Tight + Medium Quality JPEG” encoding method
`-lowqual` = select the “Tight + Low Quality JPEG” encoding method
`-lossless` = select the “Lossless Tight” encoding method
`-losslesswan` = select the “Lossless Tight + Zlib” encoding method

After connecting, you can also press the F8 key to pop up the TurboVNC Viewer Options menu, from which you can select a different encoding method.

## 7.1 Interframe Comparison

Certain ill-behaved applications can sometimes draw the same thing over and over again, and this can cause redundant framebuffer updates to be sent to the VNC viewer. The TurboVNC Server can guard against this by maintaining a copy of the remote framebuffer for each connected viewer, comparing each new framebuffer update against the pixels in the framebuffer copy, and discarding any redundant updates before they are sent to the viewer.

Enabling interframe comparison increases the memory usage of the TurboVNC Server by a factor of N, where N is the number of connected clients, and interframe comparison increases the server CPU usage by about 10-15% as well. Further, duplicate framebuffer updates are not typically a problem for 3D and video applications, and the effects of these duplicate updates, even when they exist, are not typically noticeable on high-speed networks. Thus, interframe comparison is not enabled by default and should not generally be enabled except on low-bandwidth networks and with applications for which it can be shown to be beneficial.

Interframe comparison can be enabled by either passing an argument of `-interframe` to `vncserver` when starting a TurboVNC Server session or by requesting a compression level of 5 or higher from the viewer (see below.)

## 7.2 Advanced Compression Options

One of the underlying principles of TurboVNC’s design is to expose only the options that provide the best performance “bang for the buck.” Thus, the TurboVNC Viewer GUI does not normally provide any way of requesting a compression level greater than 1. Compression Levels 2-9 can, however, be specified on the command line (or as a parameter, if using the Java TurboVNC Viewer), and doing so will enable an advanced mode in the TurboVNC Viewer GUI that allows any compression level from 0 to 9 to be requested.

When connecting to a TurboVNC server, requesting a particular compression level has the following effect:

Table 7.2: Compression Levels Supported by the TurboVNC Server (JPEG Enabled)
Compression level | Zlib compression level (non-JPEG subrectangles) | Palette threshold | Interframe comparison | Notes
--- | --- | --- | --- | ---
0 | 1 | 24 | No | Same as Compression Level 1. Bypassing zlib when JPEG is enabled would only reduce the CPU usage for non-JPEG subrectangles, which is of limited usefulness. Further, bypassing zlib requires an RFB protocol extension that is not supported by non-TurboVNC viewers. It is presumed that, if one wants to reduce the CPU usage, then one wants to do so for all subrectangles, so CL 0 without JPEG (AKA “Lossless Tight”) should be used.
1 | 1 | 24 | No | See the description of the “Tight + JPEG” encoding methods above.
2 | 3 | 96 | No | A higher palette threshold causes indexed color subencoding to be used more often than with CL 1, and indexed color subrectangles are compressed using a higher zlib compression level. This can provide typically 20-40% better compression than CL 1 (with a commensurate increase in CPU usage) for workloads that have a low number of unique colors. However, Compression Level 2 will increase the CPU usage for high-color workloads without providing significantly better compression.
3-4 | 3 | 96 | No | Same as Compression Level 2 (reserved for future expansion)
5-6 | 1 | 24 | Yes | Same as Compression Level 1, but with interframe comparison enabled
7-8 | 3 | 96 | Yes | Same as Compression Level 2, but with interframe comparison enabled
9 | 7 | 256 | Yes | This mode is included only for backward compatibility with TightVNC. It provides approximately the same level of compression for 2D applications as Compression Level 9 in TightVNC 1.3.x, while using much less CPU time. It also provides much better compression than TightVNC for 3D and video applications. However, relative to Compression Level 2, this mode uses approximately twice as much CPU time and only achieves about 10-20% better average compression for 2D apps (and has no noticeable benefit for 3D and video apps.) Thus, its usefulness is generally very limited.

Table 7.3: Compression Levels Supported by the TurboVNC Server (JPEG Disabled)
Compression Level | Zlib compression level (indexed color subrectangles) | Zlib compression level (raw subrectangles) | Palette threshold | Interframe comparison | Notes
--- | --- | --- | --- | --- | ---
0 | None | None | Subrectangle size / 4 | No | See the description of the “Lossless Tight” encoding method above.
1 | 1 | 1 | Subrectangle size / 96 | No | See the description of the “Lossless Tight + Zlib” encoding method above.
2-4 | 1 | 1 | Subrectangle size / 96 | No | Same as Compression Level 1 (reserved for future expansion)
5 | None | None | Subrectangle size / 4 | Yes | Same as Compression Level 0, but with interframe comparison enabled
6-8 | 1 | 1 | Subrectangle size / 96 | Yes | Same as Compression Level 1, but with interframe comparison enabled
9 | 7 | 5 | Subrectangle size / 96 | Yes | This mode is included only for backward compatibility with TightVNC. It provides approximately the same level of compression for 2D applications as Compression Level 9 in TightVNC 1.3.x, while using much less CPU time. It also provides much better compression than TightVNC for 3D and video applications. However, relative to Compression Level 1, this mode uses approximately twice as much CPU time and only achieves about 10% better average compression for 2D apps (and has no noticeable benefit for 3D and video apps.) Thus, its usefulness is generally very limited.

## 7.3 Lossless Refresh

Since both of TurboVNC’s mathematically lossless encoding methods 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, press CTRL-ALT-SHIFT-L (in the Windows and Java/Mac TurboVNC Viewers, you can also click on the Lossless Refresh toolbar icon.)

## 7.4 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 any screen regions that have been affected by lossy compression. You can also pass arguments of `-alrqual` and `-alrsamp` to `vncserver` to specify that automatic lossless refreshes should be sent using JPEG instead (see the `Xvnc` man page for details.)

The ALR feature is designed mainly for use with 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 that 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 that are quality-critical. The default ALR behavior also prevents what might best be called 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 that 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 updates, so the problem is effectively worked around by limiting the regions that are “eligible” for ALR to just the subset of regions that 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.

## 7.5 Multithreading

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 viewer and the network. If either the viewer or the network is the primary performance bottleneck, 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 as an applet.

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.

## 7.6 Accelerating the Java TurboVNC Viewer

### Accelerating JPEG Decoding

The Java TurboVNC Viewer can be used as a standalone app, in which case it provides most of the same features as the native TurboVNC viewers. It can also load libjpeg-turbo through JNI to accelerate JPEG decoding, which gives the Java viewer similar performance to the native viewers in most cases. If you are using the Mac TurboVNC Viewer (which is just the Java viewer packaged in a Mac app bundle), then libjpeg-turbo is embedded in the app bundle, so no further action is needed to accelerate it. If you are using the Java TurboVNC Viewer on Windows or Linux, then you will need to install one of the official libjpeg-turbo packages (version 1.3.0 or later) in order to accelerate JPEG decoding. Install the appropriate version of libjpeg-turbo (32-bit or 64-bit) to match your JRE. If you are launching the Java TurboVNC Viewer from the command line, then it will print a warning if it is unable to load libjpeg-turbo. Otherwise, if you are launching the viewer from an icon, you can verify whether libjpeg-turbo has been loaded by opening the “Connection info” dialog (after the connection to the server has been established) and verifying that the “JPEG decompression” field says “Turbo”.

### Accelerating X11 Blitting

When running the Java TurboVNC Viewer on Un*x platforms, it is necessary to enable MIT-SHM Pixmap support in order to achieve optimal blitting (image drawing) performance. MIT-SHM Pixmaps are not always enabled by default on certain graphics cards (some nVidia cards, for instance), and in such cases, it may be necessary to add an entry to xorg.conf in order to enable them. You can verify whether X11 blitting is being accelerated by running

    java -Dsun.java2d.trace=count -cp /opt/TurboVNC/java/VncViewer.jar com.turbovnc.vncviewer.ImageDrawTest

Let the benchmark run for 15 or 20 seconds, then abort it with CTRL-C. If you notice in the Java 2D trace output that there are no calls to `sun.java2d.x11.X11PMBlitLoops::Blit()`, then blitting is not being accelerated, and the most likely reason is that MIT-SHM Pixmaps are not enabled.

Sometimes the benchmark will report that the graphics device supports H/W acceleration even when it doesn’t. This is due to a bug in Java 2D. Thus, looking at the trace output is the only reliable way to determine whether or not X11 blitting is being accelerated.

Even with accelerated X11 blitting, the Java TurboVNC Viewer may not be quite as fast as the X11 TurboVNC Viewer on older, slower systems. This is because image drawing in Java 2D requires an extra memory copy that is not required when using raw X11 commands. However, on newer systems with fast memory access (particularly systems with a large L2 or L3 cache), this overhead should have a negligible impact on overall performance.

### Using the Server VM

Passing an argument of `-server` to `java` when launching the Java TurboVNC Viewer is recommended. This enables the adaptive compiler, which performs aggressive code optimizations and actually learns how to better optimize a piece of code the more times it encounters it. Such optimizations greatly improve the decoding performance for non-JPEG subrectangles. If using the Mac TurboVNC Viewer app, then the Server VM is automatically enabled.

### Java Web Start

Java Web Start can be used to deploy the Java TurboVNC Viewer and the associated libjpeg-turbo JNI libraries from a web server. Deploying the viewer using JWS provides a fully functional and performant TurboVNC Viewer environment without requiring the viewer to be installed on the client machine. This mechanism is preferred over deploying the viewer as an applet, since JPEG decoding cannot be accelerated when the Java TurboVNC Viewer is run as an applet. See http://www.virtualgl.org/Documentation/JWS for more details.

# 8 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 scheme (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 scheme (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 using the “Unix login” authentication scheme (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 scheme 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 6.4.)

The TurboVNC Viewer supports three “authentication schemes”, 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 scheme be used only with an SSH-encrypted TurboVNC connection (see Section 6.4.)

## 8.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 schemes, then the client’s default authentication scheme 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 the Unix, Mac, and Windows versions of `vncviewer`. When using the Java/Mac TurboVNC Viewer, you can also accomplish the same thing by unchecking “Unix Login” or “Standard VNC” in the “Security” tab of the Options dialog. When using the Java TurboVNC Viewer as an applet, you can accomplish the same thing by setting the `User` or `NoUnixLogin` parameters in `/opt/TurboVNC/java/index.vnc` on the server.

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.

## 8.2 Further Reading

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

    man -M /opt/TurboVNC/man vncserver
    man -M /opt/TurboVNC/man Xvnc
    man -M /opt/TurboVNC/man vncviewer
    man -M /opt/TurboVNC/man vncpasswd

# 9 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)

- When using the VGL Transport, non-3D portions of the application’s GUI are sent over the network using remote X11, which will create performance problems on high-latency networks (such as broadband or long-haul fibre.) Non-3D portions of the application’s GUI will load and render much faster (perhaps even orders of magnitude faster) with TurboVNC than with the VGL Transport on such connections.
- For 3D applications whose rendered images do not contain very many unique colors (for instance, CAD applications in wireframe mode), the hybrid encoding methods used by TurboVNC will generally use less network bandwidth than the pure JPEG encoding method used by the VGL Transport.
- TurboVNC provides two lossless compression modes, one of which is designed to reduce server CPU usage on gigabit networks and the other of which is designed to provide reasonable performance on wide-area networks (at the expense of higher server CPU usage.) The VGL Transport’s only lossless option is uncompressed RGB.
- TurboVNC includes a lossless refresh feature that will, on demand, send a mathematically lossless image of the current VNC desktop to the client. A user connecting over a low-bandwidth connection can use low-quality JPEG to achieve the best performance when manipulating the 3D model, then they can request a lossless refresh when they are ready to study the model in detail.
- The TurboVNC Server can be configured to send a mathematically lossless copy of certain regions of the screen during periods of inactivity (Automatic Lossless Refresh.)
- TurboVNC provides rudimentary collaboration capabilities. Multiple clients can simultaneously view the same TurboVNC session and pass around control of the keyboard and mouse.
- The TurboVNC Viewer is stateless. If the network hiccups or the viewer is otherwise disconnected, the session continues to run on the server and can be rejoined from any machine on the network.
- No X server is required on the client machine. This reduces the deployment complexity for Windows clients.
- Any web browser or mobile device can be used as a TurboVNC client (with reduced performance.)

### Disadvantages of TurboVNC (when compared to the VGL transport)

- No seamless windows. All application windows are constrained to a “virtual desktop”, which displays in a single window on the client machine.
- TurboVNC will generally require about 20% more server CPU cycles to maintain the same frame rate as the VGL Transport, both because it has to compress more pixels in each frame (an entire desktop rather than a single window) and because it has to perform 2D (X11) rendering as well as 3D rendering.
- TurboVNC does not support quad-buffered stereo or transparent overlays.

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

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

### Procedure

1. Follow the procedure described in Chapter 6 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.

## 9.2 Using TurboVNC When VirtualGL Is Running on a Different Machine

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 6 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 username 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}

# 10 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 compatible with TigerVNC, TightVNC, RealVNC, and other VNC flavors. You can use the TurboVNC Viewer to connect to a non-TurboVNC server (or vice versa), although this will generally result in some decrease in performance.

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

## 10.1 TightVNC or TigerVNC Servers

- TightVNC and TigerVNC specify the JPEG quality level on a scale from 0 to 9. This translates to actual JPEG quality as follows:
  TightVNC JPEG Quality Levels

    JPEG quality level | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
    --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
    Actual JPEG quality | 5 | 10 | 15 | 25 | 37 | 50 | 60 | 70 | 75 | 80
    Actual chrominance subsampling | 2X | 2X | 2X | 2X | 2X | 2X | 2X | 2X | 2X | 2X

  TigerVNC JPEG Quality Levels

    JPEG quality level | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
    --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
    Actual JPEG quality | 15 | 29 | 41 | 42 | 62 | 77 | 79 | 86 | 92 | 100
    Actual chrominance subsampling | 4X | 4X | 4X | 2X | 2X | 2X | 1X | 1X | 1X | 1X
    Average compression ratio * | 100 | 80 | 70 | 60 | 50 | 40 | 30 | 25 | 20 | 10

    * Experimentally determined by compressing every 10th frame in the SPECviewperf 9 benchmark suite

  TurboVNC, on the other hand, includes extensions to Tight encoding that allow the JPEG quality to be specified on the standard 1-100 scale and allow the JPEG chrominance subsampling to be specified seperately. TigerVNC 1.2 (and later) includes the same extensions on the server side, so the TigerVNC 1.2 Server will behave like the TurboVNC Server when a TurboVNC viewer is connected to it.
  When a TurboVNC viewer is connected to a TightVNC or TigerVNC 1.0/1.1 server, setting the JPEG quality to N in the TurboVNC Viewer sets the JPEG quality level to N/10 on the TightVNC or TigerVNC server. For instance, if you set the JPEG quality to 95 in the TurboVNC Viewer, this would translate to a JPEG quality level of 9, which would set the actual JPEG quality/subsampling to 80/2X if connected to a TightVNC server or 100/1X if connected to a TigerVNC 1.0/1.1 server.
- Changing the JPEG chrominance subsampling option in the TurboVNC Viewer has no effect when connected to a TightVNC or TigerVNC 1.0/1.1 server.
- Although Compression Levels 2-9 cannot be set using the TurboVNC Viewer GUI, you can still specify these higher compression levels from the TurboVNC Viewer command line. It should be noted, however, that our experiments have shown that compression levels higher than 5 are generally not useful in the TightVNC or TigerVNC Servers. They increase CPU usage exponentially without providing any significant savings in bandwidth relative to Compression Level 5.
- TurboVNC supports an extension to Tight encoding that allows the server to tell the viewer not to use zlib to decompress a particular subrectangle. zlib introduces a tremendous amount of performance overhead, even when zlib compression level 0 (no compression) is used. Thus, when a TurboVNC viewer requests Compression Level 0 from the TurboVNC Server, the TurboVNC Server bypasses zlib altogether. TightVNC and TigerVNC servers do not support this extension, and thus they will still use zlib to “compress” the framebuffer updates even if you request Compression Level 0 using the TurboVNC Viewer.
- The TightVNC Server will use much more CPU time across the board than the TurboVNC Server, all else being equal. TigerVNC 1.2 can be made to perform similarly to a single-threaded instance of TurboVNC, but this requires using non-default settings in TigerVNC. The default TigerVNC settings are roughly equivalent to Compression Level 2 in TurboVNC, which will use significantly more CPU time than Compression Level 1. Additionally, TigerVNC does interframe comparison by default whenever Compression Level 2 or above is selected, and this increases CPU time even more. Compression Level 1 should be used in TigerVNC in order to simulate the behavior of TurboVNC’s “Tight + JPEG” encoding methods.

## 10.2 TightVNC or TigerVNC Viewers

- The TurboVNC Server will attempt to emulate the behavior of a TigerVNC server and will translate JPEG quality levels into actual JPEG quality and subsampling, as specified in Section 10.1.
- When either a TightVNC or TigerVNC viewer is connected to a TurboVNC server and JPEG subencoding is disabled, setting the compression level to 0 in the viewer will cause the connection to abort with a “bad subencoding value” error. This is because the TurboVNC Server is attempting to send the framebuffer updates with no zlib compression, and the TightVNC and TigerVNC viewers don’t support this.
- Refer to Section 7.2 for a description of how the TurboVNC Server responds to requests for Compression Levels 0-9.

## 10.3 RealVNC

The TurboVNC Viewer supports the Hextile and Raw encoding types, which are compatible with RealVNC. The Java/Mac TurboVNC Viewer additionally supports ZRLE and RRE. None of these encoding types can be selected from the TurboVNC Viewer GUI, but Hextile or ZRLE 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. Non-Tight encoding types, such as Hextile and Raw, can also be manually selected from the `vncviewer` command line. In addition to Hextile, Raw, ZRLE, and RRE, the TurboVNC Server also supports the CoRRE and Zlib legacy encoding types, for compatibility with older VNC viewers.

All of the non-Tight encoding types have performance drawbacks. Raw encoding requires gigabit in order to achieve decent performance, and it can easily take up an entire gigabit connection’s worth of bandwidth. Hextile uses very small tiles, which causes it to incur a large amount of computational overhead. It compresses too poorly to perform well on slow links but uses too much CPU time to perform well on fast links. ZRLE improves upon this, but it is still too computationally intense for fast networks.

# 11 Advanced Configuration

## 11.1 Server Settings

Environment Variable | `TVNC_ALRALL =` `0 | 1`
Summary | Disable/Enable automatic lossless refresh for regions that were drawn using methods other than `X[Shm]PutImage()`
Default Value | Disabled

Description
  See Section 7.4

Environment Variable | `TVNC_COMBINERECT =` `{c}`
Summary | Combine framebuffer updates with more than `{c}` rectangles into a single rectangle spanning the bounding box of all of the constituent rectangles
Default Value | 100

Description
  Applications can sometimes draw many thousands of points or tiny lines using individual X11 calls, and this can cause the VNC server to send many thousands of tiny rectangles to the VNC viewer. The overhead associated with this can bog down the viewer, and in extreme cases, the number of rectangles may even exceed the maximum number that is allowed in a single framebuffer update (65534.) Thus, if a framebuffer update contains more than `{c}` rectangles, TurboVNC will coalesce it into a single rectangle that covers all of the rectangles in the update. For applications that generate many tiny rectangles, increasing `TVNC_COMBINERECT` may significantly increase the number of pixels sent to the viewer, which will increase network usage. However, for those same applications, lowering `TVNC_COMBINERECT` will increase the number of rectangles sent to the viewer, which will increase the CPU usage of both the server and the viewer.

Environment Variable | `TVNC_IFDEBUG =` `0 | 1`
Summary | Disable/Enable the ICE debugger
Default Value | Disabled

Description
  If interframe comparison is enabled (see Section 7.1), then setting this environment variable to 1 will cause the interframe comparison engine (ICE) to change the color of duplicate updates without culling them from the update stream. This allows you to easily see which applications are generating duplicate updates.

Environment Variable | `TVNC_MT =` `0 | 1`
Summary | Disable/Enable multithreaded image encoding
Default Value | Disabled

Description
  See Section 7.5

Environment Variable | `VGL_NTHREADS =` `{n}`
Summary | Use `{n}` threads to perform image encoding
Default Value | `{n}` = the number of CPU cores in the system

Description
  See Section 7.5

Environment Variable | `TVNC_PROFILE =` `0 | 1`
Summary | Disable/enable profiling output
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.

## 11.2 Client Settings

Environment Variable | `TVNC_PROFILE =` `0 | 1`
Summary | Disable/enable profiling output
Platforms | X11
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.