In this guide, we are going to learn how to install Apache Guacamole on Ubuntu 20.04. Apache Guacamole is a clientless HTML5 web based remote desktop gateway which provides remote access to servers and desktops through a web browser. It supports standard protocols like VNC, RDP, and SSH.
Install Apache Guacamole on Ubuntu 20.04
Guacamole is made up of two parts;
guacamole-server, which provides the guacd proxy and all the native, server-side components required by Guacamole to connect to remote desktops.
guacamole-clientwhich provides the client to be served by the servlet container which is usually
You need to install both of these components to setup Apache Guacamole web-based remote desktop client.
Installing Guacamole Server on Ubuntu 20.04
Install Required Build Tools
To install guacamole-server, you need to build it from the source. This, therefore, requires that you need install the required build tools before you can start to build guacamole-server component;
apt install -y gcc g++ libcairo2-dev libjpeg-turbo8-dev libpng-dev \ libtool-bin libossp-uuid-dev libavcodec-dev libavutil-dev libswscale-dev \ freerdp2-dev libpango1.0-dev libssh2-1-dev libvncserver-dev libtelnet-dev \ libssl-dev libvorbis-dev libwebp-dev
A comprehensive description of these dependency tools is available on required dependencies section.
Building Guacamole-Server on Ubuntu 20.04
To build guacamole-server, download the latest source archive tarball from Guacamole releases page. Guacamole 1.3.0 is the latest release version as of this writing. You can simply run the command below;
Once the download is done, extract the source tarball.
tar xzf guacamole-server-1.3.0.tar.gz
Navigate to guacamole server source code directory;
configure script to check if any required dependency is missing and to adapt Guacamole server to your system.
For more configure options, run,
... ------------------------------------------------ guacamole-server version 1.3.0 ------------------------------------------------ Library status: freerdp2 ............ yes pango ............... yes libavcodec .......... yes libavutil ........... yes libssh2 ............. yes libssl .............. yes libswscale .......... yes libtelnet ........... yes libVNCServer ........ yes libvorbis ........... yes libpulse ............ no libwebsockets ....... no libwebp ............. yes wsock32 ............. no Protocol support: Kubernetes .... no RDP ........... yes SSH ........... yes Telnet ........ yes VNC ........... yes Services / tools: guacd ...... yes guacenc .... yes guaclog .... yes FreeRDP plugins: /usr/lib/x86_64-linux-gnu/freerdp2 Init scripts: /etc/init.d Systemd units: no Type "make" to compile guacamole-server.
Pay attention to out of the
Compile and install Guacamole Server on Ubuntu 20.04;
Next, run the
ldconfig command to create the necessary links and cache to the most recent shared libraries found in the guacamole server directory.
Start and enable guacd (Guacamole Daemon) to run on boot after the installation.
systemctl start guacd
systemctl enable guacd
To check the status;
systemctl status guacd
● guacd.service - LSB: Guacamole proxy daemon Loaded: loaded (/etc/init.d/guacd; generated) Active: active (running) since Mon 2020-04-20 21:19:30 EAT; 50s ago Docs: man:systemd-sysv-generator(8) Tasks: 1 (limit: 2319) Memory: 10.2M CGroup: /system.slice/guacd.service └─38896 /usr/local/sbin/guacd -p /var/run/guacd.pid Apr 20 21:19:30 koromicha systemd: Starting LSB: Guacamole proxy daemon... Apr 20 21:19:30 koromicha guacd: Guacamole proxy daemon (guacd) version 1.3.0 started Apr 20 21:19:30 koromicha guacd: Starting guacd: Apr 20 21:19:30 koromicha guacd: Starting guacd: Apr 20 21:19:30 koromicha guacd: uacd: INFO: Guacamole proxy daemon (guacd) versio Apr 20 21:19:30 koromicha systemd: Started LSB: Guacamole proxy daemon. Apr 20 21:19:30 koromicha guacd: uacd[388 Apr 20 21:19:30 koromicha guacd: Listening on host 127.0.0.1, port 4822
Install Tomcat Servlet
Apache Tomcat is used to serve guacamole client content to users that connects to guacamole server via the web browser. To install Tomcat, run the command below;
apt install tomcat9 tomcat9-admin tomcat9-common tomcat9-user -y
Tomcat9 is started and enabled to run on system boot upon installation.
If UFW is running, allow Tomcat through it.
ufw allow 8080/tcp
Installing Guacamole Client on Ubuntu 20.04
guacamole-client contains provides web application that will serve the HTML5 Guacamole client to users that connect to your server. The web application will then connect to guacd on behalf of connected users in order to serve them any remote desktop they are authorized to access.
Create Guacamole configuration directory;
Download Guacamole-client Binary
Guacamole client can be installed from a source code or from ready binary. Binary installation is used in this demo. Download Guacamole-client from Guacamole releases page for the respective latest version (v1.3.0 as of this writing) and store it in the configuration directory created above;
wget https://downloads.apache.org/guacamole/1.3.0/binary/guacamole-1.3.0.war -O /etc/guacamole/guacamole.war
Create a symbolic link of the guacamole client to Tomcat webapps directory as shown below;
ln -s /etc/guacamole/guacamole.war /var/lib/tomcat9/webapps/
Restart Tomcat to deploy the new web application;
systemctl restart tomcat9
Restart guacd daemon as well;
systemctl restart guacd
Configure Apache Guacamole on Ubuntu 20.04
Guacamole has two major configuration files;
/etc/guacamole which is referenced by the
GUACAMOLE_HOME environment variable and
/etc/guacamole/guacamole.properties which is the main configuration file used by Guacamole and its extensions.
There are also guacamole extensions and libraries configurations. You need to create the directories for these configs;
Set the guacamole home directory environment variable and add it to
/etc/default/tomcat9 configuration file.
echo "GUACAMOLE_HOME=/etc/guacamole" >> /etc/default/tomcat9
Configure Guacamole Server Connections
To define how Guacamole connects to
guacd, create the
guacamole.properties file under
/etc/guacamole directory with the following content.
guacd-hostname: localhost guacd-port: 4822 user-mapping: /etc/guacamole/user-mapping.xml auth-provider: net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider
After that, save the configuration file and link the Guacamole configurations directory to Tomcat servlet directory as shown below.
ln -s /etc/guacamole /usr/share/tomcat9/.guacamole
Configure Guacamole Authentication Method
Guacamole’s default authentication method reads all users and connections from a single file called
user-mapping.xml. In this file,you need to define the users allowed to access Guacamole web UI, the servers to connect to and the method of connection.
Therefore, run the command below to create this file with the following contents.
Generate the MD5 hash of passwords for the user used for logging into Guacamole web user interface. Replace you password accordingly;
echo -n password | openssl md5
printf '%s' password | md5sum
Be sure to replace password with your strong password.
<user-mapping> <!-- Per-user authentication and config information --> <!-- A user using md5 to hash the password guacadmin user and its md5 hashed password below is used to login to Guacamole Web UI--> <authorize username="guacadmin" password="5f4dcc3b5aa765d61d8327deb882cf99" encoding="md5"> <!-- First authorized Remote connection --> <connection name="CentOS-Server"> <protocol>ssh</protocol> <param name="hostname">192.168.56.156</param> <param name="port">22</param> </connection> <!-- Second authorized remote connection --> <connection name="Windows 7"> <protocol>rdp</protocol> <param name="hostname">192.168.56.122</param> <param name="port">3389</param> <param name="username">koromicha</param> <param name="ignore-cert">true</param> </connection> </authorize> </user-mapping>
If you need to explicitly define usernames and passwords, add the parameters;
<param name="username">USERNAME</param> <param name="password">PASSWORD</param>
Save and exit the configuration file.
Restart both Tomcat and guacd to effect the changes.
systemctl restart tomcat9 guacd
Be sure to check the syslog,
/var/log/tomcat9/CATALINA-* for any issues.
Accessing Apache Guacamole from Browse
Once Guacamole is setup, you can access it from web browser using the address
Upon successful login, you get to Apache Guacamole web dashboard and you should be able to see the added connections.
Click on a connection to name to initiate remote login. For example, SSHing into my CentOS-serve gets a me password prompt since we already defined the user;
To login to Windows 7 via RDP, just click on Windows 7;
And there you go. Enter your password and proceed to your desktop.
You can now add more connections to your Guacamole. That marks the end of our guide on install Apache Guacamole on Ubuntu 20.04.
Read more on Guacamole User Guide.