VNC® Open 3.3.7 Server for Windows

Getting Started - Installing and Running

WinVNC in system tray

WinVNC is a VNC server that will allow you to view your Windows desktop from any VNC viewer. Because standard versions of Windows only support a single graphical user being logged in at any one time, WinVNC makes the existing desktop of the PC available remotely, rather than creating a separate desktop as happens with the UNIX server. VNC does not make a Windows machine into a multi-user server in the same way that Citrix-based software or Windows Terminal Server, for example, does. A single Windows machine can therefore be accessed by multiple users, but if they all connect at the same time they will all see the same desktop!

On the other hand, WinVNC will run on Windows 95/98/ME, Windows NT/2000/XP and on any future Win32-based systems, without the need to replace any system files or run any OS-specific versions of the program. It is a standard application that can be run from the Start... menu and closed down just as easily.

WinVNC can also be run as a service, which means that you can log in remotely, do some work, and log out again. We recommend that you run it in this mode. See below for more details.

Installation

WinVNC is simple to install and to use:

  1. Start the WinVNC setup program. (If you received VNC as a ZIP archive, you'll need to unpack it first!)
  2. The setup program will allow you to set a number of installation parameters, such as the location of the installed files and Start... menu entries. The setup program will always install the VNC viewer for Windows, and will optionally install the WinVNC server - to install the server simply tick the appropriate checkbox during setup.
  3. As the final stage of the setup process, the installer can register WinVNC as a system service, and start it. Otherwise, WinVNC can be registered manually, or run as an application:

start winvnc

Using WinVNC

On starting, WinVNC will add a VNC icon with a green "V" to the system task bar. Clicking on this icon with the right mouse button will cause a menu to be displayed.

winvnc properties

  • Properties - This will cause the User Properties dialog to be displayed, allowing the user to change various per-user WinVNC parameters.
  • Add New Client - This allows outgoing connections to be made from the server to any "listening" viewer. The name or IP address of the target viewer machine can be entered in the dialog. The server will connect to the default listening viewer port, 5500. From version 3.3.5, a different port number can be specified by adding :portnumber after the name or IP address. Connections created this way are treated as shared. See also the -connect option below.
  • Disconnect All Clients - This will disconnect all currently connected clients from the server.
  • About WinVNC - This should be obvious!
  • Close VNC - Shutdown the server.

Moving the mouse over the icon should cause the IP address of the local machine to be displayed, if it can be discovered at that time. You can connect to the server from another machine using a VNC viewer.

winvncipaddr

WinVNC Properties

The following options are available from the Properties dialog, shown here with the default installation settings.

winvncpropertiesdetail

Incoming Connections

  • Accept Socket Connections - (default) The server normally accepts direct, socket-based connections from the vncviewer program. Clearing this will disable any incoming connections.
  • Display Number - This allows the user to specify the display number which the server will use. There is normally no need to change this from the default of zero.
  • Password - Incoming connections must be authenticated to verify that the person connecting is allowed to connect to this machine. This text box allows your password to be specified for authentication.
  • Auto - This tick box indicates to WinVNC whether it should use the display number specified in the Display Number box, or whether it should use the first display number not already in use on the server machine.
  • Enable Java Viewer - WinVNC can optionally run a simple web server on port 5800+display number, which will serve a web page allowing the machine to be accessed from any Java-enabled browser. If this box is not ticked then the machine will not be accessible via the standard web interface.
  • When Last Client Disconnects - This catchily-named option determines the VNC server's behaviour when the last client connection to it is closed. The available settings are:
    • Do Nothing (default).
    • Lock Workstation - (Only available under 2000/XP). The desktop will be automatically locked on disconnect.
    • Logoff Workstation - The current user will be logged off when the final VNC viewer disconnects.

Connection Settings

  • Disable Remote Keyboard & Pointer - Any new incoming connections will be able to view the screen but not send any input.
  • Disable Local Keyboard & Pointer - This is experimental, and works on NT/2000/XP only. If selected, then the local keyboard and mouse will be disabled during a connection. Useful if you want to log in to a machine from elsewhere and don't want passers-by to be able to use your session.
  • Remove Desktop Wallpaper - (default) Desktop wallpaper can consume excessive bandwidth when transmitted over VNC to a client. This option allows WinVNC to remove the desktop wallpaper when a client connects, and to restore it when the last client disconnects.

Update Handling

Note that clicking in a window will generally cause it to be updated, so if you have certain applications which don't update very well, try this! The default update handling settings should be the right ones for most people, and in general you will slow things down by changing them, so don't do this unless you have applications which cause problems.

  • Poll Full Screen- Some applications are incompatible with the methods currently used in WinVNC to trap screen updates. For this reason, it is sometimes useful to be able to poll the entire screen in order to check for changes, sacrificing performance for accuracy.
  • Poll Foreground Window - (default) Polling only the currently selected window for changes is less CPU intensive than full-screen polling and often gives similar results, for example when using the Command Prompt, which is not normally compatible with WinVNC.
  • Poll Window Under Cursor- A variation on Poll Foreground Window, this option causes the window under the mouse cursor to be polled for changes. Both options may be enabled simultaneously if required.
  • Poll Console Windows Only- (default) When this option is set, the only windows which will be ever be polled are Command Prompts. This works well in conjunction with Poll Window Under Cursor, to use polling only when the cursor is over a console window.
  • Poll On Event Received Only- When this option is set, the screen will only be polled for updates when a mouse or keyboard event is received from the remote client. This is provided for low bandwidth networks, where it may be useful to control how often the screen is polled and changes sent.

The user's settings are saved into the user-specific section of the registry when WinVNC quits, meaning that they will be used next time you run WinVNC.

Running WinVNC as a service

WinVNC can be made to run as a service process under both Windows NT/2000/XP and Windows 95/98/ME, by following the instructions outlined below. This allows you to connect to a machine which has nobody logged in to it, for example. On NT/2000/XP, you can also send Ctrl-Alt-Del to the server when it's running as a service, allowing you to unlock a locked workstation, for example. Note that in 'service' mode, many features are changed on a per-machine rather than per-user basis. You can access the per-machine defaults from the 'Show Default Properties' section of RealVNC group in the Start... menu

winvncdefault

The following 'features' should also be pointed out:

Windows NT/2000/XP 'features':

  • WinVNC will attempt to correctly identify the user and locate their preferred settings in the registry (unless AllowProperties has been used to disable this - see below). To do this requires that a helper application be run when a user logs in, which will pass appropriate information to the main service portion of WinVNC. If the helper fails to run for some reason then WinVNC will continue to operate but it won't know who is logged in, so its settings will be based on the local-machine and default-user settings only.

Windows 95/98/ME 'features':

  • Whether or not the VNC password is set per-machine or per-user depends on the settings in the Passwords section of the Control Panel. If Windows 95/98/ME is set to use a different set of registry values for each user then when a user logs in, the password will change from the per-machine VNC password to that user's VNC password. If Windows 95/98/ME is set to use the same settings for all users then the per-machine VNC password will always be used.

General features for both Windows NT/2000/XP and Windows 95/98/ME:

  • Anything which causes the Windows VNC server to change screen resolution will also cause all viewers to be disconnected, and you'll need to reconnect. Logging in can sometimes do this if the user has a different screen setup from the system default. Changes between pixel formats will NOT cause clients to be disconnected, however.
  • If a user has specified a display number which is different from the default used by the service, viewers will be disconnected as that user logs in.
  • When WinVNC is running as a system service, no user-level copies can be run at the same time.

Here's how to get it running as a service, assuming you've already installed it. Under Windows NT/2000/XP you need to have administrator privileges on the local machine, so log on as administrator if your account doesn't have these.

  1. Either:

    Select "Register VNC Server Service" from the VNC Server section of the Start menu.

    Or:

    Open a Command Prompt and run WinVNC with the -install (or -reinstall) option. eg:

    D:\> C:
    C:\> cd "\Program Files\RealVNC\WinVNC"
    C:\Program Files\RealVNC\WinVNC> winvnc -install
    
  2. Windows 95/98/ME : The WinVNC service is now running and is registered to run whenever the system boots up into Windows 95/98/ME.

    Windows NT/2000/XP : The WinVNC service is registered and set up to run whenever the machine is booted into Windows NT/2000/XP but IS NOT YET RUNNING! It will run when the machine next reboots. If you want to start it immediately, you can use the Services section of the Windows control panel, or "net start" from the command prompt:

    C:\> net start winvnc
    

    The service should now be running, but won't know that you are logged in until you log out and back in again. It won't yet appear on the taskbar. You can run the WinVNC Service Helper from the start menu to tell it who you are!

  3. If you wish to change the WinVNC settings (eg. password) when it is not visible on the taskbar, you can use 'Show User Properties' from the VNC Server section of the Start... menu.
    If you wish to change the default settings used by the service when there's nobody logged in, or no user-specific settings in are use, use 'Show Default Properties' from the VNC Server section of the Start... menu. See below for more information about defaults.

    NOTE : Windows 95/98/ME : If Windows 95/98/ME has been set to use different settings for each user then the settings used are those of the currently logged in user. If no user is logged in or Windows 95/98/ME is set to use the same settings for all users then the settings used are the Default user settings and are stored per-machine, rather than on a per-user basis as is done when running WinVNC normally. (Under Windows 95/98/ME, pressing Cancel on the login dialog gives access to the Default user settings.)

  4. When you wish to install a new version of WinVNC or simply wish to remove WinVNC from your machine, you must first unregister the service from the system, using the Unregister VNC Server Service menu item or the -remove command-line option.

NOTE : A message about failure to remove the service usually indicates that it was not installed in the first place!

Command-line options

The full command-line options available are as follows. You probably won't need anything other than those listed above unless you're a real VNC power-user!

-run
Causes WinVNC to run normally & ignore rest of command-line.
-install
Installs the WinVNC service and continues reading the command-line.
-reinstall
Removes, then re-installs the WinVNC service and continues reading the command-line.
-remove
Removes the WinVNC service and continues reading the command-line.
-settings
Tells a running copy of WinVNC to show the User Properties box.
-defaultsettings
Tells a running copy of WinVNC to show the Default Properties box.
-connect [host]
Tells a running copy of WinVNC to initiate an outgoing connection to a listening viewer running on the specified machine. This is the equivalent of the 'Add New Client' menu option. You can put multiple -connect options on one command line to connect to multiple viewers at once. If no host name is specified then the Add New Client dialog will be displayed.
-kill
Kills a running copy of WinVNC.
-about
Tells a running copy of WinVNC to show its About box.

If no options are given then WinVNC runs normally. Multiple options may be given. To upgrade a currently running WinVNC service to a new version, for example, you could use:

WinVNC_new -reinstall

which will stop & remove the old copy & install the new one as a service, or

WinVNC_new -kill -run

which will stop the running copy & run the new version as an application.

WinVNC - Advanced Settings

Extra options have been added to WinVNC for use primarily by system administrators, to tailor the server's behaviour to meet their particular needs. The options are DWORD values which can be set in the system registry, and tools such as the Windows Policy Editor can be used to apply these settings across a large number of machines.WinVNC will currently look for settings in the following places:

  1. Local machine-specific settings. Options specified here are not overridable.
    Location: HKEY_LOCAL_MACHINE\Software\ORL\WinVNC3\
  2. Local default user settings.
    Location: HKEY_LOCAL_MACHINE\Software\ORL\WinVNC3\Default
  3. Local per-user settings. These override the local default user settings. If there is no current user, the username SYSTEM will be used.
    Location: HKEY_LOCAL_MACHINE\Software\ORL\WinVNC3\<username>
  4. Global per-user settings. These are only read if AllowProperties has not been set to zero (see below).
    Location: HKEY_CURRENT_USER\Software\ORL\WinVNC3

Most options can only be specified in a subset of these places, as specified in each option's description below.

Advanced Options:

AllowEditClients

WinVNC will include the Add New Client and Disconnect All Clients options on the tray icon menu. This option causes these options to be disabled, preventing users from connecting out to listening viewers, or from disconnecting existing viewers.Local per-user setting

AllowLoopback

By default, WinVNC servers disallow any vncviewer connections from the same machine. For testing purposes, or, potentially, when using multiple instances of WinVNC on Windows Terminal Server, this behaviour is undesirable. Setting this registry entry to 1 will cause local-loopback connections to be allowed. Setting it to zero will filter out such connections. Local machine-specific setting.

AllowProperties

If this is set to zero, the user is not allowed to view the properties dialog and hence cannot change any settings, including the password. Note that this stops all global per-user settings. A valid password must therefore be in force before using this setting, generally in the local default-user setting. Local per-user setting.

AllowShutdown

If this is set to zero, the user is not allowed to close down WinVNC. Local per-user setting.

AuthHosts

The AuthHosts setting is, unlike the other settings, a REG_SZ string. It is used to specify a set of IP address templates which incoming connections must match in order to be accepted. By default, the template is empty and connections from all hosts are accepted. The template is of the form:

+[ip-address-template]
?[ip-address-template]
-[ip-address-template]

In the above, [ip-address-template] represents the leftmost bytes of the desired stringified IP-address.For example, +192.168 would match both 192.168.12.10 and 192.168.14.2.Multiple match terms may be specified, delimited by the ":" character. Terms appearing later in the template take precedence over earlier ones.e.g. -:+192.168: would filter out all incoming connections except those beginning with 192.168. Terms beginning with the "?" character are treated by default as indicating hosts from whom connections must be accepted at the server side via a dialog box. The QuerySetting option determines the precise behaviour of the three AuthHosts options. Local machine-specific setting.

AuthRequired

By default, all WinVNC servers will not accept incoming connections unless the server has had its password field set to a non-null value. This restriction was placed to ensure that misconfigured servers would not open security loopholes without the user realising. If a server is only to be used on a secure LAN, however, it may be desirable to forego such checking and allow machines to have a null password. Setting this registry value to zero will disable null-password checking by WinVNC. Local machine-specific setting.

AutoPortSelect

Causes WinVNC to select the first available display number automatically. Corresponds to the 'Auto' checkbox in the Properties dialog. Local or Global per-user setting

ConnectPriority

By default, all WinVNC servers will disconnect any existing connections when an incoming, non-shared connection is authenticated. This behaviour is undesirable when the server machine is being used as a shared workstation by several users or when remoting a single display to multiple clients for vewing, as in a classroom situation.

ConnectPriority indicates what WinVNC should do when a non-shared connection is received:
0 = Disconnect all existing connections.
1 = Don't disconnect any existing connections.
2 = Refuse the new connection.

This is a Local machine-specific setting.

DebugLevel
DebugMode

Run-time logging of all internal debug messages is now supported. Log data may be output to a file or a console window (or the MSVC debugger if the program was compiled with debugging active.) Two registry keys are used:

DebugMode indicates which logging methods to use,
[1 = MSVC debugger]
2 = Output to log file Winvnc.log in the "current" directory. When running as a service, this will usually be the System directory. When running as an application, this will usually be the WinVNC program directory.
4 = Output to a console window, displayed on-screen
Any combination of the above values may be used. e.g. DebugMode=6 will cause output to be sent both to the WinVNC.log file and to the a console window on the desktop.

DebugLevel indicates how much debug information to present. Any positive integer is valid. Zero indicates that no debugging information should be produced and is the default. A value of around 10-12 will cause full debugging output to be produced. Local machine-specific setting.

HTTPConnect

Corresponds to the Enable Java Viewer setting in the Properties dialog. Local or Global per-user setting

IdleTimeout

This setting tells WinVNC how many seconds a connected VNC client may remain idle for (no input events or update requests) before being disconnected. If this setting is not specified or is set to zero then no timeout is enforced. Local or Global per-user setting

InputsEnabled

Corresponds (inversely) to the 'Disable Remote keyboard and pointer' option in the Properties dialog box. Local or Global per-user setting

LockSetting

WinVNC can be made to take actions when a viewer disconnects by setting this value as follows:
0 - none
1 - lock workstation on disconnect (Windows 2000/XP Only)
2 - logoff on disconnect
Local or Global per-user setting

LoopbackOnly

By default, WinVNC servers accept incoming connections on any network adapter address, since this is the easiest way of coping with multihomed machines. In some cases, it is preferable to listen only for connections originating from the local machine and aimed at the "localhost" adapter - a particular example is the use of VNC over SSH to provide secure VNC. Setting this registry entry to 1 will cause WinVNC to only accept local connections - this overrides the AllowLoopback and AuthHosts settings. Setting this entry to zero causes WinVNC to accept connections on any adapter and is the default setting.Local machine-specific setting.

Password

Local or Global per-user setting

PollUnderCursor, PollForeground, PollFullScreen, OnlyPollConsole, OnlyPollOnEvent

These correspond to the options in the Properties dialog box. Local or Global per-user settings

PortNumber

specifies the port number to be used for VNC. You will need to disable AutoPortSelect to use this.Local or Global per-user setting

QuerySetting

The QuerySetting allows individual users to tailor the degree of paranoia expressed by the per-machine AuthHosts setting. It is a DWORD value ranging from zero (maximum availability) to four (maximum security). The following table indicates how the value affects the AuthHosts behaviour:


0 - +:Accept, ?:Accept, -:Query
1 - +:Accept, ?:Accept, -:Reject
2 - +:Accept, ?:Query, -:Reject [Default]
3 - +:Query, ?:Query, -:Reject
4 - +:Query, ?:Reject, -:Reject
By default, value 2 (Obey AuthHosts) will be assumed. Local & global per-user setting.

QueryTimeout

The QueryTimeout setting indicates the number of seconds for which the Accept Connection dialog (see AuthHosts and QuerySetting options) will be displayed before rejecting the incoming connection automatically. Local & global per-user setting.

RemoveWallpaper

Indicates whether or not WinVNC should remove the user's background wallpaper when an incoming connection is made. It is necessary to reconnect in order for this setting to take effect. Local or Global per-user setting

SocketConnect

This corresponds to the 'Accept Socket Connections' option in the properties dialog box and is a Local or Global per-user setting.

VNCHooks - Advanced Settings

WinVNC uses a special library, VNCHooks, to hook into the other running applications and retrieve notifications of areas of the screen being changed. The VNCHooks library uses the messages sent to visible Windows to decide which areas need considering for update. Not all applications use the same method of updating the screen, so you can tweak the method used by WinVNC for particular applications by editing the registry. All the entries listed can be found under

HKEY_CURRENT_USER\Software\ORL\VNCHooks\Application_Prefs
  • use_GetUpdateRect

    When a window recieves a message, (WM_PAINT), indicating that it should repaint itself, it is possible to find out precisely which regions have changed, so that WinVNC need only scan those for potential updates,increasing efficiency. However, this can cause graphical glitches occasionally, particularly when an application scrolls the contents of its window, in which case only the revealed section of the window is marked as needing to be updated. If these glitches prove to be a problem then edit the <appname>\use_GetUpdateRect entry in the registry. A value of one indicates that this optimisation will be used, while a value of zero indicates that it will not.

  • use_Timer

    A number of Windows applications, most notably the Clock program, use WM_TIMER events to trigger updates to their displays, rather than WM_PAINT messages. By default, timer messages are not used to notify WinVNC of potential updates, since many programs use timer events for purposes other than updating the screen. As a result, the clock and a few other applications don't normally update correctly under WinVNC. The fix to this is to edit the <appname>\use_Timer entry in the registry. A value of one indicates that WM_TIMER messages will trigger WinVNC updates, while a value of zero indicates that they will not.

  • use_KeyPress


    Some Windows applications write characters directly to the screen when a user types into a window, rather than using WM_PAINT messages to cause the text to be redrawn. To fix this, WinVNC can scan the window every time a key is pressed, in order to catch the change. To set this value for a problem application, edit the <appname>\use_KeyPress entry in the registry. A value of one indicates that key presses will cause updates, while a value of zero indicates that they will not.

  • use_LButtonUp, use_MButtonUp,use_RButtonUp

    Some Windows applications update the display directly in response to mouse clicks, without using intermediate WM_PAINT messages, for example. In order to catch such updates, it is necessary to trigger WinVNC to update the relevant window whenever the left mouse button is released. To set this value for a problem application, edit the <appname>\use_LButtonUp entry in the registry. A value of one indicates that left-button clicks will cause updates, while a value of zero indicates that they will not. The same rules apply to the middle and right buttons using the appropriate value name.

  • use_Deferral

    The VNCHooks library catches messages sent to windows before they are dealt with by the window. As a result, sending an update message to WinVNC to indicate the potential change can result in WinVNC sending the updated area to the client before it has actually been redrawn by the application! This is a common problem, especially on multiprocessor versions of NT/2000/XP, so deferred updates are used by default. Deferred updates are handled by posting a custom message back into the window's own message queue rather than posting to WinVNC directly. By the time this custom message is seen again by the VNCHooks library, the message that caused it will have been handled and the update can then be forwarded to WinVNC without danger of being handled prematurely. A few programs don't handle these extra messages in their queue very well, so this optimisation is optional. It can be set by editing the <appname>\use_Deferral entry in the registry. A value of one indicates that deferred updates will be used, while a value of zero indicates that they will not.

Running on other Win32 systems

WinVNC runs fine on NT3.51 but the absence of a system tray means that the Properties dialog cannot be accessed. In addition, Ctrl-Alt-Del from clients cannot be correctly interpreted under NT 3.51, limiting WinVNC's usefulness when run as a service on this platform. Under Windows NT 4, WinVNC requires at least Service Pack 3.

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.

If that doesn't help then try subscribing to the mailing list and ask your question there.