Client-free remote desktop

Holy Guacamole!

© Photo by Rafael Arizaga on Unsplash

© Photo by Rafael Arizaga on Unsplash

Article from Issue 237/2020

Use Apache Guacamole to connect to remote servers from within a web browser.

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").

Set Up TightVNC Server

There are several VNC servers, but I prefer using the cross-platform open source TightVNC Server that is available in the official repositories of the mainstream distributions. You can install it on Ubuntu with:

sudo apt install tightvncserver

On Fedora, use:

sudo dnf install tightvncserver

Then run vncserver to set it up. You'll be prompted to enter and verify a password to access your machine remotely. You'll also have the option to create a view-only password. The process then creates the necessary configuration files and connection information for the server.

Next, install the lightweight Xfce 4 desktop environment, which is what I prefer to use to power my remote desktop connection. On Ubuntu, do this with:

sudo apt install xfce4 xfce4-goodies

On Fedora, install Xfce 4 with:

sudo dnf install xfce4 xfce4-goodies

Now you need to tell your VNC server to bring up the Xfce 4 desktop whenever it detects an incoming connection request. For this, you need to edit the ~/.vnc/xstartup file:

$ nano ~/.vnc/xstartup
xrdb $HOME/.Xresources
startxfce4 &

The commands in the file first ask the VNC server to read the user's .Xresources file, which is where users specify changes to certain graphical desktop settings, such as terminal colors. The VNC server will then launch the Xfce 4 desktop.

Then make the file executable to ensure that the VNC server will be able to use this new startup file properly:

$ sudo chmod +x ~/.vnc/xstartup

Finally, restart the VNC server.

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

The server is now all set to answer VNC connection requests.

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.

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy Linux Magazine

Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

comments powered by Disqus
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters

Support Our Work

Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.

Learn More