Setting Up Apache Guacamole on a VPS

Configuration

After installing all components, they need to be configured correctly. This includes configuring Guacamole to connect to the database, setting up Tomcat, and installing the Caddy reverse proxy server to provide HTTPS.

1. Guacamole Configuration (guacamole.properties)

The main Guacamole configuration file is guacamole.properties. It tells Guacamole how to connect to the database and other components.

# Create or edit the guacamole.properties file
sudo nano /etc/guacamole/guacamole.properties

Add the following content to the file, replacing your_db_password with your password for the PostgreSQL user guacamole_user:

# Hostname and port of guacd
guacd-hostname: localhost
guacd-port: 4822

# PostgreSQL authentication
postgresql-hostname: localhost
postgresql-port: 5432
postgresql-database: guacamole_db
postgresql-username: guacamole_user
postgresql-password: your_db_password

Save changes (Ctrl+O, Enter) and exit (Ctrl+X).

2. Configuring Tomcat to Use Guacamole

Tomcat needs to be told where to find the Guacamole configuration. This is done by creating a setenv.sh file.

# Create directory for Tomcat settings
sudo mkdir -p /etc/tomcat10/conf/Catalina/localhost/

# Create setenv.sh file for Tomcat
sudo nano /usr/share/tomcat10/bin/setenv.sh

Add the following line to setenv.sh:

#!/bin/bash
export GUACAMOLE_HOME=/etc/guacamole

Save changes. Make the file executable and restart Tomcat:

# Make setenv.sh executable
sudo chmod +x /usr/share/tomcat10/bin/setenv.sh

# Restart Tomcat to apply changes
sudo systemctl restart tomcat10

# Check Tomcat logs for errors
sudo journalctl -u tomcat10 --since "5 minutes ago"

Tomcat logs should show entries about Guacamole loading without critical errors.

3. Configuring Caddy Server for HTTPS

Caddy is a modern web server with automatic HTTPS. It is ideal for Guacamole as it automatically obtains and renews SSL/TLS certificates via Let's Encrypt.

# Install Caddy.
# Add Caddy repository
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list

# Update package list and install Caddy
sudo apt update
sudo apt install -y caddy

Configure Caddyfile. Replace guacamole.yourdomain.com with your actual domain that points to your VPS's IP address.

# Edit Caddyfile
sudo nano /etc/caddy/Caddyfile

Remove existing content and add the following:

guacamole.yourdomain.com {
    reverse_proxy localhost:8080 {
        header_up Host {host}
        header_up X-Real-IP {remote_ip}
        header_up X-Forwarded-For {remote_ip}
        header_up X-Forwarded-Proto {scheme}
    }

    # Enable Gzip compression for improved performance
    encode gzip
}

Save the file and restart Caddy:

# Validate Caddy configuration
sudo caddy validate --config /etc/caddy/Caddyfile

# Restart Caddy
sudo systemctl reload caddy

# Ensure Caddy is running
sudo systemctl status caddy

Now your Apache Guacamole should be accessible via HTTPS at https://guacamole.yourdomain.com.

4. Verifying Functionality

Open a web browser and navigate to your domain name (e.g., https://guacamole.yourdomain.com). You should see the Guacamole login page.

Use the default credentials: Username: guacadmin, Password: guacadmin. Immediately change this password after the first login!

After logging in, you can add a new connection. For example, for SSH:

• Click "New Connection".
• Select "SSH" as the protocol.
• In the "Hostname" field, enter the IP address or domain of your target SSH server.
• In the "Port" field, enter 22.
• In the "Username" and "Password" fields, enter the credentials for SSH access.
• Save the connection and try to connect to it.

If you encounter issues, check the logs for Tomcat (sudo journalctl -u tomcat10), Caddy (sudo journalctl -u caddy), and Guacd (sudo journalctl -u guacd) for errors.

Backups and Maintenance

Regular backups and system maintenance are critically important for the stable and secure operation of Apache Guacamole. Data loss or outdated software can lead to serious problems.

1. What to Back Up

For Guacamole, the following components must be backed up regularly:

• PostgreSQL Database: Contains all users, their settings, connection definitions, and audit logs. This is the most important component.
• Guacamole Configuration Files:
  • /etc/guacamole/guacamole.properties
  • /etc/guacamole/extensions/ (all JAR extension files)
  • /etc/guacamole/lib/ (JDBC driver)
• Caddy Configuration: /etc/caddy/Caddyfile
• Tomcat Configuration: /usr/share/tomcat10/bin/setenv.sh (and possibly other custom settings)
• SSH Keys: If you use them for Guacamole authentication on target servers (stored in /etc/guacamole/keys/ or similar locations).

2. Simple Auto-Backup Script

We will create a simple script that will back up the database and configuration files, and then package them. For storage, you can use an external S3-compatible object storage or a separate VPS.

For PostgreSQL database backups, we will use pg_dump. For files – tar. To send to S3, you can use s3cmd or awscli, but for simplicity, we will just create an archive.

# Create a directory for backup scripts
sudo mkdir -p /opt/backup_scripts
sudo chown youruser:youruser /opt/backup_scripts

# Create the backup script file
nano /opt/backup_scripts/guacamole_backup.sh

Add the following content to the guacamole_backup.sh file. Replace your_db_password, guacamole_user, and guacamole_db with your data. Also, specify the path to the directory where backups will be saved (e.g., /var/backups/guacamole).

#!/bin/bash

# Variables
BACKUP_DIR="/var/backups/guacamole"
DATE=$(date +%Y%m%d%H%M%S)
DB_NAME="guacamole_db"
DB_USER="guacamole_user"
DB_PASSWORD="your_db_password" # In production, use .pgpass or environment variables!

# Create backup directory if it doesn't exist
mkdir -p "$BACKUP_DIR"

# 1. PostgreSQL Database Backup
echo "Dumping PostgreSQL database..."
PGPASSWORD="$DB_PASSWORD" pg_dump -U "$DB_USER" -h localhost "$DB_NAME" > "$BACKUP_DIR/guacamole_db_$DATE.sql"
if [ $? -eq 0 ]; then
    echo "PostgreSQL database backup successful: $BACKUP_DIR/guacamole_db_$DATE.sql"
else
    echo "ERROR: PostgreSQL database backup failed."
    exit 1
fi

# 2. Guacamole and Caddy Configuration Files Backup
echo "Archiving configuration files..."
tar -czf "$BACKUP_DIR/guacamole_configs_$DATE.tar.gz" \
    /etc/guacamole \
    /etc/caddy/Caddyfile \
    /usr/share/tomcat10/bin/setenv.sh
if [ $? -eq 0 ]; then
    echo "Configuration files backup successful: $BACKUP_DIR/guacamole_configs_$DATE.tar.gz"
else
    echo "ERROR: Configuration files backup failed."
    exit 1
fi

# 3. Clean up old backups (keep last 7 days)
echo "Cleaning up old backups..."
find "$BACKUP_DIR" -type f -name ".sql" -mtime +7 -delete
find "$BACKUP_DIR" -type f -name ".tar.gz" -mtime +7 -delete
echo "Backup process completed."

# IMPORTANT: Send backups to external storage
# Here you can add commands to send files to S3, remote FTP/SFTP,
# or use specialized tools like restic or borg.
# Example for S3 with awscli (requires prior installation and configuration of awscli):
# aws s3 cp "$BACKUP_DIR/guacamole_db_$DATE.sql" s3://your-s3-bucket/guacamole/
# aws s3 cp "$BACKUP_DIR/guacamole_configs_$DATE.tar.gz" s3://your-s3-bucket/guacamole/

Save the file, make it executable, and configure Cron to run it regularly:

# Make the script executable
chmod +x /opt/backup_scripts/guacamole_backup.sh

# Create a directory for saving backups
sudo mkdir -p /var/backups/guacamole
sudo chown youruser:youruser /var/backups/guacamole

# Open crontab for the current user
crontab -e

Add the following line to run the backup daily at 03:00 AM:

0 3   * /opt/backup_scripts/guacamole_backup.sh >> /var/log/guacamole_backup.log 2>&1

Save and close crontab. Backups will now be created automatically.

3. Where to Store Backups

It is crucial to store backups on a resource separate from the main server. Options:

• External S3-compatible object storage: The most recommended option. Reliable, scalable, and relatively inexpensive.
• Separate VPS: You can set up a second, small VPS exclusively for storing backups from different servers.
• NAS/Network storage: If you have your own hardware.
• FTP/SFTP server: A simple but less reliable option if encryption and integrity control are not configured.

Never store the only copies of backups on the same server you are backing up!

4. Updates: rolling vs maintenance window

Regular software updates are important for security and new features. The approach to updates depends on the criticality of your system.

• Rolling updates: Suitable for less critical systems or high-availability systems with a cluster where nodes can be updated sequentially. For a single Guacamole VPS, this means applying updates as soon as they become available.
• Maintenance window: The preferred approach for most production systems, including Guacamole on a single VPS. A specific time is allocated (e.g., once a month at night) when updates can be performed, tested, and potential issues resolved.

Recommended update process:

1. Create a full backup before starting any updates.
2. Update the system:

   
   sudo apt update && sudo apt upgrade -y
   sudo apt autoremove -y
               

3. Update Guacamole components (if new versions are available):
   • Download new versions of guacamole-server (for guacd) and guacamole-client.war, as well as extensions.
   • Stop Tomcat and Guacd.
   • Replace old files with new ones.
   • Start the services.
4. Verify functionality: After each update, ensure that Guacamole is working correctly and that you can connect to various target systems.

Always read the changelog and update instructions on the official Apache Guacamole website before updating core components.

Troubleshooting + FAQ

This section covers typical issues that may arise when setting up Apache Guacamole, and answers to frequently asked questions.

Cannot connect to Guacamole by domain name (502 Bad Gateway or Connection Refused error)

What to check:

1. Ensure that your domain (e.g., guacamole.yourdomain.com) correctly points to your VPS's IP address in DNS records.
2. Check that Caddy Server is running: sudo systemctl status caddy.
3. Check Caddy logs: sudo journalctl -u caddy --since "5 minutes ago". Look for errors related to port binding or proxying.
4. Ensure that Tomcat is running and listening on port 8080: sudo systemctl status tomcat10 and sudo ss -tulpn | grep 8080.
5. Check that the UFW firewall allows incoming connections on ports 80 and 443: sudo ufw status verbose.

Guacamole page loads, but cannot log in (invalid credentials or database error)

What to check:

1. Check Tomcat logs: sudo journalctl -u tomcat10 --since "5 minutes ago". Look for errors related to database connection or authentication.
2. Ensure that PostgreSQL is running: sudo systemctl status postgresql.
3. Check the contents of /etc/guacamole/guacamole.properties. Ensure that postgresql-hostname, postgresql-port, postgresql-database, postgresql-username, and postgresql-password are specified correctly.
4. Ensure that the user guacamole_user has permissions on the guacamole_db database.
5. Try logging in with the default credentials guacadmin/guacadmin. If it works but your user does not, there might be an issue with user creation or permissions.

Cannot connect to a remote server (RDP/VNC/SSH) via Guacamole

What to check:

1. Check guacd logs: sudo journalctl -u guacd --since "5 minutes ago". Look for errors related to connecting to the remote host or protocol issues.
2. Ensure that guacd is running: sudo systemctl status guacd.
3. Check that the target server is accessible from your VPS (e.g., ping target_ip, telnet target_ip ssh_port).
4. Ensure that the firewall on the target server (and on your VPS, if it blocks outbound connections) allows incoming connections on the respective port (22 for SSH, 3389 for RDP, 5900 for VNC).
5. Check connection settings in the Guacamole web interface (hostname, port, credentials).

What is the minimum VPS configuration suitable for Apache Guacamole?

For one or two concurrent users and non-intensive use, a VPS with 2 CPU cores, 2 GB of RAM, and a 40 GB SSD disk will be minimally suitable. However, if you plan more active use, especially with RDP for graphical interfaces or for multiple users, a configuration with 4 CPU cores, 4 GB RAM, and an 80 GB NVMe SSD is highly recommended. This will provide significantly better performance and stability, preventing delays and freezes during video stream transcoding.

What to choose — VPS or dedicated for this task?

For most scenarios, including Guacamole use by a small team or individual user, a VPS is the optimal choice. It offers sufficient performance at a significantly lower cost and greater management flexibility. A dedicated server becomes necessary if you expect very high load (more than 20-30 concurrent users), require guaranteed physical CPU and RAM resources, or if you have strict regulatory requirements for complete hardware isolation. For starting and scaling, in most cases, a VPS will be the best solution, allowing you to easily upgrade your plan as needs grow.

How to reset the Guacamole administrator password?

What to check: If you forgot the guacadmin password, you can reset it by executing an SQL query in the PostgreSQL database. How to fix:

# Connect to PostgreSQL as the postgres user
sudo -i -u postgres

# Connect to the Guacamole database
psql guacamole_db

# Update the password for the guacadmin user (replace 'new_strong_password')
# The password must be SHA-256 hashed. In this example, we are resetting it to 'new_strong_password'
# and Guacamole will automatically hash it upon first login if you provide it as plaintext.
# For a secure reset, it's better to generate a hash:
# SELECT ENCODE(SHA256('new_strong_password'::bytea), 'hex');
# And then use it:
UPDATE guacamole_user SET password_hash = ENCODE(SHA256('new_strong_password'::bytea), 'hex'), password_salt = NULL WHERE username = 'guacadmin';

# If you just want to reset it to 'guacadmin' to change it later:
# UPDATE guacamole_user SET password_hash = 'C634887019799295598BB17F9A906F6F89304F7695D5D1426477546875931D80', password_salt = 'C634887019799295598BB17F9A906F6F89304F7695D5D1426477546875931D80' WHERE username = 'guacadmin';
# (this is the hash for 'guacadmin' with salt 'guacadmin', which was default during initialization)

# Exit psql
\q

# Exit postgres user
exit

# Restart Tomcat
sudo systemctl restart tomcat10

After this, you will be able to log in with the new password.