Install Apache Guacamole on Rocky Linux 8

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.

Installing 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-client which provides the client to be served by the servlet container which is usually Tomcat.

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;

mkdir /usr/share/tomcat

Download Tomcat binary distributions. We use version 9.0.50 in this demo.

https://downloads.apache.org/tomcat/tomcat-9/v9.0.50/bin/apache-tomcat-9.0.50.tar.gz

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 daemon-reload

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[1]: Starting Tomcat Server...
Jul 24 07:28:00 localhost.localdomain systemd[1]: 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;

wget https://downloads.apache.org/guacamole/1.3.0/source/guacamole-server-1.3.0.tar.gz

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;

cd guacamole-server-1.3.0

Run the configure script to check if any required dependency is missing and to adapt Guacamole server to your system.

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

For more configure options, run, ./configure --help.

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;

make

make install

Next, run the ldconfig command to create the necessary links and cache to the most recent shared libraries found in the guacamole server directory.

ldconfig

Running Guacamole-Server

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[1]: Started Guacamole Server.
Jul 24 07:01:17 localhost.localdomain guacd[41779]: Guacamole proxy daemon (guacd) version 1.3.0 started
Jul 24 07:01:17 localhost.localdomain guacd[41779]: guacd[41779]: INFO:        Guacamole proxy daemon (guacd) version 1.3.0 started
Jul 24 07:01:17 localhost.localdomain guacd[41779]: guacd[41779]: INFO:        Listening on host 127.0.0.1, port 4822
Jul 24 07:01:17 localhost.localdomain guacd[41779]: 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;

mkdir /etc/guacamole

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;

mkdir /etc/guacamole/{extensions,lib}

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 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.

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, /var/log/messages or /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 http://server-IP:8080/guacamole.

Allow external access to Apache Guacamole via Apache Tomcat on firewalld;

firewall-cmd --add-port=8080/tcp --permanent

firewall-cmd --reload

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 /var/log/messages.

Jul 25 20:31:28 localhost guacd[3875]: guacd[4152]: 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[4152]: No security mode specified. Defaulting to security mode negotiation with server.
Jul 25 20:31:28 localhost guacd[4152]: Resize method: none

Jul 25 20:31:29 localhost guacd[4152]: RDP server closed/refused connection: Security negotiation failed (wrong security type?)
Jul 25 20:31:29 localhost guacd[3875]: guacd[4152]: 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

mkdir /var/lib/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;

systemctl daemon-reload

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.

Read more on Guacamole User Guide.

Other Tutorials

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