vncserver-virtual - VNC® Server in Virtual Mode  


vncserver-virtual [OPTION...] [:DISPLAY]
vncserver-virtual [OPTION...] COMMAND  


vncserver-virtual starts VNC Server in Virtual Mode in order to create a virtual desktop and provide a dedicated workspace for connected VNC Viewer(s). A virtual desktop persists until VNC Server is explicitly stopped, even if the user starting it logs out, or all VNC Viewers disconnect. It is entirely independent of the console of the host computer; neither the desktop of the currently logged on user, nor the login screen, are available to connected VNC Viewers.

By default, a VNC Viewer can connect if VNC Server has:

An Enterprise or a Personal license by supplying the system credentials of the user starting VNC Server. Specify the Permissions VNC parameter to widen access to other users or groups.
A Free license by supplying a password specific to VNC; see vncpasswd(1).

Note that vncserver-virtual is the recommended interface to Xvnc. vncserver-virtual passes all COMMANDS and OPTIONS to Xvnc, and in addition runs a default desktop environment, handles logging, and prompts for a password if the VNC authentication scheme is chosen. Note there may be circumstances in which you need to interact with Xvnc directly; see Xvnc(1). Note also that vncserver is a symlink to vncserver-virtual.

Run vncserver-virtual to start VNC Server and create a virtual desktop on the first available display, for example 1. By convention, this equates to a port number of 5900 + DISPLAY, so in this case port 5901. Note that no user interface is available for you to work with VNC Server; specify OPTIONS to configure VNC Server before it starts. Run vncserver-virtual :DISPLAY to start VNC Server on the specified display, if it is available.

Note that if you have an Enterprise license, VNC Server can be started automatically to create virtual desktops on demand; see vncserver-virtuald(1).

vncserver-virtual consumes one desktop from your license, as the user starting it.  


Applying one of the following commands to vncserver-virtual performs an auxiliary operation instead of starting VNC Server:
Deletes any /tmp/.X11-unix directory and /tmp/.X<num> files that may persist if VNC Server is stopped abruptly.
Shows a help summary.
-kill :DISPLAY
Stops VNC Server, disconnecting all VNC Viewers, and destroying the virtual desktop on DISPLAY.
Shows a list of OPTIONS.
Test mode. The environment and any OPTIONS are tested, and the expected command is printed rather than executed. For example:

vncserver-virtual -test :1 -config=/my/Xvnc/options

verifies that display 1 is available, checks that the /my/Xvnc/options file contains only valid Xvnc options in the correct format for the X server, prints the command, and exits.

Note that other commands are available to perform operations on existing virtual desktops, but these must be applied to Xvnc; see Xvnc(1).  


Options can be any combination of the following:
VNC parameters, used to configure VNC Server. Run vncserver-virtual -list and examine the output at the bottom. Note it is preferable to specify VNC parameters in VNC CONFIGURATION FILES.
Xvnc options, used to configure the built-in X server. Run vncserver-virtual -list and examine the output at the top, and see Xserver(1) for more information on shared options. Note it may be more convenient to specify Xvnc options in XVNC CONFIGURATION FILES.
The following additional Xvnc options, which may also be specified in XVNC CONFIGURATION FILES:
-blackpixel N
Specifies the pixel value for black.
-config FILE
Loads Xvnc options from FILE (one per line, in the format expected by the X server) instead of those in $HOME/.vnc/config.
-depth D
Specifies the pixel depth in bits of the virtual desktop. The default is 16; alternatives are 8, 15, and 24.
-geometry WxH
Specifies the size of the virtual desktop. The default is 1024x768.
-iconnect HOST[::PORT]
Establishes a reverse connection to a Listening VNC Viewer on HOST at PORT (5500 by default). See vncviewer(1).
-linebias N
Adjusts thin line pixelization.
-pixdepths list-of-int
Supports the given list of pixmap depths.
-pixelformat FMT
Specifies the pixel format (RGBnnn or BGRnnn). The default for depth 8 is to use a colormap (palette); the default for depth 16 is RGB565 and for depth 24, RGB888.
-screen N WxHxD [XxY]
Sets the width, height, depth, and origin of screen N.
Causes the VNC Server status dialog to be displayed to connected VNC Viewers (the dialog is hidden by default).
-vncconfigfile FILE
For convenience, if you have many VNC parameters to specify at the command line, populate a text file (one parameter per line; omit the dash) and reference it using this flag.
-whitepixel N
Specifies the pixel value for white.
The following special options, which must NOT be specified in XVNC CONFIGURATION FILES:
-config FILE
Loads Xvnc options from FILE (one per line, in the format expected by the X server) instead of those in $HOME/.vnc/config.
Does not prompt for a password if the VNC authentication scheme is chosen.


VNC parameters can be specified as command line OPTIONS, but preferably in VNC configuration files. VNC configuration files are available for:
All VNC applications, or just VNC Server
All users of the computer, or just the user starting VNC Server
Policy, in order to lock down VNC Server (Enterprise license required)

When VNC Server starts, VNC parameters are applied in the following order:

System-wide VNC configuration files
Per-user VNC configuration files
Command line OPTIONS
Policy VNC configuration files

This means that a particular VNC parameter specified at the command line overrides the same parameter specified in a per-user or in a system-wide VNC configuration file, but is itself overridden by the same parameter specified in a policy VNC configuration file. Policy cannot be changed by users.

Note there is a disadvantage to specifying VNC parameters at the command line: parameters cannot be reloaded while VNC Server is running. VNC configuration files can be reloaded, however, which means that VNC Server can be reconfigured without downtime.

For a list of the VNC configuration files available for VNC Server, and for detailed explanations of individual VNC parameters, start with  


Xvnc options can be specified as command line OPTIONS, or in Xvnc configuration files:
To specify Xvnc options for all users of the computer, create /etc/vnc/config.custom.
To specify Xvnc options for a particular user, create $HOME/.vnc/config (though see also the -config flag).

For more information, see Note if you specify the same Xvnc option in multiple locations there is no guarantee which will actually take effect.  


By default, vncserver-virtual runs /etc/vnc/xstartup to select a desktop environment for the virtual desktop. You may want to choose a different desktop environment, or run particular applications:
To make changes for all users of the computer, create /etc/vnc/xstartup.custom. If this file exists, the default script is not run.
To make changes for a particular user, create $HOME/.vnc/xstartup. If this file exists, no system-wide script is run for that user.



The X server built-in to VNC Server may have different capabilities to the console X server; most notably, hardware acceleration is not available. For this reason, some desktop environments (particularly those with a reliance on graphical effects) may not work.

Where possible, the default X STARTUP SCRIPT chooses a "fallback" or "2D" desktop environment, although even these are not guaranteed to work in all cases. For more information, including a list of recommended desktop environments for supported platforms, see  


vncserver-virtual creates $HOME/.vnc/, containing the process ID of the virtual desktop. This file is required for the -kill command.  


By default, vncserver-virtual logs basic activity to Standard Error, and automatically redirects it to file at $HOME/.vnc/HOST:DISPLAY.log. The log output of any applications in the X startup script is also included.

To change the log quality, quantity, or destination, specify the Log, LogDir, and LogFile VNC parameters.  


Xvnc(1), vncserver-virtuald(1), vnclicense(1), vncinitconfig(1), vncpasswd(1), vncviewer(1)  


Copyright © 2002-2014 RealVNC Ltd.

VNC is a registered trademark of RealVNC Ltd. in the U.S. and in other countries. Protected by UK patent 2481870.