Holy Guacamole!

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.

Window to Windows

You can create other connections by selecting different protocols such as RDP.

Again, head back to Settings | Connections and click the New Connection button. Here, give your connection a name and select RDP from the Protocol pull-down. Scroll down to the Parameters section and enter the hostname or the IP address of the Windows machine you wish to access and enter 3389 in the Port field. And just like before, enter the authentication information for the Windows user you wish to remotely access.

You can now save the details and try connecting to the Windows machine. Depending on the version of Windows you want to access, you might have to take additional steps. First up, in any case, you'll have to enable Remote Desktop Sharing in Windows. For this, switch to the Windows machine and head to Control Panel | System and Security and select the Allow remote access option under the System section. You'll be taken to the Remote tab in the System Properties window, where you need to toggle the Allow remote connections to this computer option.

In Windows 10, the option for only allowing connections from PCs running Remote Desktop with Network Level Authentication is also enabled by default. Make sure you disable this option; otherwise, you'll not be able to connect to your Windows machine from Linux.

Furthermore, to access a Windows 10 machine, I had to toggle the Ignore server certificate option under the Authentication section in the Guacamole settings (Figure 3).

Figure 3: By default, Guacamole selects a security mode as part of the negotiation process.

Remote Control

As mentioned earlier, all configured connections are listed in Guacamole's dashboard, along with icons of the most recently accessed ones (Figure 4).

Figure 4: In addition to a screenshot, you can view the number of users connected to each remote desktop session from the desktop.

You can double-click a listed connection to launch a remote desktop session. Guacamole includes a hidden onscreen menu that you can bring up with the Ctrl+Alt+Shift key combination (Figure 5). If you are accessing Guacamole from a mobile device, you can bring up the menu by swiping from the left edge of the screen. The menu offers several features such as an on-screen keyboard, clipboard management, screen zoom control, and more.

Figure 5: You can use the onscreen keyboard to pass certain key combinations (such as Alt+Tab) to the remote desktop.

Click your username in this menu to bring up more options. The Disconnect option will terminate the session, the Home option will take you to the Guacamole dashboard, and the Settings option will take you to the dashboard's Settings window.

The Active Sessions tab in the Settings window lists all sessions that you have exited without first disconnecting them. The sessions are listed in a sortable table along with various details such as the username, the duration of the active session, and more (Figure 6). You can terminate an active session by selecting its corresponding checkbox. After you've selected the sessions you wish to terminate, click the Kill Sessions button to disconnect them.

Figure 6: While Active Sessions lists all ongoing sessions, switch to the History tab to view a list of recently used sessions.

Sharing Is Caring

While Guacamole offers several options to tweak your remote desktop connections, one of the most essential is file sharing. You can easily transfer files back and forth between your local computer and the remote desktop. Currently, Guacamole supports file transfer for VNC, RDP, and SSH, using either the protocol's native file transfer support or SFTP.

To enable file transfer, bring up the Settings page for one of your remote connections. Scroll down to the SFTP section and toggle the Enable SFTP button (Figure 7). Enter the remote machine's hostname and 22 as the port since you are connecting using the SSH protocol. Finally, enter the authentication information and click the Save button to activate the settings.

Figure 7: You can provide the optional SFTP Host key for Guacamole to verify the SFTP server's identity before transferring files.

You'll now be able to transfer files to the remote machine. You can either drag and drop them inside the browser window or use the file browser located in the Guacamole menu (Figure 8). Navigate the filesystem and then use the Upload Files button to select the file you wish to upload to the remote machine.

Figure 8: A notification dialog tracks the status of all uploads, while the browser's download notification system tracks downloads.

Once you have configured and accessed a remote connection, you can explore the various other parameters to tweak the connection per your requirements. Guacamole offers extensive options, and you can refer to its official documentation [6] for more information.

The Author

Mayank Sharma is a technology writer. You can read his scribblings in various geeky magazines on both sides of the pond.