- 1 Installation
- 2 Running vncserver for virtual (headless) sessions
- 3 Running vncserver to directly control the local display
- 4 Connecting to vncserver
- 5 Accessing vncserver via SSH tunnels
- 6 Tips and tricks
Install the package.
Vncserver provides two major remote control abilities:
- Virtual (headless) server which is similar to the standard X server, but has a virtual screen rather than a physical one. The virtual server runs completely parallel to the physical X server should one be running.
- Direct control of the local X session(s) which do run on the physical monitor.
Running vncserver for virtual (headless) sessions
Create environment, config, and password files
Vncserver will create its initial environment, config, and user password file the first time it is run. These will be stored in
~/.vnc which will be created if not present.
You will require a password to access your desktops. Password: Verify: New 'mars:1 (facade)' desktop is mars:1 Creating default startup script /home/facade/.vnc/xstartup Starting applications specified in /home/facade/.vnc/xstartup Log file is /home/facade/.vnc/mars:1.log
Notice the :1 trailing the hostname. This is indicating the TCP port number on which the virtual vncserver is running. In this case, :1 is actually TCP port 5901 (5900+1). Running
vncserver a second time will create a second instance running on the next highest, free port, i.e 5902 (5900+2) which shall end in :2 as above.
Shutdown the vncserver by using the -kill switch:
$ vncserver -kill :1
Edit the environment file
For example, starting lxqt:
#!/bin/sh exec startlxqt
Edit the optional config file
With the release of tigervnc 1.60-1, support for parsing options in
~/.vnc/config has been implemented which obviates the need to call
vncserver with command line switches. The format is one option per line. An example is provided:
## Supported server options to pass to vncserver upon invocation can be listed ## in this file. See the following manpages for more: vncserver(1) Xvnc(1). ## Several common ones are shown below. Uncomment and modify to your liking. ## securitytypes=tlsvnc desktop=sandbox geometry=1200x700 dpi=96 localhost alwaysshared
Starting and stopping vncserver via systemd
Systemd can manage the vncserver via a service in one of two modes using either a user or system service. Both are presented below.
Start the service in usermode:
$ systemctl --user start vncserver@:1
Enable the service in usermode:
$ systemctl --user enable vncserver@:1
In order to keep the vncserver alive when the user logs out (physically or via ssh), one must enable the linger option for loginctl:
# loginctl enable-linger username
/etc/systemd/system/vncserver@:1.service and modify it defining the user to run the server, and the desired options.
# The vncserver service unit file system mode # # 1. Copy this file to /etc/systemd/system/vncserver@:<display>.service # 2. Edit User= # ("User=foo") # 3. Edit the vncserver parameters appropriately # ("/usr/bin/vncserver %i -arg1 -arg2 -argn") # 4. Run `systemctl --system daemon-reload` # 5. Run `systemctl enable vncserver@:<display>.service` # # DO NOT RUN THIS SERVICE if your local area network is untrusted! # # See the wiki page for more on security # https://wiki.archlinux.org/index.php/Vncserver [Unit] Description=Remote desktop service (VNC) After=syslog.target network.target [Service] Type=simple User=foo PAMName=login ExecStartPre=/bin/sh -c '/usr/bin/vncserver -kill %i > /dev/null 2>&1 || :' ExecStart=/usr/bin/vncserver -geometry 1440x900 -alwaysshared -fg %i ExecStop=/usr/bin/vncserver -kill %i [Install] WantedBy=multi-user.target
You can use systemd socket activation in combination with XDMCP to automatically spawn VNC servers for each user who attempts to login, so there is no need to set up one server/port per user. It uses your display manager to authenticate users and login, so there is no need for VNC passwords. The downside is that you cannot leave a session running on the server and reconnect to it later. To get this running, first set up XDMCP and make sure whichever display manager you're using is running. Then create:
[Unit] Description=XVNC Server [Socket] ListenStream=5900 Accept=yes [Install] WantedBy=sockets.target
[Unit] Description=XVNC Per-Connection Daemon [Service] ExecStart=-/usr/bin/Xvnc -inetd -query localhost -geometry 1920x1080 -once -SecurityTypes=None User=nobody StandardInput=socket StandardError=syslog
If your VNC server is exposed to the internet, add the
-localhost option to
xvnc@.service and follow the instructions below about connecting over SSH (Note that the 'localhost' in
-query localhost is not
-localhost). Since we only select a user after connecting, the VNC server runs as user 'nobody' and uses xvnc directly instead of the 'vncserver' script, so any options in ~/.vnc are ignored. You might want to autostart
vncconfig so that the clipboard works (
vncconfig exits immediately in non-VNC sessions). One way is to create:
#!/bin/sh vncconfig -nowin &
Running vncserver to directly control the local display
Using tigervnc's x0vncserver
provides the x0vncserver binary which allows direct control over a physical X session. Invoke it like so:
$ x0vncserver -display :0 -passwordfile ~/.vnc/passwd
For more see
Another option is to use X11vnc.which has the advantage or disadvantage, depending on one's perspective, of requiring root to initiate the access. For more, see:
Connecting to vncserver
Any number of clients can connect to a vncserver. A simple example is given below where vncserver is running on 10.1.10.2 on port 5901 (:1) in shorthand notation:
$ vncviewer 10.1.10.2:1
-passwd switch allows one to define the location of the server's
~/.vnc/passwd file. It is expected that the user has access to this file on the server through SSH or through physical access. In either case, place that file on the client's file system in a safe location, i.e. one that has read access ONLY to the expected user.
$ vncviewer -passwd /path/to/server-passwd-file
Example GUI-based clients
- broken link: replaced by ] [
TigerVNC's vncviewer also has a simple GUI when run without any parameters:
Accessing vncserver via SSH tunnels
An advantage of SSH tunneling is one does not need to open up another port to the outside, since the traffic is literally tunneled through the SSH port which the user already has open to the WAN. It is highly recommended to use the
-localhost switch when running vncserver with this method since this switch only allows connections from the localhost and by analogy, only by users physically ssh'ed and authenticated on the box.
On the server
Below is an example invoking vncserver with the -localhost flag:
$ vncserver -geometry 1440x900 -alwaysshared -dpi 96 -localhost :1
Alternatively, simply add the "localhost" option as a single line in
~/.vnc/config. Below is the example above in this format:
## Supported server options to pass to vncserver upon invocation can be listed ## in this file. See the following manpages for more: vncserver(1) Xvnc(1). ## Several common ones are shown below. Uncomment and modify to your liking. ## geometry=1200x700 alwaysshared dpi=96 localhost
On the client
With the server now only accepting connection from the localhost, connect to the box via ssh using the -L switch to enable tunnels. For more on this feature, see the manpage for ssh itself. For example:
$ ssh 10.1.10.2 -L 5901:localhost:5901
This forwards the server port 5901 to the client box also on port 5901. Note that one does not have to match the port numbers on the server and client. For example:
$ ssh 10.1.10.2 -L 8900:localhost:5901
This forwards the server port 5901 to the client box on port 8900.
Once connected via SSH, leave that xterm or shell window open since it is acting as the secured tunnel to/from server. To connect via this encrypted tunnel, simply point the vncviewer to the client port on the localhost.
Using the matched ports on the server/client:
$ vncviewer localhost:1
Using different ports on the server/client:
$ vncviewer localhost:8900
Connecting to a vncserver from Android devices over SSH
To connect to a VNC Server over SSH using an Android device:
1. SSH server running on the machine to connect to. 2. VNC server running on the machine to connect to. (Run server with -localhost flag as mentioned above) 3. SSH client on the Android device (ConnectBot is a popular choice and will be used in this guide as an example). 4. VNC client on the Android device (androidVNC).
Consider some dynamic DNS service for targets that do not have static IP addresses.
In ConnectBot, type in the IP and connect to the desired machine. Tap the options key, select Port Forwards and add a new port:
Nickname: vnc Type: Local Source port: 5901 Destination: 127.0.0.1:5901
Nickname: nickname Password: the password used to set up the VNC server Address: 127.0.0.1 (we are in local after connecting through SSH) Port: 5901
Tips and tricks
Connecting to an OSX system
See https://help.ubuntu.com/community/AppleRemoteDesktop. Tested with Remmina.
Copying clipboard contents from the remote machine to the local
If copying from the remote machine to the local machine does not work, run autocutsel on the server, as mentioned below reference:
$ autocutsel -fork
Now press F8 to display the VNC menu popup, and select
Clipboard: local -> remote option.
One can put the above command in
~/.vnc/xstartup to have it run automatically when vncserver is started.
Fix for no mouse cursor
If no mouse cursor is visible when using
x0vncserver, start vncviewer as follows:
$ vncviewer DotWhenNoCursor=1 <server>
DotWhenNoCursor=1 in the tigervnc configuration file, which is at
~/.vnc/default.tigervnc by default.
Recommended security settings
SecurityTypes controls the preferred security algorithms. The default in the current version 1.5.0 is "X509Plain,TLSPlain,X509Vnc,TLSVnc,X509None,TLSNone,VncAuth,None". A more secure alternative is "X509Vnc,TLSVnc", which will disable all unencrypted data traffic.
It is recommended to use X509Vnc, as TLSVnc lacks identity verification.
$ vncserver -x509key /path/to/key.pem -x509cert /path/to/cerm.pem -SecurityTypes X509Vnc :1
Issuing x509 certificates is beyond the scope of this guide. However, this is expected to be straightforward after the public launch of Let's Encrypt. Alternatively, one can issue certificates using OpenSSL and manually share the keys between server and client using email for instance.
This can be done through vncclient's Menu. By default, vncclient's Menu Key is F8.
Unable to type less than character (<)
< on a remote client emits the
> character, try remapping the incoming key :
$ x0vncserver -RemapKeys="0x3c->0x2c"