Apache Guacamole is a powerful remote desktop gateway that allows users to connect to their computers or servers remotely using various protocols such as SSH, RDP, and VNC. It is a clientless solution, meaning it can be accessed using only a web browser, making it convenient and flexible for users. In this article, we will guide you through the process of installing and configuring Apache Guacamole on a Debian 11 Bullseye server.

Prerequisites

Before we begin, let’s ensure that we have all the necessary prerequisites in place:

• A server with at least 2GB of RAM running Debian 11 Bullseye.
• A user with root privileges or a non-root user with sudo privileges.
• Basic knowledge of the nano editor or any preferred text editor.

Installing Build Dependencies

To start the installation process, we need to install some build dependencies that are required for building the Apache Guacamole server. These dependencies include packages for various protocols such as VNC, SSH, and RDP. Additionally, we’ll install other necessary libraries and tools. Run the following commands to update the package list and install the dependencies:

sudo apt update
sudo apt install -y freerdp2-dev libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libcairo2-dev libjpeg62-turbo-dev libjpeg-dev libpng-dev libtool-bin libpango1.0-dev libpango1.0-0 libssh2-1 libwebsockets16 libwebsocketpp-dev libossp-uuid-dev libssl-dev libwebp-dev libvorbis-dev libpulse-dev libwebsockets-dev libvncserver-dev libssh2-1-dev openssl

Installing Apache Tomcat 9

Next, we will install Apache Tomcat 9, which is required for running the Guacamole web application. Apache Tomcat is a popular open-source web server and servlet container that supports Java-based web applications. Run the following command to install Apache Tomcat 9:

sudo apt install -y tomcat9 tomcat9-admin tomcat9-common tomcat9-user

Once the installation is complete, start and enable the Apache Tomcat service using the following command:

sudo systemctl enable --now tomcat9

To verify the status of the Tomcat service, run the following command:

sudo systemctl status tomcat9

Make sure the service is active and running.

Compiling Guacamole-Server

Now, let’s move on to compiling the Guacamole-server, which is the main component of Apache Guacamole. The Guacamole-server contains libraries for connecting to remote servers and desktops, as well as the guacd service that handles client connections. To get started, run the following commands:

cd /usr/src
wget https://dlcdn.apache.org/guacamole/1.3.0/source/guacamole-server-1.3.0.tar.gz
tar -xzvf guacamole-server-1.3.0.tar.gz
cd guacamole-server-*/

Before we proceed with the compilation process, let’s ensure that all the necessary system requirements are met. Run the following command to verify the requirements and set up the environment:

./configure --with-systemd-dir=/etc/systemd/system/

This command will check for the required libraries and protocols, and set up the systemd service file for Guacamole. Make sure all the required libraries are present and the protocols you need are supported.

Next, compile and install the Guacamole-server by running the following commands:

make
sudo make install

After the installation is complete, apply the new system libraries by running the following command:

sudo ldconfig

Congratulations! You have successfully installed the Guacamole-server package.

Setting Up Guacamole-Server

In this section, we will configure the Guacamole-server by creating the necessary configuration files. These files include ‘guacamole.properties’ for general server configuration, ‘logback.xml’ for logging, and ‘user-mapping.xml’ for user authentication and connection definitions.

To begin, create the ‘/etc/guacamole/’ directory and its subdirectories using the following command:

sudo mkdir -p /etc/guacamole/{extensions,lib}

Next, add the ‘GUACAMOLE_HOME’ environment variable to the ‘/etc/default/tomcat9’ file, which tells Tomcat 9 to look for Guacamole configuration files in the ‘/etc/guacamole/’ directory:

echo 'GUACAMOLE_HOME=/etc/guacamole' | sudo tee -a /etc/default/tomcat9

Now, let’s create the ‘guacamole.properties’ file, which contains the main server configuration:

sudo nano /etc/guacamole/guacamole.properties

Enter the following configuration into the file:

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

In this configuration, ‘guacd-hostname’ specifies the hostname or IP address where the guacd service is running. For this tutorial, we will use ‘localhost’.

‘guacd-port’ specifies the port number for the guacd service. The default port is 4822.

‘user-mapping’ specifies the path to the ‘user-mapping.xml’ file, which defines user authentication and connection details.

Save and close the file.

Next, let’s create the ‘logback.xml’ file for logging and debugging:

sudo nano /etc/guacamole/logback.xml

Add the following configuration to the file:

<configuration>
<appender name="GUAC-DEBUG" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
<pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
</encoder>
</appender>

<root level="debug">
<appender-ref ref="GUAC-DEBUG"/>
</root>
</configuration>

This configuration enables logging and sets the log level to ‘debug’, allowing you to troubleshoot any issues that may arise.

Save and close the file.

Now, let’s create the ‘user-mapping.xml’ file to define user authentication and connection details:

sudo nano /etc/guacamole/user-mapping.xml

Enter the following configuration into the file:

<user-mapping>
<authorize username="shapehost" password="aca22211ffcfb8aa8ad7627195ad4fce" encoding="md5">
<connection name="SSH localhost">
<protocol>ssh</protocol>
<param name="hostname">localhost</param>
<param name="port">22</param>
<param name="username">shapehost</param>
<param name="password">shapehost</param>
</connection>
</authorize>
</user-mapping>

In this configuration, ‘authorize’ defines the username and password for authentication. The password is encoded using MD5.

‘connection’ defines the connection details, such as the protocol, hostname, port, and credentials.

Save and close the file.

Congratulations! You have successfully set up the Guacamole-server.

Installing Guacamole Client Web Application

Now that the Guacamole-server is configured, let’s install the Guacamole web application, which provides the user interface for accessing remote desktops. Run the following commands to download and deploy the Guacamole web application:

cd /usr/src
wget https://dlcdn.apache.org/guacamole/1.3.0/binary/guacamole-1.3.0.war
sudo cp guacamole-1.3.0.war /var/lib/tomcat9/webapps/guacamole.war

This will download the Guacamole web application and deploy it to the Tomcat webapps directory.

Restart the Tomcat service to apply the changes:

sudo systemctl restart tomcat9

Next, start and enable the ‘guacd’ service, which is responsible for handling client connections:

sudo systemctl enable --now guacd

Verify the status of the ‘guacd’ service:

sudo systemctl status guacd

Make sure the service is active and running.

Setup Nginx Reverse Proxy for Guacamole

To make the Guacamole web application accessible from a domain name and secure it with SSL certificates, we will set up Nginx as a reverse proxy. Nginx is a popular web server and reverse proxy server that provides excellent performance and security features.

Start by installing Nginx on your Debian 11 server:

sudo apt install nginx -y

Once the installation is complete, create a new virtual host file for Guacamole:

sudo nano /etc/nginx/sites-available/guacamole

Enter the following configuration into the file:

server {
listen 80;
server_name example.io;
rewrite ^ https://$host$request_uri? permanent;
}

server {
listen 443 ssl http2;
server_name example.io;

root /var/www/html;
index index.html;

location / {
try_files $uri $uri/ =404;
}

ssl_certificate /etc/letsencrypt/live/example.io/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.io/privkey.pem;

access_log /var/log/nginx/guacamole-access.log;
error_log /var/log/nginx/guacamole-error.log;

location /guacamole/ {
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;
access_log off;
}
}

In this configuration, replace ‘example.io’ with your domain name. Also, make sure to specify the correct paths for your SSL certificates.

Save and close the file.

Activate the virtual host by creating a symbolic link:

sudo ln -s /etc/nginx/sites-available/guacamole /etc/nginx/sites-enabled/

Verify the Nginx configuration for any syntax errors:

sudo nginx -t

If there are no errors, restart the Nginx service:

sudo systemctl restart nginx

Congratulations! You have successfully set up Nginx as a reverse proxy for Guacamole.

Verify Apache Guacamole Installation

Now that everything is set up, let’s verify the Apache Guacamole installation.

Open a web browser and enter the following URL, replacing ‘example.io’ with your domain name:

https://example.io/guacamole/

You will see the Guacamole login page. Enter the username and password that you configured in the ‘user-mapping.xml’ file, and click the Login button.

Once logged in, you will see a list of defined connections. Click on a connection name to connect to the corresponding server or desktop.

Congratulations! You have successfully installed and configured Apache Guacamole on Debian 11. You can now securely access your remote servers and desktops using the Guacamole web application.

For reliable and scalable cloud hosting solutions, consider checking out Shape.host. Shape.host offers Linux SSD VPS services that provide excellent performance and flexibility for your business needs.