forked from TurboVNC/turbovnc
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
3035 lines (2590 loc) · 135 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!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="2015-08-03T18:45:26">
<meta name="generator" content="deplate.rb 0.8.5">
<title>User’s Guide for TurboVNC 2.1</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’s Guide for TurboVNC 2.1</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>
<li class="Itemize-3 hd">
<a href="#hd009003" class="hd">9.3 NV-CONTROL Emulation</a>
</li>
</ul>
</li>
<li class="Itemize-1 hd">
<a href="#hd0010" class="hd">10 Compatibility Guide</a>
<ul class="hd">
<li class="Itemize-3 hd">
<a href="#hd0010001" class="hd">10.1 TightVNC or TigerVNC Servers</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd0010002" class="hd">10.2 TightVNC or TigerVNC Viewers</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd0010003" class="hd">10.3 RealVNC</a>
</li>
</ul>
</li>
<li class="Itemize-1 hd">
<a href="#hd0011" class="hd">11 Advanced Configuration</a>
<ul class="hd">
<li class="Itemize-3 hd">
<a href="#hd0011001" class="hd">11.1 Server Settings</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd0011002" class="hd">11.2 Client Settings</a>
</li>
<li class="Itemize-3 hd">
<a href="#hd0011003" class="hd">11.3 Java Client Settings</a>
</li>
</ul>
</li>
</ul>
</div></div>
<a name="file000"></a>
<p><br /></p>
<hr class="break" />
<h1 id="hd001"><a name="file001"></a>1 Legal Information</h1>
<p><img src="somerights20.png" alt="somerights20" class="inline" id="imgid_0" name="imgid_0"/></p>
<p>This document and all associated illustrations are licensed under the
<span class="remote"><a href="http://creativecommons.org/licenses/by/2.5/" class="remote">Creative
Commons Attribution 2.5 License</a></span><a name="idx001"></a>. Any
works that contain material derived from this document must cite The
VirtualGL Project as the source of the material and list the current URL
for the TurboVNC web site.</p>
<p>The official TurboVNC binaries contain libjpeg-turbo, which is based in
part on the work of the Independent JPEG Group.</p>
<p>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 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 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 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 “tightest” compression mode in
TightVNC 1.3.x while using only typically 15-20% of the CPU time of the
latter. Using non-default settings, TurboVNC can also match the best
compression ratios produced by TightVNC 1.3.x for 2D workloads (see
Section <a href="#AdvancedCompression" class="ref">7.2</a>.)</p>
<p>All VNC implementations, including TurboVNC, use the RFB (remote
framebuffer) protocol to send “framebuffer updates” from the
VNC server to any connected “viewers.” Each framebuffer
update can contain multiple “rectangles” (regions that have
changed since the last update.) As with TightVNC, TurboVNC analyzes
each rectangle, splits it into multiple “subrectangles”, and
attempts to encode each subrectangle using the “subencoding
type” that will provide the most efficient compression, given the
number of unique colors in the subrectangle. The process by which
TurboVNC does this is referred to as an “encoding method.”
A rectangle is first analyzed to determine if any significant portion of
it is solid, and if so, that portion is encoded as a bounding box and a
fill color (“Solid subencoding.”) Of the remaining
subrectangles, those with only two colors are encoded as a
1-bit-per-pixel bitmap with a 2-color palette (“Mono
subencoding”), those with low numbers of unique colors are encoded
as a color palette and an 8-bit-per-pixel bitmap (“Indexed color
subencoding”), and subrectangles with high numbers of unique
colors are encoded using either JPEG or arrays of RGB pixels (“Raw
subencoding”), depending on the encoding method. zlib can
optionally be used to compress the indexed color, mono and raw
subrectangles.</p>
<p>Part of TurboVNC’s speedup comes from the use of libjpeg-turbo,
the same high-speed SIMD-optimized JPEG codec used by VirtualGL.
However, TurboVNC also eliminates the CPU-hungry smoothness detection
routines that TightVNC uses to determine whether a subrectangle is a
good candidate for JPEG compression, and TurboVNC’s encoding
methods tend to favor the use of JPEG more, since it is now generally
the fastest subencoding type. Furthermore, TurboVNC eliminates buffer
copies, it maximizes network efficiency by splitting framebuffer updates
into relatively large subrectangles, and it uses only the zlib
compression levels that can be shown to have a measurable performance
benefit.</p>
<p>TurboVNC is the product of extensive research, in which many different
permutations of the TightVNC encoder were benchmarked at the low level
against a variety of captured RFB sessions that simulate real-world
application workloads, both 2D and 3D. For more information on the
research leading to TurboVNC’s encoder design, see
<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 clients 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">
“Lossless refresh” allows a viewer to request a lossless
copy of the current screen image. This is useful in situations in which
image quality is critical but the network is too slow to support sending
a high-quality image for every frame. Lossless refreshes can be
performed manually when a certain hotkey is pressed, or the TurboVNC
Server can be configured to send a lossless refresh automatically if the
user stops interacting with the application for a certain period of time.
</li>
<li class="Itemize-1 Itemize asterisk">
High-performance zero-install Java viewer, which can be launched via
Java Web Start using TurboVNC’s built-in web server or deployed on
a dedicated web server. By calling libjpeg-turbo through JNI, the Java
TurboVNC Viewer achieves similar levels of performance to the native
TurboVNC Viewer, 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 “modern” hardware, TurboVNC is capable of streaming 50+
Megapixels/second over a 100 Megabit/second local area network with
perceptually lossless image quality. TurboVNC can stream between 10 and
12 Megapixels/second over a 5 Megabit/second broadband connection at
reduced (but usable) image quality.</p>
<p>TurboVNC is compatible with other VNC distributions. See Chapter
<a href="#Compatibility" class="ref">10</a> for more information. The
official TurboVNC binaries can be installed onto the same system as
other VNC distributions without interference.</p>
<p><br /></p>
<hr class="break" />
<h1 id="hd004"><a name="file004"></a>4 System Requirements</h1>
<h2 id="hd004001">4.1 Linux/x86 and Other x86 Un*x Operating Systems</h2>
<div class="table">
<table class="standard">
<thead class="standard">
<tr class="head ">
<th class="head standard"></th>
<th class="head standard">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 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 (“Leopard”) 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 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 Obtaining and Installing TurboVNC</h1>
<h2 id="hd005001">5.1 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 server error:
could not open default font '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 -U turbovnc*.rpm
</pre>
</dd>
<dt class="Description-3 Description">Debian-based systems</dt>
<dd class="Description-3 Description">
<pre class="verbatim">
dpkg -i turbovnc*.deb
</pre>
</dd>
</dl>
</li>
</ol>
<h2 id="hd005002">5.2 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 “AppleJava” package will work with OS X 10.5 and later. It uses Apple’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 “Java for OS X” package from Apple Support.) The “OracleJava” 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 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 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 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 Uninstalling TurboVNC</h2>
<h3 id="hd005005001">Linux</h3>
<p>As root, issue one of the following commands:</p>
<dl class="Description">
<dt class="Description-1 Description">RPM-based systems</dt>
<dd class="Description-1 Description">
<pre class="verbatim">
rpm -e turbovnc
</pre>
</dd>
<dt class="Description-1 Description">Debian-based systems</dt>
<dd class="Description-1 Description">
<pre class="verbatim">
dpkg -r turbovnc
</pre>
</dd>
</dl>
<h3 id="hd005005002">OS X</h3>
<p>Open the “Uninstall TurboVNC” application, located in the
“TurboVNC” Applications folder. You can also open a
terminal and execute:</p>
<pre class="verbatim">
sudo /opt/TurboVNC/bin/uninstall
</pre>
<h3 id="hd005005003">Windows</h3>
<p>Use the “Programs and Features” applet in the Control Panel
(or the “Add or Remove Programs” applet if you are running
Windows XP), or select “Uninstall TurboVNC” in the
“TurboVNC” Start Menu group.</p>
<p><br /></p>
<hr class="break" />
<h1 id="hd006"><a name="file006"></a>6 Using TurboVNC</h1>
<p><a name="TurboVNC_Usage"></a></p>
<h2 id="hd006001">6.1 Starting and Connecting to a TurboVNC Session</h2>
<h3 id="hd006001001">Procedure</h3>
<ol class="Ordered numeric">
<li class="Ordered-1 Ordered">
Open a new Command Prompt/terminal window on your client machine.
</li>
<li class="Ordered-1 Ordered">
In the new Command Prompt/terminal window, open a Secure Shell (SSH)
session into the TurboVNC 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 {user}@{server}
</pre>
</dd>
<dt class="Description-3 Description">Windows clients</dt>
<dd class="Description-3 Description">
<pre class="verbatim">
"c:\program files\turbovnc\putty" {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 'TurboVNC: my_server:1 (my_user)' started on display 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 “TurboVNC Viewer” application, located in the
“TurboVNC” Applications folder.
</dd>
<dt class="Description-3 Description">Windows clients</dt>
<dd class="Description-3 Description">
Select “TurboVNC Viewer” in the “TurboVNC”
Start Menu group.
</dd>
</dl>
</li>
<li class="Ordered-1 Ordered">
A small dialog box will appear. <br /><br />
<div class="table">
<table class="standard">
<thead class="standard">
<tr class="head ">
<th class="head standard">Windows TurboVNC Viewer</th>
<th class="head standard">Linux/Un*x/Mac (Java) TurboVNC Viewer</th>
</tr>
</thead>
<tr class="standard">
<td class="standard"><img src="newconn-win.png" alt="newconn-win" class="inline" id="imgid_1" name="imgid_1"/></td>
<td class="standard"><img src="newconn-java.png" alt="newconn-java" class="inline" id="imgid_2" name="imgid_2"/></td>
</tr>
</table>
</div>
<br /> Enter the X display name (hostname, or IP address, and display
number) of the TurboVNC session in the “VNC server” field,
then click “Connect”.
</li>
<li class="Ordered-1 Ordered">
Another dialog box appears, prompting for the password (if standard VNC
authentication is being used) or for the username and password (if Unix
login authentication is being used.) <br /><br />
<div class="table">
<table class="standard">
<thead class="standard">
<tr class="head ">
<th class="head standard"></th>
<th class="head standard">Windows TurboVNC Viewer</th>
<th class="head standard">Linux/Un*x/Mac (Java) TurboVNC Viewer</th>
</tr>
</thead>
<tr class="standard">
<td class="standard">Standard VNC Authentication Dialog</td>
<td class="standard"><img src="vncauth-win.png" alt="vncauth-win" class="inline" id="imgid_3" name="imgid_3"/></td>
<td class="standard"><img src="vncauth-java.png" alt="vncauth-java" class="inline" id="imgid_4" name="imgid_4"/></td>
</tr>
<tr class="standard">
<td class="standard">Unix Login Authentication Dialog</td>
<td class="standard"><img src="unixauth-win.png" alt="unixauth-win" class="inline" id="imgid_5" name="imgid_5"/></td>
<td class="standard"><img src="unixauth-java.png" alt="unixauth-java" class="inline" id="imgid_6" name="imgid_6"/></td>
</tr>
</table>
</div>
<br /> Enter the VNC session password or the Unix username/password and
click “OK” (Windows) or press Enter (Linux/Un*x/Mac.)
<br /><br /> A TurboVNC desktop window should appear on your client
machine. This window contains a virtual desktop with which you can
interact to launch X-Windows applications on the TurboVNC server machine.
</li>
</ol>
<h2 id="hd006002">6.2 Disconnecting and Killing a TurboVNC Session</h2>
<p>Closing the TurboVNC Viewer disconnects from the TurboVNC session, but
the TurboVNC session will remain running on the TurboVNC 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 Files\TurboVNC\putty.exe</code> on
Windows clients), log into the server machine that is running the
TurboVNC session you want to kill.<br /> … or …<br />
Using the TurboVNC Viewer, connect to the TurboVNC session that you want
to kill, and open a new terminal in that TurboVNC session.
</li>
<li class="Ordered-1 Ordered">
Type the following command:
<pre class="verbatim">
/opt/TurboVNC/bin/vncserver -kill :{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’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 -list
</pre>
<h2 id="hd006003">6.3 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>&</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&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&samp=2x&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’s Exception Site List, which can be found under the “Security” tab in the Java Control Panel.
</p></div>
<div class="important"><p class="important">
NOTE: On some newer OS X systems, downloading a JNLP file may result in an error: “xxxxxxxx.jnlp can’t be opened because it it from an unidentified developer.” To work around this, you can either open the JNLP file directly from your Downloads folder, or you can change the application security settings in the “Security & Privacy” section of System Preferences to allow applications downloaded from anywhere.
</p></div>
<h2 id="hd006004">6.4 Deploying the Java TurboVNC Viewer Using Java Web Start</h2>
<p>Accessing the Java TurboVNC Viewer through TurboVNC’s built-in
HTTP server, as described above, is a quick and easy way of running the
TurboVNC Viewer on machines that don’t already have a VNC viewer
installed (for instance, for the purpose of collaborating with
colleagues who don’t normally use TurboVNC.)</p>
<p>To set up a large-scale 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">
<?xml version="1.0" encoding="utf-8"?>
<jnlp codebase="{turbovnc_url}">
<information>
<title>TurboVNC Viewer</title>
<vendor>The VirtualGL Project</vendor>
</information>
<resources>
<j2se version="1.6+" java-vm-args="-server -Dsun.java2d.d3d=false"/>
<jar href="VncViewer.jar"/>
</resources>
<security>
<all-permissions/>
</security>
<resources os="Mac OS X">
<nativelib href="ljtosx.jar"/>
</resources>
<resources os="Windows" arch="x86">
<nativelib href="ljtwin32.jar"/>
</resources>
<resources os="Windows" arch="amd64">
<nativelib href="ljtwin64.jar"/>
</resources>
<resources os="Linux" arch="i386">
<nativelib href="ljtlinux32.jar"/>
</resources>
<resources os="Linux" arch="amd64">
<nativelib href="ljtlinux64.jar"/>
</resources>
<application-desc main-class="com.turbovnc.vncviewer.VncViewer"/>
</jnlp>
</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