RDP VNC to HTML5 proxy: Guacamole

Apache Guacamole is a clientless remote desktop gateway. It supports standard protocols like VNC, RDP, and SSH and runs very easily in containers. We call it clientless because no plugins or client software are required. Thanks to HTML5, once Guacamole is installed on a server, all you need to access your desktops is a web browser. All traffic, be it RDP, VNC or the other implemented protocols are all streamed over the single tcp port out of Guacamole.

Guacamole provides a web portal, after you authenticate it lists the connections that are possible. Connections are previously configured by the Guac-admin or someone with the proper authorization. A single click on the connection item will open a new webpage where the screen output of the session is waiting on your mouse and keyboard input. You are connected to the target via SSH, RDP or VNC over HTML5.

To connect to a new target you need admin authorization, configure the connection in the admin section, then make it possible for you or other users to consume that connection. It does not allow simpler, ‘on the fly’ connections where you just put some ip in a field and click on connect.

Use-cases are easy to dream up, easy on click access to:

• Testlab
  • As a technician i have a lot of systems scattered on various networks. I want a uniform way to access them via a proxy/webbrowser, regardless of where my workstation lives.
  • As a technician, I want to access a lot of unimportant systems by seeing the hostnames in a list in a webbrowser and access them by clicking on an item.
  • As a technician I don’t want to keep track of all the separate login details of a lof unimportant systems, I just want to click on the hostname in a webbrowser, see the screen and be authenticated.
• Early phases of PoC’s and pilots
  • As a PoC/Pilot technician, I want to keep track of everything the team has built and want to have quick access to building blocks via a webbrowser based on hostnames in a list.
  • If something is wrong I want to access my PoC systems quickly without looking up IP and Authentication information in a sheet.
• Demo
  • As a presenter, I want to show relevant systems in a websession, elegantly and limit my presentation/demo steps to what is important.
  • As a presenter of a technical demo, i want all my demo systems listed in a list where i can click and access them instantly via a webbrowser.
• Generally, act as Jump server
  • As a system administrator or SRE i have a relatively static list of systems I use a lot. I want them in a list with easy access to them from any web (HTML5) capable device. A list I can share with colleagues to there is no doubt on how to access them.
  • As a IT manager I want to control who access systems easily and prescribe how they are accessed, regardless if it is employee, contractor or intern.
  • As a manager of IT I want all the sessions to be logged and maybe even recorded so I can audit actions and help with post mortem analysis to learn from past actions and have the team improve

Containerized deployment

Guacamole comes as two daemons and it needs a database service. So you need to start three things. In this article, we use the container method to deploy. These containers need to run on a container-able system like RHEL with docker or better yet, podman. This article shows the steps from a freshly installed, RHEL8 system registered to BaseOS and APPstream repos.
I have also tested this on an Intel Celeron equipped Synology NAS, works great!

There are other articles that explain how to deploy Guacamole on a Linux machine, compiling and deploying code directly to the OS. That article can also be used to create a Guacamole image from a Universal Base image or another OS.
https://www.howtoforge.com/install-and-use-guacamole-remote-desktop-on-centos-8/

Start the MariaDB container

The MariaDB is used to store Guacamole application data such as users, connections and their settings. Guacamole also provides some level of audit capabilities, such as seeing which user used which connection.

podman run --name some-mariadb -e MYSQL_ROOT_PASSWORD=my-secret-pw -e MYSQL_DATABASE=guac_db -e MYSQL_USER=guac_dbuser -e MYSQL_PASSWORD=gvbvd52d -d -p 3306:3306 -d mariadb:10.5.8

Populate the guac_db tables 

Guacamole comes with a sql script that creates all the tables and some initial content such as the guac-admin user with a default password. First, we extract the database script then we transfer it. There are several ways to apply this script, the most fault-tolerant way I found is to copy the file into the MariaDB container. Then run a command to apply it.

podman run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --mysql > initdb.sql

podman cp /root/initdb.sql some-mariadb:/root

podman exec -i some-mariadb sh -c 'exec mysql -uguac_dbuser -p"gvbvd52d" guac_db < /root/initdb.sql'

Start the Guacamole backend service container

The backend container runs the guacd process and is available on TCP port 4822. The front-end service will connect on this port requesting it to start VNC, RDP and SSH sessions and forward the session back to the frontend. It’s ephemeral in its nature, it does not use the database or local storage to store ‘state’.

podman run --name some-guacd -d -p 4822:4822 -e GUACD_LOG_LEVEL=debug --rm guacamole/guacd

Start the front-end service

In this step, we start the Guacamole service which connects to the database and opens up a web portal on port 8080. It needs to connect to guacd and the database services. Change the information where appropriate for you, let’s say IP addresses etc.

podman run --name some-guacamole -e GUACD_HOSTNAME=192.168.178.119 -e GUACD_PORT=4822  -e MYSQL_HOSTNAME=192.168.178.119 -e GUACD_LOG_LEVEL=debug -e MYSQL_DATABASE=guac_db -e MYSQL_USER=guac_dbuser -e MYSQL_PASSWORD=gvbvd52d -d --rm -p 8080:8080 guacamole/guacamole

Checking if this works correctly can be done in two ways, see with a web browser if this all shows up as the following login screen

If you see only labels instead of the proper names see the note below. You may experience inter container connectivity problems. It may still work though…

Note: Communication between containers may not work on fresh RHEL8 systems. Easy fix by loading a kernel module (br_netfilter) see https://bugzilla.redhat.com/show_bug.cgi?id=1703261

Adding connections and testing

The next step is to configure some connections. This article will show three connections SSH, VNC and RDP. After login you will find yourself of the ‘home’ page where Guacamole lists available connections, click on your username in the upper right corner. Then select settings. Open the connections tab.

Adding a SSH connection

• Click on “New connection”
• Add the following information, at a minimum
  • Name:
  • Protocol: select the SSH protocol
  • Parameters – Network – Hostname:
  • Parameters – Network – Port: 22

Other parameters can be set like username and password, connection certificates and passphrases. Pre-setting authentication means that the session will log you in to the target and the password will not be shown to the person activating the connection. Session recording and other facilities are also available, a lot is possible.

Test the connection by clicking on the upper right corner username, then select home. See click on the connection.

Adding a VNC connection

• Click on “New connection”
• Add the following information, at a minimum
  • Name:
  • Protocol: select the VNC protocol
  • Parameters – Network – Hostname:
  • Parameters – Network – Port:

Adding a RDP connection

• Click on “New connection”
• Add the following information, at a minimum
  • Name:
  • Protocol: select the RDP protocol
  • Parameters – Network – Hostname:
  • Parameters – Network – Port: 3389
  • Parameters – Authentication – Username:
  • Parameters – Authentication – Password:
  • Parameters – Authentication – Security mode: Select “NLA”

There is a authentication dialog process in Guacamole for some reason it does not allow this for new connections. Could have to do with certificated or other matters, first use a username and password in new connections. Test it, then it will allow the password and even the username to be blank in the connection settings to offer the user activating the connection the authentication dialog.