Install and use Guacamole remote desktop on CentOS 8

You can download this article in PDF format via the link below to support us.

Download the guide in PDF format

turn off


Apache Guacamole is a clientless remote desktop gateway that supports standard protocols such as VNC, RDP and SSH. Thanks to HTML5, after installing guacamole on the server, you can access the desktop just by using a web browser.

Guacamole is divided into two parts: guacamole-server and guacamole-client, which provides guacd proxy and related libraries, while guacamole-client provides the client to be served by the servlet container. In most cases, the only resource you need to build is guacamole-server, and downloading the latest guacamole.war from the project website is enough to serve customers.

Credit: Guacamole website

Step 1: Server preparation

Apache Guacamole has many dependencies, and we will handle most of them in this step. You will notice that I used some packages from the Devel repository because it is a challenge to get them from the official repository. Once the package we need is installed, please disable it.

                        sudo dnf update
sudo dnf install -y vim wget unzip make cmake wget gcc zlib-devel compat-openssl10
sudo dnf config-manager --set-enabled PowerTools
sudo dnf config-manager --enable Devel
sudo dnf -y install 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 libwebsockets-devel libtheora opus lame-libs
sudo dnf config-manager --disable Devel

Install other libraries from source

Some libraries are not yet available on the repository. They include libtelnet

tar -xf libtelnet-0.23.tar.gz
cd libtelnet-0.23
make && sudo make install

Step 2: Install Apache Tomcat

After sorting the prerequisites, run the following command to install the Apache Tomcat Javaservelet container that can serve the Guacamole Java client and all required dependencies. Since it is the Java language, we first install Java.

Install Java on CentOS 8

Run the following command to get java-11-openjdk.

                        sudo yum install java-11-openjdk-devel

Create a file and set the Java environment variables.

                        $ sudo vim /etc/profile.d/

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

Provide the file source to start using it without logging out.

                        source /etc/profile.d/

Install Apache Tomcat on CentOS 8

To install Apache Tomcat, please follow our detailed guide on how to install Apache Tomcat 9 on CentOS 8. Since we have already installed the Java installer, please ignore it.

Step 3: Build a guacamole server from source code

guacamole-server contains all the native server-side components that Guacamole needs to connect to the remote desktop. It provides the general C library libguac on which all other native components depend, as well as independent libraries for each supported protocol, and the proxy daemon guacd (the core of guacamole).

Download The latest stable version of the Guacamole server

                        cd ~

Unzip the downloaded file.

                        tar -xvf guacamole-server-1.2.0.tar.gz

Go to the extracted directory.

                        cd guacamole-server-1.2.0

Configure the build environment. Running configure will determine the libraries available on the system, and will select appropriate components to build based on the actual installed content.

                        ./configure --with-init-dir=/etc/init.d

Then compile the guacamole server. After compiling all components, quite a bit of output will scroll on the screen


After everything is done, all you have to do is type “sudo make install” to install the built components, and then type “ldconfig” to update the system’s cache of installed libraries.

                        sudo make install

Update the cache of installed libraries in the system.

                        sudo ldconfig

Refresh it to find the guacd (guacamole agent daemon) service installed in the /etc/init.d/ directory.

                        sudo systemctl daemon-reload

After restarting, start the guacd service.

                        sudo systemctl start guacd
sudo systemctl enable guacd

To put a 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 2020-08-27 10:26:04 UTC; 43s ago
     Docs: man:systemd-sysv-generator(8)
  Process: 51357 ExecStart=/etc/rc.d/init.d/guacd start (code=exited, status=0/SUCCESS)
    Tasks: 1 (limit: 11070)
   Memory: 11.9M
   CGroup: /system.slice/guacd.service
           └─51360 /usr/local/sbin/guacd -p /var/run/

Step 4: Install the Guacamole web application

The deployment of Guacamole involves two key files: guacamole.war (it is the file that contains the web application) and, which is the main configuration file of Guacamole. The recommended way to use Guacamole is to put these files in a standard location, and then create a symbolic link to them so that Tomcat can find them

guacamole-client contains all the Java and Maven components of Guacamole (guacamole, guacamole-common, guacamole-ext and guacamole-common-js). These components ultimately constitute a web application that will provide an HTML5 guacamole client to users who connect to the server. This web application will connect to the guacd part of the guacamole server on behalf of connected users in order to provide them with any remote desktops they have access to.

Install Guacamole Client on CentOS 8

Guacamole client can be used as a binary file. To install it, simply pull it from the Guacamole binary download page as shown below, and copy it to /etc/guacamole/ Directory and rename at the same time.

                        cd ~
sudo mkdir /etc/guacamole
wget -O /etc/guacamole/guacamole.war

To install the Guacamole client binaries, create a symbolic link from the guacamole client to the Tomcat webapps directory as shown below;

                        sudo ln -s /etc/guacamole/guacamole.war /usr/share/tomcat/webapps/

Step 5: Configure the guacamole server

After installing the Guacamole server daemon, you need to define how to connect the Guacamole client to the Guacamole server (guacd) located at the following location. /etc/guacamole/ Configuration file. In this configuration, you only need to define the hostname, port, user mapping profile, and authentication provider of the Guacamole server.

GUACAMOLE_HOME is the name of the guacamole configuration directory, which is located at /etc/guacamole by default. All configuration files, extensions, etc. are located in this directory.

Create GUACAMOLE_HOME environment variable

                        echo "GUACAMOLE_HOME=/etc/guacamole" | sudo tee -a /etc/default/tomcat

Create and fill in the /etc/guacamole/ configuration file as shown below:

                        $ sudo vim /etc/guacamole/

guacd-hostname: localhost
guacd-port:    4822
user-mapping:    /etc/guacamole/user-mapping.xml

After configuring as shown above, save it and link the Guacamole configuration directory to the Tomcat servlet directory as shown below.

                        sudo ln -s /etc/guacamole /usr/share/tomcat/.guacamole

Step 6: Set up the guacamole authentication method

Guacamole’s default authentication method reads all users and connections from a file called user-mapping.xml. In this file, you need to define the users who are allowed to access the Guacamole Web UI, the server to connect to, and the connection method.

Generate an MD5 hash of the password for the user who will be used to log in to the Guacamole web user interface. Replace your password accordingly.

                        $ echo -n StrongPassword | openssl md5
(stdin)= 0f6e4a1df0cf5ee97c2066953bed21b2

After preparing the password, create a user mapping file with the following sample content. You can put any hostname, username and host according to your environment.

                        $ sudo vim /etc/guacamole/user-mapping.xml


good stuff. After completing all operations, restart Tomcat and guacd to implement the changes.

                        sudo systemctl restart tomcat guacd

If you are running a firewall and have not yet allowed the port, you can do so as quickly as possible as follows:

                        sudo firewall-cmd --permanent --add-port={4822,8080}/tcp
sudo firewall-cmd --reload

Step 7: Get the guacamole web interface

So far, we have set everything up well, so we should be ready to access the application we have been working on. To access Guacamole’s web interface, simply point your browser to http: // ip-or-domain-name: 8080 / guacamole And the login screen shown below appears:

As you can see, the connection we established in the configuration file is loaded when you log in.

Simply click on the one you wish to connect to and you will be prompted to enter your username and password, whether via SSH or RDP.

Enter your server password

We should be allowed in

Concluding remarks

Since the Guacamole client is an HTML5 web application, your use of the computer is not restricted by any device or location. As long as you have access to a web browser, you can access your machine. With Guacamole and a desktop operating system hosted in the cloud, you can combine the convenience of Guacamole with the elasticity and flexibility of cloud computing. Check it out and take advantage of its flexibility and convenience, especially in this season when most of us are working from home.


Apache Guacamole page

Apache Guacamole documentation

Thank you for your continued support, and please keep having fun as you take other ideas from the subtle guide shared below.

The easy way to create an SSH tunnel on Linux CLI

Install and configure OpenSSH Server on Windows Server 2019

How to set up two-factor (2FA) authentication for SSH on CentOS/RHEL 7/8

You can download this article in PDF format via the link below to support us.

Download the guide in PDF format

turn off


Related Posts