- 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
- 7 Troubleshooting
- 8 See also
Install the package.
Two VNC servers are available with TigerVNC:
- Xvnc is the default and recommended server for TigerVNC. It is both a VNC server and an X server with a virtual framebuffer. This means it is similar to the standard X server but has a virtual screen rather than a physical one. The virtual server runs in parallel with the physical X server should one be running. See for the manual. vncserver is a wrapper script which eases the starting of Xvnc, see .
- x0vncserver provides direct control of the local X session(s) which are running on the physical monitor. It continuously polls the X display which is a simple but inefficient implementation. See for the manual.
Running vncserver for virtual (headless) sessions
Create environment, config, and password files
The first time vncserver is run, it creates its initial environment, config, and user password file. 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
:1 trailing the hostname. This indicates 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.
To shutdown the just created VNC server, use the
$ vncserver -kill :1
Edit the environment file
~/.vnc/xstartup script is sourced by vncserver for creating the virtual X session and it must be adapted to one's needs.
It functions like an .xinitrc file. Users are expected to start a Desktop environment, see: General recommendations#Desktop environments.
For example, starting XFCE:
#!/bin/sh unset SESSION_MANAGER unset DBUS_SESSION_BUS_ADDRESS exec startxfce4
~/.vnc/xstartup has a execute permission:
chmod u+x ~/.vnc/xstartup
Edit the optional config file
TigerVNC supports parsing
vncserver options in the file
~/.vnc/config rather than through the command line. The format is one option per line. An example is provided below:
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.
# loginctl enable-linger usernameFailure to do so will result in the vncserver getting killed when the user logs off the machine.
:1 is the
$DISPLAY environment variable.
Modify the service by defining the user (
User=) to run the server, and the desired Vncserver options (
usr/bin/vncserver %i -arg1 -arg2 -argn).
[Unit] Description=Remote desktop service (VNC) After=syslog.target network.target [Service] Type=simple User=foo PAMName=login PIDFile=/home/%u/.vnc/%H%i.pid ExecStartPre=/bin/sh -c '/usr/bin/vncserver -kill %i > /dev/null 2>&1 || :' ExecStart=/usr/bin/vncserver %i -geometry 1440x900 -alwaysshared -fg ExecStop=/usr/bin/vncserver -kill %i [Install] WantedBy=multi-user.target
One 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. This setup uses the display manager to authenticate users and login, so there is no need for VNC passwords. The downside is that users cannot leave a session running on the server and reconnect to it later.
To get this running, first set up XDMCP and make sure the display manager 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 the VNC server is exposed to the internet, add the
-localhost option to
xvnc@.service (note that
-query localhost and
-localhost are different switches) and follow #Accessing vncserver via SSH tunnels. 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. Optionally, 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
The tigervnc package 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 information see.
Starting and stopping x0vncserver via systemd
In order to have a VNC Server runnning x0vncserver, which is the easiest way for most users to quickly have remote access to the current desktop, you can create a systemd unit as follows replacing the user and the options with the desired ones:
[Unit] Description=Remote desktop service (VNC) After=syslog.target network.target [Service] Type=forking User=foo ExecStart=/usr/bin/sh -c '/usr/bin/x0vncserver -display :0 -rfbport 5900 -passwordfile /home/foo/.vnc/passwd &' [Install] WantedBy=multi-user.target
- This unit will only be useful if the user in the unit is currently running a X session.
- Do not run this service if your local area network is untrusted.
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
SecurityTypesto a non-secure option, although this lacks identity verification and will not prevent man-in-the-middle attack during the connection setup. X509Vnc is the recommended option for a secure connection.
Any number of clients can connect to a vncserver. A simple example is given below where vncserver is running on 10.1.10.2 port 5901, or :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
TigerVNC's vncviewer also has a simple GUI when run without any parameters:
Accessing vncserver via SSH tunnels
For servers offering SSH connection, an advantage of this method is that it is not necessary to open any other port than the already opened SSH port to the outside, since the vnc traffic is tunneled through the SSH port. It is highly recommended to use the
-localhost switch when running vncserver this way since it allows connections from the localhost only and by analogy, only from users ssh'ed and authenticated on the box.
SecurityTypesparameter. Authentication and traffic is encrypted, but there is no identity verification. TigerVNC supports alternative encryption schemes such as X509Vnc that allows the client to verify the identity of the server. When
SecurityTypeson the server side is set to a non-secure option as high-priority (such as None, VncAuth, Plain, TLSNone, TLSPlain, X509None, X509Plain; which is ill-advised), it is not possible to use encryption. In that case, one can tunnel over SSH. When running vncviewer, it is safer to explicitly set
SecurityTypesand not accept any unencrypted traffic.
On the server
The vncserver must be run on the server, it is appropriate to use the
-localhost flag to only allow connections from the same machine and stop all non-SSH connections from any other host. For example run a command line similar to:
$ vncserver -geometry 1440x900 -alwaysshared -dpi 96 -localhost :1
On the client
The VNC server has been setup on the remote machine to only accept local connections. Now, the client must open a secure shell with the remote machine (10.1.10.2 in this example) and create a tunnel from the client port 5901 to the remote server 5901 port. For more details on this feature, see Secure Shell#Forwarding other ports and .
$ ssh 10.1.10.2 -L 5901:localhost:5901
Note that the port number on the server and the one on the client do not need to match. For example to forward the client port 8900 to the server port 5901:
$ ssh 10.1.10.2 -L 8900:localhost:5901
Once connected via SSH, leave this shell window open since it is acting as the secured tunnel to/from server (or just run SSH in the background with the
-f option). On the client side, to connect via this encrypted tunnel, point the vncviewer to the forwarded client port on the localhost.
Using the matched ports on the server/client:
$ vncviewer localhost:5901
Using different ports on the server/client:
$ vncviewer localhost:8900
What happens in practice is that the vncviewer connects locally to port 8900 which is tunneled to the server's localhost port 5901. The connection is established to the right port within the secure shell.
Connecting to a vncserver from Android devices over SSH
To connect to a VNC server over SSH using an Android device as a client, consider having the following setup:
- SSH running on the server
- vncserver running on server (with
-localhostflag for security)
- SSH client on the Android device: ConnectBot is a popular choice and will be used in this guide as an example
- VNC client on the Android device: androidVNC used here
In ConnectBot, connect to the desired machine. Tap the options key, select Port Forwards and add a port:
Type: Local Source port: 5901 Destination: 127.0.0.1:5901
In androidVNC connect to the VNC port, this is the local address following the SSH connection:
Password: the vncserver password Address: 127.0.0.1 Port: 5901
Tips and tricks
Connecting to an OSX system
See https://help.ubuntu.com/community/AppleRemoteDesktop. Tested with Remmina.
Connecting to non-X environments on a Raspberry Pi (Arch ARM)
InstallAUR on the Arch ARM device. Frame rates are not very high but it provides a working VNC access.
Recommended security settings
If not #Accessing vncserver via SSH tunnels where the identification and the encryption are handled via SSH, it is recommended to use X509Vnc, as TLSVnc lacks identity verification.
$ vncserver -x509key /path/to/key.pem -x509cert /path/to/cert.pem -SecurityTypes X509Vnc :1
Issuing x509 certificates is beyond the scope of this guide. However, Let's Encrypt provides an easy way to do so. Alternatively, one can issue certificates using OpenSSL, share the public key with the client and specify it with the
-X509CA parameter. An example is given below the server is running on 10.1.10.2:
$ vncviewer 10.1.10.2 -X509CA /path/to/cert.pem
This can be done through vncclient's Menu. By default, vncclient's Menu Key is F8.
Unable to type '<' character
< on a remote client emits the
> character, try remapping the incoming key :
$ x0vncserver -RemapKeys="0x3c->0x2c"
Black rectangle instead of window
Most probably it means that you use application that strictly requires Composite Xorg extension. For example webkit based app: midori, psi-plus, etc.
You should restart vncserver in this case using something like following:
vncserver -geometry ... -depth 24 :1 +extension Composite
It looks like Composite extension in VNC will work only with 24bit depth.
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.
Copying clipboard content from the remote machine
If copying from the remote machine to the local machine does not work, run
autocutsel on the server, as mentioned in :
$ 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.