Last updated on April 9th, 2022 at 06:43 pm
In this guide, we are going to learn how to install Apache Guacamole on Rocky Linux 8. 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 Rocky Linux 8
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 Rocky Linux 8
Install Additional Repositories
Some of the required packages are provided by EPEL/PowerTools repositories. Install and enable them as follows;
dnf install epel-release -y
dnf config-manager --set-enabled powertools
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;
dnf install -y unzip curl make cmake wget gcc zlib-devel compat-openssl10 cairo-devel libjpeg-turbo-devel \ libpng-devel libtool uuid-devel freerdp-devel pango-devel libssh2-devel libtelnet-devel libvncserver-devel \ libwebsockets-devel pulseaudio-libs-devel openssl-devel libvorbis-devel libwebp-devel wget vim
A comprehensive description of these dependency tools is available on required dependencies section.
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;
dnf install java-11-openjdk-devel
Create Tomcat user;
useradd -d /usr/share/tomcat -M -r -s /bin/false tomcat
Create the home directory;
Download Tomcat binary distributions. We use version 9.0.50 in this demo.
Extract the tarball to home directory created above;
tar xzf apache-tomcat-9.0.50.tar.gz -C /usr/share/tomcat --strip-components=1
Set ownership of the Tomcat home directory;
chown -R tomcat:tomcat /usr/share/tomcat
Create systemd service for Apache Tomcat by running the command below;
cat > /etc/systemd/system/tomcat.service << 'EOL' [Unit] Description=Tomcat Server After=syslog.target network.target [Service] Type=forking User=tomcat Group=tomcat Environment=JAVA_HOME=/usr/lib/jvm/jre Environment='JAVA_OPTS=-Djava.awt.headless=true' Environment=CATALINA_HOME=/usr/share/tomcat Environment=CATALINA_BASE=/usr/share/tomcat Environment=CATALINA_PID=/usr/share/tomcat/temp/tomcat.pid Environment='CATALINA_OPTS=-Xms512M -Xmx1024M' ExecStart=/usr/share/tomcat/bin/catalina.sh start ExecStop=/usr/share/tomcat/bin/catalina.sh stop [Install] WantedBy=multi-user.target EOL
Start and enable Apache Tomcat service.
systemctl start tomcat
Check the status;
systemctl status tomcat
● tomcat.service - Tomcat Server Loaded: loaded (/etc/systemd/system/tomcat.service; disabled; vendor preset: disabled) Active: active (running) since Sat 2021-07-24 07:28:00 EAT; 2min 3s ago Process: 42628 ExecStart=/usr/share/tomcat/bin/catalina.sh start (code=exited, status=0/SUCCESS) Main PID: 42633 (java) Tasks: 34 (limit: 11388) Memory: 86.3M CGroup: /system.slice/tomcat.service └─42633 /usr/lib/jvm/jre/bin/java -Djava.util.logging.config.file=/usr/share/tomcat/conf/logging.properties -Djava.util.logging.manager=org.apache.juli.ClassLoa> Jul 24 07:28:00 localhost.localdomain systemd: Starting Tomcat Server... Jul 24 07:28:00 localhost.localdomain systemd: Started Tomcat Server.
If you want to enable it to run on boot;
systemctl enable tomcat
Building Guacamole-Server on Rocky Linux 8
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,
Sample configuration output;
------------------------------------------------ guacamole-server version 1.3.0 ------------------------------------------------ Library status: freerdp2 ............ yes pango ............... yes libavcodec .......... no libavformat.......... no libavutil ........... no libssh2 ............. yes libssl .............. yes libswscale .......... no libtelnet ........... yes libVNCServer ........ yes libvorbis ........... yes libpulse ............ yes libwebsockets ....... yes libwebp ............. yes wsock32 ............. no Protocol support: Kubernetes .... yes RDP ........... yes SSH ........... yes Telnet ........ yes VNC ........... yes Services / tools: guacd ...... yes guacenc .... no guaclog .... yes FreeRDP plugins: /usr/lib64/freerdp2 Init scripts: no Systemd units: /etc/systemd/system Type "make" to compile guacamole-server.
Pay attention to out of the
configure script. If any error, fix it before you can proceed.
Compile and install Guacamole Server on Rocky Linux 8;
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 guacd (Guacamole Daemon) to run on boot after the installation.
systemctl start guacd
Check the status;
systemctl status guacd
● guacd.service - Guacamole Server Loaded: loaded (/etc/systemd/system/guacd.service; disabled; vendor preset: disabled) Active: active (running) since Sat 2021-07-24 07:01:17 EAT; 6s ago Docs: man:guacd(8) Main PID: 41779 (guacd) Tasks: 1 (limit: 11388) Memory: 10.0M CGroup: /system.slice/guacd.service └─41779 /usr/local/sbin/guacd -f Jul 24 07:01:17 localhost.localdomain systemd: Started Guacamole Server. Jul 24 07:01:17 localhost.localdomain guacd: Guacamole proxy daemon (guacd) version 1.3.0 started Jul 24 07:01:17 localhost.localdomain guacd: guacd: INFO: Guacamole proxy daemon (guacd) version 1.3.0 started Jul 24 07:01:17 localhost.localdomain guacd: guacd: INFO: Listening on host 127.0.0.1, port 4822 Jul 24 07:01:17 localhost.localdomain guacd: Listening on host 127.0.0.1, port 4822
If you want to enable guacd (Guacamole Daemon) to run on boot after the installation.
systemctl enable guacd
Installing Guacamole Client on Rocky Linux 8
guacamole-client 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 /usr/share/tomcat/webapps/
Restart Tomcat to deploy the new web application;
systemctl restart tomcat
Restart guacd daemon as well;
systemctl restart guacd
Configure Apache Guacamole on Rocky Linux 8
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/tomcat
Configure Guacamole Server Connections
To define how Guacamole connects to
guacd, create the
guacamole.properties file under
/etc/guacamole directory with the following content.
cat > /etc/guacamole/guacamole.properties << 'EOL' guacd-hostname: localhost guacd-port: 4822 user-mapping: /etc/guacamole/user-mapping.xml auth-provider: net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider EOL
After that, link the Guacamole configurations directory to Tomcat servlet directory as shown below.
ln -s /etc/guacamole /usr/share/tomcat/.guacamole
Configure Guacamole Authentication Method
Guacamole’s default authentication method reads all users and connections from a single file called
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.
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.
Next, run the command below to create this file,
user-mapping.xml, with the following contents.
cat> /etc/guacamole/user-mapping.xml << 'EOL' <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="Ubuntu 20.04 Server"> <protocol>ssh</protocol> <param name="hostname">192.168.59.14</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> EOL
If you need to explicitly define usernames and passwords, add the parameters;
<param name="username">USERNAME</param> <param name="password">PASSWORD</param>
Restart both Tomcat and guacd to effect the changes.
systemctl restart tomcat guacd
Be sure to check the syslog,
/usr/share/tomcat/logs/catalina.* for any issues.
Accessing Apache Guacamole from Browser
Once Guacamole is setup, you can access it from web browser using the address
Allow external access to Apache Guacamole via Apache Tomcat on firewalld;
firewall-cmd --add-port=8080/tcp --permanent
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 ubuntu-server vm gets a me password prompt since we already defined the user in the configuration file;
To login to Windows 7 via RDP, just click on Windows 7. Ensure that you have allowed the user to login via RDP.
How to fix RDP server closed/refused connection: Security negotiation failed (wrong security type?)
Windows RDP Authenthication may fail with errors shown below on
Jul 25 20:31:28 localhost guacd: guacd: WARNING:#011FreeRDP initialization may fail: The current user's home directory ("/sbin") is not writable, but FreeRDP generally requires a writable home directory for storage of configuration files and certificates. Jul 25 20:31:28 localhost guacd: No security mode specified. Defaulting to security mode negotiation with server. Jul 25 20:31:28 localhost guacd: Resize method: none
Jul 25 20:31:29 localhost guacd: RDP server closed/refused connection: Security negotiation failed (wrong security type?) Jul 25 20:31:29 localhost guacd: guacd: INFO:#011RDP server closed/refused connection: Security negotiation failed (wrong security type?)
As much as you need to check the RDP Authentication and Security settings on what security mode to configure, this is how I fixed the above error.
Firs thing to note is Guacamole server (guacd) service runs as user
daemon by default.
ps aux | grep -v grep| grep guacd
daemon 4815 0.0 0.7 85404 14228 ? Ss 20:44 0:00 /usr/local/sbin/guacd -f
In this case, the easiest way to enable RDP is to actually create a guacd system with its own home directory which it will have full access to write to.
useradd -M -d /var/lib/guacd/ -r -s /sbin/nologin -c "Guacd User" guacd
chown -R guacd: /var/lib/guacd
Next, update the Guacd service user;
sed -i 's/daemon/guacd/' /etc/systemd/system/guacd.service
Reload systemd daemon;
Restart Guacd Service;
systemctl restart guacd
Windows RDP should now be working.
You can now add more connections to your Guacamole. That marks the end of our guide on install Apache Guacamole on Rocky Linux 8.
Read more on Guacamole User Guide.
Setup Apache Guacamole OpenLDAP Authentication
Install Apache Guacamole on Debian 10
Configure Guacamole SSL/TLS with Nginx Reverse Proxy
How to Enable RDP/SSH File Transfer Over Guacamole
Hi, good article. Can you tell me how to install a self-signed certificate (openssl) and run the server via the https protocol?
Thanks for the feedback Alex. Kindly check this article Configure Guacamole SSL/TLS with Nginx Reverse Proxy.
Just replace apt with dnf/yum command to install nginx.
Let us know if it works.
I tried to install several times (I did a recovery on a virtual machine), but I get an error on the make install command. Installation log link https://gofile.io/d/8bDIJY
I’ve been running Guac 1.1.0 as a container for a while and it works great. I tried to upgrade to 1.3.0 and am getting the error you mentioned “Security negotiation failed (wrong security type?)” on any RDP connection. I can’t implement your work around since it’s a container image and I don’t see this issue documented anywhere else. I’ll probably have to rollback to 1.1.0 but any ideas you might have would be appreciated.
you should update the instructions to use ./configure –with-systemd-dir=/etc/systemd/system if you are gonna start guacd with systemctl. also you might include that windows10 might require nla in order to function.
Hi SM. Thanks for the feedback. We will update this.
I believe I followed every step in your tutorial properly, and I believe I corrected any mistakes (e.g. telling it to use systemd instead of init.d) but I’m stuck at the step, “Accessing Apache Guacamole from Browser.” I get a 404 from tomcat when I go to localhost:8080/guacamole. Does anyone have any ideas?
In the meantime, I think I will install it using Docker.
Sounds like you didnt deploy the web app/client? guacamole.war. Please check and confirm.
Also go through the logs to find an idea what issue might be