undo previous commit and redo it properly via a patch file instead of
[invirt/packages/invirt-vnc-client.git] / README
1
2   TightVNC Java Viewer version 1.3.9
3
4 ======================================================================
5
6 This distribution is based on the standard VNC source and includes new
7 TightVNC-specific features and fixes, such as additional low-bandwidth
8 optimizations, major GUI improvements, and more.
9
10         Copyright (C) 1999 AT&T Laboratories Cambridge.
11         Copyright (C) 2000 Tridia Corp.
12         Copyright (C) 2002-2003 RealVNC Ltd.
13         Copyright (C) 2001-2004 HorizonLive.com, Inc.
14         Copyright (C) 2000-2007 Constantin Kaplinsky
15         Copyright (C) 2000-2007 TightVNC Group
16         All rights reserved.
17
18 This software is distributed under the GNU General Public Licence as
19 published by the Free Software Foundation. See the file LICENCE.TXT for the
20 conditions under which this software is made available. TightVNC also
21 contains code from other sources. See the Acknowledgements section below, and
22 the individual files for details of the conditions under which they are made
23 available.
24
25
26 Compiling from the sources
27 ==========================
28
29 To compile all the .java files to .class files, simply do:
30
31         % make all
32
33 This will also generate a JAR (Java archive) file containing all the classes. 
34 Most JVM (Java Virtual Machine) implementations are able to use either a set
35 of .class files, or the JAR archive.
36
37
38 Installation
39 ============
40
41 There are three basic ways to use TightVNC Java viewer:
42
43   1. Running applet as part of TightVNC server installation.
44
45      Both the Unix and Windows versions of TightVNC servers include small
46      built-in HTTP server which can serve Java viewer to Web clients. This
47      enables easy Web access to the shared desktop without need to install
48      any software on the client computer. Unix and Windows versions of
49      TightVNC servers are different in the way they store the .class and .jar
50      files: the Unix server (Xvnc) is able to serve any set of files present
51      in a particular directory, while the Windows server (WinVNC) has all the
52      .class and .jar files inside the WinVNC executable file. Therefore, for
53      Xvnc, it's enough to copy the files into a correct directory, but for
54      WinVNC, the server binaries should be rebuild if the built-in Java
55      viewer should be updated.
56
57      To install the Java viewer under Xvnc, copy all the .class files, the
58      .jar file and the .vnc files to an installation directory (e.g.
59      /usr/local/vnc/classes):
60
61          cp *.class *.jar *.vnc /usr/local/vnc/classes
62
63      Also, make sure that the vncserver script is configured to point to the
64      installation directory (see the Xvnc manual page for the description of
65      the -httpd command-line option).
66
67   2. Running applet hosted on a standalone Web server.
68
69      Another possibility to use the Java viewer is to install it under a
70      fully-functional HTTP server such as Apache or IIS. Obviously, this
71      method requires running an HTTP server, and due to the Java security
72      restrictions, it's also required that the server should be installed on
73      the same machine which is running the TightVNC server. In this case,
74      installation is simply copying the .class and .jar files into a
75      directory that is under control of the HTTP server. Also, an HTML page
76      should be created which will act as a the base document for the viewer
77      applet (see an example named index.html in this distribution).
78
79      NOTE: Provided index.html page is an example only. Before using that
80      file, edit it with a text editor. See more information inside
81      index.html.
82
83   3. Running the viewer as a standalone application.
84
85      Finally, the Java viewer can be executed locally on the client machine,
86      but this method requires installation of either JRE (Java Runtime
87      Environment) or JDK (Java Development Kit). If all the .class files are
88      in the current directory, the Java viewer can be executed like this,
89      from the command line:
90
91          java VncViewer HOST vnchost PORT 5900
92
93      The parameters HOST and PORT are required, but there is a number of
94      optional parameters as well (see the Parameters section below).
95
96 Parameters
97 ==========
98
99 TightVNC Java viewer supports a number of parameters allowing you to
100 customize its behavior. Most parameters directly correspond to the settings
101 found in the Options window. However, there are parameters that do not
102 correspond to those settings. For such parameters, you can see a note "no GUI
103 equivalent", in the documentation below.
104
105 Parameters can be specified in one of the two ways, depending on how the Java
106 viewer is used:
107
108   1. When the Java viewer is run as an applet (embedded within an HTML
109      document), parameters should be specified in the <PARAM> HTML tags,
110      within the appropriate <APPLET> section. Here is an example:
111
112     <APPLET CODE=VncViewer.class ARCHIVE=VncViewer.jar WIDTH=400 HEIGHT=300>
113       <PARAM NAME="PORT" VALUE=5901>
114       <PARAM NAME="Scaling factor" VALUE=50>
115     </APPLET>
116
117   2. When run as a standalone application, the Java viewer reads parameters
118      from the command line. Command-line arguments should be specified in
119      pairs -- first goes parameter name, then parameter value. Here is a
120      command line example:
121
122      java VncViewer HOST vnchost PORT 5901 "Scaling factor" 50
123
124 Both parameter names and their values are case-insensitive. The only
125 exception is the "PASSWORD" parameter, as VNC passwords are case-sensitive.
126
127 Here is the complete list of parameters supported in TightVNC Java viewer:
128
129 --> "HOST" (no GUI equivalent)
130
131     Value: host name or IP address of the VNC server.
132     Default: in applet mode, the host from which the applet was loaded.
133
134     This parameter tells the viewer which server to connect to. It's not
135     needed in the applet mode, because default Java security policy allow
136     connections from applets to the only one host anyway, and that is the
137     host from which the applet was loaded. However, this parameter is
138     required if the viewer is used as a standalone application.
139
140 --> "PORT" (no GUI equivalent)
141
142     Value: TCP port number on the VNC server.
143     Default: none.
144
145     This parameter is required in all cases. Note that this port is not the
146     one used for HTTP connection from the browser, it is the port used for
147     RFB connection. Usually, VNC servers use ports 58xx for HTTP connections,
148     and ports 59xx for RFB connections. Thus, most likely, this parameter
149     should be set to something like 5900, 5901 etc.
150
151 --> "PASSWORD"
152
153     Value: session password in plain text.
154     Default: none, ask user.
155
156     DO NOT EVER USE THIS PARAMETER, unless you really know what you are
157     doing. It's extremely dangerous from the security point of view. When
158     this parameter is set, the viewer won't ever ask for a password.
159
160 --> "ENCPASSWORD"
161
162     Value: encrypted session password in hex-ascii.
163     Default: none, ask user.
164
165     The same as the "PASSWORD" parameter but DES-encrypted using a fixed key.
166     Its value should be represented in hex-ascii e.g. "494015f9a35e8b22".
167     This parameter has higher priority over the "PASSWORD" parameter. DO NOT
168     EVER USE THIS PARAMETER, unless you really know what you are doing. It's
169     extremely dangerous from the security point of view, and encryption does
170     not actually help here since the decryption key is always known.
171
172 --> "Encoding"
173
174     Values: "Auto", "Raw", "RRE", "CoRRE", "Hextile", "ZRLE", "Zlib", "Tight".
175     Default: "Auto".
176
177     The preferred encoding. If the value is "Auto", then the viewer will
178     continuously estimate average network throughput and request encodings
179     that are appropriate for current connection speed. "Hextile" is an
180     encoding that was designed for fast networks, while "Tight" is better
181     suited for low-bandwidth connections. From the other side, "Tight"
182     decoder in the TightVNC Java viewer seems to be more efficient than
183     "Hextile" decoder so it may be ok for fast networks too. "ZRLE" encoding
184     is similar to "Tight", but it does not support JPEG compression and
185     compression levels. Unlike "Tight" encoding, "ZRLE" is supported in
186     recent versions of RealVNC products. Other encodings are not efficient
187     and provided for compatibility reasons.
188
189 --> "Compression level"
190
191     Values: "Default", "1", "2", "3", "4", "5", "6", "7", "8", "9".
192     Default: "Default". ;-)
193
194     Use specified compression level for "Tight" and "Zlib" encodings. Level 1
195     uses minimum of CPU time on the server but achieves weak compression
196     ratios. Level 9 offers best compression but may be slow in terms of CPU
197     time consumption on the server side. Use high levels with very slow
198     network connections, and low levels when working over higher-speed
199     networks. The "Default" value means that the server's default compression
200     level should be used.
201
202 --> "JPEG image quality"
203
204     Values: "JPEG off", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9".
205     Default: "6".
206
207     Use the specified image quality level in "Tight" encoding. Quality level
208     0 denotes bad image quality but very impressive compression ratios, while
209     level 9 offers very good image quality at lower compression ratios. If
210     the value is "JPEG off", the server will not use lossy JPEG compression
211     in "Tight" encoding.
212
213 --> "Cursor shape updates"
214
215     Values: "Enable", "Ignore", "Disable".
216     Default: "Enable".
217
218     Cursor shape updates is a protocol extension used to handle remote cursor
219     movements locally on the client side, saving bandwidth and eliminating
220     delays in mouse pointer movement. Note that current implementation of
221     cursor shape updates does not allow a client to track mouse cursor
222     position at the server side. This means that clients would not see mouse
223     cursor movements if mouse was moved either locally on the server, or by
224     another remote VNC client. Set this parameter to "Disable" if you always
225     want to see real cursor position on the remote side. Setting this option
226     to "Ignore" is similar to "Enable" but the remote cursor will not be
227     visible at all. This can be a reasonable setting if you don't care about
228     cursor shape and don't want to see two mouse cursors, one above another.
229
230 --> "Use CopyRect"
231
232     Values: "Yes", "No".
233     Default: "Yes".
234
235     The "CopyRect" encoding saves bandwidth and drawing time when parts of
236     the remote screen are moving around. Most likely, you don't want to
237     change this setting.
238
239 --> "Restricted colors"
240
241     Values: "Yes", "No".
242     Default: "No".
243
244     If set to "No", then 24-bit color format is used to represent pixel data. 
245     If set to "Yes", then only 8 bits are used to represent each pixel. 8-bit
246     color format can save bandwidth, but colors may look very inaccurate.
247
248 --> "Mouse buttons 2 and 3"
249
250     Values: "Normal", "Reversed".
251     Default: "Normal".
252
253     If set to "Reversed", then right mouse button (button 2) will act as it
254     was middle mouse button (button 3), and vice versa.
255
256 --> "View only"
257
258     Values: "Yes", "No".
259     Default: "No".
260
261     If set to "Yes", then all keyboard and mouse events in the desktop window
262     will be silently ignored and will not be passed to the remote side.
263
264 --> "Scale remote cursor"
265
266     Values: "No", "50%", "75%", "125%", "150%".
267     Default: "No".
268
269     If a percentage value is specified, the remote cursor is reduced
270     or enlarged accordingly. Scaling takes place only when "View only"
271     is set to "No", and "Cursor shape updates" is set to "Enable".
272
273 --> "Share desktop"
274
275     Values: "Yes", "No".
276     Default: "Yes".
277
278     Share the connection with other clients on the same VNC server. The exact
279     behaviour in each case depends on the server configuration.
280
281 --> "Open new window" (no GUI equivalent, applicable only in the applet mode)
282
283     Values: "Yes", "No".
284     Default: "No".
285
286     Operate in a separate window. This makes possible resizing the desktop,
287     and adds scroll bars when necessary. If the server supports variable
288     desktop size, the window will resize automatically when remote desktop
289     size changes.
290
291 --> "Scaling factor" (no GUI equivalent)
292
293     Value: an integer in the range of [1..1000], or the string "auto".
294     Default: "100".
295
296     Scale local representation of the remote desktop. The value is
297     interpreted as scaling factor in percents. The default value of 100%
298     corresponds to the original framebuffer size. Values below 100 reduce
299     image size, values above 100 enlarge the image proportionally. If the
300     parameter is set to "auto", automatic scaling is performed. Auto-scaling
301     tries to choose scaling factor such way that the whole remote framebuffer
302     will fit on the local screen. Currently, auto-scaling is supported only
303     when the remote desktop is shown in a separate frame (always true in the
304     application mode, and also in the applet mode with "Open new window"
305     parameter set to "yes").
306
307 --> "Show controls" (no GUI equivalent)
308
309     Values: "Yes", "No".
310     Default: "Yes".
311
312     Set to "No" if you want to get rid of that button panel at the top.
313
314 --> "Offer relogin" (no GUI equivalent, not applicable in the applet mode)
315
316     Values: "Yes", "No".
317     Default: "Yes".
318
319     If set to "No", the buttons "Login again" and "Close window" won't be
320     shown on disconnects or after an error has occured.
321
322 --> "Show offline desktop" (no GUI equivalent)
323
324     Values: "Yes", "No".
325     Default: "No".
326
327     If set to "Yes", the viewer would continue to display desktop even
328     if the remote side has closed the connection. In this case, if the
329     button panel is enabled, then the "Disconnect" button would be
330     changed to "Hide desktop" after the connection is lost.
331
332 --> "Defer screen updates" (no GUI equivalent)
333
334     Value: time in milliseconds.
335     Default: "20".
336
337     When updating the desktop contents after receiving an update from server,
338     schedule repaint within the specified number of milliseconds. Small delay
339     helps to coalesce several small updates into one drawing operation,
340     improving CPU usage. Set this parameter to 0 to disable deferred updates.
341
342 --> "Defer cursor updates" (no GUI equivalent)
343
344     Value: time in milliseconds.
345     Default: "10".
346
347     When updating the desktop after moving the mouse, schedule repaint within
348     the specified number of milliseconds. This setting makes sense only when
349     "Cursor shape updates" parameter is set to "Enable". Small delay helps to
350     coalesce several small updates into one drawing operation, improving CPU
351     usage. Set this parameter to 0 to disable deferred cursor updates.
352
353 --> "Defer update requests" (no GUI equivalent)
354
355     Value: time in milliseconds.
356     Default: "50".
357
358     After processing an update received from server, wait for the specified
359     number of milliseconds before requesting next screen update. Such delay
360     will end immediately on every mouse or keyboard event if not in the "view
361     only" mode. Small delay helps the server to coalesce several small
362     updates into one framebuffer update, improving both bandwidth and CPU
363     usage. Increasing the parameter value does not affect responsiveness on
364     mouse and keyboard events, but causes delays in updating the screen when
365     there is no mouse and keyboard activity on the client side.
366
367 --> "SocketFactory" (no GUI equivalent)
368
369     Value: name of the class.
370     Default: none.
371
372     This option provides the way to define an alternate I/O implementation.
373     The dynamically referenced class must implement a SocketFactory
374     interface, and create a Socket, as configured by this parameter. See the
375     source in SocketFactory.java.
376
377
378 RECORDING VNC SESSIONS
379 ======================
380
381 Current version of the TightVNC Java viewer is able to record VNC (RFB)
382 sessions in files for later playback. The data format in saved session files
383 is compatible with the rfbproxy program written by Tim Waugh. Most important
384 thing about session recording is that it's supported only if Java security
385 manager allows access to local filesystem. Typically, it would not work for
386 unsigned applets. To use this feature, either use TightVNC Java viewer as a
387 standalone application (Java Runtime Environment or Java Development Kit
388 should be installed), or as a signed applet. The code checks if it's possible
389 to support session recording, and if everything's fine, the new "Record"
390 button should appear in the button panel. Pressing this button opens new
391 window which controls session recording. The GUI is pretty self-explained.
392
393 Other important facts about session recording:
394
395 --> All sessions are recorded in the 24-bit color format. If you use
396     restricted colors (8-bit format), it will be temporarly switched to
397     24-bit mode during session recording.
398
399 --> All sessions are recorded with cursor shape updates turned off. This is
400     necessary to represent remote cursor movements in recorded sessions.
401
402 --> Closing and re-opening the recording control window does not affect the
403     recording. It's not necessary to keep that window open during recording a
404     session.
405
406 --> Avoid using Zlib and ZRLE encodings when recording sessions. If you have
407     started recording BEFORE opening a VNC session, then you are ok. But
408     otherwise, all Zlib-encoded updates will be saved Raw-encoded (that is,
409     without compression at all). The case with ZRLE is even worse -- ZRLE
410     updates will not be saved at all, so the resulting session file may be
411     corrupted. Zlib decoding depends on the pixel data received earlier, thus
412     saving the data received from the server at an arbitrary moment is not
413     sufficient to decompress it correctly. And there is no way to tell Zlib
414     or ZRLE decoder to reset decompressor's state -- that's a limitation of
415     these encoders. The viewer could re-compress raw pixel data again before
416     saving Zlib-encoded sessions, but unfortunately Java API does not allow
417     to flush zlib data streams making it impossible to save Zlib-encoded RFB
418     pixel data without using native code.
419
420 --> Usually, Tight encoding is the most suitable one for session recording,
421     but some of the issues described above for the Zlib encoding affect the
422     Tight encoding as well. Unlike Zlib sessions, Tight-encoded sessions are
423     always saved Tight-encoded, but the viewer has to re-compress parts of
424     data to synchronize encoder's and decoder's zlib streams. And, due to
425     Java zlib API limitations, zlib streams' states have to be reset on each
426     compressed rectangle, causing compression ratios to be lower than in the
427     original VNC session. If you want to achieve the best possible
428     performance, turn recording on BEFORE connecting to the VNC server,
429     otherwise CPU usage and compression ratios may be notably less efficient.
430
431
432 HINTS
433 =====
434
435 --> To refresh remote desktop in the view-only mode, press "r" or "R"
436     on the keyboard.
437
438
439 ACKNOWLEDGEMENTS
440 ================
441
442 This distribution contains Java DES software by Dave Zimmerman
443 <dzimm@widget.com> and Jef Poskanzer <jef@acme.com>.  This is:
444
445     Copyright (c) 1996 Widget Workshop, Inc. All Rights Reserved.
446
447     Permission to use, copy, modify, and distribute this software and its
448     documentation for NON-COMMERCIAL or COMMERCIAL purposes and without fee
449     is hereby granted, provided that this copyright notice is kept intact.
450     
451     WIDGET WORKSHOP MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE
452     SUITABILITY OF THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT
453     NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
454     PARTICULAR PURPOSE, OR NON-INFRINGEMENT. WIDGET WORKSHOP SHALL NOT BE
455     LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING,
456     MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
457     
458     THIS SOFTWARE IS NOT DESIGNED OR INTENDED FOR USE OR RESALE AS ON-LINE
459     CONTROL EQUIPMENT IN HAZARDOUS ENVIRONMENTS REQUIRING FAIL-SAFE
460     PERFORMANCE, SUCH AS IN THE OPERATION OF NUCLEAR FACILITIES, AIRCRAFT
461     NAVIGATION OR COMMUNICATION SYSTEMS, AIR TRAFFIC CONTROL, DIRECT LIFE
462     SUPPORT MACHINES, OR WEAPONS SYSTEMS, IN WHICH THE FAILURE OF THE
463     SOFTWARE COULD LEAD DIRECTLY TO DEATH, PERSONAL INJURY, OR SEVERE
464     PHYSICAL OR ENVIRONMENTAL DAMAGE ("HIGH RISK ACTIVITIES").  WIDGET
465     WORKSHOP SPECIFICALLY DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY OF
466     FITNESS FOR HIGH RISK ACTIVITIES.
467
468     Copyright (C) 1996 by Jef Poskanzer <jef@acme.com>.  All rights
469     reserved.
470
471     Redistribution and use in source and binary forms, with or without
472     modification, are permitted provided that the following conditions
473     are met:
474     1. Redistributions of source code must retain the above copyright
475        notice, this list of conditions and the following disclaimer.
476     2. Redistributions in binary form must reproduce the above copyright
477        notice, this list of conditions and the following disclaimer in the
478        documentation and/or other materials provided with the distribution.
479
480     THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
481     ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
482     IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
483     PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS
484     BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
485     CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
486     SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
487     BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
488     WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
489     OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
490     ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
491
492     Visit the ACME Labs Java page for up-to-date versions of this and other
493     fine Java utilities: http://www.acme.com/java/