Difference between revisions of "TigerVNC"

From ArchWiki
Jump to: navigation, search
(corrected the position of @)
(User mode: switch Note below instructions, shortening by adding a crosslink to systemd)
 
(294 intermediate revisions by 58 users not shown)
Line 1: Line 1:
[[Category:Security]]
+
[[Category:Remote desktop]]
[[Category:Virtual Network Computing]]
+
[[Category:Servers]]
 
[[de:VNC]]
 
[[de:VNC]]
{{Article summary start}}
+
[[es:TigerVNC]]
{{Article summary text|Vncserver is a remote display daemon that allows users to run totally ''parallel'' sessions on a machine which can be accessed from anywhere.  All applications running under the server continue to run, even when the user disconnects. }}
+
[[ja:TigerVNC]]
{{Article summary heading|Related Articles}}
+
[[ru:TigerVNC]]
{{Article summary wiki|x11vnc}} - Another flavor of VNC which allows connections to the root (:0) desktop.
+
[[zh-hans:Virtual Network Computing]]
{{Article summary end}}
+
{{Related articles start}}
 +
{{Related|x11vnc}}
 +
{{Related articles end}}
 +
[http://tigervnc.org/ TigerVNC] is an implementation of the [[Wikipedia:Virtual Network Computing|Virtual Network Computing]] (VNC) protocol. This article focuses on the server functionality.
  
 
== Installation ==
 
== Installation ==
Vncserver is provided by {{pkg|tigervnc}} and {{pkg|tightvnc}} both of which can be installed from the [[official repositories]].
 
  
== Running Vncserver ==
+
[[Install]] the {{Pkg|tigervnc}} package.  
===First Time Setup===
 
==== Create Environment and Password Files ====
 
Vncserver will create its initial environment file and user password file the first time it is run:
 
$ vncserver
 
 
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
 
  
The default port on which  vncserver runs is :1 which corresponds to the the TCP port on which the server is running (where 5900+n = port number). In this case, it is running on 5900+1=5901. Running vncserver a second time will create a second instance running on the next highest, free port, i.e :2 or 5902.
+
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 {{man|1|Xvnc}} for the manual. ''vncserver'' is a wrapper script which eases the starting of ''Xvnc'', see {{man|1|vncserver}}.
 +
# ''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 {{man|1|x0vncserver}} for the manual.
  
{{Note|Linux systems can have as many VNC servers as physical memory allows -- all of which running in parallel to each other.}}
+
== Running vncserver for virtual (headless) sessions ==
  
Shutdown the vncserver by using the -kill switch:
+
=== Create environment, config, and password files ===
$ vncserver -kill :1
+
The first time ''vncserver'' is run, it creates its initial environment, config, and user password file.  These will be stored in {{ic|~/.vnc}} which will be created if not present.
 +
 
 +
{{hc|$ vncserver|
 +
You will require a password to access your desktops.
  
====Edit the xstartup File====
+
Password:
Vncserver sources {{ic|~/.vnc/xstartup}} which functions like an [[.xinitrc]] file.  At a minimum, users should define a DE to start if a graphical environment is desired.  For example, starting xfce4:
+
Verify:
  
#!/bin/sh
+
New 'mars:1 (facade)' desktop is mars:1
export XKL_XMODMAP_DISABLE=1
 
exec startxfce4
 
  
{{Note|The XKL_XMODMAP_DISABLE line is known to correct problems associated with "scrambled" keystrokes when typing in terminals under some virtualized DEs.}}
+
Creating default startup script /home/facade/.vnc/xstartup
{{Note|As of 31-Oct-2012, usage of the command "exec ck-launch-session ..." in ~/.vnc/xstartup is depreciated since Arch has dropped consolekit.}}
+
Starting applications specified in /home/facade/.vnc/xstartup
 +
Log file is /home/facade/.vnc/mars:1.log
 +
}}
  
==== Permissions ====
+
Note the {{ic|:1}} trailing the hostname.  This indicates the TCP port number on which the virtual vncserver is running.  In this case, {{ic|:1}} is actually TCP port 5901 (5900+1)Running {{ic|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 {{ic|:2}} as above.
It is good practice to secure {{ic|~/.vnc}} just like {{ic|~/.ssh}} although this is not a requirementExecute the following to do so:
 
$ chmod 700 ~/.vnc
 
  
== Running vncserver ==
+
{{Note|Linux systems can have as many VNC servers as memory allows, all of which will be running in parallel to each other.}}
Vncserver offers flexibility via switches.  The below example starts vncserver in a specific resolution, allowing multiple users to view/control simultaneously, and sets the dpi on the virtual server to 96:
 
 
$ vncserver -geometry 1440x900 -alwaysshared -dpi 96 :1
 
{{Note|One need not use a standard monitor resolution for vncserver; 1440x900 can be replaced with something odd like 1429x882 or 1900x200 etc.}}
 
  
For a complete list of options, pass the -badoption switch to vncserver.
+
To shutdown the just created VNC server, use the {{ic|-kill}} switch:
 +
$ vncserver -kill :1
  
$ vncserver -badoption
+
==== Edit the environment file ====
  
== Connecting to vncserver ==
+
The {{ic|~/.vnc/xstartup}} script is sourced by ''vncserver'' for creating the virtual X session and it must be adapted to one's needs.
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:
+
It functions like an [[.xinitrc]] file. In this script, users are expected to start a [[Desktop environment]], see: [[General recommendations#Desktop environments]].
$ vncviewer 10.1.10.2:1
 
  
=== Passwordless Authentication ===
+
For example, starting [[Xfce]]:
The -passwd switch allows one define the location of the sever'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 filesystem in a safe location, i.e. one that has read access ONLY to the expected user.
 
  
$ vncviewer -passwd /path/to/server-passwd-file
+
{{hc|~/.vnc/xstartup|
 +
#!/bin/sh
 +
unset SESSION_MANAGER
 +
unset DBUS_SESSION_BUS_ADDRESS
 +
exec startxfce4}}
  
=== Example GUI-based Clients ===
+
Some desktop environments may require [[D-Bus]] session. For example, starting [[GNOME]]:
*extra/gtk-vnc
 
*extra/vinagre
 
*extra/rdesktop
 
*community/remmina
 
*community/vncviewer-jar
 
  
== Securing VNC Server by SSH Tunnels ==
+
{{hc|~/.vnc/xstartup|
=== On the Server ===
+
#!/bin/sh
One wishing access to vncserver from outside the protection of a LAN should be concerned about plain text passwords and unencrypted traffic to/from the viewer and server. Vncserver is easily secured by ssh tunneling.  Additionally, one need not open up another port to the outside using this method 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 in this scenario.  This switch only allows connections ''from the localhost'' -- and by analogy only by users physically ssh'ed and authenticated on the box!
+
unset SESSION_MANAGER
 +
unset DBUS_SESSION_BUS_ADDRESS
 +
exec dbus-launch gnome-session}}
  
  $ vncserver -geometry 1440x900 -alwaysshared -dpi 96 -localhost :1
+
Make sure {{ic|~/.vnc/xstartup}} has a execute permission:
 +
  $ chmod u+x ~/.vnc/xstartup
  
=== On the Client ===
+
==== Edit the optional config file ====
  
With the server now only accepting connection from the localhost, connect to the box via ssh using the -L switch to enable tunnels. For example:
+
TigerVNC supports parsing {{ic|vncserver}} options in the file {{ic|~/.vnc/config}} rather than through the command line. The format is one option per line. An example is provided below:
 +
{{hc|~/.vnc/config|2=
 +
securitytypes=tlsvnc
 +
desktop=sandbox
 +
geometry=1200x700
 +
dpi=96
 +
localhost
 +
alwaysshared}}
  
  $ ssh IP_OF_TARGET_MACHINE -L 8900/localhost/5901
+
=== 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.
  
This forwards the server port 5901 to the client box on port 8900.  Once connected via SSH, leave that xterm or shell window open; it is acting as a secured tunnel to/from server.  To connect via vnc, open a second xterm and connect not to the remote IP address, but to the localhost of the client thus using the secured tunnel:
+
==== User mode ====
$ vncviewer localhost:8900
 
  
From the ssh man page:
+
[[Start]] and [[enable]] the service {{ic|vncserver@:1.service}} in [[Systemd/User]] mode, i.e. with the {{ic|--user}} parameter.
''-L [bind_address:] port:host:hostport''
 
  
''Specifies that the given port on the local (client) host is to be forwarded to the given host  and  port on the remote side.  This works by allocating a socket to listen to port on the local side, optionally bound to the specified bind_address.  Whenever  a  connection  is  made  to this port, the connection is forwarded over the secure channel, and a connection is made to host port hostport from the remote machine.  Port forwardings can also  be  specified  in the configuration file. IPv6 addresses can be specified with an alternative syntax:''
+
{{Note|The vncserver will get killed when the user logs off the machine, see [[Systemd/User#Automatic start-up of systemd user instances]] for related configuration.}}
  
''[bind_address/] port/host/ hostport or by enclosing the  address  in  square  brackets.''
+
==== System mode ====
''Only the superuser can forward privileged ports.  By default, the local port is bound in accordance with the GatewayPorts setting.  However, an explicit bind_address may be used to  bind  the connection to a specific address.  The bind_address of ``localhost'' indicates that the listening port be bound for local use only, while an empty address or `*' indicates that the port should be available from all interfaces.''
 
  
== Starting and Stopping VNC Server at Bootup and Shutdown ==
+
Create {{ic|/etc/systemd/system/vncserver@'':1''.service}}, where {{ic|:1}} is the 5900 port increment (5900 + 1) to which the VNC server will be listening for connections (e.g {{ic|vncserver@:5.service}} means the server will be listening to port 5905). Edit the service unit by defining the user ({{ic|1=User=}}) to run the server, and the desired [[Vncserver]] options.
{{hc|/etc/systemd/system/vncserver@:1.service|
 
<nowiki># The vncserver service unit file
 
#
 
# 1. Copy this file to /etc/systemd/system/vncserver@:x.service
 
#  Note that x is the port number on which the vncserver will runThe default is 1 which
 
#  corresponds to port 5901. For a 2nd instance, use x=2 which corresponds to port 5902.
 
# 2. Edit User=
 
#  ("User=foo")
 
# 3. Edit  and 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
 
  
 +
{{hc|/etc/systemd/system/vncserver@'':1''.service|2=
 
[Unit]
 
[Unit]
 
Description=Remote desktop service (VNC)
 
Description=Remote desktop service (VNC)
Line 122: Line 98:
  
 
[Service]
 
[Service]
Type=forking
+
Type=simple
User=
+
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}}
 +
 
 +
{{Note|
 +
* If you plan to use [[Xfce]] desktop environment on VNC server then [[D-Bus]] starting before VNC server may be required. Just add {{ic|1=ExecStartPre=/usr/bin/dbus-launch}} entry in {{ic|[Service]}} section of unit file.
 +
* Do not run this service if your local area network is untrusted.}}
 +
 
 +
[[Start]] {{ic|vncserver@'':1''.service}} and optionally [[enable]] it to run at boot time/shutdown.
 +
 
 +
==== Multi-user mode ====
 +
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:
 +
{{hc|/etc/systemd/system/xvnc.socket|2=
 +
[Unit]
 +
Description=XVNC Server
 +
 
 +
[Socket]
 +
ListenStream=5900
 +
Accept=yes
 +
 
 +
[Install]
 +
WantedBy=sockets.target}}
 +
{{hc|/etc/systemd/system/xvnc@.service|2=
 +
[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}}
 +
Use systemctl to [[start]] and [[enable]] {{ic|xvnc.socket}}. Now any number of users can get unique desktops by connecting to port 5900.
 +
 
 +
If the VNC server is exposed to the internet, add the {{ic|-localhost}} option to {{ic|Xvnc}} in {{ic|xvnc@.service}} (note that {{ic|-query localhost}} and {{ic|-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 {{ic|Xvnc}} directly instead of the {{ic|vncserver}} script, so any options in {{ic|~/.vnc}} are ignored. Optionally, [[autostart]] ''vncconfig'' so that the clipboard works (''vncconfig'' exits immediately in non-VNC sessions). One way is to create:
 +
{{hc|/etc/X11/xinit/xinitrc.d/99-vncconfig.sh|
 +
#!/bin/sh
 +
vncconfig -nowin &}}
 +
 
 +
== Running vncserver to directly control the local display ==
 +
 
 +
As mentioned in [[#Installation]], the ''tigervnc'' package also provides the x0vncserver binary which allows direct control over a physical X session.  Invoke it like so:
 +
$ x0vncserver -rfbauth ~/.vnc/passwd
 +
 
 +
For more information, see {{man|1|x0vncserver}}.
 +
 
 +
{{Tip|Another option is to use the [[x11vnc]] VNC server which also provides direct control of the current X session, note that ''x11vnc'' requires ''root'' privilege to initiate the access.}}
  
# Clean any existing files in /tmp/.X11-unix environment
+
=== Starting and stopping x0vncserver via systemd ===
ExecStartPre=-/usr/bin/vncserver -kill %i
+
In order to have a VNC Server running 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:
ExecStart=/usr/bin/vncserver %i
+
 
ExecStop=/usr/bin/vncserver -kill %i
+
{{hc|~/.config/systemd/user/x0vncserver.service|2=
 +
[Unit]
 +
Description=Remote desktop service (VNC)
 +
 
 +
[Service]
 +
Type=simple
 +
# wait for Xorg started by ${USER}
 +
ExecStartPre=/bin/sh -c 'while ! pgrep -U "$USER" Xorg; do sleep 2; done'
 +
ExecStart=/usr/bin/x0vncserver -rfbauth /home/${USER}/.vnc/passwd
 +
# or login with your username & password
 +
#ExecStart=/usr/bin/x0vncserver -PAMService=login -PlainUsers=${USER} -SecurityTypes=TLSPlain
  
 
[Install]
 
[Install]
WantedBy=multi-user.target
+
WantedBy=default.target}}
</nowiki>}}
+
 
 +
[[Start]] and [[enable]] the service {{ic|x0vncserver.service}} in [[Systemd/User]] mode, i.e. with the {{ic|--user}} parameter.
 +
 
 +
{{Note|
 +
* 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.
 +
* You may need read man page for more detail. }}
 +
 
 +
== Connecting to vncserver ==
 +
{{Warning|It is ill-advised to connect insecurely to a vncserver outside of a trusted LAN. Note that TigerVNC is encrypted by default unless it is specifically instructed otherwise by setting {{ic|SecurityTypes}} to 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
 +
 
 +
=== Passwordless authentication ===
 +
 
 +
The {{ic|-passwd}} switch allows one to define the location of the server's {{ic|~/.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 ===
 +
 
 +
* {{Pkg|gtk-vnc}}
 +
* {{Pkg|krdc}}
 +
* {{Pkg|rdesktop}}
 +
* {{Pkg|vinagre}}
 +
* {{Pkg|remmina}}
 +
* {{Pkg|virt-viewer}}
 +
* {{AUR|vncviewer-jar}}
 +
 
 +
TigerVNC's vncviewer also has a simple GUI when run without any parameters:
 +
$ vncviewer
 +
 
 +
== 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.
 +
 
 +
{{Note|TigerVNC uses ''TLSVnc'' encryption by default, unless specifically instructed via the {{ic|SecurityTypes}} parameter. 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 {{ic|SecurityTypes}} on the server is set to a non-secure option as high-priority (such as ''None'', ''VncAuth'', ''Plain'', ''TLSNone'', ''TLSPlain'', ''X509None'', ''X509Plain''); which is ill-advised, then it is not possible to use encryption. In that case, one can tunnel over SSH.  When running ''vncviewer'', it is safer to explicitly set {{ic|SecurityTypes}} and not accept any unencrypted traffic.}}
 +
 
 +
=== On the server ===
 +
On the server side, ''vncserver'' must be run. It is recommended to use the {{ic|-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.
 +
For example run a command such as:
 +
$ 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 {{man|1|ssh}}.
 +
 
 +
$ 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 with the server. Alternatively, directly run SSH in the background using the {{ic|-f}} option. On the client side, to connect via this encrypted tunnel, point the ''vncviewer'' to the forwarded client port on the localhost.
 +
 
 +
In the matched ports scenario, using the local port 5901 which is forwarded to the same port 5901 on the server:
 +
$ vncviewer localhost:5901
 +
 
 +
If port numbers are different, for example if the local port 8900 has been forwarded to the server port 5901, connect locally to 8900:
 +
$ 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 {{ic|-localhost}} flag 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) ===
 +
Install {{AUR|dispmanx_vnc}} 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, [[wikipedia:Let's Encrypt|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 {{ic|-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''
 +
 
 +
=== Toggling Fullscreen ===
 +
This can be done through vncclient's Menu. By default, vncclient's Menu Key is F8.
 +
 
 +
== Troubleshooting ==
 +
=== Unable to type '<' character ===
 +
If pressing {{ic|<}} on a remote client emits the {{ic|>}} character, try remapping the incoming key [https://insaner.com/blog/2013/05.html#20130422063137]:
 +
 
 +
$ 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 {{ic|x0vncserver}}, start vncviewer as follows:
 +
 
 +
$ vncviewer DotWhenNoCursor=1 <server>
 +
 
 +
Or put {{ic|DotWhenNoCursor<nowiki>=</nowiki>1}} in the tigervnc configuration file, which is at {{ic|~/.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 {{ic|autocutsel}} on the server, as mentioned in [https://bbs.archlinux.org/viewtopic.php?id=101243]:
 +
 
 +
$ autocutsel -fork
 +
 
 +
Now press F8 to display the VNC menu popup, and select {{ic|Clipboard: local -> remote}} option.
 +
 
 +
One can put the above command in {{ic|~/.vnc/xstartup}} to have it run automatically when vncserver is started.
 +
 
 +
=== "Authentication is required to create a color managed device" dialog when launching GNOME 3 ===
 +
A workaround is to create a "vnc" group and add the gdm user and any other users using vnc to that group.
 +
Modify {{ic|/etc/polkit-1/rules.d/gnome-vnc.rules}} with the following[https://github.com/TurboVNC/turbovnc/issues/47]:
 +
 
 +
    polkit.addRule(function(action, subject) {
 +
      if ((action.id == "org.freedesktop.color-manager.create-device" ||
 +
            action.id == "org.freedesktop.color-manager.create-profile" ||
 +
            action.id == "org.freedesktop.color-manager.delete-device" ||
 +
            action.id == "org.freedesktop.color-manager.delete-profile" ||
 +
            action.id == "org.freedesktop.color-manager.modify-device" ||
 +
            action.id == "org.freedesktop.color-manager.modify-profile") &&
 +
          subject.isInGroup("vnc")) {
 +
          return polkit.Result.YES;
 +
      }
 +
    });
 +
 
 +
== See also ==
 +
* https://github.com/TigerVNC/tigervnc

Latest revision as of 17:22, 28 November 2018

TigerVNC is an implementation of the Virtual Network Computing (VNC) protocol. This article focuses on the server functionality.

Installation

Install the tigervnc package.

Two VNC servers are available with TigerVNC:

  1. 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 Xvnc(1) for the manual. vncserver is a wrapper script which eases the starting of Xvnc, see vncserver(1).
  2. 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 x0vncserver(1) 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.

$ vncserver
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

Note the :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.

Note: Linux systems can have as many VNC servers as memory allows, all of which will be running in parallel to each other.

To shutdown the just created VNC server, use the -kill switch:

$ vncserver -kill :1

Edit the environment file

The ~/.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. In this script, users are expected to start a Desktop environment, see: General recommendations#Desktop environments.

For example, starting Xfce:

~/.vnc/xstartup
#!/bin/sh
unset SESSION_MANAGER
unset DBUS_SESSION_BUS_ADDRESS
exec startxfce4

Some desktop environments may require D-Bus session. For example, starting GNOME:

~/.vnc/xstartup
#!/bin/sh
unset SESSION_MANAGER
unset DBUS_SESSION_BUS_ADDRESS
exec dbus-launch gnome-session

Make sure ~/.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:

~/.vnc/config
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.

User mode

Start and enable the service vncserver@:1.service in Systemd/User mode, i.e. with the --user parameter.

Note: The vncserver will get killed when the user logs off the machine, see Systemd/User#Automatic start-up of systemd user instances for related configuration.

System mode

Create /etc/systemd/system/vncserver@:1.service, where :1 is the 5900 port increment (5900 + 1) to which the VNC server will be listening for connections (e.g vncserver@:5.service means the server will be listening to port 5905). Edit the service unit by defining the user (User=) to run the server, and the desired Vncserver options.

/etc/systemd/system/vncserver@:1.service
[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
Note:
  • If you plan to use Xfce desktop environment on VNC server then D-Bus starting before VNC server may be required. Just add ExecStartPre=/usr/bin/dbus-launch entry in [Service] section of unit file.
  • Do not run this service if your local area network is untrusted.

Start vncserver@:1.service and optionally enable it to run at boot time/shutdown.

Multi-user mode

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:

/etc/systemd/system/xvnc.socket
[Unit]
Description=XVNC Server

[Socket]
ListenStream=5900
Accept=yes

[Install]
WantedBy=sockets.target
/etc/systemd/system/xvnc@.service
[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

Use systemctl to start and enable xvnc.socket. Now any number of users can get unique desktops by connecting to port 5900.

If the VNC server is exposed to the internet, add the -localhost option to Xvnc in 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:

/etc/X11/xinit/xinitrc.d/99-vncconfig.sh
#!/bin/sh
vncconfig -nowin &

Running vncserver to directly control the local display

As mentioned in #Installation, the tigervnc package also provides the x0vncserver binary which allows direct control over a physical X session. Invoke it like so:

$ x0vncserver -rfbauth ~/.vnc/passwd

For more information, see x0vncserver(1).

Tip: Another option is to use the x11vnc VNC server which also provides direct control of the current X session, note that x11vnc requires root privilege to initiate the access.

Starting and stopping x0vncserver via systemd

In order to have a VNC Server running 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:

~/.config/systemd/user/x0vncserver.service
[Unit]
Description=Remote desktop service (VNC)

[Service]
Type=simple
# wait for Xorg started by ${USER}
ExecStartPre=/bin/sh -c 'while ! pgrep -U "$USER" Xorg; do sleep 2; done'
ExecStart=/usr/bin/x0vncserver -rfbauth /home/${USER}/.vnc/passwd
# or login with your username & password
#ExecStart=/usr/bin/x0vncserver -PAMService=login -PlainUsers=${USER} -SecurityTypes=TLSPlain

[Install]
WantedBy=default.target

Start and enable the service x0vncserver.service in Systemd/User mode, i.e. with the --user parameter.

Note:
  • 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.
  • You may need read man page for more detail.

Connecting to vncserver

Warning: It is ill-advised to connect insecurely to a vncserver outside of a trusted LAN. Note that TigerVNC is encrypted by default unless it is specifically instructed otherwise by setting SecurityTypes to 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

Passwordless authentication

The -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:

$ vncviewer

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.

Note: TigerVNC uses TLSVnc encryption by default, unless specifically instructed via the SecurityTypes parameter. 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 SecurityTypes on the server is set to a non-secure option as high-priority (such as None, VncAuth, Plain, TLSNone, TLSPlain, X509None, X509Plain); which is ill-advised, then it is not possible to use encryption. In that case, one can tunnel over SSH. When running vncviewer, it is safer to explicitly set SecurityTypes and not accept any unencrypted traffic.

On the server

On the server side, vncserver must be run. It is 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. For example run a command such as:

$ 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(1).

$ 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 with the server. Alternatively, directly run SSH in the background using the -f option. On the client side, to connect via this encrypted tunnel, point the vncviewer to the forwarded client port on the localhost.

In the matched ports scenario, using the local port 5901 which is forwarded to the same port 5901 on the server:

$ vncviewer localhost:5901

If port numbers are different, for example if the local port 8900 has been forwarded to the server port 5901, connect locally to 8900:

$ 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:

  1. SSH running on the server
  2. vncserver running on server (with -localhost flag for security)
  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 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)

Install dispmanx_vncAUR 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

Toggling Fullscreen

This can be done through vncclient's Menu. By default, vncclient's Menu Key is F8.

Troubleshooting

Unable to type '<' character

If pressing < on a remote client emits the > character, try remapping the incoming key [1]:

$ 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>

Or put 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 [2]:

$ 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.

"Authentication is required to create a color managed device" dialog when launching GNOME 3

A workaround is to create a "vnc" group and add the gdm user and any other users using vnc to that group. Modify /etc/polkit-1/rules.d/gnome-vnc.rules with the following[3]:

   polkit.addRule(function(action, subject) {
      if ((action.id == "org.freedesktop.color-manager.create-device" ||
           action.id == "org.freedesktop.color-manager.create-profile" ||
           action.id == "org.freedesktop.color-manager.delete-device" ||
           action.id == "org.freedesktop.color-manager.delete-profile" ||
           action.id == "org.freedesktop.color-manager.modify-device" ||
           action.id == "org.freedesktop.color-manager.modify-profile") &&
          subject.isInGroup("vnc")) {
         return polkit.Result.YES;
      }
   });

See also