VNC® documentation

Index

Features

VNC Viewer Enterprise Edition 4.0 for Java offers a number of improvments over VNC Viewer Free Edition for Java, including:

Running from a Web Browser

The VNC servers also contain a small web server. If you connect to this with a web browser, you can download the Java version of the viewer, and use this to view the server. You can then see your desktop from any Java-capable browser, unless you are using a proxy to connect to the web. The UNIX VNC Server listens for HTTP connections on port 5800+display number. So to view display 2 on machine 'snoopy', you would point your web browser at http://snoopy:5802/.

The Windows VNC Server listens on port 5800 by default, but this can be configured per-server.

When the applet has downloaded, your web browser will ask whether or not you wish to trust the code:

java signed

The applet can run in either trusted or untrusted mode depending on your response at this stage. However, in untrusted mode, some advanced features are not available. These will be noted as appropriate throughout this documentation.

You may not see a dialog similar to the one shown above in the following circumstances:

It is also possible that the dialog contains a warning that the certificate has expired. Certificates have a built-in expiry date to reduce the length of time that an attacker has in which to compromise them; after this date your browser or Java plug-in will warn you that the certificate has expired. It is possible to run the viewer in both trusted and untrusted modes with an expired certificate, but you can obtain an applet signed with a more recent certificate by upgrading the VNC Server to which you are connecting to the latest version.

Running as an Application

You can run the viewer outside a browser using, for example:

java -jar vncviewer.jar snoopy:2

The precise command line will depend on your particular Java installation. If you do not specify a server on the command line then the application will prompt you for one when it starts up.

Connecting to a VNC Server

Once the applet or application has been started, the Connection Details dialog will be displayed, allowing the IP address or name of the target VNC Server to be specified:

java connect number

java connect name

An untrusted applet can only connect back to the VNC Server from which it originated, whereas a trusted applet does not have this restriction.

If the VNC server's display number is non-zero then the display number can be specified by adding a colon to the server's IP address or name, followed by the display number:

java connect display

If the VNC server is using a non-standard port number to accept connections then this is specified by adding two colons to the server's address or name, followed by the port number:

java connect port

As well as specifying the server to connect to, you can specify whether or not the session should be encrypted. By default, VNC Viewer will decide whether or not to encrypt the session based on the server's preference. It is possible, however, to override the server's preference. The Connection Details dialog provides a choice of three preference settings, plus the option to let the server choose:

java encrypt options

Once you have selected the VNC server to connect to, you can simply click OK or press return to attempt to connect to it. Alternatively, you can select the Options... button to override the default connection configuration before you connect. See the Configuring VNC Viewer documentation for more details.

User Authentication

VNC Viewer supports several different security schemes. When a server requires authentication, the security scheme currently in use is displayed in square brackets to the right of the Authentication dialog's title bar. The same information can also be obtained from the Connection Info dialog.

Security schemes other than None and VNC Authentication will usually support a username as well as a password. How these are used depends on the authentication method used by the server. They might, for example, be used to authenticate the user against a Windows NT domain.

java userpasswd

Before this dialog is displayed, you may be asked to enter a string of random characters. This is necessary on platforms that do not provide a mechanism for generating secure random numbers (i.e. those that cannot easily be guessed by a potential attacker). The longer and more random the string you enter at this stage, the less chance an attacker has of being able to break your security.

Server Authentication

When establishing a secure connection to a VNC Server, VNC Viewer attempts to verify that the server is the one that the user expected. This is achieved using by keeping a store of Identities of servers to which the user has previously connected.

When making a secure connection to a server for which an identity is not already cached, the user will be prompted to continue or cancel the connection. If the connection is continued then the identity will be added to the user's cache.

java no signature

N.B. if VNC Viewer is running as an untrusted applet then it cannot access the host identity cache. This dialog is therefore displayed every time a connection is made, and the user should check that the host's signature is as expected.

When making a secure connection to a server for which the identity differs from the cached version, VNC Viewer warns the user of the problem and prompts them to decide whether or not to continue connecting:

java bad signature

Configuring VNC Viewer

VNC Viewer provides a number of options allowing its behaviour to be tailored to your needs. These can be configured by clicking on the Options... button in the Connection Details dialog or, for some options, via the F8 Menu while you are connected to the server.

Encoding Options

java options encoding

The Encoding Options are used to control the bandwidth and processor requirements of the VNC session. The ZRLE, Hextile and Raw options are arranged in order of increasing bandwidth requirements and decreasing processing requirements, so that ZRLE is most effective on slow networks such as dial-ups, while Raw is often most effective on fast LANs. If the Auto select checkbox is ticked then the encoding is determined automatically by VNC Viewer based on the available bandwidth.

VNC Viewer for Java currently only supports the Medium (256 colors) color setting. Support for other color settings is planned for future releases.

Input Options

java options inputs

The Input Options are used to control what data is sent to and received from the VNC Server. Selecting View only prevents keyboard and mouse input from being sent to the server. Accept clipboard from server and Send clipboard to server are used to enable or disable receiving and sending of clipboard contents, respectively, to control cut and paste operations between locally- and remotely-running applications.

Security Options

java options security

The Security Options provide a trade-off between the length of time to generate a session key and the security provided. The session key is generated when a connection to a server is first made, and is not generated for subsequent connections unless the Java applet or application has been unloaded in the interim. This setting cannot be changed after a connection has been established.

Miscellaneous Options

java options misc

The Shared (don't disconnect other viewers) option is used to determine whether or not other connected viewers are disconnected before the connection continues. Note that the server may choose to ignore or refuse VNC Viewer's request. This setting cannot be changed after a connection has been established.

The Render cursor locally option controls whether the mouse cursor is rendered locally by VNC Viewer or remotely by the VNC Server to which it is connected. Local cursor rendering means that the cursor responds more quickly to mouse movemements and makes VNC connections over slow networks appear faster. Over faster networks, or for personal preference, this local rendering may be disabled by unticking the Render cursor locally checkbox.

The Fast CopyRect option controls how VNC protocol optimisations for operations such as window dragging is supported. If this option is enabled then these operations are handled as efficiently as possible. However, under some Java virtual machines, this can give visual artifacts. In this case you should try disabling this option.

Using the F8 Menu

The so-called F8 Menu provides a quick way to access a set of frequently-used VNC Viewer functions. It is called the F8 Menu because it can be accessed most easily simply by pressing the F8 key in a VNC Viewer window!

The F8 Menu can also be accessed by right-clicking on the titlebar of a VNC Viewer window, or by left-clicking on the System Menu button in the top left of the VNC Viewer window's titlebar.

Clicking anywhere outside the F8 Menu will cause it to go away again.

F8 Menu Functions

java f8menu

The F8 Menu provides access to the following:

Exit viewer
Exits the viewer. If you are running the VNC Viewer as a Java applet, you can refresh the web page that launched it to open the Connection Dialog. With most modern web browsers there will be no need to regenerate the session key.
Clipboard...
Opens the clipboard dialog. Because untrusted applets cannot access the system clipboard, clipboard data received from the VNC Server is copied into this dialog, from where it can be manually copied to the system clipboard. Similarly, to paste text from the system clipboard to the VNC Server, first paste it into this dialog and then click Send to VNC server. Trusted applets can access the system clipboard directly, so the clipboard dialog is not generally needed when VNC Viewer is running in trusted mode. However, it is still sometimes useful for handling applications that use the clipboard in non-standard ways.
Send F8
Because the F8 key is used to access the F8 Menu, it will not be sent to the VNC Server when it is pressed. To send an F8 keypress to the server, you can bring up the F8 Menu locally and select the Send F8 Menu option.
Send Ctrl-Alt-Del
The Ctrl-Alt-Del key sequence is intercepted by Windows operating systems for use as a Secure Access Sequence and so cannot be captured by the VNC Viewer for transmission to a remote server. Instead, you can bring up the F8 Menu and select Send Ctrl-Alt-Del to achieve the same effect.
Note that on some versions of the operating system, pressing Alt Gr-Del will cause the Ctrl-Alt-Del sequence to be captured by VNC Viewer without the operating system intercepting it. This is available primarily on European versions of the operating system.
Note that on all versions tested, pressing Shift-Ctrl-Alt-Del could be used to cause Ctrl-Alt-Del to be received by a WinVNC Server without having the local operating system capture the it.
Refresh screen
Requests a full screen update from the VNC Server. Use this if you experience any unexpected visual artifacts.
New Connection...
The New Connection... option causes a new Connection Details dialog to be displayed, so that a connection can easily be made to another VNC Server.
Note that a VNC Viewer started in this way actually shares the same process as the VNC Viewer window from which it was started. The VNC Viewer process will not quit until both windows have been closed. This may affect the behaviour of scripts which launch VNC Viewer.
Options...
This causes the Connection Options dialog to be displayed, allowing the settings for the current connection to be modified. See the description of VNC Viewer Options for more details.
Connection Info...
The Connection Info dialog displays information about the remote host, pixel format, line-speed estimate and protocol version. If you don't know what any of this means then don't worry - it's all safe to ignore! The main use of the Connection Info dialog is to help in diagnosing any problems you might encounter while using VNC Viewer.
About VNCviewer...
Displays program and version information.
Dismiss menu
Closes the F8 Menu.

Problems?

If you have difficulties which are not covered by this document, try reading the Knowledge Base. There are also some pages to help with troubleshooting.