TigerVNC: Difference between revisions
Lahwaacz.bot (talk | contribs) (update http to https) |
Lahwaacz.bot (talk | contribs) (update Pkg/AUR templates) |
||
(44 intermediate revisions by 16 users not shown) | |||
Line 2: | Line 2: | ||
[[Category:Servers]] | [[Category:Servers]] | ||
[[de:VNC]] | [[de:VNC]] | ||
[[ja:TigerVNC]] | [[ja:TigerVNC]] | ||
[[ru:TigerVNC]] | |||
[[zh-hans:TigerVNC]] | [[zh-hans:TigerVNC]] | ||
{{Related articles start}} | {{Related articles start}} | ||
{{Related|x11vnc}} | {{Related|x11vnc}} | ||
{{Related|TurboVNC}} | |||
{{Related articles end}} | {{Related articles end}} | ||
Line 21: | Line 22: | ||
{{Note|Linux systems can have as many VNC servers as memory allows, all of which will be running in parallel to each other.}} | {{Note|Linux systems can have as many VNC servers as memory allows, all of which will be running in parallel to each other.}} | ||
For a quick start, see the steps below. Users are encouraged to read | For a quick start, see the steps below. Users are encouraged to read {{man|8|vncserver}} for the complete list of configuration options. | ||
# Create a password using {{ic|vncpasswd}} which will store the hashed password in {{ic|~/.vnc/passwd}}. | # Create a password using {{ic|vncpasswd}} which will store the hashed password in {{ic|~/.vnc/passwd}}. Ensure the file's permission is set to {{ic|0600}}. | ||
# Edit {{ic|/etc/tigervnc/vncserver.users}} to define user mappings. Each user defined in this file will have a corresponding port on which its session will run. The number in the file corresponds to a TCP port. By default, :1 is TCP port 5901 (5900+1). If another parallel server is needed, a second instance can then run on the next highest, free port, i.e 5902 (5900+2). | # Edit {{ic|/etc/tigervnc/vncserver.users}} to define user mappings. Each user defined in this file will have a corresponding port on which its session will run. The number in the file corresponds to a TCP port. By default, :1 is TCP port 5901 (5900+1). If another parallel server is needed, a second instance can then run on the next highest, free port, i.e 5902 (5900+2). | ||
# Create {{ic|~/.vnc/config}} and at a minimum, define the type of session desired with a line like {{ic|1=session=foo}} where foo corresponds to | # Create {{ic|~/.vnc/config}} and at a minimum, define the type of session desired with a line like {{ic|1=session=foo}} where foo corresponds to whichever [[desktop environment]] is to run. One can see which desktop environments are available on the system by seeing their corresponding ''.desktop'' files within {{ic|/usr/share/xsessions/}}. For example: | ||
For example: | |||
{{hc|~/.vnc/config|2= | {{hc|~/.vnc/config|2= | ||
Line 32: | Line 32: | ||
geometry=1920x1080 | geometry=1920x1080 | ||
localhost | localhost | ||
alwaysshared}} | alwaysshared | ||
}} | |||
{{Note|The previous step requires additional security setup to fully work; see [[#Accessing vncserver via SSH tunnels]] to complete the setup. For testing purposes, omit this step to allow unsecured connections from outside of localhost.}} | |||
=== Starting and stopping tigervnc === | === Starting and stopping tigervnc === | ||
[[Start]] {{ic|vncserver@.service}} and optionally [[enable]] it to run at boot time/shutdown. | [[Start]] an instance of the {{ic|vncserver@.service}} template and optionally [[enable]] it to run at boot time/shutdown. Note that the ''instance identifier'' in this case is the display number (e.g. instance {{ic|vncserver@:1.service}} for display number {{ic|:1}}). | ||
{{Note|Direct calls to {{ic|/usr/bin/vncserver}} are not supported as they will not establish a proper session scope. The ''systemd'' service is the only supported method of using TigerVNC. See: [https://github.com/TigerVNC/tigervnc/issues/1096 Issue #1096].}} | |||
{{Note| | {{Note|Remove drop-in service files created for earlier versions of TigerVNC before starting '''vncserver'''. Prior versions required drop-in service files for each display, e.g. for display :1 {{ic|/etc/systemd/system/vncserver@:1.service}}. '''vncserver''' will fail to start if the old drop-in file is present when you attempt to start with the new templated service file.}} | ||
== Expose the local display directly == | == Expose the local display directly == | ||
TigerVNC includes {{ic|libvnc.so}}, which can be seamlessly loaded during X initialization for enhanced performance. To utilize this feature, create the following file and then restart X: | |||
{{hc|/etc/X11/xorg.conf.d/10-vnc.conf| | {{hc|/etc/X11/xorg.conf.d/10-vnc.conf| | ||
Section "Module" | Section "Module" | ||
Line 54: | Line 58: | ||
Option "UserPasswdVerifier" "VncAuth" | Option "UserPasswdVerifier" "VncAuth" | ||
Option "PasswordFile" "/root/.vnc/passwd" | Option "PasswordFile" "/root/.vnc/passwd" | ||
EndSection}} | EndSection | ||
}} | |||
== Running x0vncserver to directly control the local display == | == Running x0vncserver to directly control the local display == | ||
{{ | {{Pkg|tigervnc}} also provides {{man|1|x0vncserver}} which allows direct control over a physical X session. After defining a session password using the ''vncpasswd'' tool, invoke the server like so: | ||
$ x0vncserver -rfbauth ~/.vnc/passwd | $ x0vncserver -rfbauth ~/.vnc/passwd | ||
{{Note| | {{Note| | ||
* [[x11vnc]] is an alternative VNC server which can also provide direct control of the current X session. | * [[x11vnc]] is an alternative VNC server which can also provide direct control of the current X session. | ||
* {{ic|x0vncserver}} does not currently support clipboard sharing between the client and the server (even with the help of {{ic|autocutsel}}). See: [https://github.com/TigerVNC/tigervnc/issues/529 Issue #529].}} | * {{ic|x0vncserver}} does not currently support clipboard sharing between the client and the server (even with the help of {{ic|autocutsel}}). See: [https://github.com/TigerVNC/tigervnc/issues/529 Issue #529]. | ||
}} | |||
=== | === With xprofile === | ||
A simple way to start ''x0vncserver'' is adding a line in one of the [[xprofile]] files such as: | A simple way to start ''x0vncserver'' is adding a line in one of the [[xprofile]] files such as: | ||
Line 73: | Line 78: | ||
{{hc|~/.xprofile| | {{hc|~/.xprofile| | ||
... | ... | ||
x0vncserver -rfbauth ~/.vnc/passwd &}} | x0vncserver -rfbauth ~/.vnc/passwd & | ||
}} | |||
=== With systemd === | |||
==== With a system service ==== | |||
This option will allow the users to access the current display, including the login screen provided by your display manager. | |||
The service will be relaunched automatically every time an user logs off of their session. | |||
[[LightDM]] is used for the example below, but it should be possible to adapt it to other display managers by modifying the {{ic|XAUTHORITY}} variable. | |||
{{hc|/etc/systemd/system/x0vncserver.service|2= | |||
[Unit] | |||
Description=Remote desktop service (VNC) for :0 display | |||
Requires=display-manager.service | |||
After=network-online.target | |||
After=display-manager.service | |||
[Service] | |||
Type=simple | |||
Environment=HOME=/root | |||
Environment=XAUTHORITY=/var/run/lightdm/root/:0 | |||
ExecStart=x0vncserver -display :0 -rfbauth ~/.vnc/passwd | |||
Restart=on-failure | |||
RestartSec=500ms | |||
[Install] | |||
WantedBy=multi-user.target | |||
}} | |||
As this is a system unit, {{ic|-rfbauth ~/.vnc/passwd}} refers to {{ic|/root/.vnc/passwd}} | |||
[[Start/enable]] {{ic|x0vncserver.service}}. | |||
=== | ==== With a user service ==== | ||
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, create a systemd unit as follows replacing the user and the options with the desired ones: | 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, create a ''systemd'' unit as follows replacing the user and the options with the desired ones: | ||
{{hc|~/.config/systemd/user/x0vncserver.service|2= | {{hc|~/.config/systemd/user/x0vncserver.service|2= | ||
Line 85: | Line 124: | ||
[Service] | [Service] | ||
Type=simple | Type=simple | ||
ExecStartPre=/bin/sh -c 'while ! pgrep -U "$USER" Xorg; do sleep 2; done' | ExecStartPre=/bin/sh -c 'while ! pgrep -U "$USER" Xorg; do sleep 2; done' | ||
ExecStart=/usr/bin/x0vncserver -rfbauth %h/.vnc/passwd | ExecStart=/usr/bin/x0vncserver -rfbauth %h/.vnc/passwd | ||
[Install] | [Install] | ||
WantedBy=default.target}} | WantedBy=default.target | ||
}} | |||
The {{ic|ExecStartPre}} line waits for Xorg to be started by {{ic|${USER}<nowiki/>}}. | |||
To login with your username and password, replace {{ic|ExecStart}} by {{ic|1=/usr/bin/x0vncserver -PAMService=login -PlainUsers=${USER} -SecurityTypes=TLSPlain}}. | |||
[[Start | [[Start/enable]] the {{ic|x0vncserver.service}} [[user unit]]. | ||
== Running Xvnc with XDMCP for on demand sessions == | == Running Xvnc with XDMCP for on demand sessions == | ||
Line 102: | Line 143: | ||
To get this running, first set up [[XDMCP]] and make sure the display manager is running. | To get this running, first set up [[XDMCP]] and make sure the display manager is running. | ||
Then create: | Then create: | ||
{{hc|/etc/systemd/system/xvnc.socket|2= | {{hc|/etc/systemd/system/xvnc.socket|2= | ||
[Unit] | [Unit] | ||
Line 111: | Line 153: | ||
[Install] | [Install] | ||
WantedBy=sockets.target}} | WantedBy=sockets.target | ||
}} | |||
{{hc|/etc/systemd/system/xvnc@.service|2= | {{hc|/etc/systemd/system/xvnc@.service|2= | ||
[Unit] | [Unit] | ||
Line 120: | Line 164: | ||
User=nobody | User=nobody | ||
StandardInput=socket | StandardInput=socket | ||
StandardError=syslog}} | StandardError=syslog | ||
}} | |||
[[Start/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: | 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| | {{hc|/etc/X11/xinit/xinitrc.d/99-vncconfig.sh| | ||
#!/bin/sh | #!/bin/sh | ||
vncconfig -nowin &}} | vncconfig -nowin & | ||
}} | |||
== Connecting to vncserver == | == Connecting to vncserver == | ||
{{Warning|The default's TigerVNC security method is not secure | {{Warning|The default's TigerVNC security method is not secure. It lacks identity verification and will not prevent man-in-the-middle attack during the connection setup. Make sure you understand the security settings of your server and do not connect insecurely to a vncserver outside of a trusted LAN.}} | ||
{{Note|By default, TigerVNC uses the ''TLSVnc'' authentication/encryption method unless specifically instructed via the {{ic|SecurityTypes}} parameter. With ''TLSVnc'', there is standard VNC authentication and traffic is encrypted with GNUTLS but the identity of the server is not verified. TigerVNC supports alternative security schemes such as ''X509Vnc'' that combines standard VNC authentication with GNUTLS encryption and server identification | {{Note|By default, TigerVNC uses the ''TLSVnc'' authentication/encryption method unless specifically instructed via the {{ic|SecurityTypes}} parameter. With ''TLSVnc'', there is standard VNC authentication and traffic is encrypted with GNUTLS but the identity of the server is not verified. TigerVNC supports alternative security schemes such as ''X509Vnc'' that combines standard VNC authentication with GNUTLS encryption and server identification; this is the recommended mode for a secure connection. | ||
When {{ic|SecurityTypes}} on the server is set to a non-encrypted option as high-priority (such as ''None'', ''VncAuth'', ''Plain'', ''TLSNone'', ''TLSPlain'', ''X509None'', ''X509Plain'') | When {{ic|SecurityTypes}} on the server is set to a non-encrypted 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. When running ''vncviewer'', it is safer to explicitly set {{ic|SecurityTypes}} and not accept any unencrypted traffic. Any other mode is to be used only when [[#Accessing vncserver via SSH tunnels]]. }} | ||
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: | 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: | ||
Line 141: | Line 189: | ||
=== Passwordless authentication === | === Passwordless authentication === | ||
The {{ic|-passwd}} switch | The {{ic|-passwd}} switch enables one to specify the location of the server's {{ic|~/.vnc/passwd}} file. This file is expected to be accessible to the user through [[SSH]] or physical access to the server. In either case, place the file on the client's file system in a safe location, i.e. one in which only the intended user has read access. | ||
$ vncviewer -passwd ''/path/to/server-passwd-file'' | $ vncviewer -passwd ''/path/to/server-passwd-file'' | ||
Line 158: | Line 206: | ||
* [[remmina]] | * [[remmina]] | ||
* {{Pkg|virt-viewer}} | * {{Pkg|virt-viewer}} | ||
* {{AUR|vncviewer-jar}} | * {{AUR|vncviewer-jar}}{{Broken package link|package not found}} | ||
TigerVNC's vncviewer also has a simple GUI when run without any parameters: | TigerVNC's vncviewer also has a simple GUI when run without any parameters: | ||
$ vncviewer | $ vncviewer | ||
Line 177: | Line 226: | ||
geometry=1920x1080 | geometry=1920x1080 | ||
localhost | localhost | ||
alwaysshared}} | alwaysshared | ||
}} | |||
Make sure to [[Start]] or [[Restart]] the {{ic|vncserver@.service}}, for example (see also [[#Initial setup]]): | Make sure to [[Start]] or [[Restart]] the {{ic|vncserver@.service}}, for example (see also [[#Initial setup]]): | ||
# systemctl start vncserver@:1 | # systemctl start vncserver@:1 | ||
or for ''x0vncserver'': | or for ''x0vncserver'': | ||
$ x0vncserver '''-localhost''' -SecurityTypes none | $ x0vncserver '''-localhost''' -SecurityTypes none | ||
Line 200: | Line 252: | ||
{{Tip|It is possible, with a one-liner, to keep the port forwarding active during the connection and close it right after: | {{Tip|It is possible, with a one-liner, to keep the port forwarding active during the connection and close it right after: | ||
{{bc|$ ssh -fL 9901:localhost:5901 10.1.10.2 sleep 10; vncviewer localhost:9901}} | {{bc|$ ssh -fL 9901:localhost:5901 10.1.10.2 sleep 10; vncviewer localhost:9901}} | ||
What it does is that the {{ic|-f}} switch will make ssh go in the background | What it does is that the {{ic|-f}} switch will make ssh go in the background; it will still be alive executing {{ic|sleep 10}}. vncviewer is then executed and ssh remains open in the background as long as vncviewer makes use of the tunnel. ssh will close once the tunnel is dropped which is the wanted behavior. | ||
Alternatively, vncviewer's {{ic|-via}} switch provides a shortcut for the above command: | Alternatively, vncviewer's {{ic|-via}} switch provides a shortcut for the above command: | ||
Line 210: | Line 262: | ||
To connect to a VNC server over SSH using an Android device as a client, consider having the following setup: | 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 | # SSH running on the server | ||
# vncserver running on server (with {{ic|-localhost}} flag for security) | # vncserver running on server (with {{ic|-localhost}} flag for security) | ||
Line 216: | Line 269: | ||
In ''ConnectBot'', connect to the desired machine. Tap the options key, select ''Port Forwards'' and add a port: | In ''ConnectBot'', connect to the desired machine. Tap the options key, select ''Port Forwards'' and add a port: | ||
Type: Local | Type: Local | ||
Source port: 5901 | Source port: 5901 | ||
Destination: 127.0.0.1:5901 | Destination: 127.0.0.1:5901 | ||
In ''androidVNC'' connect to the VNC port | In ''androidVNC'', connect to the VNC port; this is the local address following the SSH connection: | ||
Password: the vncserver password | Password: the vncserver password | ||
Address: 127.0.0.1 | Address: 127.0.0.1 | ||
Line 227: | Line 282: | ||
== Tips and tricks == | == Tips and tricks == | ||
=== Connecting to | === Connecting to a macOS system === | ||
See https://help.ubuntu.com/community/AppleRemoteDesktop. Tested with Remmina. | See https://help.ubuntu.com/community/AppleRemoteDesktop. Tested with Remmina. | ||
Line 238: | Line 293: | ||
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: | 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'' | $ vncviewer 10.1.10.2 -X509CA ''/path/to/cert.pem'' | ||
Line 246: | Line 302: | ||
=== Workaround for mouse back and forward buttons not working === | === Workaround for mouse back and forward buttons not working === | ||
The VNC protocol currently only uses 7 mouse buttons (left, middle, right, scroll up, scroll down, scroll left, scroll right) which means if your mouse has a back and a forward button these are not usable and input will be ignored. | The VNC protocol currently only uses 7 mouse buttons (left, middle, right, scroll up, scroll down, scroll left, scroll right) which means if your mouse has a back and a forward button, these are not usable and input will be ignored. | ||
[https://www.bedroomlan.org/projects/evrouter/ evrouter] can be used to work around this limitation by sending keyboard key presses when clicking the mouse back/forward buttons. Optionally xte found in {{Pkg|xautomation}} and {{Pkg|xbindkeys}} can be used on the server to map the keyboard key presses back to mouse button clicks if needed. | [https://www.bedroomlan.org/projects/evrouter/ evrouter] can be used to work around this limitation by sending keyboard key presses when clicking the mouse back/forward buttons. Optionally, xte found in {{Pkg|xautomation}} and {{Pkg|xbindkeys}} can be used on the server to map the keyboard key presses back to mouse button clicks if needed. | ||
==== Substituting mouse back/forward buttons with keyboard keys XF86Back/XF86Forward ==== | ==== Substituting mouse back/forward buttons with keyboard keys XF86Back/XF86Forward ==== | ||
Line 255: | Line 311: | ||
Install {{AUR|evrouter}} and {{Pkg|xautomation}} on the client. Configure evrouter, see [[Mouse buttons#evrouter]] and evrouter man pages for instructions and tips on how to find the correct device name, window name, button names etc. Example config: | Install {{AUR|evrouter}} and {{Pkg|xautomation}} on the client. Configure evrouter, see [[Mouse buttons#evrouter]] and evrouter man pages for instructions and tips on how to find the correct device name, window name, button names etc. Example config: | ||
{{hc|~/.evrouterrc|Window "OtherComputer:0 - TigerVNC": # Window title used as filter | |||
{{hc|~/.evrouterrc| | |||
Window "OtherComputer:0 - TigerVNC": # Window title used as filter | |||
# Using Shell to avoid repeating key presses (see evrouter manual) | # Using Shell to avoid repeating key presses (see evrouter manual) | ||
"USB mouse" "/dev/input/by-id/usb-Mouse-name-event-mouse" none key/275 "Shell/xte 'key XF86Back'" | "USB mouse" "/dev/input/by-id/usb-Mouse-name-event-mouse" none key/275 "Shell/xte 'key XF86Back'" | ||
"USB | "USB mouse" "/dev/input/by-id/usb-Mouse-name-event-mouse" none key/276 "Shell/xte 'key XF86Forward'" | ||
# Use XKey below instead if repeating keys is desired (see evrouter manual) | # Use XKey below instead if repeating keys is desired (see evrouter manual) | ||
#"Logitech Gaming Mouse G400" "/dev/input/by-id/usb-Logitech_Gaming_Mouse_G400-event-mouse" none key/275 "XKey/XF86Back" | #"Logitech Gaming Mouse G400" "/dev/input/by-id/usb-Logitech_Gaming_Mouse_G400-event-mouse" none key/275 "XKey/XF86Back" | ||
#"Logitech Gaming Mouse G400" "/dev/input/by-id/usb-Logitech_Gaming_Mouse_G400-event-mouse" none key/276 "XKey/XF86Forward"}} | #"Logitech Gaming Mouse G400" "/dev/input/by-id/usb-Logitech_Gaming_Mouse_G400-event-mouse" none key/276 "XKey/XF86Forward" | ||
}} | |||
Start evrouter on the client. With above configuration keyboard key XF86Back is sent to the VNC server when clicking the back button on the mouse, and XF86Forward is sent when clicking the forward button. | Start evrouter on the client. With above configuration keyboard key {{ic|XF86Back}} is sent to the VNC server when clicking the back button on the mouse, and {{ic|XF86Forward}} is sent when clicking the forward button. | ||
==== Mapping the keyboard key presses back to mouse button clicks on the server ==== | ==== Mapping the keyboard key presses back to mouse button clicks on the server ==== | ||
If needed it | If needed, it is possible to map the keyboard keys back to mouse button clicks on the server. In this case, it might be a good idea to use keyboard keys which are never on the client or server. In the example below, keyboard keys {{ic|XF86Launch8}}/{{ic|XF86Launch9}} are used as mouse buttons 8/9. | ||
Evrouter configuration on the client: | Evrouter configuration on the client: | ||
{{hc|~/.evrouterrc|Window "OtherComputer:0 - TigerVNC": # Window title | |||
{{hc|~/.evrouterrc| | |||
Window "OtherComputer:0 - TigerVNC": # Window title | |||
# Using Shell to avoid repeating key presses (see evrouter manual) | # Using Shell to avoid repeating key presses (see evrouter manual) | ||
"USB mouse" "/dev/input/by-id/usb-Mouse-name-event-mouse" none key/275 "Shell/xte 'key XF86Launch8'" | "USB mouse" "/dev/input/by-id/usb-Mouse-name-event-mouse" none key/275 "Shell/xte 'key XF86Launch8'" | ||
"USB | "USB mouse" "/dev/input/by-id/usb-Mouse-name-event-mouse" none key/276 "Shell/xte 'key XF86Launch9'" | ||
}} | |||
Install {{Pkg|xautomation}} and {{Pkg|xbindkeys}} on the server. Configure xbindkeys to map keyboard keys {{ic|XF86Launch8}}/{{ic|XF86Launch9}} to mouse buttons 8/9 with xte. | |||
{{hc|~/.xbindkeysrc| | {{hc|~/.xbindkeysrc| | ||
"xte 'mouseclick 8'" | "xte 'mouseclick 8'" | ||
Line 286: | Line 349: | ||
XF86Launch9 | XF86Launch9 | ||
}} | }} | ||
Start xbindkeys {{ic| | |||
Start xbindkeys ({{ic|xbindkeys -f ~/.xbindkeysrc}}). The server will now map {{ic|XF86Launch8}}/{{ic|XF86Launch9}} to mouse buttons 8/9. | |||
== Troubleshooting == | == Troubleshooting == | ||
=== Black rectangle instead of window === | === Black rectangle instead of window === | ||
Most probably this is due to the application strictly requiring the composite Xorg extension. For example webkit based app: midori, psi-plus, etc. | Most probably, this is due to the application strictly requiring the composite Xorg extension. For example webkit based app: midori, psi-plus, etc. | ||
Restart vncserver in this case using something like following: | Restart vncserver in this case using something like following: | ||
Line 309: | Line 363: | ||
It looks like Composite extension in VNC will work only with 24bit depth. | It looks like Composite extension in VNC will work only with 24bit depth. | ||
=== Empty black window with mouse cursor or xinit: connection to X server lost=== | |||
Verify that the user is not logged into a physical X session, unless this option was configured with {{ic|x0vncserver}}. Multiple X sessions for a single user are not supported, see [https://github.com/TigerVNC/tigervnc/issues/684#issuecomment-494385395 684#issuecomment-494385395] and [https://github.com/TigerVNC/tigervnc/issues/1634 #1634]. | |||
Conversely, trying to log into a local X session while a VNC server service is running for that user will likely not work, and you may get stuck on a splash screen when using a desktop environment. | |||
=== No mouse cursor === | === No mouse cursor === | ||
If no mouse cursor is visible when using | If no mouse cursor is visible when using ''x0vncserver'', start ''vncviewer'' as follows: | ||
$ vncviewer DotWhenNoCursor=1 | $ vncviewer DotWhenNoCursor=1 ''server'' | ||
Alternatively, put {{ic|1=DotWhenNoCursor=1}} in the TigerVNC configuration file, which is at {{ic|~/.vnc/default.tigervnc}} by default. | |||
=== Copying clipboard content from the remote machine === | === Copying clipboard content from the remote machine === | ||
Line 324: | Line 384: | ||
$ autocutsel -fork | $ autocutsel -fork | ||
Now press F8 to display the VNC menu popup, and select {{ic|Clipboard: local -> remote}} option. | Now, press {{ic|F8}} to display the VNC menu popup, and select {{ic|Clipboard: local -> remote}} option. | ||
=== No window decoration / borders / titlebars / cannot move windows around === | === No window decoration / borders / titlebars / cannot move windows around === | ||
Start a window manager to fix an empty xterm frame. | Start a window manager to fix an empty [[xterm]] frame. For example, on [[Xfce]], run {{ic|xfwm4 &}}. | ||
=== Desktop environment is displaying only boxes for font === | |||
Some [[desktop environment]]s might be missing necessary font to display ASCII characters. [[Install]] {{pkg|ttf-dejavu}}. | |||
== See also == | == See also == | ||
* https://github.com/TigerVNC/tigervnc | * https://github.com/TigerVNC/tigervnc |
Latest revision as of 21:36, 28 February 2024
TigerVNC is an implementation of the Virtual Network Computing (VNC) protocol. This article focuses on the server functionality.
Installation
Running vncserver for virtual (headless) sessions
Initial setup
For a quick start, see the steps below. Users are encouraged to read vncserver(8) for the complete list of configuration options.
- Create a password using
vncpasswd
which will store the hashed password in~/.vnc/passwd
. Ensure the file's permission is set to0600
. - Edit
/etc/tigervnc/vncserver.users
to define user mappings. Each user defined in this file will have a corresponding port on which its session will run. The number in the file corresponds to a TCP port. By default, :1 is TCP port 5901 (5900+1). If another parallel server is needed, a second instance can then run on the next highest, free port, i.e 5902 (5900+2). - Create
~/.vnc/config
and at a minimum, define the type of session desired with a line likesession=foo
where foo corresponds to whichever desktop environment is to run. One can see which desktop environments are available on the system by seeing their corresponding .desktop files within/usr/share/xsessions/
. For example:
~/.vnc/config
session=lxqt geometry=1920x1080 localhost alwaysshared
Starting and stopping tigervnc
Start an instance of the vncserver@.service
template and optionally enable it to run at boot time/shutdown. Note that the instance identifier in this case is the display number (e.g. instance vncserver@:1.service
for display number :1
).
/usr/bin/vncserver
are not supported as they will not establish a proper session scope. The systemd service is the only supported method of using TigerVNC. See: Issue #1096./etc/systemd/system/vncserver@:1.service
. vncserver will fail to start if the old drop-in file is present when you attempt to start with the new templated service file.Expose the local display directly
TigerVNC includes libvnc.so
, which can be seamlessly loaded during X initialization for enhanced performance. To utilize this feature, create the following file and then restart X:
/etc/X11/xorg.conf.d/10-vnc.conf
Section "Module" Load "vnc" EndSection Section "Screen" Identifier "Screen0" Option "UserPasswdVerifier" "VncAuth" Option "PasswordFile" "/root/.vnc/passwd" EndSection
Running x0vncserver to directly control the local display
tigervnc also provides x0vncserver(1) which allows direct control over a physical X session. After defining a session password using the vncpasswd tool, invoke the server like so:
$ x0vncserver -rfbauth ~/.vnc/passwd
- x11vnc is an alternative VNC server which can also provide direct control of the current X session.
x0vncserver
does not currently support clipboard sharing between the client and the server (even with the help ofautocutsel
). See: Issue #529.
With xprofile
A simple way to start x0vncserver is adding a line in one of the xprofile files such as:
~/.xprofile
... x0vncserver -rfbauth ~/.vnc/passwd &
With systemd
With a system service
This option will allow the users to access the current display, including the login screen provided by your display manager.
The service will be relaunched automatically every time an user logs off of their session.
LightDM is used for the example below, but it should be possible to adapt it to other display managers by modifying the XAUTHORITY
variable.
/etc/systemd/system/x0vncserver.service
[Unit] Description=Remote desktop service (VNC) for :0 display Requires=display-manager.service After=network-online.target After=display-manager.service [Service] Type=simple Environment=HOME=/root Environment=XAUTHORITY=/var/run/lightdm/root/:0 ExecStart=x0vncserver -display :0 -rfbauth ~/.vnc/passwd Restart=on-failure RestartSec=500ms [Install] WantedBy=multi-user.target
As this is a system unit, -rfbauth ~/.vnc/passwd
refers to /root/.vnc/passwd
Start/enable x0vncserver.service
.
With a user service
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, 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 ExecStartPre=/bin/sh -c 'while ! pgrep -U "$USER" Xorg; do sleep 2; done' ExecStart=/usr/bin/x0vncserver -rfbauth %h/.vnc/passwd [Install] WantedBy=default.target
The ExecStartPre
line waits for Xorg to be started by ${USER}
.
To login with your username and password, replace ExecStart
by /usr/bin/x0vncserver -PAMService=login -PlainUsers=${USER} -SecurityTypes=TLSPlain
.
Start/enable the x0vncserver.service
user unit.
Running Xvnc with XDMCP for on demand sessions
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
Start/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 &
Connecting to vncserver
SecurityTypes
parameter. With TLSVnc, there is standard VNC authentication and traffic is encrypted with GNUTLS but the identity of the server is not verified. TigerVNC supports alternative security schemes such as X509Vnc that combines standard VNC authentication with GNUTLS encryption and server identification; this is the recommended mode for a secure connection.
When SecurityTypes
on the server is set to a non-encrypted 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. When running vncviewer, it is safer to explicitly set SecurityTypes
and not accept any unencrypted traffic. Any other mode is to be used only when #Accessing vncserver via SSH tunnels. 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 enables one to specify the location of the server's ~/.vnc/passwd
file. This file is expected to be accessible to the user through SSH or physical access to the server. In either case, place the file on the client's file system in a safe location, i.e. one in which only the intended user has read access.
$ vncviewer -passwd /path/to/server-passwd-file
The password can also be provided directly.
ps
on the machine will see it.$ vncviewer -passwd <(echo MYPASSWORD | vncpasswd -f)
Example GUI-based clients
- gtk-vnc
- krdc
- vinagre
- remmina
- virt-viewer
- vncviewer-jarAUR[broken link: package not found]
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.
On the server
On the server side, vncserver or x0vncserver must be run.
When running either one of these, it is recommended to use the localhost
option in ~/.vnc/config
or the -localhost
switch (for x0vncserver) since it allows connections from the localhost only and by analogy, only from users ssh'ed and authenticated on the box. For example:
~/.vnc/config
session=lxqt geometry=1920x1080 localhost alwaysshared
Make sure to Start or Restart the vncserver@.service
, for example (see also #Initial setup):
# systemctl start vncserver@:1
or for x0vncserver:
$ x0vncserver -localhost -SecurityTypes none
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, for instance 9901, to the remote server 5901 port. For more details on this feature, see OpenSSH#Forwarding other ports and ssh(1).
$ ssh 10.1.10.2 -L 9901: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.
$ vncviewer localhost:9901
What happens in practice is that the vncviewer connects locally to port 9901 which is tunneled to the server's localhost port 5901. The connection is established to the right port within the secure shell.
$ ssh -fL 9901:localhost:5901 10.1.10.2 sleep 10; vncviewer localhost:9901
What it does is that the -f
switch will make ssh go in the background; it will still be alive executing sleep 10
. vncviewer is then executed and ssh remains open in the background as long as vncviewer makes use of the tunnel. ssh will close once the tunnel is dropped which is the wanted behavior.
Alternatively, vncviewer's -via
switch provides a shortcut for the above command:
$ vncviewer -via 10.1.10.2 localhost::5901
(Notice the double colon – vncviewer's syntax is [host]:[display#]
or [host]::[port]
.)
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
-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 a macOS system
See https://help.ubuntu.com/community/AppleRemoteDesktop. Tested with Remmina.
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 vnc client's menu. By default, vnc client's mkey is F8
.
Workaround for mouse back and forward buttons not working
The VNC protocol currently only uses 7 mouse buttons (left, middle, right, scroll up, scroll down, scroll left, scroll right) which means if your mouse has a back and a forward button, these are not usable and input will be ignored.
evrouter can be used to work around this limitation by sending keyboard key presses when clicking the mouse back/forward buttons. Optionally, xte found in xautomation and xbindkeys can be used on the server to map the keyboard key presses back to mouse button clicks if needed.
Substituting mouse back/forward buttons with keyboard keys XF86Back/XF86Forward
This method is simple and suitable if you only need a way to navigate backward/forward while using web browsers or file browsers for example.
Install evrouterAUR and xautomation on the client. Configure evrouter, see Mouse buttons#evrouter and evrouter man pages for instructions and tips on how to find the correct device name, window name, button names etc. Example config:
~/.evrouterrc
Window "OtherComputer:0 - TigerVNC": # Window title used as filter # Using Shell to avoid repeating key presses (see evrouter manual) "USB mouse" "/dev/input/by-id/usb-Mouse-name-event-mouse" none key/275 "Shell/xte 'key XF86Back'" "USB mouse" "/dev/input/by-id/usb-Mouse-name-event-mouse" none key/276 "Shell/xte 'key XF86Forward'" # Use XKey below instead if repeating keys is desired (see evrouter manual) #"Logitech Gaming Mouse G400" "/dev/input/by-id/usb-Logitech_Gaming_Mouse_G400-event-mouse" none key/275 "XKey/XF86Back" #"Logitech Gaming Mouse G400" "/dev/input/by-id/usb-Logitech_Gaming_Mouse_G400-event-mouse" none key/276 "XKey/XF86Forward"
Start evrouter on the client. With above configuration keyboard key XF86Back
is sent to the VNC server when clicking the back button on the mouse, and XF86Forward
is sent when clicking the forward button.
Mapping the keyboard key presses back to mouse button clicks on the server
If needed, it is possible to map the keyboard keys back to mouse button clicks on the server. In this case, it might be a good idea to use keyboard keys which are never on the client or server. In the example below, keyboard keys XF86Launch8
/XF86Launch9
are used as mouse buttons 8/9.
Evrouter configuration on the client:
~/.evrouterrc
Window "OtherComputer:0 - TigerVNC": # Window title # Using Shell to avoid repeating key presses (see evrouter manual) "USB mouse" "/dev/input/by-id/usb-Mouse-name-event-mouse" none key/275 "Shell/xte 'key XF86Launch8'" "USB mouse" "/dev/input/by-id/usb-Mouse-name-event-mouse" none key/276 "Shell/xte 'key XF86Launch9'"
Install xautomation and xbindkeys on the server. Configure xbindkeys to map keyboard keys XF86Launch8
/XF86Launch9
to mouse buttons 8/9 with xte.
~/.xbindkeysrc
"xte 'mouseclick 8'" XF86Launch8 "xte 'mouseclick 9'" XF86Launch9
Start xbindkeys (xbindkeys -f ~/.xbindkeysrc
). The server will now map XF86Launch8
/XF86Launch9
to mouse buttons 8/9.
Troubleshooting
Black rectangle instead of window
Most probably, this is due to the application strictly requiring the composite Xorg extension. For example webkit based app: midori, psi-plus, etc.
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.
Empty black window with mouse cursor or xinit: connection to X server lost
Verify that the user is not logged into a physical X session, unless this option was configured with x0vncserver
. Multiple X sessions for a single user are not supported, see 684#issuecomment-494385395 and #1634.
Conversely, trying to log into a local X session while a VNC server service is running for that user will likely not work, and you may get stuck on a splash screen when using a desktop environment.
No mouse cursor
If no mouse cursor is visible when using x0vncserver, start vncviewer as follows:
$ vncviewer DotWhenNoCursor=1 server
Alternatively, 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 [1]:
$ autocutsel -fork
Now, press F8
to display the VNC menu popup, and select Clipboard: local -> remote
option.
No window decoration / borders / titlebars / cannot move windows around
Start a window manager to fix an empty xterm frame. For example, on Xfce, run xfwm4 &
.
Desktop environment is displaying only boxes for font
Some desktop environments might be missing necessary font to display ASCII characters. Install ttf-dejavu.