Date: 2024-11-19T14:57:09

User’s Guide for TurboVNC 3.1.4

- 1 Legal Information
- 2 Conventions Used in This Document
  - 2.1 Terminology
- 3 Overview
- 4 System Requirements
  - 4.1 Linux and Other Un*x Operating Systems
  - 4.2 Mac
  - 4.3 Windows
- 5 Obtaining and Installing TurboVNC
  - 5.1 Installing TurboVNC on Linux
  - 5.2 Installing the TurboVNC Viewer on macOS
  - 5.3 Installing the TurboVNC Viewer on Windows
  - 5.4 Installing TurboVNC from Source
  - 5.5 Uninstalling TurboVNC
- 6 Using TurboVNC
  - 6.1 The TurboVNC Session Manager
  - 6.2 Manually Starting a TurboVNC Session
  - 6.3 Manually Connecting to a VNC Server
  - 6.4 Disconnecting and Killing a TurboVNC Session
  - 6.5 Using TurboVNC in a Web Browser
  - 6.6 Using SSH to Manually Secure a TurboVNC Connection
  - 6.7 Requiring SSH Tunneling
  - 6.8 Running OpenGL Applications
  - 6.9 Window Manager Compatibility
  - 6.10 Further Reading
- 7 Performance and Image Quality
  - 7.1 Interframe Comparison
  - 7.2 Advanced Compression Options
  - 7.3 Lossless Refresh
  - 7.4 Automatic Lossless Refresh
  - 7.5 Multithreading
- 8 TurboVNC Security Extensions
  - 8.1 Terminology
  - 8.2 TurboVNC Server Authentication Methods
  - 8.3 TurboVNC Viewer Authentication Schemes
  - 8.4 Supported Encryption Methods
  - 8.5 Supported Security Types
  - 8.6 Enabling Security Types
  - 8.7 Further Reading
- 9 GPU-Accelerated OpenGL (Using VirtualGL with TurboVNC)
  - 9.1 Using VirtualGL on a TurboVNC Host
  - 9.2 Using VirtualGL on a Machine Other Than a TurboVNC Host
  - 9.3 NV-CONTROL Emulation
- 10 Compatibility Guide
  - 10.1 TightVNC or TigerVNC Servers
  - 10.2 TightVNC or TigerVNC Viewers
  - 10.3 RealVNC
- 11 Advanced Configuration
  - 11.1 Server Settings
  - 11.2 Viewer Settings

# 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 TurboVNC web site.

The official TurboVNC binaries contain libjpeg-turbo, which is based in part on the work of the Independent JPEG Group.

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 Linux/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.

## 2.1 Terminology

VNC server (sometimes just “server”)
  A computer program, implementing the Remote Framebuffer (RFB) protocol and usually designed to run as a background process, that provides an interactive remote desktop environment through which authenticated users can run graphical programs remotely from other computers on the network. VNC servers can be implemented as single-user screen scrapers, which transmit the contents of the host’s physical display (most common with Windows and Mac VNC servers), or as virtual display servers, which provide isolated remote desktop environments for an arbitrary number of simultaneous users on the same host (most common with Un*x VNC servers.)
VNC host (sometimes just “host”)
  The machine on which a VNC server is running
VNC viewer (sometimes just “viewer”)
  A computer program, implementing the Remote Framebuffer (RFB) protocol, that connects to a VNC server running on another computer, thus allowing users to run graphical programs remotely.
client machine (sometimes just “client”)
  The machine on which a VNC viewer is running
VNC session (sometimes just “session”)
  A specific instance of a Un*x VNC server (Xvnc.) Each instance of an Xvnc server, including the TurboVNC Server, acts as an independent virtual X server, listening on a unique X11 display number for connections from X11 clients and listening on a unique TCP port number or Unix domain socket for connections from VNC viewers. Multiple simultaneous VNC sessions can exist on a given host, under any number of different user accounts.

# 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 a fork of TightVNC 1.3.x. However, the current version of TurboVNC contains a modern X server code base (based on X.org) and a variety of other notable features and fixes relative to TightVNC 1.3.x, including a high-performance cross-platform VNC viewer with session management capabilities, as well as some unique features designed specifically for visualization applications. Some of those features are not available in any other open source Linux/Un*x remote display solutions. 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, a SIMD-accelerated JPEG codec. 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 RFB session captures that simulate real-world application workloads, both 2D and 3D. TurboVNC’s encoding methods have been adopted by TigerVNC, LibVNC, UltraVNC, and other projects.

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 and Other Un*x Operating Systems

| Host | Client (Linux) | Client (non-Linux)
--- | --- | --- | ---
CPU | x86-64 or AArch64 required At least two processors or cores recommended | x86-64 or AArch64 required
O/S | TurboVNC should work with a variety of Linux distributions, FreeBSD, and Solaris 11, but currently-supported versions of Red Hat Enterprise Linux and its derivatives, Ubuntu LTS, and SUSE Linux Enterprise tend to receive the most attention from the TurboVNC community.
Other | SSH server (if using the TurboVNC Session Manager) | For optimal performance, the X server should be configured to export True Color (24-bit or 32-bit) visuals. | For optimal performance, the X server should be configured to export True Color (24-bit or 32-bit) visuals. Oracle Java or OpenJDK

## 4.2 Mac

| Client
--- | ---
CPU | 64-bit Intel or Apple silicon required
O/S | macOS 10.12 “Sierra” or later (Intel); macOS 11 “Big Sur” or later (Apple silicon)

## 4.3 Windows

| Client
--- | ---
CPU | For optimal performance, the CPU should support SSE2 extensions.
O/S | Windows 7 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

### Installing TurboVNC

1. Download the appropriate TurboVNC binary package for your system from the Releases area of the TurboVNC GitHub project page. RPM and Debian packages are provided for Linux distributions that contain GLIBC 2.17 or later.
2. `cd` to the directory where you downloaded the binary package, and issue one of the following commands as root:
   RPM-based systems using YUM

         yum install turbovnc*.rpm

   RPM-based systems using DNF

         dnf install turbovnc*.rpm

   RPM-based systems using YaST2

         yast2 --install turbovnc*.rpm

   Other RPM-based systems (dependencies will not be installed automatically)

         rpm -U turbovnc*.rpm

   Debian-based systems

         dpkg -i turbovnc*.deb
         apt install -f

### Installing TurboVNC for a Single User

Download the appropriate binary package, as above, then execute the following commands:

RPM-based systems

      mkdir ~/turbovnc
      cd ~/turbovnc
      rpm2cpio full/path/of/turbovnc*.rpm | cpio -idv

Debian-based systems

      dpkg-deb –extract full/path/of/turbovnc*.deb ~/turbovnc

Add ~/turbovnc to any paths specified in this document.

If using the TurboVNC Session Manager, set the `turbovnc.serverdir` Java system property in the TurboVNC Viewer to `~/turbovnc/opt/TurboVNC`, or set the `TVNC_SERVERDIR` environment variable on the client machine to `\~/turbovnc/opt/TurboVNC` (note backslash.) Refer to Section 11.2.

The TurboVNC security configuration file will not work when TurboVNC is installed in this manner.

## 5.2 Installing the TurboVNC Viewer on macOS

1. Download the TurboVNC Mac disk image (TurboVNC-3.1.4-x86_64.dmg for Intel CPUs or TurboVNC-3.1.4-arm64.dmg for Apple silicon CPUs) from the Releases area of the TurboVNC GitHub 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-3.1.4-x64.exe for 64-bit systems or TurboVNC-3.1.4-x86.exe for legacy 32-bit-only systems) from the Releases area of the TurboVNC GitHub 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 Linux/Un*x platform for which there is not a pre-built TurboVNC binary package available, then download the TurboVNC source tarball (turbovnc-3.1.4.tar.gz) from the Releases area of the TurboVNC GitHub project page, uncompress it, `cd turbovnc-3.1.4`, and read BUILDING.md 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

### macOS

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 Apps & Features applet if you are running Windows 10), or select Uninstall TurboVNC in the TurboVNC Start Menu group.

# 6 Using TurboVNC

## 6.1 The TurboVNC Session Manager

The TurboVNC Viewer, like any VNC viewer, can be used to connect to any VNC server. However, the TurboVNC Viewer also includes the TurboVNC Session Manager, which can be used with the TurboVNC Server to remotely start or kill a TurboVNC session, list all TurboVNC sessions running under a particular user account on a particular host, and choose a TurboVNC session to which to connect. The TurboVNC Session Manager uses the TurboVNC Viewer’s built-in SSH client, which supports OpenSSH config files and password-less public key authentication (using ssh-agent or Pageant.)

### Procedure

- On the client machine, start the TurboVNC Viewer.
  Linux/Un*x clients
    Open a new terminal/xterm and type

        /opt/TurboVNC/bin/vncviewer

  Mac clients
    Open the TurboVNC Viewer application, located in the TurboVNC Applications folder, or open a new terminal and type

        /opt/TurboVNC/bin/vncviewer

  Windows clients
    Select TurboVNC Viewer in the TurboVNC Start Menu group, or open a new command prompt and type

        c:\Program Files\TurboVNC\vncviewer.bat

- A small dialog box will appear.
  Enter the hostname or IP address of the TurboVNC host in the “VNC server” field, then click “Connect”.
- The TurboVNC Session Manager will connect to the host using SSH, and it will prompt for an SSH private key passphrase or an SSH password, if necessary. (The TurboVNC Viewer’s built-in SSH client will first try to fetch the private key passphrase from ssh-agent or Pageant, if either is running.)

  You can specify the SSH username, if it differs from your local username, by prefixing the hostname/IP address with `user@`, where `user` is the SSH username.

- If no TurboVNC sessions are currently running under your user account on the TurboVNC host, then the session manager will:
  - start a new session
  - generate a new one-time password (OTP) for the session
  - automatically configure the TurboVNC Viewer so that it tunnels the VNC connection through SSH (reusing the SSH channel that the session manager already opened) and authenticates using the newly-generated OTP
  - connect to the session
  Once connected, 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 host.
- If one or more TurboVNC sessions are currently running under your user account on the TurboVNC host, then the session manager will enumerate the sessions and display a dialog similar to the following, allowing you to manage the sessions remotely, to start a new session, or to choose a session to which to connect:
  Upon choosing a session to which to connect, the session manager will (as described above) automatically generate a new OTP for the session and configure the TurboVNC Viewer so that it tunnels the VNC connection through SSH and authenticates using the newly-generated OTP.
  One-time passwords can be used with any VNC viewer, so generating a new OTP for a TurboVNC session (using the “New OTP” button) is a convenient way of allowing colleagues to temporarily access the session. Generating a new OTP for a TurboVNC session is also useful when using noVNC. If “View-only” is checked, then users who authenticate using the new OTP will not be able to remotely control the session.

  The TurboVNC Session Manager automatically uses SSH tunneling and OTP authentication by default, but you can set the TurboVNC Viewer’s `NoSessMgrAuto` parameter to disable this behavior, thus allowing any authentication/encryption method to be used. Additional parameters can be used to specify the port on which the SSH server is listening and the location of the SSH private key file. The OpenSSH config file (~/.ssh/config by default) can also be used to specify those parameters persistently for a given host.

  The `TVNC_SERVERDIR` and `TVNC_SERVERARGS` environment variables, and their equivalent Java system properties (`turbovnc.serverdir` and `turbovnc.serverargs`) can be used to specify a non-default installation path for the TurboVNC Server or additional arguments to pass to the TurboVNC Server when starting new sessions. (Refer to Section 11.2.) TurboVNC Server arguments can also be specified on the host using the system-wide or per-user turbovncserver.conf file.

## 6.2 Manually Starting 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 host:

       ssh user@host

   Replace `user` with your username on the TurboVNC host and `host` with the hostname or IP address of the host.
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_host:1 (my_user)' started on display my_host: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.3 Manually Connecting to a VNC Server

### Procedure

1. On the client machine, start the TurboVNC Viewer.
   Linux/Un*x clients
     Open a new terminal/xterm and type

         /opt/TurboVNC/bin/vncviewer

   Mac clients
     Open the TurboVNC Viewer application, located in the TurboVNC Applications folder, or open a new terminal and type

         /opt/TurboVNC/bin/vncviewer

   Windows clients
     Select TurboVNC Viewer in the TurboVNC Start Menu group, or open a new command prompt and type

         c:\Program Files\TurboVNC\vncviewer.bat

2. A small dialog box will appear.
   Enter the X display name (hostname, or IP address, and display number) of the VNC server or TurboVNC session in the “VNC server” field, then click “Connect”.
3. 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.)

   Standard VNC Authentication Dialog |
   Unix Login Authentication Dialog |

   Enter the VNC server password or the Unix username/password and press Enter.
   A VNC desktop window should appear on your client machine. This window contains a virtual desktop with which you can interact to launch graphical applications on the VNC host.

   If you are connecting to a non-VeNCrypt-compatible VNC server, then the authentication dialog will warn you that the connection is not encrypted:
   You should never use Unix Login authentication with an unencrypted connection. Instead, tunnel the connection through SSH. (See Section 6.6 below for more details.)

## 6.4 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 host (as will any applications that you may have started within the session), and you can reconnect to the session at any time.

If the TurboVNC session was created with default settings, then the easiest way to kill it is to log out of the window manager running in the session. You can also use the TurboVNC Session Manager to remotely kill TurboVNC sessions, or you can type the following command:

    /opt/TurboVNC/bin/vncserver -kill :n

from a terminal in the TurboVNC session or from an SSH session on the host. 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 host, type the following command:

    /opt/TurboVNC/bin/vncserver -list

from a terminal in the TurboVNC session or from an SSH session on the host.

## 6.5 Using TurboVNC in a Web Browser

When a TurboVNC session is started, the `vncserver` script can optionally start a simple web server that serves up noVNC, an HTML 5/JavaScript VNC viewer that works in any web browser (with reduced performance and features relative to the TurboVNC Viewer.) This allows you to easily connect to a TurboVNC session from a machine that does not have the TurboVNC Viewer installed (including mobile devices.)

To launch noVNC along with a TurboVNC session, pass `-novnc dir` to `vncserver` when starting the session, where `dir` is the directory containing noVNC. (Setting the `$noVNC` variable in turbovncserver.conf has the same effect.) The `vncserver` script will print the noVNC URL, which will be of the form:

    http://host:5800+n/vnc.html?host=host&port=5900+n

or

    https://host:5800+n/vnc.html?host=host&port=5900+n&encrypt=1

where `host` is the hostname or IP address of the TurboVNC host and `n` is the X display number of the TurboVNC session.

Point your web browser to that URL in order to access the TurboVNC session. You can optionally pass `-x509cert certificate-file -x509key private-key-file` to `vncserver` (or set the `$x509CertFile` and `$x509KeyFile` variables in turbovncserver.conf) to encrypt both the HTTP and RFB connections. See the `vncserver` man page for more details.

NOTE: noVNC only supports VNC Password authentication, so it is strongly recommended that it be used only with one-time passwords unless the connections are encrypted.

## 6.6 Using SSH to Manually Secure a TurboVNC Connection

If the TurboVNC Session Manager is not being used, then the connection between the TurboVNC Server and the TurboVNC Viewer will, by default, use Anonymous TLS encryption. (Refer to Chapter 8.) However, it may be preferable to secure the TurboVNC connection using SSH rather than Anonymous TLS encryption, particularly if one does not want to open additional ports in the host’s firewall. This can easily be accomplished using the TurboVNC Viewer’s `Via` and `Tunnel` parameters (or the equivalent GUI options, which are located under the “Security” tab in the TurboVNC Viewer Options dialog.)

The TurboVNC Viewer’s `Via` and `Tunnel` parameters take advantage of the port forwarding feature in SSH. For instance, running

    vncviewer -via user@host localhost:n

or

    vncviewer -tunnel user@host:n

is the equivalent of running

    ssh -L fp:localhost:5900+n user@host
    vncviewer localhost::fp

where `fp` is a free TCP port on the client machine (this is automatically determined by the TurboVNC Viewer.)

In the above examples, `vncviewer` is the command used to launch the TurboVNC Viewer– `/opt/TurboVNC/bin/vncviewer` on Linux/Un*x and Mac systems and `c:\Program Files\TurboVNC\vncviewer.bat` on Windows systems.

The `Tunnel` parameter can be used as a shortcut whenever the SSH and VNC hosts 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.

## 6.7 Requiring SSH Tunneling

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

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

If the host is configured such that it only allows SSH connections, then disallowing the TLS* security types on a system-wide basis (by setting the `permitted-security-types` directive in the TurboVNC security configuration file) is recommended. Otherwise, when using the TurboVNC Viewer with default settings, the connection will have redundant encryption.

Note that only the OTP security type is needed when using the TurboVNC Session Manager with its default settings.

## 6.8 Running OpenGL Applications

The TurboVNC Server includes a software GLX/OpenGL implementation that can be used for casual 3D rendering. This implementation uses the swrast DRI driver provided by Mesa 8.x and later, and it supports only direct rendering. Thus, it can only be used on systems that do not have vendor-specific GPU drivers installed or on systems that provide a libglvnd-enabled build of Mesa. In general, if the TurboVNC host has a GPU, then you should use VirtualGL rather than relying on TurboVNC’s software OpenGL implementation.

Passing `-extension GLX` to `vncserver` disables the built-in GLX/OpenGL implementation, thus restoring the behavior of TurboVNC 2.1.x and earlier (which required VirtualGL in order to run OpenGL applications.) If the built-in GLX/OpenGL implementation is not functioning properly, then pass `-verbose` to `vncserver` to log informational messages that may reveal the source of the problem.

## 6.9 Window Manager Compatibility

This version of the TurboVNC Server can run 3D (compositing) window managers, such as Unity or GNOME 3+ or KDE 5+, using its built-in software OpenGL implementation. It also provides a command-line option (`-vgl`) and a turbovncserver.conf variable (`$useVGL`) that allow for running 3D window managers using VirtualGL. However, for performance reasons, it is generally recommended that you use a 2D (non-compositing) window manager with the TurboVNC Server. (Even with VirtualGL, 3D window managers have a lot of overhead.) As of this writing, Ubuntu, RHEL 7+, and Fedora provide an optional 2D window manager called “GNOME Fallback”, “GNOME Flashback”, or “GNOME Classic”, which will be used if it is installed and the TurboVNC window manager is set to `2d` (by passing `-wm 2d` to `vncserver` or setting `$wm = "2d";` in turbovncserver.conf.) For other systems that lack a 2D window manager, it is recommended that you install MATE or Xfce. Refer to this report for an up-to-date list of window managers that have been tested with this version of the TurboVNC Server, how to configure the TurboVNC Server to use those window managers, and a list of known compatibility issues.

## 6.10 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
      man -M /opt/TurboVNC/man tvncconfig

TurboVNC Viewer
  Run

      /opt/TurboVNC/bin/vncviewer -?

  on Linux/Un*x and Mac systems or

      c:\Program Files\TurboVNC\vncviewer.bat -?

  on Windows systems 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 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.
Compression level
  In TurboVNC, the compression level specifies:
  1. the level of zlib compression that will be used with indexed color, mono, and raw subrectangles
  2. the “palette threshold” (the minimum number of colors that a subrectangle must have before it is encoded as JPEG or raw instead of indexed color)
  3. whether or not interframe comparison should be used
  See Section 7.2 below for more details.

These parameters can be adjusted by accessing the TurboVNC Viewer Options dialog box. (Click on the “Options” button in the New TurboVNC Connection dialog box or, after connecting to the server, click on the Connection Options button in the toolbar.)

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 | 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 | 6 | 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. Interframe comparison is enabled with this encoding method. (Compression Level 6 = Compression Level 1 + interframe comparison.)
“Tight + Low-Quality JPEG” | Yes | 30 | 4x | 7 | 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. In addition to reducing the JPEG quality to a “minimum usable” level, this encoding method also enables interframe comparison and Compression Level 2. (CL 7 = CL 2 + interframe comparison.) Compression Level 2 can reduce network usage for low-color application workloads that are not good candidates for JPEG compression.
“Lossless Tight” | No | N/A | N/A | 0 | 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 | 6 | 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. Interframe comparison is enabled with this encoding method. (Compression Level 6 = Compression Level 1 + interframe comparison.)

The encoding method can be set in the TurboVNC Viewer Options dialog box. (Click on the “Options” button in the New TurboVNC Connection dialog box or, after connecting to the server, click on the Connection Options button in the toolbar.)

## 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. Additionally, modern GUI toolkits often use image-based drawing methods (the X Rendering Extension, for instance), which can result in an entire window being redrawn even if only a few pixels in the window have changed. The TurboVNC Server can guard against this by maintaining a copy of the remote framebuffer for each connected viewer, comparing each new framebuffer update rectangle against the pixels in the framebuffer copy, and discarding any redundant portions of the rectangle before they are sent to the viewer.

Interframe comparison has some tradeoffs. Perhaps the most important of these is that it increases the memory usage of the TurboVNC Server by a factor of N, where N is the number of connected viewers. This can prove to be quite significant if the remote desktop size is relatively large. 2D applications are most often the ones that generate duplicate framebuffer updates, so using interframe comparison with such applications can significantly reduce the network usage and the host CPU usage (since fewer rectangles are actually being encoded.) However, with 3D applications, the benefits of interframe comparison are less clear, since it is less common for those applications to generate duplicate framebuffer updates. Interframe comparison may benefit certain classes of 3D applications, such as design applications that render a model against a static background– particularly when the model is not zoomed in enough to fill the entire window. In real-world tests, however, interframe comparison rarely reduces the network usage for 3D applications by more than 5-10%. Furthermore, with games and other immersive applications that modify most of the pixels on the screen each time a frame is rendered, interframe comparison can actually increase both CPU usage and network usage. Furthermore, the effects of duplicate framebuffer updates are not typically noticeable on high-speed networks, but an increase in host CPU usage might be.

For these reasons, interframe comparison is not enabled by default and should not generally be enabled except on bandwidth-constrained networks and with applications for which it can be shown to be beneficial. Interframe comparison can be enabled by passing an argument of `-interframe` to `vncserver` when starting a TurboVNC session, by using `tvncconfig` to set the `Interframe` parameter for a running TurboVNC 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 have proven to be useful (that is, the options that have proven to have good performance tradeoffs.) Thus, the TurboVNC Viewer Options dialog normally only allows you to select Compression Levels 1-2 if JPEG subencoding is enabled (6-7 if interframe comparison is also enabled) or Compression Levels 0-1 if JPEG subencoding is disabled (5-6 if interframe comparison is enabled.) Other compression levels can, however, be specified using the TurboVNC Viewer’s `CompressLevel` parameter, and doing so will enable a compatibility mode in the TurboVNC Viewer Options dialog that allows any compression level from 0 to 9 to be requested.

When connected to a TurboVNC session, 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. Furthermore, 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 can increase the CPU usage for some 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 applications (and has no noticeable benefit for 3D and video applications.) 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 applications (and has no noticeable benefit for 3D and video applications.) 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 VNC server will send a mathematically lossless image of the remote desktop to the requesting viewer. A user could, for instance, use the “Tight + Low-Quality JPEG” encoding method on a low-bandwidth network to improve the performance of rotating/panning/zooming an object in a 3D application, then the user could request a lossless refresh when they are ready to interpret or analyze the object.

To perform a lossless refresh, press CTRL-ALT-SHIFT-L or click on the Lossless Refresh toolbar icon.

## 7.4 Automatic Lossless Refresh

Passing an argument of `-alr timeout` to `vncserver` (or using `tvncconfig` to set the `ALR` parameter for a running TurboVNC session) enables the Automatic Lossless Refresh (ALR) feature for the TurboVNC session. ALR monitors 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 sends that viewer a mathematically lossless copy of any “ALR-eligible” screen regions that have been affected by lossy compression. You can also pass arguments of `-alrqual` and `-alrsamp` to `vncserver` (or use `tvncconfig` to set the `ALRQual` and `ALRSamp` parameters for a running TurboVNC session) 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 3D scene is rotated/panned/zoomed, but when the motion stops, a fully lossless copy of the 3D image is sent and can be studied in detail.

The default is for any regions drawn with `X[Shm]PutImage()` to be ALR-eligible– as well as any regions drawn with CopyRect, if the source of the CopyRect operation was affected by lossy compression. (CopyRect is an RFB encoding that allows the VNC server to request that a VNC viewer move a rectangle of pixels from one location to another.) When used with VirtualGL, this means that ALRs will mainly just be sent for the OpenGL-rendered regions of the remote desktop. That should be fine for most 3D applications, since the OpenGL-rendered regions are the ones that are quality-critical. The default ALR behavior also prevents what might best be called the “blinking cursor dilemma.” 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 frequent updates prevent an ALR from ever being sent. Fortunately, blinking cursors are not typically drawn using `X[Shm]PutImage()`, so the problem is effectively worked around by limiting the ALR-eligible regions to just the subset of regions that were drawn using `X[Shm]PutImage()` and CopyRect.

NOTE: Ill-behaved applications that continuously render the same image will cause a variation of the “blinking cursor dilemma” and thus defeat ALR unless interframe comparison is enabled.

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 host prior to starting a TurboVNC session or by using `tvncconfig` to set the `ALRAll` parameter for a running TurboVNC session.

## 7.5 Multithreading

By default, the TurboVNC Server uses 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 enabling multithreading in the server will not help. Multithreading is also not currently implemented with non-Tight encoding types.

To disable server-side multithreading, set the `TVNC_MT` environment variable to `0` on the host prior to starting `vncserver`, or pass an argument of `-nomt` to `vncserver`. The default behavior is to use as many threads as there are cores on the TurboVNC host (up to a maximum of 4), but you can set the `TVNC_NTHREADS` environment variable or pass an argument of `-nthreads` to `vncserver` to override this.

# 8 TurboVNC Security Extensions

## 8.1 Terminology

In an attempt to be consistent with other VNC implementations, TurboVNC uses the following terminology when referring to its security extensions:

Authentication Method
  A technique that the VNC server uses to validate authentication credentials sent from a VNC viewer. If the credentials sent from a particular VNC viewer are not valid, then that viewer is not allowed to connect.
Authentication Scheme
  A protocol used to send authentication credentials from a VNC viewer to a VNC server for validation. Some authentication schemes are required by the RFB protocol specification, and others are implemented as extensions to that specification.
Encryption Method
  A technique used to encrypt the data sent between the VNC server and the VNC viewer
Security Type
  A specific combination of an authentication method, an authentication scheme, and an encryption method

## 8.2 TurboVNC Server Authentication Methods

No Authentication
  The VNC server does not authenticate the VNC viewer at all.
VNC Password Authentication
  A session password sent from the VNC viewer is validated against a password file, which is typically located under the user’s home directory on the VNC host. The VNC password 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 user’s account password are not the same.)
One-Time Password (OTP) Authentication
  Using the `vncpasswd` program, a unique password is generated “on the fly” for the TurboVNC session, and the password is printed on the command line. (See the `vncpasswd` man page for more details.) The user enters this password into the VNC viewer, and the VNC viewer sends the password to the server as if it were a VNC password. However, once the OTP has been used to authenticate a viewer, the OTP 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. The TurboVNC Session Manager uses OTP authentication by default, which allows it to securely authenticate with a TurboVNC session without prompting for additional credentials.
PAM User/Password Authentication
  The VNC server uses Pluggable Authentication Modules (PAM) to validate a username and password received from a VNC viewer. The password received from the VNC viewer need not necessarily be validated against the user’s account password. Generally, the TurboVNC Server can validate the username and password using any authentication credentials that can be accessed through PAM. Since the user/password authentication schemes supported by TurboVNC (see below) transmit the password from the VNC viewer to the VNC server as plain text, it is strongly recommended that the PAM User/Password authentication method be used only with session encryption or if the session is restricted to allow only loopback (SSH) connections and to disallow reverse connections (see Section 6.6.)

## 8.3 TurboVNC Viewer Authentication Schemes

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 1990s.)
Unix Login/Plain Authentication
  Both the username and password are sent to the VNC server as plain text. Thus, it is strongly recommended that this authentication scheme be used only with VNC connections that are encrypted using TLS (see below) or SSH (see Section 6.6.) Per the RFB spec, this authentication scheme is referred to as “Unix Login” when used with a TightVNC-compatible server and “Plain” when used with a VeNCrypt-compatible server.

## 8.4 Supported Encryption Methods

TurboVNC supports three encryption methods:

None
  No encryption
Anonymous TLS Encryption
  The connection is encrypted using TLS (Transport Layer Security) without authentication (i.e. without a certificate.)
TLS/X.509 Encryption
  The connection is encrypted using TLS with a specified X.509 certificate.

## 8.5 Supported Security Types

TurboVNC supports the following security types:

Server Security Type | Authentication Method | Encryption Method | Viewer Security Type | Authentication Scheme | Compatibility
--- | --- | --- | --- | --- | ---
None | None | None | None | None | RFB 3.3+
VNC | VNC Password | None | VNC | Standard VNC | RFB 3.3+
OTP | One-Time Password | None
Plain | PAM User/Password | None | Plain | Plain | RFB 3.7+ with VeNCrypt extensions
TLSNone | None | Anonymous TLS | TLSNone | None | RFB 3.7+ with VeNCrypt extensions
TLSVnc | VNC Password | Anonymous TLS | TLSVnc | Standard VNC | RFB 3.7+ with VeNCrypt extensions
TLSOtp | One-Time Password | Anonymous TLS
TLSPlain | PAM User/Password | Anonymous TLS | TLSPlain | Plain | RFB 3.7+ with VeNCrypt extensions
X509None | None | TLS/X.509 | X509None | None | RFB 3.7+ with VeNCrypt extensions
X509Vnc | VNC Password | TLS/X.509 | X509Vnc | Standard VNC | RFB 3.7+ with VeNCrypt extensions
X509Otp | One-Time Password | TLS/X.509
X509Plain | PAM User/Password | TLS/X.509 | X509Plain | Plain | RFB 3.7+ with VeNCrypt extensions
UnixLogin | PAM User/Password | None | UnixLogin | Unix Login | RFB 3.7+ with TightVNC extensions

NOTE: The security type names are case-insensitive. The capitalization conventions above are used for consistency with the RFB protocol specification.

## 8.6 Enabling Security Types

The default behavior of the TurboVNC Server is for all security types except TLSNone, X509None, and None to be enabled and for VNC Password and OTP authentication to be preferred over PAM User/Password authentication. However, the system administrator can disable one or more of the security types or change their preferred order by editing the TurboVNC security configuration file. See the `Xvnc` man page for more details. Note that only the OTP security type is needed when using the TurboVNC Session Manager with its default settings.

If the VNC server allows multiple security types, then the TurboVNC Viewer’s default security type will be determined by the server’s preferred security type. In this case, the user can override the default by using the TurboVNC Viewer’s `SecurityTypes`, `User`, and `NoUnixLogin` parameters. If the VNC server prefers a security type that supports Standard VNC authentication, then the user can force the use of Unix Login/Plain authentication by setting the TurboVNC Viewer’s `User` parameter to `user-name` when connecting to the VNC server. Similarly, if the VNC server prefers a security type that supports Unix Login/Plain authentication, then the user can force the use of Standard VNC authentication by setting the `NoUnixLogin` parameter. The same thing can also be accomplished by unchecking specific security types in the “Security” tab of the TurboVNC Viewer Options dialog or by using the `SecurityTypes` parameter to limit the available security types or change their preferred order.

If the system administrator has not restricted any of the server security types on a system-wide basis, then the user can disable some of them, or change their preferred order, for a particular TurboVNC session by using the `-securitytypes` command-line argument when starting the session (or by setting the `$securityTypes` variable in turbovncserver.conf.) See the `Xvnc` man page for more details.

## 8.7 Further Reading

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

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

# 9 GPU-Accelerated OpenGL (Using VirtualGL with TurboVNC)

Referring to the VirtualGL User’s Guide, VirtualGL’s X11 Transport draws OpenGL-rendered frames to an X display using standard X11 drawing commands. Since this results in the frames 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 applications (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 sends rendered frames to the X proxy at a very fast rate, the X proxy must be able to compress the frames very quickly in order to keep up. When VirtualGL was first released, most X proxies couldn’t. They simply weren’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 frames from VirtualGL to a client machine without using VirtualGL’s built-in VGL Transport.

### Advantages of TurboVNC (when compared to the VGL Transport)

- When using the VGL Transport, non-OpenGL elements of the 3D application’s GUI are sent over the network using remote X11, which does not perform well on high-latency networks such as broadband or long-haul fibre. On such networks, non-OpenGL elements of the 3D application’s GUI will load and render much faster (perhaps even orders of magnitude faster) with TurboVNC than with the VGL Transport.
- For 3D applications whose rendered frames do not contain very many unique colors (for instance, CAD applications in wireframe mode), the hybrid encoding methods used by TurboVNC generally require 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 host 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 host CPU usage.) The VGL Transport’s only lossless option is uncompressed RGB.
- TurboVNC includes a Lossless Refresh feature that will, automatically (during periods of inactivity) or on demand, send a mathematically lossless copy of remote desktop regions that were previously sent using lossy compression. Refer to Sections 7.3 and Section 7.4.
- TurboVNC provides rudimentary collaboration capabilities. Multiple users can simultaneously view the same TurboVNC session and pass around control of the keyboard and mouse.
- From the point of view of the 3D application, the TurboVNC session is stateless. If the network hiccups or the viewer is otherwise disconnected, then the TurboVNC session continues to run on the host 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 machine with a web browser, and any mobile device, can be used as a TurboVNC client (with reduced performance and features relative to the TurboVNC Viewer.) Refer to Section 6.5.

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

- No seamless windows. All application windows are constrained to a virtual desktop, which is displayed in a single window on the client machine.
- TurboVNC generally requires about 20% more host 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.

## 9.1 Using VirtualGL on a TurboVNC Host

The most common (and optimal) way to use VirtualGL with TurboVNC is to configure the same machine as a TurboVNC host and a VirtualGL server. This allows VirtualGL to send rendered frames to TurboVNC through shared memory rather than 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 remote desktop.
3. In the terminal, start a 3D application using VirtualGL:

       /opt/VirtualGL/bin/vglrun [vglrun options] 3D-application-executable-or-script [arguments]

## 9.2 Using VirtualGL on a Machine Other Than a TurboVNC Host

If the TurboVNC host and VirtualGL server are different machines, then it is desirable to use the VGL Transport to send rendered frames from the VirtualGL server to the TurboVNC session. 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 host 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 remote desktop.
3. In the same terminal window, open a Secure Shell (SSH) session into the VirtualGL server:

       /opt/VirtualGL/bin/vglconnect [vglconnect options] 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 result.

5. In the SSH session, start a 3D application using VirtualGL:

       /opt/VirtualGL/bin/vglrun [vglrun options] 3D-application-executable-or-script [arguments]

## 9.3 NV-CONTROL Emulation

This version of TurboVNC includes partial emulation of the `NV-CONTROL` X11 extension provided by nVidia’s proprietary Un*x drivers. Certain 3D applications rely on this extension to query and set low-level GPU properties, and unfortunately the library (libXNVCtrl) used by applications to interact with the extension is static, making it impossible to interpose using VirtualGL.

Passing an argument of `-nvcontrol display` to `vncserver` causes the TurboVNC Server to create a fake `NV-CONTROL` extension in the TurboVNC session and redirect all `NV-CONTROL` requests to `display`. `display` should be the X display/screen of the 3D X server you plan to use with VirtualGL (`:0.0`, for instance.) The TurboVNC Server does not attempt to open a connection to this display until an application uses the `NV-CONTROL` extension. If a connection to the 3D X server cannot be opened, if the 3D X server does not have the `NV-CONTROL` extension, or if other issues are encountered when attempting to redirect `NV-CONTROL` requests, then an X11 BadRequest error will be returned to the application, and the TurboVNC session log will display an error message explaining why the request failed. It is assumed that you have already followed the procedure in the VirtualGL User’s Guide to allow access to the 3D X server. If access to the 3D X server is restricted to members of the `vglusers` group, then you may need to execute

    xauth merge /etc/opt/VirtualGL/vgl_xauth_key

in order to use the `NV-CONTROL` extension prior to invoking `vglrun` for the first time.

You can change the 3D X server for a particular TurboVNC session after the session has been started. For instance, if you wanted to redirect both `NV-CONTROL` requests and OpenGL to a GPU attached to Screen 1 of Display :0, then you could execute

    xprop -root -f VNC_NVCDISPLAY 8s -set VNC_NVCDISPLAY :0.1
    vglrun -d :0.1 3D-application-executable-or-script

# 10 Compatibility Guide

In order to realize the full benefits of TurboVNC, it is necessary to use the TurboVNC Server and the TurboVNC Viewer together. However, TurboVNC is 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, and features such as the TurboVNC Session Manager will not be available.

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 that allow the JPEG chrominance subsampling to be specified seperately. TigerVNC 1.2 and later includes the same extensions on the server side, so in this regard, the TigerVNC 1.2+ Server behaves 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 in 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 and 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.
- Normally, the TurboVNC Viewer Options dialog only allows you to select the compression levels that are useful for the TurboVNC Server, but you can use the TurboVNC Viewer’s `CompressLevel` parameter to specify additional compression levels. You can also set the TurboVNC Viewer’s `CompatibleGUI` parameter to expose all 10 compression levels in the TurboVNC Viewer Options dialog, which is useful when connecting to non-TurboVNC servers. It should be noted, however, that our experiments have shown that compression levels higher than 5 are generally not useful in the TightVNC and TigerVNC Servers. They increase CPU usage exponentially without significantly reducing network usage relative to Compression Level 5.
- TurboVNC supports an extension to Tight encoding that allows the server to tell the viewer to bypass zlib when decompressing 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, so they will still use zlib to “compress” framebuffer updates even if you request Compression Level 0.
- When properly configured, version 1.2 and later (except versions 1.4.0 - 1.4.2, which contained a performance regression) of the TigerVNC Server can be made to perform similarly to a single-threaded instance of the TurboVNC Server. However, all other versions of TigerVNC and TightVNC will use much more CPU time across the board than the TurboVNC Server, all else being equal. With JPEG enabled, Compression Levels 1 and 2 in TigerVNC are roughly equivalent to the same compression levels in TurboVNC, except that TigerVNC enables interframe comparison automatically with Compression Level 2 and above.

## 10.2 TightVNC or TigerVNC Viewers

- When either a TightVNC or TigerVNC viewer is connected to a TurboVNC session, the TurboVNC Server emulates the behavior of a TigerVNC server, translating 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 session 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 attempts to send framebuffer updates with no zlib compression, and the TightVNC and TigerVNC viewers don’t support that.
  A similar issue occurs when using more than four encoding threads in the TurboVNC session. Since the Tight encoding type is limited to four zlib streams, any encoding threads beyond the first four cannot use zlib compression.
- Refer to Section 7.2 for a description of how the TurboVNC Server implements Compression Levels 0-9.

## 10.3 RealVNC

The TurboVNC Viewer supports the Hextile, Raw, and ZRLE encoding types, which are compatible with RealVNC. None of those encoding types can be selected from the TurboVNC Viewer Options dialog, but Hextile or ZRLE will be selected automatically when connecting to a RealVNC server. Non-Tight encoding types, such as Hextile and Raw, can also be specified using the TurboVNC Viewer’s `Encoding` parameter. In addition to Hextile, Raw, and ZRLE, the TurboVNC Server also supports the RRE, 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 a gigabit or faster network in order to achieve decent performance, and it can easily take up all of the bandwidth on a gigabit network. (It also doesn’t perform particularly well in the TurboVNC Viewer, because of the need to convert pixels from bytes to ints in Java.) 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 networks but uses too much CPU time to perform well on fast networks. ZRLE improves upon this, but it is still too computationally intense for fast networks. The `vncviewer` man page contains additional information about how Hextile and ZRLE work.

# 11 Advanced Configuration

## 11.1 Server Settings

The TurboVNC Server is normally configured in the following ways, in increasing order of precedence:

1. A system-wide configuration file (/etc/turbovncserver.conf), which can be used to modify the default values of certain `vncserver` and `Xvnc` command-line options
2. A per-user configuration file (~/.vnc/turbovncserver.conf), which can be used to modify the default values of certain `vncserver` and `Xvnc` command-line options
3. `vncserver` and `Xvnc` command-line options
4. `tvncconfig`, which can be used to modify certain TurboVNC Server parameters in a running TurboVNC session
5. A system-wide security configuration file (/etc/turbovncserver-security.conf), which can be used to configure certain TurboVNC Server security features as well as restrict the scope of TurboVNC Server features that users are allowed to configure

Refer to the TurboVNC man pages for more information:

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

This section documents rarely-used advanced TurboVNC Server settings that can be configured using environment variables.

Environment Variable | `TVNC_ALRALL = 0 | 1`
TurboVNC Server Parameter | `ALRAll = False | True`
Summary | Disable/Enable automatic lossless refresh for regions that were drawn using X11 functions other than `X[Shm]PutImage()`
Default Value | Disabled

Description
  See Section 7.4

Environment Variable | `TVNC_ALRCOPYRECT = 0 | 1`
Summary | Disable/Enable automatic lossless refresh for regions that were drawn using CopyRect
Default Value | Enabled

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, the TurboVNC Server will coalesce it into a single rectangle that covers all of the rectangles in the update. For applications that generate many tiny rectangles, increasing the value of `TVNC_COMBINERECT` may significantly increase the number of pixels sent to the viewer, which will increase network usage. However, for those same applications, lowering the value of `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_ICEBLOCKSIZE = {s}`
Summary | Set the block size for the interframe comparison engine (ICE) to `{s}` x `{s}` pixels. Setting `{s}` to 0 causes the ICE to compare full rectangles, as TurboVNC 1.2.x did.
Default Value | `256`

Description
  If interframe comparison is enabled (see Section 7.1), then the TurboVNC Server compares each rectangle of each framebuffer update on a block-by-block basis and sends only the blocks that have changed. This prevents large rectangles from being re-transmitted if only a few pixels in the rectangle have changed. Using smaller block sizes can decrease network usage if only a few pixels have changed between updates. However, using smaller block sizes can also interfere with the Tight encoder’s ability to efficiently split rectangles into subrectangles, thus increasing host CPU usage (and sometimes increasing network usage as well, which defeats the purpose of interframe comparison.) Setting the block size to 0 causes the ICE to compare full framebuffer update rectangles, as TurboVNC 1.2.x did.
  The default block size of 256x256 was chosen based on extensive low-level experiments using the same set of RFB session captures that were used when designing the TurboVNC encoder. For most of those datasets, 256x256 blocks produced the lowest network and CPU usage, but actual mileage may vary. There were rare cases in which 64x64 blocks or full-rectangle comparison produced better network and CPU usage.

Environment Variable | `TVNC_ICEDEBUG = 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 screen regions without culling them from the framebuffer 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 | Enabled

Description
  See Section 7.5

Environment Variable | `TVNC_NTHREADS = {n}`
Summary | Use `{n}` threads (1 <= `{n}` <= 8) to perform image encoding
Default Value | `{n}` = the number of CPU cores in the system, up to a maximum of 4

Description
  See Section 7.5

Environment Variable | `TVNC_PROFILE = 0 | 1`
TurboVNC Server Parameter | `Profile = False | True`
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 TurboVNC session log.

## 11.2 Viewer Settings

The TurboVNC Viewer is normally configured in the following ways, in increasing order of precedence:

1. A per-user configuration file (~/.vnc/default.turbovnc), which can be used to modify the default values of TurboVNC Viewer parameters
2. TurboVNC Viewer parameters, which can be set on the command line or in a connection info file

Run

    /opt/TurboVNC/bin/vncviewer -?

on Linux/Un*x and Mac systems or

    c:\Program Files\TurboVNC\vncviewer.bat -?

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

This section documents rarely-used advanced TurboVNC Viewer settings that can be configured using environment variables or Java system properties.

Java system properties can be set using the `JAVA_TOOL_OPTIONS` environment variable. For instance, on Linux/Un*x and Mac systems, you could execute:

    JAVA_TOOL_OPTIONS=-Dturbovnc.sessmgr=0 /opt/TurboVNC/bin/vncviewer

to start the TurboVNC Viewer with the TurboVNC Session Manager disabled.

Java System Property | `turbovnc.ciphersuites`
Summary | Available cipher suites for TLS encryption
Default Value | System-dependent

Description
  If the logging level is 100 or higher, then the TurboVNC Viewer will print a list of cipher suites that are available for use with the current TLS encryption method. (This occurs during RFB authentication if one of the TLS* or X509* security types is selected.) You can then use this property to further restrict the list of available cipher suites or change their preferred order.

Java System Property | `turbovnc.primary = 0 | 1`
Summary | Disable/enable the use of the X11 PRIMARY clipboard selection
Default Value | Enabled

Description
  X11 has two ways of copying/pasting text. When text is selected in most X11 applications, it is copied to the PRIMARY selection, and it can be pasted by pressing the middle mouse button. When text is explicitly copied using a “Copy” menu option or a hotkey (such as CTRL-C), it is copied to the CLIPBOARD selection, and it can only be pasted using a “Paste” menu option or a hotkey (such as CTRL-V.) Normally, on X11 platforms, the TurboVNC Viewer transfers the PRIMARY selection from client to server, and when receiving a clipboard update from the server, it sets both the PRIMARY and CLIPBOARD selections with the server’s clipboard contents. Disabling this property causes only the CLIPBOARD selection to be transferred from client to server. (In other words, the clipboard will not be transferred unless you explicitly copy something using a menu option or a hotkey.) Also, if this property is disabled, then clipboard changes from the server will only affect the client’s CLIPBOARD selection. (In other words, you will have to use a menu option or a hotkey to paste the server’s clipboard contents.)

Environment Variable | `TVNC_PROFILE = 0 | 1`
Summary | Disable/enable profiling output
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. The TurboVNC Viewer’s `ProfileInterval` parmeter can be used to specify the time period over which performance statistics are averaged and reported.

Environment Variable | `TVNC_SERVERARGS`
Java System Property | `turbovnc.serverargs`
Summary | Additional arguments that the TurboVNC Session Manager will pass to `vncserver` when starting a new TurboVNC session

Description
  The TurboVNC Session Manager will pass these command-line arguments to the `vncserver` script when starting a new TurboVNC session on the TurboVNC host. This can be used, for instance, to enable automatic lossless refresh.

Environment Variable | `TVNC_SERVERDIR`
Java System Property | `turbovnc.serverdir`
Summary | The directory in which the TurboVNC Server is installed on the TurboVNC host
Default Value | `/opt/TurboVNC`

Description
  The TurboVNC Session Manager will execute `bin/vncserver` and `bin/vncpasswd` from this directory on the TurboVNC host.

Java System Property | `turbovnc.sessmgr = 0 | 1`
Summary | Disable/enable the TurboVNC Session Manager
Default Value | Enabled

Description
  Disabling this property will completely disable the TurboVNC Session Manager.

Environment Variable | `TVNC_SINGLESCREEN = 0 | 1`
Java System Property | `turbovnc.singlescreen = 0 | 1`
Summary | Disable/enable forcing a single-screen layout when using automatic desktop resizing
Default Value | Disabled

Description
  If automatic desktop resizing and multi-screen spanning are enabled, then the TurboVNC Viewer normally requests a screen layout from the server that fits within the viewer window without using scrollbars and that aligns the server’s screen boundaries with the client’s when the viewer window is in its default position. Setting this environment variable or property to `1` restores the automatic desktop resizing behavior of version 2.1.x and prior of the TurboVNC Viewer, requesting a single-screen layout from the server even if it supports multi-screen layouts.

Java System Property | `turbovnc.sshauth`
Summary | Preferred authentication methods for the built-in SSH client
Default Value | `publickey,keyboard-interactive,password`

Description
  This property can be used to enable or disable particular SSH authentication methods, as well as to specify their preferred order. The same thing can be accomplished using the `PreferredAuthentications` directive in the OpenSSH config file.

Java System Property | `turbovnc.sshbannerdlg = 0 | 1`
Summary | Display the banner message from the SSH server in a dialog box
Default Value | Disabled

Description
  The default behavior of the TurboVNC Viewer is to display the banner message from the SSH server on the command line. Enabling this property causes the viewer to display the banner message in a dialog box instead.

Environment Variable | `VNC_VIA_CMD`, `VNC_TUNNEL_CMD`
Java System Property | `turbovnc.via`, `turbovnc.tunnel`
Summary | SSH command-line templates for use with the `Via` and `Tunnel` parameters (respectively)
Default Value | See below

Description
  When the `Via` parameter is used along with the `ExtSSH` parameter, the TurboVNC Viewer reads the `VNC_VIA_CMD` environment variable or the `turbovnc.via` property, expands patterns beginning with the “%” character, and uses the resulting command line to establish the secure tunnel to the VNC gateway. If `VNC_VIA_CMD` and `turbovnc.via` are not set, then this command-line template defaults to one of the following values:

  Connection Type | Default `VNC_VIA_CMD`/`turbovnc.via` Value
  --- | ---
  TCP port | `%S -f -L %L:%H:%R %G sleep 20`
  Unix domain socket | `%S -J %G -- %H exec socat stdio unix-connect:%R`

  When the `Tunnel` parameter is used along with the `ExtSSH` parameter, the TurboVNC Viewer reads the `VNC_TUNNEL_CMD` environment variable or the `turbovnc.tunnel` property, expands patterns beginning with the “%” character, and uses the resulting command line to establish the secure tunnel to the VNC host. If `VNC_TUNNEL_CMD` and `turbovnc.tunnel` are not set, then this command-line template defaults to one of the following values:

  Connection Type | Default `VNC_TUNNEL_CMD`/`turbovnc.tunnel` Value
  --- | ---
  TCP port | `%S -f -L %L:localhost:%R %H sleep 20`
  Unix domain socket | `%S -- %H exec socat stdio unix-connect:%R`

  The following patterns are recognized in the `VNC_VIA_CMD` and `VNC_TUNNEL_CMD` environment variables and their corresponding properties. Note that `%H` and `%R` must be present in the command-line template, and `%G` must also be present if using the `Via` parameter. If the VNC server is listening on a TCP port, then `%L` must also be present. If the VNC server is listening on a Unix domain socket, then `%L` can optionally be used to forward a local TCP port to the remote Unix domain socket (for instance, by setting `VNC_TUNNEL_CMD` to `%S -f -L %L:%R %H sleep 20`.) If `%L` is not present, then the TurboVNC Viewer expects the SSH command line to connect standard input and standard output to the remote Unix domain socket.

  `%%` | A literal “%”
  `%G` | gateway host name or IP address
  `%H` | remote VNC host name or IP address (if using the `Via` parameter, then this is specified from the point of view of the gateway)
  `%L` | local TCP port number
  `%R` | remote TCP port number or the escaped name of a Unix domain socket on the VNC host
  `%S` | the external SSH client command, which can be specified using the TurboVNC Viewer’s `ExtSSHCommand` parameter