Apache Guacamole is a clientless remote desktop gateway that supports standard protocols like VNC, RDP, and SSH. Thanks to HTML5, once Guacamole is installed on a server, all you need to access your desktops is a web browser.
Guacamole is separated into two pieces: guacamole-server, which provides the guacd proxy and related libraries, and guacamole-client, which provides the client to be served by your servlet container. In most cases, the only source you will need to build is guacamole-server, and downloading the latest guacamole.war from the project website will be sufficient to provide the client.

Installation on Ubuntu: Install and Use Guacamole Remote Desktop on Ubuntu
Step 1: Server Preparation
Enable EPEL and PowerTools repository:
### CentOS 8 Stream ###
sudo dnf -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
sudo dnf config-manager --set-enabled powertools
### RHEL 8 ###
sudo subscription-manager repos --enable codeready-builder-for-rhel-8-x86_64-rpms
sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
Install and update the system.
sudo dnf update -y
Apache Guacamole has many dependencies and we are going to deal with most of them in this step. You will notice that I used some packages from the Devel repository because getting them from the official repositories was a challenge. Disable it once the packages we need are all installed.
sudo dnf --enablerepo=devel install vim wget unzip make cmake wget gcc zlib-devel compat-openssl10 cairo-devel libuv-devel libjpeg-turbo-devel libjpeg-devel libpng-devel libtool uuid-devel freerdp-devel pango-devel libvncserver-devel pulseaudio-libs-devel openssl-devel libvorbis-devel libwebp-devel libssh2-devel libtheora opus lame-libs libwebsockets-devel libtelnet-devel
Agree to install the dependencies:
...
Transaction Summary
======================================================================================================================================================================================================
Install 153 Packages
Total download size: 48 M
Installed size: 153 M
Is this ok [y/N]: y
Step 2: Install Apache Tomcat
Once the prerequisites are sorted, run the command below to install the Apache Tomcat Java servelet container that serves the Guacamole Java client and all the required dependencies. Since it is in Java, let us first get Java installed.
Install OpenJDK 11
Run the command below to fetch java-11-openjdk.
sudo yum install java-11-openjdk-devel
Create a file and set Java environment variables.
$ sudo vim /etc/profile.d/java11.sh
export JAVA_HOME=$(dirname $(dirname $(readlink -f $(which javac))))
export PATH=$PATH:$JAVA_HOME/bin
export CLASSPATH=.:$JAVA_HOME/jre/lib:$JAVA_HOME/lib:$JAVA_HOME/lib/tools.jar
Source the file to start using it without logging out.
source /etc/profile.d/java11.sh
Install Apache Tomcat on CentOS 8 / RHEL 8
Tomcat exists in the default CentOS 8 / RHEL 8 repositories and can be downloaded easily using the command:
sudo yum install tomcat
Once installed, start and enable the service:
sudo systemctl enable --now tomcat
And Tomcat should be running happily.
$ systemctl status tomcat
● tomcat.service - Apache Tomcat Web Application Container
Loaded: loaded (/usr/lib/systemd/system/tomcat.service; enabled; vendor preset: disabled)
Active: active (running) since Thu 2023-08-17 06:13:54 EDT; 6s ago
Main PID: 63201 (java)
Tasks: 27 (limit: 23505)
Memory: 72.7M
CGroup: /system.slice/tomcat.service
└─63201 /usr/lib/jvm/jre/bin/java -Djavax.sql.DataSource.Factory=org.apache.commons.dbcp.BasicDataSourceFactory -classpath /usr/share/tomcat/bin/bootstrap.jar:/usr/share/tomcat/b>
Aug 17 06:13:55 localhost.localdomain server[63201]: 17-Aug-2023 06:13:55.291 INFO [main] org.apache.catalina.core.AprLifecycleListener.lifecycleEvent Loaded Apache Tomcat Native library [1>
Aug 17 06:13:55 localhost.localdomain server[63201]: 17-Aug-2023 06:13:55.291 INFO [main] org.apache.catalina.core.AprLifecycleListener.lifecycleEvent APR capabilities: IPv6 [true], sendfil>
....
Step 3: Build the Guacamole Server From Source
guacamole-server contains all the native, server-side components required by Guacamole to connect to remote desktops. It provides a common C library, libguac, which all other native components depend on, as well as separate libraries for each supported protocol, and a proxy daemon, guacd, the heart of Guacamole.
Download the latest stable version of guacamole-server
cd ~/
VER=1.5.3
wget https://archive.apache.org/dist/guacamole/$VER/source/guacamole-server-$VER.tar.gz
Extract the downloaded archive.
tar -xvf guacamole-server-$VER.tar.gz
Change into the extracted directory.
cd guacamole-server-*/
Configure the build environment. Running configure will determine which libraries are available on your system and will select the appropriate components for building depending on what you actually have installed.
./configure --with-init-dir=/etc/init.d
Then compile the guacamole server. Quite a bit of output will scroll up the screen as all the components are compiled
make
Once everything finishes, all you have left to do is type “sudo make install” to install the components that were built, and then “ldconfig” to update your system’s cache of installed libraries.
sudo make install
Update the system’s cache of installed libraries.
sudo ldconfig
Create the required Guacamole directories:
sudo mkdir -p /etc/guacamole/{extensions,lib}
Create a config file for guacd:
$ sudo vim /etc/guacamole/guacd.conf
[daemon]
pid_file = /var/run/guacd.pid
#log_level = debug
[server]
#bind_host = localhost
bind_host = 127.0.0.1
bind_port = 4822
#[ssl]
#server_certificate = /etc/ssl/certs/guacd.crt
#server_key = /etc/ssl/private/guacd.key
Refresh systemd for it to find the guacd (Guacamole proxy daemon) service installed in /etc/init.d/ directory.
sudo systemctl daemon-reload
Once reloaded, start the guacd service.
sudo systemctl start guacd
sudo systemctl enable guacd
And to have that smile on your face, check its status.
$ systemctl status guacd
● guacd.service - LSB: Guacamole proxy daemon
Loaded: loaded (/etc/rc.d/init.d/guacd; generated)
Active: active (running) since Thu 2023-08-17 06:18:06 EDT; 7s ago
Docs: man:systemd-sysv-generator(8)
Tasks: 1 (limit: 23505)
Memory: 10.4M
CGroup: /system.slice/guacd.service
└─76310 /usr/local/sbin/guacd -p /var/run/guacd.pid
Aug 17 06:18:06 localhost.localdomain systemd[1]: Starting LSB: Guacamole proxy daemon...
Aug 17 06:18:06 localhost.localdomain guacd[76307]: Starting guacd:
Aug 17 06:18:06 localhost.localdomain guacd[76308]: Starting guacd:
Aug 17 06:18:06 localhost.localdomain guacd[76308]: uacd[76308]: INFO: Guacamole proxy daemon (guacd) versio
Aug 17 06:18:06 localhost.localdomain systemd[1]: Started LSB: Guacamole proxy daemon.
Aug 17 06:18:06 localhost.localdomain guacd[76307]: uacd[763
Aug 17 06:18:06 localhost.localdomain guacd[76310]: Listening on host 127.0.0.1, port 4822
Step 4: Install the Guacamole Web Application
There are two critical files involved in the deployment of Guacamole: guacamole.war, which is the file containing the web application, and guacamole.properties, the main configuration file for Guacamole. The recommended way to set up Guacamole involves placing these files in standard locations, and then creating symbolic links to them so that Tomcat can find them.
guacamole-client contains all Java and Maven components of Guacamole (guacamole, guacamole-common, guacamole-ext, and guacamole-common-js). These components ultimately make up the web application that will serve the HTML5 Guacamole client to users that connect to your server. This web application will connect to guacd, part of guacamole-server, on behalf of connected users in order to serve them any remote desktop they are authorized to access.
Install Guacamole Client
The Guacamole client is available as a binary. To install it, just pull it from the Guacamole binaries downloads page as shown below, copy it to /etc/guacamole/ directory and rename it at the same time.
cd ~
VER=1.5.3
wget https://archive.apache.org/dist/guacamole/$VER/binary/guacamole-$VER.war
Move the file to the Tomcat webapps directory:
sudo mv guacamole-$VER.war /var/lib/tomcat/webapps/guacamole.war
Step 5: Configure Guacamole Server
After the installation of the Guacamole server daemon, you need to define how to Guacamole client will connect to the Guacamole server (guacd) under the /etc/guacamole/guacamole.properties configuration file. Within this configuration, you need to simply define the Guacamole server hostname, port, user mapping configuration file, and authentication provider.
GUACAMOLE_HOME is the name given to Guacamole’s configuration directory, which is located at /etc/guacamole by default. All configuration files, extensions, etc. reside within this directory.
Create GUACAMOLE_HOME environment variable
echo "GUACAMOLE_HOME=/etc/guacamole" | sudo tee -a /etc/default/tomcat
echo "export GUACAMOLE_HOME=/etc/guacamole" | sudo tee -a /etc/profile
Create /etc/guacamole/guacamole.properties config file and populate it as shown below:
$ sudo vim /etc/guacamole/guacamole.properties
guacd-hostname: localhost
guacd-port: 4822
Step 6: Setup 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.
But the above method is only recommended for testing purposes. For production, we will use database authentication, which makes it easier to manage users and connections.
First, ensure that you have MariaDB/MySQL installed. This can be done by following the below guides:
Once installed, log in to the database server:
sudo mysql -u root -p
Create a user and database to be used by Guacamole:
CREATE DATABASE guacamole_db;
CREATE USER 'guacamole_user'@'localhost' IDENTIFIED BY 'Passw0rd!';
GRANT SELECT,INSERT,UPDATE,DELETE ON guacamole_db.* TO 'guacamole_user'@'localhost';
FLUSH PRIVILEGES;
QUIT
Now download the MySQL Connector/J to be used by Guacamole.
VER=8.1.0
wget https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-j-$VER.tar.gz
Extract the file and copy it to the /etc/guacamole/lib/ directory::
tar -xf mysql-connector-j-*.tar.gz
sudo cp mysql-connector-j-$VER/mysql-connector-j-$VER.jar /etc/guacamole/lib/
The JDBC auth plugin is also required for database authentication.
VER=1.5.3
wget https://downloads.apache.org/guacamole/$VER/binary/guacamole-auth-jdbc-$VER.tar.gz
Extract it and copy it to the extensions directory:
tar -xf guacamole-auth-jdbc-$VER.tar.gz
sudo mv guacamole-auth-jdbc-$VER/mysql/guacamole-auth-jdbc-mysql-$VER.jar /etc/guacamole/extensions/
We now need to import the database schemas for Guacamole. Begin by switching to the below directory:
cd guacamole-auth-jdbc-*/mysql/schema
Run the below command to import schemas to the database:
cat *.sql | sudo mysql -u root -p guacamole_db
You need to enter the root password for the MySQL user. Once imported, we will modify the Guacamole config:
sudo vim /etc/guacamole/guacamole.properties
Now add these lines to the file:
###MySQL properties
mysql-hostname: 127.0.0.1
mysql-port: 3306
mysql-database: guacamole_db
mysql-username: guacamole_user
mysql-password: Passw0rd!
In case you have a firewall running and you haven’t allowed the ports yet, then this is the chance to do so as quickly as below:
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload
Configure SELinux contexts with the commands:
sudo ausearch -c 'Catalina-utilit' --raw | audit2allow -M my-Catalinautilit
sudo semodule -X 300 -i my-Catalinautilit.pp
sudo ausearch -c 'java' --raw | audit2allow -M my-java
sudo semodule -X 300 -i my-java.pp
sudo setsebool -P domain_can_mmap_files 1
sudo setsebool -P tomcat_can_network_connect_db 1
sudo /sbin/restorecon -v /var/lib/tomcat/webapps/guacamole.war
Restart the services:
sudo systemctl restart tomcat guacd
Step 7: Getting Guacamole Web Interface
Thus far, we have set up everything well and we should therefore be ready to access the application we have been toiling to bring up. To access Guacamole’s web interface, simply point your browser to http://ip-or-domain-name:8080/guacamole and you should be greeted with a login screen as shown below:

On this page, you will authenticate with the default creds; username: guacadmin and password: guacadmin. Once logged in, you can create a new admin user and delete the old default one.
To achieve that, go to Settings ->User->New User.

Provide all the required permissions for the user and create them. You can then log out and log in with the new user. Then proceed and delete the old admin user:

Create Connections on Guacamole
Now to make remote connections, you need to create them under Settings ->Connection->New Connection

Provide all the required details here. Remember to provide the hostname/IP and port of the remote host under Parameters->Network.
If you have SSH key authentication between the hosts, you need to tweak your SSH configs on the remote host for SSH connections to work:
$ sudo vim /etc/ssh/sshd_config
HostKeyAlgorithms +ssh-rsa
PubkeyAcceptedKeyTypes +ssh-rsa
Restart the SSH service on the remote host:
sudo systemctl restart sshd
Now the added connections will appear on your Guacaome home as shown:

You can launch any connection by clicking on it!

You can also use other Authentication Methods as shown here:
To configure SSL check out our article:
Closing Remarks
Because the Guacamole client is an HTML5 web application, the use of your computers is not tied to any one device or location. As long as you have access to a web browser, you have access to your machines. With both Guacamole and a desktop operating system hosted in the cloud, you can combine the convenience of Guacamole with the resilience and flexibility of cloud computing. Check it out and leverage its flexibility and convenience, especially during this season when most of us are working from home.
References:
As we appreciate your continued support, keep the fun as you grab other ideas from the exquisite guides shared below.
- Easy way to Create SSH tunnels on Linux CLI
- Install and Configure OpenSSH Server on Windows Server
- How To Set Up Two factor (2FA) Authentication for SSH on CentOS / RHEL 7/8
Had to use these commands to get things installed on my Centos 8
# lower case:
yum config-manager –enable devel
yum config-manager –set-enabled powertools
# Needed for libssh2-devel and libwebsockets-devel:
yum install epel-release -y
Additionally, I had to disable the Windows Remote Desktop NLA setting in order for RDP to work. Otherwise, I would see this line in /var/log/messages: RDP server closed/refused connection: Server refused connection (wrong security type?)
Also, for SSH connections, the /etc/ssh/sshd_config file has to enable this:
PasswordAuthentication yes
is there any way to use Active directory groups to control who gets access to what in the XML file?
Hello @jeremy,
We have a guide for AD access here