Tested March 2026<\/strong> on Ubuntu 24.04.4 LTS with Apache Guacamole 1.6.0, Tomcat 10.1.16, MariaDB 10.11.14, Nginx 1.24.0, FreeRDP 2.11.5<\/em><\/p>\n\n\n\n Before starting, confirm you have the following ready:<\/p>\n\n\n\n Update the system packages first:<\/p>\n\n\n\n Guacamole-server compiles from source and needs development libraries for each protocol it supports. Ubuntu 24.04 ships Install everything in one shot:<\/p>\n\n\n\n This pulls in the build toolchain, protocol libraries (VNC, RDP, SSH, Telnet, Kubernetes), Tomcat 10 as the servlet container, MariaDB for database-backed authentication, Nginx for reverse proxying, and the Jakarta migration tool (needed because Tomcat 10 uses Jakarta EE instead of javax).<\/p>\n\n\n\n Download the 1.6.0 source tarball and extract it:<\/p>\n\n\n\n Run the configure script to detect available protocol support:<\/p>\n\n\n\n At the end of the configure output, you should see all five protocols enabled:<\/p>\n\n\n\n If any protocol shows “no,” you’re missing a development library. Go back and check the dependency list. With all five confirmed, compile and install:<\/p>\n\n\n\n Update the shared library cache so the system can find the newly installed libraries:<\/p>\n\n\n\n Reload systemd and start the guacd daemon:<\/p>\n\n\n\n Verify guacd is running on port 4822:<\/p>\n\n\n\n The output should show The web application is a single WAR file that runs inside Tomcat. Download it:<\/p>\n\n\n\n Tomcat 10 on Ubuntu 24.04 uses the Jakarta EE namespace instead of the older javax namespace. The Guacamole WAR still uses javax internally, so it needs conversion. Without this step, you’ll get a blank page after login. The Restart Tomcat to deploy the converted WAR:<\/p>\n\n\n\n Tomcat should unpack the WAR into While Guacamole can use a simple XML file for user management, a database backend is the way to go for production. It gives you user management through the web UI, connection grouping, and session history. MariaDB 10.11.14 ships with Ubuntu 24.04.<\/p>\n\n\n\n Start by creating the database and user:<\/p>\n\n\n\n Replace Import the MySQL schema into the database:<\/p>\n\n\n\n Create the Guacamole extensions directory and convert the JDBC JAR to Jakarta namespace:<\/p>\n\n\n\n The JDBC JAR also needs the javax-to-jakarta conversion because it runs inside Tomcat 10. Skipping this causes authentication failures.<\/p>\n\n\n\n Now download the MySQL Connector\/J driver so Guacamole can talk to MariaDB:<\/p>\n\n\n\n MySQL Connector\/J 9.2.0 works with both MySQL and MariaDB.<\/p>\n\n\n\n Guacamole reads its main configuration from Use the same password you set when creating the MariaDB user. Lock down the file permissions since it contains a database password:<\/p>\n\n\n\n Link the Guacamole home directory so Tomcat can find it:<\/p>\n\n\n\n Restart Tomcat to pick up the new configuration:<\/p>\n\n\n\n At this point, Guacamole should be accessible on port 8080 via Tomcat directly. The next step adds Nginx with SSL in front of it.<\/p>\n\n\n\n Running Guacamole behind Nginx with SSL gives you encrypted connections and lets you serve it on a clean URL without the Replace Create the Nginx virtual host configuration:<\/p>\n\n\n\n Add the following configuration. The WebSocket headers are critical because Guacamole uses WebSocket for the remote desktop tunnel:<\/p>\n\n\n\n Enable the site and test the configuration:<\/p>\n\n\n\n If the syntax test passes, start Nginx:<\/p>\n\n\n\n Open the firewall for HTTPS traffic:<\/p>\n\n\n\n Verify certificate auto-renewal is working:<\/p>\n\n\n\n Guacamole is now accessible at Open your browser and navigate to your domain. The default credentials are After logging in, you’ll land on the home dashboard. Since this is a fresh installation, the recent connections list will be empty:<\/p>\n\n\n\n Click the guacadmin<\/strong> username in the top-right corner, then select Settings<\/strong> to reach the administration panel:<\/p>\n\n\n\n The Users<\/strong> tab shows all accounts in the system. From here you can create new users, assign them to connection groups, and control permissions:<\/p>\n\n\n\n To add a remote connection, go to Settings<\/strong> \u2192 Connections<\/strong> \u2192 New Connection<\/strong>. Select the protocol (RDP, VNC, SSH, Telnet, or Kubernetes), enter the target hostname and port, and provide credentials. All five protocols are fully functional on Ubuntu 24.04 since FreeRDP 2.11.5 is compatible with Guacamole 1.6.0. For SSH connections, you can paste your private key directly into the connection settings. For RDP, specify the target host’s IP, port 3389, and the Windows username and password.<\/p>\n\n\n\n The default Restrict access to the administration panel by creating regular (non-admin) accounts for daily use. Only grant admin privileges to accounts that genuinely need to manage connections and users.<\/p>\n\n\n\n For two-factor authentication, download the TOTP extension and convert it to Jakarta namespace, same as the JDBC extension:<\/p>\n\n\n\n After restarting Tomcat, the next login will prompt each user to scan a QR code with an authenticator app like Google Authenticator or Authy. This adds a significant layer of protection, especially if you’re exposing Guacamole to the internet.<\/p>\n\n\n\n This is the most common issue. Tomcat 10 uses the Jakarta EE namespace ( Check the logs for missing library errors:<\/p>\n\n\n\n The most common cause is a missing If remote desktop connections fail with tunnel errors in the browser, the Nginx configuration is likely missing the WebSocket upgrade headers. Guacamole uses WebSocket for the display tunnel, and without the The For additional configuration options including recording sessions, connecting to Kubernetes pods, and setting up failover, refer to the official Guacamole documentation<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":" Apache Guacamole gives you browser-based access to your servers through RDP, VNC, SSH, Telnet, and even Kubernetes pods, all without installing a client on your local machine. It’s one of those tools that, once set up, makes you wonder why you ever bothered with standalone remote desktop apps. Version 1.6.0 brings several improvements to the … Read more<\/a><\/p>\n","protected":false},"author":7,"featured_media":81524,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[299,50,75,81],"tags":[35640,762,2254],"class_list":["post-81520","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-how-to","category-linux-tutorials","category-security","category-ubuntu","tag-guacamole","tag-remote-desktop","tag-ubuntu"],"_links":{"self":[{"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/posts\/81520","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/users\/7"}],"replies":[{"embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/comments?post=81520"}],"version-history":[{"count":1,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/posts\/81520\/revisions"}],"predecessor-version":[{"id":164842,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/posts\/81520\/revisions\/164842"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/media\/81524"}],"wp:attachment":[{"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/media?parent=81520"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/categories?post=81520"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/tags?post=81520"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}Prerequisites<\/h2>\n\n\n\n
\n
sudo apt update && sudo apt upgrade -y<\/code><\/pre>\n\n\n\nInstall Build Dependencies<\/h2>\n\n\n\n
freerdp2-dev<\/code> (FreeRDP 2.11.5), which is fully compatible with Guacamole 1.6.0. This is a real advantage over Debian 13, which ships FreeRDP 3 and requires extra work for RDP support.<\/p>\n\n\n\nsudo apt-get install -y build-essential libcairo2-dev libjpeg-turbo8-dev libpng-dev libtool-bin uuid-dev libossp-uuid-dev \\\n libvncserver-dev freerdp2-dev libssh2-1-dev libssl-dev libtelnet-dev libpango1.0-dev libwebsockets-dev \\\n libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libvorbis-dev libwebp-dev libpulse-dev \\\n tomcat10 mariadb-server nginx certbot tomcat-jakartaee-migration wget curl<\/code><\/pre>\n\n\n\nBuild and Install guacamole-server<\/h2>\n\n\n\n
cd \/tmp\nwget https:\/\/downloads.apache.org\/guacamole\/1.6.0\/source\/guacamole-server-1.6.0.tar.gz\ntar -xzf guacamole-server-1.6.0.tar.gz\ncd guacamole-server-1.6.0<\/code><\/pre>\n\n\n\n.\/configure --with-systemd-dir=\/etc\/systemd\/system\/<\/code><\/pre>\n\n\n\n Protocol support:\n\n Kubernetes .... yes\n RDP ........... yes\n SSH ........... yes\n Telnet ........ yes\n VNC ........... yes<\/code><\/pre>\n\n\n\nmake -j$(nproc)\nsudo make install<\/code><\/pre>\n\n\n\nsudo ldconfig<\/code><\/pre>\n\n\n\nsudo systemctl daemon-reload\nsudo systemctl enable --now guacd<\/code><\/pre>\n\n\n\nsudo systemctl status guacd<\/code><\/pre>\n\n\n\nactive (running)<\/code> with guacd listening on its default port. If it fails to start, check \/var\/log\/syslog<\/code> for missing library errors.<\/p>\n\n\n\nDeploy the Guacamole Web Application<\/h2>\n\n\n\n
cd \/tmp\nwget https:\/\/downloads.apache.org\/guacamole\/1.6.0\/binary\/guacamole-1.6.0.war<\/code><\/pre>\n\n\n\ntomcat-jakartaee-migration<\/code> package you installed earlier provides the conversion tool:<\/p>\n\n\n\nsudo javax2jakarta \/tmp\/guacamole-1.6.0.war \/var\/lib\/tomcat10\/webapps\/guacamole.war<\/code><\/pre>\n\n\n\nsudo systemctl restart tomcat10<\/code><\/pre>\n\n\n\n\/var\/lib\/tomcat10\/webapps\/guacamole\/<\/code> within a few seconds.<\/p>\n\n\n\nSet Up MariaDB Database<\/h2>\n\n\n\n
sudo mysql -e \"CREATE DATABASE guacamole_db CHARACTER SET utf8mb4;\"\nsudo mysql -e \"CREATE USER 'guacamole_user'@'localhost' IDENTIFIED BY 'StrongPassword123!';\"\nsudo mysql -e \"GRANT SELECT,INSERT,UPDATE,DELETE ON guacamole_db.* TO 'guacamole_user'@'localhost';\"\nsudo mysql -e \"FLUSH PRIVILEGES;\"<\/code><\/pre>\n\n\n\nStrongPassword123!<\/code> with a real password. Next, download the JDBC authentication extension:<\/p>\n\n\n\ncd \/tmp\nwget https:\/\/downloads.apache.org\/guacamole\/1.6.0\/binary\/guacamole-auth-jdbc-1.6.0.tar.gz\ntar -xzf guacamole-auth-jdbc-1.6.0.tar.gz<\/code><\/pre>\n\n\n\ncat \/tmp\/guacamole-auth-jdbc-1.6.0\/mysql\/schema\/*.sql | sudo mysql guacamole_db<\/code><\/pre>\n\n\n\nsudo mkdir -p \/etc\/guacamole\/extensions\nsudo javax2jakarta \/tmp\/guacamole-auth-jdbc-1.6.0\/mysql\/guacamole-auth-jdbc-mysql-1.6.0.jar \/etc\/guacamole\/extensions\/guacamole-auth-jdbc-mysql-1.6.0.jar<\/code><\/pre>\n\n\n\nsudo mkdir -p \/etc\/guacamole\/lib\ncd \/tmp\nwget https:\/\/dev.mysql.com\/get\/Downloads\/Connector-J\/mysql-connector-j-9.2.0.tar.gz\ntar -xzf mysql-connector-j-9.2.0.tar.gz\nsudo cp mysql-connector-j-9.2.0\/mysql-connector-j-9.2.0.jar \/etc\/guacamole\/lib\/<\/code><\/pre>\n\n\n\nConfigure guacamole.properties<\/h2>\n\n\n\n
\/etc\/guacamole\/guacamole.properties<\/code>. This file tells the web application where to find guacd and which database to authenticate against.<\/p>\n\n\n\necho \"guacd-hostname: localhost\nguacd-port: 4822\nmysql-hostname: localhost\nmysql-port: 3306\nmysql-database: guacamole_db\nmysql-username: guacamole_user\nmysql-password: StrongPassword123!\nmysql-auto-create-accounts: true\" | sudo tee \/etc\/guacamole\/guacamole.properties<\/code><\/pre>\n\n\n\nsudo chmod 600 \/etc\/guacamole\/guacamole.properties\nsudo chown tomcat:tomcat \/etc\/guacamole\/guacamole.properties<\/code><\/pre>\n\n\n\nsudo ln -sf \/etc\/guacamole \/var\/lib\/tomcat10\/.guacamole<\/code><\/pre>\n\n\n\nsudo systemctl restart tomcat10<\/code><\/pre>\n\n\n\nSet Up Nginx Reverse Proxy with SSL<\/h2>\n\n\n\n
\/guacamole<\/code> path suffix. Obtain a Let’s Encrypt certificate first:<\/p>\n\n\n\nsudo certbot certonly --standalone -d guacamole.computingforgeeks.com --non-interactive --agree-tos -m kiplangatmtai@gmail.com<\/code><\/pre>\n\n\n\nguacamole.computingforgeeks.com<\/code> with your actual domain. Certbot needs port 80 free, so stop Nginx temporarily if it’s already running (sudo systemctl stop nginx<\/code>) before running certbot.<\/p>\n\n\n\nsudo vi \/etc\/nginx\/sites-available\/guacamole<\/code><\/pre>\n\n\n\nserver {\n listen 443 ssl http2;\n server_name guacamole.computingforgeeks.com;\n\n ssl_certificate \/etc\/letsencrypt\/live\/guacamole.computingforgeeks.com\/fullchain.pem;\n ssl_certificate_key \/etc\/letsencrypt\/live\/guacamole.computingforgeeks.com\/privkey.pem;\n\n location \/ {\n proxy_pass http:\/\/127.0.0.1:8080\/guacamole\/;\n proxy_buffering off;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n proxy_set_header Upgrade $http_upgrade;\n proxy_set_header Connection $http_connection;\n proxy_cookie_path \/guacamole\/ \/;\n }\n}\n\nserver {\n listen 80;\n server_name guacamole.computingforgeeks.com;\n return 301 https:\/\/$host$request_uri;\n}<\/code><\/pre>\n\n\n\nsudo ln -sf \/etc\/nginx\/sites-available\/guacamole \/etc\/nginx\/sites-enabled\/\nsudo rm -f \/etc\/nginx\/sites-enabled\/default\nsudo nginx -t<\/code><\/pre>\n\n\n\nsudo systemctl enable --now nginx<\/code><\/pre>\n\n\n\nsudo ufw allow 80\/tcp\nsudo ufw allow 443\/tcp\nsudo ufw reload<\/code><\/pre>\n\n\n\nsudo certbot renew --dry-run<\/code><\/pre>\n\n\n\nhttps:\/\/guacamole.computingforgeeks.com<\/code>.<\/p>\n\n\n\nAccess the Web UI<\/h2>\n\n\n\n
guacadmin<\/code> for both username and password.<\/p>\n\n\n\n![\"Apache](\"https:\/\/computingforgeeks.com\/wp-content\/uploads\/2026\/03\/01-login-1.png\" "\\"\\"")
<\/figure>\n\n\n\n![\"Apache](\"https:\/\/computingforgeeks.com\/wp-content\/uploads\/2026\/03\/02-home.png\" "\\"\\"")
<\/figure>\n\n\n\nManage Connections and Users<\/h2>\n\n\n\n
![\"Apache](\"https:\/\/computingforgeeks.com\/wp-content\/uploads\/2026\/03\/03-settings.png\" "\\"\\"")
<\/figure>\n\n\n\n![\"Apache](\"https:\/\/computingforgeeks.com\/wp-content\/uploads\/2026\/03\/04-users.png\" "\\"\\"")
<\/figure>\n\n\n\nProduction Hardening<\/h2>\n\n\n\n
guacadmin<\/code> account is a well-known target. Change its password immediately after your first login through Settings<\/strong> \u2192 Users<\/strong> \u2192 guacadmin<\/strong> \u2192 Change Password<\/strong>. Better yet, create a new admin user with a unique username and disable the default account entirely.<\/p>\n\n\n\ncd \/tmp\nwget https:\/\/downloads.apache.org\/guacamole\/1.6.0\/binary\/guacamole-auth-totp-1.6.0.tar.gz\ntar -xzf guacamole-auth-totp-1.6.0.tar.gz\nsudo javax2jakarta \/tmp\/guacamole-auth-totp-1.6.0\/guacamole-auth-totp-1.6.0.jar \/etc\/guacamole\/extensions\/guacamole-auth-totp-1.6.0.jar\nsudo systemctl restart tomcat10<\/code><\/pre>\n\n\n\nTroubleshooting<\/h2>\n\n\n\n
Blank page after login on Tomcat 10<\/h3>\n\n\n\n
jakarta.servlet<\/code>) while the Guacamole WAR and JDBC extension use the older javax.servlet<\/code> namespace. If you deployed the WAR without running javax2jakarta<\/code> on it, the application loads but every servlet call fails silently, resulting in a blank page. The fix is to convert both the WAR file and the JDBC extension JAR using the javax2jakarta<\/code> tool, then restart Tomcat.<\/p>\n\n\n\nguacd fails to start<\/h3>\n\n\n\n
sudo journalctl -u guacd -n 50 --no-pager<\/code><\/pre>\n\n\n\nldconfig<\/code> run after make install<\/code>. The guacd binary links against shared libraries installed to \/usr\/local\/lib<\/code>, and without updating the library cache, the dynamic linker can’t find them. Run sudo ldconfig<\/code> and try starting guacd again.<\/p>\n\n\n\nWebSocket connection errors behind Nginx<\/h3>\n\n\n\n
Upgrade<\/code> and Connection<\/code> headers being passed through, the connection falls back to HTTP polling (which is slower) or fails entirely. Confirm your Nginx config includes these lines in the location block:<\/p>\n\n\n\nproxy_set_header Upgrade $http_upgrade;\nproxy_set_header Connection $http_connection;<\/code><\/pre>\n\n\n\nproxy_cookie_path \/guacamole\/ \/;<\/code> directive is equally important. Without it, session cookies won’t match the proxied path and you’ll be kicked back to the login page repeatedly. Reload Nginx after any configuration change with sudo systemctl reload nginx<\/code>.<\/p>\n\n\n\n