<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
<meta name="language" content="en">
<meta name="date" content="2021-01-26T18:48:30">
<meta name="generator" content="deplate.rb 0.8.5">
<title>User’s Guide for TurboVNC 2.2.6</title>
<link rel="start" href="index.html" title="Frontpage">
<link rel="chapter" href="index.html#hd001" title="1 Legal Information">
<link rel="chapter" href="index.html#hd002" title="2 Conventions Used in This Document">
<link rel="chapter" href="index.html#hd003" title="3 Overview">
<link rel="chapter" href="index.html#hd004" title="4 System Requirements">
<link rel="chapter" href="index.html#hd005" title="5 Obtaining and Installing TurboVNC">
<link rel="chapter" href="index.html#hd006" title="6 Using TurboVNC">
<link rel="chapter" href="index.html#hd007" title="7 Performance and Image Quality">
<link rel="chapter" href="index.html#hd008" title="8 TurboVNC Security Extensions">
<link rel="chapter" href="index.html#hd009" title="9 Hardware 3D Acceleration (Using VirtualGL with TurboVNC)">
<link rel="chapter" href="index.html#hd0010" title="10 Compatibility Guide">
<link rel="chapter" href="index.html#hd0011" title="11 Advanced Configuration">
<link rel="stylesheet" type="text/css" href="turbovnc.css" title="turbovnc">
</head>
<body >
<a name="#pagetop"></a>
<div class="title">
<p class="title">User’s Guide for TurboVNC 2.2.6</p>
</div>
<div id="hd">
<div id="hdBlock" class="hd">
<ul class="hd">
<li class="Itemize-1 hd">
<a href="#hd001" class="hd">1 Legal Information</a>
</li>
<li class="Itemize-1 hd">
<a href="#hd002" class="hd">2 Conventions Used in This Document</a>
<ul class="hd">
<li class="Itemize-3 hd">
<a href="#hd002001" class="hd">2.1 Terminology</a>
</li>
</ul>
</li>
<li class="Itemize-1 hd">
<a href="#hd003" class="hd">3 Overview</a>
</li>
<li class="Itemize-1 hd">
<a href="#hd004" class="hd">4 System Requirements</a>
<ul class="hd">
<li class="Itemize-3 hd">
<a href="#hd004001" class="hd">4.1 Linux/x86 and Other x86 Un*x
Operating Systems</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd004002" class="hd">4.2 Mac/x86</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd004003" class="hd">4.3 Windows</a>
</li>
</ul>
</li>
<li class="Itemize-1 hd">
<a href="#hd005" class="hd">5 Obtaining and Installing TurboVNC</a>
<ul class="hd">
<li class="Itemize-3 hd">
<a href="#hd005001" class="hd">5.1 Installing TurboVNC on Linux</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd005002" class="hd">5.2 Installing the TurboVNC Viewer on
macOS</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd005003" class="hd">5.3 Installing the TurboVNC Viewer on
Windows</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd005004" class="hd">5.4 Installing TurboVNC from Source</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd005005" class="hd">5.5 Uninstalling TurboVNC</a>
</li>
</ul>
</li>
<li class="Itemize-1 hd">
<a href="#hd006" class="hd">6 Using TurboVNC</a>
<ul class="hd">
<li class="Itemize-3 hd">
<a href="#hd006001" class="hd">6.1 Starting and Connecting to a TurboVNC
Session</a>
<ul class="hd">
<li class="Itemize-5 hd">
<a href="#hd006001002" class="hd">6.1.2 Window Manager Compatibility</a>
</li>
</ul>
</li>
<li class="Itemize-3 hd">
<a href="#hd006002" class="hd">6.2 Disconnecting and Killing a TurboVNC
Session</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd006003" class="hd">6.3 Launching the TurboVNC Viewer from a
Web Browser</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd006004" class="hd">6.4 Deploying the Java TurboVNC Viewer
Using Java Web Start</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd006005" class="hd">6.5 Using SSH to Secure a TurboVNC
Connection</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd006006" class="hd">6.6 Running OpenGL Applications</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd006007" class="hd">6.7 Further Reading</a>
</li>
</ul>
</li>
<li class="Itemize-1 hd">
<a href="#hd007" class="hd">7 Performance and Image Quality</a>
<ul class="hd">
<li class="Itemize-3 hd">
<a href="#hd007001" class="hd">7.1 Interframe Comparison</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd007002" class="hd">7.2 Advanced Compression Options</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd007003" class="hd">7.3 Lossless Refresh</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd007004" class="hd">7.4 Automatic Lossless Refresh</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd007005" class="hd">7.5 Multithreading</a>
</li>
</ul>
</li>
<li class="Itemize-1 hd">
<a href="#hd008" class="hd">8 TurboVNC Security Extensions</a>
<ul class="hd">
<li class="Itemize-3 hd">
<a href="#hd008001" class="hd">8.1 Terminology</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd008002" class="hd">8.2 TurboVNC Server Authentication
Methods</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd008003" class="hd">8.3 TurboVNC Viewer Authentication
Schemes</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd008004" class="hd">8.4 Supported Encryption Methods</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd008005" class="hd">8.5 Supported Security Types</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd008006" class="hd">8.6 Enabling Security Types</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd008007" class="hd">8.7 Further Reading</a>
</li>
</ul>
</li>
<li class="Itemize-1 hd">
<a href="#hd009" class="hd">9 Hardware 3D Acceleration (Using VirtualGL
with TurboVNC)</a>
<ul class="hd">
<li class="Itemize-3 hd">
<a href="#hd009001" class="hd">9.1 Using VirtualGL on a TurboVNC Host</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd009002" class="hd">9.2 Using VirtualGL on a Machine Other
Than a TurboVNC Host</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd009003" class="hd">9.3 NV-CONTROL Emulation</a>
</li>
</ul>
</li>
<li class="Itemize-1 hd">
<a href="#hd0010" class="hd">10 Compatibility Guide</a>
<ul class="hd">
<li class="Itemize-3 hd">
<a href="#hd0010001" class="hd">10.1 TightVNC or TigerVNC Servers</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd0010002" class="hd">10.2 TightVNC or TigerVNC Viewers</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd0010003" class="hd">10.3 RealVNC</a>
</li>
</ul>
</li>
<li class="Itemize-1 hd">
<a href="#hd0011" class="hd">11 Advanced Configuration</a>
<ul class="hd">
<li class="Itemize-3 hd">
<a href="#hd0011001" class="hd">11.1 Server Settings</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd0011002" class="hd">11.2 Viewer Settings</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd0011003" class="hd">11.3 Java Viewer Settings</a>
</li>
</ul>
</li>
</ul>
</div></div>
<a name="file000"></a>
<p><br /></p>
<hr class="break" />
<h1 id="hd001"><a name="file001"></a>1 Legal Information</h1>
<p><img src="somerights20.png" alt="somerights20" class="inline" id="imgid_0" name="imgid_0"/></p>
<p>This document and all associated illustrations are licensed under the
<span class="remote"><a href="http://creativecommons.org/licenses/by/2.5/" class="remote">Creative
Commons Attribution 2.5 License</a></span><a name="idx001"></a>. 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.</p>
<p>The official TurboVNC binaries contain libjpeg-turbo, which is based in
part on the work of the Independent JPEG Group.</p>
<p>TurboVNC is licensed under the <a href="LICENSE.txt">GNU General Public
License, v2</a><a name="idx002"></a>.</p>
<p><br /></p>
<hr class="break" />
<h1 id="hd002"><a name="file002"></a>2 Conventions Used in This Document</h1>
<p>This document assumes that TurboVNC will be installed in the default
directory (<strong class="filename">/opt/TurboVNC</strong> on Linux/Un*x
and Mac systems and <strong class="filename">c:\Program
Files\TurboVNC</strong> on Windows systems.) If your installation of
TurboVNC resides in a different directory, then adjust the instructions
accordingly.</p>
<h2 id="hd002001">2.1 Terminology</h2>
<dl class="Description">
<dt class="Description-1 Description">VNC server (sometimes just “server”)</dt>
<dd class="Description-1 Description">
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.)
</dd>
<dt class="Description-1 Description">VNC host (sometimes just “host”)</dt>
<dd class="Description-1 Description">
The machine on which a VNC server is running
</dd>
<dt class="Description-1 Description">VNC viewer (sometimes just “viewer”)</dt>
<dd class="Description-1 Description">
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.
</dd>
<dt class="Description-1 Description">client machine (sometimes just “client”)</dt>
<dd class="Description-1 Description">
The machine on which a VNC viewer is running
</dd>
<dt class="Description-1 Description">VNC session (sometimes just “session”)</dt>
<dd class="Description-1 Description">
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 RFB port number
for connections from VNC viewers. Multiple simultaneous VNC sessions
can exist on a given host, under any number of different user accounts.
</dd>
</dl>
<p><br /></p>
<hr class="break" />
<h1 id="hd003"><a name="file003"></a>3 Overview</h1>
<p>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
<span class="remote"><a href="http://www.tightvnc.com" class="remote">TightVNC</a></span><a name="idx003"></a>
1.3.x, and on the surface, the X server and Windows viewer still behave
similarly to their parents. However, the current version of TurboVNC
contains a much more modern X server code base (based on X.org) and a
variety of other features and fixes, including a high-performance
zero-install Java viewer. 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 <a href="#AdvancedCompression" class="ref">7.2</a>.)</p>
<p>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.</p>
<p>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.</p>
<p>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. For more information on the
research leading to TurboVNC’s encoder design, see
<span class="remote"><a href="http://www.TurboVNC.org/pmwiki/uploads/About/tighttoturbo.pdf" class="remote">this
report</a></span><a name="idx004"></a>.</p>
<p>In addition to high performance, other notable features of TurboVNC
include:</p>
<ul class="Itemize">
<li class="Itemize-1 Itemize asterisk">
Fine-grained control over the JPEG image quality and the level of
chrominance subsampling
</li>
<li class="Itemize-1 Itemize asterisk">
Double buffering on the client side to reduce tearing artifacts in 3D
and video applications
</li>
<li class="Itemize-1 Itemize asterisk">
Flexible and configurable full-screen/multi-screen support
</li>
<li class="Itemize-1 Itemize asterisk">
Full support for IPv6
</li>
<li class="Itemize-1 Itemize asterisk">
Advanced flow control and continuous updates. This allows viewers to
receive framebuffer updates without specifically requesting them, which
can improve performance dramatically on high-latency connections.
</li>
<li class="Itemize-1 Itemize asterisk">
Authentication with one-time passwords or Unix login credentials.
Access control lists can be used to share TurboVNC sessions with only
certain users.
</li>
<li class="Itemize-1 Itemize asterisk">
TLS encryption support (VeNCrypt-compatible)
</li>
<li class="Itemize-1 Itemize asterisk">
TurboVNC allows security/authentication policies to be set globally for
a particular host.
</li>
<li class="Itemize-1 Itemize asterisk">
Multithreaded Tight encoding
</li>
<li class="Itemize-1 Itemize asterisk">
“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.
</li>
<li class="Itemize-1 Itemize asterisk">
High-performance zero-install Java viewer, which can be launched via
Java Web Start using TurboVNC’s built-in web server or deployed on
a dedicated web server. By calling libjpeg-turbo through JNI, the Java
TurboVNC Viewer achieves similar levels of performance to the native
TurboVNC Viewer.
</li>
<li class="Itemize-1 Itemize asterisk">
The TurboVNC Server and Java TurboVNC Viewer can be used with an
instance of the UltraVNC Repeater in Mode I or II.
</li>
<li class="Itemize-1 Itemize asterisk">
Remote extended input device support
</li>
</ul>
<p>TurboVNC, when used with VirtualGL, provides a highly performant and
robust solution for remotely displaying 3D applications over all types
of networks.</p>
<p>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.</p>
<p>TurboVNC is compatible with other VNC distributions. See Chapter
<a href="#Compatibility" class="ref">10</a> for more information. The
official TurboVNC binaries can be installed onto the same system as
other VNC distributions without interference.</p>
<p><br /></p>
<hr class="break" />
<h1 id="hd004"><a name="file004"></a>4 System Requirements</h1>
<h2 id="hd004001">4.1 Linux/x86 and Other x86 Un*x Operating Systems</h2>
<div class="table">
<table class="standard">
<thead class="standard">
<tr class="head ">
<th class="head standard"></th>
<th class="head standard">Host (x86)</th>
<th class="head standard">Host (x86-64)</th>
<th class="head standard">Client</th>
</tr>
</thead>
<tr class="standard">
<td class="high standard">Recommended CPU</td>
<td class="standard"><ul class="Itemize"><li class="Itemize-0">
For optimal performance, the CPU should support SSE2 extensions.
</li>
<li class="Itemize-0">
Dual processors or dual cores recommended
</li></ul></td>
<td class="standard">Dual processors or dual cores recommended</td>
<td class="standard">For optimal performance, the CPU should support SSE2 extensions.</td>
</tr>
<tr class="standard">
<td class="high standard">O/S</td>
<td class="standard" colspan="3">TurboVNC should work with a variety of Linux distributions, <span class="remote"><a href="http://www.freebsd.org" class="remote">FreeBSD</a></span><a name="idx005"></a>, and <span class="remote"><a href="http://www.oracle.com/us/products/servers-storage/solaris" class="remote">Solaris</a></span><a name="idx006"></a>, but currently-supported versions of <span class="remote"><a href="http://www.redhat.com/products/enterprise-linux/" class="remote">Red Hat Enterprise Linux</a></span><a name="idx007"></a> (and its work-alikes, including <span class="remote"><a href="http://www.centos.org" class="remote">CentOS</a></span><a name="idx008"></a>, <span class="remote"><a href="http://www.oracle.com/us/technologies/linux" class="remote">Oracle Linux</a></span><a name="idx009"></a>, and <span class="remote"><a href="https://www.scientificlinux.org" class="remote">Scientific Linux</a></span><a name="idx0010"></a>), <span class="remote"><a href="http://www.ubuntu.com" class="remote">Ubuntu</a></span><a name="idx0011"></a> LTS, and <span class="remote"><a href="http://www.suse.com" class="remote">SuSE</a></span><a name="idx0012"></a> Linux Enterprise tend to receive the most attention from the TurboVNC community.</td>
</tr>
<tr class="standard">
<td class="high standard">Other</td>
<td class="standard"></td>
<td class="standard"></td>
<td class="standard"><ul class="Itemize"><li class="Itemize-0">
For optimal performance, the X server should be configured to export
True Color (24-bit or 32-bit) visuals.
</li>
<li class="Itemize-0">
<span class="remote"><a href="http://www.java.com" class="remote">Oracle
Java</a></span><a name="idx0013"></a> or OpenJDK (Oracle Java 8 or
IcedTea-Web is required if using <a href="#JWS">Java Web
Start</a><a name="idx0014"></a>.)
</li></ul></td>
</tr>
</table>
</div>
<h2 id="hd004002">4.2 Mac/x86</h2>
<div class="table">
<table class="standard">
<thead class="standard">
<tr class="head ">
<th class="head standard"></th>
<th class="head standard">Client</th>
</tr>
</thead>
<tr class="standard">
<td class="high standard">Recommended CPU</td>
<td class="standard">Any 64-bit Intel-based Mac</td>
</tr>
<tr class="standard">
<td class="high standard">O/S</td>
<td class="standard">OS X/macOS 10.7 “Lion” or later</td>
</tr>
<tr class="standard">
<td class="high standard">Other Software</td>
<td class="standard"><span class="remote"><a href="http://www.java.com" class="remote">Oracle Java</a></span><a name="idx0015"></a> 8u40 or later, or <span class="remote"><a href="https://jdk.java.net" class="remote">OpenJDK</a></span><a name="idx0016"></a> 8 or later (Oracle Java 8 or <span class="remote"><a href="https://icedtea.classpath.org/wiki/IcedTea-Web" class="remote">IcedTea-Web</a></span><a name="idx0017"></a> is required if using <a href="#JWS">Java Web Start</a><a name="idx0018"></a>.)</td>
</tr>
</table>
</div>
<h2 id="hd004003">4.3 Windows</h2>
<div class="table">
<table class="standard">
<thead class="standard">
<tr class="head ">
<th class="head standard"></th>
<th class="head standard">Client</th>
</tr>
</thead>
<tr class="standard">
<td class="high standard">Recommended CPU</td>
<td class="standard">For optimal performance, the CPU should support SSE2 extensions.</td>
</tr>
<tr class="standard">
<td class="high standard">O/S</td>
<td class="standard">Windows 2000 SP1 or later</td>
</tr>
<tr class="standard">
<td class="high standard">Other</td>
<td class="standard"><ul class="Itemize"><li class="Itemize-0">
For optimal performance, the client display should have a 24-bit or
32-bit (True Color) color depth.
</li>
<li class="Itemize-0">
SSH client
(<span class="remote"><a href="https://www.msys2.org" class="remote">MSYS2</a></span><a name="idx0019"></a>
or
<span class="remote"><a href="http://cygwin.com" class="remote">Cygwin</a></span><a name="idx0020"></a>
implementation preferred, since those implementations work with the
<a href="#Secure_TurboVNC_Usage"><code>-via</code> and
<code>-tunnel</code> options</a><a name="idx0021"></a> in the native
Windows TurboVNC Viewer, but other SSH implementations will work without
the <code>-via</code> and <code>-tunnel</code> options.
<strong class="filename">ssh.exe</strong> should be in the
<code>PATH</code>.)
</li>
<li class="Itemize-0">
<span class="remote"><a href="http://www.java.com" class="remote">Oracle
Java</a></span><a name="idx0022"></a> 8 or
<span class="remote"><a href="https://icedtea.classpath.org/wiki/IcedTea-Web" class="remote">IcedTea-Web</a></span><a name="idx0023"></a>
is required if using <a href="#JWS">Java Web
Start</a><a name="idx0024"></a>.
</li></ul></td>
</tr>
</table>
</div>
<p><br /></p>
<hr class="break" />
<h1 id="hd005"><a name="file005"></a>5 Obtaining and Installing TurboVNC</h1>
<h2 id="hd005001">5.1 Installing TurboVNC on Linux</h2>
<h3 id="hd005001001">Installing TurboVNC</h3>
<ol class="Ordered numeric">
<li class="Ordered-1 Ordered" value="1">
Download the appropriate TurboVNC binary package for your system from
the
<span class="remote"><a href="http://sourceforge.net/projects/turbovnc/files/" class="remote">Files
area</a></span><a name="idx0025"></a> of the
<span class="remote"><a href="http://sourceforge.net/projects/turbovnc" class="remote">TurboVNC
SourceForge project page</a></span><a name="idx0026"></a>. Packages are
provided for RPM-based and Debian-based Linux distributions that contain
GLIBC 2.5 or later. <br />
</li>
<li class="Ordered-1 Ordered" value="2">
cd to the directory where you downloaded the binary package, and issue
one of the following commands as root:
<dl class="Description">
<dt class="Description-3 Description">RPM-based systems using YUM</dt>
<dd class="Description-3 Description">
<pre class="verbatim">
yum install turbovnc*.rpm
</pre>
</dd>
<dt class="Description-3 Description">RPM-based systems using DNF</dt>
<dd class="Description-3 Description">
<pre class="verbatim">
dnf install turbovnc*.rpm
</pre>
</dd>
<dt class="Description-3 Description">RPM-based systems using YaST2</dt>
<dd class="Description-3 Description">
<pre class="verbatim">
yast2 --install turbovnc*.rpm
</pre>
</dd>
<dt class="Description-3 Description">Other RPM-based systems (dependencies will not be installed automatically)</dt>
<dd class="Description-3 Description">
<pre class="verbatim">
rpm -U turbovnc*.rpm
</pre>
</dd>
<dt class="Description-3 Description">Debian-based systems</dt>
<dd class="Description-3 Description">
<pre class="verbatim">
dpkg -i turbovnc*.deb
apt install -f
</pre>
</dd>
</dl>
</li>
</ol>
<h3 id="hd005001002">Installing TurboVNC for a Single User</h3>
<p>Download the appropriate binary package, as above, then execute the
following commands:</p>
<dl class="Description">
<dt class="Description-1 Description">RPM-based systems</dt>
<dd class="Description-1 Description">
<pre class="verbatim">mkdir ~/turbovnc<br />cd ~/turbovnc<br />rpm2cpio <em>full/path/of/turbovnc*.rpm</em> | cpio -idv</pre>
</dd>
<dt class="Description-1 Description">Debian-based systems</dt>
<dd class="Description-1 Description">
<pre class="verbatim">dpkg-deb –extract <em>full/path/of/turbovnc*.deb</em> ~/turbovnc</pre>
</dd>
</dl>
<p>Add <strong class="filename">~/turbovnc</strong> to any paths specified
in this document. Note that the TurboVNC security configuration file
will not work when TurboVNC is installed in this manner.</p>
<h2 id="hd005002">5.2 Installing the TurboVNC Viewer on macOS</h2>
<ol class="Ordered numeric">
<li class="Ordered-1 Ordered">
Download the TurboVNC Mac disk image
(<strong class="filename">TurboVNC-2.2.6.dmg</strong>) from the
<span class="remote"><a href="http://sourceforge.net/projects/turbovnc/files/" class="remote">Files
area</a></span><a name="idx0027"></a> of the
<span class="remote"><a href="http://sourceforge.net/projects/turbovnc" class="remote">TurboVNC
SourceForge project page</a></span><a name="idx0028"></a>.
<div class="important"><p class="important">
This package requires <span class="remote"><a href="http://www.java.com" class="remote">Oracle Java</a></span><a name="idx0029"></a> or <span class="remote"><a href="https://jdk.java.net" class="remote">OpenJDK</a></span><a name="idx0030"></a>.
</p></div>
</li>
<li class="Ordered-1 Ordered">
Open the disk image, then open
<strong class="filename">TurboVNC.pkg</strong> inside the disk image.
Follow the instructions to install the Mac TurboVNC Viewer.
</li>
</ol>
<h2 id="hd005003">5.3 Installing the TurboVNC Viewer on Windows</h2>
<ol class="Ordered numeric">
<li class="Ordered-1 Ordered">
Download the TurboVNC Windows installer package
(<strong class="filename">TurboVNC-2.2.6-x86.exe</strong> for 32-bit
systems or <strong class="filename">TurboVNC-2.2.6-x64.exe</strong> for
64-bit systems) from the
<span class="remote"><a href="http://sourceforge.net/projects/turbovnc/files/" class="remote">Files
area</a></span><a name="idx0031"></a> of the
<span class="remote"><a href="http://sourceforge.net/projects/turbovnc" class="remote">TurboVNC
SourceForge project page</a></span><a name="idx0032"></a>.
</li>
<li class="Ordered-1 Ordered">
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.
</li>
</ol>
<h2 id="hd005004">5.4 Installing TurboVNC from Source</h2>
<p>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 (<strong class="filename">turbovnc-2.2.6.tar.gz</strong>)
from the
<span class="remote"><a href="http://sourceforge.net/projects/turbovnc/files/" class="remote">Files
area</a></span><a name="idx0033"></a> of the
<span class="remote"><a href="http://sourceforge.net/projects/turbovnc" class="remote">TurboVNC
SourceForge project page</a></span><a name="idx0034"></a>, uncompress
it, <code>cd turbovnc-2.2.6</code>, and read
<strong class="filename">BUILDING.md</strong> for further instructions
on how to build TurboVNC from source.</p>
<h2 id="hd005005">5.5 Uninstalling TurboVNC</h2>
<h3 id="hd005005001">Linux</h3>
<p>As root, issue one of the following commands:</p>
<dl class="Description">
<dt class="Description-1 Description">RPM-based systems</dt>
<dd class="Description-1 Description">
<pre class="verbatim">
rpm -e turbovnc
</pre>
</dd>
<dt class="Description-1 Description">Debian-based systems</dt>
<dd class="Description-1 Description">
<pre class="verbatim">
dpkg -r turbovnc
</pre>
</dd>
</dl>
<h3 id="hd005005002">macOS</h3>
<p>Open the <strong class="filename">Uninstall TurboVNC</strong>
application, located in the <strong class="filename">TurboVNC</strong>
Applications folder. You can also open a terminal and execute:</p>
<pre class="verbatim">
sudo /opt/TurboVNC/bin/uninstall
</pre>
<h3 id="hd005005003">Windows</h3>
<p>Use the <strong class="filename">Programs and Features</strong> applet
in the Control Panel (or the <strong class="filename">Apps &
Features</strong> applet if you are running Windows 10), or select
<strong class="filename">Uninstall TurboVNC</strong> in the
<strong class="filename">TurboVNC</strong> Start Menu group.</p>
<p><br /></p>
<hr class="break" />
<h1 id="hd006"><a name="file006"></a>6 Using TurboVNC</h1>
<p><a name="TurboVNC_Usage"></a></p>
<h2 id="hd006001">6.1 Starting and Connecting to a TurboVNC Session</h2>
<h3 id="hd006001001">Procedure</h3>
<ol class="Ordered numeric">
<li class="Ordered-1 Ordered">
Open a new Command Prompt/terminal window on your client machine.
</li>
<li class="Ordered-1 Ordered">
In the new Command Prompt/terminal window, open a Secure Shell (SSH)
session into the TurboVNC host:
<pre class="verbatim">ssh <em>user</em>@<em>host</em></pre>
Replace <em><code>user</code></em> with your username on the TurboVNC
host and <em><code>host</code></em> with the hostname or IP address of
the host.
</li>
<li class="Ordered-1 Ordered">
In the SSH session, start a TurboVNC session:
<pre class="verbatim">
/opt/TurboVNC/bin/vncserver
</pre>
</li>
<li class="Ordered-1 Ordered">
Make a note of the X display number that the TurboVNC session is
occupying, for instance: <br /><br />
<code>Desktop 'TurboVNC: my_host:1 (my_user)' started on display my_host:1</code>
<br /><br /> 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.
</li>
<li class="Ordered-1 Ordered">
The SSH session can now be exited, if desired.
</li>
<li class="Ordered-1 Ordered">
On the client machine, start the TurboVNC Viewer.
<dl class="Description">
<dt class="Description-3 Description">Linux/Un*x clients</dt>
<dd class="Description-3 Description">
Open a new terminal/xterm and type
<pre class="verbatim">
/opt/TurboVNC/bin/vncviewer
</pre>
</dd>
<dt class="Description-3 Description">Mac clients</dt>
<dd class="Description-3 Description">
Open the <strong class="filename">TurboVNC Viewer</strong> application,
located in the <strong class="filename">TurboVNC</strong> Applications
folder.
</dd>
<dt class="Description-3 Description">Windows clients</dt>
<dd class="Description-3 Description">
Select <strong class="filename">TurboVNC Viewer</strong> in the
<strong class="filename">TurboVNC</strong> Start Menu group.
</dd>
</dl>
</li>
<li class="Ordered-1 Ordered">
A small dialog box will appear. <br /><br />
<div class="table">
<table class="standard">
<thead class="standard">
<tr class="head ">
<th class="head standard">Windows TurboVNC Viewer</th>
<th class="head standard">Linux/Un*x/Mac (Java) TurboVNC Viewer</th>
</tr>
</thead>
<tr class="standard">
<td class="standard"><img src="newconn-win.png" alt="newconn-win" class="inline" id="imgid_1" name="imgid_1"/></td>
<td class="standard"><img src="newconn-java.png" alt="newconn-java" class="inline" id="imgid_2" name="imgid_2"/></td>
</tr>
</table>
</div>
<br /> Enter the X display name (hostname, or IP address, and display
number) of the TurboVNC session in the “VNC server” field,
then click “Connect”.
</li>
<li class="Ordered-1 Ordered">
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.) <br /><br />
<div class="table">
<table class="standard">
<thead class="standard">
<tr class="head ">
<th class="head standard"></th>
<th class="head standard">Windows TurboVNC Viewer</th>
<th class="head standard">Linux/Un*x/Mac (Java) TurboVNC Viewer</th>
</tr>
</thead>
<tr class="standard">
<td class="standard">Standard VNC Authentication Dialog</td>
<td class="standard"><img src="vncauth-win.png" alt="vncauth-win" class="inline" id="imgid_3" name="imgid_3"/></td>
<td class="standard"><img src="vncauth-java.png" alt="vncauth-java" class="inline" id="imgid_4" name="imgid_4"/></td>
</tr>
<tr class="standard">
<td class="standard">Unix Login Authentication Dialog</td>
<td class="standard"><img src="unixauth-win.png" alt="unixauth-win" class="inline" id="imgid_5" name="imgid_5"/></td>
<td class="standard"><img src="unixauth-java.png" alt="unixauth-java" class="inline" id="imgid_6" name="imgid_6"/></td>
</tr>
</table>
</div>
<br /> Enter the VNC session password or the Unix username/password and
click “OK” (Windows) or press Enter (Linux/Un*x/Mac.)
<br /><br /> 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.
</li>
</ol>
<h3 id="hd006001002">6.1.2 Window Manager Compatibility</h3>
<p>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, and it also provides an option
(<code>-vgl</code>) that allows for running 3D window managers using
VirtualGL. However, for performance reasons, it is generally
recommended that you use a 2D 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
automatically be used if it is installed and the <code>TVNC_WM</code>
environment variable is set to <code>2d</code>. For other systems that
lack a 2D window manager, it is recommended that you install MATE.
Refer to
<span class="remote"><a href="http://www.turbovnc.org/Documentation/Compatibility22" class="remote">this
report</a></span><a name="idx0035"></a> 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.</p>
<h2 id="hd006002">6.2 Disconnecting and Killing a TurboVNC Session</h2>
<p>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.</p>
<p>To kill a TurboVNC session:</p>
<ol class="Ordered numeric">
<li class="Ordered-1 Ordered">
Using SSH, log into the host that is running the TurboVNC session you
want to kill.<br /> … or …<br /> Using the TurboVNC
Viewer, connect to the TurboVNC session that you want to kill, and open
a new terminal in that TurboVNC session.
</li>
<li class="Ordered-1 Ordered">
Type the following command:
<pre class="verbatim">/opt/TurboVNC/bin/vncserver -kill :<em>n</em></pre>
Replace <em><code>n</code></em> with the X display number of the
TurboVNC session you want to kill.
</li>
</ol>
<p>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:</p>
<pre class="verbatim">
/opt/TurboVNC/bin/vncserver -list
</pre>
<h2 id="hd006003">6.3 Launching the TurboVNC Viewer from a Web Browser</h2>
<p>When a TurboVNC session is created, it automatically starts a miniature
web server that serves up the Java TurboVNC Viewer as a Java Web Start
app. This allows you to easily connect to the TurboVNC session from a
machine that does not have the TurboVNC Viewer installed locally. If
one of the official TurboVNC binary packages is installed on the host,
then the miniature web server will automatically send the appropriate
x86 or x86-64 libjpeg-turbo JNI library for Linux, macOS, or Windows
clients when launching the TurboVNC Viewer. This provides most of the
advantages of the standalone TurboVNC viewers, including native levels
of performance on popular client platforms.</p>
<p>To launch the Java TurboVNC Viewer from a web browser, point your web
browser to:</p>
<pre class="verbatim">http://<em>host</em>:<em>5800+n</em></pre>
<p>where <em><code>host</code></em> is the hostname or IP address of the
TurboVNC host, and <em><code>n</code></em> is the X display number of
the TurboVNC session to which you want to connect.</p>
<p><em>Example:</em> If the TurboVNC session is occupying X display
<code>my_host:1</code>, then point your web browser to:</p>
<pre class="verbatim">
http://my_host:5801
</pre>
<p>This will download a JNLP file to your computer, which you can open in
Java Web Start.</p>
<p>You can add viewer parameters to the URL using the following format:</p>
<pre class="verbatim">http://<em>host</em>:<em>5800+n</em>?<em>param1</em>=<em>value1</em>&<em>param2</em>=<em>value2</em></pre>
<p>Example:</p>
<pre class="verbatim">
http://my_host:5801?tunnel=1&samp=2x&quality=80
</pre>
<p>will tunnel the VNC connection through SSH and enable Medium-Quality
JPEG.</p>
<div class="important"><p class="important">
NOTE: As of Java 7 Update 51, self-signed JARs are not allowed to run in Java Web Start by default. This is not an issue if you are using the official TurboVNC binary packages, but if you are building a self-signed version of the Java TurboVNC Viewer for development purposes, then you will need to add <code>http://<em>host</em>:<em>http-port</em></code> (for example, <code>http://my_host:5801</code>) to Java’s Exception Site List, which can be found under the “Security” tab in the Java Control Panel.
</p></div>
<div class="important"><p class="important">
NOTE: On some newer macOS systems, downloading a JNLP file may result in an error: “xxxxxxxx.jnlp can’t be opened because it it from an unidentified developer.” To work around this, you can either open the JNLP file directly from your <strong class="filename">Downloads</strong> folder, or you can change the application security settings in the <strong class="filename">Security & Privacy</strong> section of <strong class="filename">System Preferences</strong> to allow applications downloaded from anywhere.
</p></div>
<h2 id="hd006004">6.4 Deploying the Java TurboVNC Viewer Using Java Web Start</h2>
<p><a name="JWS"></a></p>
<p>Accessing the Java TurboVNC Viewer through TurboVNC’s built-in
HTTP server, as described above, is a quick and easy way of running the
TurboVNC Viewer on machines that don’t already have a VNC viewer
installed (for instance, for the purpose of collaborating with
colleagues who don’t normally use TurboVNC.)</p>
<p>To set up a large-scale deployment of the Java TurboVNC Viewer, however,
it is desirable to serve up the JAR files from a dedicated web server.</p>
<p>For the purposes of this guide, it is assumed that the reader has some
knowledge of web server administration.</p>
<ul class="Itemize">
<li class="Itemize-1 Itemize asterisk">
Copy the Java TurboVNC Viewer JAR file
(<strong class="filename">VncViewer.jar</strong>) into a directory on
your web server. <br /><br />
</li>
<li class="Itemize-1 Itemize asterisk">
Copy the libjpeg-turbo JNI JAR files into that same directory. You can
obtain these from one of the official TurboVNC 2.0 or later binary
packages for Linux, or you can download
<strong class="filename">libjpeg-turbo-<em>version</em>-jws.zip</strong>
from libjpeg-turbo 1.4.0 or later (available in the
<span class="remote"><a href="http://sourceforge.net/projects/libjpeg-turbo/files/" class="remote">Files
area</a></span><a name="idx0036"></a> of the
<span class="remote"><a href="http://sourceforge.net/projects/libjpeg-turbo" class="remote">libjpeg-turbo
SourceForge project page</a></span><a name="idx0037"></a>.) Note that
only the JARs included in the official TurboVNC packages are signed
using an official code signing certificate. <br /><br />
</li>
<li class="Itemize-1 Itemize asterisk">
<em>OPTIONAL:</em> Copy the TurboVNC Helper JAR files into that same
directory. You can obtain these from
<strong class="filename">turbovnc-2.2.6-jws.zip</strong>, which is
available in the
<span class="remote"><a href="http://sourceforge.net/projects/turbovnc/files/" class="remote">Files
area</a></span><a name="idx0038"></a> of the
<span class="remote"><a href="http://sourceforge.net/projects/turbovnc" class="remote">TurboVNC
SourceForge project page</a></span><a name="idx0039"></a>. <br /><br />
</li>
<li class="Itemize-1 Itemize asterisk">
<em>OPTIONAL:</em> For large organizations, it may be desirable to
obtain your own code signing certificate from a trusted certificate
authority and use <code>jarsigner</code> to sign all of the JARs with
that certificate. The specifics of this are left as an exercise for the
reader. <br /><br />
</li>
<li class="Itemize-1 Itemize asterisk">
Create a file called <strong class="filename">TurboVNC.jnlp</strong> in
the same directory as <strong class="filename">VncViewer.jar</strong> on
the web server, and give it the following contents:
<pre class="verbatim">
<?xml version="1.0" encoding="utf-8"?>
<jnlp codebase="{turbovnc-url}">
<information>
<title>TurboVNC Viewer</title>
<vendor>The VirtualGL Project</vendor>
</information>
<resources>
<jar href="VncViewer.jar"/>
</resources>
<security>
<all-permissions/>
</security>
<resources os="Mac OS X">
<j2se version="1.8+" java-vm-args="-server"/>
<nativelib href="ljtosx.jar"/>
<!-- Enable drawing tablet support for macOS clients -->
<nativelib href="tvnchelper-osx.jar"/>
</resources>
<resources os="Windows" arch="x86">
<j2se version="1.8+" java-vm-args="-Dsun.java2d.d3d=false"/>
<nativelib href="ljtwin32.jar"/>
<!-- Enable keyboard grabbing for 32-bit Windows clients -->
<nativelib href="tvnchelper-win32.jar"/>
</resources>
<resources os="Windows" arch="amd64">
<j2se version="1.8+" java-vm-args="-Dsun.java2d.d3d=false"/>
<nativelib href="ljtwin64.jar"/>
<!-- Enable keyboard grabbing for 64-bit Windows clients -->
<nativelib href="tvnchelper-win64.jar"/>
</resources>
<resources os="Linux" arch="i386">
<j2se version="1.8+" java-vm-args="-server"/>
<nativelib href="ljtlinux32.jar"/>
<!-- Enable keyboard grabbing, multi-screen spanning, and extended
input device support for 32-bit Linux clients -->
<nativelib href="tvnchelper-linux32.jar"/>
</resources>
<resources os="Linux" arch="amd64">
<j2se version="1.8+"/>
<nativelib href="ljtlinux64.jar"/>
<!-- Enable keyboard grabbing, multi-screen spanning, and extended
input device support for 64-bit Linux clients -->
<nativelib href="tvnchelper-linux64.jar"/>
</resources>
<application-desc main-class="com.turbovnc.vncviewer.VncViewer"/>
</jnlp>
</pre>
<div class="important"><p class="important">
NOTE: <em><code>{turbovnc-url}</code></em> should be the absolute URL of the TurboVNC Viewer directory on the web server, e.g. <code>http://my_host/turbovnc</code>.
</p></div>
<div class="important"><p class="important">
NOTE: Leave out the lines referring to <code>tvnchelper-*.jar</code> if you have not installed the TurboVNC Helper JARs.
</p></div>
This is just a minimal example. Refer to the
<span class="remote"><a href="https://docs.oracle.com/javase/8/docs/technotes/guides/javaws/developersguide/syntax.html" class="remote">JNLP
file syntax</a></span><a name="idx0040"></a> for additional fields that
you might want to add. <br /><br />
</li>
<li class="Itemize-1 Itemize asterisk">
You should now be able to access
<code><em>{turbovnc-url}</em>/TurboVNC.jnlp</code> in your browser to
launch the Java TurboVNC Viewer with full performance.
</li>
</ul>
<h2 id="hd006005">6.5 Using SSH to Secure a TurboVNC Connection</h2>
<p><a name="Secure_TurboVNC_Usage"></a></p>
<p>If you are using the Java TurboVNC Viewer, then the connection between
the TurboVNC Server and the TurboVNC Viewer will be encrypted by default
(refer to Chapter <a href="#Security_Extensions" class="ref">8</a>.)
Otherwise, the connection can easily be secured with SSH by using the
<code>-via</code> and <code>-tunnel</code> command-line options in the
TurboVNC Viewer (or, if you are using the Java TurboVNC Viewer, the
equivalent GUI options, which are located under the
“Security” tab in the Options dialog.) SSH is also
preferable to TurboVNC’s built-in encryption if one does not want
to open additional ports in the host’s firewall.</p>
<p>The <code>-via</code> and <code>-tunnel</code> options in the TurboVNC
Viewer take advantage of the port forwarding feature in SSH. For
instance, running</p>
<pre class="verbatim"><em>vncviewer</em> -via <em>user</em>@<em>host</em> localhost:<em>n</em></pre>
<p>or</p>
<pre class="verbatim"><em>vncviewer</em> -tunnel <em>user</em>@<em>host</em></pre>
<p>is the equivalent of running</p>
<pre class="verbatim">ssh -L <em>fp</em>:localhost:<em>5900+n</em> <em>user</em>@<em>host</em>
<em>vncviewer</em> localhost::<em>fp</em></pre>
<p>where <em><code>fp</code></em> is a free TCP port on the client machine
(this is automatically determined by the TurboVNC Viewer.)</p>
<div class="important"><p class="important">
In the above examples, <em><code>vncviewer</code></em> is the command used to launch the TurboVNC Viewer– <code>/opt/TurboVNC/bin/vncviewer</code> on Mac/Linux/Un*x systems, or <code>c:\Program Files\TurboVNC\vncviewer-java.bat</code> if running the Java TurboVNC Viewer on Windows systems, or <code>c:\Program Files\TurboVNC\cvncviewer.exe</code> if running the native Windows TurboVNC Viewer.
</p></div>
<p><code>-tunnel</code> can be used as a shortcut whenever the SSH and VNC
hosts are the same machine. <code>-via</code> 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 <code>localhost</code> in the above example.</p>
<p>The command used to establish the SSH tunnel is configurable by way of
environment variables. See Section
<a href="#VNC_VIA_CMD" class="ref">11.2</a> for more details.</p>
<div class="important"><p class="important">
NOTE: Since the Java TurboVNC Viewer contains an embedded SSH client, the <code>-via</code> and <code>-tunnel</code> command-line options can also be used when the viewer is deployed using <a href="#JWS">Java Web Start</a><a name="idx0041"></a>. These options would be specified as <code><argument></code> elements under the <code><application-desc></code> element in the JNLP file.
</p></div>
<div class="important"><p class="important">
Currently the use of the <code>-via</code> and <code>-tunnel</code> command-line options in the Windows TurboVNC Viewer requires Cygwin or MSYS2, since those are the only known Windows SSH implementations that support detaching the SSH process once the tunnel has been established. When using <code>-via</code> or <code>-tunnel</code>, it is recommended that you use the console version of the Windows TurboVNC Viewer (<code>cvncviewer.exe</code>) rather than <code>vncviewer.exe</code>. Otherwise, a new console window will pop up and remain for the duration of the VNC connection.
</p></div>
<h3 id="hd006005001">Forcing SSH Connections</h3>
<p>Passing an argument of <code>-localhost</code> to <code>vncserver</code>
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 <code>no-remote-connections</code> directive
is set in the TurboVNC security configuration file, then that has the
effect of enabling the <code>-localhost</code> option for all new
TurboVNC sessions that are started on the host.</p>
<p>Passing an argument of <code>-noreverse</code> to <code>vncserver</code>
will disable the ability to make outbound (reverse) connections from the
TurboVNC session. If the <code>no-reverse-connections</code> directive
is set in the TurboVNC security configuration file, then that has the
effect of enabling the <code>-noreverse</code> option for all new
TurboVNC sessions that are started on the host.</p>
<p>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 <code>permitted-security-types</code> directive in the TurboVNC
security configuration file) is recommended. Otherwise, when using the
Java TurboVNC Viewer with default settings, the connection will have
redundant encryption.</p>
<h2 id="hd006006">6.6 Running OpenGL Applications</h2>
<p>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. On systems that do
not have vendor-specific GPU drivers installed, or on systems that
provide a libglvnd-enabled build of Mesa, TurboVNC’s software
OpenGL implementation can use direct rendering. Otherwise, it falls back
to indirect rendering, which is limited to the OpenGL 1.4 API and which
may perform sluggishly (particularly with continuous mouse input.) In
general, if the TurboVNC host has a GPU, then you should use
<a href="#VGL">VirtualGL</a><a name="idx0042"></a> rather than relying
on TurboVNC’s software OpenGL implementation.</p>
<p>Passing <code>-extension GLX</code> to <code>vncserver</code>
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.) Passing <code>-iglx</code> to
<code>vncserver</code> disables indirect rendering. If the built-in
GLX/OpenGL implementation is not functioning properly, then pass
<code>-verbose</code> to <code>vncserver</code> to log informational
messages that may reveal the source of the problem.</p>
<h2 id="hd006007">6.7 Further Reading</h2>
<p>For more detailed instructions on the usage of TurboVNC:</p>
<dl class="Description">
<dt class="Description-1 Description">TurboVNC Server</dt>
<dd class="Description-1 Description">
Refer to the TurboVNC man pages:
<pre class="verbatim">
man -M /opt/TurboVNC/man vncserver
man -M /opt/TurboVNC/man Xvnc
man -M /opt/TurboVNC/man vncconnect
man -M /opt/TurboVNC/man vncpasswd
</pre>
</dd>
<dt class="Description-1 Description">Windows TurboVNC Viewer</dt>
<dd class="Description-1 Description">
Use the embedded help feature (the question mark button in the upper
right of the TurboVNC Viewer dialogs.) You can also run
<code>vncviewer.exe /?</code> from a command prompt to get a full
list of supported command-line options and their descriptions.
</dd>
<dt class="Description-1 Description">Linux/Un*x/Mac (Java) TurboVNC Viewer</dt>
<dd class="Description-1 Description">
Run
<pre class="verbatim">
/opt/TurboVNC/bin/vncviewer -?
</pre>
to display a full list of supported command-line options/parameters and
their descriptions.
</dd>
<dt class="Description-1 Description">Java TurboVNC Viewer on Windows</dt>
<dd class="Description-1 Description">
Run
<pre class="verbatim">
c:\Program Files\TurboVNC\vncviewer-java.bat -?
</pre>
to display a full list of supported command-line options/parameters and
their descriptions.
</dd>
</dl>
<p><br /></p>
<hr class="break" />
<h1 id="hd007"><a name="file007"></a>7 Performance and Image Quality</h1>
<p>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:</p>
<dl class="Description">
<dt class="Description-1 Description">Allow JPEG compression</dt>
<dd class="Description-1 Description">
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.
</dd>
<dt class="Description-1 Description">JPEG image quality</dt>
<dd class="Description-1 Description">
Lower quality levels produce grainier JPEG images with more noticeable
compression artifacts, but lower quality levels also use less network
bandwidth and CPU time.
</dd>
<dt class="Description-1 Description">JPEG chrominance subsampling</dt>
<dd class="Description-1 Description">
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.
</dd>
<dt class="Description-1 Description">Compression level</dt>
<dd class="Description-1 Description">
In TurboVNC, the compression level specifies:
<ol class="Ordered numeric"><li class="Ordered-0">
the level of zlib compression that will be used with indexed color,
mono, and raw subrectangles
</li>
<li class="Ordered-0">
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)
</li>
<li class="Ordered-0">
whether or not <a href="#InterframeComparison">interframe
comparison</a><a name="idx0043"></a> should be used
</li></ol> See Section
<a href="#AdvancedCompression" class="ref">7.2</a> below for more
details.
</dd>
</dl>
<p>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.)</p>
<p>The TurboVNC Viewer provides five preset “encoding methods”,
corresponding to the most useful combinations of the image compression
options described above:</p>
<a name="tab007001"></a>
<div class="table">
<table class="standard" summary="TurboVNC Encoding Methods">
<caption>Table 7.1: TurboVNC Encoding Methods</caption>
<thead class="standard">
<tr class="head ">
<th class="head standard">Encoding method</th>
<th class="head standard">Allow JPEG</th>
<th class="head standard">JPEG image quality</th>
<th class="head standard">JPEG chrominance subsampling</th>
<th class="head standard">Compression level</th>
<th class="head standard">Notes</th>
</tr>
</thead>
<tr class="standard">
<td class="standard">“Tight + Perceptually Lossless JPEG”</td>
<td class="standard">Yes</td>
<td class="standard">95</td>
<td class="standard">1x</td>
<td class="standard">1</td>
<td class="standard">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.</td>
</tr>
<tr class="standard">
<td class="standard">“Tight + Medium-Quality JPEG”</td>
<td class="standard">Yes</td>
<td class="standard">80</td>
<td class="standard">2x</td>
<td class="standard">6</td>
<td class="standard">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.)</td>
</tr>
<tr class="standard">
<td class="standard">“Tight + Low-Quality JPEG”</td>
<td class="standard">Yes</td>
<td class="standard">30</td>
<td class="standard">4x</td>
<td class="standard">7</td>
<td class="standard">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 <a href="#LR">Lossless Refresh feature</a><a name="idx0044"></a>. 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 bandwidth for low-color application workloads that are not good candidates for JPEG compression.</td>
</tr>
<tr class="standard">
<td class="standard">“Lossless Tight”</td>
<td class="standard">No</td>
<td class="standard">N/A</td>
<td class="standard">N/A</td>
<td class="standard">0</td>
<td class="standard">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.</td>
</tr>
<tr class="standard">
<td class="standard">“Lossless Tight + Zlib”</td>
<td class="standard">No</td>
<td class="standard">N/A</td>
<td class="standard">N/A</td>
<td class="standard">6</td>
<td class="standard">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.)</td>
</tr>
</table>
</div>
<p>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.)</p>
<h2 id="hd007001">7.1 Interframe Comparison</h2>
<p><a name="InterframeComparison"></a></p>
<p>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.</p>
<p>Interframe comparison has some tradeoffs associated with it. 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.</p>
<p>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.</p>
<p>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 either passing an argument of
<code>-interframe</code> to <code>vncserver</code> when starting a
TurboVNC session or by requesting a compression level of 5 or higher
from the viewer (see below.)</p>
<h2 id="hd007002">7.2 Advanced Compression Options</h2>
<p><a name="AdvancedCompression"></a></p>
<p>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 GUI will normally only allow 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 on the command line (or as a
parameter, if using the Java TurboVNC Viewer), and doing so will enable
a compatibility mode in the TurboVNC Viewer GUI that allows any
compression level from 0 to 9 to be requested.</p>
<p>When connecting to a TurboVNC server, requesting a particular
compression level has the following effect:</p>
<a name="tab007002"></a>
<div class="table">
<table class="standard" summary="Compression Levels Supported by the TurboVNC Server (JPEG Enabled)">
<caption>Table 7.2: Compression Levels Supported by the TurboVNC Server (JPEG Enabled)</caption>
<thead class="standard">
<tr class="head ">
<th class="head standard">Compression level</th>
<th class="head standard">Zlib compression level (non-JPEG subrectangles)</th>
<th class="head standard">Palette threshold</th>
<th class="head standard">Interframe comparison</th>
<th class="head standard">Notes</th>
</tr>
</thead>
<tr class="standard">
<td class="standard">0</td>
<td class="standard">1</td>
<td class="standard">24</td>
<td class="standard">No</td>
<td class="standard">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.</td>
</tr>
<tr class="standard">
<td class="standard">1</td>
<td class="standard">1</td>
<td class="standard">24</td>
<td class="standard">No</td>
<td class="standard">See the description of the “Tight + JPEG” encoding methods above.</td>
</tr>
<tr class="standard">
<td class="standard">2</td>
<td class="standard">3</td>
<td class="standard">96</td>
<td class="standard">No</td>
<td class="standard">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.</td>
</tr>
<tr class="standard">
<td class="standard">3-4</td>
<td class="standard">3</td>
<td class="standard">96</td>
<td class="standard">No</td>
<td class="standard">Same as Compression Level 2 (reserved for future expansion)</td>
</tr>
<tr class="standard">
<td class="standard">5-6</td>
<td class="standard">1</td>
<td class="standard">24</td>
<td class="standard">Yes</td>
<td class="standard">Same as Compression Level 1, but with interframe comparison enabled</td>
</tr>
<tr class="standard">
<td class="standard">7-8</td>
<td class="standard">3</td>
<td class="standard">96</td>
<td class="standard">Yes</td>
<td class="standard">Same as Compression Level 2, but with interframe comparison enabled</td>
</tr>
<tr class="standard">
<td class="standard">9</td>
<td class="standard">7</td>
<td class="standard">256</td>
<td class="standard">Yes</td>
<td class="standard">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.</td>
</tr>
</table>
</div>
<p></p>
<a name="tab007003"></a>
<div class="table">
<table class="standard" summary="Compression Levels Supported by the TurboVNC Server (JPEG Disabled)">
<caption>Table 7.3: Compression Levels Supported by the TurboVNC Server (JPEG Disabled)</caption>
<thead class="standard">
<tr class="head ">
<th class="head standard">Compression Level</th>
<th class="head standard">Zlib compression level (indexed color subrectangles)</th>
<th class="head standard">Zlib compression level (raw subrectangles)</th>
<th class="head standard">Palette threshold</th>
<th class="head standard">Interframe comparison</th>
<th class="head standard">Notes</th>
</tr>
</thead>
<tr class="standard">
<td class="standard">0</td>
<td class="standard">None</td>
<td class="standard">None</td>
<td class="standard">Subrectangle size / 4</td>
<td class="standard">No</td>
<td class="standard">See the description of the “Lossless Tight” encoding method above.</td>
</tr>
<tr class="standard">
<td class="standard">1</td>
<td class="standard">1</td>
<td class="standard">1</td>
<td class="standard">Subrectangle size / 96</td>
<td class="standard">No</td>
<td class="standard">See the description of the “Lossless Tight + Zlib” encoding method above.</td>
</tr>
<tr class="standard">
<td class="standard">2-4</td>
<td class="standard">1</td>
<td class="standard">1</td>
<td class="standard">Subrectangle size / 96</td>
<td class="standard">No</td>
<td class="standard">Same as Compression Level 1 (reserved for future expansion)</td>
</tr>
<tr class="standard">
<td class="standard">5</td>
<td class="standard">None</td>
<td class="standard">None</td>
<td class="standard">Subrectangle size / 4</td>
<td class="standard">Yes</td>
<td class="standard">Same as Compression Level 0, but with interframe comparison enabled</td>
</tr>
<tr class="standard">
<td class="standard">6-8</td>
<td class="standard">1</td>
<td class="standard">1</td>
<td class="standard">Subrectangle size / 96</td>
<td class="standard">Yes</td>
<td class="standard">Same as Compression Level 1, but with interframe comparison enabled</td>
</tr>
<tr class="standard">
<td class="standard">9</td>
<td class="standard">7</td>
<td class="standard">5</td>
<td class="standard">Subrectangle size / 96</td>
<td class="standard">Yes</td>
<td class="standard">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.</td>
</tr>
</table>
</div>
<h2 id="hd007003">7.3 Lossless Refresh</h2>
<p><a name="LR"></a></p>
<p>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.</p>
<p>To perform a lossless refresh, press CTRL-ALT-SHIFT-L or click on the
Lossless Refresh toolbar icon.</p>
<h2 id="hd007004">7.4 Automatic Lossless Refresh</h2>
<p><a name="ALR"></a></p>
<p>Passing an argument of <code>-alr <em>timeout</em></code> to
<code>vncserver</code> 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 <em><code>timeout</code></em>
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 “ALR-eligible” screen
regions that have been affected by lossy compression. You can also pass
arguments of <code>-alrqual</code> and <code>-alrsamp</code> to
<code>vncserver</code> to specify that automatic lossless refreshes
should be sent using JPEG instead (see the <code>Xvnc</code> man page
for details.)</p>
<p>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.</p>
<p>The default is for any regions drawn with <code>X[Shm]PutImage()</code>
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 server to request that the
viewer move a rectangle of pixels from one location to another.) 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 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, blinking cursors are not typically drawn using
<code>X[Shm]PutImage()</code>, so the problem is effectively worked
around by limiting the ALR-eligible regions to just the subset of
regions that were drawn with <code>X[Shm]PutImage()</code> and CopyRect.</p>
<div class="important"><p class="important">
NOTE: Ill-behaved applications that continuously render the same image will cause a variation of the “blinking cursor dilemma” and thus defeat ALR unless <a href="#InterframeComparison">interframe comparison</a><a name="idx0045"></a> is enabled.
</p></div>
<p>You can override the default ALR behavior, thus making all screen
regions eligible for ALR, by setting the <code>TVNC_ALRALL</code>
environment variable to <code>1</code> on the TurboVNC host prior to
starting a TurboVNC session. You can also set
<code>TVNC_ALRCOPYRECT</code> to <code>0</code> to make CopyRect regions
ALR-ineligible, which approximates the behavior of TurboVNC 1.2.1 and
prior.</p>
<h2 id="hd007005">7.5 Multithreading</h2>
<p><a name="Multithreading"></a></p>
<p>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.</p>
<p>To disable server-side multithreading, set the <code>TVNC_MT</code>
environment variable to <code>0</code> on the host prior to starting
<code>vncserver</code>, or pass an argument of <code>-nomt</code> to
<code>vncserver</code>. 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 <code>TVNC_NTHREADS</code> environment variable or pass an
argument of <code>-nthreads</code> to <code>vncserver</code> to override
this.</p>
<p><br /></p>
<hr class="break" />
<h1 id="hd008"><a name="file008"></a>8 TurboVNC Security Extensions</h1>
<p><a name="Security_Extensions"></a></p>
<h2 id="hd008001">8.1 Terminology</h2>
<p>In an attempt to maintain consistency with other VNC implementations,
TurboVNC uses the following terminology when referring to its security
extensions:</p>
<dl class="Description">
<dt class="Description-1 Description">Authentication Method</dt>
<dd class="Description-1 Description">
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.
</dd>
<dt class="Description-1 Description">Authentication Scheme</dt>
<dd class="Description-1 Description">
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.
</dd>
<dt class="Description-1 Description">Encryption Method</dt>
<dd class="Description-1 Description">
A technique used to encrypt the data sent between the VNC server and
the VNC viewer
</dd>
<dt class="Description-1 Description">Security Type</dt>
<dd class="Description-1 Description">
A specific combination of an authentication method, an authentication
scheme, and an encryption method
</dd>
</dl>
<h2 id="hd008002">8.2 TurboVNC Server Authentication Methods</h2>
<dl class="Description">
<dt class="Description-1 Description">No Authentication</dt>
<dd class="Description-1 Description">
The VNC server does not authenticate the VNC viewer at all.
</dd>
<dt class="Description-1 Description">VNC Password Authentication</dt>
<dd class="Description-1 Description">
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.)
</dd>
<dt class="Description-1 Description">One-Time Password (OTP) Authentication</dt>
<dd class="Description-1 Description">
Using the <code>vncpasswd</code> program, a unique password is
generated “on the fly” for the TurboVNC session, and the
password is printed on the command line (see the man page for
<code>vncpasswd</code> for more details.) The user enters this
password in 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.
</dd>
<dt class="Description-1 Description">PAM User/Password Authentication</dt>
<dd class="Description-1 Description">
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
<a href="#Secure_TurboVNC_Usage" class="ref">6.5</a>.)
</dd>
</dl>
<h2 id="hd008003">8.3 TurboVNC Viewer Authentication Schemes</h2>
<dl class="Description">
<dt class="Description-1 Description">None</dt>
<dd class="Description-1 Description">
No authentication credentials are sent to the server.
</dd>
<dt class="Description-1 Description">Standard VNC Authentication</dt>
<dd class="Description-1 Description">
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.)
</dd>
<dt class="Description-1 Description">Unix Login/Plain Authentication</dt>
<dd class="Description-1 Description">
Both the username and password are sent to the VNC server as plain
text. Thus, it is <em>strongly</em> recommended that this
authentication scheme be used only with VNC connections that are
encrypted using TLS (see below) or SSH (see Section
<a href="#Secure_TurboVNC_Usage" class="ref">6.5</a>.) 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.
</dd>
</dl>
<h2 id="hd008004">8.4 Supported Encryption Methods</h2>
<p>The Linux/Un*x/Mac/Java TurboVNC Viewer and the TurboVNC Server support
three encryption methods:</p>
<dl class="Description">
<dt class="Description-1 Description">None</dt>
<dd class="Description-1 Description">
No encryption
</dd>
<dt class="Description-1 Description">Anonymous TLS Encryption</dt>
<dd class="Description-1 Description">
The connection is encrypted using TLS (Transport Layer Security)
without authentication (i.e. without a certificate.)
</dd>
<dt class="Description-1 Description">TLS/X.509 Encryption</dt>
<dd class="Description-1 Description">
The connection is encrypted using TLS with a specified X.509
certificate.
</dd>
</dl>
<h2 id="hd008005">8.5 Supported Security Types</h2>
<p>The TurboVNC Server and Linux/Un*x/Mac/Java TurboVNC Viewer support the
following security types:</p>
<div class="table">
<table class="standard">
<thead class="standard">
<tr class="head ">
<th class="head standard">Server Security Type</th>
<th class="head standard">Authentication Method</th>
<th class="head standard">Encryption Method</th>
<th class="head standard">Viewer Security Type</th>
<th class="head standard">Authentication Scheme</th>
<th class="head standard">Compatibility</th>
</tr>
</thead>
<tr class="standard">
<td class="high standard">None</td>
<td class="standard">None</td>
<td class="standard">None</td>
<td class="high standard">None</td>
<td class="standard">None</td>
<td class="standard">RFB 3.3+</td>
</tr>
<tr class="standard">
<td class="high standard">VNC</td>
<td class="standard">VNC Password</td>
<td class="standard">None</td>
<td class="high standard">VNC</td>
<td class="standard">Standard VNC</td>
<td class="standard">RFB 3.3+</td>
</tr>
<tr class="standard">
<td class="high standard">OTP</td>
<td class="standard">One-Time Password</td>
<td class="standard">None</td>
<td class="high standard">VNC</td>
<td class="standard">Standard VNC</td>
<td class="standard">RFB 3.3+</td>
</tr>
<tr class="standard">
<td class="high standard">Plain</td>
<td class="standard">PAM User/Password</td>
<td class="standard">None</td>
<td class="high standard">Plain</td>
<td class="standard">Plain</td>
<td class="standard">RFB 3.7+ with VeNCrypt extensions</td>
</tr>
<tr class="standard">
<td class="high standard">TLSNone</td>
<td class="standard">None</td>
<td class="standard">Anonymous TLS</td>
<td class="high standard">TLSNone</td>
<td class="standard">None</td>
<td class="standard">RFB 3.7+ with VeNCrypt extensions</td>
</tr>
<tr class="standard">
<td class="high standard">TLSVnc</td>
<td class="standard">VNC Password</td>
<td class="standard">Anonymous TLS</td>
<td class="high standard">TLSVnc</td>
<td class="standard">Standard VNC</td>
<td class="standard">RFB 3.7+ with VeNCrypt extensions</td>
</tr>
<tr class="standard">
<td class="high standard">TLSOtp</td>
<td class="standard">One-Time Password</td>
<td class="standard">Anonymous TLS</td>
<td class="high standard">TLSVnc</td>
<td class="standard">Standard VNC</td>
<td class="standard">RFB 3.7+ with VeNCrypt extensions</td>
</tr>
<tr class="standard">
<td class="high standard">TLSPlain</td>
<td class="standard">PAM User/Password</td>
<td class="standard">Anonymous TLS</td>
<td class="high standard">TLSPlain</td>
<td class="standard">Plain</td>
<td class="standard">RFB 3.7+ with VeNCrypt extensions</td>
</tr>
<tr class="standard">
<td class="high standard">X509None</td>
<td class="standard">None</td>
<td class="standard">TLS/X.509</td>
<td class="high standard">X509None</td>
<td class="standard">None</td>
<td class="standard">RFB 3.7+ with VeNCrypt extensions</td>
</tr>
<tr class="standard">
<td class="high standard">X509Vnc</td>
<td class="standard">VNC Password</td>
<td class="standard">TLS/X.509</td>
<td class="high standard">X509Vnc</td>
<td class="standard">Standard VNC</td>
<td class="standard">RFB 3.7+ with VeNCrypt extensions</td>
</tr>
<tr class="standard">
<td class="high standard">X509Otp</td>
<td class="standard">One-Time Password</td>
<td class="standard">TLS/X.509</td>
<td class="high standard">X509Vnc</td>
<td class="standard">Standard VNC</td>
<td class="standard">RFB 3.7+ with VeNCrypt extensions</td>
</tr>
<tr class="standard">
<td class="high standard">X509Plain</td>
<td class="standard">PAM User/Password</td>
<td class="standard">TLS/X.509</td>
<td class="high standard">X509Plain</td>
<td class="standard">Plain</td>
<td class="standard">RFB 3.7+ with VeNCrypt extensions</td>
</tr>
<tr class="standard">
<td class="high standard">UnixLogin</td>
<td class="standard">PAM User/Password</td>
<td class="standard">None</td>
<td class="high standard">UnixLogin</td>
<td class="standard">Unix Login</td>
<td class="standard">RFB 3.7+ with TightVNC extensions</td>
</tr>
</table>
</div>
<div class="important"><p class="important">
NOTE: The security type names are case-insensitive. The capitalization conventions above are used in order to maintain consistency with the RFB protocol specification.
</p></div>
<h2 id="hd008006">8.6 Enabling Security Types</h2>
<p>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 set the preferred order of the security types by
editing the TurboVNC security configuration file. See the
<code>Xvnc</code> man page for more details.</p>
<p>If the VNC server allows multiple security types, then the VNC
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 passing command-line arguments to
<code>vncviewer</code>. 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 passing an argument of <code>-user
<em>user-name</em></code> to <code>vncviewer</code> when connecting to
the TurboVNC session. 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 passing an argument of
<code>-nounixlogin</code> to <code>vncviewer</code>. Both of these
command-line options work with all versions of the TurboVNC Viewer.
When using the Java TurboVNC Viewer, you can also accomplish the same
thing by unchecking “Unix Login” or “Plain” or
“Standard VNC” in the “Security” tab of the
Options dialog or by limiting the available security types using the
<code>SecurityTypes</code>, <code>User</code>, or
<code>NoUnixLogin</code> arguments/parameters.</p>
<p>If the system administrator has not restricted any of the server
security types on a system-wide basis, then the user can choose to
disable some or all of them for a particular TurboVNC session by using
the <code>-SecurityTypes</code> command-line argument when starting the
session. See the <code>Xvnc</code> man page for more details.</p>
<h2 id="hd008007">8.7 Further Reading</h2>
<p>For more detailed information about the TurboVNC security extensions,
refer to the TurboVNC man pages:</p>
<pre class="verbatim">
man -M /opt/TurboVNC/man vncserver
man -M /opt/TurboVNC/man Xvnc
man -M /opt/TurboVNC/man vncpasswd
</pre>
<p><br /></p>
<hr class="break" />
<h1 id="hd009"><a name="file009"></a>9 Hardware 3D Acceleration (Using VirtualGL with TurboVNC)</h1>
<p><a name="VGL"></a></p>
<p>Referring to the VirtualGL User’s Guide, VirtualGL’s X11
Transport draws OpenGL-rendered frames onto 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.</p>
<p>Since VirtualGL is sending rendered frames to the X proxy at a very fast
rate, the proxy must be able to compress the frames 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.</p>
<p>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.</p>
<h3 id="hd009000001">Advantages of TurboVNC (when compared to the VGL Transport)</h3>
<ul class="Itemize">
<li class="Itemize-1 Itemize asterisk">
When using the VGL Transport, non-OpenGL elements of the 3D
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-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 on
such connections.
</li>
<li class="Itemize-1 Itemize asterisk">
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 will generally use less network
bandwidth than the pure JPEG encoding method used by the VGL Transport.
</li>
<li class="Itemize-1 Itemize asterisk">
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.
</li>
<li class="Itemize-1 Itemize asterisk">
TurboVNC includes a lossless refresh feature that will, on demand, send
a mathematically lossless image of the remote desktop to the client. A
user connecting over a low-bandwidth connection can use low-quality JPEG
to achieve the best performance when manipulating a 3D model, then they
can request a lossless refresh when they are ready to study the model in
detail.
</li>
<li class="Itemize-1 Itemize asterisk">
The TurboVNC Server can be configured to send, during periods of
inactivity, a mathematically lossless copy of the rendered frames drawn
by VirtualGL (Automatic Lossless Refresh.)
</li>
<li class="Itemize-1 Itemize asterisk">
TurboVNC provides rudimentary collaboration capabilities. Multiple
users can simultaneously view the same TurboVNC session and pass around
control of the keyboard and mouse.
</li>
<li class="Itemize-1 Itemize asterisk">
From the point of view of the 3D application, the TurboVNC client/server
connection is stateless. If the network hiccups or the viewer is
otherwise disconnected, the TurboVNC session continues to run on the
host and can be rejoined from any machine on the network.
</li>
<li class="Itemize-1 Itemize asterisk">
No X server is required on the client machine. This reduces the
deployment complexity for Windows clients.
</li>
<li class="Itemize-1 Itemize asterisk">
Zero-install high-performance Java viewer can be launched from any
machine that has Java and a web browser installed.
</li>
<li class="Itemize-1 Itemize asterisk">
Any mobile device can be used as a TurboVNC client (with reduced
performance.)
</li>
</ul>
<h3 id="hd009000002">Disadvantages of TurboVNC (when compared to the VGL transport)</h3>
<ul class="Itemize">
<li class="Itemize-1 Itemize asterisk">
No seamless windows. All application windows are constrained to a
“virtual desktop”, which displays in a single window on the
client machine.
</li>
<li class="Itemize-1 Itemize asterisk">
TurboVNC will generally require about 20% more host/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.
</li>
<li class="Itemize-1 Itemize asterisk">
TurboVNC does not support quad-buffered stereo or transparent overlays.
</li>
</ul>
<h2 id="hd009001">9.1 Using VirtualGL on a TurboVNC Host</h2>
<p>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.</p>
<div class="figure">
<img src="x11transport.png" alt="x11transport" class="figure" id="imgid_7" name="imgid_7"/>
</div>
<p>The following procedure describes how to launch a 3D application using
this configuration.</p>
<h3 id="hd009001001">Procedure</h3>
<ol class="Ordered numeric">
<li class="Ordered-1 Ordered">
Follow the procedure described in Chapter
<a href="#TurboVNC_Usage" class="ref">6</a> for starting a TurboVNC
session and connecting to it.
</li>
<li class="Ordered-1 Ordered">
Open a new terminal inside the TurboVNC desktop.
</li>
<li class="Ordered-1 Ordered">
In the terminal, start a 3D application using VirtualGL:
<pre class="verbatim">/opt/VirtualGL/bin/vglrun <em>[vglrun options]</em> <em>3D-application-executable-or-script</em> <em>[arguments]</em></pre>
</li>
</ol>
<h2 id="hd009002">9.2 Using VirtualGL on a Machine Other Than a TurboVNC Host</h2>
<div class="figure">
<img src="vgltransportservernetwork.png" alt="vgltransportservernetwork" class="figure" id="imgid_8" name="imgid_8"/>
</div>
<p>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.</p>
<h3 id="hd009002001">Procedure</h3>
<ol class="Ordered numeric">
<li class="Ordered-1 Ordered">
Follow the procedure described in Chapter
<a href="#TurboVNC_Usage" class="ref">6</a> for starting a TurboVNC
session and connecting to it.
</li>
<li class="Ordered-1 Ordered">
Open a new terminal inside the TurboVNC desktop.
</li>
<li class="Ordered-1 Ordered">
In the same terminal window, open a Secure Shell (SSH) session into the
VirtualGL server:
<pre class="verbatim">/opt/VirtualGL/bin/vglconnect <em>user</em>@<em>server</em></pre>
Replace <em><code>user</code></em> with your username on the VirtualGL
server and <em><code>server</code></em> with the hostname or IP address
of that server. Refer to the VirtualGL User’s Guide for
additional <code>vglconnect</code> options.
</li>
<li class="Ordered-1 Ordered">
In the SSH session, set the <code>VGL_COMPRESS</code> environment
variable to <code>rgb</code>
<div class="important"><p class="important">
Passing an argument of <code>-c rgb</code> to <code>vglrun</code> achieves the same result.
</p></div>
</li>
<li class="Ordered-1 Ordered">
In the SSH session, start a 3D application using VirtualGL:
<pre class="verbatim">/opt/VirtualGL/bin/vglrun <em>[vglrun options]</em> <em>3D-application-executable-or-script</em> <em>[arguments]</em></pre>
</li>
</ol>
<h2 id="hd009003">9.3 NV-CONTROL Emulation</h2>
<p>This version of TurboVNC includes partial emulation of the
<code>NV-CONTROL</code> 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.</p>
<p>Passing an argument of <code>-nvcontrol <em>display</em></code> to
<code>vncserver</code> will set up a fake <code>NV-CONTROL</code>
extension in the TurboVNC session and will redirect all
<code>NV-CONTROL</code> requests to <em><code>display</code></em>.
<em><code>display</code></em> should generally be the name of the 3D X
server you plan to use with VirtualGL (<code>:0</code>, for instance.)
The TurboVNC Server does not attempt to open a connection to this
display until an application uses the <code>NV-CONTROL</code> extension.
If a connection to the 3D X server cannot be opened, if the 3D X server
does not have the <code>NV-CONTROL</code> extension, or if other issues
are encountered when attempting to redirect <code>NV-CONTROL</code>
requests, then a BadRequest X11 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 <code>vglusers</code> group, then you may need to
execute</p>
<pre class="verbatim">
xauth merge /etc/opt/VirtualGL/vgl_xauth_key
</pre>
<p>if you need to use the <code>NV-CONTROL</code> extension prior to
invoking <code>vglrun</code> for the first time.</p>
<p>You can change the 3D X server for a particular TurboVNC session after
the session has been started. For instance, if you want to redirect
both <code>NV-CONTROL</code> requests and OpenGL to a GPU attached to
Screen 1 of Display :0, you would execute</p>
<pre class="verbatim">xprop -root -f VNC_NVCDISPLAY 8s -set VNC_NVCDISPLAY :0.1
vglrun -d :0.1 <em>3D-application-executable-or-script</em></pre>
<p><br /></p>
<hr class="break" />
<h1 id="hd0010"><a name="file010"></a>10 Compatibility Guide</h1>
<p><a name="Compatibility"></a></p>
<p>In order to realize the full performance benefits of TurboVNC, it is
necessary to use the TurboVNC Server and the TurboVNC Viewer in concert.
However, TurboVNC is fully compatible with
<span class="remote"><a href="http://www.tigervnc.com" class="remote">TigerVNC</a></span><a name="idx0046"></a>,
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.</p>
<p>The following sections list additional things to bear in mind when
mixing TurboVNC with other VNC flavors.</p>
<h2 id="hd0010001">10.1 TightVNC or TigerVNC Servers</h2>
<ul class="Itemize">
<li class="Itemize-1 Itemize asterisk">
TightVNC and TigerVNC specify the JPEG quality level on a scale from 0
to 9. This translates to actual JPEG quality as follows:
<dl class="Description">
<dt class="Description-3 Description">TightVNC JPEG Quality Levels</dt>
<dd class="Description-3 Description">
<div class="table">
<table class="standard">
<thead class="standard">
<tr class="head ">
<th class="head standard">JPEG quality level</th>
<th class="head standard">0</th>
<th class="head standard">1</th>
<th class="head standard">2</th>
<th class="head standard">3</th>
<th class="head standard">4</th>
<th class="head standard">5</th>
<th class="head standard">6</th>
<th class="head standard">7</th>
<th class="head standard">8</th>
<th class="head standard">9</th>
</tr>
</thead>
<tr class="standard">
<td class="high standard">Actual JPEG quality</td>
<td class="standard">5</td>
<td class="standard">10</td>
<td class="standard">15</td>
<td class="standard">25</td>
<td class="standard">37</td>
<td class="standard">50</td>
<td class="standard">60</td>
<td class="standard">70</td>
<td class="standard">75</td>
<td class="standard">80</td>
</tr>
<tr class="standard">
<td class="high standard">Actual chrominance subsampling</td>
<td class="standard">2X</td>
<td class="standard">2X</td>
<td class="standard">2X</td>
<td class="standard">2X</td>
<td class="standard">2X</td>
<td class="standard">2X</td>
<td class="standard">2X</td>
<td class="standard">2X</td>
<td class="standard">2X</td>
<td class="standard">2X</td>
</tr>
</table>
</div>
<a name="TigerVNC_JPEG_Qual"></a>
</dd>
<dt class="Description-3 Description">TigerVNC JPEG Quality Levels</dt>
<dd class="Description-3 Description">
<div class="table">
<table class="standard">
<thead class="standard">
<tr class="head ">
<th class="head standard">JPEG quality level</th>
<th class="head standard">0</th>
<th class="head standard">1</th>
<th class="head standard">2</th>
<th class="head standard">3</th>
<th class="head standard">4</th>
<th class="head standard">5</th>
<th class="head standard">6</th>
<th class="head standard">7</th>
<th class="head standard">8</th>
<th class="head standard">9</th>
</tr>
</thead>
<tr class="standard">
<td class="high standard">Actual JPEG quality</td>
<td class="standard">15</td>
<td class="standard">29</td>
<td class="standard">41</td>
<td class="standard">42</td>
<td class="standard">62</td>
<td class="standard">77</td>
<td class="standard">79</td>
<td class="standard">86</td>
<td class="standard">92</td>
<td class="standard">100</td>
</tr>
<tr class="standard">
<td class="high standard">Actual chrominance subsampling</td>
<td class="standard">4X</td>
<td class="standard">4X</td>
<td class="standard">4X</td>
<td class="standard">2X</td>
<td class="standard">2X</td>
<td class="standard">2X</td>
<td class="standard">1X</td>
<td class="standard">1X</td>
<td class="standard">1X</td>
<td class="standard">1X</td>
</tr>
<tr class="standard">
<td class="high standard">Average compression ratio *</td>
<td class="standard">100</td>
<td class="standard">80</td>
<td class="standard">70</td>
<td class="standard">60</td>
<td class="standard">50</td>
<td class="standard">40</td>
<td class="standard">30</td>
<td class="standard">25</td>
<td class="standard">20</td>
<td class="standard">10</td>
</tr>
</table>
</div>
<div class="important"><p class="important">
* Experimentally determined by compressing every 10th frame in the SPECviewperf 9 benchmark suite
</p></div>
</dd>
</dl>
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. <br /><br /> 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. <br /><br />
</li>
<li class="Itemize-1 Itemize asterisk">
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.
<br /><br />
</li>
<li class="Itemize-1 Itemize asterisk">
Normally, the TurboVNC Viewer GUI only allows you to select the
compression levels that are useful for TurboVNC servers, but you can
specify additional compression levels on the TurboVNC Viewer command
line. You can also pass an argument of <code>-compatiblegui</code> to
the viewer to expose all 10 compression levels in the GUI, 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 or TigerVNC Servers.
They increase CPU usage exponentially without providing any significant
savings in bandwidth relative to Compression Level 5. <br /><br />
</li>
<li class="Itemize-1 Itemize asterisk">
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. <br /><br />
</li>
<li class="Itemize-1 Itemize asterisk">
When properly configured, version 1.2 and later (except for 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.
</li>
</ul>
<h2 id="hd0010002">10.2 TightVNC or TigerVNC Viewers</h2>
<ul class="Itemize">
<li class="Itemize-1 Itemize asterisk">
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
<a href="#TigerVNC_JPEG_Qual" class="ref">10.1</a>. <br /><br />
</li>
<li class="Itemize-1 Itemize asterisk">
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. <br /><br />
A similar issue occurs when using more than four encoding threads in the
server. Since the Tight encoding type is limited to four zlib streams,
any encoding threads beyond the first four cannot use zlib compression.
<br /><br />
</li>
<li class="Itemize-1 Itemize asterisk">
Refer to Section <a href="#AdvancedCompression" class="ref">7.2</a> for
a description of how the TurboVNC Server responds to requests for
Compression Levels 0-9. <br /><br />
</li>
</ul>
<h2 id="hd0010003">10.3 RealVNC</h2>
<p>The TurboVNC Viewer supports the Hextile and Raw encoding types, which
are compatible with RealVNC. The Java TurboVNC Viewer additionally
supports ZRLE. 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. Non-Tight encoding types, such as
Hextile and Raw, can also be manually selected from the TurboVNC Viewer
command line. 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.</p>
<p>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 (it also doesn’t perform particularly well with the Java
TurboVNC Viewer, because of the need to convert the 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 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. The <code>vncviewer</code>
man page in the TurboVNC Linux packages has some additional information
about how Hextile and ZRLE work.</p>
<p><br /></p>
<hr class="break" />
<h1 id="hd0011"><a name="file011"></a>11 Advanced Configuration</h1>
<h2 id="hd0011001">11.1 Server Settings</h2>
<div class="table">
<table class="standard">
<tr class="standard">
<td class="high standard">Environment Variable</td>
<td class="standard"><code>TVNC_ALRALL = <em>0 | 1</em></code></td>
</tr>
<tr class="standard">
<td class="high standard">Summary</td>
<td class="standard">Disable/Enable automatic lossless refresh for regions that were drawn using X11 functions other than <code>X[Shm]PutImage()</code></td>
</tr>
<tr class="standard">
<td class="high standard">Default Value</td>
<td class="standard">Disabled</td>
</tr>
</table>
</div>
<dl class="Description">
<dt class="Description-1 Description">Description</dt>
<dd class="Description-1 Description">
See Section <a href="#ALR" class="ref">7.4</a>
</dd>
</dl>
<div class="table">
<table class="standard">
<tr class="standard">
<td class="high standard">Environment Variable</td>
<td class="standard"><code>TVNC_ALRCOPYRECT = <em>0 | 1</em></code></td>
</tr>
<tr class="standard">
<td class="high standard">Summary</td>
<td class="standard">Disable/Enable automatic lossless refresh for regions that were drawn using CopyRect</td>
</tr>
<tr class="standard">
<td class="high standard">Default Value</td>
<td class="standard">Enabled</td>
</tr>
</table>
</div>
<dl class="Description">
<dt class="Description-1 Description">Description</dt>
<dd class="Description-1 Description">
See Section <a href="#ALR" class="ref">7.4</a>
</dd>
</dl>
<div class="table">
<table class="standard">
<tr class="standard">
<td class="high standard">Environment Variable</td>
<td class="standard"><code>TVNC_COMBINERECT = <em>{c}</em></code></td>
</tr>
<tr class="standard">
<td class="high standard">Summary</td>
<td class="standard">Combine framebuffer updates with more than <em><code>{c}</code></em> rectangles into a single rectangle spanning the bounding box of all of the constituent rectangles</td>
</tr>
<tr class="standard">
<td class="high standard">Default Value</td>
<td class="standard"><code>100</code></td>
</tr>
</table>
</div>
<dl class="Description">
<dt class="Description-1 Description">Description</dt>
<dd class="Description-1 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 <em><code>{c}</code></em> 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 <code>TVNC_COMBINERECT</code> may significantly increase the
number of pixels sent to the viewer, which will increase network usage.
However, for those same applications, lowering
<code>TVNC_COMBINERECT</code> will increase the number of rectangles
sent to the viewer, which will increase the CPU usage of both the server
and the viewer.
</dd>
</dl>
<div class="table">
<table class="standard">
<tr class="standard">
<td class="high standard">Environment Variable</td>
<td class="standard"><code>TVNC_ICEBLOCKSIZE = <em>{s}</em></code></td>
</tr>
<tr class="standard">
<td class="high standard">Summary</td>
<td class="standard">Set the block size for the interframe comparison engine (ICE) to <em><code>{s}</code></em> x <em><code>{s}</code></em> pixels. Setting <em><code>{s}</code></em> to 0 causes the ICE to compare full rectangles, as TurboVNC 1.2.x did.</td>
</tr>
<tr class="standard">
<td class="high standard">Default Value</td>
<td class="standard"><code>256</code></td>
</tr>
</table>
</div>
<dl class="Description">
<dt class="Description-1 Description">Description</dt>
<dd class="Description-1 Description">
If interframe comparison is enabled (see Section
<a href="#InterframeComparison" class="ref">7.1</a>), then TurboVNC will
compare each rectangle of each framebuffer update on a block-by-block
basis and send 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 are changing between updates, but 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 runs counter to 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. <br /><br /> 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 using 64x64 blocks or full-rectangle
comparison produced better network and CPU usage.
</dd>
</dl>
<div class="table">
<table class="standard">
<tr class="standard">
<td class="high standard">Environment Variable</td>
<td class="standard"><code>TVNC_ICEDEBUG = <em>0 | 1</em></code></td>
</tr>
<tr class="standard">
<td class="high standard">Summary</td>
<td class="standard">Disable/Enable the ICE debugger</td>
</tr>
<tr class="standard">
<td class="high standard">Default Value</td>
<td class="standard">Disabled</td>
</tr>
</table>
</div>
<dl class="Description">
<dt class="Description-1 Description">Description</dt>
<dd class="Description-1 Description">
If interframe comparison is enabled (see Section
<a href="#InterframeComparison" class="ref">7.1</a>), 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 update stream. This allows you to easily see which
applications are generating duplicate updates.
</dd>
</dl>
<div class="table">
<table class="standard">
<tr class="standard">
<td class="high standard">Environment Variable</td>
<td class="standard"><code>TVNC_MT = <em>0 | 1</em></code></td>
</tr>
<tr class="standard">
<td class="high standard">Summary</td>
<td class="standard">Disable/Enable multithreaded image encoding</td>
</tr>
<tr class="standard">
<td class="high standard">Default Value</td>
<td class="standard">Enabled</td>
</tr>
</table>
</div>
<dl class="Description">
<dt class="Description-1 Description">Description</dt>
<dd class="Description-1 Description">
See Section <a href="#Multithreading" class="ref">7.5</a>
</dd>
</dl>
<div class="table">
<table class="standard">
<tr class="standard">
<td class="high standard">Environment Variable</td>
<td class="standard"><code>TVNC_NTHREADS = <em>{n}</em></code></td>
</tr>
<tr class="standard">
<td class="high standard">Summary</td>
<td class="standard">Use <em><code>{n}</code></em> threads (1 <= <em><code>{n}</code></em> <= 8) to perform image encoding</td>
</tr>
<tr class="standard">
<td class="high standard">Default Value</td>
<td class="standard"><em><code>{n}</code></em> = the number of CPU cores in the system, up to a maximum of 4</td>
</tr>
</table>
</div>
<dl class="Description">
<dt class="Description-1 Description">Description</dt>
<dd class="Description-1 Description">
See Section <a href="#Multithreading" class="ref">7.5</a>
</dd>
</dl>
<div class="table">
<table class="standard">
<tr class="standard">
<td class="high standard">Environment Variable</td>
<td class="standard"><code>TVNC_PROFILE = <em>0 | 1</em></code></td>
</tr>
<tr class="standard">
<td class="high standard">Summary</td>
<td class="standard">Disable/enable profiling output</td>
</tr>
<tr class="standard">
<td class="high standard">Default Value</td>
<td class="standard">Disabled</td>
</tr>
</table>
</div>
<dl class="Description">
<dt class="Description-1 Description">Description</dt>
<dd class="Description-1 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.
</dd>
</dl>
<h2 id="hd0011002">11.2 Viewer Settings</h2>
<div class="table">
<table class="standard">
<tr class="standard">
<td class="high standard">Environment Variable</td>
<td class="standard"><code>TVNC_PROFILE = <em>0 | 1</em></code></td>
</tr>
<tr class="standard">
<td class="high standard">Summary</td>
<td class="standard">Disable/enable profiling output</td>
</tr>
<tr class="standard">
<td class="high standard">Platforms</td>
<td class="standard">Un*x, Mac (Java)</td>
</tr>
<tr class="standard">
<td class="high standard">Default Value</td>
<td class="standard">Disabled</td>
</tr>
</table>
</div>
<dl class="Description">
<dt class="Description-1 Description">Description</dt>
<dd class="Description-1 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.
</dd>
</dl>
<p><a name="TVNC_SINGLESCREEN"></a></p>
<div class="table">
<table class="standard">
<tr class="standard">
<td class="high standard">Environment Variable</td>
<td class="standard"><code>TVNC_SINGLESCREEN = <em>0 | 1</em></code></td>
</tr>
<tr class="standard">
<td class="high standard">Summary</td>
<td class="standard">Disable/enable forcing a single-screen layout when using automatic desktop resizing</td>
</tr>
<tr class="standard">
<td class="high standard">Platforms</td>
<td class="standard">All</td>
</tr>
<tr class="standard">
<td class="high standard">Default Value</td>
<td class="standard">Disabled</td>
</tr>
</table>
</div>
<dl class="Description">
<dt class="Description-1 Description">Description</dt>
<dd class="Description-1 Description">
The default behavior of the TurboVNC Viewer, when automatic desktop
resizing is enabled, is to request a desktop size from the server that
will fit within the viewer window without using scrollbars, and (if
multi-screen spanning is enabled) to request a screen layout from the
server that will align the server’s screen boundaries with the
client’s when the viewer window is in its default position.
Setting this environment variable to 1 will restore the automatic
desktop resizing behavior of previous versions of the TurboVNC Viewer,
thus forcing the server to use a single-screen layout even if it
supports multi-screen layouts.
</dd>
</dl>
<p><a name="VNC_VIA_CMD"></a></p>
<div class="table">
<table class="standard">
<tr class="standard">
<td class="high standard">Environment Variable</td>
<td class="standard"><code>VNC_VIA_CMD</code>, <code>VNC_TUNNEL_CMD</code></td>
</tr>
<tr class="standard">
<td class="high standard">Summary</td>
<td class="standard">SSH command-line templates for use with the <code>via</code> and <code>tunnel</code> options (respectively)</td>
</tr>
<tr class="standard">
<td class="high standard">Platforms</td>
<td class="standard">All</td>
</tr>
<tr class="standard">
<td class="high standard">Default Value</td>
<td class="standard">See below</td>
</tr>
</table>
</div>
<dl class="Description">
<dt class="Description-1 Description">Description</dt>
<dd class="Description-1 Description">
When the <code>-via</code> option (or the <code>via</code> parameter in
the Java viewer, along with the <code>extssh</code> parameter) is used,
the TurboVNC Viewer reads the <code>VNC_VIA_CMD</code> environment
variable (the Java viewer can also read this information from the
<code>turbovnc.via</code> system property), expands patterns beginning
with the “%” character, and uses the resulting command line
to establish the secure tunnel to the VNC gateway. If
<code>VNC_VIA_CMD</code> is not set, then this command line defaults to
<code>/usr/bin/ssh -f -L %L:%H:%R %G sleep 20</code>
on Linux/Un*x and Mac systems and
<code>ssh.exe -f -L %L:%H:%R %G sleep 20</code>
on Windows systems. <br /><br /> When the <code>-tunnel</code> option
(or the <code>tunnel</code> parameter in the Java viewer, along with the
<code>extssh</code> parameter) is used, the TurboVNC Viewer reads the
<code>VNC_TUNNEL_CMD</code> environment variable (the Java viewer can
also read this information from the <code>turbovnc.tunnel</code> system
property), expands patterns beginning with the “%”
character, and uses the resulting command line to establish the secure
tunnel to the VNC host. If <code>VNC_TUNNEL_CMD</code> is not set, then
this command line defaults to
<code>/usr/bin/ssh -f -L %L:localhost:%R %H sleep 20</code>
on Linux/Un*x and Mac systems and
<code>ssh.exe -f -L %L:localhost:%R %H sleep 20</code>
on Windows systems. <br /><br /> The following patterns are recognized
in the <code>VNC_VIA_CMD</code> and <code>VNC_TUNNEL_CMD</code>
environment variables (note that <code>%H</code>, <code>%L</code> and
<code>%R</code> must be present in the command template, and
<code>%G</code> must also be present if using the <code>-via</code>
option): <br /><br />
<div class="table">
<table class="standard">
<tr class="standard">
<td class="standard"><code>%%</code></td>
<td class="standard">A literal “%”</td>
</tr>
<tr class="standard">
<td class="standard"><code>%G</code></td>
<td class="standard">gateway host name or IP address</td>
</tr>
<tr class="standard">
<td class="standard"><code>%H</code></td>
<td class="standard">remote VNC host name or IP address (if using the <code>-via</code> option, then this is specified from the point of view of the gateway)</td>
</tr>
<tr class="standard">
<td class="standard"><code>%L</code></td>
<td class="standard">local TCP port number</td>
</tr>
<tr class="standard">
<td class="standard"><code>%R</code></td>
<td class="standard">remote TCP port number</td>
</tr>
</table>
</div>
</dd>
</dl>
<h2 id="hd0011003">11.3 Java Viewer Settings</h2>
<p>Java system properties are normally specified as command-line arguments
to the Java executable. For example:</p>
<pre class="verbatim">java -Dmy.system.property=<em>value</em> -jar MyClass.jar</pre>
<p>However, since TurboVNC hides the Java command line inside of its
startup scripts (or inside of an application bundle on macOS), the
easiest way to set these properties is by using the
<code>JAVA_TOOL_OPTIONS</code> environment variable, which allows you to
specify Java command-line arguments even if you don’t have access
to the command line. For instance, on Linux you could execute:</p>
<pre class="verbatim">
JAVA_TOOL_OPTIONS=-Dturbovnc.turbojpeg=0 /opt/TurboVNC/bin/vncviewer
</pre>
<p>to start the TurboVNC Viewer without JPEG acceleration.</p>
<p>Refer to the default <strong class="filename">VncViewer.jnlp</strong>
file installed with the TurboVNC Server for an example of how to specify
Java command-line arguments in a Java Web Start environment.</p>
<div class="table">
<table class="standard">
<tr class="standard">
<td class="high standard">Java System Property</td>
<td class="standard"><code>turbovnc.forcealpha = <em>0 | 1</em></code></td>
</tr>
<tr class="standard">
<td class="high standard">Summary</td>
<td class="standard">Disable/enable back buffer alpha channel</td>
</tr>
<tr class="standard">
<td class="high standard">Default Value</td>
<td class="standard">Enabled if using OpenGL Java 2D blitting, disabled otherwise</td>
</tr>
</table>
</div>
<dl class="Description">
<dt class="Description-1 Description">Description</dt>
<dd class="Description-1 Description">
If this property is enabled, then the Java TurboVNC Viewer will use a
TYPE_INT_ARGB_PRE (BGRA with pre-computed alpha channel) BufferedImage
as its back buffer instead of a TYPE_INT_RGB (BGRX) BufferedImage. When
using OpenGL blitting in Java 2D (normally accomplished by passing an
argument of <code>-Dsun.java2d.opengl=true</code> to <code>java</code>),
it is generally faster to draw an alpha-enabled BufferedImage to the
screen, because otherwise glDrawPixels() has to set all of the alpha
values itself (which can cause it to revert to an unaccelerated code
path in some cases.)
<div class="important"><p class="important">
NOTE: this property is enabled by default when using Java 7 or later on Mac platforms, because OpenGL Java 2D blitting is the only option available.
</p></div>
</dd>
</dl>
<div class="table">
<table class="standard">
<tr class="standard">
<td class="high standard">Java System Property</td>
<td class="standard"><code>turbovnc.lionfs = <em>0 | 1</em></code></td>
</tr>
<tr class="standard">
<td class="high standard">Summary</td>
<td class="standard">Disable/enable the use of the macOS full-screen application feature</td>
</tr>
<tr class="standard">
<td class="high standard">Default Value</td>
<td class="standard">Enabled</td>
</tr>
</table>
</div>
<dl class="Description">
<dt class="Description-1 Description">Description</dt>
<dd class="Description-1 Description">
When running in full-screen mode, the Java TurboVNC Viewer will normally
try to take advantage of the full-screen application feature provided by
OS X/macOS 10.7 and later, if available. Disabling this property will
force the viewer to use its own built-in cross-platform
“pseudo-full-screen” feature instead. This is useful mainly
for testing.
</dd>
</dl>
<div class="table">
<table class="standard">
<tr class="standard">
<td class="high standard">Java System Property</td>
<td class="standard"><code>turbovnc.primary = <em>0 | 1</em></code></td>
</tr>
<tr class="standard">
<td class="high standard">Summary</td>
<td class="standard">Disable/enable the use of the X11 PRIMARY clipboard selection</td>
</tr>
<tr class="standard">
<td class="high standard">Default Value</td>
<td class="standard">Enabled</td>
</tr>
</table>
</div>
<dl class="Description">
<dt class="Description-1 Description">Description</dt>
<dd class="Description-1 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 by explicitly selecting a “Paste” menu option or
pressing 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 will cause only the the CLIPBOARD
selection to be transferred from client to server (in other words, the
clipboard will not be transferred unless you explicitly copy something
by using a menu option or hotkey), and clipboard changes from the server
will only affect the client’s CLIPBOARD selection (in other words,
you will have to explicitly paste the server’s clipboard contents
by using a menu option or hotkey on the client.)
</dd>
</dl>
<div class="table">
<table class="standard">
<tr class="standard">
<td class="high standard">Java System Property</td>
<td class="standard"><code>turbovnc.singlescreen = <em>0 | 1</em></code></td>
</tr>
<tr class="standard">
<td class="high standard">Summary</td>
<td class="standard">Disable/enable forcing a single-screen layout when using automatic desktop resizing</td>
</tr>
<tr class="standard">
<td class="high standard">Default Value</td>
<td class="standard">Disabled</td>
</tr>
</table>
</div>
<dl class="Description">
<dt class="Description-1 Description">Description</dt>
<dd class="Description-1 Description">
A more Java-friendly way of disabling the multi-screen-aware automatic
desktop resize feature. See the
<a href="#TVNC_SINGLESCREEN"><code>TVNC_SINGLESCREEN</code> environment
variable</a><a name="idx0047"></a> above for more details.
</dd>
</dl>
<div class="table">
<table class="standard">
<tr class="standard">
<td class="high standard">Java System Property</td>
<td class="standard"><code>turbovnc.sshauth</code></td>
</tr>
<tr class="standard">
<td class="high standard">Summary</td>
<td class="standard">Preferred authentication methods for the built-in SSH client</td>
</tr>
<tr class="standard">
<td class="high standard">Default Value</td>
<td class="standard"><code>publickey,keyboard-interactive,password</code></td>
</tr>
</table>
</div>
<dl class="Description">
<dt class="Description-1 Description">Description</dt>
<dd class="Description-1 Description">
This system 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 by using the
<code>PreferredAuthentications</code> directive in the OpenSSH config
file.
</dd>
</dl>
<div class="table">
<table class="standard">
<tr class="standard">
<td class="high standard">Java System Property</td>
<td class="standard"><code>turbovnc.sshbannerdlg = <em>0 | 1</em></code></td>
</tr>
<tr class="standard">
<td class="high standard">Summary</td>
<td class="standard">Display the banner message from the SSH server in a dialog box</td>
</tr>
<tr class="standard">
<td class="high standard">Default Value</td>
<td class="standard">Enabled</td>
</tr>
</table>
</div>
<dl class="Description">
<dt class="Description-1 Description">Description</dt>
<dd class="Description-1 Description">
The default behavior of the Java TurboVNC Viewer is to display the
banner message from the SSH server in a dialog box. Disabling this
system property causes the viewer to display the banner message on the
command line instead.
</dd>
</dl>
<div class="table">
<table class="standard">
<tr class="standard">
<td class="high standard">Java System Property</td>
<td class="standard"><code>turbovnc.swingdb = <em>0 | 1</em></code></td>
</tr>
<tr class="standard">
<td class="high standard">Summary</td>
<td class="standard">Disable/enable Swing double buffering</td>
</tr>
<tr class="standard">
<td class="high standard">Default Value</td>
<td class="standard">Disabled</td>
</tr>
</table>
</div>
<dl class="Description">
<dt class="Description-1 Description">Description</dt>
<dd class="Description-1 Description">
The Java TurboVNC Viewer has its own double buffering mechanism, so it
normally disables the double buffering mechanism in Swing and Java 2D in
order to increase performance. This also allows the viewer to achieve
optimal performance under X11 without requiring MIT-SHM pixmap support.
Although the viewer has been thoroughly tested, the
<code>turbovnc.swingdb</code> system property is provided as a fallback
in case issues are discovered when running it under a specific version
of Java.
</dd>
</dl>
<div class="table">
<table class="standard">
<tr class="standard">
<td class="high standard">Java System Property</td>
<td class="standard"><code>turbovnc.tunnel</code></td>
</tr>
<tr class="standard">
<td class="high standard">Summary</td>
<td class="standard">SSH command-line template for use with the <code>Tunnel</code> and <code>ExtSSH</code> parameters</td>
</tr>
</table>
</div>
<dl class="Description">
<dt class="Description-1 Description">Description</dt>
<dd class="Description-1 Description">
A more Java-friendly way of specifying the command line to use when
establishing a secure tunnel with the <code>Tunnel</code> and
<code>ExtSSH</code> parameters. See the
<a href="#VNC_VIA_CMD"><code>VNC_TUNNEL_CMD</code> environment
variable</a><a name="idx0048"></a> above for more details.
</dd>
</dl>
<div class="table">
<table class="standard">
<tr class="standard">
<td class="high standard">Java System Property</td>
<td class="standard"><code>turbovnc.turbojpeg = <em>0 | 1</em></code></td>
</tr>
<tr class="standard">
<td class="high standard">Summary</td>
<td class="standard">Disable/enable JPEG acceleration</td>
</tr>
<tr class="standard">
<td class="high standard">Default Value</td>
<td class="standard">Enabled if the libjpeg-turbo JNI library is available</td>
</tr>
</table>
</div>
<dl class="Description">
<dt class="Description-1 Description">Description</dt>
<dd class="Description-1 Description">
Normally, the Java TurboVNC Viewer will try to load the libjpeg-turbo
JNI library and use it to accelerate the decompression of JPEG
subrectangles. If this property is disabled, then the viewer will
revert to using unaccelerated JPEG decompression. This is useful mainly
for testing and benchmarking purposes.
</dd>
</dl>
<div class="table">
<table class="standard">
<tr class="standard">
<td class="high standard">Java System Property</td>
<td class="standard"><code>turbovnc.via</code></td>
</tr>
<tr class="standard">
<td class="high standard">Summary</td>
<td class="standard">SSH command-line template for use with the <code>Via</code> and <code>ExtSSH</code> parameters</td>
</tr>
</table>
</div>
<dl class="Description">
<dt class="Description-1 Description">Description</dt>
<dd class="Description-1 Description">
A more Java-friendly way of specifying the command line to use when
establishing a secure tunnel with the <code>Via</code> and
<code>ExtSSH</code> parameters. See the
<a href="#VNC_VIA_CMD"><code>VNC_VIA_CMD</code> environment
variable</a><a name="idx0049"></a> above for more details.
</dd>
</dl>
<p><br /></p>
</body>
</html>