How to Install Apache Guacamole on CentOS Stream 9: Manage RDP, SSH, and VNC via Your Browser

CentOS tutorial - IT technology blog
CentOS tutorial - IT technology blog

Midnight Server Outages and the Unfamiliar Device Dilemma

It’s 11 PM on a Saturday, and an alert notifies you that a critical service is down. You’re away from your workstation, with only a borrowed Chromebook or an iPad on hand. The device lacks OpenVPN, has no PuTTY, and certainly doesn’t have Remote Desktop pre-configured with your private keys.

At this moment, troubleshooting via SSH feels nearly impossible. You face spending 20 minutes just downloading client software, importing network profiles, and configuring everything from scratch.

This challenge is equally common for standard office staff. An accountant working from home or an executive on a business trip simply wants to open a browser and access company desktop software. Forcing them to install a VPN client, extract certificates, and configure Remote Desktop invariably generates a flood of IT support tickets.

Why Traditional Remote Access Creates Operational Headaches

Client-dependent remote access architectures introduce several critical bottlenecks:

  • Tool Fragmentation: Each protocol requires a dedicated application, such as PuTTY for SSH, Remote Desktop for RDP, or RealVNC.
  • Port Exposure Risks: Exposing ports 3389 or 22 directly to the internet via NAT invites botnet attacks. Shodan data reveals that an exposed RDP port is typically targeted by brute-force scans within 15 to 30 minutes.
  • Environment Conflicts: Configuring VPN clients on personal macOS, Linux, or Android devices frequently breaks virtual TAP/TUN network drivers following OS updates.

When managing a 40-node CentOS cluster and handing off staging environments to external partners, our team previously spent an average of 45 minutes per team member just walking them through OpenVPN installation and access provisioning.

Comparing Popular Remote Access Approaches

Before implementing a centralized gateway, most sysadmins weigh three primary options:

  1. Router NAT/Port Forwarding: The fastest setup, but it carries a severe risk of zero-day exploits and bandwidth degradation from continuous port-scanning traffic.
  2. Commercial Software (TeamViewer, AnyDesk): Convenient for end users, but enterprise tiers cost $30–$50/user/month and route all traffic through third-party servers.
  3. Dedicated VPN Servers (WireGuard, OpenVPN): Strong encryption and security, but still mandate installing client software, making access from borrowed or public machines impossible.

The Solution: Apache Guacamole as a Browser-Based Remote Gateway

Apache Guacamole is a clientless remote desktop gateway. Running centrally on your server, it acts as a protocol translator. Guacamole connects to internal machines using RDP, SSH, or VNC, renders the remote desktop into an HTML5 stream, and serves it directly to the browser via WebSockets.

Users only need a standard browser like Chrome, Firefox, or Safari for a seamless remote session. The platform delivers full support for keyboard, mouse, clipboard sharing, and bidirectional audio.

Step 1: Prepare the Environment and Build Dependencies

CentOS Stream 9 requires enabling the EPEL and CRB (CodeReady Builder) repositories to retrieve required development libraries:

sudo dnf update -y
sudo dnf install -y epel-release dnf-plugins-core
sudo dnf config-manager --set-enabled crb
sudo dnf install -y gcc make cairo-devel libpng-devel libtool libuuid-devel \
    pango-devel libvncserver-devel freerdp-devel libssh2-devel libvorbis-devel \
    libwebp-devel pulseaudio-libs-devel openssl-devel java-11-openjdk-devel wget tar

Step 2: Compile Guacamole Server (guacd)

Download the source code for guacd version 1.5.5 and compile it from source to ensure maximum compatibility with system libraries:

cd /tmp
wget https://downloads.apache.org/guacamole/1.5.5/source/guacamole-server-1.5.5.tar.gz
tar -xvzf guacamole-server-1.5.5.tar.gz
cd guacamole-server-1.5.5

./configure --with-systemd-dir=/etc/systemd/system
make -j$(nproc)
sudo make install
sudo ldconfig

Enable and start the background daemon listening on port 4822:

sudo systemctl daemon-reload
sudo systemctl enable --now guacd
sudo systemctl status guacd

Step 3: Install Tomcat and Deploy the Web Client

The Guacamole Client runs as a .war file on a Java servlet container such as Apache Tomcat:

sudo dnf install -y tomcat
sudo mkdir -p /etc/guacamole /etc/guacamole/extensions /etc/guacamole/lib

cd /tmp
wget https://downloads.apache.org/guacamole/1.5.5/binary/guacamole-1.5.5.war
sudo cp guacamole-1.5.5.war /var/lib/tomcat/webapps/guacamole.war

Create the connection configuration file /etc/guacamole/guacamole.properties:

sudo bash -c 'cat <<EOF > /etc/guacamole/guacamole.properties
guacd-hostname: 127.0.0.1
guacd-port: 4822
user-mapping: /etc/guacamole/user-mapping.xml
EOF'

Create a symbolic link so Tomcat can locate the configuration directory:

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

Step 4: Configure Users and Remote Target Connections

If you don’t yet need an external database (MySQL/PostgreSQL) or LDAP integration, you can quickly define users in /etc/guacamole/user-mapping.xml:

sudo bash -c 'cat <<EOF > /etc/guacamole/user-mapping.xml
<user-mapping>
    <authorize username="sysadmin" password="SecurePassword@2026">
        <connection name="Windows-Server-App">
            <protocol>rdp</protocol>
            <param name="hostname">192.168.1.50</param>
            <param name="port">3389</param>
            <param name="ignore-cert">true</param>
            <param name="enable-wallpaper">false</param>
        </connection>
        <connection name="DB-Master-CentOS">
            <protocol>ssh</protocol>
            <param name="hostname">192.168.1.10</param>
            <param name="port">22</param>
        </connection>
    </authorize>
</user-mapping>
EOF'

Start Tomcat:

sudo systemctl enable --now tomcat

Step 5: Set Up an Nginx Reverse Proxy and Firewall

Tomcat listens on port 8080 by default. Placing Nginx in front improves WebSocket handling and streamlines SSL certificate management via Let’s Encrypt:

sudo dnf install -y nginx
sudo bash -c 'cat <<EOF > /etc/nginx/conf.d/guacamole.conf
server {
    listen 80;
    server_name remote.company.com;

    location / {
        proxy_pass http://127.0.0.1:8080/guacamole/;
        proxy_buffering off;
        proxy_http_version 1.1;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_set_header Upgrade \$http_upgrade;
        proxy_set_header Connection \$http_connection;
        proxy_read_timeout 3600s;
    }
}
EOF'

Configure SELinux permissions and allow traffic through FirewallD:

sudo setsebool -P httpd_can_network_connect 1
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload
sudo systemctl enable --now nginx

Real-World Performance Evaluation

Navigate to http://remote.company.com and sign in using the sysadmin credentials you created. The dashboard will display all configured remote targets ready for connection.

Testing over a standard 4G connection with ~25ms latency yielded responsive Windows 11 RDP sessions with no noticeable input lag. Total RAM usage across the entire Guacamole stack (Tomcat + guacd) hovered around 1.2 GB—exceptionally lightweight for a standard CentOS Stream 9 VPS.

Share: