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/