<!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="2016-03-12T18:49:49">
<meta name="generator" content="deplate.rb 0.8.5">
<title>User&rsquo;s Guide for TurboVNC 2.0.2</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 Authentication Extensions">
<link rel="chapter" href="index.html#hd009" title="9 Using TurboVNC with VirtualGL">
<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&rsquo;s Guide for TurboVNC 2.0.2</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>
    </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 OS 
                X</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>
            </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 Using TurboVNC in 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 Securing a TurboVNC Connection</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd006006" class="hd">6.6 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>
            <li class="Itemize-3 hd">
                <a href="#hd007006" class="hd">7.6 Maximizing the Performance of the 
                Java TurboVNC Viewer</a>
            </li>
        </ul>
    </li>
    <li class="Itemize-1 hd">
        <a href="#hd008" class="hd">8 TurboVNC Authentication Extensions</a>
        <ul class="hd">
            <li class="Itemize-3 hd">
                <a href="#hd008001" class="hd">8.1 Enabling Authentication Methods</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd008002" class="hd">8.2 Further Reading</a>
            </li>
        </ul>
    </li>
    <li class="Itemize-1 hd">
        <a href="#hd009" class="hd">9 Using TurboVNC with VirtualGL</a>
        <ul class="hd">
            <li class="Itemize-3 hd">
                <a href="#hd009001" class="hd">9.1 Using TurboVNC and VirtualGL on the 
                Same Server</a>
            </li>
            <li class="Itemize-3 hd">
                <a href="#hd009002" class="hd">9.2 Using TurboVNC When VirtualGL Is 
                Running on a Different Machine</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&nbsp;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>The TurboVNC Windows packages include 
<span class="remote"><a href="http://www.chiark.greenend.org.uk/~sgtatham/putty/" class="remote">PuTTY</a></span><a name="idx002"></a>, 
which is released under <a href="LICENSE-PuTTY.txt">this 
license</a><a name="idx003"></a>.</p>

<p>TurboVNC is licensed under the <a href="LICENSE.txt">GNU General Public 
License, v2</a><a name="idx004"></a>.</p>

<p><br /></p>

<hr class="break" />



<h1 id="hd002"><a name="file002"></a>2&nbsp;Conventions Used in This Document</h1>

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

<p><br /></p>

<hr class="break" />



<h1 id="hd003"><a name="file003"></a>3&nbsp;Overview</h1>

<p><a name="Overview"></a></p>

<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="idx005"></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 7.7) 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 &ldquo;tightest&rdquo; 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 &ldquo;framebuffer updates&rdquo; from the 
VNC server to any connected &ldquo;viewers.&rdquo;  Each framebuffer 
update can contain multiple &ldquo;rectangles&rdquo; (regions that have 
changed since the last update.)  As with TightVNC, TurboVNC analyzes 
each rectangle, splits it into multiple &ldquo;subrectangles&rdquo;, and 
attempts to encode each subrectangle using the &ldquo;subencoding 
type&rdquo; 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 &ldquo;encoding method.&rdquo;  
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 (&ldquo;Solid subencoding.&rdquo;)  Of the remaining 
subrectangles, those with only two colors are encoded as a 
1-bit-per-pixel bitmap with a 2-color palette (&ldquo;Mono 
subencoding&rdquo;), those with low numbers of unique colors are encoded 
as a color palette and an 8-bit-per-pixel bitmap (&ldquo;Indexed color 
subencoding&rdquo;), and subrectangles with high numbers of unique 
colors are encoded using either JPEG or arrays of RGB pixels (&ldquo;Raw 
subencoding&rdquo;), depending on the encoding method. zlib can 
optionally be used to compress the indexed color, mono and raw 
subrectangles.</p>

<p>Part of TurboVNC&rsquo;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&rsquo;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 captured RFB sessions that simulate real-world 
application workloads, both 2D and 3D.  For more information on the 
research leading to TurboVNC&rsquo;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="idx006"></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 VNC sessions with only certain 
        users.
    </li>
    <li class="Itemize-1 Itemize asterisk">
        TurboVNC allows security/authentication policies to be set globally for 
        a particular server machine.
    </li>
    <li class="Itemize-1 Itemize asterisk">
        Multithreaded Tight encoding
    </li>
    <li class="Itemize-1 Itemize asterisk">
        &ldquo;Lossless refresh&rdquo; 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&rsquo;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, and its performance is generally equal to or better 
        than that of the TigerVNC native viewers.
    </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>
</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 &ldquo;modern&rdquo; 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&nbsp;System Requirements</h1>


<h2 id="hd004001">4.1&nbsp;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">Server (x86)</th>
    <th class="head standard">Server (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="idx007"></a>, and <span class="remote"><a href="http://www.oracle.com/us/products/servers-storage/solaris" class="remote">Solaris</a></span><a name="idx008"></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="idx009"></a> (and its work-alikes, including <span class="remote"><a href="http://www.centos.org" class="remote">CentOS</a></span><a name="idx0010"></a>, <span class="remote"><a href="http://www.oracle.com/us/technologies/linux" class="remote">Oracle Linux</a></span><a name="idx0011"></a>, and <span class="remote"><a href="https://www.scientificlinux.org" class="remote">Scientific Linux</a></span><a name="idx0012"></a>), <span class="remote"><a href="http://www.ubuntu.com" class="remote">Ubuntu</a></span><a name="idx0013"></a> LTS, and <span class="remote"><a href="http://www.suse.com" class="remote">SuSE</a></span><a name="idx0014"></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">
    Java 5 or later (Java 6 or later recommended)
</li></ul></td>
  </tr>
</table>
</div>




<h2 id="hd004002">4.2&nbsp;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 Intel-based Mac</td>
  </tr>
  <tr class="standard">
    <td class="high standard">O/S</td>
    <td class="standard">OS X 10.5 (&ldquo;Leopard&rdquo;) or later</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Other Software</td>
    <td class="standard">Java for OS X or Oracle Java 8u40 or later (see Section <a href="#MacJavaPerf" class="ref">7.6.3</a> for more details)</td>
  </tr>
</table>
</div>




<h2 id="hd004003">4.3&nbsp;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">For optimal performance, the client display should have a 24-bit or 32-bit (True Color) color depth.</td>
  </tr>
</table>
</div>


<p><br /></p>

<hr class="break" />



<h1 id="hd005"><a name="file005"></a>5&nbsp;Obtaining and Installing TurboVNC</h1>


<h2 id="hd005001">5.1&nbsp;Installing TurboVNC on Linux</h2>


<h3 id="hd005001001">Font Dependencies</h3>

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

<pre class="verbatim">
Fatal&nbsp;server&nbsp;error:
could&nbsp;not&nbsp;open&nbsp;default&nbsp;font&nbsp;'fixed'
</pre>



<h3 id="hd005001002">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="idx0015"></a> of the 
        <span class="remote"><a href="http://sourceforge.net/projects/turbovnc" class="remote">TurboVNC 
        SourceForge project page</a></span><a name="idx0016"></a>. Packages are 
        provided for RPM-based and Debian-based Linux distributions that contain 
        GLIBC 2.5 or later (including 
        <span class="remote"><a href="http://fedoraproject.org" class="remote">Fedora</a></span><a name="idx0017"></a> 
        6 or later, 
        <span class="remote"><a href="http://www.redhat.com/products/enterprise-linux" class="remote">Red 
        Hat Enterprise 
        Linux</a></span><a name="idx0018"></a>/<span class="remote"><a href="http://www.centos.org/" class="remote">CentOS</a></span><a name="idx0019"></a> 
        5 or later, 
        <span class="remote"><a href="http://www.suse.com" class="remote">SuSE</a></span><a name="idx0020"></a> 
        Linux 
        Enterprise/<span class="remote"><a href="http://www.opensuse.org" class="remote">openSUSE</a></span><a name="idx0021"></a> 
        11 or later, and 
        <span class="remote"><a href="http://www.ubuntu.com" class="remote">Ubuntu</a></span><a name="idx0022"></a> 
        8.04 or later.) <br />
    </li>
    <li class="Ordered-1 Ordered" value="2">
        Log in as root, cd to the directory where you downloaded the binary 
        package, and issue one of the following commands:
        <dl class="Description">
            <dt class="Description-3 Description">RPM-based systems</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
rpm&nbsp;-U&nbsp;turbovnc*.rpm
</pre>

            </dd>
            <dt class="Description-3 Description">Debian-based systems</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
dpkg&nbsp;-i&nbsp;turbovnc*.deb
</pre>

            </dd>
        </dl>
    </li>
</ol>



<h3 id="hd005001003">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&nbsp;~/turbovnc
cd&nbsp;~/turbovnc
rpm2cpio&nbsp;{full&nbsp;path&nbsp;of&nbsp;turbovnc*.rpm}&nbsp;|&nbsp;cpio&nbsp;-idv
</pre>

    </dd>
    <dt class="Description-1 Description">Debian-based systems</dt>
    <dd class="Description-1 Description">
<pre class="verbatim">
dpkg-deb&nbsp;--extract&nbsp;{full&nbsp;path&nbsp;of&nbsp;turbovnc*.deb}&nbsp;~/turbovnc
</pre>

    </dd>
</dl>

<p>Add <em>~/turbovnc</em> 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&nbsp;Installing the TurboVNC Viewer on OS X</h2>

<ol class="Ordered numeric">
    <li class="Ordered-1 Ordered">
        Download the TurboVNC Mac disk image 
        (<code>TurboVNC-</code><em><code>{version}</code></em><code>-OracleJava.dmg</code> 
        or 
        <code>TurboVNC-</code><em><code>{version}</code></em><code>-AppleJava.dmg</code>) 
        from the 
        <span class="remote"><a href="http://sourceforge.net/projects/turbovnc/files/" class="remote">Files 
        area</a></span><a name="idx0023"></a> of the 
        <span class="remote"><a href="http://sourceforge.net/projects/turbovnc" class="remote">TurboVNC 
        SourceForge project page</a></span><a name="idx0024"></a>.
        <div class="important"><p class="important">
        The &ldquo;AppleJava&rdquo; package will work with OS X 10.5 and later.  It uses Apple&rsquo;s distribution of Java, which was pre-installed on versions of OS X prior to 10.7 (but which can be installed on later OS X versions by downloading the &ldquo;Java for OS X&rdquo; package from Apple Support.)  The &ldquo;OracleJava&rdquo; package will work with OS X 10.7 or later and uses the Oracle Java plugin.  In order to achieve the best performance possible with the TurboVNC Viewer, you should generally use Apple Java with older Macs and Oracle Java with newer Macs.  See Section <a href="#MacJavaPerf" class="ref">7.6.3</a> for more details.
        </p></div>
    </li>
    <li class="Ordered-1 Ordered">
        Open the disk image, then open <code>TurboVNC.pkg</code> inside the disk 
        image.  Follow the instructions to install the Mac TurboVNC Viewer.
    </li>
</ol>



<h2 id="hd005003">5.3&nbsp;Installing the TurboVNC Viewer on Windows</h2>

<ol class="Ordered numeric">
    <li class="Ordered-1 Ordered">
        Download the TurboVNC Windows installer package 
        (<code>TurboVNC-</code><em><code>{version}</code></em><code>.exe</code> 
        for 32-bit systems or 
        <code>TurboVNC64-</code><em><code>{version}</code></em><code>.exe</code> 
        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="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>.
    </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&nbsp;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 log in as root, 
download the TurboVNC source tarball 
(<code>turbovnc-</code><em><code>{version}</code></em><code>.tar.gz</code>) 
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>, uncompress 
it, <code>cd&nbsp;turbovnc-</code><em><code>{version}</code></em>, and 
read <code>BUILDING.txt</code> for further instructions on how to build 
TurboVNC from source.</p>



<h2 id="hd005005">5.5&nbsp;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&nbsp;-e&nbsp;turbovnc
</pre>

    </dd>
    <dt class="Description-1 Description">Debian-based systems</dt>
    <dd class="Description-1 Description">
<pre class="verbatim">
dpkg&nbsp;-r&nbsp;turbovnc
</pre>

    </dd>
</dl>



<h3 id="hd005005002">OS X</h3>

<p>Open the &ldquo;Uninstall TurboVNC&rdquo; application, located in the 
&ldquo;TurboVNC&rdquo; Applications folder.  You can also open a 
terminal and execute:</p>

<pre class="verbatim">
sudo&nbsp;/opt/TurboVNC/bin/uninstall
</pre>



<h3 id="hd005005003">Windows</h3>

<p>Use the &ldquo;Programs and Features&rdquo; applet in the Control Panel 
(or the &ldquo;Add or Remove Programs&rdquo; applet if you are running 
Windows XP), or select &ldquo;Uninstall TurboVNC&rdquo; in the 
&ldquo;TurboVNC&rdquo; Start Menu group.</p>

<p><br /></p>

<hr class="break" />



<h1 id="hd006"><a name="file006"></a>6&nbsp;Using TurboVNC</h1>

<p><a name="TurboVNC_Usage"></a></p>


<h2 id="hd006001">6.1&nbsp;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 server machine:
        <dl class="Description">
            <dt class="Description-3 Description">Linux/Un*x/Mac clients</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
ssh&nbsp;{user}@{server}
</pre>

            </dd>
            <dt class="Description-3 Description">Windows clients</dt>
            <dd class="Description-3 Description">
<pre class="verbatim">
&quot;c:\program&nbsp;files\turbovnc\putty&quot;&nbsp;{user}@{server}
</pre>

        Replace <em><code>{user}</code></em> with your username on the TurboVNC 
        server machine and <em><code>{server}</code></em> with the hostname or 
        IP address of that machine.
            </dd>
        </dl>
    </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&nbsp;'TurboVNC:&nbsp;my_server:1&nbsp;(my_user)'&nbsp;started&nbsp;on&nbsp;display&nbsp;my_server: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 &ldquo;TurboVNC Viewer&rdquo; application, located in the 
                 &ldquo;TurboVNC&rdquo; Applications folder.
            </dd>
            <dt class="Description-3 Description">Windows clients</dt>
            <dd class="Description-3 Description">
                 Select &ldquo;TurboVNC Viewer&rdquo; in the &ldquo;TurboVNC&rdquo; 
                 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 &ldquo;VNC server&rdquo; field, 
        then click &ldquo;Connect&rdquo;.
    </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 &ldquo;OK&rdquo; (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 server machine.
    </li>
</ol>



<h2 id="hd006002">6.2&nbsp;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 server machine 
(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 (<code>c:\Program&nbsp;Files\TurboVNC\putty.exe</code> on 
        Windows clients), log into the server machine that is running the 
        TurboVNC session you want to kill.<br /> &hellip; or &hellip;<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&nbsp;-kill&nbsp;:{n}
</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&rsquo;s of all TurboVNC 
sessions currently running under your user account on a particular 
server machine, type the following command:</p>

<pre class="verbatim">
/opt/TurboVNC/bin/vncserver&nbsp;-list
</pre>



<h2 id="hd006003">6.3&nbsp;Using TurboVNC in a Web Browser</h2>

<p>When a TurboVNC session is created, it automatically launches a 
miniature web server that serves up the Java TurboVNC Viewer as either 
an applet or 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.  The Java TurboVNC Viewer, when launched in 
this manner, can use the libjpeg-turbo JNI library to accelerate JPEG 
decoding, if the library is available on the client machine.  If one of 
the official TurboVNC binary packages is installed on the server, then 
it will automatically send the appropriate x86 or x86-64 libjpeg-turbo 
JNI library for Linux, OS X, or Windows clients when launching the 
TurboVNC Viewer using Java Web Start.  If using the Java TurboVNC Viewer 
as an applet, then you can install 
<span class="remote"><a href="http://www.sourceforge.net/projects/libjpeg-turbo/files" class="remote">one 
of the official libjpeg-turbo packages</a></span><a name="idx0029"></a> 
on the client machine to accelerate JPEG decoding.</p>

<p>To use the Java TurboVNC Viewer in a web browser, point your web browser 
to:</p>

<p><code>http://</code><em><code>{turbovnc_server}</code></em><code>:{5800+</code><em><code>n</code></em><code>}</code></p>

<p>where <em><code>{turbovnc_server}</code></em> is the hostname or IP 
address of the TurboVNC server machine, 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_server:1</code>, then point your web browser to:</p>

<p><code>http://my_server:5801</code></p>

<p>This will download a JNLP file to your computer, which you can open in 
Java Web Start.  Add <code>/applet</code> to the URL to launch the 
viewer as a Java applet instead (as of this writing, browsers are 
starting to do away with Java plugins, so running the viewer as an 
applet is more of a legacy feature.)</p>

<p>You can add viewer parameters to the URL using the following format:</p>

<p><code>http://</code><em><code>{turbovnc_server}</code></em><code>:{5800+</code><em><code>n</code></em><code>}?</code><em><code>{param1}</code></em><code>=</code><em><code>{value1}</code></em><code>&amp;</code><em><code>{param2}</code></em><code>=</code><em><code>{value2}</code></em></p>

<p>Examples:</p>

<p><code>http://my_server:5801/applet?embed=1&amp;tunnel=1</code></p>

<p>will run the viewer as an applet in the browser window and tunnel the 
VNC connection through SSH.</p>

<p><code>http://my_server:5801?tunnel=1&amp;samp=2x&amp;quality=80</code></p>

<p>will run the viewer as a JWS app, 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 the Java browser plug-in or JWS 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://{turbovnc_server}:{http_port}</code> (for example, <code>http://my_server:5801</code>) to Java&rsquo;s Exception Site List, which can be found under the &ldquo;Security&rdquo; tab in the Java Control Panel.
</p></div>

<div class="important"><p class="important">
NOTE: On some newer OS X systems, downloading a JNLP file may result in an error: &ldquo;xxxxxxxx.jnlp can&rsquo;t be opened because it it from an unidentified developer.&rdquo;  To work around this, you can either open the JNLP file directly from your Downloads folder, or you can change the application security settings in the &ldquo;Security &amp; Privacy&rdquo; section of System Preferences to allow applications downloaded from anywhere.
</p></div>



<h2 id="hd006004">6.4&nbsp;Deploying the Java TurboVNC Viewer Using Java Web Start</h2>

<p>Accessing the Java TurboVNC Viewer through TurboVNC&rsquo;s built-in 
HTTP server, as described above, is a quick and easy way of running the 
TurboVNC Viewer on machines that don&rsquo;t already have a VNC viewer 
installed (for instance, for the purpose of collaborating with 
colleagues who don&rsquo;t normally use TurboVNC.)</p>

<p>To set up a large-scale zero-install deployment of the Java TurboVNC 
Viewer, it is desirable to serve up the JAR files from a dedicated web 
server.  When deployed using JWS, the Java TurboVNC Viewer provides all 
of the advantages of a standalone native viewer, including native levels 
of performance on most platforms (see <a href="#MacJavaPerf">notes 
regarding performance on Mac platforms</a><a name="idx0030"></a>.)</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 (<code>VncViewer.jar</code>) 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 
        <code>libjpeg-turbo-{version}-jws.zip</code> from libjpeg-turbo 1.3.0 or 
        later (available at 
        <span class="remote"><a href="http://sourceforge.net/projects/libjpeg-turbo/files" class="remote">http://sourceforge.net/projects/libjpeg-turbo/files</a></span><a name="idx0031"></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">
        For large organizations, it is recommended that you obtain your own code 
        signing certificate from a trusted certificate authority and use 
        <code>jarsigner</code> to sign all of the JARs with this 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 <code>TurboVNC.jnlp</code> in the same directory as 
        <code>VncViewer.jar</code> on the web server, and give it the following 
        contents:
<pre class="verbatim">
&lt;?xml&nbsp;version=&quot;1.0&quot;&nbsp;encoding=&quot;utf-8&quot;?&gt;
&lt;jnlp&nbsp;codebase=&quot;{turbovnc_url}&quot;&gt;
&nbsp;&nbsp;&lt;information&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&lt;title&gt;TurboVNC&nbsp;Viewer&lt;/title&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&lt;vendor&gt;The&nbsp;VirtualGL&nbsp;Project&lt;/vendor&gt;
&nbsp;&nbsp;&lt;/information&gt;

&nbsp;&nbsp;&lt;resources&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&lt;j2se&nbsp;version=&quot;1.6+&quot;&nbsp;java-vm-args=&quot;-server&nbsp;-Dsun.java2d.d3d=false&quot;/&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&lt;jar&nbsp;href=&quot;VncViewer.jar&quot;/&gt;
&nbsp;&nbsp;&lt;/resources&gt;

&nbsp;&nbsp;&lt;security&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&lt;all-permissions/&gt;
&nbsp;&nbsp;&lt;/security&gt;

&nbsp;&nbsp;&lt;resources&nbsp;os=&quot;Mac&nbsp;OS&nbsp;X&quot;&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&lt;nativelib&nbsp;href=&quot;ljtosx.jar&quot;/&gt;
&nbsp;&nbsp;&lt;/resources&gt;

&nbsp;&nbsp;&lt;resources&nbsp;os=&quot;Windows&quot;&nbsp;arch=&quot;x86&quot;&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&lt;nativelib&nbsp;href=&quot;ljtwin32.jar&quot;/&gt;
&nbsp;&nbsp;&lt;/resources&gt;

&nbsp;&nbsp;&lt;resources&nbsp;os=&quot;Windows&quot;&nbsp;arch=&quot;amd64&quot;&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&lt;nativelib&nbsp;href=&quot;ljtwin64.jar&quot;/&gt;
&nbsp;&nbsp;&lt;/resources&gt;

&nbsp;&nbsp;&lt;resources&nbsp;os=&quot;Linux&quot;&nbsp;arch=&quot;i386&quot;&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&lt;nativelib&nbsp;href=&quot;ljtlinux32.jar&quot;/&gt;
&nbsp;&nbsp;&lt;/resources&gt;

&nbsp;&nbsp;&lt;resources&nbsp;os=&quot;Linux&quot;&nbsp;arch=&quot;amd64&quot;&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&lt;nativelib&nbsp;href=&quot;ljtlinux64.jar&quot;/&gt;
&nbsp;&nbsp;&lt;/resources&gt;

&nbsp;&nbsp;&lt;application-desc&nbsp;main-class=&quot;com.turbovnc.vncviewer.VncViewer&quot;/&gt;
&lt;/jnlp&gt;
</pre>

        <div class="important"><p class="important">
        NOTE: <code>{turbovnc_url}</code> should be the absolute URL of the TurboVNC Viewer directory on the web server, e.g. <code>http://my_server/turbovnc</code>.
        </p></div>
        This is just a minimal example.  Refer to the 
        <span class="remote"><a href="http://docs.oracle.com/javase/6/docs/technotes/guides/javaws/" class="remote">Java 
        Web Start documentation</a></span><a name="idx0032"></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>{turbovnc_url}/TurboVNC.jnlp</code> in your browser to launch the 
        Java TurboVNC Viewer with full performance.
    </li>
</ul>



<h2 id="hd006005">6.5&nbsp;Securing a TurboVNC Connection</h2>

<p><a name="Secure_TurboVNC_Usage"></a></p>

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

<dl class="Description">
    <dt class="Description-1 Description">Linux/Un*x/Mac clients</dt>
    <dd class="Description-1 Description">
<pre class="verbatim">
ssh&nbsp;-L&nbsp;{5900+n}:localhost:{5900+n}&nbsp;{user}@{server}
</pre>

    </dd>
    <dt class="Description-1 Description">Windows clients</dt>
    <dd class="Description-1 Description">
<pre class="verbatim">
&quot;c:\program&nbsp;files\turbovnc\putty&quot;&nbsp;-L&nbsp;{5900+n}:localhost:{5900+n}&nbsp;{user}@{server}
</pre>

    </dd>
</dl>

<p>Replace <em><code>{user}</code></em> with your username on the TurboVNC 
server machine and <em><code>{server}</code></em> with the hostname or 
IP address of that machine. Replace <em><code>n</code></em> with the X 
display number of the TurboVNC session to which you want to connect.</p>

<p>For instance, if you want to connect to display <code>:1</code> on 
server <code>my_server</code> using user account <code>my_user</code>, 
you would type:</p>

<dl class="Description">
    <dt class="Description-1 Description">Linux/Un*x/Mac clients</dt>
    <dd class="Description-1 Description">
<pre class="verbatim">
ssh&nbsp;-L&nbsp;5901:localhost:5901&nbsp;my_user@my_server
</pre>

    </dd>
    <dt class="Description-1 Description">Windows clients</dt>
    <dd class="Description-1 Description">
<pre class="verbatim">
&quot;c:\program&nbsp;files\turbovnc\putty&quot;&nbsp;-L&nbsp;5901:localhost:5901&nbsp;my_user@my_server
</pre>

    </dd>
</dl>

<p>After the SSH connection has been established, you can then launch the 
TurboVNC Viewer and point it to 
<code>localhost:</code><em><code>{n}</code></em> 
(<code>localhost:1</code> in the above example.)</p>

<div class="important"><p class="important">
You can force PuTTY to use an IPv6 interface for the local end of the tunnel by replacing <code>-L</code> with <code>-L6</code> in the above command line.
</p></div>

<div class="important"><p class="important">
For LAN connections and other high-speed networks, tunneling the TurboVNC connection through PuTTY will reduce performance by as much as 20%.
</p></div>


<h3 id="hd006005001">The <code>-via</code> and <code>-tunnel</code> Command-Line Options</h3>

<p>If you are using the Java TurboVNC Viewer (which you are if you are 
using a Mac, Linux, or Un*x platform), then you can simplify the above 
by using the <code>-via</code> and <code>-tunnel</code> command-line 
options, or the equivalent GUI options (located under the 
&ldquo;Security&rdquo; tab in the Options dialog.)  For instance, running</p>

<pre class="verbatim">
{vncviewer}&nbsp;-via&nbsp;{user}@{server}&nbsp;localhost:{n}
</pre>

<p>or</p>

<pre class="verbatim">
{vncviewer}&nbsp;-tunnel&nbsp;{user}@{server}
</pre>

<p>is the equivalent of running</p>

<pre class="verbatim">
/usr/bin/ssh&nbsp;-L&nbsp;{fp}:localhost:{5900+n}&nbsp;{user}@{server}
{vncviewer}&nbsp;localhost::{fp}
</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, <code>{vncviewer}</code> is the command used to launch the TurboVNC Viewer&ndash; <code>/opt/TurboVNC/bin/vncviewer</code> on Mac/Linux/Un*x systems or <code>c:\Program&nbsp;Files\TurboVNC\vncviewer-java.bat</code> if running the Java TurboVNC Viewer on Windows systems.
</p></div>

<p><code>-tunnel</code> can be used as a shortcut whenever the SSH and VNC 
servers 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: In this release of TurboVNC, the TurboVNC Viewer for Linux/Un*x and Mac platforms is actually the Java TurboVNC Viewer, which is packaged along with the libjpeg-turbo JNI library and necessary glueware to make the viewer behave and perform like a standalone native viewer.  Since the Java TurboVNC Viewer contains an embedded SSH client, the <code>via</code> and <code>tunnel</code> parameters can also be used when the viewer is run as an applet or deployed using Java Web Start.
</p></div>

<div class="important"><p class="important">
The Windows TurboVNC Viewer contains experimental support for the <code>-via</code> and <code>-tunnel</code> command-line options.  Currently, the use of these requires Cygwin OpenSSH, since it is the only version of SSH on Windows that supports detaching the SSH process once the tunnel has been established. When using these options, a console window pops up and remains for the duration of the VNC connection.
</p></div>



<h3 id="hd006005002">Forcing Secure Connections</h3>

<p>Passing an argument of <code>-localhost</code> to <code>vncserver</code> 
will force the TurboVNC Server session to accept inbound connections 
only from the server machine. This effectively forces SSH tunneling to 
be used for remote connections.  If the 
<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 machine.</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 Server 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 machine.</p>



<h2 id="hd006006">6.6&nbsp;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&nbsp;-M&nbsp;/opt/TurboVNC/man&nbsp;vncserver
man&nbsp;-M&nbsp;/opt/TurboVNC/man&nbsp;Xvnc
man&nbsp;-M&nbsp;/opt/TurboVNC/man&nbsp;vncconnect
man&nbsp;-M&nbsp;/opt/TurboVNC/man&nbsp;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&nbsp;/?</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&nbsp;-?
</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&nbsp;Files\TurboVNC\vncviewer-java.bat&nbsp;-?
</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&nbsp;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 &ldquo;luminance&rdquo;) value and a 
         pair of color (Cb &amp; Cr, or &ldquo;chrominance&rdquo;) 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 
         &ldquo;smooth&rdquo; 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 &ldquo;palette threshold&rdquo; (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="idx0033"></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 &ldquo;Options&rdquo; button in the 
&ldquo;TurboVNC Connection&rdquo; 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 &ldquo;encoding methods&rdquo;, 
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">&ldquo;Tight + Perceptually Lossless JPEG&rdquo;</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">&ldquo;Tight + Medium-Quality JPEG&rdquo;</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 &ldquo;Tight + Low-Quality JPEG&rdquo; encoding method and about half the bandwidth of the &ldquo;Tight + Perceptually Lossless JPEG&rdquo; 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">&ldquo;Tight + Low-Quality JPEG&rdquo;</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="idx0034"></a>.  In addition to reducing the JPEG quality to a &ldquo;minimum usable&rdquo; 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">&ldquo;Lossless Tight&rdquo;</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">&ldquo;Lossless Tight + Zlib&rdquo;</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 &ldquo;Tight + Perceptually Lossless JPEG&rdquo; 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 &ldquo;Options&rdquo; button in the &ldquo;TurboVNC 
Connection&rdquo; dialog box or, after connecting to the server, click 
on the Connection Options button in the toolbar.)</p>


<h2 id="hd007001">7.1&nbsp;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 server 
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&ndash; 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 server 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 Server session or by requesting a compression level of 5 or 
higher from the viewer (see below.)</p>



<h2 id="hd007002">7.2&nbsp;Advanced Compression Options</h2>

<p><a name="AdvancedCompression"></a></p>

<p>One of the underlying principles of TurboVNC&rsquo;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 &ldquo;Lossless Tight&rdquo;) 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 &ldquo;Tight + JPEG&rdquo; 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 &ldquo;Lossless Tight&rdquo; 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 &ldquo;Lossless Tight + Zlib&rdquo; 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&nbsp;Lossless Refresh</h2>

<p><a name="LR"></a></p>

<p>Since both of TurboVNC&rsquo;s mathematically lossless encoding methods 
have performance drawbacks, another option for image-quality-critical 
applications is the &ldquo;Lossless Refresh&rdquo; 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&rsquo;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&nbsp;Automatic Lossless Refresh</h2>

<p><a name="ALR"></a></p>

<p>Passing an argument of 
<code>-alr&nbsp;</code><em><code>{timeout}</code></em> 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 &ldquo;ALR-eligible&rdquo; 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 
&ldquo;blinking cursor dilemma.&rdquo;  Certain ill-behaved window 
managers update a small region of the taskbar continuously, even though 
none of the pixels in that region have changed.  Also, certain programs 
have a blinking cursor that may update more frequently than the ALR 
timeout.  Since an ALR is triggered based on a period of inactivity 
relative to the last framebuffer update, these continuous updates 
prevent an ALR from ever being sent. Fortunately, these ill-behaved 
window managers and blinking cursors do not typically use 
<code>X[Shm]PutImage()</code> to perform their updates, 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>

<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 server machine 
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&nbsp;Multithreading</h2>

<p><a name="Multithreading"></a></p>

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

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



<h2 id="hd007006">7.6&nbsp;Maximizing the Performance of the Java TurboVNC Viewer</h2>


<h3 id="hd007006001">Accelerated JPEG Decoding</h3>

<p>The Java TurboVNC Viewer can be used as a standalone app, in which case 
it provides most of the same features as the native TurboVNC viewer.  It 
can also load libjpeg-turbo through JNI to accelerate JPEG decoding, 
which gives the Java viewer similar performance to the native viewer in 
most cases.  The TurboVNC Viewer on Mac and Linux/Un*x platforms is 
simply the Java TurboVNC Viewer packaged in such a way that it behaves 
like a native viewer.  On Windows, the Java TurboVNC Viewer is packaged 
similarly, but it is included alongside the native TurboVNC Viewer, 
giving users a choice between the two. The Java TurboVNC Viewer 
packaging includes the libjpeg-turbo JNI library, which is automatically 
loaded when you launch the TurboVNC Viewer app on Mac, run the 
<code>vncviewer</code> script on Linux/Un*x, run the 
<code>vncviewer-java.bat</code> script on Windows, or launch &ldquo;Java 
TurboVNC Viewer&rdquo; from the Windows Start Menu.  Thus, if you are 
running the Java TurboVNC Viewer in one of those ways, then no further 
action is needed to accelerate it.</p>

<p>If you suspect for whatever reason that JPEG decoding is not being 
accelerated, then the easiest way to check is to open the 
&ldquo;Connection Info&rdquo; dialog (after the connection to the server 
has been established) and verify that the &ldquo;JPEG 
decompression&rdquo; field says &ldquo;Turbo&rdquo;.  If you are 
launching the Java TurboVNC Viewer from the command line, then it will 
also print a warning if it is unable to load libjpeg-turbo.</p>



<h3 id="hd007006002">Windows Blitting Performance</h3>

<p>The default in Java 2D on Windows platforms is to use Direct3D for 
blitting, but in the case of TurboVNC, using GDI blitting is almost 
always much faster. If you are using Java 7 or later, or if you are 
running the Java TurboVNC Viewer using the 
<code>vncviewer-java.bat</code> script or launching it using the Windows 
Start Menu shortcut, then Direct3D blitting will be disabled by default, 
and no further action is necessary.  Otherwise, you should consider 
setting the <code>sun.java2d.d3d</code> system property to 
<code>false</code> (for instance, by passing 
<code>-Dsun.java2d.d3d=false</code> as an argument to 
<code>java</code>.)  You can use the ImageDrawTest benchmark to verify 
whether Direct3D blitting is enabled or disabled.  To do this, execute 
the following command:</p>

<pre class="verbatim">
java&nbsp;-Dsun.java2d.trace=count&nbsp;-cp&nbsp;&quot;c:\Program&nbsp;Files\TurboVNC\Java\VncViewer.jar&quot;&nbsp;com.turbovnc.vncviewer.ImageDrawTest
</pre>

<p>Let the benchmark run for 15 or 20 seconds, then abort it with CTRL-C.  
Looking at the Java 2D trace output will reveal which underlying API 
(such as Windows GDI, OpenGL, Direct3D, etc.) is being used to draw the 
images.</p>



<h3 id="hd007006003">Mac Blitting Performance</h3>

<p><a name="MacJavaPerf"></a></p>

<p>The Oracle Java plugin (Java 7 or later) is used on OS X 10.7 and later 
when launching the Java TurboVNC Viewer as an applet or using Java Web 
Start.  When using TurboVNC as a standalone application, there are two 
packages provided: one that uses the afore-mentioned Oracle Java plugin 
and one that uses Apple&rsquo;s distribution of Java (Java for OS X.)  
The tradeoffs between the two Java flavors are as follows:</p>

<p>Java for OS X:</p>

<ul class="Itemize">
    <li class="Itemize-1 Itemize asterisk">
        Pre-installed on OS X 10.6 and earlier (can be installed on later OS X 
        releases by downloading the Java for OS X package from Apple Support)
    </li>
    <li class="Itemize-1 Itemize asterisk">
        Includes a Quartz-accelerated Java 2D blitter that provides optimal 
        performance for TurboVNC on older Macs (those containing nVidia and 
        Intel HD Graphics GPUs, specifically)
    </li>
</ul>

<p>Oracle Java 7 and later:</p>

<ul class="Itemize">
    <li class="Itemize-1 Itemize asterisk">
        Requires OS X 10.7 or later
    </li>
    <li class="Itemize-1 Itemize asterisk">
        Uses OpenGL for Java 2D blitting, which provides optimal performance for 
        TurboVNC on newer Macs (those containing Intel Iris GPUs, 
        specifically&ndash; Java for OS X does not appear to include Java 2D 
        hardware acceleration for those GPUs)
    </li>
</ul>

<p>If you are unsure which package to use, then you can compare the 
performance of both of them using the ImageDrawTest benchmark:</p>

<pre class="verbatim">
java&nbsp;-cp&nbsp;/Applications/TurboVNC/TurboVNC\&nbsp;Viewer.app/Contents/Resources/Java/VncViewer.jar&nbsp;com.turbovnc.vncviewer.ImageDrawTest
</pre>

<div class="important"><p class="important">
NOTE: if you intend to use the desktop scaling feature in the Java TurboVNC Viewer along with the Oracle Java plugin, then upgrade the plugin to Java 8 Update 40 or later.  Java 8 Update 40 includes a fix for a severe performance issue in the OpenGL Java 2D blitter that affected scaled blitting.
</p></div>



<h3 id="hd007006004">Using the Server VM</h3>

<p>Passing an argument of <code>-server</code> to <code>java</code> when 
launching the Java TurboVNC Viewer is recommended.  This enables the 
adaptive compiler, which performs aggressive code optimizations and 
actually learns how to better optimize a piece of code the more times it 
encounters it.  Such optimizations greatly improve the decoding 
performance for non-JPEG subrectangles.  If you are launching the Java 
TurboVNC Viewer using the Mac app, the <code>vncviewer</code> 
or<code>vncviewer-java.bat</code> scripts, or the Windows Start Menu 
shortcut, then the Server VM is automatically enabled.</p>

<p><br /></p>

<hr class="break" />



<h1 id="hd008"><a name="file008"></a>8&nbsp;TurboVNC Authentication Extensions</h1>

<p>The TurboVNC Server supports four &ldquo;authentication methods&rdquo;, 
which are techniques 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.</p>

<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&rsquo;s home 
         directory on the server machine.  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&rsquo;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 &ldquo;on the fly&rdquo; for the VNC server 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 VNC 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&rsquo;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 scheme supported by TurboVNC (see below) transmits 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 if the server 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>

<p>The TurboVNC Viewer supports three &ldquo;authentication schemes&rdquo;, 
which are protocols used to send authentication credentials from a VNC 
viewer to a VNC server for validation.</p>

<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&rsquo;s standards (56-bit DES was 
         broken by brute force attack in the late 90&rsquo;s.)
    </dd>
    <dt class="Description-1 Description">Unix Login 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 SSH (see Section 
         <a href="#Secure_TurboVNC_Usage" class="ref">6.5</a>.)
    </dd>
</dl>


<h2 id="hd008001">8.1&nbsp;Enabling Authentication Methods</h2>

<p>The default behavior of the TurboVNC Server is for all authentication 
methods except &ldquo;None&rdquo; 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 authentication methods or set the preferred order of the 
authentication methods by editing the server&rsquo;s security 
configuration file.  See the <code>Xvnc</code> man page for more details.</p>

<p>If the VNC server allows multiple authentication methods that support 
multiple authentication schemes, then the VNC viewer&rsquo;s default 
authentication scheme will be determined by the server&rsquo;s preferred 
authentication method.  In this case, the user can override the default 
by passing command-line arguments to <code>vncviewer</code>.  If the VNC 
server prefers an authentication method that supports Standard VNC 
authentication, then the user can force the use of Unix Login 
authentication by passing an argument of 
<code>-user&nbsp;</code><em><code>{user_name}</code></em> to 
<code>vncviewer</code> when connecting to the TurboVNC session.  
Similarly, if the VNC server prefers an authentication method that 
supports Unix Login authentication, then the user can force the use of 
Standard VNC authentication by passing an argument of 
<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 &ldquo;Unix Login&rdquo; or &ldquo;Standard 
VNC&rdquo; in the &ldquo;Security&rdquo; 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 authentication 
methods on a system-wide basis, then the user can choose to disable some 
or all of them for a single TurboVNC session by passing command-line 
arguments to <code>vncserver</code>.  See the <code>vncserver</code> man 
page for more details.</p>



<h2 id="hd008002">8.2&nbsp;Further Reading</h2>

<p>For more detailed information about the TurboVNC authentication 
extensions, refer to the TurboVNC man pages:</p>

<pre class="verbatim">
man&nbsp;-M&nbsp;/opt/TurboVNC/man&nbsp;vncserver
man&nbsp;-M&nbsp;/opt/TurboVNC/man&nbsp;Xvnc
man&nbsp;-M&nbsp;/opt/TurboVNC/man&nbsp;vncpasswd
</pre>

<p><br /></p>

<hr class="break" />



<h1 id="hd009"><a name="file009"></a>9&nbsp;Using TurboVNC with VirtualGL</h1>

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

<p>Since VirtualGL is sending rendered 3D images to the X proxy at a very 
fast rate, the proxy must be able to compress the images very quickly in 
order to keep up.  Unfortunately, however, most X proxies can&rsquo;t.  
They simply aren&rsquo;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 3D images 
from VirtualGL to a client machine without using VirtualGL&rsquo;s 
embedded 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-3D portions of the application&rsquo;s 
        GUI are sent over the network using remote X11, which will create 
        performance problems on high-latency networks (such as broadband or 
        long-haul fibre.) Non-3D portions of the application&rsquo;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 images do not contain very many 
        unique colors (for instance, CAD applications in wireframe mode), the 
        hybrid encoding methods used by TurboVNC will generally use less network 
        bandwidth than the pure JPEG encoding method used by the VGL Transport.
    </li>
    <li class="Itemize-1 Itemize asterisk">
        TurboVNC provides two lossless compression modes, one of which is 
        designed to reduce server CPU usage on gigabit networks and the other of 
        which is designed to provide reasonable performance on wide-area 
        networks (at the expense of higher server CPU usage.)  The VGL 
        Transport&rsquo;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 current VNC desktop to the 
        client. A user connecting over a low-bandwidth connection can use 
        low-quality JPEG to achieve the best performance when manipulating the 
        3D model, then they can request a lossless refresh when they are ready 
        to study the model in detail.
    </li>
    <li class="Itemize-1 Itemize asterisk">
        The TurboVNC Server can be configured to send a mathematically lossless 
        copy of certain regions of the screen during periods of inactivity 
        (Automatic Lossless Refresh.)
    </li>
    <li class="Itemize-1 Itemize asterisk">
        TurboVNC provides rudimentary collaboration capabilities.  Multiple 
        clients can simultaneously view the same TurboVNC session and pass 
        around control of the keyboard and mouse.
    </li>
    <li class="Itemize-1 Itemize asterisk">
        The TurboVNC Viewer is stateless.  If the network hiccups or the viewer 
        is otherwise disconnected, the session continues to run on the server 
        and can be rejoined from any machine on the network.
    </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 
        &ldquo;virtual desktop&rdquo;, which displays in a single window on the 
        client machine.
    </li>
    <li class="Itemize-1 Itemize asterisk">
        TurboVNC will generally	require about 20% more server CPU cycles to 
        maintain the same frame rate as the VGL Transport, both because it has 
        to compress more pixels in each frame	(an entire desktop rather than a 
        single window) and because it has to perform 2D (X11) rendering as well 
        as 3D rendering.
    </li>
    <li class="Itemize-1 Itemize asterisk">
        TurboVNC does not support quad-buffered stereo or transparent overlays.
    </li>
</ul>



<h2 id="hd009001">9.1&nbsp;Using TurboVNC and VirtualGL on the Same Server</h2>

<p><a name="TurboVNC_Usage_Local"></a></p>

<p>The most common (and optimal) way to use TurboVNC is to set it up on the 
same server that is running VirtualGL.  This allows VirtualGL to send 
its rendered 3D images to TurboVNC through shared memory rather than 
sending them over a network.</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&nbsp;[vglrun&nbsp;options]&nbsp;{application_executable_or_script}&nbsp;{arguments}
</pre>

        The TurboVNC startup script sets the <code>VGL_COMPRESS</code> 
        environment variable to <code>0</code>, which will automatically enable 
        the X11 Transport within VirtualGL.
    </li>
</ol>



<h2 id="hd009002">9.2&nbsp;Using TurboVNC When VirtualGL Is Running on a Different Machine</h2>

<p><a name="TurboVNC_Usage_Remote"></a></p>

<div class="figure">
<img src="vgltransportservernetwork.png" alt="vgltransportservernetwork" class="figure" id="imgid_8" name="imgid_8"/>
</div>

<p>If TurboVNC and VirtualGL are running on different servers, then it is 
desirable to use the VGL Transport to send images from the VirtualGL 
server to the TurboVNC server.  It is also desirable to disable image 
compression in the VGL Transport.  Otherwise, the images would have to 
be compressed by the VirtualGL server, decompressed by the VirtualGL 
Client, then recompressed by the TurboVNC Server, which is a waste of 
CPU resources. However, sending images uncompressed over a network 
requires a fast network (generally, Gigabit Ethernet or faster), so 
there needs to be a fast link between the VirtualGL server and the 
TurboVNC server for this procedure to perform well.</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&nbsp;{user}@{server}
</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&rsquo;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&nbsp;rgb</code> to <code>vglrun</code> achieves the same effect.
        </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&nbsp;[vglrun&nbsp;options]&nbsp;{application_executable_or_script}&nbsp;{arguments}
</pre>

    </li>
</ol>

<p><br /></p>

<hr class="break" />



<h1 id="hd0010"><a name="file010"></a>10&nbsp;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 a TurboVNC server and a 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="idx0035"></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&nbsp;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 &ldquo;compress&rdquo; 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&nbsp;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 &ldquo;bad 
        subencoding value&rdquo; 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&rsquo;t support this. <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&nbsp;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 and RRE.  None of these encoding types can be selected 
from the TurboVNC Viewer GUI, but Hextile or ZRLE will be selected 
automatically when connecting to a RealVNC server.  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, ZRLE, and 
RRE, the TurboVNC Server also supports the 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&rsquo;s worth of 
bandwidth (it also doesn&rsquo;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, RRE, and ZRLE work.</p>

<p><br /></p>

<hr class="break" />



<h1 id="hd0011"><a name="file011"></a>11&nbsp;Advanced Configuration</h1>


<h2 id="hd0011001">11.1&nbsp;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&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></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&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></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&nbsp;=&nbsp;</code><em><code>{c}</code></em></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">100</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&nbsp;=&nbsp;</code><em><code>{s}</code></em></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">256</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&rsquo;s 
        ability to efficiently split rectangles into subrectangles, thus 
        increasing server 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&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></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&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></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">Disabled</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>VGL_NTHREADS&nbsp;=&nbsp;</code><em><code>{n}</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Use <em><code>{n}</code></em> threads 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</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&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></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&nbsp;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&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></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="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>


<p>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 &ldquo;%&rdquo; 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&nbsp;-f&nbsp;-L&nbsp;%L:%H:%R&nbsp;%G&nbsp;sleep&nbsp;20</code> 
(or 
<code>c:\cygwin\bin\ssh.exe&nbsp;-f&nbsp;-L&nbsp;%L:%H:%R&nbsp;%G&nbsp;sleep&nbsp;20</code> 
if using the Windows native viewer.)</p>

<p>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 &ldquo;%&rdquo; 
character, and uses the resulting command line to establish the secure 
tunnel to the VNC server.  If <code>VNC_TUNNEL_CMD</code> is not set, 
then this command line defaults to 
<code>/usr/bin/ssh&nbsp;-f&nbsp;-L&nbsp;%L:localhost:%R&nbsp;%H&nbsp;sleep&nbsp;20</code> 
(or 
<code>c:\cygwin\bin\ssh.exe&nbsp;-f&nbsp;-L&nbsp;%L:localhost:%R&nbsp;%H&nbsp;sleep&nbsp;20</code> 
if using the Windows native viewer.)</p>

<p>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):</p>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="standard"><code>%%</code></td>
    <td class="standard">A literal &ldquo;%&rdquo;</td>
  </tr>
  <tr class="standard">
    <td class="standard"><code>%G</code></td>
    <td class="standard">gateway machine name</td>
  </tr>
  <tr class="standard">
    <td class="standard"><code>%H</code></td>
    <td class="standard">remote VNC machine name (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>




<h2 id="hd0011003">11.3&nbsp;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&nbsp;-Dmy.system.property={value}&nbsp;-jar&nbsp;MyClass.jar
</pre>

<p>However, since TurboVNC hides the Java command line inside of its 
startup scripts (or inside of an application bundle on OS X), 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&rsquo;t have access 
to the command line.  For instance, on Linux you could execute:</p>

<pre class="verbatim">
JAVA_TOOL_OPTIONS=-Dturbovnc.turbojpeg=0&nbsp;/opt/TurboVNC/bin/vncviewer
</pre>

<p>to start the TurboVNC Viewer without JPEG acceleration.</p>

<p>Refer to the default <code>index.vnc</code> and 
<code>TurboVNC.jnlp</code> files installed with the TurboVNC Server for 
an example of how to specify Java command-line arguments in an applet or 
Java Web Start environment.</p>

<p><a name="turbovnc.forcealpha"></a></p>

<div class="table">
<table class="standard">
  <tr class="standard">
    <td class="high standard">Java System Property</td>
    <td class="standard"><code>turbovnc.forcealpha&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></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&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></td>
  </tr>
  <tr class="standard">
    <td class="high standard">Summary</td>
    <td class="standard">Disable/enable the use of the OS X full-screen application feature</td>
  </tr>
  <tr class="standard">
    <td class="high standard">Default Value</td>
    <td class="standard">Enabled if running on OS X 10.7 or later</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 10.7 and later, if available.  Disabling this property will force 
        the viewer to use its own built-in cross-platform 
        &ldquo;pseudo-full-screen&rdquo; 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&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></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 &ldquo;Copy&rdquo; 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 &ldquo;Paste&rdquo; 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&rsquo;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&rsquo;s CLIPBOARD selection (in other words, 
        you will have to explicitly paste the server&rsquo;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.swingdb&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></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 <code>VNC_TUNNEL_CMD</code> 
        environment variable 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&nbsp;=&nbsp;</code><em><code>0&nbsp;|&nbsp;1</code></em></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 <code>VNC_VIA_CMD</code> 
        environment variable above for more details.
    </dd>
</dl>

<p><br /></p>


</body>
</html>