Apache Guacamole [1] is billed as a clientless HTML5 web application that you can use to access your remote servers and desktops. It's called clientless, because Guacamole only requires a web browser unlike other remote desktop solutions that require a client to communicate with the server.

Although Guacamole only reached the 1.0 milestone (the latest version is 1.1) in 2019, the project has been in development for about a decade. Despite its low version number, the project has a mature code base, which is malleable enough to fit all kinds of deployments. You can use it in simple standalone local networks and also on enterprise networks where it can integrate with other existing resources to enhance security and user management.

Guacamole supports all the popular remote desktop protocols including VNC, RDP, SSH, and Telnet. The most recent addition to the list is a Kubernetes client that you can use to attach to the console inside a container. In addition to its protocol support, Guacamole has several enterprise integration capabilities, including LDAP authentication, Duo two-factor authentication (2FA), TOTP 2FA, CAS authentication, OpenID Connect authentication, HTTP header authentication, and more.

The Guacamole client/server architecture consists of a client-side layer implemented in HTML and JavaScript. This browser front-end client layer communicates with the Tomcat Java-based servlet container. The server layer is chiefly exposed as the guacd proxy daemon.

Get Guacamole

Installing Guacamole is an involved process. You must fetch various dependencies before you download and compile the latest version from source. The process is time-consuming but well-documented [2]. Alternatively, you can also install Guacamole via Docker. Again the project has clear step-by-step documentation [3] if you prefer to take this route.

But if all this sounds like too much work, you can also use a script that will fetch all the dependencies, configure all the components, and leave you with a working installation with minimal intervention on your part.

Ubuntu users can use the guac-install script [4] to get a working installation of Guacamole. If you have a CentOS 7 or a RHEL 7 installation, you can use the guacamole-install-rhel script [5].

Both scripts go about the task slightly differently. By default, the Ubuntu script will only prompt you for the database's password. It does however ship with several options that you can use to override the default behavior. For instance, the --totp switch will enable 2FA. You can also use the script to upgrade your installation whenever there is a new Guacamole version.

The RHEL/CentOS script is more verbose. It guides you through a few interactive menus that ask for information to help set up Guacamole as per your requirements. The most notable of these is the SSL certificate type menu that gives you the option to either install a Let's Encrypt certificate, a self-signed one, or none at all. If you don't install a certificate, Guacamole will operate over an unencrypted HTTP connection. You should only use this if you're using a certificate from another authority besides Let's Encrypt. Even for small networks, or even while evaluating Guacamole, I'd suggest you use the self-signed option instead of no encryption at all.

Irrespective of which script you choose, you will have a working Guacamole installation in no time. Again, my advice would be to test the scripts inside the safe confines of a virtual machine before deploying them on a physical server.

Regular Housekeeping

When the scripts have completed the installation, they'll both show you the URL for accessing the Guacamole interface. Usually it is either http://localhost:8080/guacamole or https://localhost:8443/guacamole. You can substitute localhost with the IP address of the machine on which you've run the script in order to access it from any other machine on the network.

This should bring up the login page. You can log in using the default credentials, which are guacadmin:guacadmin. You are now at the rather bland-looking dashboard since you haven't added any remote desktop connections yet.

Before doing that, the first order of business is to change the default password. To do so, click on the username in the top-right corner of the dashboard and select Settings from the drop-down menu. Next, jump to the Preferences tab and scroll down to the Change Password section to update the password.

While you are here, take some time to explore the other settings. Make sure Guacamole has the right time zone, for instance. Multilingual users can also use the Display language field to select another supported language, such as Dutch, Spanish, French, Italian, and more.

Once you are comfortable with Guacamole, you can return to the Settings screen and add more users from under the Users tab. Guacamole has useful permission settings (Figure 1) that you can access from this interface. You can give users the ability to become full administrators or restrict their administrative abilities. For instance, regular non-administrative users can only access the remote machines for which you've granted permission. But you can give them some administrative powers, such as the ability to add new users or create new connections.

Figure 1: Unless explicitly allowed, users won't be able to change their own passwords by default.

Make Connections

Now you are all set to create a new remote desktop connection. Log into the Guacamole dashboard and head to Settings | Connections and click the New Connection button. This opens the Edit Connection page where you can enter various details to describe your connection (Figure 2). Remember that not all options are necessary to establish a connection. You can begin with the least number of details and then fine-tune the connection as per your requirements, once it has been established.

Figure 2: Images transmitted to Guacamole over VNC are always encoded losslessly as PNG images.

Also note that the requested parameters change depending on the protocol you use for connecting to the remote desktop. Begin by adding a VNC connection to a remote Linux machine on the network. First make sure there's a VNC server running on the remote machine (see the box "Set Up TightVNC Server").

sudo apt install tightvncserver

sudo dnf install tightvncserver

sudo apt install xfce4 xfce4-goodies

sudo dnf install xfce4 xfce4-goodies

$ nano ~/.vnc/xstartup
#!/bin/bash
xrdb $HOME/.Xresources
startxfce4 &

$ sudo chmod +x ~/.vnc/xstartup

$ vncserver
New 'X' desktop is dholak:1
Starting applications specified in /home/bodhi/.vnc/xstartup
Log file is /home/bodhi/.vnc/dholak:1.log

Start by adding a name for the connection, such as Ubuntu 18.10 Desktop. Leave the Location as ROOT and select VNC from the Protocol drop-down menu. You can then skip over the next few sections for the time being and jump straight to the Parameters section. Here, enter the hostname or the IP address of the remote machine you wish to access, along with the port number. For a VNC connection, the port number is 5900 plus the display the session is running on. So if your VNC server is running on :1, enter 5901 in the Port parameter. Finally, enter the password for accessing the VNC session that you specified while setting up TightVNC Server, in the Authentication field.

That's all there is to it. Scroll down to the bottom of the page and click the Save button. The newly added connection will now be listed on the dashboard. Double-click on the connection to remotely access the Xfce desktop on the Ubuntu installation.