Set Up Apache Guacamole Remote Desktop on Ubuntu 22.04/20.04 Server
This tutorial will be showing you how to set up Guacamole remote desktop on Ubuntu 22.04/20.04 server. Guacamole is a free, open-source remote desktop gateway developed by the Apache software foundation.
Guacamole Features
- It allows you to access your remote desktop from a web browser. No other software needs to be installed on the client-side.
- Supports standard protocols like VNC, RDP, SSH and Kubernetes.
- VNC sessions can be recorded graphically.
- Single Sign-on with CAS, OpenID Connect or SAML 2.0
- Wake-on-LAN
- Easily manage multiple remote desktop sessions.
- Supports TOTP two-factor authentication.
- Supports clipboard (copy and paste) and file transfer via SFTP.
- Supports audio input and output
- and more.
Guacamole itself is not a remote desktop protocol. It’s a proxy between the remote desktop and the client, so the remote desktop can be displayed and controlled in a web browser.
Step 1: Build the Guacamole Server From Source
Log in to your Ubuntu 22.04/20.04 server and install dependency packages.
sudo apt update sudo apt install build-essential libcairo2-dev libjpeg-turbo8-dev libpng-dev libtool-bin libossp-uuid-dev libvncserver-dev freerdp2-dev libssh2-1-dev libtelnet-dev libwebsockets-dev libpulse-dev libvorbis-dev libwebp-dev libssl-dev libpango1.0-dev libswscale-dev libavcodec-dev libavutil-dev libavformat-dev
Download the latest stable version of guacamole-server.
wget https://dlcdn.apache.org/guacamole/1.4.0/source/guacamole-server-1.4.0.tar.gz
Extract the archive.
tar -xvf guacamole-server-1.4.0.tar.gz
Change to the extracted directory.
cd guacamole-server-1.4.0
Configure the build environment.
./configure --with-init-dir=/etc/init.d
Then compile guacamole-server.
sudo make
Install the guacamole-server.
sudo make install
Update the system’s cache of installed libraries.
sudo ldconfig
Reload systemd, so it can find the guacd (Guacamole proxy daemon) service installed in /etc/init.d/ directory.
sudo systemctl daemon-reload
Start the guacd service.
sudo systemctl start guacd
Enable auto-start at boot time.
sudo systemctl enable guacd
Check its status.
systemctl status guacd
As you can see, it’s active (running).
Guacd listens on 127.0.0.1:4822, as can be shown with the ss utility.
sudo ss -lnpt | grep guacd
Step 2: Install the Guacamole Web Application
The Guacamole web application is written in Java, so we need to install a Java Servlet container like Apache Tomcat.
sudo apt install tomcat9 tomcat9-admin tomcat9-common tomcat9-user
Apache Tomcat will listen on port 8080, as can been shown with:
sudo ss -lnpt | grep java
If you have other software that listens on port 8080, then Tomcat can’t bind to port 8080. You should configure the other process to use a different port, then restart Tomcat (sudo systemctl restart tomcat9).
Next, download the Guacamole web application.
wget https://downloads.apache.org/guacamole/1.4.0/binary/guacamole-1.4.0.war
Move the file to the web application directory (/var/lib/tomcat9/webapps) and rename the file at the same time (delete the version number).
sudo mv guacamole-1.4.0.war /var/lib/tomcat9/webapps/guacamole.war
Restart Tomcat and guacd.
sudo systemctl restart tomcat9 guacd
Step 3: Configure Guacamole
Create a configuration directory for Guacamole.
sudo mkdir /etc/guacamole/
Create a configuration file.
sudo nano /etc/guacamole/guacamole.properties
Add the following lines in this file. Some folks might say you don’t need to add these lines because they are the default values. I show you a basic configuration, so you can customize it when the need arises.
# Hostname and port of guacamole proxy guacd-hostname: localhost guacd-port: 4822 # Auth provider class (authenticates user/pass combination, needed if using the provided login screen) auth-provider: net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider basic-user-mapping: /etc/guacamole/user-mapping.xml
Save and close the file. The default authentication module in Guacamole reads usernames and passwords from an XML file: /etc/guacamole/user-mapping.xml. Before creating this file, we need to generate an MD5 hash for your password with the following command. Replace your_password with your preferred password.
echo -n your_password | openssl md5Sample output:
(stdin)= 1060b7b46a3bd36b3a0d66e0127d0517
Next, create the user mapping XML file.
sudo nano /etc/guacamole/user-mapping.xml
Add the following lines. Here we specify that the backend will use VNC (Vritual Network Computing) protocol. Replace the username and the password hash. We will create a VNC password later.
<user-mapping>
<!-- Per-user authentication and config information -->
<authorize
username="your_preferred_username"
password="1060b7b46a3bd36b3a0d66e0127d0517"
encoding="md5">
<connection name="default">
<protocol>vnc</protocol>
<param name="hostname">localhost</param>
<param name="port">5901</param>
<param name="password">vnc_password</param>
</connection>
</authorize>
</user-mapping>
Save and close the file. Restart Tomcat and guacd.
sudo systemctl restart tomcat9 guacd
Step 4: Install a Desktop Environment on Ubuntu 22.04/20.04 Server
Since we are going to set up a remote desktop, we need a desktop environment. Make sure your server has enough RAM before installing a desktop environment. There are many desktop environments. I found the lightweight XFCE desktop environment works well with VNC, so install it with the following command.
sudo apt install xfce4 xfce4-goodies firefox
During installation, you may be asked to choose a default display manager. This choice doesn’t matter much, because you will not see the login screen in a VNC session.
Since there’s a desktop environment running on the server, it’s strongly recommended that you use a firewall like UFW to restrict access and open only the necessary ports to the public. You can read the following tutorial to learn how to enable and use UFW on Ubuntu.
Step 5: Install a VNC Server on Ubuntu 22.04/20.04 Server
There are several VNC server software available for Linux users. We are going to use TigerVNC server because it works best with Guacamole.
sudo apt install tigervnc-standalone-server
Run the following command to start the VNC server.
vncserver
When TigerVNC first starts, it asks you to set a VNC password. Note that the password should not be more than 8 characters. Then you can choose if you need a view-only password.
Now you should edit the /etc/guacamole/user-mapping.xml file and change the VNC password. Then restart Tomcat and guacd.
sudo systemctl restart tomcat9 guacd
The vncserver command creates two files under your home directory.
- ~/.Xauthrirty
- ~/.vnc/xstartup
The xstartup file specifies the applications that will be started by TigerVNC server. Edit this file.
nano ~/.vnc/xstartup
Change
#!/bin/sh
to
#!/bin/bash
Because Bash is the standard Shell on Linux. Then comment out the following lines. (Add a # character at the beginning of each line).
xsetroot -solid grey export XKL_XMODMAP_DISABLE=1 /etc/X11/Xsession
Next, add the following line at the bottom, which will make TigerVNC server start the LXQT desktop environment. The startxfce4 binary is installed by the xfce4-session package.
startxfce4 &
Save and close the file.
Troubleshooting
If your tigerVNC server didn’t create the ~/.vnc/xstartup file and the VNC server failed like below:
Then you can manually create the file.
nano ~/.vnc/xstartup
Add the following lines in the file.
#!/bin/sh xrdb $HOME/.Xresources startxfce4 &
Save and close the file.
Creating A Systemd Service
TigerVNC server doesn’t ship with any systemd service units. To make it start at boot time, we need to create a systemd service unit.
sudo nano /etc/systemd/system/vncserver@.service
Add the following lines in the file. Replace username with your real username.
[Unit] Description=a wrapper to launch an X server for VNC After=syslog.target network.target [Service] Type=forking User=username Group=username WorkingDirectory=/home/username ExecStartPre=-/usr/bin/vncserver -kill :%i > /dev/null 2>&1 ExecStart=/usr/bin/vncserver -depth 24 -geometry 1280x800 -localhost :%i ExecStop=/usr/bin/vncserver -kill :%i [Install] WantedBy=multi-user.target
Save and close the file. Stop the current VNC server instance.
vncserver -kill :1
Start the VNC server with systemd.
sudo systemctl start vncserver@1.service
Enable auto-start at boot time.
sudo systemctl enable vncserver@1.service
Check its status:
systemctl status vncserver@1.service
As you can see, it’s active (running).
Now TigerVNC Server listens on port 5901.
sudo ss -lnpt | grep vnc
Step 6: Set Up a Reverse Proxy for the Guacamole Web Application
Apache Tomcat is listening on port 8080. To have an easy way to access the Guacamole web application, we can set up a reverse proxy with Apache or Nginx, so end-users will be able to use a domain name to access the web application. It also allows us to easily install a TLS certificate to encrypt the connection.
Apache
If you prefer to use Apache, then install Apache from the default Ubuntu software repository.
sudo apt install apache2
To use Apache as a reverse proxy, we need to enable the proxy modules and the header module.
sudo a2enmod proxy proxy_http headers proxy_wstunnel
Then create a virtual host file for Guacamole.
sudo nano /etc/apache2/sites-available/guacamole.conf
Add the following lines in the file. Replace guacamole.example.com with your own domain name. Remember to create an A record for the sub-domain in your DNS manager. If you don’t have a real domain name, I recommend going to NameCheap to buy one. The price is low and they give whois privacy protection free for life.
<VirtualHost *:80>
ServerName guacamole.example.com
ErrorLog ${APACHE_LOG_DIR}/guacamole_error.log
CustomLog ${APACHE_LOG_DIR}/guacamole_access.log combined
<Location />
Require all granted
ProxyPass http://localhost:8080/guacamole/ flushpackets=on
ProxyPassReverse http://localhost:8080/guacamole/
</Location>
<Location /websocket-tunnel>
Require all granted
ProxyPass ws://localhost:8080/guacamole/websocket-tunnel
ProxyPassReverse ws://localhost:8080/guacamole/websocket-tunnel
</Location>
Header always unset X-Frame-Options
</VirtualHost>
Save and close the file. Test the Syntax.
sudo apachectl -t
If Syntx is Ok, then enable this virtual host.
sudo a2ensite guacamole.conf
Restart Apache
sudo systemctl restart apache2
Now you can access the Apache Guacamole login page via guacamole.example.com. If you see the “invalid request” or a similar error message, it could mean that Apache Tomcat can’t bind to port 8080, because this port is already taken by another process on the server. You should configure the other process to use a different port, then restart Tomcat.
Nginx
If you prefer to use Nginx, then install Nginx from the default Ubuntu software repository.
sudo apt install nginx
Create a server block file for Guacamole.
sudo nano /etc/nginx/conf.d/guacamole.conf
Add the following lines in the file. Replace guacamole.example.com with your own domain name. Remember to create an A record for the sub-domain in your DNS manager. If you don’t have a real domain name, I recommend going to NameCheap to buy one. The price is low and they give whois privacy protection free for life.
server {
listen 80;
listen [::]:80;
server_name guacamole.example.com;
access_log /var/log/nginx/guac_access.log;
error_log /var/log/nginx/guac_error.log;
location / {
proxy_pass http://127.0.0.1:8080/guacamole/;
proxy_buffering off;
proxy_http_version 1.1;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $http_connection;
proxy_cookie_path /guacamole/ /;
}
}
Save and close this file. Then test Nginx configuration.
sudo nginx -t
If the test is successful, reload Nginx for the change to take effect.
sudo systemctl reload nginx
Now you can access the Apache Guacamole login page via guacamole.example.com. If you see the “invalid request” or a similar error message, it could mean that Apache Tomcat can’t bind to port 8080, because this port is already taken by another process on the server. You should configure the other process to use a different port, then restart Tomcat.
Enable HTTPS
To encrypt the HTTP traffic when you visit the Guacamole web interface, we can enable HTTPS by installing a free TLS certificate issued from Let’s Encrypt. Run the following command to install Let’s Encrypt client (certbot) on Ubuntu 22.04/20.04.
sudo apt install certbot
If you use Apache, then you need to install the Certbot Apache plugin.
sudo apt install python3-certbot-apache
Next, run the following command to obtain and install TLS certificate.
sudo certbot --apache --agree-tos --redirect --hsts --staple-ocsp --email you@example.com -d guacamole.example.com
If you use Nginx, then you also need to install the Certbot Nginx plugin.
sudo apt install python3-certbot-nginx
Next, run the following command to obtain and install TLS certificate.
sudo certbot --nginx --agree-tos --redirect --hsts --staple-ocsp --email you@example.com -d guacamole.example.com
Where:
--nginx: Use the nginx plugin.--apache: Use the Apache plugin.--agree-tos: Agree to terms of service.--redirect: Force HTTPS by 301 redirect.--hsts: Add the Strict-Transport-Security header to every HTTP response. Forcing browser to always use TLS for the domain. Defends against SSL/TLS Stripping.--staple-ocsp: Enables OCSP Stapling. A valid OCSP response is stapled to the certificate that the server offers during TLS.
The certificate should now be obtained and automatically installed.
And you can access Guacamole web interface via HTTPS. (https://guacamole.example.com).
After logging in, you will be able to use the remote desktop.
Warning: Some desktop environments will suspend the system if there’s no user activity. If you install a desktop environment on a cloud VPS, make sure you disable the suspend function in your desktop environment.
Wrapping UP
I hope this tutorial helped you set up Apache Guacamole remote desktop on Ubuntu 22.04/20.04 server. As always, if you found this post useful, then subscribe to our free newsletter to get more tips and tricks. Take care 🙂
Tidak ada komentar:
Posting Komentar