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 md5
Sample 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/[email protected]
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 [email protected]
Enable auto-start at boot time.
sudo systemctl enable [email protected]
Check its status:
systemctl status [email protected]
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 [email protected] -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 [email protected] -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 🙂
Great, thanks a lot!
Please add a few lines on its usage.
Hello, thanks for the guide, it’s dope!
I’d like to ask a silly question, kindly bear with me. Which IP in particular would guacamole.example.com point to?
If you set up Guacamole on an Internet-facing server, then you should point the domain name to the public IP address of your Ubuntu server.
RIght! Got it, thanks.
hi, another excellent tutorial.
I tried to add to /etc/guacamole/user-mapping.xml this line comand:true and localhost but yet i dont have audio. Some advice?
Audio output is enabled by default in Guacamole. Do you have a sound card on the remote host?
Yes, i work in a Raspberry 4
yeah, no sound for me too. im running a ubuntu 20.04 LTS on a vps. i enable the pulseaudio(‘pulseaudio -D’) still no sound. the output is ‘dummy’. any advice is appreciate. thanks.
p/s – i notice this setup is really resource hungry. cant even run firefox with an entry level vps. what spec would you suggest for this?
hello, works the configuration with windows 10?
Excellent !!! How we
can admin guacamole?
Great guide! Getting rid of VNC client software is extremely useful.
A useless note here, `make` does not need `sudo` privilege.
Hi,
Should I disable and remove the default site?
Everything works except the reverse proxy…
Going to :8080/gucamole works though?
Going to / brings Apache2 It works! web page…
Any suggestion?
Thanks
Replying to my own question.
Just disable default apache site and reload.
Same problem but solution didn’t work
Stuck on nano ~/.vnc/xstartup
VNCServer did not create any such dir that I can find, nor did it create the files.. I’m lost
Nevermind, I feel so dumb. The internet I am on takes forever to install anything from the internet (satellite) and it didn’t occur to me to just keep reading. #facepalm
2 things after I have successfully build a Guac server:
1: What port do I forward to on modem side to access my RDP? Presumably, I go to domain.com or guac.domain.com and it should go to port 80? But 80 takes me to the tomcat page.
and 2: is there a way to manage Guac “Servers” and view log ins and such?
Hi,
I’d like it to log out and go back to login screen or at least lock out session after 5 minutes of inactivity for example.
I’ve done some google searching and apparently this is done through this command:
localadmin@virtmgr:~#vncserver −MaxIdleTime 300
But I haven’t seen any reference as to how to put it in the ~/.vnc/xstartup config file?
Also, does this keep the vncserver session alive but requiring a new login or does it kill the VNC session? If so, how to make sure the session is restarted if killed?
I sometimes make the mistake of logging out of the GUI within the guacamole page and it bothers me as I have to ssh and restart the session, any way to have a sort of watchdog that’d respawn the session?
Regards
Thanks
I rather not install a desktop on a server, can i jump that configuration part? I just want to provide someone with the link to the server and have them put in a password so that I may access their desktop.
I think having a desktop on the server itself only uses spaces and eats memory in my case.
“provide someone with the link to the server and have them put in a password so that I may access their desktop”?
I’m not sure what you are going to achieve.
If you simply want to control someone else’s computer, maybe using AnyDesk will be better.
I’m looking to create a few users that can login to the server on demand, when instructed to so that we may help them. They are remote users, and they all have different systems. Nota all are using the company’s computer.
Any desk would be fine, except for the pricing and exchange rate killing this option right now.
TeamViewer also works but it’s expensive as well. In a team of 4 techs the cost is too much and business is not as strong as before the pandemic. The coast of a self hosted tool is alot cheaper and easier to absorb right now.
We’ve tried mesh commander as well but the program is always getting removed by the antivirus.
Anyway. The idea is to make a bridged between the connected computers of a tech and a user.
Would it be able to buy a full Hyper-V VM from you, with Guacamole on Ubuntu server. Willing to pay say NZ$100.00?
All worked except when i got to the vncserver -kill:1
i am also getting this same error
root@apachequacomole:~/.vnc# sudo systemctl restart apache2
root@apachequacomole:~/.vnc# sudo systemctl start [email protected]
Job for [email protected] failed because the control process exited with error code.
See “systemctl status [email protected]” and “journalctl -xe” for details.
root@apachequacomole:~/.vnc# systemctl status [email protected]
● [email protected]
Loaded: loaded (/etc/systemd/system/[email protected]; enabled; vendor preset: enabled)
Active: failed (Result: exit-code) since Thu 2020-10-22 14:34:29 UTC; 8s ago
Process: 59630 ExecStartPre=/usr/bin/vncserver -kill :1 > /dev/null 2>&1 (code=exited, status=0/SUCCESS)
Process: 59645 ExecStart=/usr/bin/vncserver -depth 24 -geometry 1280×800 -localhost :1 (code=exited, status=1/FAILURE)
Oct 22 14:34:29 apachequacomole systemd[1]: Starting [email protected]…
Oct 22 14:34:29 apachequacomole vncserver[59645]: You will require a password to access your desktops.
Oct 22 14:34:29 apachequacomole vncserver[59650]: getpassword error: Inappropriate ioctl for device
Oct 22 14:34:29 apachequacomole vncserver[59650]: Password:
Oct 22 14:34:29 apachequacomole systemd[1]: [email protected]: Control process exited, code=exited, status=1/FAILURE
Oct 22 14:34:29 apachequacomole systemd[1]: [email protected]: Failed with result ‘exit-code’.
Oct 22 14:34:29 apachequacomole systemd[1]: Failed to start [email protected].
Oct 22 14:34:37 apachequacomole systemd[1]: /etc/systemd/system/[email protected]:1: Unknown section ‘unit’. Ignoring.
root@apachequacomole:~/.vnc#
I have installed and am getting the login, and a connected message, but then it just hangs never paints any session.
I’ve only got ssh and rdp clients configured and neither connect.
I’ve traced guad, and it’s spinning on a connection to it’s port, but getting no action.
Any suggestions on further debugging? I have turned on the logging from one clue for guacamole but it’s not spitting out much of any clues either into the catalina logs. there are messages there, but not very useful ones, and no “fail” or obvious error messages.
This tutorial shows how to connect to a remote VNC desktop. To Connect to SSH or RDP, you need to add additional configs in
/etc/guacamole/user-mapping.xmlfile.after logging im getting this page please help, can anyone help me explain whats going on ?
Thanks for the great and fully working instruction. I tried to install Guacamole using different tutorials in ran into issues with non-supported packages. This install guide does only use the Ubuntu native packages, so no not only installation is easy, but packages are also updates using apt. Only guacamole itself is not updated automatically, but that is not possible as it is not an package (yet).
I am really happy accessing my RDP server at home from anywhere using any native HTML-5 browser. I am using a Cisco ASA Clientless VPN as reverse proxy.
same here…
Hi @Xiao Guoan
I have the same problem
What wrong with me ?
Thanks so much
Hi Admin
Can you write tutorial Config Guacamole authentication with database (Mysql)
Many Thanks
Hi
I have two problems:
1. when i enter my domain: remote.mydomain.com, it redirects me correctly, but in the URL bar it still shows my ip, not the domain name.
2. When i tried to install the Certificate with the apache thingy, it output this Error:
Thanks in andvance.
Can you tell me who solved the problem of invalid login?
Hi, when I run “systemctl status guacd” command getting permission error. Using 22.04 server.Below you can find the error.
× guacd.service – Guacamole Server
Loaded: loaded (/etc/systemd/system/guacd.service; enabled; vendor preset: enabled)
Active: failed (Result: exit-code) since Fri 2023-06-09 10:04:35 UTC; 20s ago
Docs: man:guacd(8)
Main PID: 11317 (code=exited, status=1/FAILURE)
CPU: 13ms
Jun 09 10:04:35 yyyyy systemd[1]: Started Guacamole Server.
Jun 09 10:04:35 yyyyy guacd[11317]: Guacamole proxy daemon (guacd) version 1.5.2 started
Jun 09 10:04:35 yyyyy guacd[11317]: guacd[11317]: INFO: Guacamole proxy daemon (guacd) version 1.5.2 started
Jun 09 10:04:35 yyyyy guacd[11317]: guacd[11317]: ERROR: Could not write PID file: Permission denied
Jun 09 10:04:35 yyyyy guacd[11317]: Could not write PID file: Permission denied
Jun 09 10:04:35 yyyyy systemd[1]: guacd.service: Main process exited, code=exited, status=1/FAILURE
Jun 09 10:04:35 yyyyy systemd[1]: guacd.service: Failed with result ‘exit-code’.