« Back to docs

Configuring VNC Connect using parameters

VNC Server, VNC Viewer and supporting programs are controlled by parameters, set to suitable default values for most users out-of-the-box.

You can configure a program by specifying new values for parameters either:

For more information on VNC Server modes, click here.

Configuring programs before they start

You can specify parameters yourself:

Note that if you have an Enterprise subcription, it might be easier to use policy to deploy parameters remotely. This has the additional benefit of locking down programs so they cannot be changed by users.

Populating the Windows Registry with parameters

Under Windows, if you have permission to edit the Windows Registry, you can specify parameters as values for particular Registry keys.

The following table lists the Registry keys to create or edit for each program, and the order in which parameters are applied. Parameters specified using policy override parameters specified at the command line, which in turn override parameters specified manually in the Registry.

Program Order parameters are applied
(lowest takes precedence)
Notes
VNC Server in Service Mode HKLM\Software\RealVNC\vncserver
HKLM\Software\Policies\RealVNC\vncserver

The Options dialog for a program updates a particular Registry key; see this table.

Note it is not possible to specify parameters at the command line for VNC Server in Service Mode.

VNC Server in User Mode HKCU\Software\RealVNC\vncserver
<parameters at the command line>
HKCU\Software\Policies\RealVNC\vncserver
VNC Viewer HKCU\Software\RealVNC\vncviewer
<parameters at the command line>
HKCU\Software\Policies\RealVNC\vncviewer

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 parameters take string values, even boolean parameters.

Populating VNC configuration files with parameters

Under Linux and Mac, each program has a number of VNC configuration files, and additionally a number shared between all programs and user accounts on the computer.

The following tables list the files you can create or edit for each, and the order in which parameters are applied. Note that parameters specified using policy override parameters specified at the command line, which in turn override parameters specified manually in VNC configuration files.

Linux

Program Order parameters are applied
(lowest takes precedence)
Notes
VNC Server in Service Mode
vncserver-x11, via vncserver-x11-serviced
/etc/vnc/config.d/common.custom
/etc/vnc/config.d/vncserver-x11
/root/.vnc/config.d/common
/root/.vnc/config.d/vncserver-x11
/etc/vnc/policy.d/common
/etc/vnc/policy.d/vncserver-x11

The Options dialog updates a particular VNC configuration file; see this table.

Parameters specified in /etc/vnc/*/vncserver-x11 are applied to VNC Server in User Mode too.

VNC Server in User Mode
vncserver-X11
/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.

Parameters specified in /etc/vnc/*/vncserver-x11 are applied to VNC Server in Service Mode too.

VNC Server in Virtual Mode
Xvnc, via vncserver-virtual 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
The Options dialog updates a particular VNC configuration file; see this table.
VNC Server in Virtual Mode daemon
vncserver-virtuald
/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 the daemon does not have an Options dialog.

VNC Viewer
vncviewer
/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 a particular VNC configuration file; see this table.

Mac

Program Order parameters are applied
(lowest takes precedence)
Notes
VNC Server in Service Mode /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

Parameters specified in /etc/vnc/*.d/vncserver are applied to VNC Server in User Mode too.

The Options dialog updates a particular VNC configuration file; see this table.

Note it is not possible to specify parameters at the command line.

VNC Server in User Mode /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.

The Options dialog updates the VNC configuration file in this table.

VNC Viewer /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.

Sharing VNC configuration files between programs and user accounts

When VNC Connect is installed, /etc/vnc/config.d/common is created. Note this file is reserved for use by RealVNC.

To specify parameters for all programs for all user accounts on the computer, create /etc/vnc/config.d/common.custom.

To specify parameters for all programs for a particular user account, create ~/.vnc/config.d/common.

Note

~ is the root user account for certain programs; see the tables above.

Other VNC configuration files are program-specific. For example, to specify parameters for VNC Server in User Mode for all user accounts on a Linux computer, create /etc/vnc/config.d/vncserver-x11.

To specify parameters for VNC Server in User Mode for a particular user account, create ~/.vnc/config.d/vncserver-x11. Note this is the file updated by the Options dialog.

Format of a VNC configuration file

Each parameter in a VNC configuration file should be on a separate line; leading and trailing white space and comments are skipped, and environment variables expanded for parameters that accept them. For example:

#This is a comment
Desktop=Build machine
Encryption=AlwaysOn
Authentication=SystemAuth
RsaPrivateKeyFile=$HOME/secure/vnc
Permissions=admin:f,vncusers:d,guests:v

Configuring programs on the command line at start-up

Under any platform, for most programs, you can pass parameters in at the command line when you start that app, each preceded by a dash (-). This enables you to configure a particular instance of the program, rather than every time it runs. For example:

vncserver-x11 -Desktop="Debug machine" -Authentication=VncAuth

Note

You cannot configure VNC Server in Service Mode at the command line. For 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 you use VNC configuration files instead.

Parameters specified at the command line override the same parameters specified in the Windows Registry (see this table for the exact order) or in VNC configuration files (see these tables), 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 Linux and Mac, parameters may be overridden if a running program is reloaded.

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 programs

You can reconfigure:

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 program to be restarted. See the parameter reference for more information.

Using the Options dialog

Most programs have an Options dialog, providing a user-friendly interface to the 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 parameters directly.

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.
  • The Options dialog can be hidden from users.
  • 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 program are then reloaded.

Windows

Program 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 for a complete list of Registry keys and the order in which they are applied.

Linux

Program The Options dialog updates...
VNC Server in Service Mode /root/.vnc/config.d/vncserver-x11
VNC Server in User Mode ~/.vnc/config.d/vncserver-x11
VNC Server in Virtual Mode ~/.vnc/config.d/Xvnc
VNC Viewer ~/.vnc/config.d/vncviewer

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

Mac

Program 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 for a complete list of VNC configuration files and order in which they are applied.

Reloading 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, to reload VNC Server in User Mode under Linux:

vncserver-x11 -reload

Note that:

  • The -reload command also re-applies license keys.
  • The -reload command does not re-apply:
    • Parameters specified at the command line under Linux and Mac. If these parameters have subsequently changed, the original command line values will be overridden.
    • X options, for VNC Server in Virtual Mode under Linux.
  • 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.
×