VNC User Guide

Version 5.2

June 2014

Trademarks
VNC is a registered trademark of RealVNC Ltd. in the U.S. and in other countries. Other trademarks are the
property of their respective owners.
Protected by UK patent 2481870.

Copyright
Copyright RealVNC Limited, 2002-2014. All rights reserved.
No part of this documentation may be reproduced in any form or by any means or be used to make any
derivative work (including translation, transformation or adaptation) without explicit written consent of
RealVNC.

Confidentiality
All information contained in this document is provided in commercial confidence for the sole purpose of use
by an authorized user in conjunction with RealVNC products. The pages of this document shall not be
copied, published, or disclosed wholly or in part to any party without RealVNCs prior permission in writing,
and shall be held in safe custody. These obligations shall not apply to information which is published or
becomes known legitimately from some source other than RealVNC.

Contact
RealVNC Limited
Betjeman House
104 Hills Road
Cambridge
CB2 1LQ
United Kingdom
www.realvnc.com

Contents

Chapter 1:

Chapter 2:

Chapter 3:

About This Guide

Introduction

Principles of VNC remote control

10

Getting two computers ready to use

11

Connectivity and feature matrix

13

What to read next

17

Getting Connected

19

Step 1: Ensure VNC Server is running on the host computer

20

Step 2: Start VNC Viewer on the client computer

21

Step 3: Identify VNC Server running on the host computer

21

Step 4: Request an encrypted connection

22

Step 5: Connect to VNC Server

23

Troubleshooting connection

26

Using VNC Viewer

35

Starting VNC Viewer

36

Starting Listening VNC Viewer

36

Configuring VNC Viewer before you connect

37

Connecting to a host computer

39

The VNC Viewer user experience

40

Using the toolbar

42

Using the shortcut menu

43

Using the Options dialog

44

Managing the current connection

45

Changing appearance and behavior

46

Restricting access to features

48

Chapter 4:

Chapter 5:

Chapter 6:

Chapter 7:

Connecting From A Web Browser

51

Connecting to a host computer

52

The VNC Viewer for Java user experience

56

Working with VNC Viewer for Java

57

Exchanging Information

61

Printing host computer files to a local printer

62

Transfering files between client and host computers

64

Copying and pasting text between client and host computers

68

Communicating securely using chat

69

Working With VNC Server

73

Licensing VNC Server

74

Starting VNC Server

75

Running multiple instances of VNC Server

78

Keeping VNC Server up-to-date

81

The VNC Server user interface

82

Troubleshooting VNC Server

87

Configuring VNC Server

89

Changing ports

90

Notifying when users connect

92

Stopping VNC Server

93

Making Connections Secure

95

Authenticating users

96

Authenticating using system credentials

96

Authenticating using a password specific to VNC

98

Relaxing the authentication rules

99

Bypassing the authentication rules

101

Changing the encryption rules

104

Preventing connections to VNC Server

105

Restricting functionality for connected users

109

Appendix A:

Appendix B:

Appendix C:

Appendix D:

Verifying the identity of VNC Server

114

Protecting privacy

115

Saving Connections

117

Saving connections to VNC Address Book

118

Using VNC Address Book to connect

123

Managing connections using VNC Address Book

124

Saving connections to desktop icons

127

Setting Up VNC

129

Configuring VNC

130

Specifying VNC parameters

130

Specifying Xvnc options

136

Preventing users configuring VNC

138

Managing system authentication

141

Setting up single sign-on authentication

143

Hosting VNC on a UNIX network share

145

Logging information

148

Removing VNC

150

VNC Parameters

153

Categorizing VNC parameters

154

VNC Server parameters

155

VNC Viewer parameters

175

VNC At The Command Line

189

VNC Server at the command line

190

VNC Viewer at the command line

192

About This Guide

This Guide explains how to use VNC 5.x remote access and control software from RealVNC to connect two
computers over a network, and control one from the other.

Applicable software
All the information in this Guide applies to connections established between a client computer running the
latest version of VNC Viewer and a host computer running the same version of VNC Server with an
Enterprise license. Unless otherwise stated, this combination is assumed. To see how to set these
applications up, read Getting two computers ready to use on page11.
Note that general principles of remote control, and information relating to particular supported features, also
applies to connections established between any combination of the products and license types listed below.
VNC Server (with different license types applied)

VNC Server with a Personal license

Contains most VNC remote control features. A thirty day trial is available.

VNC Server with a Free license

Contains basic remote control features.

For more information on licensing, start with Licensing VNC Server on page74.
VNC Viewer

VNC Viewer for Java

This application is freely available to download on demand from VNC Server with an Enterprise or a
Personal license.

VNC Viewer Plus

This application is available to purchase from www.realvnc.com/products/viewerplus/.

VNC Viewer for iOS

This application is freely available from the Apple App Store. Visit www.realvnc.com/products/ios/ for
more information.

VNC Viewer for Android

This application is freely available from Google Play. Visit www.realvnc.com/products/android/ for more
information.

VNC Viewer for Google Chrome

This application is freely available from the Google Chrome Web Store. Visit www.realvnc.com/products/
chrome/ for more information.

To understand restrictions for connections established between particular combinations of products and
license types, see Connectivity and feature matrix on page13.

VNC User Guide

About This Guide

Intended audience
There is no such thing as a typical RealVNC user or remote control session. This Guide therefore has more
than one audience in mind:

Chapter 1 is a general introduction to remote control, intended for everybody.

Chapters 2 through 5 are intended for users who want to connect to and control a remote computer.

Chapters 6 and 7 are intended for users who want to set up the remote computer to be controlled.

Appendices B, C, and D are intended for system administrators responsible for deploying, licensing, and
configuring VNC 5.x in an enterprise environment.

This Guide is intended to be operating system-agnostic, as far as possible. Information related to specific
operating systems is clearly marked.

Conventions
Screen captures are from Windows 7 unless otherwise stated. Dialogs and other artifacts may appear
differently under UNIX and Mac OS X, or versions of Windows with different themes, but the principle is the
same.

Contacting Technical Support

You can contact Technical Support if you have an Enterprise or a Personal license to use VNC Server and
your support and upgrades contract is valid. This contract lasts for a minimum of one year from the date of
purchase of the license, and can be renewed. To see whether it is valid, examine the Details section of the
VNC Server dialog, or run the command vnclicense -list.
To obtain support, visit support.realvnc.com. For information about critical security patches and product
upgrades, see Keeping VNC Server up-to-date on page81.

Related information
Visit www.realvnc.com for:

Supported platforms, operating systems, and system requirements.

Instructions on how to install and uninstall VNC 5.x.

Release notes, Knowledge Base articles, forums, and FAQs.

Information relating to legacy VNC Enterprise Edition and VNC Personal Edition.

Information relating to other RealVNC products and solutions.

VNC User Guide

1
Introduction

This Guide explains how to use VNC 5.x remote access and control software from RealVNC to connect two
computers over a network and take control of one (the host computer) from the other (a client computer),
irrespective of where the two are in the world, or incompatibilities they may have in platform, architecture, or
operating system.
VNC 5.x consists of two components: VNC Server and VNC Viewer. All the information in this Guide applies
to connections established between a client computer running the latest version of VNC Viewer and a host
computer running the same version of VNC Server with an Enterprise license. For a list of other products
and license types to which information may also apply, see Applicable software on page7.

Contents
Principles of VNC remote control

10

Getting two computers ready to use

11

Connectivity and feature matrix

13

What to read next

17

VNC User Guide

Chapter 1: Introduction

Principles of VNC remote control

To connect to and control one computer from another:

An application called VNC Server must be running on the host computer; that is, on the computer you
want to control. To see how to obtain, license, and start VNC Server, read Setting up the host computer
on page11.
Note: You may be able to control computers that are running alternatives to VNC Server. For more
information, see Connecting to VNC-compatible Server software on page15.

An application called VNC Viewer must be running on the client computer; that is, on the computer you
are sitting in front of, and want to exercise control from. To see how to obtain and start VNC Viewer, read
Setting up the client computer on page12.
Note: You may be able to exercise control using alternatives to VNC Viewer. For more information, see
Connecting from alternatives to VNC Viewer on page15.

Host and client computers must be connected to the same TCP/IP network. This can be a private
network such as a LAN or VPN, or a public network such as the Internet. Note that firewalls and routers
must typically be configured before an Internet connection can be established. See Connecting over the
Internet on page28 for more information.

Consider the following example:

A. Client computer (typically a laptop or desktop) running VNC Viewer. B. Client device (handset or tablet) running
VNC Viewer for iOS or Android. C. Host computer (typically a workstation or server) running VNC Server. D. Router
exposing a public network address for Internet connections to the host computer.

10

VNC User Guide

Chapter 1: Introduction

To start a remote control session, run VNC Viewer and identify VNC Server on the host computer you want
to control. Once authenticated, VNC Viewer displays the host computers desktop in a new window, and you
can take control using the client computers keyboard and mouse (or device touch). You can run
applications, change settings, and access data on the host computer exactly as you would be permitted to
do were you sitting in front of it. See a picture.
Note: By default, VNC Server allows other users to connect to the host computer at the same time as you.
You may be sharing control.
VNC 5.x remote access and control software solves different problems for users with different requirements,
from the family member troubleshooting computer problems over the Internet to the system administrator
configuring devices remotely in an enterprise environment. To find out how to get the information you need
from this Guide, see What to read next on page17.

Getting two computers ready to use

Before you can establish a connection, certain operations must be performed on both host and client
computer.
This section addresses the client computer user and assumes the same person is able (that is, is physically
present and has sufficient privileges) to configure the host computer as well. If not, contact a system
administrator or a host computer user.
Note: Some operations need only be performed once. Others must be performed before each connection.

Setting up the host computer

1. Ensure the host computer is turned on, has a functioning operating system, and is connected to a
network to which the client computer can also connect. This can be:
A private network such as a LAN or VPN, if both computers are co-located at home or in a typical
small office environment.
A public network such as the Internet for most other kinds of connection, and especially those made
from an Internet caf, a public Wi-Fi hotspot, or over a mobile (cellular) data network (4G/3G/GPRS/
EDGE).
2. Download and install VNC 5.x from www.realvnc.com/download/vnc/, and license VNC Server (note
administrative privileges are required). For more information on licensing, start with Licensing VNC
Server on page74.
3. If you are connecting over a public network such as the Internet, it is very likely that the host computer
will be protected by at least one firewall. If so, each must be configured to allow network communications
through to the port on which VNC Server is listening, which is 5900 by default. See Allowing network
communications through a firewall on page31 for more information.
4. If you are connecting over a public network such as the Internet, it is very likely that the host computer
will be protected by at least one router. If so, each must be configured to forward network
communications through to the port on which VNC Server is listening, which is 5900 by default. See
Configuring a router to forward network communications on page29.

VNC User Guide

11

Chapter 1: Introduction

5. Make sure VNC Server is running on the host computer and that it can accept incoming connections.
See Step 1: Ensure VNC Server is running on the host computer on page20 for more information.
6. Find out the network address of VNC Server. If you are connecting:
Over a LAN or VPN, this is a private address, which is that of the host computer itself. See
Connecting within a private network on page28 for more information.
Over the Internet, this is a public address, which is that of a router or similar device acting as a public
gateway. See Connecting over the Internet on page28 for more information.
7. Find out the credentials required to authenticate to VNC Server. By default, if you are connecting to:
VNC Server with an Enterprise or a Personal license, you require the user name and password of a
user account with administrative privileges on the host computer. See Authenticating using system
credentials on page96 for more information.
VNC Server with a Free license, you require a password specific to VNC. See Authenticating using a
password specific to VNC on page98 for more information.
Note: If you cannot perform these operations and a host computer user is present, you may be able to
jointly establish a reverse connection. See Establishing a reverse connection on page102 for more
information.

Setting up the client computer

1. Ensure your client computer is turned on, has a functioning operating system, and is connected to the
same network as the host computer (for example, the Internet).
2. Obtain VNC Viewer. You can either:
Download VNC Viewer as a standalone application from www.realvnc.com/download/viewer/, and
save the file to an appropriate location. (Depending on the download package chosen, you may need
to extract it first.) Under UNIX and Linux, you must also make the file executable, for example by
running the command:
chmod +x <VNC Viewer download file>
Under Mac OS X, you must mount the disk image, for example by double-clicking it, or alternatively
by running the command:
hdiutil attach <VNC Viewer download file>
Install VNC 5.x from www.realvnc.com/download/vnc/, which incorporates VNC Viewer, and for
which you do not require a license key. If you do this, VNC Viewer can be started from the menu
system of most operating systems, which may be more convenient, and in addition you can save
connections to VNC Address Book. However, note that administrative privileges are typically
required to install software.
3. If your client computer is protected by a proxy server, specify the details of that proxy server. For more
information, see Connecting via a proxy server on page38.

12

VNC User Guide

Chapter 1: Introduction

Connectivity and feature matrix

You can use the latest version of VNC Viewer to connect to:

The latest version of VNC Server incorporated in VNC 5.x.

Previous versions of VNC Server incorporated in VNC Enterprise Edition or VNC Personal Edition.

VNC-compatible Server software from third parties.

Note that the latter two may require configuration before a connection can be established, and that not all
VNC remote control features will be available once connected.
Note: For alternatives to VNC Viewer, see Connecting from alternatives to VNC Viewer on page15.

Connecting to VNC 5.x

You can establish a connection from VNC Viewer to the latest version of VNC Server incorporated in VNC
5.x providing the following conditions are met.
VNC Server

VNC Viewer

Enterprise

Personal

Free

No configuration required.

On the client computer, VNC

Viewer encryption must not be
set to Always Maximum.

On the client computer, VNC

Viewer encryption must not be
set to Always Maximum or
Always on.

Note: For information on VNC Viewer encryption, see Step 4: Request an encrypted connection on
page22.
Restrictions

Connections to VNC Server with a Personal license cannot be encrypted using ultra-secure 256-bit AES.

Connections to VNC Server with a Free license cannot be encrypted at all.

The credentials you enter to log on to your client computer cannot authenticate you automatically to VNC
Server with a Personal license.

The credentials of a user account on the host computer cannot be used to authenticate to VNC Server
with a Free license.

Connections to VNC Server with a Free license are not optimized for performance.

VNC Viewer for Java cannot be downloaded from VNC Server with a Free license.

Note that once a connection to VNC Server with a Free license is established, you cannot perform the
following operations:

Exchange files with the host computer.

Print host computer files to a local printer.

Chat with other connected users, or with a host computer user.

VNC User Guide

13

Chapter 1: Introduction

Connecting to VNC Enterprise Edition or VNC Personal Edition 4.6

You can establish a connection from VNC Viewer to VNC Server incorporated in VNC Enterprise Edition or
VNC Personal Edition 4.6 without configuration.
Restrictions

The credentials of a user account on the host computer cannot be used to authenticate to VNC Personal
Edition.

Connecting to VNC Enterprise Edition or VNC Personal Edition 4.5 or

earlier
You can establish a connection from VNC Viewer to VNC Server incorporated in VNC Enterprise Edition or
VNC Personal Edition 4.5 or earlier providing the following conditions are met.
VNC Server

VNC Viewer

VNC Enterprise Edition 4.5-

VNC Personal Edition 4.5-

On the client computer, VNC Viewer encryption

must not be set to Always Maximum.

On the client computer, VNC Viewer encryption

must not be set to Always Maximum.

Restrictions

Connections to VNC Enterprise Edition and VNC Personal Edition cannot be encrypted using ultrasecure 256-bit AES.

The credentials of a user account on the host computer cannot be used to authenticate to VNC Personal
Edition.

Once a connection is established, you cannot:

Exchange files with VNC Enterprise Edition or VNC Personal Edition 4.3 or earlier. Note under Windows,
there are also certain restrictions when connected to version 4.5 and 4.4 as well.

Print VNC Enterprise Edition or VNC Personal Edition 4.4 or earlier files.

Chat with VNC Enterprise Edition or VNC Personal Edition 4.4 or earlier users.

14

VNC User Guide

Chapter 1: Introduction

Connecting to VNC-compatible Server software

You can establish a connection from VNC Viewer to the following (selected) third party VNC-compatible
Server software providing certain conditions are met.
VNC-Compatible Server software

VNC Viewer

Apple Remote Desktop or

Screen Sharing built-in to Mac
OS X

Remote Desktop or Desktop

Sharing built-in to Ubuntu

Community projects such as

TightVNC or UltraVNC

On the host computer, VNC

viewers may control screen
with password must be turned
on, and a password set.

On the host computer, Allow

other users to view your
desktop and Allow other users
to control your desktop must
be turned on.

On the client computer, VNC

Viewer encryption must not be
set to Always Maximum or
Always on.

On the client computer, VNC

Viewer encryption must not be
set to Always Maximum or
Always on.

On the client computer, VNC

Viewer encryption must not be
set to Always Maximum or
Always on.

Restrictions

Note that no VNC remote control features are available for connections to host computers running VNCcompatible Server software. In particular, connections cannot be encrypted.

Connecting from alternatives to VNC Viewer

You can connect to the latest version of VNC Server from the following alternatives to VNC Viewer:

VNC Viewer for Java. See Connecting from VNC Viewer for Java on page15.

VNC Viewer Plus. See Connecting from VNC Viewer Plus on page16.

VNC Viewer for iOS. See Connecting from mobile devices on page16.

VNC Viewer for Android. See Connecting from mobile devices on page16.

VNC Viewer for Google Chrome. See Connecting from VNC Viewer for Google Chrome on page16.

VNC-compatible Viewer software from third parties. See Connecting from VNC-compatible Viewer
software on page17.

Connecting from VNC Viewer for Java

You can use any modern web browser to download VNC Viewer for Java on demand from VNC Server with
an Enterprise or a Personal license, and then immediately connect.
Note: You cannot download VNC Viewer for Java from VNC Server with a Free license.
You do not require administrative privileges in order to download and use VNC Viewer for Java. For more
information, see Chapter 4, Connecting From A Web Browser on page51.

VNC User Guide

15

Chapter 1: Introduction

Restrictions

Once a connection is established, you cannot:

Exchange files with the host computer.

Print host computer files.

Chat with other connected users, or with a host computer user.

Save connections.

Scale the host computers desktop.

Connecting from VNC Viewer Plus

You can purchase and install VNC Viewer Plus from www.realvnc.com/products/viewerplus/.
In order to make a standard VNC connection, select VNC from the Connection Mode dropdown on the VNC
Viewer Plus dialog.
Restrictions

Once a connection is established, you cannot save connections to VNC Address Book.

Connecting from mobile devices

You can purchase and install:

VNC Viewer for iOS from the Apple App Store. Visit www.realvnc.com/products/ios/ for more information.

VNC Viewer for Android from Google Play. Visit www.realvnc.com/products/android/ for more
information.

Restrictions

Once a connection is established, you cannot:

Exchange files with the host computer.

Print host computer files.

Make the connection view only.

Chat with other connected users, or with a host computer user.

Connecting from VNC Viewer for Google Chrome

If you have the Google Chrome web browser version 25 or later, you can download and install VNC Viewer
for Google Chrome from the Google Chrome Web Store for free, and use it to connect.
You do not require administrative privileges in order to download and use VNC Viewer for Google Chrome.
For more information, visit www.realvnc.com/products/chrome/.
Restrictions

Once a connection is established, you cannot:

Exchange files with the host computer.

Print host computer files.

16

VNC User Guide

Chapter 1: Introduction

Copy and paste text

Chat with other connected users, or with a host computer user.

Save connections.

Scale the host computers desktop.

Connecting from VNC-compatible Viewer software

Other organizations offer VNC-compatible Viewer applications, for example Remote Desktop Viewer built-in
to Ubuntu.
If you wish to allow connections to VNC Server with an Enterprise or a Personal license, make sure:

Encryption is turned off. See Changing the encryption rules on page104.

System authentication or single sign-on are not selected. See Relaxing the authentication rules on
page99.

Restrictions

Note that no VNC remote control features are available for connections from client computers running VNCcompatible Viewer software. In particular, connections cannot be encrypted.

What to read next

RealVNC remote control software can be used in many different ways to solve many different kinds of
problem. There is no such thing as a typical RealVNC user or remote control session.
For example, you may be sitting in front of the client computer and want to know how to use VNC Viewer to
control a remote host. There may or may not be a host computer user for you to communicate with, and you
may be sharing the host computers desktopand therefore controlwith other users. Or you may be sitting
in front of the host computer and need to know how to set up VNC Server for multiple incoming connections.
You may be connecting within a corporate network, in which case a system administrator might be available
to help with connection issues. Or you may be helping friends or family over the Internet, and have to
negotiate firewalls and routers on your own.
RealVNC remote control software is designed to be as useful out-of-the-box to as many people as possible.
However, there is virtually no limit to the ways in which it can be configured to suit your requirements and
environment. Some chapters in this User Guide are targeted at more experienced users, likely to require the
power of changing options system administrators setting up VNC Server for virtualization or remote
configuration, for example. Other chapters, especially the first two, should be useful for all users.

To walk through establishing your first connection from a client computer running VNC Viewer to a host
computer running VNC Server, see Chapter 2, Getting Connected on page19.

To learn how to use features of VNC Viewer to enhance your experience of controlling a host computer,
read Chapter 3, Using VNC Viewer on page35.

If you want to control a host computer from a web browser instead of VNC Viewer, read Chapter 4,
Connecting From A Web Browser on page51.

To see how to exchange information between client and host computers, read Chapter 5, Exchanging
Information on page61.

VNC User Guide

17

Chapter 1: Introduction

To learn how to configure VNC Server on the host computer, and for advanced topics such as running
multiple instances of VNC Server, see Chapter 6, Working With VNC Server on page73.

By default, VNC Server authenticates connecting users and, depending on the license, encrypts
connections end-to-end. To learn more about security, and how to relax the rules if you consider it safe to
do so, read Chapter 7, Making Connections Secure on page95.

18

VNC User Guide

2
Getting Connected
This chapter aims to help the majority of users get started establishing their first connection from a client
computer running the latest version of VNC Viewer to a host computer running the same version of VNC
Server with an Enterprise license. For a list of other products and license types to which these instructions
may also apply, see Applicable software on page7.
Note: This chapter assumes both host and client computers are set up correctly. For more information, see
Getting two computers ready to use on page11.
Connecting is usually a straightforward process but because computer networks must be secure, problems
can occasionally occur. This chapter offers help for the most common connection issues but it may also be
necessary to consult the RealVNC web site, or contact Technical Support. Alternatively, if you are
connecting within a private network such as a corporate Local Area Network (LAN), consult your system
administrator.

Contents
Step 1: Ensure VNC Server is running on the host computer

20

Step 2: Start VNC Viewer on the client computer

21

Step 3: Identify VNC Server running on the host computer

21

Step 4: Request an encrypted connection

22

Step 5: Connect to VNC Server

23

Troubleshooting connection

26

VNC User Guide

19

Chapter 2: Getting Connected

Step 1: Ensure VNC Server is running on the host

computer
VNC Server may already be running on the host computer, but to make sure, and if you have access, follow
the appropriate instructions for the host computers platform below. If you do not have access, contact your
system administrator or a host computer user.

Under Windows, search for or navigate to the VNC Server program, or double-click the VNC Server
shortcut icon, if available on the desktop. Note administrative privileges are required.

Under UNIX, search for or navigate to the VNC Server (User Mode) program.

Under Mac OS X, search for or navigate to the VNC Server program. Note administrative privileges are
required.

Note: For alternatives ways to start VNC Server, and more information about different modes, see Starting
VNC Server on page75.
The VNC Server dialog opens:

If the status bar is green, VNC Server should be licensed and configured correctly for connections.
If VNC Server is not licensed, or it is not configured correctly, the status bar turns red. Click the Show button
that appears, and follow the instructions. For more information, consult Troubleshooting connection on
page26.

20

VNC User Guide

Chapter 2: Getting Connected

Step 2: Start VNC Viewer on the client computer

To start VNC Viewer, either:

Double-click the VNC Viewer shortcut icon, if available on the desktop.

Search for or navigate to the VNC Viewer program, if VNC Viewer is installed on the client computer.
See Setting up the client computer on page12 for more information.

Run the appropriate platform-specific command from these tables on page192 in a Terminal window or
Command Prompt.

The VNC Viewer dialog opens:

Step 3: Identify VNC Server running on the host

computer
You must uniquely identify VNC Server running on the host computer you want to control.
If you are connecting within a private network such as a LAN or VPN, enter the network address of the host
computer itself in the VNC Server dropdown. This address can take the following forms:

A host name, for example johndoe. (Note the host computer may not have a host name.)

An IP address in IPv4 format, for example 192.168.5.54.

An IP address in IPv6 format within square brackets, for example [2001:db8::1]. (Note IPv6 may not
be enabled.)

If you do not know the network address of the host computer, start with Connecting within a private network
on page28.
If you are connecting over the Internet, and the host computer is protected by a router, then enter the
network address of the router in the VNC Server dropdown instead. If you do not know the network address
of the router, see Connecting over the Internet on page28.

VNC User Guide

21

Chapter 2: Getting Connected

In the following example, the host computer is identified by an IPv4 network address:

Typically, a host computer needs no further identification. This is because, by default, VNC Server listens for
network communications on a registered port, 5900. Carry on from Step 4: Request an encrypted
connection on page22.
There may be circumstances, however, when VNC Server is listening on a different port. This can occur if
the host computer is running UNIX, or if more than one instance of VNC Server is running on the host
computer. If, when you try to connect, you see an error message similar to the following:
Connection refused (10061)

then you probably need to qualify the network address with a port number. For more information, see
Qualifying a network address with a port number on page30.

Step 4: Request an encrypted connection

You can request that the connection be encrypted.
Encryption ensures that data exchanged between the two computers while the connection is in progress
cannot be intercepted by third parties. Note that requesting encryption is not a guarantee; VNC Server
determines whether or not the connection will actually be encrypted.
Note: For more information on encryption, and security in general, see Chapter 7, Making Connections
Secure on page95.
By default, connections to VNC Server with:

An Enterprise license are encrypted using industry-standard 128-bit AES. You can request that this be
enhanced to ultra-secure 256-bit AES.

A Personal license are encrypted using industry-standard 128-bit AES.

A Free license cannot be encrypted. Upgrade to an Enterprise or a Personal license if security is

important to you.

22

VNC User Guide

Chapter 2: Getting Connected

By default, the Encryption dropdown in the VNC Viewer dialog is set to Let VNC Server choose:

If you are connecting to VNC Server with:

An Enterprise or a Personal license, it is recommended you retain this option unless you have a good
reason to either request that encryption be:
Enhanced to 256-bit AES for connections to VNC Server with an Enterprise license only.
Turned off.
For more information on these operations, see Changing the encryption rules on page104.

A Free license, do not change this option. Doing so may prevent you connecting. For more information,
see Connectivity and feature matrix on page13.

Step 5: Connect to VNC Server

To connect to VNC Server, click the Connect button at the bottom of the VNC Viewer dialog:

You are guided through steps to ensure that the connection is legitimate and secure.

VNC User Guide

23

Chapter 2: Getting Connected

Checking the identity of VNC Server

If you are connecting to VNC Server with an Enterprise or a Personal license, you may see a message
similar to the following:

If you have access to the host computer, or can communicate with a host computer user, you can check that
VNC Viewer is connecting to the intended destination (and not, for example, a malicious third party) by
comparing the signature (or more-memorable catchphrase) with that displayed in the Get Started section of
the VNC Server dialog:

If you see any other message referring to the VNC Server signature, it is recommended that you do not
connect. For more information on this security feature, see Verifying the identity of VNC Server on page114.
Click the Yes button to continue connecting to VNC Server.

24

VNC User Guide

Chapter 2: Getting Connected

Acknowledging the encryption status

If the connection will not be encrypted, you are prompted to acknowledge that sensitive information may not
be secure:

If you are connecting to VNC Server with an Enterprise or a Personal license, you may be able to turn
encryption on. Click the Cancel button and see Changing the encryption rules on page104 for more
information. Otherwise, click Continue.

Entering authentication credentials

You may be required to enter a user name and/or a password:

By default, if you are connecting to VNC Server with:

An Enterprise or a Personal license, enter the user name and password you use to log on to the host
computer. If these system credentials do not work and you have access to the host computer, you may
be able to register your user account; see Authenticating using system credentials on page96 for more
information. If you do not have access, contact a system administrator or a host computer user.

A Free license, enter the VNC password, leaving the Username field blank. If you do not know this
password but have access to the host computer, you may be able to reset it; see Authenticating using a

VNC User Guide

25

Chapter 2: Getting Connected

password specific to VNC on page98 for more information. If you do not have access, contact a system
administrator or a host computer user.
Click the OK button. If the connection succeeds, VNC Viewer displays the host computers desktop in a new
window on the client computer. Carry on from The VNC Viewer user experience on page40.
If the connection fails for any reason, start with Troubleshooting connection on page26.
Note: Once connected, you can save a connection so you can quickly reconnect without having to
remember the network address and authentication credentials. For more information, see Appendix A,
Saving Connections on page117.

Troubleshooting connection
This section provides additional information to help you connect.
If, after reading this, you still cannot connect:
1. Consult www.realvnc.com.
2. You may be eligible to contact Technical Support. Start with Contacting Technical Support on page8.
3. If all else fails, and providing you have a secure network environment and a host computer user is present, you can ask that person to connect to you. For more information, see Establishing a reverse connection on page102.

Licensing VNC Server

VNC Server must be licensed. If it is not, users cannot connect.
Note: VNC Viewer does not require a license key.
If VNC Server is not licensed, the status bar on the VNC Server dialog turns red:

26

VNC User Guide

Chapter 2: Getting Connected

Click the Show button to see more information:

Click the Resolve button to start the process of licensing VNC Server, and follow the instructions. See
Licensing VNC Server on page74 for more information.

VNC User Guide

27

Chapter 2: Getting Connected

Connecting within a private network

If both client and host computers are managed within a closed network environment such as a LAN or VPN,
you are connecting within a private network. This is common in corporate and other enterprise
environments, and may also be the case if you are connecting two computers at home.
To connect within a private network, enter the network address of the host computer itself in the VNC
Viewer dialog, for example:

If you do not know the network address of the host computer:

And you do not have access to it, you will need to consult your system administrator or a host computer
user.

And you do have access to the host computer:

a. Open the VNC Server dialog. More on this dialog.
b. Examine the appropriate section of the Get Started section:

Connecting over the Internet

If you are connecting over the Internet (for example, to friends and family, over a cellular network, or in to the
office on the move), it is very likely that the host computer will be protected by a router or similar device
acting as a communication gateway and public interface.
Note: The host computer is also very likely to be protected by a firewall. For more information, see Allowing
network communications through a firewall on page31.

28

VNC User Guide

Chapter 2: Getting Connected

To connect over the Internet, enter the network address of the router in the VNC Viewer dialog, for example:

If you do not know the network address of a host computers router:

And you do not have access to the host computer, you will need to ask a host computer user either to
follow the instructions below, or to visit www.whatismyip.com.

And you do have access to the host computer:

a. Open the VNC Server shortcut menu. More on this menu.
b. Choose Information Center and, on the Diagnostics tab, click the Test Internet Connection
button.
c. Click the Start button. RealVNC attempts to contact the host computer over the Internet. Providing
the host computer is connected to the Internet, the network address of an intermediary device is
revealed:
VNC Server appears to be behind a NAT router with IP address 212.44.6.81.
You will need to configure that router to forward port 5900 to this
computer before you can connect to VNC Server over the Internet.

Configuring a router to forward network communications

In a typical home or small office environment, a router assigns a private network address to an internal
computer. You should also be aware that VNC Server listens for network communications on a particular
port. The router must be configured to forward communications from VNC Viewer to the correct port at the
correct private network address. This procedure is known as port forwarding.
Note: Port forwarding instructions are specific to routers. If you do not have access to the host computer,
ask a host computer user to consult the manufacturers documentation, or visit www.portforward.com.
Note that a router may act as a public interface to more than one computer in a home or small office
environment. If you want to connect to multiple host computers, then VNC Server must be running on each
and listening on a different port. The router must be configured to distinguish between host computers using
port numbers.

VNC User Guide

29

Chapter 2: Getting Connected

Consider the following example:

A. Router with a network address assigned by an ISP, for example 212.44.6.81. B. Host computer with a network
address assigned by the router, for example 192.168.0.1. VNC Server is listening on the default port, 5900. C. Host
computer with a network address assigned by the router, for example 192.168.0.2. VNC Server has been configured to
listen on port 5901. D. Client computer running VNC Viewer.
In this scenario, the router must be configured to forward port 5900 to host computer B at 192.168.0.1 and
port 5901 to host computer C at 192.168.0.2.
When you connect to either host computer from VNC Viewer, you must enter the network address of the
router: 212.44.6.81. In addition, to connect to host computer C, you must qualify the routers network
address with the port number: 212.44.6.81:1. To find out why this is, see Qualifying a network address with
a port number on page30.

Qualifying a network address with a port number

VNC Server listens for network communications on a particular port. By default, and providing it is available
when VNC Server starts, this is port 5900 for connection requests. This port is registered for use by VNC
Server with the Internet Assigned Numbers Authority (IANA).
Note: For more information on ports, see Changing ports on page90.

30

VNC User Guide

Chapter 2: Getting Connected

If VNC Server is listening on any other port, you must qualify the network address of the host computer (or
router) with the port number when you connect from VNC Viewer, for example:

If you know that VNC Server is listening on a port between 5901 and 5999, append a colon (:) and an
identifying number (1 through 99) to the network address, for example:
johndoe:1
192.168.5.54:1
[2001:db8::1]:1

If you know that VNC Server is listening on any other port, append a double colon (::) and the full port
number to the network address, for example:
johndoe::6001
192.168.5.54::6001
[2001:db8::1]::6001

If you do not know on which port VNC Server is listening:

And you do not have access to the host computer, you will need to consult your system administrator or
a host computer user.

And you do have access to the host computer:

a. Open the VNC Server dialog. See how to do this.
b. Examine the appropriate section of the Get Started section:

In this example, VNC Server is running on host computer 192.168.5.54 and listening on port 5901.

Allowing network communications through a firewall

If the host computer is protected by a firewall, then the firewall must be configured to allow incoming network
communications to the port on which VNC Server is listening. To find out which port this is, see Qualifying a
network address with a port number on page30.

VNC User Guide

31

Chapter 2: Getting Connected

The firewall might be automatically configured by the operating system of the host computer. If not, you will
probably see the following error message when you connect from VNC Viewer:
Connection timed out (10060)
The instructions for adding exceptions for ports are specific to firewalls. If you do not have access to the host
computer, ask a host computer user to consult the manufacturers documentation.

Miscellaneous connection messages

This section explains various error messages you might see.

Failing to authenticate correctly

If you see the following error message:
Either the username was not recognized, or the password was incorrect.

then you have not authenticated correctly to VNC Server. Note that user names and passwords are casesensitive.
If you do not know the correct credentials, and you do not have access to the host computer, you will need to
consult your system administrator or a host computer user. If you do have access to the host computer, and
sufficient privileges to configure VNC Server, you may be able to relax the authentication rules. For more
information, see Relaxing the authentication rules on page99.

Failing to authenticate as you

If you see the following error message:
Access is denied.

then VNC Server has been configured to require the system credentials of a user account on the host
computer. Your user account, however, has not been registered with VNC Server.
If this is the case and you do not have access to the host computer, you will need to consult your system
administrator or a host computer user. If you do have access to the host computer, and sufficient privileges
to configure VNC Server, you may be able to register your user account. For more information, see
Managing the list of registered user accounts and groups on page97.

Connecting from an unauthorized computer

If you see the following error message:
The connection closed unexpectedly.

then it could be that VNC Server has been configured to prevent connections from the client computer you
are using.
If this is the case and you do not have access to the host computer, you will need to consult your system
administrator or a host computer user. If you do have access to the host computer, and sufficient privileges

32

VNC User Guide

Chapter 2: Getting Connected

to configure VNC Server, you may be able to unblock your client computer. For more information, see
Preventing connections from particular client computers on page106.
Alternatively, you may be able to connect from a different client computer.

Being rejected by a host computer user

If you see the following error message:
Connection rejected by host computer user.

then VNC Server has been configured to display connection prompts, and your request has either been
explicitly rejected, or has timed out (this could either be because the prompt was deliberately ignored, or
because no-one was present to respond).
If this is the case and you do not have access to the host computer, you will need to consult your system
administrator or a host computer user. If you do have access to the host computer, and sufficient privileges
to configure VNC Server, you may be able to bypass connection prompts. For more information, see
Preventing particular users connecting on page108.

VNC User Guide

33

Chapter 2: Getting Connected

34

VNC User Guide

3
Using VNC Viewer
This chapter explains how to control a host computer to which you are connected using VNC Viewer, and
how VNC Viewer features can enhance your productivity while the connection is in progress.

Contents
Starting VNC Viewer

36

Starting Listening VNC Viewer

36

Configuring VNC Viewer before you connect

37

Connecting to a host computer

39

The VNC Viewer user experience

40

Using the toolbar

42

Using the shortcut menu

43

Using the Options dialog

44

Managing the current connection

45

Changing appearance and behavior

46

Restricting access to features

48

VNC User Guide

35

Chapter 3: Using VNC Viewer

Starting VNC Viewer

To start VNC Viewer, follow the instructions in Step 2: Start VNC Viewer on the client computer on page21.
The VNC Viewer dialog appears:

In most circumstances, VNC Viewer is ready to connect to VNC Server out-of-the-box. Carry on from
Connecting to a host computer on page39.
In some circumstances, you may need to configure VNC Viewer before you connect. For more information,
see Configuring VNC Viewer before you connect on page37.
To see how to start VNC Viewer so that it listens for a reverse connection, see Starting Listening VNC
Viewer on page36.

Starting Listening VNC Viewer

You can start VNC Viewer in such a way that it does not connect to VNC Server but rather waits for VNC
Server to connect to it. This is called a reverse connection. For more information about this feature, and why
you might want to use it in conjunction with a host computer user, see Establishing a reverse connection on
page102.
Note: Reverse connections are not secure and should only be used in a locked-down environment.
To start Listening VNC Viewer:

Under Windows or Mac OS X, search for or navigate to the Listening VNC Viewer program.

Under UNIX, you must start Listening VNC Viewer at the command line. Run the appropriate command
from this table on page192 in a Terminal window.

Using Listening VNC Viewer

Under Windows and Mac OS X, a VNC Viewer icon
is displayed in the Notification area or Status bar
respectively when Listening VNC Viewer starts. Note that under Windows 7, the Notification area is hidden
by default and accessible only from

36

VNC User Guide

to the right of the Taskbar.

Chapter 3: Using VNC Viewer

Note: Under UNIX, no user interface is available for you to work with Listening VNC Viewer. If you need to
configure it before it starts, read Specifying VNC parameters on page130.
Under Windows and Mac OS X, hover the mouse cursor over the icon to confirm that Listening VNC Viewer
is running:

The VNC Viewer icon has a shortcut menu:

You do not need to configure Listening VNC Viewer, but if you want to do so before a connection is
established, select Default Options. For more information, start with Configuring VNC Viewer before you
connect on page37.
Note: Select New Connection to establish a connection to VNC Server in the normal way. Carry on from
Connecting to a host computer on page39.
If when a host computer user attempts to establish a reverse connection:

it is successful, Listening VNC Viewer displays the host computers desktop in a new window on the
client computer in exactly the same way as VNC Viewer. Carry on from The VNC Viewer user experience
on page40.

It is not successful, read Establishing a reverse connection on page102 in conjuction with the host
computer user.

Configuring VNC Viewer before you connect

In most circumstances, VNC Viewer is ready to connect to VNC Server out-of-the-box. You do not need to
configure it. Carry on from Connecting to a host computer on page39.
However, you may need to configure VNC Viewer before you connect in the following circumstances:

Your client computer is protected by a proxy server. See Connecting via a proxy server on page38.

VNC Server mandates the single sign-on authentication scheme but you do not want to authenticate
automatically as the user you logged on to the client computer as. See Disabling single sign-on on
page39.

You want to specify printing options. See Configuring printing on page39.

VNC User Guide

37

Chapter 3: Using VNC Viewer

To configure VNC Viewer before you connect, click the Options button at the bottom of the VNC Viewer
dialog. The Options dialog opens:

(In this picture, the dialog is in Advanced mode.)

Note that the Connection and Printing tabs are not available after you connect. More on this dialog.

Connecting via a proxy server

If your client computer is protected by a proxy server, you must tell VNC Viewer about that proxy server. On
the Connection tab, choose:

Use Microsoft Internet Explorer proxy settings if you use Internet Explorer and it has already been
provisioned with proxy server information. Note this option has a different name under UNIX and Mac
OS X, and refers to system proxy environment variables.

Use these proxy settings to specify the network address of either an HTTP or a SOCKS 5 proxy
server, and a port on which an appropriate application or process is listening, separated by a colon.
If the proxy server is protected by BASIC or DIGEST authentication, enter a user name and password in
the appropriate boxes.

38

VNC User Guide

Chapter 3: Using VNC Viewer

Disabling single sign-on

Note: The information in this section applies to connections to VNC Server with an Enterprise license only.
By default, if VNC Server specifies single sign-on as its authentication scheme, then you may be able to
connect without supplying a user name and password. This is because you have already successfully
authenticated to the system by logging on to your client computer. For more information, see Authenticating
users automatically on page100.
You can disable this feature if you want to authenticate to VNC Server using the credentials of a different
user account. This might give you access to a different set of remote control features while the connection is
in progress. To do this, turn off Use single sign-on if VNC Server supports it on the Connection tab.

Configuring printing
By default, when you connect to VNC Server with an Enterprise or a Personal license, your client computers
default printer (if it has one) is shared with the host computer and made its default while the connection is in
progress. This means you can print host computer files directly to your local printer. For more information
about this feature, see Printing host computer files to a local printer on page62.
You can print but choose not to change the host computers default printer. This means you will have to
explicitly select your local printer when you print. To do this, turn off Make it the default printer on VNC
Server on the Printing tab.
To disable printing, choose Dont share a printer.

Connecting to a host computer

This section summarizes how to connect from a client computer running VNC Viewer to a host computer
running VNC Server. For a step-by-step guide, see Chapter 2, Getting Connected on page19.
1. Start VNC Viewer on the client computer. The VNC Viewer dialog opens.
2. In the VNC Server dropdown, enter a private or a public network address for the host computer, qualified, if applicable, by the port number on which VNC Server is listening, for example 192.168.5.54:1.
3. From the Encryption dropdown, select an encryption option, or retain the default: Let VNC Server
choose.
4. Click the Connect button.
You may be asked to confirm a VNC Server signature, acknowledge the encryption status, and authenticate
to VNC Server.
If the connection is successful, VNC Viewer displays the host computers desktop in a new window on the
client computer. Carry on from The VNC Viewer user experience on page40. If the connection fails for any
reason, start with Troubleshooting connection on page26.
Note: Once connected, you can save a connection so you can quickly reconnect without having to
remember the network address and authentication credentials. For more information, see Appendix A,
Saving Connections on page117.

VNC User Guide

39

Chapter 3: Using VNC Viewer

The VNC Viewer user experience

The rest of this chapter assumes you are successfully connected to a host computer. If not, see Connecting
to a host computer on page39.
When a connection is established, VNC Viewer displays the host computers desktop in a new window on
the client computer:

A. Desktop of a client computer running Windows 7. B. VNC Viewer displaying the desktop of a host computer
running Ubuntu 11.04 Linux.
Note: If the host computer is running UNIX, VNC Viewer may display a virtual desktop instead, in which
case what you see is not the desktop visible to a host computer user. For more information on this feature,
see Running multiple instances of VNC Server on page78.

40

VNC User Guide

Chapter 3: Using VNC Viewer

Note that other VNC Viewer users may be connected to the host computer and controlling it at the same
time as you. In addition, a host computer user may be present. Operations may occur unexpectedly!

Controlling the host computer using your mouse

Your client computers mouse is now shared with the host computer. This means that:

Moving the mouse and clicking within the VNC Viewer window affects the host computer and not the
client.

Moving the mouse and clicking outside the VNC Viewer window, or on the VNC Viewer title bar or
window buttons (Minimize, Maximize, and Close), affects the client computer and not the host.

Note: If your mouse has no effect on the host computer, it may have been disabled. For more information,
see Restricting access to features on page48.
If client and host computers have different numbers of mouse buttons, you can configure VNC Viewer to
emulate those you do not have. See Configuring your mouse on page47 for more information.

Controlling the host computer using your keyboard

Your client computers keyboard is now shared with the host computer, with the exception of:

The function key that opens the shortcut menu (F8 by default).

The CTRL-ALT-DELETE key combination.

These commands are interpreted by the client computer. Alternative ways of sending them to the host
computer are available; start with Using the shortcut menu on page43 for more information. Under
Windows and Mac OS X, note you can cause certain other keys and key combinations to be interpreted by
your client computer rather than the host. See Configuring your keyboard on page47 for more information.
Note: If your keyboard has no effect on the host computer, it may have been disabled. For more information,
see Restricting access to features on page48.
Note it is possible for client and host computers to have different types of keyboard. Not all the keys available
to a host computer user may be available to you, and some keys with the same name may have different
behavior. This is especially likely if you are connecting to Mac OS X from Windows or Linux with a PC
keyboard or vice versa; see www.realvnc.com/products/vnc/documentation/latest/misc/keyboard-mapping/.

Interacting with VNC Server

When you connect, a VNC Server icon

and VNC Server dialog will likely be available:

(VNC Server icon shaded black to indicate a connection is in progress.)

See The VNC Server user interface on page82 for more information.

VNC User Guide

41

Chapter 3: Using VNC Viewer

Using the toolbar

VNC Viewer has a toolbar to facilitate common operations.
Note: If you cannot access the VNC Viewer toolbar, it may have been disabled. For more information, see
Changing appearance and behavior on page46.
The VNC Viewer toolbar is located at the top center of the VNC Viewer window. To use it, hover the mouse
cursor over the hot area:

The following table explains the effect of clicking each toolbar button.
Button

Purpose

New Connection

Establish a new connection. See Connecting to a host computer on page39.

Save Connection

Save the current connection so you can quickly reconnect without having to
remember the network address and authentication credentials. See Appendix A,
Saving Connections on page117.

Close Connection

Close the current connection (and the VNC Viewer window).

Options

Configure most aspects of VNC Viewer while the current connection is in progress.
See Using the Options dialog on page44.
Note that some options must be configured before you connect. See Configuring
VNC Viewer before you connect on page37.

42

Full Screen Mode

Toggle full screen mode on and off.

Send Ctrl-Alt-Del

Send the CTRL-ALT-DELETE command to the host computer. (Pressing this key
combination will be interpreted by the client computer.) You could alternatively
press SHIFT-CTRL-ALT-DELETE.

File Transfer

Browse to the location of client computer files to send to the host computer. See
Transfering files between client and host computers on page64.

Start Chat Session

Chat with other VNC Viewer users connected to the same host computer, or with a
host computer user. See Communicating securely using chat on page69.

Connection
Information

Display technical information about the current connection, such as the encryption
method and compression format. You may need this if you contact Technical
Support.

connection speed

Hover over to reveal the current connection speed. For more information on
performance, see Changing appearance and behavior on page46.

VNC User Guide

Chapter 3: Using VNC Viewer

Using the shortcut menu

VNC Viewer has a shortcut menu that facilitates many of the same common operations as the VNC Viewer
toolbar. More on this toolbar.
Note: If you cannot access the VNC Viewer shortcut menu, it may have been disabled. For more
information, see Changing appearance and behavior on page46.
By default, to open the shortcut menu, press the F8 key (you may need to hold down the FN key on some
PC laptops or Mac OS X computers):

(Some standard Windows menu options have been omitted from this example.)

Note: Under Mac OS X, more Send <key> options are available to send Mac-specific commands to a host
computer also running Mac OS X.
The following table explains the effect of selecting shortcut menu options that do not have equivalent toolbar
buttons.
Option

Purpose

Relative Pointer Motion

Turn on if the host computers mouse cursor appears to be behaving abnormally, for
example by accelerating too fast.

Send F8

Send an F8 command to the host computer. (By default, F8 opens the shortcut menu; see
Changing the shortcut menu key on page48 for how to choose a different key.)

Ctrl key

Turn on to simulate holding down the CTRL key.

Alt key

Turn on to simulate holding down the ALT key.

Refresh Screen

Refresh the display of the host computers desktop.

VNC User Guide

43

Chapter 3: Using VNC Viewer

Option

Purpose

About VNC Viewer

Display version information. You may need this if you contact Technical Support.

Using the Options dialog

The Options dialog allows you to configure VNC Viewer while a connection is in progress:

(In this picture, the dialog is in Advanced mode.)

Note: Some VNC Viewer options must be configured before you connect. For more information, see
Configuring VNC Viewer before you connect on page37.
To open the Options dialog, click the Options
toolbar button, or select Options from the shortcut menu.
(If the VNC Viewer toolbar or shortcut menu are not accessible, see Changing appearance and behavior on
page46.)

44

VNC User Guide

Chapter 3: Using VNC Viewer

The first time you open this dialog, it opens in Basic mode, and only one tab is available, containing the most
common options. Click the Advanced button in the bottom left corner to switch to Advanced mode and see
all the tabs in the example above. Note that the Expert tab is recommended for expert users only.
By default, any changes you make apply both to the current connection and to all future connections to any
host computer. To apply changes just to the current connection, turn off Use these settings for all new
connections first.
Many of the options in this dialog are explained in the remainder of this chapter.

Managing the current connection

You can manage aspects of the current connection while it is in progress.
Note: Most of the operations described in this section are facilitated by the VNC Viewer toolbar. More on this
toolbar.

Saving the current connection

You can save the current connection so you can quickly reconnect without having to remember the network
address and authentication credentials. In addition, your preferred VNC Viewer environment for controlling
the host computer is automatically recreated each time.
To save the current connection, click the Save Connection
Saving Connections on page117.

toolbar button. Carry on from Appendix A,

Establishing a new connection

You can establish a new connection to the same host computer, or to a different one.
To do this, click the New Connection
toolbar button. The VNC Viewer dialog opens. Carry on from
Connecting to a host computer on page39.
By default, any options you configure are inherited by the new connection. To prevent this, open the Options
dialog and turn off Use these settings for all new connections first. More on this dialog.

Closing the current connection

You can quickly close the current connection. To do this, click the Close Connection
are prompted to confirm the operation before the VNC Viewer window closes.

toolbar button. You

VNC User Guide

45

Chapter 3: Using VNC Viewer

Changing appearance and behavior

By default, when a connection is established:

VNC Viewer does not scale the host computers desktop. Instead, scroll bars are added to the window if
the desktop is too large.

The VNC Viewer window is set to a particular size.

VNC Viewer displays the host computers desktop in a color quality appropriate to the network
connection speed.

Your mouse and keyboard are set to interact with the client and host computers in particular ways.

The VNC Viewer toolbar is accessible (from the top center hot area).

The VNC Viewer shortcut menu is accessible (by pressing F8).

You can change these defaults by configuring options on the Display tab of the Options dialog. More on
this dialog.

46

VNC User Guide

Chapter 3: Using VNC Viewer

Scaling the host computers desktop

You can scale the host computers desktop, which might make it easier to navigate and to use.
To scale the desktop to the size of the VNC Viewer window, choose Scale to window size.
To scale the desktop to a custom size, choose Custom scaling, and specify a width and height. Turn on
Preserve aspect ratio to automatically calculate a height for a given width, and vice versa. Note that the
VNC Viewer window inherits these dimensions and cannot be made bigger using the mouse (only smaller).

Changing the size of the VNC Viewer window

You can use the mouse to resize the VNC Viewer window in the expected way for the platform of the client
computer. The windows Application buttons (Minimize, Maximize, and Close) also work as expected.
To toggle full screen mode on and off, click the Full Screen Mode
displayed in this mode; bump the mouse against an edge to scroll.

toolbar button. Note scroll bars are not

Trading performance for picture quality

You may be able to enhance the performance of the connection by reducing the number of colors used to
display the host computers desktop. To do this, turn off Adapt to network speed, and move the slider
towards Best compression.
Conversely, you may be able to improve the picture quality by increasing the number of colors. To do this,
move the slider towards Best quality. Note that sending more pixel information across the network may
have an adverse effect on performance.

Configuring your mouse

Note: The information in this section applies to VNC Viewer for Windows and Mac OS X only.
You can emulate buttons missing because your mouse has fewer buttons than the host computers mouse.
For example, if your mouse only has two buttons, turn on Enable 3-button mouse emulation. To emulate
the missing middle button, click the left and right mouse buttons simultaneously. Under Mac OS X, if your
mouse only has one button, you can also, or alternatively, turn on Enable 2-button mouse emulation. To
emulate the missing right button, hold down the CTRL key and press the button.
Note these options are on the Inputs tab.

Configuring your keyboard

Note: The information in this section applies to VNC Viewer for Windows and Mac OS X only.
By default, and with the exception of CTRL-ALT-DELETE and the function key used to open the shortcut
menu, key presses affect the host computer and not the client. To reverse this behavior and cause the client
computer to be affected by the following keys and key combinations:

Under Windows, turn off Pass special keys directly to VNC Server for WINDOWS (also known as
START), PRINT SCREEN, ALT-TAB, ALT-ESCAPE, CTRL-ESCAPE.

Under Mac OS X, turn off Pass media keys directly to VNC Server for VOLUME UP, PLAY, and similar
media keys.

VNC User Guide

47

Chapter 3: Using VNC Viewer

Note these options are on the Inputs tab.

Disabling the toolbar

You can disable the VNC Viewer toolbar. More on this toolbar. To do this, turn off Enable toolbar.
Note that if you disable the VNC Viewer shortcut menu as well you will not be able to access the VNC Viewer
toolbar again while the current connection is in progress.

Disabling the shortcut menu

You can disable the VNC Viewer shortcut menu. More on this menu. To do this, select none from the Menu
key dropdown. Note this option is on the Inputs tab.
Note that if you disable the VNC Viewer toolbar as well you will not be able to access the VNC Viewer
shortcut menu again while the current connection is in progress.

Changing the shortcut menu key

You can change the function key used to open the shortcut menu. To do this, select a function key from the
Menu key dropdown. Note this option is on the Inputs tab. The shortcut menu updates to reflect the fact
that you can no longer press the chosen key to send a command to the host computer.

Restricting access to features

By default, while a connection is in progress, you can control the host computer using your keyboard and
mouse, and in addition copy and paste text between applications running on the client and host computers.
For connections to VNC Server with an Enterprise or a Personal license, you can also:

Print host computer files directly to a local printer.

Exchange files with the host computer.

Chat with other VNC Viewer users connected to the same host computer, or with a host computer user.

Note that:

VNC Viewer might have been configured to disable printing before the connection started; see
Configuring printing on page39.

VNC Server may have been configured to prevent some or all of these features; see Restricting
functionality for connected users on page109.

48

VNC User Guide

Chapter 3: Using VNC Viewer

You can restrict access to features while the connection is in progress by configuring options on the Inputs
tab of the Options dialog. More on this dialog. You might want to do this if you are watching a
demonstration on the host computer, for example, and want to prevent inadvertent interruption.

Note: You can enable features again at any time. To prevent this for the current connection only, disable the
VNC Viewer toolbar and shortcut menu. For more information, see Changing appearance and behavior on
page46.

Making VNC Viewer view only

You can quickly prevent all interchange with the host computer, making VNC Viewer view only. To do this,
select Disabled (view-only mode) from the Inputs dropdown.

Disabling your keyboard

You can disable the client computers keyboard. To do this, turn off Enable keyboard input.

VNC User Guide

49

Chapter 3: Using VNC Viewer

Disabling your mouse

You can disable the client computers mouse. To do this, turn off Enable mouse input.

Disabling file transfer

You can disable file transfer between client and host computers. To do this, turn off Enable file transfer.
For more information about this feature, see Transfering files between client and host computers on
page64.

Disabling copy and paste text

You can disable copy and paste text between applications running on the client and host computers. To do
this, turn off Share clipboard with VNC Server.
For more information about this feature, see Copying and pasting text between client and host computers
on page68.

Disabling chat
You can disable chat. To do this, turn off Enable chat. For more information about this feature, see
Communicating securely using chat on page69.

50

VNC User Guide

4
Connecting From A Web Browser
This chapter explains how to connect to and control a host computer using VNC Viewer for Java. All you
need to do this is a Java-enabled web browser with which to download VNC Viewer for Java from VNC
Server with an Enterprise or a Personal license on demand; you do not have to install any software. This
may be useful if you are at an Internet caf, for example.
Note: VNC Viewer for Java is not available to download from VNC Server with a Free license.
Once downloaded, you can use the VNC Viewer for Java applet to establish a connection in exactly the
same way as VNC Viewer. You use your mouse and keyboard to control the host computer exactly as you
would using VNC Viewer.
Note: VNC Viewer for Java has considerably fewer remote control features than VNC Viewer. For more
information, see Connecting from VNC Viewer for Java on page15.

Contents
Connecting to a host computer

52

The VNC Viewer for Java user experience

56

Working with VNC Viewer for Java

57

VNC User Guide

51

Chapter 4: Connecting From A Web Browser

Connecting to a host computer

Connecting to a host computer is a two-stage process using VNC Viewer for Java:
1. Download VNC Viewer for Java from VNC Server with an Enterprise or a Personal license running on the
host computer you want to connect to. See Downloading VNC Viewer for Java on page52.
2. Use the VNC Viewer for Java applet to connect to VNC Server. See Connecting to VNC Server on
page54.

Downloading VNC Viewer for Java

The first stage is to download VNC Viewer for Java to your web browser on demand. To do this:
1. Start a Java-enabled web browser on the client computer, for example the latest version of Internet
Explorer, Firefox, Safari, or Chrome.
Note: For more information on Java, visit www.java.com. Note that Java (JRE or JDK) 5+ must be
installed on the client computer.
2. In the address bar, enter http:// and the network address of the host computer, qualified by the port
number on which VNC Server is listening for download requests, for example http://
192.168.5.54:5800.
If you do not know a network address for the host computer and you do not have access to it, you will
need to consult your system administrator or a host computer user. If you do have access to the host
computer, and you are connecting within a private network, the information you need is displayed in the
Get Started section of the VNC Server dialog. More on this dialog.

Note: If you are connecting over the Internet, you will probably need to enter the network address of a
router instead. See Connecting over the Internet on page28 for more information.
By default, VNC Server listens for download requests on port 5800. If the download request fails, it may
be because VNC Server is listening on a different port; see Qualifying a network address with a port
number on page30 for more information. A download request may also fail if the host computer is
protected by a router and/or a firewall and these devices have not been configured to allow access to
VNC Server at the correct port. For more information on this, and connection issues in general, see
Troubleshooting connection on page26.

52

VNC User Guide

Chapter 4: Connecting From A Web Browser

3. If this is the first time you have downloaded VNC Viewer for Java, you are prompted to trust it:

You can do this in complete confidence. However, you can choose not to trust VNC Viewer for Java and
still connect, though note you cannot copy and paste text between applications in the normal way.
In the example above, click the Run button to trust VNC Viewer for Java, and Cancel to continue
connecting without trusting it.
If VNC Viewer for Java successfully downloads, the VNC Viewer dialog opens:

(In this picture, the web browser is Firefox 25. Note that the web browser window must stay open while the connection
is in progress.)

VNC User Guide

53

Chapter 4: Connecting From A Web Browser

Connecting to VNC Server

The second stage is to use VNC Viewer for Java to connect to VNC Server. This is the same process as
connecting from VNC Viewer.
The VNC Server dropdown on the VNC Viewer dialog displays the network address of the host computer,
qualified by the port number on which VNC Server is listening for connection requests (in the example
below, the digit 0 corresponds to the default port, 5900):

For more information on network addresses and port numbers, start with Step 3: Identify VNC Server
running on the host computer on page21.
To continue connecting:
1. From the Encryption dropdown, select an encryption option, or retain the default: Let VNC Server
choose. For more information on this, see Step 4: Request an encrypted connection on page22.
2. If you want to configure VNC Viewer for Java before you connect, click the Options button. For information on why you might want to do this, see Configuring VNC Viewer for Java before you connect on
page55.
3. Click the Connect button.
You may be asked to check the identity of VNC Server, acknowledge the encryption status, and
authenticate. For more information on these issues, see Step 5: Connect to VNC Server on page23.
If the connection is successful, VNC Viewer for Java displays the host computers desktop in a new window
on the client computer. Carry on from The VNC Viewer for Java user experience on page56.
If the connection fails for any reason, start with Troubleshooting connection on page26.

54

VNC User Guide

Chapter 4: Connecting From A Web Browser

Configuring VNC Viewer for Java before you connect

VNC Viewer for Java is ready to connect to VNC Server and control a host computer out-of-the-box. You do
not need to configure it. However, you can change some aspects to suit your requirements and environment
if you wish.
Some options must be configured before you connect. Most, however, can be configured once you are
connected, and changes applied to the current connection. For more information, see Using the Options
dialog on page58.
To configure VNC Viewer for Java before you connect, click the Options button in the VNC Viewer dialog.
The Options dialog opens:

The following options must be configured before a connection is made:

To make the connection more secure, choose an alternative to the default key length of 512 bits. This
option is on the Security tab.

To ensure your privacy at the start of the connection, turn off Shared (dont disconnect other VNC
Viewers) in order to disconnect other users. This option is on the Misc tab.

VNC User Guide

55

Chapter 4: Connecting From A Web Browser

The VNC Viewer for Java user experience

When a connection is established, VNC Viewer for Java displays the host computers desktop in a new
window on the client computer:

A. Desktop of a client computer running Windows 7. B. Java-enabled web browser. This window must stay open
while the connection is in progress. C. VNC Viewer for Java displaying the desktop of a host computer running Ubuntu
11.04 Linux.

The client computers mouse and keyboard are now shared with the host computer in exactly the same way
as VNC Viewer. For more information, start with Controlling the host computer using your mouse on
page41.

56

VNC User Guide

Chapter 4: Connecting From A Web Browser

Working with VNC Viewer for Java

You can use VNC Viewer for Java to:

Control the host computer using your keyboard and mouse.

Copy and paste text between applications running on the client and host computers.

Trade performance for picture quality while the connection is in progress.

Restrict access to functionality while the connection is in progress.

See the sections below for more information on these issues. For a summary of functionality that is not
available, see Connecting from VNC Viewer for Java on page15.

Using the VNC Viewer for Java shortcut menu

VNC Viewer for Java has a shortcut menu to facilitate common operations.
Note: VNC Viewer for Java does not have a toolbar.
To open the shortcut menu, press the F8 key (you may need to hold down the FN key under Mac OS X):

The following table explains the effect of selecting these menu options.
Option

Purpose

Exit VNC Viewer

Close the current connection (and the VNC Viewer for Java window).

Clipboard

Preview the contents of the Clipboard and, providing copy and paste is enabled, paste it to an
application running either on the client or on the host computer. See Copying and pasting text
on page59.
Note that if you chose not to trust VNC Viewer for Java when you downloaded it, you can only
copy and paste text between the two computers via this dialog.

Send F8

Send an F8 command to the host computer. (F8 opens the shortcut menu.)

Send Ctrl-Alt-Del

Send the CTRL-ALT-DELETE command to the host computer. (Pressing this key combination
would be interpreted by the client computer.)

VNC User Guide

57

Chapter 4: Connecting From A Web Browser

Option

Purpose

Refresh screen

Refresh the display of the host computers desktop.

New connection

Start a new connection to the same host computer, or to a different one, using the same web
browser session. You do not need to download VNC Viewer for Java again.

Options

Configure most aspects of VNC Viewer for Java while the current connection is in progress. See
Using the Options dialog on page58.
Note that some options must be configured before you connect. See Configuring VNC Viewer for
Java before you connect on page55.

Connection info

Display technical information about the current connection, such as the encryption method and
compression format. You may need this if you contact Technical Support.

About VNC Viewer

Display information about VNC Viewer for Java. You may need this if you contact Technical
Support.

Dismiss menu

Close the shortcut menu.

Using the Options dialog

The Options dialog enables you to configure VNC Viewer for Java while the current connection is in
progress:

Note: Some VNC Viewer for Java options must be configured before you connect. For more information,
see Configuring VNC Viewer for Java before you connect on page55.
To open the Options dialog, select Options from the shortcut menu. More on this menu.
The following sections explain the options in this dialog.

Trading performance for picture quality

You may be able to enhance the performance of VNC Viewer for Java by reducing the number of colors used
to display the host computers desktop. To do this, turn off Auto select and choose either 256, 64, or 8
colors. These options are on the Encoding tab.
You can also choose an alternative to the default ZRLE encoding. The Hextile and Raw encodings require
increasingly less processing power to display the host computers desktop, though note they also require
progressively more bandwidth.

58

VNC User Guide

Chapter 4: Connecting From A Web Browser

Restricting access to functionality

You can quickly prevent all interchange with the host computer, making VNC Viewer for Java view only. To
do this, turn on View only (ignore mouse & keyboard). This option is on the Inputs tab.
You can disable copy and paste, or just copy and paste in a particular direction. For more information, see
Copying and pasting text on page59.

Troubleshooting display
If the mouse cursor is not behaving in the expected way, turn off Render cursor locally. If the screen is not
updating properly, turn off Fast CopyRect. These options are on the Misc tab.

Copying and pasting text

You can copy and paste text between applications running on the client and host computers. This feature
works in the same way as it does for VNC Viewer. See Copying and pasting text between client and host
computers on page68 for more information.
You can preview the contents of the Clipboard to see what text is available to paste. To do this, select
Clipboard from the VNC Viewer for Java shortcut menu. More on this menu. The Clipboard dialog opens:

Disabling and enabling copy and paste

You can disable copy and paste while the current connection is in progress. To do this, open the Options
dialog. More on this dialog. On the Inputs tab, turn off Accept clipboard from VNC Server and Send
clipboard to VNC Server.
Note you can turn these options off separately in order to disable copy and paste in one direction only.

VNC User Guide

59

Chapter 4: Connecting From A Web Browser

60

VNC User Guide

5
Exchanging Information
This chapter explains how to use VNC Viewer to exchange information with the host computer, or with other
VNC Viewer users connected at the same time as you.
Note: Not all features are available for connections to VNC Server with a Free license. For a summary, see
Connecting to VNC 5.x on page13.

Contents
Printing host computer files to a local printer

62

Transfering files between client and host computers

64

Copying and pasting text between client and host computers

68

Communicating securely using chat

69

VNC User Guide

61

Chapter 5: Exchanging Information

Printing host computer files to a local printer

If you are connected to VNC Server with an Enterprise or a Personal license, you can print host computer
files directly to the default printer attached to your client computer (that is, to a local printer).

A. Local printer. B. Client computer running VNC Viewer. Printer A must be the clients default printer. C. Host
computer running VNC Server, and storing the files to print.

Note: To see how to make a printer the client computers default, consult its operating system
documentation.
This powerful feature is ready to use out-of-the-box. Open a host computer file in the VNC Viewer window
and print in the expected way for the application, for example by selecting File > Print. The local printer is
automatically shared with the host computer and made its default while the connection is in progress, so the
correct device should already be selected. Your request is added to the printers queue and executed in turn.
A best possible quality print finish is attempted. This may mean the contents of the file are scaled to fit the
dimensions of the local printers paper. If the results are unexpected, see Manipulating the quality of the
print finish on page62.
If the host computer file does not print to the local printer, start with Troubleshooting printing on page63.

Disabling and enabling printing

You may be allowed to disable printing providing you do so before you connect. Open the Options dialog
and, on the Printing tab, choose Dont share a printer. More on this dialog.
You can still print but choose not to change the host computers default printer. To do this, turn off Make it
the default printer on VNC Server. This means you will have to explicitly select the local printer when you
print. The local printer will have a name of the form <printer name> via VNC from <client computer
name>, for example HP Color LaserJet CP2020 via VNC from Neptune.

Manipulating the quality of the print finish

The quality of the print finish is determined by the characteristics of the local printer. For example, if the host
computer file is a color photo but the local printer only prints in black and white, then color will be lost.
You may be able to configure printer options in order to achieve a better quality print finish. You should do
this before you connect in the way expected for the operating system of the client computer, for example by
selecting Control Panel > Devices and Printers under Windows 7.
If you are already connected, then you may be able to configure some printing preferences for the
application you are printing from. This may include rotating pages, changing the page order, choosing a

62

VNC User Guide

Chapter 5: Exchanging Information

number of pages per sheet, and advanced options such as changing the resolution or paper size. For more
information, consult the applications documentation.

Troubleshooting printing
Printing host computer files to a local printer should work out-of-the-box. If it does not, check the following:
1. Are you connected to VNC Server with an Enterprise or a Personal license? You cannot print when
connected to VNC Server with a Free license. For more information, see Connecting to VNC 5.x on
page13.
2. If you are using a previous version of VNC Viewer or VNC Server, is it at least version 4.5? Printing is not
supported by earlier versions.
3. Are both client and host computers running supported operating systems? Printing is not supported to or
from certain platforms, including HP-UX, AIX, and Windows NT 4; in addition, prior configuration is
required in order to print to or from Solaris 9 and 10, SUSE Linux, and systems with SE Linux enabled.
For the latest information, visit www.realvnc.com/products/vnc/documentation/latest/misc/printing/.
4. If the host computer is running Linux or Mac OS X, is CUPS version 1.3 or later installed? For more
information, consult the host computers operating system documentation.
5. Is the local printer connected to the client computer? Is it switched on? Is it ready to print? Does it have
paper? Is it set as the client computers default printer?
6. Has VNC Viewer been configured to disable printing? To see how to enable it again, read Disabling and
enabling printing on page62. You will have to close the current connection and then reconnect.
7. Has VNC Viewer been configured to prevent the local printer becoming the host computers default,
which means it is not automatically selected? The request may have been sent to the wrong printer. To
see how to make the local printer the host computers default so it is always selected, read Disabling and
enabling printing on page62. You will have to close the current connection and then reconnect.
Note that if another VNC Viewer user connected to the same host computer before you, then their local
printer becomes the host computers default. You cannot change this. You must always explicitly select
your local printer when you print.
If you have to explicitly select your local printer, note it will have a name of the form <printer name> via
VNC from <client computer name>, for example HP Color LaserJet CP2020 via VNC from
Neptune.
8. Has VNC Server been configured to disable printing? If this is the case and you do not have access to
the host computer, you will need to consult your system administrator or a host computer user. If you do
have access to the host computer, and sufficient privileges to configure VNC Server, you may be allowed
to enable it again; see Restricting functionality for all connected users on page110.
9. Has VNC Server been configured to prevent you printing? If this is the case and you do not have access
to the host computer, you will need to consult your system administrator or a host computer user. If you
do have access to the host computer, and sufficient privileges to configure VNC Server, you may be able
to allow it again; see Restricting functionality for particular connected users on page111.

VNC User Guide

63

Chapter 5: Exchanging Information

Transfering files between client and host computers

If you are connected to VNC Server with an Enterprise or a Personal license, you can exchange files with the
host computer.
Note: If file transfer fails for any reason, see Troubleshooting file transfer on page67.

Sending files to a host computer

To send files to a host computer:
1. Click the File Transfer
computer:

VNC Viewer toolbar button. The File Transfer dialog opens on the client

2. Click the Send files button. The Send Files dialog opens.
3. Select a file or folder. To select multiple files and/or folders, hold down the SHIFT key.
Note: Under Windows, you cannot directly select a folder. Instead, double-click to open that folder, then
click Use Entire Folder. To select multiple folders, open the parent folder and click Use Entire Folder.
Note this means other files and folders in the parent folder will also be transfered.

64

VNC User Guide

Chapter 5: Exchanging Information

4. Click Open (OK under UNIX). The File Transfer dialog opens on the host computer:

The most recent file transfer operation is highlighted. You can check its status, or pause or stop the
transfer if it takes more than a few seconds.
By default, files are downloaded to the host computers desktop (Downloads folder under Mac OS X).
To change this for future file transfer operations, select an option from the Fetch files to dropdown at the
bottom of the File Transfer dialog. Note you must have write permissions for the folder you choose.
Alternatively, you can ask to be prompted each time.

VNC User Guide

65

Chapter 5: Exchanging Information

Publishing files to all connected client computers

You can fetch files from a host computer. Note that all other VNC Viewer users connected at the same time
as you will also receive the files. To do this:
1. In the VNC Viewer window, right-click the VNC Server icon
(typically shaded black) and, from the
shortcut menu, select File Transfer. More on this icon. The File Transfer dialog opens on the host
computer:

2. Click the Send files button. The Send Files dialog opens.
3. Select a file or folder. To select multiple files and/or folders, hold down the SHIFT key.
Note: Under Windows, you cannot directly select a folder. Instead, double-click to open that folder, then
click Use Entire Folder. To select multiple folders, open the parent folder and click Use Entire Folder.
Note this means other files and/or folders in the parent folder will also be transfered.

66

VNC User Guide

Chapter 5: Exchanging Information

4. Click Open (OK under UNIX). The File Transfer dialog opens on the client computer:

The most recent file transfer operation is highlighted. You can check its status, or pause or stop the
transfer if it takes more than a few seconds.
By default, files are downloaded to the client computers desktop (Downloads folder under Mac OS X).
To change this for future file transfer operations, select an option from the Fetch files to dropdown at the
bottom of the File Transfer dialog. Note you must have write permissions for the folder you choose.
Alternatively, you can ask to be prompted each time.

Disabling and enabling file transfer

You may be allowed to disable file transfer while the current connection is in progress.
To do this, open the Options dialog and, on the Inputs tab, turn off Enable file transfer. More on this
dialog. The File Transfer

VNC Viewer toolbar button is disabled.

If you were allowed to disable file transfer, you can enable it again at any time.

Troubleshooting file transfer

If file transfer does not work, check the following:
1. Are you connected to VNC Server with an Enterprise or a Personal license? You cannot transfer files to
or from VNC Server with a Free license. For more information, see Connecting to VNC 5.x on page13.
2. If you are using a previous version of VNC Viewer or VNC Server, is it at least version 4.4? File transfer
is not supported by earlier versions.
3. Has VNC Viewer been configured to disable file transfer? To see how to enable it again, read Disabling
and enabling file transfer on page67.
4. Has VNC Server been configured to disable file transfer? If this is the case and you do not have access
to the host computer, you will need to consult your system administrator or a host computer user. If you

VNC User Guide

67

Chapter 5: Exchanging Information

do have access to the host computer, and sufficient privileges to configure VNC Server, you may be
allowed to enable it again; see Restricting functionality for all connected users on page110.
5. Has VNC Server been configured to prevent you transfering files? If this is the case and you do not have
access to the host computer, you will need to consult your system administrator or a host computer user.
If you do have access to the host computer, and sufficient privileges to configure VNC Server, you may
be able to allow it again; see Restricting functionality for particular connected users on page111.

Copying and pasting text between client and host

computers
You can copy and paste text between applications running on the client and host computers.
Note: The computer you are pasting to must support the language of the copied text in order for it to be
pasted meaningfully. In addition, any formatting applied to the copied text, such as italics, will be lost.
To copy and paste text from an application on the client computer to one on the host:
1. On the client computer, copy the text in the expected way for the platform of the client computer, for
example by selecting it and pressing Ctrl-C (Cmd-C on Mac OS X). The text is copied to the Clipboard.
2. Give the VNC Viewer window focus, open the destination application on the host computer, and paste
the text in the expected way for the hosts platform, for example by pressing Ctrl-V. (To emulate Cmd-V
for a Mac OS X host computer, press Alt-V on a PC keyboard.)
You can copy and paste text from an application on the host computer to one on the client. Note that text
copied can also be pasted by all other users connected at the same time as you. To do this:
1. Within the VNC Viewer window, copy the text in the expected way for the platform of the host computer,
for example by selecting it and pressing Ctrl-C. (To emulate Cmd-C for a Mac OS X host computer,
press Alt-C on a PC keyboard.) The text is copied to the Clipboard.
2. Give the destination application on the client computer focus, and paste the text in the expected way for
the clients platform, for example by pressing Ctrl-V (Cmd-V on Mac OS X).
If copy and paste text fails for any reason, start with Troubleshooting copy and paste text on page68.

Disabling and enabling copy and paste text

You may be allowed to disable copy and paste text while the current connection is in progress.
To do this, open the Options dialog and, on the Inputs tab, turn off Share clipboard with VNC Server.
More on this dialog.
If you were allowed to disable copy and paste text, you can enable it again at any time.

Troubleshooting copy and paste text

If copy and paste text does not work, check the following:
1. Has VNC Viewer been configured to disable copy and paste text? To see how to enable it again, read
Disabling and enabling copy and paste text on page68.

68

VNC User Guide

Chapter 5: Exchanging Information

2. Has VNC Server been configured to disable copy and paste text? If this is the case and you do not have
access to the host computer, you will need to consult your system administrator or a host computer user.
If you do have access to the host computer, and sufficient privileges to configure VNC Server, you may
be allowed to enable it again; see Restricting functionality for all connected users on page110.
3. Has VNC Server been configured to prevent you copying and pasting text? If this is the case and you do
not have access to the host computer, you will need to consult your system administrator or a host
computer user. If you do have access to the host computer, and sufficient privileges to configure VNC
Server, you may be able to allow it again; see Restricting functionality for particular connected users on
page111.
4. Does the amount of text being copied and pasted exceeed 256kB? If so, the entire paste operation fails,
and the last text copied to the Clipboard is pasted instead.

Communicating securely using chat

If you are connected to VNC Server with an Enterprise or a Personal license, you can chat with other VNC
Viewer users connected to a host computer at the same time as you, and also with a host computer user if
one is present.
Note: If you cannot use chat for any reason, see Troubleshooting chat on page71.
To participate in a conversation, or start a new one, click the Start Chat Session
button. A message box appears at the bottom of the VNC Viewer window:

VNC Viewer toolbar

Enter a message and click the Send button. The message is broadcast to a Chat dialog that opens on the
host computer, visible to you and to all other connected users (including a host computer user, if present):

Note: You are identified by the user name with which you authenticated to VNC Server, or as VNC Viewer
if you did not enter a user name to connect.

VNC User Guide

69

Chapter 5: Exchanging Information

Chatting as a host computer user

A host computer user can participate in a conversation, or start a new one. To start a new conversation as a
host computer user:
1. Open the VNC Server shortcut menu. More on this menu.
2. Select Chat. The Chat dialog opens. Type text in the field at the bottom:

3. Press the ENTER key to send the message:

Note: A host computer user is identified by the text (Local) appended to the user name.

Working with chat

The message box is minimized when chat is not being used. To see it again, hover the mouse over the hot
area at the bottom of the VNC Viewer window:

Note that the Chat dialog can also be minimized. If so, you are notified when new messages appear by the
taskbar button flashing (Windows and UNIX) or a number overlaid on the dock icon (Mac OS X).
Chat messages are stored on the host computer for 90 days. To stop recording messages, select Tools >
Options in the Chat dialog, and turn off Log chat history. Alternatively, you can reduce the number of days,
or switch to storing a particular number of messages.
To clear the conversation window, delete the vncchat.xml file. Under UNIX and Mac OS X, this file is
located in the host computer users .vnc directory (you can configure the location under Windows). Under
UNIX and Mac OS X, you must first stop VNC Server, delete the file, and then restart.

70

VNC User Guide

Chapter 5: Exchanging Information

Note that when a VNC Viewer user disconnects, messages sent by that user change color in the Chat
dialog.

Disabling and enabling chat

You can disable chat while the current connection is in progress.
To do this, open the Options dialog and, on the Inputs tab, turn off Enable chat. More on this dialog. The
Start Chat Session

VNC Viewer toolbar button is disabled.

Note: Chat is only disabled for you, and not for any other connected VNC Viewer user. You can still view
messages in the Chat dialog.
You can enable chat again at any time.

Troubleshooting chat
If you cannot use chat, check the following:
1. Are you connected to VNC Server with an Enterprise or a Personal license? You cannot chat to users of
VNC Server with a Free license. For more information, see Connecting to VNC 5.x on page13.
2. If you are using a previous version of VNC Viewer or VNC Server, is it at least version 4.5? Chat is not
supported by earlier versions.
3. Is there anyone to chat with? The VNC Server dialog reveals if any VNC Viewer users are connected.
More on this dialog.

4. Has VNC Viewer been configured to disable chat? To see how to enable it again, read Disabling and
enabling chat on page71.
5. Has VNC Server been configured to disable chat? If this is the case and you do not have access to the
host computer, you will need to consult your system administrator or a host computer user. If you do
have access to the host computer, and sufficient privileges to configure VNC Server, you may be allowed
to enable it again; see Restricting functionality for all connected users on page110.
6. Has VNC Server been configured to prevent you chatting? If this is the case and you do not have access
to the host computer, you will need to consult your system administrator or a host computer user. If you
do have access to the host computer, and sufficient privileges to configure VNC Server, you may be able
to allow it again; see Restricting functionality for particular connected users on page111.

VNC User Guide

71

Chapter 5: Exchanging Information

72

VNC User Guide

6
Working With VNC Server
Once licensed, VNC Server enables connections to the host computer on which it runs out-of-the-box. You
should not need to configure it. However, you can change almost any aspect to suit your requirements and
environment if you wish.
This chapter explains how to operate VNC Server. It also explains advanced scenarios such as running
multiple instances concurrently and in different modes, configuring ports, and troubleshooting. For
comprehensive security information, see Chapter 7, Making Connections Secure on page95.
This chapter assumes you have access to the host computer and sufficient privileges to configure both it and
VNC Server. Note that if you are setting up VNC Server for unattended access, some features require a host
computer user to be present when a connection is established, and are therefore not recommended.

Contents
Licensing VNC Server

74

Starting VNC Server

75

Running multiple instances of VNC Server

78

The VNC Server user interface

82

Troubleshooting VNC Server

87

Configuring VNC Server

89

Changing ports

90

Notifying when users connect

92

Stopping VNC Server

93

VNC User Guide

73

Chapter 6: Working With VNC Server

Licensing VNC Server

VNC Server must be licensed. If it is not, users cannot connect.
For more information on the different license types available, to compare the remote control features
provided by each, and to obtain a free, paid, or trial license key, visit www.realvnc.com/products/vnc/
licensing/.

Applying a license key

You can apply a license key to VNC Server at any time.
You typically first do this when you download and install VNC Server. You may subsequently apply a key in
order to renew your support and upgrades contract, or to add a feature.
1. Open the VNC Server shortcut menu. More on this menu.
2. Choose Licensing. The Licensing dialog opens.
3. Follow the instructions. Note you may additionally be prompted to configure VNC Server; see Repairing
VNC Server on page74 for more information.
Alternatively, you can apply a license key:

At the command line using the vnclicense utility; start with www.realvnc.com/products/vnc/
documentation/latest/reference/vnclicense.html.

Remotely to Windows computers by deploying the VNC Server MSI using Group Policy; visit
www.realvnc.com/products/vnc/deployment/msi/.

Remotely to any supported computer by setting policy; visit www.realvnc.com/products/vnc/deployment/

policy/.

Centrally for UNIX computers by hosting VNC Server on a network share; see Hosting VNC on a UNIX
network share on page145.

Repairing VNC Server

When you apply a license key you may additionally be prompted to repair VNC Server. This is typically
because your license key entitles you to fewer RealVNC remote control features than VNC Server is
currently configured to use. You must harmonize VNC Server with the license key.
For example, if at the end of a trial of an Enterprise or a Personal license you choose to downgrade to a Free
license, you must turn off encryption and system authentication. If you do not, users cannot connect.
Note it is possible to run more than one instance of VNC Server on a host computer; see Running multiple
instances of VNC Server on page78. If this is the case, you must repair all running instances separately. For
example, if under UNIX you have five instances of VNC Server running, two in User Mode and three in
Virtual Mode, and you apply the new license key to a particular instance of User Mode, then you must
separately configure:

The other instance of User Mode.

All three instances of Virtual Mode.

Until you do, users will only be able to connect to these instances for a limited time.

74

VNC User Guide

Chapter 6: Working With VNC Server

Note that administrative privileges may be required to perform this operation if you are not the user starting
VNC Server.

Understanding license scope

Under Windows, a VNC Server license key is system-wide. This means that it applies across all user
accounts on the host computer. Since only two instances of VNC Server can run concurrently on a Windows
computer (one in Service Mode, and one in User Mode for the currently logged on user account), this
means that VNC Server is always licensed for all users.
Under UNIX and Mac OS X, however, there is another dimension to license scope. The license to use VNC
Server not only applies to all user accounts, but additionally limits the number of instances of VNC Server
you can start. For example, if your license entitles you to five desktops, attempting to start VNC Server for a
sixth time fails. For more information, visit www.realvnc.com/products/vnc/documentation/latest/licensingfaq/.
Note: You can quickly see how many instances of VNC Server your license permits you to start, and how
many are currently running. See page 79 for more information.
Note you can start a maximum of five instances of VNC Server on UNIX and Mac OS X computers with a
Free or a trial license. Upgrade to an Enterprise or a Personal license if flexibility is important to you.

Starting VNC Server

Depending on the platform and your license, you can start VNC Server more than once on a host computer,
perhaps in different modes. For more information about modes, which you might want to use, and why you
might want to run more than one instance of VNC Server, see Running multiple instances of VNC Server on
page78.

VNC User Guide

75

Chapter 6: Working With VNC Server

To see how to start VNC Server, follow the platform-specific instructions below. In most circumstances, a
VNC Server dialog appears:

(In this picture, VNC Server is running in Service Mode under Windows.)

The VNC Server dialog is the gateway to VNC Server and all its features. More on this dialog.
To see how to stop VNC Server, or to learn why VNC Server might stop automatically, read Stopping VNC
Server on page93.
Windows

To start VNC Server in:

Service Mode, search for or navigate to VNC Server, or run the appropriate command in this table on
page190. Administrative privileges are required.
Note: By default, VNC Server automatically starts as a service when the computer is powered on. If you
explicitly stop VNC Server, however, the service does not restart when the computer is rebooted.

User Mode, search for or navigate to VNC Server (User Mode), or run the appropriate command in this
table on page190.
Note: Microsoft User Account Control severely restricts users connected to VNC Server in User Mode
from fully controlling a host computer running Windows Vista or later.

76

VNC User Guide

Chapter 6: Working With VNC Server

UNIX

To start VNC Server in:

User Mode, search for or navigate to VNC Server (User Mode), or run the appropriate command in this
table on page190.

Service Mode, run the appropriate command for your system, for example /etc/init.d/vncserverx11-serviced start or systemctl start vncserver-x11-serviced.service. Typically, it
is useful to have this service start automatically when the computer powers on; visit www.realvnc.com/
products/vnc/documentation/latest/reference/vncserver-x11-serviced.html for more information.

Virtual Mode, run the command vncserver-virtual. Note you should not do this with elevated
privileges. No user interface is available to help you work with VNC Server in this mode; instead, a
message is printed to the console. See Working with VNC Server in Virtual Mode on page80 for more
information.
Note: If you have an Enterprise license, you can run VNC Server in Virtual Mode as a service, in which
case a new instance is started automatically, and a virtual desktop created, on demand. See Creating
virtual desktops on demand on page81 for more information.

Mac OS X

To start VNC Server in:

Service Mode, search for or navigate to VNC Server, or run the appropriate command in this table on
page191. Note elevated privileges are required.
Note: VNC Server in Service Mode automatically starts when the computer powers on.

User Mode, search for or navigate to VNC Server (User Mode), or run the appropriate command in this
table on page191.

VNC User Guide

77

Chapter 6: Working With VNC Server

Running multiple instances of VNC Server

Under any platform, and providing your license entitles you to do so, you can run more than one instance of
VNC Server on a host computer.
This powerful feature means you can set up the host computer so users can connect to it in different ways.
For example, you could set up one instance so that connections to it are optimized for speed, and another
so connections are optimized for security. VNC Server facilitates this using modes, each of which permits a
different level of access to the host computer, in different states and for different purposes.
To...
Remote the
console of the
host computer

Run VNC
Server in...

Platforms

Connected users see...

Service Mode

All

Exactly what a person sitting in front of the host computer would see.
This is either the desktop of a user account if one is currently logged
on, or the Login screen if not. Note VNC Server is typically set to start
when the system powers on, and users can connect and reconnect
until VNC Server is explicitly stopped.

All

Exactly what a person sitting in front of the host computer would see
while the current user account is logged on. When this user account is
logged off, VNC Server automatically stops, users are disconnected,
and cannot reconnect. Note the Login screen is not available to
connected users.

UNIX

A virtual desktop, created when VNC Server is started and not

destroyed until VNC Server is explicitly stopped. Connected users
therefore do not see what a person sitting in front of the host computer
would see; neither the desktop of the currently logged on user account,
nor the Login screen, are available. Instead, connected users gain a
private workspace to which they can connect and reconnect until VNC
Server is explicitly stopped. See Working with VNC Server in Virtual
Mode on page80.

User Mode
Remote the
desktop of the
currently loggedon user account
Create and
remote a virtual
desktop

Virtual Mode

With an Enterprise license, you can run VNC Server in Virtual Mode as
a service, which means virtual desktops can be created on demand.
These virtual desktops, however, do not persist. See Creating virtual
desktops on demand on page81.

VNC Server can run in Service Mode and User Mode concurrently, though this is not generally useful, and
likely to result in port conflicts. See Changing ports on page90 for more information.
Under UNIX, VNC Server is designed to run in Virtual Mode as many times as your license has available
desktops. It can safely be run concurrently with either other mode.
For platform-specific information, see the sections below. To see how to start VNC Server in different modes,
read Starting VNC Server on page75.
Windows

You can start VNC Server a maximum of twice on a host computer; once in Service Mode, and once in User
Mode for the currently logged on user account.
Note: Microsoft User Account Control severely restricts users connected to VNC Server in User Mode from
fully controlling a host computer running Windows Vista or later. The connected user loses mouse and

78

VNC User Guide

Chapter 6: Working With VNC Server

keyboard control if a program requiring administrative privileges is run (this may or may not be preceded by
a User Account Control prompt), and can only continue if a host computer user closes the program, or
accepts the prompt.
Once connected to VNC Server in either mode, a user has the same privileges (that is, access rights) on the
host computer as the currently logged on user account. This need not be a user with administrative
privileges even if the credentials of one were supplied in order to authenticate to VNC Server; see
Authenticating users on page96 for more information. The opposite also holds true: a connected user has
administrative privileges if such a user account is currently logged on.
UNIX

You can start VNC Server as many times as your license permits. Each time you do, one desktop is
decremented from your license. To see how many are left, run the command vnclicense -check. For
example:
Licensed desktops: 5
Running desktops: 3
johndoe: 2
janedoe: 1
This means that five desktops are licensed to run concurrently on the host computer, and three are already
running; two started by John Doe, and one by Jane Doe. Two are left to run.
Note: You can re-increment your license by killing desktops. To see how to do this, read Stopping VNC
Server on page93.
You can start VNC Server once in Service Mode. You can start VNC Server once in User Mode for the
currently logged on user account. And you can start VNC Server in Virtual Mode to create as many virtual
desktops as you need.
Once connected to VNC Server in:

User Mode or Service Mode, a user has the same privileges (that is, access rights) on the host computer
as the currently logged on user account. This need not be a user with administrative privileges even if
the credentials of one were supplied in order to authenticate to VNC Server; see Authenticating users on
page96 for more information. The opposite also holds true: a connected user has administrative
privileges if such a user account is currently logged on.

Virtual Mode, a user has the same privileges as the host computer user starting VNC Server,
irrespective of whether or not a user account is currently logged on.

Mac OS X

You can start VNC Server as many times as your license permits. Each time you do, one desktop is
consumed from your license. To see how many are left, run the command /Library/vnc/vnclicense check; see the UNIX section above for an explanation of the output.
You can start VNC Server once in Service Mode. You can start VNC Server once in User Mode for the
currently logged on user account. And you can start VNC Server in User Mode for other user accounts
providing Fast User Switching is turned on, and the StopUserModeOnSwitchOut VNC parameter is set to
False. See Appendix C, VNC Parameters on page153 for more information.
Once connected to VNC Server in either mode, a user has the same privileges (that is, access rights) on the
host computer as the currently logged on user account. This need not be a user with administrative

VNC User Guide

79

Chapter 6: Working With VNC Server

privileges even if the credentials of one were supplied in order to authenticate to VNC Server; see
Authenticating users on page96 for more information. The opposite also holds true: a connected user has
administrative privileges if such a user account is currently logged on.

Working with VNC Server in Virtual Mode

Note: The information in this section applies to UNIX platforms only.
When VNC Server in Virtual Mode starts, a virtual desktop is created, independent of the console and
detached from any physical display hardware. This means that desktop artifacts such as the VNC Server
icon and VNC Server dialog are not available to help you work with VNC Server. For more information, visit
www.realvnc.com/products/vnc/documentation/latest/reference/vncserver-virtual.html.

Managing the virtual desktop environment

When VNC is installed, a default system-wide /etc/vnc/xstartup file is created, specifying a window
manager and other settings for all virtual desktops created for all user accounts on that computer. This file is
reserved for use by RealVNC.
To specify a different window manager, start particular applications, or manage any other aspect of the
virtual desktop environment, create /etc/vnc/xstartup.custom and make it executable. This file will be
executed in preference to /etc/vnc/xstartup.
To specify a virtual desktop environment for a particular user account, create ~/.vnc/xstartup and make
it executable. This file will be executed in preference to a system-wide file for all virtual desktops created for
that user account only.

Connecting to VNC Server in Virtual Mode

A virtual desktop is assigned an X Window System display number corresponding to the port on which VNC
Server is listening for connection requests. When VNC Server starts, a message ending with text similar to
the following is printed to the Terminal window:
New desktop is johndoe:1 (192.168.0.187:1)

In this example, display number 1 has been automatically assigned, corresponding to port 5901. To assign a
particular display number, declare it explicitly, for example:
vncserver-virtual :2

Configuring VNC Server in Virtual Mode

You can:

Specify VNC parameters in appropriate VNC configuration files, or at the command line when you start
VNC Server. See Specifying VNC parameters on page130 for more information.

Configure VNC Server as a connected user. To do this, start VNC Viewer and supply the network
address and display number (see the example output above). Once connected, (virtual) desktop artifacts
are available to help you work with VNC Server. See The VNC Server user interface on page82 for more
information.

80

VNC User Guide

Chapter 6: Working With VNC Server

Creating virtual desktops on demand

If you have an Enterprise license, you can run VNC Server in Virtual Mode as a service, to create virtual
desktops on demand. Note this service listens on port 5999 by default. For more information, visit
www.realvnc.com/products/vnc/documentation/latest/reference/vncserver-virtuald.html.
For example, if you run the service on a computer acmecorp and a connecting user successfully
authenticates using the credentials of the user account John Doe, then:
1. An instance of VNC Server in Virtual Mode is automatically started, and an acmecorp:1 virtual desktop
is created.
2. The newly-connected user is transferred to, and can immediately control, acmecorp:1.
3. One desktop is decremented from your license.
4. acmecorp:1 is destroyed (and your license re-incremented) when the user disconnects; a session does
not persist.
If a second user authenticates by supplying the credentials of John Doe, an acmecorp:2 virtual desktop is
created, and a second desktop is decremented from your license.
To start the service, run the appropriate command for your system, for example /etc/init.d/
vncserver-virtuald start or systemctl start vncserver-virtuald.service. Typically, it is
useful to have it start automatically when the computer powers on.
Note that no desktop artifacts are available to help you work with the service once it has started. To
configure it, specify VNC parameters in appropriate VNC configuration files; see Specifying VNC
parameters on page130 for more information. In particular, note the credentials of any user account valid to
log on to the host computer can be used to authenticate out-of-the-box. To restrict which users can connect,
specify the Permissions VNC parameter.

Keeping VNC Server up-to-date

VNC Server can automatically check for:

Critical security patches.

Product updates to which you are entitled, if you have an Enterprise or a Personal license and a valid
support and upgrades contract; see Contacting Technical Support on page8.

If any appropriate downloads are detected, you are directed to visit the RealVNC web site.
Note: This is a secure web service and no personally identifiable information is collected or stored.
The first time you start VNC Server, you are asked whether you would like an automatic check to occur daily.
You can subsequently edit your choice on the Updates page of the VNC Server Options dialog. More on
this dialog.
To alter the frequency of the update check, specify the UpdateCheckFrequencyDays VNC Server
parameter.
In addition, or alternatively, users can perform a manual check by selecting Check for updates on the VNC
Server shortcut menu. More on this menu.

VNC User Guide

81

Chapter 6: Working With VNC Server

The VNC Server user interface

This section explains key desktop artifacts enabling you to work with VNC Server:

The VNC Server icon on page82

The VNC Server shortcut menu on page83

The VNC Server dialog on page84

Other desktop artifacts are explained in subsequent sections in this chapter.

Note: Under UNIX, for VNC Server in Virtual Mode, desktop artifacts are only available to a connected user.
For more information, see Working with VNC Server in Virtual Mode on page80.

The VNC Server icon

While VNC Server is running, an icon

is displayed:

Under Windows, in the Notification area. Under Windows 7, this is hidden by default and accessible only
from

to the right of the Taskbar:

Under Windows XP, the icon may be hidden by other icons. Under Windows 8, the icon is not available
on the Start screen, only the Desktop application.

Under UNIX, in the Notification Area:

Note: Some versions of UNIX are not able to display a VNC Server icon.

Under Mac OS X, on the Status Bar:

The VNC Server icon:

Provides visual confirmation that VNC Server is running. If the icon is not available, then typically VNC
Server is not running.

Provides visual confirmation that VNC Server is configured correctly. If not, a red error glyph
Open the VNC Server dialog to begin diagnosing the problem. More on this dialog.

Confirms whether users are connected or not. When the first user connects, the icon is shaded black
When the last user disconnects, the icon reverts color again.

82

VNC User Guide

appears.

Chapter 6: Working With VNC Server

Provides convenient notification of the mode. Hover the mouse cursor over the icon:

Has a shortcut menu that performs useful operations. More on this menu.

The VNC Server shortcut menu

VNC Server has a shortcut menu to facilitate common operations. To show it, right-click (click under Mac OS
X) the VNC Server icon. More on this icon.

(Note that menu options are disabled if they are not available.)

Note: The shortcut menu is also available from the More button on the VNC Server dialog. More on this
dialog.
The following table explains the purpose of each shortcut menu option.
Option

Purpose

Open

Work with VNC Server. See The VNC Server dialog on page84.

Information Center

Understand and resolve issues affecting VNC Server, and retrieve system diagnostics.
See Troubleshooting VNC Server on page87.

Options

Configure VNC Server. Note administrative privileges are required for VNC Server in
Service Mode. See Troubleshooting VNC Server on page87.

Connections

Identify connected users. See Identifying connected users on page86.

About

See version and trademark information, and a list of open source dependencies.

Connect to Listening VNC

Viewer

Establish a reverse connection in conjunction with a client computer user. See

Establishing a reverse connection on page102.

VNC User Guide

83

Chapter 6: Working With VNC Server

Option

Purpose

Disconnect VNC Viewers

Disconnect all users. Note that, by default, users can immediately reconnect.

Guest Access

When turned on, and providing VNC Server is configured correctly, a Guest is allowed
to connect, bypassing VNC Servers authentication scheme. See Allowing a Guest to
connect on page103.
Not available for VNC Server with a Free license.

Chat

Chat with all connected users. See Communicating securely using chat on page69.
Not available for VNC Server with a Free license.

File Transfer

Send files to all connected users. See Transfering files between client and host
computers on page64.
Not available for VNC Server with a Free license.

Licensing

Apply a license key to VNC Server. See Licensing VNC Server on page74.

Check for updates

Check for crtical security patches and product updates. See Keeping VNC Server upto-date on page81.

Stop VNC Server

Stop VNC Server, disconnecting all users. Note administrative privileges are required
for VNC Server in Service Mode. See also Stopping VNC Server on page93.

The VNC Server dialog

The VNC Server dialog is the gateway to VNC Server, and the first port of call for connection information
and troubleshooting:

84

VNC User Guide

Chapter 6: Working With VNC Server

To open the VNC Server dialog, click its taskbar entry in the normal way for a program, or select Open from
the VNC Server shortcut menu. More on this menu.
The VNC Server dialog:

Confirms the license type and mode. See Confirming key information on page85.

Reveals whether VNC Server is ready to accept connections. See Troubleshooting VNC Server on
page87.

Provides information to help users connect. Start with Getting users connected on page85.

Displays the VNC Server catchphrase and signature. See Uniquely identifying VNC Server on page86.

Identifies any connected users. See Identifying connected users on page86.

Shows expiry dates for trials or support contracts. See Showing expiry dates on page87.

Note: The VNC Server dialog also has a More button providing access to the same features as the VNC
Server shortcut menu. More on this menu.

Confirming key information

The status bar confirms the license type and mode:

You can apply a license key at any time. See Licensing VNC Server on page74 for more information.
For more information on modes, start with Running multiple instances of VNC Server on page78.

Getting users connected

The Get Started section contains key information intended to get prospective users quickly connected to
VNC Server over a private network (for equivalent information for Internet connections, see Connecting over
the Internet on page28.) You can select this text and right-click to copy and paste into an email or similar:

In this picture, VNC Server is running on a host computer with a private network address of 192.168.5.54. In
addition:

VNC Server is listening for connections on port 5980. The port number is separated from the network
address by a single colon, which means it represents a port in the range 5901 to 5999. Note that:
If the port number is separated from the network address by two colons, it represents a port outside
the range 5900 to 5999, so for example 192.168.5.54::80 means VNC Server is listening on port 80.
If no port number is displayed, VNC Server is listening on the default port for VNC, 5900.

VNC Server with an Enterprise or a Personal license is serving VNC Viewer for Java on port 5880.

VNC User Guide

85

Chapter 6: Working With VNC Server

For more information on ports, start with Changing ports on page90.

Listing all connectivity information

The Connectivity section lists all network addresses and other means of connecting to VNC Server over a
private network (for equivalent information for Internet connections, see Connecting over the Internet on
page28):

In this picture:

Two IPv4 network addresses are available.

Two IPv6 network addresses are available. Note these are only valid in an IPv6-enabled environment.

The Bonjour or Avahi name is displayed. Note only Zeroconf-enabled applications such as VNC Viewer
for Android or VNC Viewer for iOS are able to discover VNC Server; VNC Viewer is not Zeroconfenabled in this release. Note this feature is also not available with a Free license.

Uniquely identifying VNC Server

For VNC Server with an Enterprise or a Personal license, the Get Started section displays a catchphrase
(and the less-memorable signature on which it is based) uniquely identifying VNC Server:

When a user connects to VNC Server for the first time, they are asked to verify its identity. For more
information on this security feature, see Verifying the identity of VNC Server on page114.

Identifying connected users

The connection bar confirms the number of currently connected users (this bar is only shown if users are
actually connected):

86

VNC User Guide

Chapter 6: Working With VNC Server

Click the Details button to identify and manage connected users. The Connections tab of the Information
Center dialog opens:

In this example, the user of client computer 192.168.0.187:

Authenticated to VNC Server by supplying the credentials of the John Doe user account. For more
information on system authentication, start with Authenticating using system credentials on page96.

Has an administrative set of VNC permissions, permitting unrestricted access to remote control features
while the connection is in progress. For more information, see Restricting functionality for particular
connected users on page111.

Click the Disconnect button to disconnect a selected user.

Showing expiry dates

The Details section reveals expiry dates for VNC Server with an Enterprise or a Personal license:

If you are trialling VNC Server, you are informed when your trial expires.

If you have purchased VNC Server, you are informed when your support and upgrades contract expires.

Troubleshooting VNC Server

The VNC Server dialog has a colored bar indicating status. More on this dialog.
The status bar is green if VNC Server is configured correctly:

Note there may be messages to read:

A message indicates that, while VNC Server is configured correctly, some minor aspect could be improved.

VNC User Guide

87

Chapter 6: Working With VNC Server

The status bar turns amber if there are warnings:

A warning does not prevent users connecting, but indicates that some important aspect of VNC Server, such
as performance or security, could be improved.
The status bar turns red if there are errors:

An error must be fixed before users can connect.

Click the Show button to open the Information Center dialog:

You can:

Repair VNC Server. On the Issues tab, follow the instructions for each issue.

List all license keys applied to VNC Server, and the features provided by each, on the Licenses tab.

Send system diagnostics to Technical Support. On the Diagnostics tab, click the Save As button.

88

VNC User Guide

Chapter 6: Working With VNC Server

Find out the address of a router protecting the host computer in preparation for Internet connections. On
the Diagnostics tab, click the Test Internet Connection button. See Connecting over the Internet on
page28 for more information.

Note: The Information Center dialog is also available from the VNC Server shortcut menu. More on this
menu.

Configuring VNC Server

You can configure VNC Server once it has started using the Options dialog:

Note: To see how to configure VNC Server before it starts, or lock down the application to prevent changes,
start with Configuring VNC on page130.
To open the Options dialog, select Options from the VNC Server shortcut menu. More on this menu. Note
that for VNC Server in Service Mode, elevated privileges are required.
For information on some of the options in this dialog, see the subsequent sections in this chapter, starting
with Changing ports on page90. For security-related information, see Chapter 7, Making Connections
Secure on page95. For the Expert page, see .

VNC User Guide

89

Chapter 6: Working With VNC Server

Note that configuring an option affects all future connections. Unless otherwise stated in the sections that
follow, configuring an option affects currently connected users as well.

Changing ports
By default, VNC Server listens for VNC connection requests on a particular port. In addition, VNC Server
with an Enterprise or a Personal license listens for VNC Viewer for Java download requests on a different
port. You can change these ports, or make them the same.
Note: VNC Viewer for Java cannot be downloaded from VNC Server with a Free license. Upgrade to an
Enterprise or a Personal license if flexibility is important to you.
By default, two separate ports are assigned when VNC Server starts, one for VNC connections and one for
VNC Viewer for Java downloads:

VNC Server in both Service Mode and User Mode is assigned port 5900 for connections and port 5800
for downloads.

Under UNIX, the first instance of VNC Server in Virtual Mode is assigned port 5901 for connections and
port 5801 for downloads. Subsequent instances of VNC Server in Virtual Mode are assigned port
numbers incremented by one, where possible, for example 5902, 5903 (and 5802, 5803) and so on, up
to the maximum number of desktops permitted by the host computers license.

Note: For more information about running multiple instances of VNC Server, and the different modes, see
Running multiple instances of VNC Server on page78.
If more than one instance of VNC Server is running on a host computer, they must all listen on different
ports; see below for information on resolving port conflicts. Note, however, that a particular instance of VNC
Server can listen on the same port for VNC connections and for VNC Viewer for Java download requests;
see Making the connection and download port the same on page91 for more information.
Note: When connecting to VNC Server, a user must qualify the host computers network address with the
port number in all cases except when VNC Server is listening for VNC connections on port 5900 only. For
more information, see Qualifying a network address with a port number on page30.

Resolving port conflicts

VNC Server must listen for VNC connections and VNC Viewer for Java download requests on a unique port.
This is one on which no other instance of VNC Server, nor any other program or service, is listening.
Port conflicts disable VNC Server. You should be able to resolve them by changing ports on the
Connections page of the Options dialog. More on this dialog.

90

VNC User Guide

Chapter 6: Working With VNC Server

Changing the connection port

You can change the port on which VNC Server is listening for VNC connections. If you do this:

Users need to know the new port number (if it is not 5900) in order to connect. For more information, see
Qualifying a network address with a port number on page30.

If the host computer is protected by a firewall, then the firewall must be configured to allow incoming
network communications to the new port. For more information, see Allowing network communications
through a firewall on page31.

If the host computer is protected by a router and users are connecting over the Internet, then the router
must be configured to forward communications to the new port. For more information, see Configuring a
router to forward network communications on page29.

To change the port, enter a different number in the Port field opposite Allow VNC connections. Note that
changing this option does not affect currently connected users.

Changing the download port

You can change the port on which VNC Server is listening for VNC Viewer for Java download rquests. If you
do this:

Web browser users need to know the new port number in order to download. For more information, see
Qualifying a network address with a port number on page30.

If the host computer is protected by a firewall, then the firewall must be configured to allow incoming
network communications to the new port. For more information, see Allowing network communications
through a firewall on page31.

If the host computer is protected by a router and web browser users will connect over the Internet, then
the router must be configured to forward communications to the new port. For more information, see
Configuring a router to forward network communications on page29.

To change the port, enter a different number in the Port field opposite Serve VNC Viewer for Java. Note
that changing these options does not affect currently connected users.

Making the connection and download port the same

VNC Server can listen on the same port for connection and download requests. This may simplify firewall
configuration and make the host computer more secure.
To use the same port, enter the same number in both Port fields. Note that changing these options does not
affect currently connected users.

VNC User Guide

91

Chapter 6: Working With VNC Server

Notifying when users connect

By default, VNC Server displays a notification message in the bottom right corner of the host computers
desktop (top right under Mac OS X) each time a user connects:

Note: A similar message appears on disconnection.

You can disable notification messages by turning off Notify when users connect and disconnect on the
Privacy page of the Options dialog. More on this dialog.

Note: You can replace notifications with connection prompts that enable a host computer (or an alreadyconnected user) to accept or reject new users. For more information, see Preventing particular users
connecting on page108.

92

VNC User Guide

Chapter 6: Working With VNC Server

Stopping VNC Server

VNC Server runs until it is stopped.
To explicitly stop VNC Server in:

All modes and under all platforms except those below, select Stop VNC Server from the VNC Server
shortcut menu. More on this menu. Administrative privileges may be required.
Note: Under Windows, VNC Server in Service Mode will not automatically restart if you do this and then
reboot the host computer.

Service Mode under UNIX, run the appropriate command for your system, for example /etc/init.d/
vncserver-x11-serviced stop or systemctl stop vncserver-x11-serviced.service.
For more information, or to see how to prevent VNC Server starting again when the computer is
rebooted, visit www.realvnc.com/products/vnc/documentation/latest/reference/vncserver-x11serviced.html.

Virtual Mode under UNIX, run the command vncserver-virtual -kill :x, where x is the X
Window System display number. For more information, see Connecting to VNC Server in Virtual Mode
on page80.

Note that VNC Server automatically stops in:

All modes and under all platforms, when the host computer is powered down.

User Mode under all platforms, when the user account in which it was started is logged off.

VNC Server can also stop under the following circumstances:

Under Windows, VNC Server in User Mode stops automatically when the last user disconnects if the
When last user disconnects option is changed to Log the current user account off. For
more information, see Protecting privacy on page115.

A connected user can explicitly stop VNC Server in User or Virtual Mode.

A connected user can explicitly stop VNC Server in Service Mode if they have administrative privileges.

A connected user can log off and/or power down the host computer.

To see how to start VNC Server again, read Starting VNC Server on page75.

VNC User Guide

93

Chapter 6: Working With VNC Server

94

VNC User Guide

7
Making Connections Secure
VNC Server with an Enterprise or a Personal license authenticates connecting users and encrypts
connections end-to-end out-of-the-box. This chapter explains how to configure VNC Server to relax the
authentication and encryption rules if you consider it safe to do so. Conversely, you can tighten the
encryption rules for VNC Server with an Enterprise license, if necessary.
Note: VNC Server with a Free license can authenticate users but not encrypt connections. Upgrade to an
Enterprise or a Personal license if security is important to you.
This chapter also explains how to protect the host computer from accidental or malicious damage by users,
either by restricting their access to remote control features while connections are in progress, or by
preventing them connecting in the first place.

Contents
Authenticating users

96

Authenticating using system credentials

96

Authenticating using a password specific to VNC

98

Relaxing the authentication rules

99

Bypassing the authentication rules

101

Changing the encryption rules

104

Preventing connections to VNC Server

105

Restricting functionality for connected users

109

Verifying the identity of VNC Server

114

Protecting privacy

115

VNC User Guide

95

Chapter 7: Making Connections Secure

Authenticating users
By default, all connecting users must authenticate to VNC Server. Note this is not the same as logging on to
a user account on the host computer, though the same credentials may be used for both operations.
By default, VNC Server with:

An Enterprise or a Personal license is set to use the system authentication scheme. This means that
connecting users can supply the same credentials they use to log on to the host computer in order to
authenticate to VNC Server. Note that user accounts must be registered with VNC Server. See
Authenticating using system credentials on page96.

A Free license is set to use the VNC authentication scheme. This means that connecting users must
supply a password specific to VNC. See Authenticating using a password specific to VNC on page98.

If you consider it safe to do so, you can:

Relax the authentication rules for all connecting users. See Relaxing the authentication rules on
page99.

Allow particular users to bypass authentication. See Bypassing the authentication rules on page101.

Authenticating using system credentials

By default, VNC Server with an Enterprise or a Personal license is set to use the system authentication
scheme, which means that VNC Server is integrated into the credentialing mechanism of the system
(whether local, domain, or cloud). This scheme is typically both secure and convenient; system
administrators commonly force the adoption of complex user names and passwords in enterprise
environments, and users with their own accounts can authenticate using already-familiar credentials.
Note: VNC Server with a Free license does not support system authentication. Upgrade to an Enterprise or
a Personal license if security is important to you.
To authenticate to VNC Server, a connecting user can supply the credentials:

Under any platform, of a local user account (that is, one set up directly on the host computer).

Under Windows and Mac OS X, providing the host computer is joined to a domain, of a domain user
account (one that is managed by a network service such as Active Directory). Note that prior
configuration is required to use domain accounts under UNIX; see Managing system authentication on
page141 for more information.

Under Windows 8, providing the host computer is connected to the Internet, of a cloud user account (that
is, a Microsoft account, in which the email address constitutes the user name).

Certain user accounts and groups are pre-registered with VNC Server, to enable basic connectivity out-ofthe-box. See Managing the list of registered user accounts and groups on page97 for more information.
Note: Under Windows, it is possible to create a local user account for a computer that does not have a
password set (this is likely for friends and family only). However, a connecting user cannot leave the VNC
Viewer Password field empty. Either change the authentication scheme, or specify a password for the local
user account (recommended).

96

VNC User Guide

Chapter 7: Making Connections Secure

Note that under any platform, the credentials supplied by a user in order to authenticate to VNC Server
determine the VNC permissions granted to that user. VNC permissions control the availability of remote
control features such as file transfer and chat while their connection is in progress. By default, an
administrative set of VNC permissions is granted. For more information on what this means, and to see how
to revoke VNC permissions in order to disable remote control features, see Restricting functionality for
particular connected users on page111.
Under each platform, system authentication is managed by an appropriately-named option in the Security >
Authentication dropdown of the Options dialog. More on this dialog.

Note: This option is called UNIX password and Mac password under their respective platforms.

Managing the list of registered user accounts and groups

User accounts must be registered with VNC Server in order that connecting users may authenticate using
familiar, securely-managed system credentials. To see which user accounts and groups are currently
registered, ensure system authentication is selected in the Security > Authentication dropdown of the
Options dialog, and open the Users & Permissions page:

(VNC Server in Service Mode under Windows)

In this example, the built-in Windows Administrators group is registered, which means that any user in
this group can authenticate to VNC Server. Note this group typically includes Domain Admins if the host
computer is joined to a domain.

VNC User Guide

97

Chapter 7: Making Connections Secure

Note: Guest access is disabled by default. See Allowing a Guest to connect on page103 for more
information.
The following table lists the pre-registered user accounts and groups for all platforms and modes, to enable
connectivity out-of-the-box:
Mode

Windows

Mac OS X

Service

Administrators group

admin group

UNIX

root user account

admin group

User

User account starting VNC Server User account starting VNC Server User account starting VNC Server

Virtual

User account starting VNC Server

To add a new user account or group, click the Add button, and follow the instructions. Note if you remove all
user accounts and groups from the list, connections cannot be established.

Authenticating using a password specific to VNC

By default, VNC Server with a Free license is set to use the VNC authentication scheme, which means that
VNC Server has its own password, disassociated from the credentialing mechanism of the system. Note this
scheme is only as secure as the complexity of the password chosen.
Note: You can specify VNC authentication for VNC Server with an Enterprise or a Personal license if you
wish.
VNC authentication is managed by the VNC password option in the Security > Authentication dropdown
of the Options dialog. More on this dialog.

To specify a new or to change an existing password, open the Users & Permissions page, select the
Standard user, and click the Password button. Note that connecting users must supply this password in
order to authenticate to VNC Server, but need not provide a user name.

Specifying additional users

If you choose the VNC authentication scheme for VNC Server with an Enterprise or a Personal license, you
can specify up to two additional users, enabling you to distinguish between view-only, normal, and
administrative connections.

98

VNC User Guide

Chapter 7: Making Connections Secure

Note: VNC Server with a Free license does not support additional users. Upgrade to an Enterprise or a
Personal license if flexibility is important to you.
To do this, make sure VNC password is selected in the Security > Authentication dropdown, and open
the Users & Permissions page:

Note: Guest access is disabled by default. See Allowing a Guest to connect on page103 for more
information.
Click the Add button, and follow the instructions to create:

An administrative user. Connecting users must supply the user name Admin and the password you
specify in order to authenticate to VNC Server. These users can bypass connection prompts and, once
connected, can use all available remote control features. For more information on connection prompts,
see Preventing particular users connecting on page108.

A view-only user. Connecting users must supply the user name ViewOnly and the password you
specify in order to authenticate to VNC Server. Once connected, users can observe but not interact.

Relaxing the authentication rules

By default, the most secure authentication scheme available for your license is chosen for VNC Server. See
Authenticating users on page96 for more information.
The following table explains ways in which you can relax the authentication rules for all prospective users if
you consider it safe to do so.
VNC Server
Enterprise

Personal

Free

Authenticate users without interaction. See Authenticating

users automatically on page100.

YES

Require connecting users to supply just a password. See

Authenticating using a password specific to VNC on
page98.

YES

YES

(default)

Disable authentication. See Turning authentication off on

page101.

YES

YES

YES

VNC User Guide

99

Chapter 7: Making Connections Secure

Authenticating users automatically

For VNC Server with an Enterprise license, you can specify the single sign-on (SSO) authentication
scheme. This means that system credentials already entered by connecting users in order to log on to some
other system service (perhaps their client computers) are automatically used to authenticate to VNC Server.
Note this is only possible in a managed network environment; see Setting up single sign-on authentication
on page143 for more information.
Note: Single sign-on authentication is not available for VNC Server with a Personal or a Free license.
Upgrade to an Enterprise license if flexibility is important to you.
To do this, choose the Single sign-on option from the Security > Authentication dropdown of the
Options dialog. More on this dialog.

Note that the domain accounts of all prospective users must be registered with VNC Server on the Users &
Permissions page:

See Managing the list of registered user accounts and groups on page97 for more information. Note that
VNC permissions are granted to each connected user in the same way as for system authentication.

100

VNC User Guide

Chapter 7: Making Connections Secure

Turning authentication off

You can turn authentication off if you are sure all prospective users are trustworthy.
Note: Alternatively, you can allow just particular users to bypass authentication. See Bypassing the
authentication rules on page101 for more information.
To do this, choose the None option in the Security > Authentication dropdown of the Options dialog. More
on this dialog.

Bypassing the authentication rules

You can allow just particular users to bypass the authentication scheme, keeping VNC Server passwordprotected.
Note: You can turn authentication off for all users if you consider it safe to do so. See Turning authentication
off on page101.
You can:

Establish a reverse connection to a particular client computer. See Establishing a reverse connection on
page102.

If VNC Server has an Enterprise or a Personal license, allow a particular user to connect as a Guest.
See Allowing a Guest to connect on page103.

Clearly, you should only establish reverse connections to client computers with trustworthy prospective
users, and only allow trustworthy users to connect as Guests.
Note: If you are setting up VNC Server for unattended access, note that a host computer user must be
present for either of these features to work.

VNC User Guide

101

Chapter 7: Making Connections Secure

Establishing a reverse connection

You may be able to establish a reverse connection to a particular client computer, allowing the user of that
computer to bypass the authentication scheme.
Note: The client computer must be running Listening VNC Viewer. For more information, see Starting
Listening VNC Viewer on page36.
Note this feature is also useful if the host computer is protected by a firewall that cannot be configured to
allow, or by a router that cannot be configured to forward, network communications, thus preventing
incoming connections. In a reverse connection, network communications from the host computer are
outgoing.
To establish a reverse connection from the user interface (see these tables on page190 for command line
instructions):
1. Open the VNC Server shortcut menu. More on this menu.
2. Select Connect to Listening VNC Viewer:

3. If you are connecting:

Within a private network, enter the network address of the client computer itself. If you do not know
what this is, ask a client computer user to run a command such as ipconfig (Windows) or
ifconfig (Linux and Mac OS X).
Over the Internet, enter the network address of a router protecting the client computer. If you do not
know what this is, you can ask a client computer user to visit www.whatismyip.com.
For more information on private and public networks, start with Connecting within a private network on
page28.
Listening VNC Viewer listens for reverse connections on port 5500. If a reverse connection fails, it may be
because the client computer is protected by a router and/or a firewall and these have not been configured to
allow access to Listening VNC Viewer on port 5500. For more information on this, and connection issues in
general, see Troubleshooting connection on page26.
When a reverse connection is established, the desktop of the host computer is displayed on the client
computer in exactly the same way as it is for VNC Viewer. A Listening VNC Viewer user can control the host
computer exactly as a VNC Viewer user does. For more information, start with Chapter 3, Using VNC
Viewer on page35.

102

VNC User Guide

Chapter 7: Making Connections Secure

Allowing a Guest to connect

If VNC Server has an Enterprise or a Personal license, you can allow a particular user to connect as a
Guest, bypassing the authentication scheme. A Guest typically connects infrequently, or for a short period of
time.
Note: This feature is not available for VNC Server with a Free license. Upgrade to an Enterprise or a
Personal license if flexibility is important to you.
To enable Guest access:
1. On the Users & Permissions page of the Options dialog, select VNC guest user. More on this
dialog.

2. In the Permissions area, change No access to:

View-only permissions to allow connected Guests to observe but not interact.
Normal permissions to allow connected Guests to use all remote contol features.
Administrative permissions to allow connecting Guests to bypass connection prompts, and
then use all remote control features.
Custom permissions to customize access; see page 112 for more information.
3. On the VNC Server shortcut menu, turn on Guest Access. More on this menu. A tick appears:

Note: If the Guest Access menu option is turned off, guests cannot connect. Note that other connected
users can turn this menu option on and off.

VNC User Guide

103

Chapter 7: Making Connections Secure

Connecting users must supply the user name Guest. There is no need to supply a password.
Unless you grant Administrative permissions to Guests, each is subject to a connection prompt,
giving the host computer (or an already-connected) user the ability to accept or reject the connection, or
make it view-only:

By default, if no response is received within ten seconds, the connection is automatically rejected. For more
information on connection prompts, see Preventing particular users connecting on page108.

Changing the encryption rules

By default, connections to VNC Server with an Enterprise or a Personal license are encrypted end-to-end
using 128-bit AES technology.
Note: Connections to VNC Server with a Free license cannot be encrypted. Upgrade to an Enterprise or a
Personal license if security is important to you.
For VNC Server with an Enterprise license, you can:

Relax the encryption rules if you are sure all potential client computers are within a secure network
environment, and that eavesdropping is impossible. This may improve performance. It may also allow
older versions of VNC Viewer, or VNC-compatible Viewer technology, that do not support encryption to
connect.
Note: Even if encryption is turned off, a password supplied by a connecting user in order to authenticate
to VNC Server is always encrypted.

Tighten the encryption rules by increasing the AES key size to 256-bit. This makes connections ultrasecure, but may impact performance slightly. It also means only VNC Viewer 4.6 or later can connect.

For VNC Server with a Personal license, you can only relax the encryption rules; 256-bit AES encryption is
not available. Upgrade to an Enterprise license if maximum security is important to you.

104

VNC User Guide

Chapter 7: Making Connections Secure

To change the encryption rules, select an alternative to the default Always on option from the Security >
Encryption dropdown of the Options dialog. More on this dialog.

Choose:

Always maximum to specify 256-bit AES. Note that only VNC Viewer 4.6 or later can connect. A
connecting user cannot request that encryption be turned off, or the AES key size be reduced to 128-bit.

Prefer on to prefer, though not mandate, that connections be encrypted using 128-bit AES. A
connecting user can request either that encryption be turned off (by selecting Prefer off in the VNC
Viewer dialog), or the AES key size be increased to 256-bit (by selecting Always maximum in the VNC
Viewer dialog).

Prefer off to prefer, though not mandate, that connections be unencrypted. Choose this option to
allow older versions of VNC Viewer, or VNC-compatible Viewer technology, to connect. A connecting
user can request that encryption be turned back on, either to 128-bit AES (by selecting Prefer on or
Always on in the VNC Viewer dialog), or to 256-bit AES (by selecting Always maximum in the VNC
Viewer dialog).

For more information about requesting encryption in the VNC Viewer dialog, see Step 4: Request an
encrypted connection on page22.

Preventing connections to VNC Server

By default, as soon as VNC Server starts:

Users can connect to VNC Server.

If VNC Server has an Enterprise or a Personal license, web browser users can download VNC Viewer for
Java and use it to connect.

You can:

Prevent all incoming connections (reverse connections can still be established). See Preventing all
incoming connections on page106.

Prevent connections from particular client computers. See Preventing connections from particular client
computers on page106.

Prevent particular users connecting. See Preventing particular users connecting on page108.

VNC User Guide

105

Chapter 7: Making Connections Secure

Preventing all incoming connections

You can prevent all incoming connections on the Connections page of the Options dialog. More on this
dialog.

To:

Prevent all incoming connections, including VNC Viewer for Java downloads, turn off Allow VNC
connections over TCP.

Prevent just VNC Viewer for Java downloads, turn off Serve VNC Viewer for Java.

Note that:

Currently connected users are not affected.

You can still use VNC Server to establish reverse connections to client computers. See Establishing a
reverse connection on page102 for more information.

Preventing connections from particular client computers

You can prevent all connections originating from particular client computers by filtering the network
addresses of those client computers.
Note: If you filter computers, users can no longer supply IPv6 network addresses in order to connect to VNC
Server (even from authorized client computers). This is a known restriction.

106

VNC User Guide

Chapter 7: Making Connections Secure

By default, connections are accepted from all client computers. To filter one or more computers:
1. Open the Connections page of the Options dialog. More on this dialog.

2. Click the Add rule button:

3. Specify a IPv4 network address, or range of addresses, and then choose one of the following options:
To:

Choose:

Accept connections from matching client computer(s).

Accept the connection

Reject connections from matching client computer(s).

Reject the connection

VNC User Guide

107

Chapter 7: Making Connections Secure

To:

Choose:

Subject connections from matching client computer(s) to connection

prompts, giving the host computer (or an already-connected) user the
ability to accept or reject each connection, or make it view-only.

Ask the VNC Server user what

to do

For more information on connection prompts, see Preventing particular

users connecting on page108.

Note that if you create multiple filter rules, their order in the list on the Connections page is important. The
first matching rule determines what happens to a particular client computer. For example, if a rule rejecting a
client computer is encountered before one accepting it, then all connections from that client computer will be
rejected. You can move rules up and down in the list using the arrows.
By default, the Default rule accepts connections from all client computers. You can change this so that it
rejects or queries all connections instead. To do this, select the Default rule, and click the Edit rule button.
Note this rule is always last in the list.

Preventing particular users connecting

You can prevent a particular user connecting by causing connection prompts to appear on the host
computers desktop:

A connection prompts enables a host computer (or an already-connected) user to identify a connecting user
and either accept or reject their connection, or make it view-only. By default, if no response is received within
ten seconds, the connection is automatically rejected. Note if you are setting up VNC Server for unattended
access then enabling this feature may prevent users connecting.
Note: In some circumstances, certain users are able to bypass connection prompts. To see how to subject
these users to prompts, read Restricting functionality for particular connected users on page111.

108

VNC User Guide

Chapter 7: Making Connections Secure

To show connection prompts, turn on Show accept/reject prompt for each connection on the
Connections page of the Options dialog. More on this dialog.

Note: This option has a slightly different name under VNC Server in Virtual Mode.

Restricting functionality for connected users

By default, any number of users can connect to VNC Server, and immediately:

Control the host computer using their keyboard.

Control the host computer using their mouse.

Copy and paste text between applications running on the host and their client computer.

If VNC Server has an Enterprise or a Personal license, connected users can also:

Chat with other users connected to the same host computer, or with a host computer user.

Transfer files in either direction.

Print to a local printer (that is, one connected to the client computer).

You can:

Restrict functionality for all connected users. See Restricting functionality for all connected users on
page110.

For VNC Server with an Enterprise or a Personal license, restrict functionality for particular connected
users. See Restricting functionality for particular connected users on page111.

VNC User Guide

109

Chapter 7: Making Connections Secure

Restricting functionality for all connected users

You can restrict access to remote control features for all connected users, if necessary, by disabling features.
To do this, open the Users & Permissions page of the Options dialog. More on this dialog. Select Global
permissions, and turn off individual features:

(VNC Server with an Enterprise or a Personal license. A Free license has fewer features.)

110

VNC User Guide

Chapter 7: Making Connections Secure

Restricting functionality for particular connected users

If VNC Server has an Enterprise or a Personal license, and the authentication scheme is either:

System authentication; see Authenticating using system credentials on page96

Single sign-on; see Authenticating users automatically on page100 (Enterprise licenses only)

then a configurable set of VNC permissions is granted to each user account registered with VNC Server, or
to all the user accounts in a registered group.
Note: Configurable permissions are not available for the VNC authentication scheme. Choose a different
scheme, or upgrade from VNC Server with a Free license.
To see the list of registered user accounts and groups, open the Users & Permissions page of the Options
dialog. More on this dialog.

In this example, the built-in Windows Administrators group grants an administrative set of permissions
to all users in the group. For more information, and to see which user accounts and groups are preregistered with VNC Server, read Managing the list of registered user accounts and groups on page97.
To change the permissions granted by a particular user account or group, select it in the list and, from the
Permissions dropdown, choose either:

View-only permissions to allow connected users to observe but not interact.

Normal permissions to grant connected users access to all remote contol features.

Administrative permissions to allow connecting users to bypass connection prompts, and then
grant access to all remote control features.

VNC User Guide

111

Chapter 7: Making Connections Secure

Alternatively, to tailor permissions more precisely, choose Custom permissions:

To:

Grant permission to use a particular feature, turn on Allow. If a group is selected, this can be overridden
for an individual member by turning on Deny.

Disallow permission to use a feature, turn off Allow. If a group is selected, this can be overridden for an
individual member by turning on Allow or Deny.

Disable a feature, turn on Deny. This cannot be overridden.

Note that:

Omitting to grant the View the desktop permission means connected users see only a blank screen.

Granting permission to use the following features has no effect if those features are disabled globally:
Control desktop using keyboard
Control desktop using mouse
Copy and paste text in either direction
Chat with other users
Transfer files in either direction
Print to a local printer
See Restricting functionality for all connected users on page110 for more information.

112

VNC User Guide

Chapter 7: Making Connections Secure

Consider the following example of a registered Domain Admins group consisting of two user accounts,
johndoe and janedoe. The johndoe user account is also registered separately, for fine-grained control:

The following table explains for whom the printing feature is available given that johndoe inherits
permissions from Domain Admins, but can override these in certain circumstances:
Is printing available?

johndoe
Allow

Domain Admins

Allow

Deny

Allow

YES

janedoe: YES
johndoe: NO

janedoe: YES
johndoe: NO

Allow

janedoe: NO
johndoe: YES

NO

NO

Deny

NO

NO

NO

VNC User Guide

113

Chapter 7: Making Connections Secure

Verifying the identity of VNC Server

VNC Server with an Enterprise or a Personal license has a digital signature:

Under Windows and Mac OS X, this signature uniquely identifies a particular instance of VNC Server
running on a host computer.

Under UNIX, this signature is shared by all instances of VNC Server started by the same computer user.

Note: This feature is not available for VNC Server with a Free license. Upgrade to an Enterprise or a
Personal license if security is important to you.
The VNC Server signature and catchphrase (a more-memorable version of the signature) are displayed in
the Get Started area of the VNC Server dialog. More on this dialog.

When a user connects from a particular client computer for the first time, the signature and catchphrase are
published. The user is asked to verify that the information they see matches that of VNC Server; see
Checking the identity of VNC Server on page24 for more information.
A VNC Server signature should not change. The next (and all subsequent) times a user connects from the
same client computer, the signature is not published. If the signature changes, it may be because a third
party is interrupting the connection between client and host computers and eavesdropping on
communications a so-called man-in-the-middle attack. If a user sees a message similar to the following:

then it is recommended that that user does not connect.

Note: The signature does change if VNC Server is re-installed, or if the private key is regenerated.

114

VNC User Guide

Chapter 7: Making Connections Secure

Protecting privacy
By default, VNC Server promotes sharing. That is to say, multiple users can connect at the same time, all
connected users can observe each others operations, and if a host computer user is present, then that user
can observe the operations of connected users.
Note: To allow only one connection at a time, specify VNC Server parameters; start with AlwaysShared in
VNC Server parameters on page155 for more information.
Under some platforms, you can configure VNC Server to uphold other aspects on the Privacy page of the
Options dialog. More on this dialog.

To:

Prevent a host computer user observing the operations of connected users, turn on Blank screen while
users are connected (Windows only; not available under Windows 8).

Prevent a host computer user interrupting the operations of connected users, turn on Disable keyboard
and mouse while users are connected (Windows only).

Protect the host computer when no connections are in progress, select an appropriate option from the
When last user disconnects dropdown (Windows and Mac OS X 10.5+; VNC Server in Service Mode
only).

For more information on notification messages, see Notifying when users connect on page92.

VNC User Guide

115

Chapter 7: Making Connections Secure

116

VNC User Guide

A
Saving Connections
This appendix explains how to use VNC Viewer to save connections so you can quickly connect to favorite
host computers again with just a few mouse clicks.
Note: You can save connections to desktop icons. You can save connections to VNC Address Book if you
installed VNC on the client computer. See Setting up the client computer on page12 for more information.
A saved connection remembers the network address of the host computer and the authentication
credentials required to connect to VNC Server, so you do not have to, and automatically recreates your
preferred working environment each time.

Contents
Saving connections to VNC Address Book

118

Using VNC Address Book to connect

123

Managing connections using VNC Address Book

124

Saving connections to desktop icons

127

VNC User Guide

117

Appendix A: Saving Connections

Saving connections to VNC Address Book

You can save connections to VNC Address Book if you installed VNC on the client computer. For more
information, see Setting up the client computer on page12.
Note: If VNC Address Book is not available, you can save connections to desktop icons. This is equally
convenient but may be less secure. See Saving connections to desktop icons on page127.
When you save a connection, you can subsequently use VNC Address Book to connect to that host
computer instead of VNC Viewer. This means you do not have to remember the network address of the host
computer or the port number for VNC Server, nor a user name and password. In addition, VNC Address
Book automatically recreates the VNC Viewer environment you chose for controlling that host computer last
time, for example the scaling applied to the desktop, the encryption level, and the color quality.
Note: Because VNC Address Book stores VNC Server authentication credentials, access to it is controlled
by a master password. For more information, see Working with the master password on page126.
You can additionally use VNC Address Book to organize connections, configure the appearance and
behavior of VNC Viewer for particular connections, and share connections with other VNC Viewer users.

Saving the current connection

If you are connected to a host computer, you can save the current connection to VNC Address Book at any
time. To do this:
1. Click the Save Connection
VNC Viewer toolbar button. VNC Address Book opens. If you entered a
password in order to connect to VNC Server, you are prompted to save it:

Choose:
Dont save VNC Server password in order to forget the password. You will need to enter it each
time you use VNC Address Book to connect.
Save VNC Server password to save the password in obfuscated, though not encrypted, form. You
will no longer need to remember the password. However, since the connection will not be protected
by the VNC Address Book master password, any other user of your client computer will also be able
to connect.
Encrypt VNC Server password to create a protected connection in which the password is both
saved and encrypted. You will no longer need to remember it. You will, however, have to enter the

118

VNC User Guide

Appendix A: Saving Connections

VNC Address Book master password in order to connect (and also to edit the connection). Note that
a protected connection is identified by a padlock symbol

throughout VNC Address Book.

2. Click the OK button. If you chose to create a protected connection, and this is the first time you have
used VNC Address Book, you are prompted to specify a master password:

3. Click the OK button. The connection is saved to VNC Address Book:

To see how to use VNC Address Book to connect to this host computer again, read Using VNC Address
Book to connect on page123.
For more information on editing and organizing connections, start with Organizing connections on
page125.

VNC User Guide

119

Appendix A: Saving Connections

Creating a new connection

You can create a connection in VNC Address Book directly. To do this:
1. Start VNC Address Book on the client computer. See how to do this. The VNC Address Book dialog
opens:

120

VNC User Guide

Appendix A: Saving Connections

2. Click the New Entry

toolbar button. The Properties dialog opens:

3. Enter a network address for the host computer in the VNC Server field (including a port number if necessary), choose an Encryption option (or retain the default) and, optionally, specify your VNC Server
user name and password in the Authentication area. To see how to find out this information, start with
Step 3: Identify VNC Server running on the host computer on page21.
By default, VNC Address Book creates a protected connection. This means you must enter the VNC
Address Book master password in order to connect to the host computer, and also to edit the
connection. A protected connection is identified by a padlock symbol

throughout VNC Address Book.

Note: Turn off Encrypt password (recommended) if you do not want to enter the VNC Address Book
master password in order to connect. Note this may constitute a security risk if others use your client
computer.
You can optionally edit VNC Viewer options in order to set up your preferred environment for controlling
this host computer. To do this, use the Basic tab to configure common options, or click the Advanced
button to see all the tabs. For more information, start with Configuring VNC Viewer before you connect
on page37.

VNC User Guide

121

Appendix A: Saving Connections

4. Click the OK button. If you chose to create a protected connection, and this is the first time you have
used VNC Address Book, you are prompted to specify a master password:

5. Click the OK button. The connection is saved to VNC Address Book:

To see how to use VNC Address Book to connect to this host computer, read Using VNC Address Book to
connect on page123.
For more information on editing and organizing connections, start with Organizing connections on
page125.

122

VNC User Guide

Appendix A: Saving Connections

Using VNC Address Book to connect

You can use VNC Address Book to quickly connect to a host computer. To do this:
1. Start VNC Address Book on the client computer. See how to do this. The VNC Address Book dialog
opens:

2. Either:
Double-click a connection in the Alphabetic or Hierarchical list.
Select a connection in a list and click the Connect

toolbar button.

You may be required to enter the VNC Address Book master password in order to connect. For more
information, see Working with the master password on page126.
Under Windows, when VNC Address Book starts, a VNC Address Book icon
is displayed in the
Notification area. This icon provides further options for quickly and conveniently connecting to host
computers. For more information, see Working with VNC Address Book on page124.

VNC User Guide

123

Appendix A: Saving Connections

Managing connections using VNC Address Book

This section explains VNC Address Book features and operations.

Starting VNC Address Book

To start VNC Address Book:

Under Windows, select RealVNC > VNC Address Book from the Start menu.
Note: Under Windows, you can start VNC Address Book automatically when the computer is powered
on. To do this, select Tools > Options and, in the UI behavior area, turn on Start with Windows.

Under UNIX, select Applications > Internet > VNC Address Book from the menu system, or search for
this application using the standard operating system facility.
Note: If no menu system or search facility is available, open a Terminal window and run the command
vncaddrbook. Note you should not do this as a user with administrative privileges.

Under Mac OS X, navigate to Applications > RealVNC, and double-click VNC Address Book.

Working with VNC Address Book

Under Windows, while VNC Address Book is running, a VNC Address Book icon
Notification area. Under Windows 7, note this is hidden by default and accessible from
Taskbar:

is displayed in the
to the right of the

Under Windows XP, the icon may be hidden by other icons.

Note: Under UNIX and Mac OS X, no VNC Address Book icon is available. However, most operations
explained below can be performed from the VNC Address Book dialog.
The VNC Address Book icon:

Provides visual confirmation that VNC Address Book is running on the client computer. If the icon is not
available, then VNC Address Book is not running.

Has a shortcut menu that performs useful operations:

124

VNC User Guide

Appendix A: Saving Connections

The following table explains the effect of selecting each VNC Address Book shortcut menu option.
Option

Purpose

Connect to

Choose a host computer to connect to.

Launch VNC Viewer

Start VNC Viewer, enabling you to connect to a new host computer in the standard
way. For more information, see Connecting to a host computer on page39.

Open Address Book

Create new connections or edit and organize existing ones. (Alternatively, double-click
the VNC Address Book icon to open the VNC Address Book dialog.)

Exit

Close VNC Address Book.

Organizing connections
VNC Address Book organizes connections both alphabetically and hierarchically:

You can reorganize connections in the Hierarchical list. (The Alphabetic list is automatically organized.)
Click the New Folder
toolbar button to create folders in the Hierarchical list. You can drag-and-drop
connections to, from, and between folders. Note that if you delete a folder, all connections in that folder are
deleted too.

Editing connections
You can edit an existing connection. Note you may be required to enter the VNC Address Book master
password first.
To do this, select a connection in the Alphabetic or Hierarchical list, and either:

Click the Properties

Select Edit > Properties.

toolbar button.

For more information on editing VNC Viewer options, start with Configuring VNC Viewer before you connect
on page37.
To rename a connection in VNC Address Book, select it in the Alphabetic or Hierarchical list and select
Edit > Rename, or right-click and select Rename from the shortcut menu.

VNC User Guide

125

Appendix A: Saving Connections

Sharing connections
You can share one or more connections with other fully-featured VNC Viewer users. Note that VNC Server
passwords are also shared, albeit in obfuscated or encrypted form.
To share:

All VNC Address Book connections, select Tools > Export Address Book.

A single connection, right-click it in the Alphabetic or Hierarchical list and, from the shortcut menu,
select Export.

Choose a location for the exported file. If the file contains a protected connection (one in which the VNC
Server password was saved and encrypted), the recipient will need your VNC Address Book master
password in order to import it.
You can import one or more connections shared by other fully-featured VNC Viewer users. To do this, select
Tools > Import Address Book, and select the file to import. If the file contains a protected connection, you
will need the VNC Address Book master password of the user who created the file in order to import it.

Removing connections
To remove a connection, select it in the Alphabetical or Hierarchical list, and either:

Click the Delete

Select Edit > Delete.

toolbar button.

Working with the master password

If you chose to encrypt a VNC Server password when you saved a connection to a host computer, you
created a protected connection.
VNC Address Book secures protected connections using the master password. You must enter the master
password in order to perform an operation on a protected connection, for example connecting to the host
computer, or editing the connection.
Note: You do not have to enter the master password in order to perform operations on connections for which
the VNC Server password was not saved, or was saved in obfuscated, though not encrypted, form. For more
information on saving VNC Server passwords, start with Saving the current connection on page118.
By default, VNC Address Book remembers the master password for one hour. This means you have sixty
minutes after you first enter it in order to perform an operation on a protected connection. To change this,
and require the entry of the master password, select:

Tools > Forget Master Password to require the entry of the master password for the next operation on
a protected connection.

Tools > Options and, in the Master password area, turn off Remember for to require the entry of the
master password for all future operations on protected connections. (Alternatively, you can decrease the
length of time the master password is remembered.)

Note: The Status Bar reports Master Password: Stored if you do not currently need to enter the
master password, and Master Password: Required if you do.

126

VNC User Guide

Appendix A: Saving Connections

To change the master password, select Tools > Options and, in the Master password area, click the
Change button.

Saving connections to desktop icons

You can save the current connection to a desktop icon on the client computer:

A desktop icon provides an extremely quick and convenient way of connecting to a host computer. Simply
double-click the icon to connect. Your preferred VNC Viewer environment for controlling the host computer is
automatically recreated.
Note: You may need to associate the desktop icon with the VNC Viewer executable file the first time you
double-click an icon connect.
To save the current connection as a desktop icon:
1. Click the Save Connection

VNC Viewer toolbar button.

Note: If VNC Address Book is installed on the client computer, you must first disable it. To do this, click
the Options
VNC Viewer toolbar button to open the Options dialog and, on the Expert tab, set the
UseAddrBook parameter to False.
2. If you entered a password in order to connect to VNC Server, you are prompted to save the password.
Note that doing so may constitute a security risk, since the password is saved in obfuscated, though not
encrypted, form. If you do not save the password, you must enter it each time you connect.
3. Choose a location to save the icon file to (for example, the desktop), and an intuitive name.

VNC User Guide

127

Appendix A: Saving Connections

128

VNC User Guide

B
Setting Up VNC
This appendix explains to system administrators how to set up and configure VNC applications for multiple
users in an enterprise environment.
Note an Enterprise license to use VNC Server is required for many features.

Contents
Configuring VNC

130

Specifying VNC parameters

130

Specifying Xvnc options

136

Preventing users configuring VNC

138

Managing system authentication

141

Setting up single sign-on authentication

143

Hosting VNC on a UNIX network share

145

Logging information

148

Removing VNC

150

VNC User Guide

129

Appendix B: Setting Up VNC

Configuring VNC
VNC applications can be configured in almost any way to suit your requirements and environment.
Specify...
To configure...

VNC parameters (page 130)

Xvnc options (page 136)

VNC Server in Virtual Mode under UNIX

YES

YES

All other VNC applications and platforms

YES

You can:

Configure VNC applications on the same computer on which applications are installed; start with
Specifying VNC parameters on page130.

Remotely configure and lock down VNC applications using policy; start with Preventing users
configuring VNC on page138.

Remotely configure VNC applications on Windows computers using VNC Deployment Tool; visit
www.realvnc.com/products/vnc/deployment/vnctool/.

Host certain VNC applications on a UNIX network share and specify a single set of preferences
centrally; see Hosting VNC on a UNIX network share on page145.

For more information on remote configuration options, start with www.realvnc.com/products/vnc/

deployment/.
By default, users can configure VNC applications. To see how to prevent or mitigate against this, see
Preventing users configuring VNC on page138.

Specifying VNC parameters

All VNC applications are controlled by VNC parameters, set to suitable default values for most users out-ofthe-box.
You can configure any VNC application by specifying new values for VNC parameters:

Before the application starts. See Configuring VNC applications before they start on page131.

While the application is running, and connections are in progress. See Reconfiguring running VNC
applications on page134.

For explanations of individual parameters, see Appendix C, VNC Parameters on page153.

130

VNC User Guide

Appendix B: Setting Up VNC

Configuring VNC applications before they start

Specify VNC parameters...
To configure VNC applications...

Windows

UNIX

Mac OS X

Prior to start-up

Registry keys
(page 131)

VNC configuration files

(page 132)

VNC configuration files

(page 132)

At start-up (page 134)

Command line

Command line

Command line

Using policy (page 138)

Registry keys

VNC configuration files

VNC configuration files

Note that parameters are applied in the order listed in the table above, so that a parameter set by policy
overrides the same parameter specified at the command line, which in turn overrides the same parameter
specified prior to start up. Note that parameters set by policy cannot be changed by users. See the sections
below for more information.

Populating the Windows Registry with VNC parameters

Under Windows, if you have permission to edit the Windows Registry, you can specify VNC parameters as
values for particular Registry keys.
Note: If you have an Enterprise license, and do not wish to edit the Registry directly, you can set policy or
use VNC Deployment Tool. Visit www.realvnc.com/products/vnc/deployment/ for more information.
The following table lists the Registry keys to create or edit for each VNC application, and the order in which
parameters are applied.
VNC application

Order parameters are applied

(lowest takes precedence)

Notes

VNC Server in
Service Mode

HKLM\Software\RealVNC\vncserver
HKLM\Software\Policies\RealVNC\vncserver

VNC Server in
User Mode

HKCU\Software\RealVNC\vncserver
<parameters at the command line>
HKCU\Software\Policies\RealVNC\vncserver

The Options dialog for an

application updates a particular
Registry key; see this table on
page135.

VNC Viewer

HKCU\Software\RealVNC\vncviewer
<parameters at the command line>
HKCU\Software\Policies\RealVNC\vncviewer

Note it is not possible to specify

parameters at the command line
for VNC Server in Service Mode.

For example, to specify the Log parameter for VNC Server in Service Mode:
1. Using Registry Editor, navigate to HKEY_LOCAL_MACHINE\Software\RealVNC\vncserver.
2. Select New > String Value from the shortcut menu, and create Log.
3. Select Modify from the shortcut menu, and specify appropriate Value data, for example *:file:100.
Note: All VNC parameters take string values, even boolean parameters.

VNC User Guide

131

Appendix B: Setting Up VNC

Populating VNC configuration files with VNC parameters

Under UNIX and Mac OS X, each VNC application has a number of VNC configuration files, and additionally
a number shared between all VNC applications and user accounts on the computer. The following tables list
the files you can create or edit for each application, and the order in which parameters are applied.
UNIX

VNC application Order parameters are applied

(lowest takes precedence)

Notes

VNC Server in
User Mode
(vncserverX11)

/etc/vnc/config.d/common.custom
/etc/vnc/config.d/vncserver-x11
~/.vnc/config.d/common
~/.vnc/config.d/vncserver-x11
<parameters at the command line>
/etc/vnc/policy.d/common
/etc/vnc/policy.d/vncserver-x11

The Options dialog updates a particular

VNC configuration file; see this table on
page135.

VNC Server in
Service Mode
daemon
(vncserverX11-serviced)

/etc/vnc/config.d/common.custom
/etc/vnc/config.d/vncserver-x11-serviced
/root/.vnc/config.d/common
/root/.vnc/config.d/vncserver-x11-serviced
<parameters at the command line>
/etc/vnc/policy.d/common
/etc/vnc/policy.d/vncserver-x11-serviced

The daemon only accepts a subset of

parameters; run vncserver-x11serviced -help for a list. The daemon
then launches the vncserver-x11
process as root, at which point its VNC
configuration files are applied to it (see
VNC Server in User Mode, above).
The Options dialog updates a particular
vncserver-x11 VNC configuration file;
see this table on page135.

VNC Server in
Virtual Mode
(Xvnc, via
vncservervirtual or
vncserver)

/etc/vnc/config.d/common.custom
/etc/vnc/config.d/Xvnc
~/.vnc/config.d/common
~/.vnc/config.d/Xvnc
<parameters at the command line>
/etc/vnc/policy.d/common
/etc/vnc/policy.d/Xvnc

The Options dialog updates a particular

VNC configuration file; see this table on
page135.

VNC Server in
Virtual Mode
daemon
(vncservervirtuald)

/etc/vnc/config.d/common.custom
/etc/vnc/config.d/vncserver-virtuald
/root/.vnc/config.d/common
/root/.vnc/config.d/vncserver-virtuald
<parameters at the command line>
/etc/vnc/policy.d/common
/etc/vnc/policy.d/vncserver-virtuald

The daemon only accepts a subset of

parameters; run vncserver-virtuald
-help for a list The daemon then
launches the Xvnc process for each
connecting user, at which point its VNC
configuration files are applied to it (see
VNC Server in Virtual Mode, above).
Note this application does not have an
Options dialog.

VNC Viewer
(vncviewer)

132

/etc/vnc/config.d/common.custom
/etc/vnc/config.d/vncviewer
~/.vnc/config.d/common
~/.vnc/config.d/vncviewer
<parameters at the command line>
/etc/vnc/policy.d/common
/etc/vnc/policy.d/vncviewer

VNC User Guide

The Options dialog updates a particular

VNC configuration file; see this table on
page135.

Appendix B: Setting Up VNC

Mac OS X

VNC application Order parameters are applied

(lowest takes precedence)

Notes

VNC Server in
Service Mode

Parameters specified in /etc/vnc/*.d/

vncserver are applied to VNC Server in
User Mode too.

/etc/vnc/config.d/common.custom
/etc/vnc/config.d/vncserver
/var/root/.vnc/config.d/common
/var/root/.vnc/config.d/vncserver
/etc/vnc/policy.d/common
/etc/vnc/policy.d/vncserver

The Options dialog updates a particular VNC

configuration file; see this table on page135.
Note it is not possible to specify parameters at
the command line.

VNC Server in
User Mode

VNC Viewer

/etc/vnc/config.d/common.custom
/etc/vnc/config.d/vncserver
~/.vnc/config.d/common
~/.vnc/config.d/vncserver
<parameters at the command line>
/etc/vnc/policy.d/common
/etc/vnc/policy.d/vncserver

Parameters specified in /etc/vnc/*.d/

vncserver are applied to VNC Server in
Service Mode too.

/etc/vnc/config.d/common.custom
/etc/vnc/config.d/vncviewer
~/.vnc/config.d/common
~/.vnc/config.d/vncviewer
<parameters at the command line>
/etc/vnc/policy.d/common
/etc/vnc/policy.d/vncviewer

The Options dialog updates the VNC

configuration file in this table on page135.

The Options dialog updates the VNC

configuration file in this table on page135.

Sharing VNC configuration files between applications and user accounts

When VNC is installed, /etc/vnc/config.d/common is created. This file is reserved for use by RealVNC.
To specify parameters for all VNC applications for all user accounts on the computer, create the following
file:
/etc/vnc/config.d/common.custom

To specify parameters for all VNC applications for a particular user account, create the following file:
~/.vnc/config.d/common

Note: ~ is the root user account for certain applications; see the tables above.
Other VNC configuration files are application-specific. For example, to specify parameters for VNC Server in
User Mode for all user accounts on a UNIX computer, create the following file:
/etc/vnc/config.d/vncserver-x11

To specify parameters for VNC Server in User Mode for a particular user account, create the following file:
~/.vnc/config.d/vncserver-x11

Note this is the file updated by the Options dialog; see Using the Options dialog on page135.

VNC User Guide

133

Appendix B: Setting Up VNC

Format of a VNC configuration file

Each parameter in a VNC configuration file should be on a separate line; white space and comments are
stripped, and environment variables expanded for parameters that accept them. For example:
#This is a comment
Desktop="Build machine"
UserPasswdVerifier=VncAuth
SecurityTypes=RA2ne,RA2
RsaPrivateKeyFile=$HOME/secure/vnc
Permissions=admin:f;vncusers:d;guests:v

Specifying VNC parameters at the command line

Under any platform, for most VNC applications, you can pass VNC parameters in at the command line when
you start that application, each preceded by a dash (-). This enables you to configure a particular instance
of the application, rather than every time it runs. For example:
vncserver-x11 -Desktop="Debug machine" -UserPasswdVerifier=UnixAuth
Note: You cannot specify parameters at the command line for VNC Server in Service Mode under Windows
or Mac OS X. For VNC Server in Service Mode under UNIX, and the VNC Server in Virtual Mode daemon,
you can specify command line parameters in the /etc/init.d/<daemon> script or in /etc/systemd/
system/<daemon>.service, but it is recommended to use VNC configuration files instead.
Parameters specified at the command line override the same parameters specified in the Windows Registry
(see this table on page131 for the exact order) or in VNC configuration files (see these tables on page132),
except for those set by policy.
Note there are disadvantages to specifying parameters at the command line:

The Options dialog does not reflect your choices, which may confuse users.

Under UNIX and Mac OS X, parameters may be overridden if a running application is reloaded; see
Reconfiguring running VNC applications on page134.

Note: RealVNC recommends specifying parameters either in the Windows Registry/VNC configuration files
or at the command line, but not both.
For convenience, if you have many command line parameters to specify, you can populate a text file (one
parameter per line; omit the dash) and reference it using the -vncconfigfile option, for example:
vncserver-x11 -vncconfigfile /my/command/line/parameter/file

Reconfiguring running VNC applications

You can reconfigure:

Any VNC application using its Options dialog, if it has one; see Using the Options dialog on page135.

VNC Server by reloading parameters; see Reloading VNC parameters on page136.

Note that most changes take effect immediately. Changes to a few parameters, however, require all
connections to be terminated, and changes to a very small minority require the application to be restarted.
See Chapter C, VNC Parameters on page153 for more information.

134

VNC User Guide

Appendix B: Setting Up VNC

Using the Options dialog

Most VNC applications have an Options dialog, providing a user-friendly interface to the VNC parameter
mechanism. An Options dialog typically consists of several tabs or pages devoted to particular topics such
as security or connectivity, and an Expert tab or page enabling users to edit VNC parameters directly. See a
picture.
Note the following:

The Options dialog for VNC Server in Service Mode requires elevated privileges.

The Options dialog for VNC Server in Virtual Mode is only available to connected users; see Working
with VNC Server in Virtual Mode on page80.

The Options dialog can be hidden from users; see Mitigating against change on page140.

VNC parameters set by policy are disabled in the Options dialog.

Changes made in an Options dialog automatically update a particular Registry key or VNC configuration
file; see the tables below. When the OK or Apply button is clicked, all Registry keys or VNC configuration
files for that application are then reloaded.
Windows

VNC application

The Options dialog updates...

VNC Server in Service Mode

HKLM\Software\RealVNC\vncserver

VNC Server in User Mode

HKCU\Software\RealVNC\vncserver

VNC Viewer

HKCU\Software\RealVNC\vncviewer

See this table on page131 for a complete list of Registry keys and the order in which they are applied.
UNIX

VNC application

The Options dialog updates...

VNC Server in User Mode

~/.vnc/config.d/vncserver-x11

VNC Server in Service Mode

/root/.vnc/config.d/vncserver-x11

VNC Server in Virtual Mode

~/.vnc/config.d/Xvnc

VNC Viewer

~/.vnc/config.d/vncviewer

See this table on page132 for a complete list of VNC configuration files and order in which they are applied.
Mac OS X

VNC application

The Options dialog updates...

VNC Server in Service Mode

/var/root/.vnc/config.d/vncserver

VNC Server in User Mode

~/.vnc/config.d/vncserver

VNC Viewer

~/.vnc/config.d/vncviewer

See this table on page133 for a complete list of VNC configuration files and order in which they are applied.

VNC User Guide

135

Appendix B: Setting Up VNC

Reloading VNC parameters

You can reconfigure a running instance of VNC Server without downtime by editing Registry keys (Windows)
or VNC configuration files (other platforms) and then running the -reload command to re-apply all Registry
keys or VNC configuration files to that instance of VNC Server. For example:
vncserver-x11 -reload
Note that:

The -reload command also re-applies license keys.

The -reload command does not re-apply:

VNC parameters specified at the command line under UNIX and Mac OS X. If these parameters
have subsequently changed, the original command line values will be overridden. See Specifying
VNC parameters at the command line on page134 for more information.
Xvnc options, for VNC Server in Virtual Mode under UNIX. See Specifying Xvnc options on
page136 for more information.

To reload all running instances of VNC Server for the current user, in any mode, run the command
vnclicense -reload. To reload all running instances of VNC Server in any mode for all users, run
the same command with elevated privileges.

Specifying Xvnc options

The information in this section applies to VNC Server in Virtual Mode under UNIX only.
In Virtual Mode, VNC Server is both:

An X server, with a virtual display. To configure it, specify Xvnc options; run the command vncservervirtual -list to see a list of valid options, and examine the output at the top. Note that many of
these options may also be valid for your actual X server; run the command man Xserver for a more
detailed explanation of shared options.

A standard VNC server. To configure it, specify VNC parameters in the same way as for any other VNC
application; start with Specifying VNC parameters on page130.

To compare VNC Server modes, consult Running multiple instances of VNC Server on page78.

Configuring VNC Server prior to start up

You can specify Xvnc options in one or more Xvnc configuration files.
When VNC is installed, /etc/vnc/config is created; this file is reserved for use by RealVNC. To specify
Xvnc options for all user accounts on the computer, create the following file:
/etc/vnc/config.custom
If this file exists, /etc/vnc/config is ignored.
To specify Xvnc options for a particular user account, create the following file:
~/.vnc/config

136

VNC User Guide

Appendix B: Setting Up VNC

If this file exists, it is applied in addition to either /etc/vnc/config or /etc/vnc/config.custom. Note if

you specify the same Xvnc option in multiple locations there is no guarantee which will actually take effect.
Note: ~/.vnc/config is ignored if VNC Server is started with the -config FILE switch; see Configuring
VNC Server at start up on page137.

Format of an Xvnc configuration file

Each option in an Xvnc configuration file should be on a separate line, and in the format expected by the X
Window System; white space and comments are stripped, and environment variables expanded. For
example:
#This is a comment
-dumbSched
+kb
-core
+xinerama
nologo
Note: RealVNC recommends you do not put VNC parameters in Xvnc configuration files.

Configuring VNC Server at start up

You can pass Xvnc options in at the command line when you start VNC Server. RealVNC recommends
using the vncserver-virtual command or the vncserver symlink to start the Xvnc process; options
are passed directly to Xvnc without alteration. For example:
vncserver-virtual -xinerama -logo
Xvnc options specified at the command line are applied in addition to those in any Xvnc configuration files;
see Configuring VNC Server prior to start up on page136. Note if you specify the same Xvnc option in
multiple locations there is no guarantee which will actually take effect.
Note: If the -config FILE command line switch is applied, ~/.vnc/config is ignored. Visit
www.realvnc.com/products/vnc/documentation/latest/reference/vncserver-virtual.html for more information.

VNC User Guide

137

Appendix B: Setting Up VNC

Preventing users configuring VNC

By default, users can configure VNC applications.
If you have:

An Enterprise license, you can set policy to lock down any VNC application to prevent change. See
Setting policy to lock down VNC applications on page138.

A Personal or a Free license, you can set policy to lock down VNC Viewer. You cannot lock down VNC
Server, though you can make it harder to change. See Mitigating against change on page140.

Multiple computers with a mix of license types, you can lock down VNC Server on computers that have
an Enterprise license, and then prevent VNC Server running on computers that have a Personal and a
Free license. For more information, visit www.realvnc.com/products/vnc/deployment/policy/.

Setting policy to lock down VNC applications

You can specify VNC parameters in special policy Registry keys (Windows) or VNC configuration files (other
platforms) in order to lock down VNC applications. Parameters in these locations are applied after all others,
overriding the same parameters specified elsewhere, and cannot be changed by users.
Note: Policy template files containing VNC parameters for each application are freely available to download
from the RealVNC web site. Visit www.realvnc.com/download/deployment/policy/ for more information.
Windows

VNC application

Registry key mandating policy...

VNC Server in Service Mode

HKLM\Software\Policies\RealVNC\vncserver

VNC Server in User Mode

HKCU\Software\Policies\RealVNC\vncserver

VNC Viewer

HKCU\Software\Policies\RealVNC\vncviewer

It is possible to create policy Registry keys manually; see Populating the Windows Registry with VNC
parameters on page131. However, RealVNC recommends downloading policy template files, making the
necessary edits, and then using Microsoft tools such as Group Policy to distribute GPOs to target
computers.
Note: Set appropriate permissions on HKLM\Software\Policies\RealVNC and
HKCU\Software\Policies\RealVNC to ensure users cannot edit policy Registry keys.

138

VNC User Guide

Appendix B: Setting Up VNC

UNIX

VNC application

VNC configuration file mandating policy...

Notes

VNC Server in User

Mode

/etc/vnc/policy.d/vncserver-x11

VNC Server in
Service Mode

/etc/vnc/policy.d/vncserver-x11-serviced Note most parameters should be

specified in /etc/vnc/policy.d/
vncserver-x11; see this table on
page132 for why.

VNC Server in Virtual

Mode

/etc/vnc/policy.d/Xvnc

VNC Server in Virtual

Mode daemon

/etc/vnc/policy.d/vncserver-virtuald

VNC Viewer

/etc/vnc/policy.d/vncviewer

Note parameters related to individual

sessions should be specified in /etc/
vnc/policy.d/Xvnc; see this table
on page132 for why.

It is possible to create policy VNC configuration files manually; see Populating VNC configuration files with
VNC parameters on page132. However, RealVNC recommends downloading policy template files, making
the necessary edits, and then distributing files to the /etc/vnc/policy.d directory of target computers.
Note: Set appropriate ownership or permissions on the /etc/vnc/policy.d directory to ensure users
cannot edit policy VNC configuration files.
Mac OS X

VNC application

VNC configuration file mandating policy... Notes

All VNC applications

/etc/vnc/policy.d/common

VNC Server in Service Mode

/etc/vnc/policy.d/vncserver

VNC Server in User Mode

VNC Viewer

Note both modes share the same file

(see this table on page133) so it is not
possible to lock them down
separately.

/etc/vnc/policy.d/vncviewer

It is possible to create policy VNC configuration files manually; see Populating VNC configuration files with
VNC parameters on page132. However, RealVNC recommends downloading policy template files, making
the necessary edits, and then distributing files to the /etc/vnc/policy.d directory of target computers.
Note: Set appropriate ownership or permissions on the /etc/vnc/policy.d directory to ensure users
cannot edit policy VNC configuration files.

VNC User Guide

139

Appendix B: Setting Up VNC

Mitigating against change

Most VNC applications have an Options dialog that users can use to make changes; see Using the Options
dialog on page135 for more information.

Disabling the VNC Server Options dialog

You can disable the VNC Server Options dialog. To do this, specify the DisableOptions VNC parameter:

Under Windows, in the HKEY_LOCAL_MACHINE\Software\RealVNC\vncserver (Service Mode) or

HKEY_CURRENT_USER\Software\RealVNC\vncserver (User Mode) Registry key.

Under UNIX, in the /root/.vnc/config.d/vncserver-x11 (Service Mode), ~/.vnc/config.d/

vncserver-x11 (User Mode), or ~/.vnc/config.d/Xvnc (Virtual Mode) VNC configuration file.

Under Mac OS X, in the /var/root/.vnc/config.d/vncserver (Service Mode) or ~/.vnc/

config.d/vncserver (User Mode) VNC configuration file.

Note: Under UNIX and Mac OS X, you can disable the Options dialog for all modes and users by specifying
the DisableOptions parameter in a global location such as /etc/vnc/config.d/common.custom.

Disabling the VNC Viewer Options dialog

You cannot disable the VNC Viewer Options dialog. However, you can set policy to lock down VNC Viewer
irrespective of license.

Preventing users editing storage locations

VNC parameters and other settings are stored in the locations listed below. Files and directories should have
suitable ownership or permissions to prevent users making changes.
Note: Connected users have administrative permissions on a computer if such a user account is currently
logged on (Service Mode, User Mode) or was used to start VNC Server (Virtual Mode).

140

VNC User Guide

Appendix B: Setting Up VNC

Windows

Registry key

Notes

HKEY_LOCAL_MACHINE\Software\RealVNC
HKEY_CURRENT_USER\Software\RealVNC

For each user account running VNC applications.

UNIX

Directory or file

Notes

/etc/vnc/config.d/
/etc/vnc/config

VNC Server in Virtual Mode only.

/etc/vnc/config.custom

VNC Server in Virtual Mode only.

/root/.vnc/config.d/
~/.vnc/config.d/

For each user account running VNC applications.

~/.vnc/config

For each user account running VNC Server in Virtual Mode only.

Mac OS X

Directory

Notes

/etc/vnc/config.d/
/var/root/.vnc/config.d/
~/.vnc/config.d/

For each user account running VNC applications.

Managing system authentication

If you have an Enterprise or a Personal license, VNC Server is set to use system authentication out-of-thebox. For more information, see Authenticating using system credentials on page96.
Under Windows and Mac OS X, providing the host computer is successfully joined to a domain, there
should be no need to configure system authentication. Under UNIX, however, connecting users are by
default only able to supply the credentials of local user accounts in order to authenticate to VNC Server. To
enable connecting users to supply the credentials of domain accounts, you must configure both VNC Server
and the host computer.

Setting up domain accounts under UNIX

When VNC Server is installed, a suitable PAM library checking credentials against the local database store
is automatically referenced. To see which library this is, and also the default authorization and account rules
specified, examine the following file:

Under modern versions of Linux: /etc/pam.d/vncserver.

Under Solaris, HP-UX, and older versions of Linux: /etc/pam.conf (see lines starting vncserver).

VNC User Guide

141

Appendix B: Setting Up VNC

Note: Under AIX, VNC Server uses LAM by default; contact Technical Support for more information. To use
PAM, specify the UsePam parameter; see Appendix C, VNC Parameters on page153.
To check credentials against an LDAP or an Active Directory password store:
1. Obtain a PAM library that provides this functionality, for example libpam-krb5.so. Running the
command vncinitconfig -pam may help find a suitable library already in use on your system.
2. Reference that library, and specify appropriate account and authentication rules, in the following file:
For platforms using /etc/pam.d/vncserver, in /etc/pam.d/vncserver.custom. Create this
file if it does not exist.
For platforms using /etc/pam.conf: edit this same file to create vncserver.custom rules
pointing to the new PAM library.
3. In an appropriate system-wide VNC configuration file (for example /etc/vnc/config.d/common.custom), specify the following VNC parameter to register your changes with VNC Server:
PamApplicationName=vncserver.custom
For more information on VNC configuration files, see Configuring VNC applications before they start on
page131. For more information on this parameter, see Appendix C, VNC Parameters on page153.
Note that a suitable PAM library for your platform may already be installed on the host computer, and
appropriate account and authentication rules specified. For example, if your system has been Kerberized, or
third party software such as Centrify or PowerBroker Identity Services installed to integrate with Active
Directory, then you may be able to simply reference changes already made. For example, under Debiancompatible Linux, you may be able to edit /etc/pam.d/vncserver.custom as follows:
@include common-auth
@include common-account
@include common-session
For Red Hat-compatible Linux, the equivalent edits might be:
auth
account
session

include
include
include

password-auth
password-auth
password-auth

Registering domain accounts with VNC Server

Domain accounts must be registered with VNC Server in the standard way, using either:

The Permissions parameter; see Appendix C, VNC Parameters on page153.

The user interface; see Managing the list of registered user accounts and groups on page97.

You may need to qualify user names with the domain name, for example DEV.ACMECORP.COM\johndoe.
Note that connecting users may also need to supply the user name qualified in this way too.

142

VNC User Guide

Appendix B: Setting Up VNC

Setting up single sign-on authentication

If you have an Enterprise license, you can specify single sign-on as the authentication scheme for VNC
Server. See Authenticating users automatically on page100 for more information.
Note the following conditions, which may mean that single sign-on is unsuitable for use in a home or small
office environment:

All prospective client and host computers must be joined to the same domain (a network managed by a
domain controller, running specialized software such as Kerberos or Active Directory).

All prospective VNC Viewer users must log on to their client computers using the credentials of domain
accounts; that is, of user accounts managed by the domain controller.

A fallback authentication scheme must be provided in case single sign-on fails for any reason. See
Providing a fallback scheme on page144.

Setting up the host computer

Perform the following steps:
1. Make sure the host computer is joined to a domain.
2. Specify the single sign-on authentication scheme, using either:
The SecurityTypes VNC parameter. Include at least one of the SSO or SSOne security types; see
Appendix C, VNC Parameters on page153.
The user interface; see Authenticating users automatically on page100.
3. Under UNIX and Mac OS X, reference a GSSAPI-compatible library.
Note a suitable library may already be present on your system, for example /usr/lib/x86_64linux-gnu/libgssapi_krb5.so under Ubuntu Linux, or /usr/lib/libgssapi_krb5.dylib
under Mac OS X. Alternatively, you may be able to obtain one by installing third party software such as
PowerBroker Identity Services or Centrify, designed to integrate with Active Directory.
4. Under UNIX and Mac OS X, create an /etc/vnc/ssolib symbolic link pointing to the location of the
GSSAPI-compatible library (above).
5. Under Mac OS X 10.7 only, if you are integrating with Active Directory, edit the /etc/pam.d/authorization file as follows:
auth
optional
auth
sufficient
auth
optional
auth
required
account required

pam_krb5.so use_first_pass use_kcminit default_principal

pam_krb5.so use_first_pass default_principal
pam_ntlm.so use_first_pass
pam_opendirectory.so use_first_pass nullok
pam_opendirectory.so

VNC User Guide

143

Appendix B: Setting Up VNC

6. Under Mac OS X 10.7 onwards, use Directory Utility (/System/Library/CoreServices/Directory Utility.app) to ascertain the service principal name of the host computer as it is registered
with the domain controller, for example:

Assign the dsAttrTypeNative:servicePrincipalName host value to the VNC Server

KerberosPrincipalName parameter, so in this case host/users-macbookp.dev.realvnc.ltd.
7. Register the domain accounts of all prospective VNC Viewer users with VNC Server, using either:
The Permissions VNC parameter; see Appendix C, VNC Parameters on page153.
The user interface; see Managing the list of registered user accounts and groups on page97.
Note you may need to qualify user names with the domain name, for example
DEV.ACMECORP.COM\johndoe.

Providing a fallback scheme

If single sign-on fails for any reason (for example, the domain controller cannot be contacted), VNC Server
automatically falls back to the authentication scheme specified by the UserPasswdVerifier VNC
parameter. By default, this is system authentication, and connecting users are prompted to supply the
credentials of a user account valid for logging on to the host computer.
By default under UNIX, connecting users are only able to supply the credentials of local user accounts. To
enable connecting users to supply their own credentials (that is, of domain accounts), you must configure
both VNC Server and the host computer. Follow the instructions in Managing system authentication on
page141.

Setting up each client computer

Perform the following steps:
1. Make sure the client computer is joined to the same domain as the host computer.
2. Make sure the VNC Viewer user logs on to their client computer using the credentials of a domain
account.
3. Under UNIX and Mac OS X, reference a GSSAPI-compatible library.
Note a suitable library may already be present on your system, for example /usr/lib/x86_64linux-gnu/libgssapi_krb5.so under Ubuntu Linux, or /usr/lib/libgssapi_krb5.dylib

144

VNC User Guide

Appendix B: Setting Up VNC

under Mac OS X. Alternatively, you may be able to obtain one by installing third party software such as
PowerBroker Identity Services or Centrify, designed to integrate with Active Directory.
4. Under UNIX and Mac OS X, create an /etc/vnc/ssolib symbolic link pointing to the location of the
GSSAPI-compatible library (above).
5. Make sure VNC Viewer is set to use single sign-on, by either:
Setting the SingleSignOn VNC parameter to TRUE; see Appendix C, VNC Parameters on
page153.
Turning on Use single sign-on if VNC Server supports it in the VNC Viewer Options dialog); see
page 38.

Hosting VNC on a UNIX network share

This section explains how to install VNC applications on one UNIX computer and run those applications
from any other UNIX computer with whom the installation directory is shared.
Note the following restrictions, which may mean that certain VNC applications or VNC Server modes cannot
be hosted in this way:

A domain license key is required for VNC Server. Contact RealVNC for more information.

VNC Server in Service Mode (vncserver-x11-serviced) and the VNC Server in Virtual Mode
daemon (vncserver-virtuald) cannot be served.

If system authentication is specified, connecting users can only authenticate using the credentials of the
host computer user starting VNC Server. The credentials of other local user accounts registered using
the Permissions VNC parameter are ignored.

The single sign-on authentication scheme is not available.

Printing is not available.

The vncserver symlink is not available to start VNC Server in Virtual Mode out-of-the-box.

To host VNC applications (note all commands require administrative privileges):

1. On the hosting computer, download generic installer(s) containing unpackaged binaries from
www.realvnc.com/download/vnc/, and extract to <install dir>. Do not run the vncinstall script.
Note: Choose a generic installer appropriate to the platform and architecture of the computers you
intend to share the installation directory with (that is, from which VNC applications will be run). For
example, if you are targeting a mixture of Ubuntu computers, you could download both VNC for Linux
generic installers, and create and share <install dir>/x86 and <install dir>/x64 appropriately.
2. Create an <install dir>/vnc directory.
3. Run the following command to license VNC Server:
vnclicense -LicenseDir=<install dir>/vnc -add <domain license key>
4. Run the command vncinitconfig -config to generate a font path for virtual desktops, and move
the resulting /etc/vnc/config file to <install dir>/vnc.

VNC User Guide

145

Appendix B: Setting Up VNC

Note: This path is extracted from the X server of the hosting computer. If computers from which
applications will be run have a different X server configuration, it may be necessary to create an /etc/
vnc/config.custom file on each, and populate it with the Font Path output of the command xset
-q.
5. Run the command vncinitconfig -xstartup to generate a start up script for virtual desktops, and
move the resulting /etc/vnc/xstartup file to <install dir>/vnc.
6. On computers from which applications will be run, mount <install dir> read-only, and add the location to
users paths.

Configuring VNC applications centrally

You can configure VNC applications using VNC parameters, and additionally VNC Server in Virtual Mode
using Xvnc options. See Configuring VNC on page130 for general information.

Specifying VNC parameters

You can specify VNC parameters in one or more VNC configuration files. VNC configuration files have a
strict heirarchy; see Populating VNC configuration files with VNC parameters on page132 for more
information, a full list of files, and the order in which parameters are applied.
VNC configuration files must be located in directories under <install dir>/vnc. Perform the following steps:
1. Create an <install dir>/vnc/config.d directory, and move /etc/vnc/config.d/common to it. This
file is reserved for use by RealVNC.
2. Create an <install dir>/vnc/policy.d directory if you want to set policy. See Setting policy to lock
down VNC applications on page138 for more information.
3. Create and populate with VNC parameters as many of the following files as required:
To configure...

Create and populate...

All VNC applications that

can be served

<install dir>/vnc/config.d/common.custom

VNC Server in User Mode

(vncserver-x11)

<install dir>/vnc/config.d/vncserver-x11

VNC Server in Virtual Mode

(Xvnc, via vncserver-virtual)

<install dir>/vnc/config.d/Xvnc

VNC Viewer
(vncviewer)

<install dir>/vnc/config.d/vncviewer

<install dir>/vnc/policy.d/common

<install dir>/vnc/policy.d/vncserver-x11

<install dir>/vnc/policy.d/Xvnc

<install dir>/vnc/policy.d/vncviewer

Note the following:

If you specify a default configuration in <install dir>/vnc/config.d, individual users on computers

running VNC applications can override your preferences by specifying the same VNC parameters at the
command line when applications start. To prevent this, set policy.

If you specify a default configuration in <install dir>/vnc/config.d, individual users on computers

running VNC applications can persist changes they make via Options dialogs, since these changes are

146

VNC User Guide

Appendix B: Setting Up VNC

written to VNC configuration files in ~/.vnc/config.d, and reloaded each time the applications run.
To prevent this, set policy.

If computers running VNC applications have VNC configuration files stored locally in /etc/vnc/
config.d (perhaps because VNC was previously installed), VNC parameters in those files override the
same parameters specified in <install dir>/vnc/config.d. To prevent this, remove this directory from
affected computers, or set policy.

If computers running VNC applications have policy set locally in /etc/vnc/policy.d (perhaps
because VNC was previously installed), VNC parameters in those files override the same parameters
specified in <install dir>/vnc/policy.d. To prevent this, remove this directory from affected
computers.

Specifying Xvnc options

You can specify Xvnc options for VNC Server in Virtual Mode in an Xvnc configuration file. See Specifying
Xvnc options on page136 for why you might want to do this.
Note: RealVNC recommends you do not put VNC parameters in Xvnc configuration files.
To do this, create <install dir>/vnc/config.custom and populate it with valid Xvnc options. Note options
in this file override the same options specified by RealVNC in <install dir>/vnc/config.
Note the following:

If you specify Xvnc options in <install dir>/vnc/config.custom, individual users on computers

running VNC Server in Virtual Mode can override your preferences by appending Xvnc options to the
vncserver-virtual command.

If computers running VNC Server in Virtual Mode have either the /etc/vnc/config or /etc/vnc/
config.custom Xvnc configuration files stored locally (perhaps because VNC was previously
installed), Xvnc options in these files override the same options specified in <install dir>/vnc/
config.custom. To prevent this, remove these files from affected computers.

If individual users have a ~/.vnc/config Xvnc configuration file stored locally (perhaps because VNC
was previously installed), Xvnc options in this file override the same options specified in <install dir>/
vnc/config.custom. To prevent this, remove this file from affected computers.

VNC User Guide

147

Appendix B: Setting Up VNC

Logging information
By default, VNC Server and VNC Viewer record basic information about connection activity. You can
increase the amount of information recorded, change the type of activity, or alter the destination. In addition,
you can start recording information about other VNC applications and processes.
The following table lists the default destinations for VNC Server and VNC Viewer log output:
Application

Windows

Mac OS X

UNIX

VNC
Server

Service Mode

Event Log
(see note 3)

/Library/Logs/
vncserver.log

/var/log/vncserverx11.log

User Mode

C:\Users\<user>\
AppData\Local\
RealVNC\vncserver.log
(see note 4)

~/Library/Logs/
vnc/vncserver.log

~/.vnc/vncserverx11.log

Virtual Mode

Standard Error
(see note 5)

Virtual Mode
daemon

/var/log/vncservervirtuald.log
(see also note 6)

Standard Error

Standard Error

Standard Error

VNC Viewer

Note the following:

1. If the destination is to file, the location is determined by the LogDir and LogFile VNC parameters.
Containing directories must be writable. See Appendix C, VNC Parameters on page153 for more information on these parameters.
2. If the destination is to file, file contents are overwritten each time an application is restarted. To preserve
information, choose a different destination, for example Standard Error. (You could still redirect this to file,
for example by using a command such as vncserver-x11 -Log=*:stderr:100 2>>myfile.)
3. Under Windows, you must ensure the Windows Event Log service is running and that Event Viewer >
Windows Logs > Application > Properties is set to overwrite as needed. If the service is not running
or the event log is full, connections cannot be established.
4. This location is for Windows 7, though note AppData may be hidden by default. The location is slightly
different under some other versions of Windows.
5. Under UNIX, the default destination for VNC Server in Virtual Mode is Standard Error, but vncservervirtual (or the vncserver symlink) automatically redirects this to file at ~/.vnc/<computer>:<display number>.log. Note the output of the X server session is included.
6. Under UNIX, each time a user connects to the VNC Server in Virtual Mode daemon, a new instance of
VNC Server in Virtual Mode is immediately started, and its log output automatically redirected to file as
above.
Note: Under UNIX and Mac OS X, VNC Server automatically logs connections authenticated using the
system authentication or single sign-on schemes to the syslog AUTHPRIV facility, typically located at /var/
log/auth.log and /var/log/secure.log respectively.

148

VNC User Guide

Appendix B: Setting Up VNC

Changing the information recorded

To change the content, destination, and quality of information recorded, edit the Log VNC parameter.
See Specifying VNC parameters on page130 for an introduction to VNC parameters. See Appendix C,
VNC Parameters on page153 for valid values for the VNC Server and VNC Viewer Log parameters.

Quickly generating debug logs

You may be eligible to contact Technical Support if you encounter a problem or require assistance. See
Contacting Technical Support on page8 for more information.
The Technical Support team rely on comprehensive debug log files to troubleshoot problems, equivalent to
setting the VNC Server and VNC Viewer Log parameters to *:file:100.
In order to quickly generate a debug log file for either VNC Server or VNC Viewer:
1. On the Troubleshooting page of the Options dialog, choose Create a debug log file, and then OK.
2. Restart the application.
3. Recreate the problem, and send the file in the specified location to Technical Support.

Recording information about other applications and processes

You can apply the Log, LogFile, and LogDir VNC parameters to VNC applications other than VNC
Server and VNC Viewer, and also to VNC Server sub-processes. This may be useful if Technical Support
requests that you dig deeper into any problems you may encounter.
Windows

You can apply parameters to the following applications and sub-processes by creating special keys in the
Windows Registry. Alternatively, for some applications, you can apply parameters at the command line.
Application or sub-process

Registry key

Parameters can Registry hive

be applied...

VNC Server

Registry

Licensing

Service
Mode

Service

vncserver-sservice

User interface

vncserverui-service

User Mode

User interface

vncserverui-user

(command line)

vnclicense

(Wizard)

vnclicensewiz

VNC Address Book

HKEY_LOCAL_MACHINE
HKEY_CURRENT_USER

Registry or
command line

vncaddrbook

For example, to create a log file for the VNC Server in Service Mode service:
1. Using Registry Editor, navigate to HKEY_LOCAL_MACHINE\Software\RealVNC.
2. Select New > Key from the shortcut menu, and create vncserver-sservice.
3. Select New > String Value from the shortcut menu, and create Log.
4. Select Modify from the shortcut menu, and specify appropriate Value data, for example *:file:100.

VNC User Guide

149

Appendix B: Setting Up VNC

Repeat steps 3 and 4 for the LogFile and LogDir parameters, if necessary. Restart the service to create
the new log file.
To create a log file for an application at the command line, apply parameters before any command, for
example:
vnclicense.exe -Log=*:file:100 -LogFile=license.log -add <key>
UNIX

You can apply parameters to the following applications when run from the command line:
vnclicense, vnclicensewiz, vncaddrbook
Do so before any command, for example:
vnclicense -Log=*:file:100 -LogDir=/home/dev/logs -add <key>
Mac OS X

You can apply the logging parameters to the following applications when run from the command line:
vnclicense, vnclicensewiz
Do so before any command, for example:
/Library/vnc/VNC\ Server\ Licensing.app/Contents/MacOS/vnclicensewiz
-Log=*:file:100
Note: Two files are created for the VNC Server Licensing Wizard: ~/Library/Logs/vnc/
vnclicensewiz.log and /Library/Logs/vnclicensewiz_helper.log.

Removing VNC
To completely remove VNC, first run the VNC uninstaller(s) in the standard way for your operating system.
Follow the appropriate instructions at www.realvnc.com/products/vnc/documentation/latest/installingremoving/.
The VNC uninstaller(s) remove all program files, and security-related files and settings. This section lists the
(benign) files and settings that remain. It assumes an original installation to the default location.

150

VNC User Guide

Appendix B: Setting Up VNC

Windows

Registry key or other setting

Notes

HKEY_LOCAL_MACHINE\Software\RealVNC
HKEY_LOCAL_MACHINE\Software\Policies\RealVNC
HKEY_CURRENT_USER\Software\RealVNC

For each user account running VNC applications.

HKEY_CURRENT_USER\Software\Policies\RealVNC

For each user account running VNC applications.

C:\Users\~\.vnc\

For each user account running VNC applications.

A firewall entry for Listening VNC Viewer.

If one was created.

Note: VNC Mirror Driver has been uninstalled if it is no longer listed as a display adaptor in Windows Device
Manager. Note any remaining files are managed by Windows as part of the Driver Store and should not be
manually removed.
UNIX

Directory or file

Notes

/etc/vnc/
/root/.vnc/
~/.vnc/

For each user account running VNC applications.

/etc/pam.d/vncserver*
/etc/init.d/vncserver*

Linux distributions using initd

/user/lib/systemd/system/vncserver*

Linux distributions using systemd

/var/log/vncserver*
/tmp/.vnc*

Note: VNC Server in Virtual Mode creates a /tmp/.X11-unix directory and /tmp/.X<num> files that
may persist after the application stops. Run the command vncserver-virtual -clean before
uninstalling VNC to delete stale files.
Mac OS X

Directory or file

Notes

/etc/vnc/
/var/root/.vnc/
~/.vnc/

For each user account running VNC applications.

/etc/pam.d/vncserver*
/Library/Logs/vnc*.log
~/Library/Logs/vnc

For each user account running VNC applications.

/tmp/.vnc*

VNC User Guide

151

Appendix B: Setting Up VNC

152

VNC User Guide

C
VNC Parameters
This appendix categorizes and explains the VNC parameters you can use to control the behavior of VNC
Server and VNC Viewer.
For information on how to specify parameters, why you might want to do so, and the order in which the same
parameters specified in multiple locations are applied, see Specifying VNC parameters on page130.

Contents
Categorizing VNC parameters

154

VNC Server parameters

155

VNC Viewer parameters

175

VNC User Guide

153

Appendix C: VNC Parameters

Categorizing VNC parameters

Note: Not all parameters can be easily categorized. Not all parameters are available for all platforms or all
modes. Some parameters may be classified in more than one category.
Category

VNC Server

Connectivity

InTransports, ProtocolVersion,
AllowHTTP, AllowRFB,
ProxyServer
EnableGuestLogin, GuestAccess,
Hosts, HttpPort, InTransports,
KerberosPrincipalName, localhost,
NtLogonAsInteractive,
PamAccountCheck, PamApplicationName,
Permissions, ProtocolVersion,
RfbPort, ServiceDiscoveryEnabled,
UsePam

Security

AuthTimeout, BlacklistThreshold,
BlacklistTimeout, ConnNotifyTimeout,
DisconnectAction, Hosts,
IdleTimeout, localhost,
NtLogonAsInteractive, Permissions,
QueryConnect, ReverseSecurityTypes,
RootSecurity, RsaPrivateKeyFile,
SecurityTypes, UserPasswdVerifier,
UsePam

Privacy

Shared
AlwaysShared, BlankScreen,
ConnNotifyTimeout,
DisableLocalInputs,
DisconnectAction, DisconnectClients,
NeverShared, QueryConnect

Performance

DisableAero, DisableEffects,
PollInterval, RemovePattern,
RemoveWallpaper, UpdateMethod,
UseCaptureBlt

AutoSelect, ColorLevel,
PointerEventInterval,
PreferredEncoding, ScalingQuality

Picture quality/
fidelity

DisableAero, DisableEffects,
PollInterval, ProvideVisuals,
UpdateMethod, UseCaptureBlt

AutoSelect, AutoSelectLossy,
ColorLevel, FullColor,
PointerEventInterval, ScalingQuality

Display/monitor

display, DisplayDevice, Monitor,

RandR

FullScreen,
FullScreenChangeResolution, Monitor,
Scaling, UseAllMonitors

User interaction

AcceptCutText, AcceptKeyEvents,
AcceptPointerEvents, ClipboardFT,
DisableLocalInputs, EnableChat,
SendCutText, ShareFiles

ClientCutText, EnableChat,
SendKeyEvents, SendMediaKeys,
SendPointerEvents, SendPrimary,
SendSpecialKeys, ServerCutText,
ShareFiles, UseDisplayCapture

User interface

DisableAddNewClient, DisableClose,
DisableOptions, DisableTrayIcon,
EnableManualUpdateChecks, Locale,
StartUI

EnableToolbar, Locale, MenuKey,

ToolbarIconSize,
DisableOptionsModeSwitch

154

VNC User Guide

VNC Viewer

Encryption, Identities,
RsaPrivateKeyFile,
SecurityNotificationTimeout,
VerifyID, WarnUnencrypted

Appendix C: VNC Parameters

VNC Server parameters

This section explains the VNC Server parameters available from the Expert tab of the Options dialog.
Key:
Parameter name

Platform(s), unless all

Default value

Explanatory text: Note all parameters are case-insensitive, for all platforms.
See also: Related parameters...

Note that:

VNC Server parameters override equivalent VNC Viewer parameters unless otherwise stated.

Changes made to parameters in the Expert tab take effect when the Apply button is clicked, unless
otherwise stated.
AcceptCutText

TRUE

Specify FALSE to prevent connected users pasting text to the host computer.
See also: SendCutText, ClipboardFT

AcceptKeyEvents

TRUE

Specify FALSE to prevent connected users controlling the host computer using their keyboards.
Use in conjunction with AcceptPointerEvents to make connections view only, and with AcceptCutText,
SendCutText, ShareFiles, and EnableChat to prevent all user interaction with the host computer.
See also: AcceptPointerEvents

AcceptPointerEvents

TRUE

Specify FALSE to prevent connected users controlling the host computer using their mice or other pointing devices.
Use in conjunction with AcceptKeyEvents to make connections view only, and with AcceptCutText,
SendCutText, ShareFiles, and EnableChat to prevent all user interaction with the host computer.
See also: AcceptKeyEvents

AllowChangeDefaultPrinter

TRUE

Specify FALSE to prevent the host computers default printer being changed to that of the first client computer that
connects.
Note: This parameter is ignored unless EnableRemotePrinting is TRUE.

AllowHTTP

TRUE

Specify FALSE to prevent VNC Viewer for Java being downloaded from VNC Server.
Note: This parameter is ignored unless AllowRFB is TRUE.
See also: AllowRFB, HttpPort, httpd

VNC User Guide

155

Appendix C: VNC Parameters

AllowRFB

TRUE

Specify FALSE to prevent connections to VNC Server. Existing connections are not terminated.
Note that FALSE also prevents VNC Viewer for Java being downloaded, even if AllowHTTP is TRUE.
See also: RfbPort, AllowRFB

AlwaysShared

FALSE

Specify TRUE or FALSE in conjunction with NeverShared, DisconnectClients, and the VNC Viewer Shared
parameter to determine whether one or multiple users can connect to and control the host computer at the same time.
AlwaysShared

NeverShared

DisconnectClients

Shared

Concurrent connections?

TRUE

FALSE

ignored

ignored

Yes.

FALSE

TRUE

TRUE

ignored

No. A new user will disconnect an existing user.

FALSE

TRUE

FALSE

ignored

No. A new user will not be able to connect.

FALSE

FALSE

ignored

TRUE

Yes.

FALSE

FALSE

TRUE

FALSE

No. A new user will disconnect an existing user.

FALSE

FALSE

FALSE

FALSE

No. A new user will not be able to connect.

AuthTimeout

120

Specify a number of seconds to give connecting users time to enter authentication credentials. After this, connections
are rejected, even if the correct credentials are supplied.
Specify 0 to give connecting users unlimited time.
Note: This parameter is ignored if UserPasswdVerifier is None.
See also: BlacklistThreshold, IdleTimeout

AutoLogonOverride

Windows

FALSE

VNC Server in Service Mode only.

Specify TRUE to allow connected users pressing the Shift key while logging off to override the ForceAutoLogon and
IgnoreShiftOverride Windows Registry values, and show the login screen. This means connected users can
choose a different user account to log on to.
By default, the Shift key press is ignored and the same user account is automatically logged back on.

156

VNC User Guide

Appendix C: VNC Parameters

BlacklistThreshold

Specify a number of unsuccessful authentication attempts that can be made from each client computer (identified by its
IP address) before all connections from that computer are rejected for BlacklistTimeout. This may help protect
against brute-force dictionary attacks on the password used to authenticate to VNC Server.
Note: This parameter is ignored if UserPasswdVerifier is None. Under UNIX, if UserPasswdVerifier is
UnixAuth, the underlying authentication system may also have a protection mechanism after 10 unsuccessful
attempts.
Specify 0 to allow unlimited unsuccessful authentication attempts from each client computer, for example if the host
computer is not connected to the Internet.
See also: BlacklistTimeout

BlacklistTimeout

10

Specify a number of seconds during which connections from the client computer identified by BlacklistThreshold
are forbidden. After this time, one further unsuccessful authentication attempt is permitted before BlacklistTimeout
is doubled and applied again.
Note: To reset BlacklistThreshold and BlacklistTimeout to their original values, restart VNC Server.
See also: BlacklistThreshold

BlankScreen

Windows

FALSE

Specify TRUE to blank the monitor of the host computer when users are connected, in order to protect their privacy.
Note: This parameter has no effect under Windows 8.
See also: ShareFiles

ClipboardFT

Windows

TRUE

Specify FALSE to prevent connected users on Windows client computers exchanging files with the host computer using
the standard operating system copy and paste mechanism.
Note: VNC Server must be restarted in order for a change to this parameter to take effect. In addition, this parameter is
ignored unless AcceptCutText and SendCutText are both TRUE.
See also: ShareFiles

ConnNotifyTimeout

Specify a number of seconds between 1 and 255 to display connection and disconnection notification messages for.
Specify 0 to disable notification messages.
See also: QueryConnect

Desktop

<mode-specific>

Specify a name for the host computer desktop to display on the title bar of connected VNC Viewer application windows.
Note: VNC Server must be restarted in order for a change to this parameter to take effect.

DebugClipboardHelper

Windows

Please do not change this parameter unless directed to do so by Technical Support.

VNC User Guide

157

Appendix C: VNC Parameters

DisableAddNewClient

FALSE

Specify TRUE to disable the Connect to Listening VNC Viewer option on the VNC Server shortcut menu, preventing
either a host computer or connected users establishing reverse connections via the user interface.
Note: Reverse connections can still be established from the command line.
See also: DisableTrayIcon, DisableClose, DisableOptions, ReverseSecurityTypes

DisableAero

Windows

FALSE

Specify TRUE to disable Windows Aero (the default graphical user interface and theme in most editions of Windows
Vista and 7) while connections are in progress. This may improve performance.
See also: DisableEffects, RemovePattern, RemoveWallpaper

DisableClose

FALSE

Specify TRUE to disable the Stop VNC Server option on the VNC Server shortcut menu, preventing either a host
computer or connected users stopping VNC Server via the user interface.
Note: VNC Server can still be stopped from the command line, or by (for example) using Control Panel >
Administrative Tools > Services under Windows.
See also: DisableTrayIcon, DisableClose, DisableOptions

DisableEffects

Windows

FALSE

Specify TRUE to disable particular graphical user interface effects such as font smoothing while connections are in
progress. This may improve performance.
See also: DisableAero, RemovePattern, RemoveWallpaper

DisableLocalInputs

Windows

FALSE

Specify TRUE to disable the keyboard and mouse of the host computer while connections are in progress, preventing a
host computer user interrupting connected users.
See also: AcceptKeyEvents

DisableOptions

FALSE

Specify TRUE to disable the Options option on the VNC Server shortcut menu, preventing either a host computer or
connected users configuring VNC Server via the user interface.
Note: VNC Server can still be configured from the command line.
See also: DisableAddNewClient, DisableClose, DisableTrayIcon

DisableTrayIcon

Specify one of the following values to control the appearance of the VNC Server icon in the notification tray (Windows
and UNIX) or on the Status Bar (Mac OS X):

0 to show the VNC Server icon at all times.

1 to hide the VNC Server icon while no connections are in progress, preventing a host computer user performing
certain operations via the user interface. The icon is shown when a connection is first established.

2 to hide the VNC Server icon permanently. This is effective only for OEM license keys.

See also: DisableAddNewClient, DisableClose, DisableOptions

158

VNC User Guide

Appendix C: VNC Parameters

DisconnectAction

Windows

None

VNC Server in Service Mode only. (Do not change this parameter for VNC Server in User Mode, or users will not be
able to reconnect.)
Specify one of the following values to determine the behavior of the host computer when the last user disconnects (or is
disconnected):

None to leave the host computer as is (that is, potentially with a user account logged on).

Lock to lock the host computer. A connection can immediately be re-established, but at least one connected user
must unlock the host computer in order to continue.

Logoff to log the current user account out. A connection can immediately be re-established, but at least one
connected user must log on to a user account in order to continue.

DisconnectClients

See AlwaysShared.

display

UNIX

NULL

Not available for VNC Server in Virtual Mode.

Specify the X Window display and optionally the screen number to remote to connected users, for example :1.0.
Note: This parameter overrides the DISPLAY environment variable.
See also: DisplayDevice, Monitor

DisplayDevice

Windows

Specify the name of a particular monitor or similar device attached to the host computer to remote to connected users,
for example \\.\Display1. Available names are shown on the Diagnostics page of the Information Center dialog.
Note: All existing connections must be terminated in order for a change to this parameter to take effect.
By default, or if the value is not recognized, all monitors are remoted.
See also: Monitor, display

EnableAutoUpdateChecks

Specify:

0 to prevent VNC Server automatically checking for critical software patches and product updates to which you are
entitled every UpdateCheckFrequencyDays.

1 to ensure VNC Server automatically checks.

By default, VNC Server prompts a host computer user to choose one of the above options the first time it runs.
See also: UpdateCheckFrequencyDays, EnableManualUpdateChecks

EnableChat

TRUE

Specify FALSE to prevent connected users participating in chat sessions.

VNC User Guide

159

Appendix C: VNC Parameters

EnableGuestLogin

FALSE

Specify TRUE to turn on the Guest Login option on the VNC Server icon shortcut menu, allowing particular connecting
users to bypass the VNC Server authentication scheme.
Note: This parameter is ignored if GuestAccess is set to 0.
See also: GuestAccess

EnableManualUpdateChecks

TRUE

Specify TRUE to disable the Check for updates option on the VNC Server shortcut menu, preventing either a host
computer or connected users checking for critical software patches or product updates.
See also: EnableAutoUpdateChecks

EnableRemotePrinting

TRUE

Specify FALSE to prevent connected users printing host computer files to their local printers.
See also: AllowChangeDefaultPrinter

GuestAccess

Determine whether users can connect as guests, bypassing the VNC Server authentication scheme. In addition, grant
VNC permissions to connected guests.
Note: For a value other than 0, EnableGuestLogin must also be set to TRUE.
Specify a value consisting of one or particular combinations of the following characters:

0 to prevent users connecting as guests, even if EnableGuestLogin is TRUE.

s to allow connected guests to view the desktop. Note that omitting this value means guests see a blank screen.

v to give connected guests a view-only set of permissions (equivalent to s in this release).

k to allow connected guests to exercise control using their keyboards (subject to AcceptKeyEvents).

p to allow connected guests to exercise control using their mice (subject to AcceptPointerEvents).

c to allow connected guests to copy and paste text between the computers (subject to SendCutText and
AcceptCutText).

t to allow connected guests to transfer files between the computers (subject to ShareFiles).

r to allow connected guests to print to local printers (subject to EnableRemotePrinting).

h to allow connected guests to chat (subject to EnableChat).

d to give connected guests a default set of permissions (equivalent to skpctrh).

q to allow connected guests to bypass connection prompts (subject to QueryConnect).

f to give connected guests a full set of permissions (equivalent to dq).

For example:
skpc
grants connected guests viewing (s), controlling (k and p), and copy and paste (c) permissions. The other permissions
are omitted, which means the corresponding features are not available.
See also: EnableGuestLogin

160

VNC User Guide

Appendix C: VNC Parameters

Hosts

Filter incoming connections by IPv4 address. Client computers can either be permitted to connect, be rejected, or be
flagged up for verification by a host computer (or an already-connected) user.
Note: The default + value permits connections from all client computers. Note that changing this default means users
will no longer be able to specify IPv6 addresses in order to connect (even if InTransports includes IPv6).
Specify an ordered, comma-separated list of actions and network addresses, each of the form:
<action><ip address-or-range>
where <action> is either:

+ to permit connections

- to reject connections

? to flag connections

and <ip address-or-range> is either a particular IPv4 address, or a range suffixed by a forward slash (/) and either a
subnet mask (for example 192.168.0.187/255.255.0.0) or the number of bits in the routing prefix (for example
192.168.0.187/24).
Consider the following example:
+192.168.0.1,?192.168.4.0/255.255.255.0,

The first entry permits connections from a client computer with the IP address 192.168.0.1.

The second entry flags connections from any client computer situated in the 192.168.4 subnet.

The third entry rejects connections from all other client computers.

To exclude particular addresses (or small ranges) from within an included range, add the address and suitable subnet
mask before the include entry and prefix with .
See also: InTransports, localhost

httpd

<platform-specific>

Specify a full path to a directory containing VNC Viewer for Java files. This may be useful if you wish to customize VNC
Viewer for Java, for example by changing the background web page or logo.
Note: This parameter is ignored unless AllowHTTP and AllowRFB are both TRUE.
To obtain VNC Viewer for Java files:

Under Mac OS X, navigate to /Library/vnc/java/.

Under UNIX, download VNC Viewer for Java from VNC Server and use web browser tools to save the downloaded
artifacts.

See also: AllowHTTP

HttpPort

5800

Specify a number between 1 and 65535 representing an available TCP port from which VNC Viewer for Java can be
downloaded from VNC Server. This can be the same as rfbPort, to simplify firewall and router configuration. Note that
ports 1 to 1024 are restricted by some operating systems.
Note: This parameter is ignored unless AllowHTTP and AllowRFB are TRUE.
See also: AllowHTTP

VNC User Guide

161

Appendix C: VNC Parameters

IdleTimeout

3600

Specify a number of seconds to wait before disconnecting users who have not interacted with the host computer during
that time.
Specify 0 to never disconnect idle users.
See also: DisconnectAction

InTransports

IPv6,IPv4

Specify either IPv4 or IPv6 to restrict VNC Server to connection requests framed using that version of the Internet
Protocol only.
Note that IPv6 connection requests are always rejected if the Hosts parameter is set to a value other than + (the
default).
See also: Hosts

KerberosPrincipalName

Mac OS X, UNIX

host/<computer name>

Specify the host service principle name as it is registered for the host computer with the domain controller, for example
host/<computer name>.dev.acmecorp.com.
Note: This parameter is ignored unless SecurityTypes includes at least one of SSO, SSOne.
This may be useful if connecting users are experiencing problems authenticating automatically to VNC Server. For more
information, see Setting up single sign-on authentication on page143.

LeftCmdKey

Mac OS X

Alt_L

Specify one of the following values to map a particular keysym received from client computers to the left Command key:
Alt_L, Alt_R, Super_L, Super_R, ExtendedChars
The default value of Alt_L means that, for connections from:

Windows or UNIX computers with PC keyboards, connected users can press the left Alt key to simulate a press of
the left Command key.

Mac computers, it is recommended you do not change this parameter unless you are also able to make the same
change to the VNC Viewer LeftCmdKey parameter, which by default maps the left Command key to the Alt_L
keysym.

Note that ExtendedChars refers to the key typically used to create extended characters, for example Alt Gr on non-US
PC keyboards.
Note: This parameter is ignored unless the AcceptKeyEvents parameter is set to TRUE.
See also: LeftOptKey, RightCmdKey, RightOptKey, AcceptKeyEvents

LeftOptKey
See LeftCmdKey, but for the left Option key.

162

VNC User Guide

Mac OS X

ExtendedChars

Appendix C: VNC Parameters

Locale
Specify one of the following values to choose a display language for VNC Server:

en_US (English)

fr_FR (French)

de_DE (German)

es_ES (Spanish)

By default, this parameter is empty, and the VNC Server user interface inherits the desktop language of the currently
logged-on computer user, or falls back to English if this language has not yet been translated.
There are two aspects to the display language; specifying this parameter in different locations enables these aspects to
be controlled separately (if required):

The language in which the VNC Server user interface is displayed. Note VNC Server must be restarted in order for
any change to take effect.

The language in which connectivity and other messages are transmitted to VNC Viewer users.

To change the user interface language, specify the Locale parameter:

Under Windows, in the Software\RealVNC\vncserverui-service (Service Mode) or

Software\RealVNC\vncserverui-user (User Mode) Registry key. Note these keys are both in the
HKEY_CURRENT_USER hive.

Under UNIX, in the vncserverui-service (Service Mode), vncserverui-user (User Mode), or

vncserverui-virtual (Virtual Mode) VNC configuration file. You can create these files if they do not exist in any
appropriate location in this table on page132.

Under Mac OS X, in the vncserverui-service (Service Mode) or vncserverui-user (User Mode) VNC
configuration file. You can create these files if they do not exist in any appropriate location in this table on page133.

To change the language of transmitted messages, you can either edit the Locale parameter in the Expert tab of the
VNC Server Options dialog box, or alternatively specify it:

Under Windows, in the HKEY_LOCAL_MACHINE\Software\RealVNC\vncserver (Service Mode) or

HKEY_CURRENT_USER\Software\RealVNC\vncserver (User Mode) Registry key.

Under UNIX, in the /root/.vnc/config.d/vncserver-x11 (Service Mode), ~/.vnc/config.d/

vncserver-x11 (User Mode), or ~/.vnc/config.d/Xvnc (Virtual Mode) VNC configuration file.

Under Mac OS X, in the /var/root/.vnc/config.d/vncserver (Service Mode) or ~/.vnc/config.d/

vncserver (User Mode) VNC configuration file.

Note: Under UNIX and Mac OS X, you can configure both language aspects together (and for all applications) by
specifying the Locale parameter in a global location such as /etc/vnc/config.d/common.custom.

localhost

FALSE

Specify TRUE to permit only connections from VNC Viewer running on the same computer as VNC Server.
See also: Hosts

VNC User Guide

163

Appendix C: VNC Parameters

Log

<platform-specific>

Record information about the main VNC Server process.

Note: It is possible to record information about sub-processes, for example the VNC Server service under Windows.
See Logging information on page148 for more information.
Specify an ordered, comma-separated list of activities, each of the form:
<log>:<target>:<level>
where:

<log> determines the type of activity to record, for example connection, printing or file transfer activity, or * to record
all. To see a list of available logs, examine the Log names section in the advanced help output (run the command
<application> -help all; see VNC Server at the command line on page190 for platform-specific information).

<target> determines the output destination:

Under Windows, either stderr, file (see the LogDir and LogFile parameters), or EventLog (to write to
the Windows Event Log service).
Under Mac OS X and UNIX, either stderr or file.

<level> determines severity: 0 includes only serious errors, 10 includes basic audit information, 30 includes general
information, and 100 includes all possible information, potentially including keystrokes.

Consider the following example:

*:file:10,Connections:file:100

The first entry (*:file:10) specifies that all activity is recorded to file at level 10.

The second entry (Connections:file:100) overrides this for connection activity, recording it (to the same file) at
level 100.

See also: LogDir, LogFile

LogDir

<platform-specific>

Specify a directory in which VNC Server should create a log file. This location must be writable.
Note: This parameter is ignored unless at least one Log entry has an output destination of file.
For example, under Windows:
X:\my\file\server\realvnc\logs\${COMPUTERNAME}\vncserver
specifies a file share mapped to drive X, and distinguishes the name of the originating computer.
See also: Log

LogFile

<platform-specific>

Specify a name for the file VNC Server should create in LogDir, for example realvnc-debug.log.
Note: This parameter is ignored unless at least one Log entry has an output destination of file.
See also: Log

164

VNC User Guide

Appendix C: VNC Parameters

Monitor

Mac OS X

-1

Specify the number of a particular monitor or similar device attached to the host computer to remote to connected users,
for example 0 for the primary monitor, 1 for a secondary monitor, and so on.
Note: All existing connections must be terminated in order for a change to this parameter to take effect.
By default, or if the value is not recognized, all monitors are displayed.
See also: DisplayDevice, display

NeverShared

FALSE

See AlwaysShared.

NtLogonAsInteractive

Windows

FALSE

Specify TRUE to establish connections as Interactive logon type 2 rather than Network logon type 3.
Note: This parameter is ignored unless system authentication is specified (that is, UserPasswdVerifier is set to
NtLogon).
This may be useful if user accounts valid for logging on to the host computer (and whose credentials are supplied in
order to connect to VNC Server) are not accorded the higher privileges of the Network logon type, and would
consequently be rejected. Alternatively, if network access to a domain controller cannot be guaranteed, connections
may be more reliable since the Interactive logon type caches credentials.
See also: UserPasswdVerifier, Permissions

PamAccountCheck

UNIX, Mac OS X

TRUE

Specify FALSE to check just PAM authentication rules. By default, PAM account rules are checked as well.
Note: This parameter is ignored unless system authentication is specified (that is, UserPasswdVerifier is set to
UnixAuth).
This may be useful if connecting users are experiencing problems authenticating to VNC Server, since account rule
checks must be run as root.
See also: PamApplicationName, UserPasswdVerifier

PamApplicationName

UNIX, Mac OS X

vncserver

Specify vncserver.custom to use the custom PAM library and authentication and account rules specified:

Under modern versions of Linux and Mac OS X, in the /etc/pam.d/vncserver.custom file.

Under Solaris, HP-UX, and older versions of Linux, by lines starting vncserver.custom in the /etc/pam.conf
file.

Note: This parameter is ignored unless system authentication is specified (that is, UserPasswdVerifier is set to
UnixAuth).
Under UNIX, this may be useful to enable connecting users to authenticate to VNC Server using the credentials of
domain accounts. See Managing system authentication on page141 for more information.
See also: PamAccountCheck, UserPasswdVerifier

VNC User Guide

165

Appendix C: VNC Parameters

Permissions

<platform-specific>

Register user accounts or groups with VNC Server so connecting users can authenticate using familiar, securelymanaged system credentials. In addition, grant VNC permissions to use remote control features while connections are
in progress. For more information on domain accounts under UNIX, see Managing system authentication on page141.
Note: This parameter is ignored unless system authentication (see the UserPasswdVerifier parameter) or single
sign-on (see Setting up single sign-on authentication on page143) is specified.
Note: A utility is available to create a permissions string in the correct format for VNC Server; visit www.realvnc.com/
products/vnc/deployment/acl-creator/ for more information.
Specify a comma-separated list of users/groups and permissions, each of the form:
<name>:<feature>
where <name> is the user name of a valid user account, preceeded by % to distinguish a group, and <access> is a
string consisting of particular combinations of at least one of the following characters:

s to allow connected users to view the desktop. Note that omitting this value means users see only a blank screen.

v to give connected users a view-only set of permissions (equivalent to s in this release).

k to allow connected users to exercise control using their keyboards (subject to AcceptKeyEvents).

p to allow connected users to exercise control using their mice (subject to AcceptPointerEvents).

c to allow connected users to copy and paste between computers (subject to SendCutText/AcceptCutText).

t to allow connected users to transfer files between the computers (subject to ShareFiles).

r to allow connected users to print to local printers (subject to EnableRemotePrinting).

h to allow connected users to chat (subject to EnableChat).

d to give connected users a normal set of permissions (equivalent to skpctrh).

q to allow connected users to bypass connection prompts (subject to QueryConnect).

f to give connected users an administrative set of permissions (equivalent to dq).

Note: Under UNIX and Mac OS X, you can omit <name> to infer the VNC Server process owner (User Mode and
Virtual Mode) or the root user account (Service Mode). Under Windows, you can use the built-in CREATOR OWNER user
to infer the VNC Server process owner (User Mode) or the currently-logged on user account (Service Mode).
Note that specifying a character corresponds to turning the Allow checkbox on for that feature on the Users &
Permissions page of the VNC Server Options dialog box. Other behaviors can be modelled as follows:

Omit a character to disallow that feature, corresponding to turning the Allow checkbox off. Note that for a group, this
can be overridden by individual members. Alternatively, specify -<feature> to disallow that feature from a set, so for
example johndoe:d-t grants a normal set of permissions, with the exception of file transfer.

! to explicitly deny a feature, corresponding to turning the Deny checkbox on. This cannot be overridden.

Note that if you use - (to disallow) and ! (to deny) then the order of characters must be allow > disallow > deny.
Consider the following example:
superuser:f,%vncusers:d,johndoe:v,janedoe:skp-t!r

The superuser user account grants an administrative set of permissions.

The vncusers group grants a normal set of permissions.

The johndoe user account grants view-only permissions (assuming johndoe is not a member of vncusers).

The janedoe user account grants viewing (s) and controlling permissions (k and p), disallows file transfer, and
explicitly denies printing. No position is taken on copy and paste (c) or chat (h). If janedoe is a member of
vncusers, then any grant of these permissions is inherited, and those two features are allowed. If janedoe is not
a member of vncusers, then these features are disallowed.

166

VNC User Guide

Appendix C: VNC Parameters

PollInterval

UNIX

50

Not available for VNC Server in Virtual Mode.

Specify a number of milliseconds to wait before polling the display system for screen updates. A larger number may
improve performance, at a potential risk of increasing latency.
Note: This parameter is ignored unless UpdateMethod is 0.
See also: UpdateMethod

ProtocolVersion

NULL

Specify one of the following values to compel VNC Server to advertize only that version or lower of the underlying RFB
protocol:
3.3, 3.7, 3.8, 4.0, 4.1
The lower the version, the wider the range of VNC-compatible Viewer technology from third parties able to connect, but
the fewer the premium features (such as encryption, file transfer, printing, and chat) available to connected users.
By default, the latest version of the RFB protocol is advertized.

QueryConnect

FALSE

Specify TRUE to display connection prompts when particular users connect. If present, a host computer (or an alreadyconnected) user can choose to accept connections, make connections view only, or reject them. If no user is present,
connections are automatically granted QueryTimeoutRights after QueryConnectTimeout.
Note: Some users may have sufficient VNC permissions to bypass connection prompts.
See also: QueryConnectTimeout, QueryOnlyIfLoggedOn, QueryTimeoutRights

QueryConnectTimeout

10

Specify a number of seconds to display connection prompts for. If no response is received from a host computer (or an
already-connected) user during this time, connections are automatically granted QueryTimeoutRights.
See also: QueryConnect, QueryTimeoutRights

QueryOnlyIfLoggedOn

FALSE

Not available for VNC Server in User Mode. It is also not recommended for VNC Server in Service Mode under Mac OS
X in this release.
Specify TRUE to display connection prompts only if a user account is currently logged on, and therefore a host computer
user is likely to be present. (For VNC Server in Virtual Mode under UNIX, the equivalent is if at least one user is already
connected, since no host computer user can be present at a virtual desktop.)
Note: This parameter is ignored unless QueryConnect is TRUE.
If no user account is logged on (or if no user is connected in Virtual Mode), connection prompts are not displayed and
all connections are automatically granted QueryTimeoutRights.
See also: QueryConnect, QueryTimeoutRights

VNC User Guide

167

Appendix C: VNC Parameters

QueryTimeoutRights

NULL

Determine whether connections exceeding QueryConnectTimeout are accepted or rejected, and grant VNC
permissions to connected users.
Note: This parameter is ignored unless QueryConnect is TRUE.
Specify a value consisting of one or particular combinations of the following characters:

A null value (QueryTimeoutRights=) to reject connections.

s to allow connected users to view the desktop. Note that omitting this value means users see a blank screen.

v to give connected users a view-only set of permissions (equivalent to s in this release).

k to allow connected users to exercise control using their keyboards (subject to AcceptKeyEvents).

p to allow connected users to exercise control using their mice (subject to AcceptPointerEvents).

c to allow connected users to copy and paste text between computers (subject to SendCutText and
AcceptCutText).

t to allow connected users to transfer files between computers (subject to ShareFiles).

r to allow connected users to print to local printers (subject to EnableRemotePrinting).

h to allow connected users to chat (subject to EnableChat).

d to give connected users a default set of permissions (equivalent to skpctrh).

For example:
skpc
grants connected guests viewing (s), controlling (k and p), and copy and paste (c) permissions. The other permissions
are omitted, which means the corresponding features are not available.
See also: QueryConnect, QueryOnlyIfLoggedOn

QuitOnCloseStatusDialog

FALSE

Specify TRUE to stop VNC Server if a host computer (or a connected) user closes the VNC Server dialog.
By default, closing merely hides the dialog; it can be shown again from the VNC Server icon under most operating
systems.

RandR

UNIX

NULL

VNC Server in Virtual Mode only.

Specify a comma-separated list of geometries to offer the RandR X Window extension, if enabled.
For example, specifying 1024x768,1280x1024,800x600 enables a connected user to cycle between the three
geometries by running the command xrandr -s <0|1|2>.

168

VNC User Guide

Appendix C: VNC Parameters

RemapKeys

UNIX

NULL

Map or swap keyboard keys. This may be useful if client computer keyboards are likely to be different to the host
computer keyboard.
Specify a comma-separated list of X Window hexadecimal keysyms, either of the form:

<keysym><><keysym> to swap keysyms, for example 0x22<>0x40 to swap " and @.

<keysym>-><keysym> to map from the first keysym to the second, for example
0x6d->0x6e to cause m to be interpreted as n.

See also: AcceptKeyEvents

RemovePattern

Windows

FALSE

Specify TRUE to replace a repeating pattern on the host computers desktop (under old versions of Windows) with a
plain background while a connection is in progress. This may improve performance.
See also: RemoveWallpaper, DisableAero, DisableEffects

RemoveWallpaper

Windows

FALSE

Specify TRUE to replace a picture or photo on the host computers desktop with a plain background while a connection
is in progress. This may improve performance.
See also: RemovePattern, DisableAero, DisableEffects

ReverseSecurityTypes

RA2

Determine (in conjunction with VNC Viewer) whether reverse connections are encrypted or not.
For more information, and a list of valid security types, see SecurityTypes.
See also: SecurityTypes, DisableAddNewClient

RfbPort

5900

Specify a number between 1 and 65535 representing an available TCP port on which VNC Server can listen for
connection requests. This can be the same port as httpPort, to simplify firewall and router configuration. Note that
ports 1 to 1024 are restricted by some operating systems.
Note: This parameter is ignored if AllowRFB is FALSE.
Note that the default port, 5900, is registered for use by VNC Server with the Internet Assigned Numbers Authority
(IANA), and does not need to be explicitly identified by connecting users.
See also: AllowRFB, httpPort

RightCmdKey

Mac OS X

Super_L

Mac OS X

ExtendedChars

See LeftCmdKey, but for the right Command key.

RightOptKey
See LeftCmdKey, but for the right Option key.

VNC User Guide

169

Appendix C: VNC Parameters

RootSecurity

UNIX, Mac OS X

FALSE

Not available for VNC Server in Service Mode.

Specify TRUE to protect the system credentials of connecting users from observation by a VNC Server process owner
who is not root.
See also: SecurityTypes

RsaPrivateKeyFile

UNIX, Mac OS X

$HOME/.vnc/private.key

Specify the full path to a file storing a private key for VNC Server.
Note: VNC Server in Service Mode runs as the root user.
If the private key is missing or corrupt, users cannot connect. To generate a new private key, stop and restart VNC
Server.
See also: SecurityTypes

SecurityTypes

<platform-specific>

If VNC Server has an Enterprise or a Personal license, determine, in conjunction with VNC Viewer, whether:

Connections are encrypted end-to-end.

The exchange of authentication credentials is encrypted, but subsequent connections are not. This means data
transmitted while connections are in progress may be susceptible to interception by a third parties.

Note: If VNC Server has a Free license, connections cannot be encrypted. Authentication credentials, however, are
protected by a challenge-response mechanism.
From the table below, specify the ordered, comma-separated combination of security types appropriate to the level of
encryption you wish to offer, for the authentication scheme you have chosen (see the UserPasswdVerifier
parameter). For each connection request, VNC Server offers security types in left-to-right order; VNC Viewer selects the
first that accords with the preferences set by the connecting user (see the VNC Viewer Encryption parameter).
Note: Certain security types prevent connections from earlier versions of VNC Viewer (and VNC-compatible Viewer
technology from third parties).
Authentication
scheme

Encryption
preference

Security types

Reverse security types

System authentication

Always maximum

RA2:256+

RA2:256+

Always on

RA2

RA2

Prefer on

RA2,RA2ne

RA2,RA2ne,None

Prefer off

RA2ne,RA2

RA2ne,None,RA2

Always maximum

SSO:256+,RA2:256+

RA2:256+

Always on

SSO,SSPI,RA2

RA2

Prefer on

SSO,SSPI,RA2,SSOne,SSPIne,RA2ne RA2,RA2ne,None

Prefer off

SSOne,SSPIne,RA2ne,SSO,SSPI,RA2 RA2ne,None,RA2

Single sign-on

170

VNC User Guide

Appendix C: VNC Parameters

Authentication
scheme

Encryption
preference

Security types

Reverse security types

VNC password

Always maximum

RA2:256+

RA2:256+

Always on

RA2

RA2

Prefer on

RA2,RA2ne,VncAuth

RA2,RA2ne,None

Prefer off

RA2ne,VncAuth,RA2

RA2ne,None,RA2

Always maximum

RA2:256+

RA2:256+

Always on

RA2

RA2

Prefer on

RA2,RA2ne,None

RA2,RA2ne,None

Prefer off

RA2ne,None,RA2

RA2ne,None,RA2

None

It is possible to specify a custom set of security types, in different combinations to those listed in the table above. Note
the following classifications:

Any security type incorporating ne (no encryption) signifies that the exchange of authentication credentials will be
encrypted, but subsequent connections are not.

VncAuth signifies that authentication is managed by a challenge-response mechanism, offering a measure of

protection for credentials. Although it is offered when VNC authentication is specified, it can only ever be chosen
when VNC Server has a Free license.

None signifies that authentication credentials will not be exchanged, and subsequent connections are not
encrypted.

SSPI and SSPIne have been superceded by SSO and SSOne respectively. There is no need to specify these
security types when using VNC Server and VNC Viewer 5.x.

All other security types signify that both the exchange of authentication credentials and subsequent connections will
be encrypted using at least 128-bit AES.

As an example, consider the default security types for VNC Server set to use system authentication and with an
encryption preference of prefer on:
RA2,RA2ne
If a VNC Viewers Encryption parameter is set to:

AlwaysMaximum, connections are encrypted end-to-end and upgraded to 256-bit AES, providing VNC Server has
an Enterprise license. (Note connections to VNC Server with a Personal license cannot be established.)

AlwaysOn or PreferOn, connections are encrypted end-to-end using at least 128-bit AES.

PreferOff, the exchange of authentication credentials is encrypted using at least 128-bit AES (that is, VNC
Viewer chooses the RA2ne security type), but subsequent connections are not encrypted.

See also: UserPasswdVerifier, ReverseSecurityTypes, RsaPrivateKeyFile

SendCutText

TRUE

Specify FALSE to prevent connected users copying text on the host computer and pasting it to their client computers.
See also: AcceptCutText, ClipboardFT

ServiceDiscoveryEnabled

TRUE

Specify FALSE to prevent VNC Server automatically advertizing itself on Zeroconf-enabled local networks (for example,
Bonjour or Avahi).

VNC User Guide

171

Appendix C: VNC Parameters

ShareFiles

TRUE

Specify FALSE to prevent connected users exchanging files with the host computer.
See also: ClipboardFT

SimulateSAS

Windows

VNC Server in Service Mode only.

Specify one of the following values to determine whether connected users can send the Secure Attention Sequence
(SAS, the Ctrl-Alt-Del key combination) to a host computer running Windows Vista or 7:

0 to respect Windows group policy for SAS, which means that it cannot be sent to host computers running most
versions of Windows Vista and 7.

1 to override group policy if it has not been explicitly set, which means SAS can be sent in most circumstances.

2 to override group policy even if it has been explicitly set, which means SAS can always be sent.

See also: AcceptKeyEvents

StartUI

UNIX

TRUE

VNC Server in Virtual Mode only.

Specify FALSE to suppress the display of the VNC Server status dialog and notification icon.

StopUserModeOnSwitchOut

Mac OS X

TRUE

VNC Server in User Mode only.

Specify FALSE to keep VNC Server running when the current user account switches out. Note that not all third party
applications may be displayed correctly to connected users in switched out sessions, for example Calculator.
By default, VNC Server stops on switch out, and all users are disconnected and cannot reconnect.

UpdateCheckFrequencyDays
Specify a number of days to wait before VNC Server automatically checks for critical software patches and product
updates to which you are entitled.
Note: This parameter is ignored unless EnableAutoUpdateChecks is TRUE.

172

VNC User Guide

Appendix C: VNC Parameters

UpdateMethod

Windows, UNIX

<platform-specific>

Not available for VNC Server in Virtual Mode under UNIX.

Specify one of the values in the appropriate section below to determine the method used by VNC Server to monitor
changes to the host computer desktop, in order to send screen updates to VNC Viewer. Note that all connections must
be terminated before changes to this parameter take effect.
Windows

0 to poll the display system for changes to the entire desktop. This may be the slowest method, but can be useful to
track changes to applications that interface directly with the graphics card, for example some DirectX applications.

1 to use application hooks to monitor messages sent to ascertain whether application content has changed. Note
this method is not effective under Windows Vista onwards; 2 is automatically selected (if possible), else 0.

2 to use VNC Mirror Driver, if it is installed for VNC Server in Service Mode, under all platforms except NT4 and
Windows 8/Server 2012. Note that for VNC Server in User Mode, this method is not effective and 1 is automatically
selected (if possible), else 0.
This method causes graphical updates to be mirrored to a secondary driver and is typically quick and effective,
though it may not capture some DirectX or OpenGL applications, nor interface correctly with some graphics cards.

UNIX

0 to poll the display system for changes to the entire desktop. This may be the slowest option, but can be useful to
track changes to applications that interface directly with the graphics card, for example some DirectX applications.

1 to use the X Window Damage extension if it is enabled and working. If it is not working (which may be the case
under some platforms), 0 is automatically selected.

2 to always use the Damage extension if it is enabled; if not, 0 is automatically selected.

See also: UseCaptureBlt, PollInterval

UseCaptureBlt

Windows

TRUE

Specify FALSE to stop VNC Server monitoring updates to some semi-transparent windows such as certain menus and
tooltips. This may improve performance or reduce cursor flicker but does mean connected users do not have perfect
picture fidelity.
See also: UpdateMethod

UsePam

UNIX

FALSE

Only available under AIX.

Specify TRUE to use PAM instead of LAM to authenticate connecting users. Note this parameter is ignored unless
system authentication (see the UserPasswdVerifier parameter) or single sign-on (see Setting up single sign-on
authentication on page143) is specified.
See also: PamApplicationName, PamAccountCheck

VNC User Guide

173

Appendix C: VNC Parameters

UserPasswdVerifier

<platform-specific>

Specify at least one of the following values to determine the authentication scheme:

NtLogon (Windows) or UnixAuth (Mac OS X, UNIX) to specify system authentication, which means that users
can connect by supplying the credentials of user accounts (local or domain) registered with the Permissions
parameter. Note that an Enterprise or a Personal license is required. For more information on domain accounts
under UNIX, see Managing system authentication on page141.

VncAuth to specify VNC authentication, which means that users can connect by supplying password(s) set directly
in the Windows Registry or in VNC configuration files by the vncpasswd utility. Run the command vncpasswd help for more information.

None to disable authentication, which means that users can connect without having to supply a password.

Note: The SecurityTypes parameter must be set to a value or combination of values appropriate to the
authentication scheme.
Note that a comma-separated list of values can be specified in order to determine a fallback scheme. Consider the
following example:
NtLogon,VncAuth
This means that, if system authentication fails for any reason, VNC authentication is enforced.
To specify the single sign-on authentication scheme, set the SecurityTypes parameter to include a SS* security type
and, under UNIX and Mac OS X, create an /etc/vnc/ssolib symlink as described in the section Setting up single
sign-on authentication on page143. The value of UserPasswdVerifier is then used as the fallback authentication
scheme if single sign-on fails for any reason (see, for example, the VNC Viewer SingleSignOn parameter).
See also: SecurityTypes

WorkaroundXlibXkbBug

UNIX

VNC Server in Virtual Mode only.

Please do not change this parameter unless directed to do so by Technical Support.

174

VNC User Guide

TRUE

Appendix C: VNC Parameters

VNC Viewer parameters

This section explains the VNC Viewer parameters available on the Expert tab of the Options dialog.
Key:
Parameter name

Platform(s), unless all

Default value

Explanatory text: note that all parameters are case-insensitive, for all platforms.
See also: Related parameters...

Note that:

VNC Viewer parameters may be overridden by VNC Server parameters; this is clearly stated.

Changes made in the Expert tab take effect when the OK button is clicked, unless otherwise stated.
AcceptBell

TRUE

Specify FALSE to suppress system beeps produced by the host computer.

AutoReconnect

TRUE

Specify FALSE to prevent VNC Viewer 5.0+ automatically reconnecting to VNC Server in certain circumstances, for
example if the current user account is logged or switched out.

AutoSelect

TRUE

Specify FALSE to request that VNC Server send screen updates using PreferredEncoding and ColorLevel.
By default, an encoding and pixel format is automatically chosen to suit the speed of the network connection.
See also: PreferredEncoding, ColorLevel, FullColor

AutoSelectLossy

TRUE

Specify FALSE to prevent lossy encodings (such as JPEG and JRLE) being requested when AutoSelect is TRUE.
This may be useful if perfect picture fidelity is required.

ChangeServerDefaultPrinter

TRUE

Specify FALSE to not change the default printer of a host computer. A connected user must explicitly select a VNC
printer at print-time.
By default, the host computers default printer is changed to that of the first client computer that connects.
Note: This parameter is ignored unless the EnableRemotePrinting parameter and the VNC Server
AllowChangeDefaultPrinter and EnableRemotePrinting parameters are all set to TRUE.
See also: EnableRemotePrinting

ClientCutText

TRUE

Specify FALSE to prevent a connected user pasting text to the host computer.
Note: This parameter is ignored unless the VNC Server AcceptCutText parameter is set to TRUE.
See also: ServerCutText

VNC User Guide

175

Appendix C: VNC Parameters

ColorLevel (ColourLevel)

pal8

Specify one of the following values to determine the picture quality of the host computer desktop:

rgb111 to use 8 colors

rgb222 to use 64 colors

pal8 to use 256 colors

full to use full color

Using more colors gives a better user experience, at a potential cost in performance.
Note: This parameter is ignored if either FullColor or AutoSelect is set to True.
See also: FullColor, AutoSelect

DisableOptionsModeSwitch

FALSE

Specify FALSE to lock down the Options dialog box, preventing a user switching between Basic and Advanced tabs.

DotWhenNoCursor

TRUE

Specify FALSE to not show a local cursor if an application running on the host computer is set to show an invisible
cursor.
By default, VNC Viewer displays a dot cursor in this circumstance.
Note: This parameter is ignored unless the SendPointerEvents parameter and the VNC Server
AcceptPointerEvents parameter are both set to TRUE.
See also: SendPointerEvents

Emulate2

Mac OS X

FALSE

Specify TRUE if the client computers mouse has one button but the mouse attached to the host computer has two.
A connected user can emulate the missing button by holding down the Ctrl key while clicking.
Note: This parameter is ignored unless the SendPointerEvents parameter and the VNC Server
AcceptPointerEvents parameter are both set to TRUE.
See also: Emulate3, SendPointerEvents

Emulate3

FALSE

Specify TRUE if the client computers mouse has two buttons but the mouse attached to the host computer has three.
A connected user can emulate the missing middle button by clicking the left and right buttons simultaneously.
Note: This parameter is ignored unless the SendPointerEvents parameter and the VNC Server
AcceptPointerEvents parameter are both set to TRUE.
See also: Emulate2, SendPointerEvents

EnableChat
Specify FALSE to prevent a connected user participating in a chat session.
Note that the user can still view chat messages exchanged by other users connected at the same time.
Note: This parameter is ignored unless the VNC Server EnableChat parameter is set to TRUE.

176

VNC User Guide

TRUE

Appendix C: VNC Parameters

EnableRemotePrinting

TRUE

Specify FALSE to prevent a connected user printing a host computer file to a local printer.
Note: This parameter is ignored unless the VNC Server EnableRemotePrinting parameter is set to TRUE.
See also: ChangeServerDefaultPrinter

EnableToolbar

TRUE

Specify FALSE to disable the toolbar, preventing a connected user performing key operations.
See also: MenuKey, ToolbarIconSize

Encryption

Server

For connections to VNC Server with an Enterprise or a Personal license, determine, in conjunction with VNC Server,
whether:

Connections are encrypted end-to-end.

The exchange of authentication credentials is encrypted, but the subsequent connections themselves are not. This
means data transmitted while connections are in progress may be susceptible to interception by third parties.

Note: Connections to VNC Server with a Free license cannot be encrypted. Authentication credentials, however, are
protected by a challenge-response mechanism. Note this parameter must not be set to AlwaysMaximum or AlwaysOn;
see Connectivity and feature matrix on page13 for more information.
Specify one of the following values:

Server to let VNC Server choose. By default, connections will always be encrypted end-to-end unless VNC
Servers encryption preference is set to prefer off (see the VNC Server SecurityTypes parameter).

AlwaysMaximum to request that connections be encrypted end-to-end using 256-bit AES. This request is always
granted for connections to VNC Server with an Enterprise license. Do not specify this value for connections to VNC
Server with a Personal or a Free license.

AlwaysOn to request that connections be encrypted end-to-end using at least 128-bit AES. This request is always
granted for connections to VNC Server with an Enterprise or a Personal license. Do not specify this value for
connections to VNC Server with a Free license.

PreferOn to prefer that connections be encrypted end-to-end using at least 128-bit AES. This request is always
granted for connections to VNC Server with an Enterprise or a Personal license.

PreferOff to prefer that the exchange of authentication credentials be encrypted using at least 128-bit AES, but
that connections themselves need not be encrypted. This may improve performance. This request is always granted
providing VNC Servers encryption preference is set to prefer on or prefer off.

Note: The rules above apply providing the VNC Server SecurityTypes parameter is set to the default values for its
authentication scheme and encryption preference. If the SecurityTypes parameter has custom values, arbitrary
rules apply.
See also: SecurityNotificationTimeout, WarnUnencrypted, RsaPrivateKeyFile

VNC User Guide

177

Appendix C: VNC Parameters

FetchDir

<platform-specific>

Specify a full path to a directory to which files transfered from the host computer are downloaded, for example
"C:\Users\johndoe\My Documents".
By default, files are downloaded:

Under Windows and UNIX, to a userss Desktop directory.

Under Mac OS X, to a users Downloads directory.

See also: ShareFiles

FullColor (FullColour)

FALSE

Specify TRUE to display the host computers desktop in full color. Note that using more colors gives a better user
experience, at a potential cost in performance.
Note also that:

When set to TRUE, this parameter overrides ColorLevel.

This parameter is ignored if AutoSelect is TRUE.

See also: ColorLevel, AutoSelect

FullScreen

FALSE

Specify TRUE to display the VNC Viewer application window in full screen mode.
Note that scrollbars are not displayed if the host computers desktop is larger than the application window; a connected
user must bump the mouse against an edge to scroll.
See also: FullScreenChangeResolution, UseAllMonitors

FullScreenChangeResolution

Windows, Mac OS X

FALSE

Specify TRUE to change the client computers screen resolution to that of the host computer when the VNC Viewer
application window is in full screen mode.
See also: FullScreen, UseAllMonitors

GrabKeyboard

UNIX

Specify one of the following values to determine whether VNC Viewer monopolizes the client computers keyboard,
preventing other applications receiving keyboard input.

0 to never grab the keyboard.

1 to grab the keyboard when the VNC Viewer application window is in full screen mode.

2 to always grab the keyboard.

HideCloseAlert

FALSE

Specify TRUE to close VNC Viewer silently if a user is disconnected unexpectedly, perhaps because VNC Server has
stopped. Use in conjunction with AutoReconnect set to FALSE in order to exit VNC Viewer cleanly if run from a script.
By default, a newly-disconnected user is informed of the reason in a message box that must be acknowledged before
VNC Viewer can close.

178

VNC User Guide

Appendix C: VNC Parameters

Identities

Mac OS X, UNIX

$HOME/.vnc/identities

Specify a path to a file storing signatures uniquely identifying instances of VNC Server already connected to.
Depending on the value of VerifyID, a connecting user is warned if a VNC Server signature is new or has changed,
which might help prevent connections to unintended or illegitimate destinations.
See also: VerifyID

InterpretDeadKeys

UNIX

FALSE

Specify TRUE to compose a character from a dead key and the key-to-be-modified before sending the combination to
VNC Server. This may be useful for connections to host computers that cannot natively compose particular symbols.
By default, the dead key and the key-to-be-modified are sent as separate key presses.
Note: This parameter is ignored unless the SendKeyEvents parameter and the VNC Server AcceptKeyEvents
parameter are both set to TRUE.
See also: SendKeyEvents

InTransports

IPv6,IPv4

Specify either IPv4 or IPv6 to restrict Listening VNC Viewer to connection requests from VNC Server framed using
that version of the Internet Protocol only.

LeftCmdKey

Mac OS X

Alt_L

Specify one of the following values to send a particular keysym to the host computer when the left Command key is
pressed:
Alt_L, Alt_R, Super_L, Super_R, ExtendedChars
By default, for a connection to a:

Windows or UNIX computer with a PC keyboard, the left Alt key is simulated, which means that pressing left
Command+F has the effect of opening the File menu on most Windows applications.

Mac computer, it is recommended you do not change this parameter unless you are also able to make the same
change to the VNC Server LeftCmdKey parameter, which by default maps the Alt_L keysym back to the left
Command key.

Note that ExtendedChars refers to the key typically used to create extended characters, for example Alt Gr on non-US
PC keyboards.
Note: This parameter is ignored unless the SendKeyEvents parameter and the VNC Server AcceptKeyEvents
parameter are both set to TRUE.
See also: LeftOptKey, RightCmdKey, RightOptKey, SendKeyEvents

LeftOptKey

Mac OS X

ExtendedChars

See LeftCmdKey, but for the left Option key.

VNC User Guide

179

Appendix C: VNC Parameters

Locale
Specify one of the following values to choose a display language:

en_US (English)

fr_FR (French)

de_DE (German)

es_ES (Spanish)

By default, this parameter is empty, and the VNC Viewer user interface inherits the desktop language of the currently
logged-on computer user, or falls back to English if this language has not yet been translated. Note VNC Viewer must
be restarted for any change to this parameter to take effect.
Note: Some messages are transmitted by VNC Server and thus may appear in a different language. See the VNC
Server Locale parameter for more information.

Log

*:stderr:0

Specify an ordered, comma-separated list of activities to record, each of the form:

<log>:<target>:<level>
where:

<log> determines the type of activity to record, for example connection, printing or file transfer activity, or * to record
all. To see a list of available logs, examine the Log names section in the advanced help output (run the command
<application> -help all; see VNC Viewer at the command line on page192 for platform-specific information).

<target> determines the output destination: either stderr (the default) or file (see the LogDir and LogFile
parameters).

<level> determines severity: 0 includes only serious errors, 10 includes basic audit information, 30 includes general
information, and 100 includes all possible information, potentially including keystrokes.

Consider the following example:

*:file:10,CConnection:file:100

The first entry (*:file:10) specifies that all activity is recorded to file at level 10.

The second entry (CConnection:file:100) overrides this for connection activity, recording it (to the same file) at
level 100.

See also: LogDir, LogFile

LogDir

<platform-specific>

Specify a directory in which VNC Viewer should create a log file. This location must be writable.
Note: This parameter is ignored unless at least one Log entry has an output destination of file.
For example, under Windows:
X:\my\file\server\realvnc\logs\${COMPUTERNAME}\vncviewer
specifies a file share mapped to drive X, and distinguishes the name of the originating computer.
See also: Log

180

VNC User Guide

Appendix C: VNC Parameters

LogFile

<platform-specific>

Specify a name for the file VNC Viewer should create in LogDir, for example "realvnc debug.log".
Note: This parameter is ignored unless at least one Log entry has an output destination of file.
See also: Log

MenuKey

F8

Specify a function key in the range F1 to F12 to raise the shortcut menu when the VNC Viewer application window has
focus.
Specify null (-menukey=) to disable the shortcut menu, preventing a connected user performing particular operations.
See also: EnableToolbar

Monitor

Windows

NULL

Specify a monitor attached to the client computer to display the VNC Viewer application window on, for example
\\.\DISPLAY2.
By default, or if the specified value is not recognized, VNC Viewer is displayed on the primary monitor (equivalent to
\\.\DISPLAY1).
See also: UseAllMonitors

MRUEntries

Windows

20

Specify the maximum number of host computer network addresses to remember, or 0 to remember no addresses.
This most recently used list is available to a connecting user from the VNC Server dropdown of the VNC Viewer
dialog.

PointerCornerSnapThreshold

30

Specify a number of pixels from each corner of the VNC Viewer application window, on each axis.
If a connected user moves the client computers mouse cursor out of the application window within this area, the host
computers mouse cursor is snapped to the corner. This may be useful for connections to computers that trigger special
effects in the corners, for example Windows 8 and Mac OS X 10.8 (Mountain Lion).
Note: This parameter is ignored unless the SendPointerEvents parameter and the VNC Server
AcceptPointerEvents parameter are both set to TRUE.
See also: SendPointerEvents

PointerEventInterval

Specify a number of milliseconds to wait before sending mouse events such as cursor movements, clicks, and scrolls to
the host computer.
Increasing this value may make connections operating over a low-bandwidth network more responsive.
Note: This parameter is ignored unless the SendPointerEvents parameter and the VNC Server
AcceptPointerEvents parameter are both set to TRUE.
See also: SendPointerEvents

VNC User Guide

181

Appendix C: VNC Parameters

PreferredEncoding

ZRLE

Specify one of the following values to request that VNC Server send screen updates in a particular encoding:

JPEG, Zlib, ZRLE, TRLE, Hextile, Raw, JRLE

For more information on encodings, consult RFC 6143.
Note: This parameter has no effect if AutoSelect is TRUE.
See also: AutoSelect

ProtocolVersion

NULL

Specify one of the following values to request that VNC Server use only that version or lower of the underlying RFB
protocol:
3.3, 3.8, 4.0, 4.1
A lower version might be useful for connections to legacy third party VNC-compatible Server applications that do not
offer support for subsequent versions of the RFB protocol.
By default, the latest version of the RFB protocol is requested.

ProxyPassword

Null

Specify a password if ProxyServer requires authentication.

See also: ProxyServer, ProxyUserName

ProxyServer

Null

Specify the network address and port number of a proxy server if the client computer is protected by one, for example
"http://myproxyserver.com:8080". Alternatively:

Under Windows, specify _msiesettings_ to use the proxy server settings of Microsoft Internet Explorer.

Under UNIX, specify _env_ to use standard proxy server environment variables.

Under Mac OS X, specify _system_ to use standard proxy server environment variables.

Note: You must specify ProxyType for a SOCKS5 proxy server.

See also: ProxyType, ProxyUserName, ProxyPassword

ProxyType

httpconnect

Specify socks if ProxyServer is a SOCKS 5 proxy server. By default, an HTTP proxy server is assumed.
See also: ProxyServer

ProxyUserName
Specify a user name if ProxyServer requires authentication.
See also: ProxyServer, ProxyPassword

182

VNC User Guide

Null

Appendix C: VNC Parameters

RelativePtr

FALSE

Specify TRUE to send relative changes in mouse cursor position to the host computer, rather than absolute coordinates.
This may be useful to synchronize the mouse cursors of the client and host computers, if one is diverging from the other,
something that can occur if an application running on the host computer does not support absolute mouse events, or for
connections to KVM-over-IP switches. Note that a connected user will not be able to move the mouse cursor outside the
VNC Viewer application window.
Note: This parameter is ignored unless the SendPointerEvents parameter and the VNC Server
AcceptPointerEvents parameter are both set to TRUE.
See also: SendPointerEvents

RightCmdKey

Mac OS X

Super_L

Mac OS X

ExtendedChars

See LeftCmdKey, but for the right Command key.

RightOptKey
See LeftCmdKey, but for the right Option key.

RsaPrivateKeyFile

Mac OS X, UNIX

<platform-specific>

Specify the full path to a file storing a private key for VNC Viewer.
If the private key is missing or corrupt, connections cannot be established. To generate a new private key, restart VNC
Viewer.
See also: Encryption

ScalePrintOutput

True

Specify FALSE to print host computer files at their actual size.

By default, pages are scaled to fit the boundaries of the local printers paper.
Note: This parameter is ignored unless the EnableRemotePrinting parameter and the VNC Server
EnableRemotePrinting parameter are both set to TRUE.
See also: EnableRemotePrinting

VNC User Guide

183

Appendix C: VNC Parameters

Scaling

None

Specify one of the following values to determine whether the host computers desktop is scaled relative to the size of the
VNC Viewer application window:

None to not scale the host computers desktop. If it is bigger than the application window, scroll bars appear. The
window cannot be resized larger than the desktop.

Fit to scale the desktop to the size of the window.

AspectFit to scale the desktop to the size of the window, but retain the aspect ratio.

<pixel width>x<pixel height> to scale the desktop to the specified window size. The window cannot be resized
larger.

<pixel width>x to scale the desktop to the specified window width; the height is determined by the aspect ratio. The
window cannot be resized larger.

x<pixel height> to scale the desktop to the specified window height; the width is determined by the aspect ratio.
The window cannot be resized larger.

<percentage size>% to scale the desktop to a percentage of the size the window would be were this parameter set
to None. The window cannot be resized larger.

<percentage width>%x<percentage height>% to scale each axis of the desktop to a percentage of the size the
window would be were this parameter set to None. The window cannot be resized larger.

ScalingQuality

Mac OS X

Specify one of the following values to determine the rendering quality when the host computers desktop is scaled:

0 to use standard quality.

1 to use low quality (the desktop is rendered quicker).

2 to use medium quality.

3 to use high quality (note this might be CPU-intensive).

See also: Scaling

ScrollWheelAccel

Mac OS X

TRUE

Specify FALSE to ignore the speed at which the mouse is set to scroll in System Preferences, causing turns of the
mouse wheel to scroll pages at a regimented speed.
Note: This parameter is ignored unless the SendPointerEvents parameter and the VNC Server
AcceptPointerEvents parameter are both set to TRUE.
See also: SendPointerEvents

SecurityNotificationTimeout
Specify the number of milliseconds to display encryption status to a newly-connected user for.
The status is displayed at the bottom of the VNC Viewer application window, in a green bar if the connection is
encrypted and in a red bar if it is unencrypted. The connected user can dismiss the status bar at any time.
Specify 0 to suppress the display of the encryption status.

184

VNC User Guide

2500

Appendix C: VNC Parameters

SelectDesktop

NULL

Specify the name of a computer to connect to automatically when a connection is established to a suitably-enabled
ADDERLink KVM-over-IP switch.
See also: RelativePtr

SendKeyEvents

TRUE

Specify FALSE to prevent a connected user controlling the host computer using the client computers keyboard.
Note: This parameter is ignored unless the VNC Server AcceptKeyEvents parameter is set to TRUE.
See also: SendPointerEvents

SendMediaKeys

Mac OS X

FALSE

Specify FALSE to cause media keys such as Play and Volume Up to be interpreted by the client computer. By default,
these keys are sent to, and interpreted by, the host computer, providing VNC Viewer is in full screen mode.
Note: This parameter is ignored unless the SendKeyEvents parameter and the VNC Server AcceptKeyEvents
parameter are both set to TRUE.
See also: SendKeyEvents

SendPointerEvents

TRUE

Specify FALSE to prevent a connected user controlling the host computer using the client computers mouse.
Note: This parameter is ignored unless the VNC Server AcceptPointerEvents parameter is set to TRUE.
See also: SendKeyEvents

SendPrimary

UNIX

TRUE

Specify FALSE to send the PRIMARY selection (that is, the currently highlighted content) to VNC Server in preference
to the CLIPBOARD selection.
See also: ClientCutText

SendSpecialKeys

Windows

TRUE

Specify FALSE to cause the following keys and key combinations to be interpreted by the client computer:
Windows (also known as Start or Super), PrtScn (Print Screen), Alt+Tab, Alt+Esc, Ctrl+Esc
By default, these keys and key combinations are sent to, and interpreted by, the host computer.
Note: This parameter is ignored unless the SendKeyEvents parameter and the VNC Server AcceptKeyEvents
parameter are both set to TRUE.
See also: SendKeyEvents

ServerClipboardGraceTime

1000

Specify a number of milliseconds to wait before discarding text copied from the host computer if VNC Viewer no longer
has focus.
See also: ServerCutText

VNC User Guide

185

Appendix C: VNC Parameters

ServerCutText

TRUE

Specify FALSE to prevent a connected user copying text on the host computer and pasting it to their client computer.
Note: This parameter is ignored unless the VNC Server SendCutText parameter is set to TRUE.
See also: ClientCutText

Shared

TRUE

Specify FALSE to request that other users be disconnected when a connection is established.
Note: A newly-connected user cannot prevent disconnected users reconnecting, and may be disconnected in turn.
VNC Server complies with this request providing the VNC Server DisconnectClients parameter is set to TRUE.
Note: This parameter is ignored unless both the VNC Server AlwaysShared and NeverShared parameters are set to
FALSE.

ShareFiles

TRUE

Specify FALSE to prevent a connected user transferring files to and from the host computer.
Note: This parameter is ignored unless the VNC Server ShareFiles parameter is set to TRUE.
See also: FetchDir

SingleSignOn

TRUE

Specify FALSE to prevent a user authenticating automatically to VNC Server using credentials already supplied to log
on to the client computer (even if VNC Server is set to use the single sign-on authentication scheme, and all the
necessary network infrastructure is in place; see Setting up single sign-on authentication on page143.)

ToolbarIconSize

24

Specify either 16, 24, or 32 to determine the size in pixels of the icons on the VNC Viewer toolbar.
See also: EnableToolbar

UseAddrBook

TRUE

Specify FALSE to prevent a connected user saving connections to VNC Address Book.
The user is prompted to save connections to an (less secure) .vnc desktop file instead.

UseDisplayCapture

Mac OS X

TRUE

Specify FALSE to prevent key combinations such as Cmd+Tab being sent to the host computer when the VNC Viewer
application window is in full screen mode.
See also: FullScreen

UseAllMonitors

Windows, Mac OS X

FALSE

Specify TRUE to display the host computers desktop across all available monitors when VNC Viewer is in full screen
mode (if more than one monitor is attached to the client computer).
See also: FullScreen, Monitor

186

VNC User Guide

Appendix C: VNC Parameters

UseLocalCursor

TRUE

Specify FALSE to display the cursors of both the client and host computer (the former is represented by a dot). This may
be useful if the connection suffers from high latency, though note VNC Server may be required to send more screen
updates.
Note: This parameter is ignored unless the SendPointerEvents parameter and the VNC Server
AcceptPointerEvents parameter are both set to TRUE.
See also: SendPointerEvents

UserName

<user account name>

Specify the user name to use to authenticate to VNC Server.

VerifyID

Specify one of the following values to determine whether or not to warn a connecting user that VNC Servers signature
status has changed (note that in particular, a different signature may indicate a man-in-the-middle attack):

0 to suppress signature warnings.

1 to ensure warnings appear for different signatures, and for computers that no longer have a signature.

By default, warnings appear for new and for different signatures, and for computers that no longer have a signature (for
example, if VNC Server has been downgraded from an Enterprise or a Personal to a Free license).
See also: Identities

WarnUnencrypted

TRUE

Specify FALSE to prevent a connecting user being warned that the connection will be unencrypted before it is
established.

VNC User Guide

187

Appendix C: VNC Parameters

188

VNC User Guide

D
VNC At The Command Line
This appendix explains how to interact with VNC applications and perform particular operations at the
command line.
Note: VNC applications should not be run with elevated privileges unless otherwise stated.

Contents
VNC Server at the command line

190

VNC Viewer at the command line

192

VNC User Guide

189

Appendix D: VNC At The Command Line

VNC Server at the command line

VNC Server can be started in different modes, depending on the platform. See Running multiple instances
of VNC Server on page78 for more information.
By default, VNC Server and supporting applications are installed:

Under Windows, in C:\Program Files\RealVNC\VNC Server

Under UNIX, in either /usr/bin or /usr/local/bin

Under Mac OS X, in /Applications/RealVNC

Windows

Commands for VNC Server in Service Mode must be run from an Administrator Command Prompt.
To...

Mode

Run the command...

Start VNC Server

User

vncserver.exe

Service

vncserver.exe -start

Connect to Listening
VNC Viewer

User

vncserver.exe -connect <client computer>

Service

vncserver.exe -service -connect <client computer>

Start and connect to

Listening VNC Viewer

User

vncserver.exe -iconnect <client computer>

Service

invalid operation

Reload license keys and User

VNC parameters
Service

vncserver.exe -reload

Get help

User

vncserver.exe -help

Service

vncserver.exe -service -help

User

vncserver.exe -stop

Service

vncserver.exe -service -stop

Stop VNC Server

vncserver.exe -service -reload

UNIX

Commands for VNC Server in Service Mode must be run with elevated privileges.
For VNC Server in Virtual Mode, the vncserver symlink can be substituted for vncserver-virtual.
To...

Mode

Run the command...

Start VNC Server

User

vncserver-x11

Service

/etc/init.d/vncserver-x11-serviced start

#initd

systemctl start vncserver-x11-serviced.service

#systemd

Virtual

190

VNC User Guide

vncserver-virtual

Appendix D: VNC At The Command Line

To...

Mode

Run the command...

Connect to Listening
VNC Viewer

User

vncserver-x11 -connect <client computer>

Service

vncserver-x11 -service -connect <client computer>

Virtual

DISPLAY=:<display number> Xvnc -connect <client computer>

User

vncserver-x11 -iconnect <client computer>

Service

invalid operation

Virtual

vncserver-virtual -iconnect <client computer>

User

vncserver-x11 -reload

Service

vncserver-x11 -service -reload

Virtual

DISPLAY=:<display number> Xvnc -reload

Start and connect to

Listening VNC Viewer

Reload license keys and

VNC parameters

Get help

Stop VNC Server

User

vncserver-x11 -help

Service

vncserver-x11-serviced -help

Virtual

vncserver-virtual -list

User

vncserver-x11 -stop

Service

/etc/init.d/vncserver-x11-serviced stop

#initd

systemctl stop vncserver-x11-serviced.service

#systemd

Virtual

vncserver-virtual -kill :<display number>

Mac OS X

Commands for VNC Server in Service Mode must be run with elevated privileges.
To...

Mode

Run the command...

Start VNC Server

User

/Library/vnc/vncserver-root

Service

VNC\ Server.app/Contents/MacOS/vncserver_service

User

/Library/vnc/vncserver -connect <client computer>

Service

/Library/vnc/vncserver -service -connect <client computer>

Start and connect to

Listening VNC Viewer

User

/Library/vnc/vncserver -iconnect <client computer>

Service

invalid operation

Reload license keys and

VNC parameters

User

/Library/vnc/vncserver -reload

Service

/Library/vnc/vncserver -service -reload

Get help

User

/Library/vnc/vncserver -help

Stop VNC Server

User

/Library/vnc/vncserver -stop

Service

/Library/vnc/vncserver -service -stop

Connect to Listening
VNC Viewer

Service

VNC User Guide

191

Appendix D: VNC At The Command Line

VNC Viewer at the command line

The commands required to interact with VNC Viewer depend whether you:

Downloaded VNC Viewer as a standalone application from www.realvnc.com/download/viewer/. Note

that, under:
UNIX, you must first have made the downloaded file executable.
Mac OS X, you must first have mounted the downloaded disk image.

Installed VNC Viewer as part of VNC, from www.realvnc.com/download/vnc/. Note that, by default,
programs are installed:
Under Windows, in C:\Program Files\RealVNC\VNC Viewer
Under UNIX, in either /usr/bin or /usr/local/bin
Under Mac OS X, in /Applications/RealVNC

See Setting up the client computer on page12 for more information on these issues.
Windows

To...
Start VNC Viewer

Start VNC Viewer and connect

Start Listening VNC Viewer

Type

Run the command...

Standalone

<download file>.exe

Installed

vncviewer.exe

Standalone

<download file>.exe <host computer>

Installed

vncviewer.exe <host computer>

Standalone

<download file>.exe -listen [<port>]

Installed

vncviewer.exe -listen [<port>]

Standalone

<download file>.exe -help

Installed

vncviewer.exe -help

To...

Type

Run the command...

Start VNC Viewer

Standalone

./<download file>

Installed

vncviewer

Standalone

./<download file> <host computer>

Installed

vncviewer <host computer>

Start Listening VNC Viewer

Standalone

./<download file> -listen [<port>]

Installed

vncviewer -listen [<port>]

Get help

Standalone

./<download file> -help

Installed

vncviewer -help

Get help

UNIX

Start VNC Viewer and connect

192

VNC User Guide

Appendix D: VNC At The Command Line

Mac OS X

To...

Type

Run the command...

Start VNC Viewer

Standalone

/Volumes/<download file>/VNC\ Viewer.app/Contents/MacOS/

vncviewer

Installed

VNC\ Viewer.app/Contents/MacOS/vncviewer

Standalone

/Volumes/<download file>/VNC\ Viewer.app/Contents/MacOS/

vncviewer <host computer>

Installed

VNC\ Viewer.app/Contents/MacOS/vncviewer <host computer>

Start VNC Viewer and

connect

Start Listening VNC Viewer Standalone

Get help

/Volumes/<download file>/VNC\ Viewer.app/Contents/MacOS/

vncviewer -listen [<port>]

Installed

VNC\ Viewer.app/Contents/MacOS/vncviewer -listen

[<port>]

Standalone

/Volumes/<download file>/VNC\ Viewer.app/Contents/MacOS/

vncviewer -help

Installed

VNC\ Viewer.app/Contents/MacOS/vncviewer -help

VNC User Guide

193

Appendix D: VNC At The Command Line

194

VNC User Guide