Guacamole is a web application:-

Guacamole is an HTML5 web application that provides access to desktop environments using remote desktop protocols (such as VNC or RDP). Guacamole is also the project that produces this web application, and provides an API that drives it. This API can be used to power other similar applications or services.

“Guacamole” is most commonly used to refer to the web application produced by the Guacamole project using their API. This web application is part of a stack that, overall, provides a protocol-agnostic remote desktop gateway. Written in JavaScript and using only HTML5 and other standards, the client part of Guacamole requires nothing more than a modern web browser or web-enabled device when accessing any of the desktops served.

guac-arch

Historically, Guacamole was an HTML5 VNC client, and before that, a JavaScript Telnet client called RealMint (“RealMint” is an anagram for “terminal”), but this is no longer the case. Guacamole’s architecture has grown to encompass remote desktop in general, and can be used as a gateway for any number of computers. Originally a proof-of-concept, Guacamole is now performant enough for daily use, and all Guacamole development is done over Guacamole.

Access your computers from anywhere

If you want to access one or more desktops from anywhere remotely, without having to install a client, particularly when installing a client is not possible, Guacamole is an excellent solution. By setting up a Guacamole server, you can provide access to any other computer on the network from virtually any other computer on the internet, anywhere in the world. Even mobile phones or tablets can be used, without having to install anything.

Another common reason is the presence of a corporate firewall at the workplace preventing SSH or other access to remote machines. Usually, such a firewall prevents access to anything other than HTTP or HTTPS, and corporate policies prohibit intentionally circumventing these restrictions (by changing port numbers, for example).

As a true web application whose communication is over HTTP or HTTPS only, Guacamole allows you to access your machines from anywhere without violating the policy of your workplace, and without requiring the installation of special clients.

Pre-built packages

By far, the easiest way to install Guacamole is through pre-built binary packages. Binary packages are provided with every Guacamole release for several Linux distributions, and there may be Guacamole packages available in the official repository of your distribution.

If your distribution provides Guacamole packages for you, this is the preferred method of installing Guacamole. Install your distribution’s Guacamole package, and then follow the common instructions here for configuring Guacamole once it is installed.

If your distribution does not provide Guacamole packages, or the packages provided are too old, you can try the packages built by the Guacamole project with every release. If the Guacamole project does not provide packages for your specific distribution, you will need to build everything yourself from source.

Important

Be aware that Guacamole is a remote desktop gateway, and cannot access your desktop’s display without a remote desktop server of some kind to connect to. Guacamole does not contain its own VNC or RDP server, and these installation procedures will not walk you through the installation of a VNC or RDP server.

Your distribution of choice will provide documentation for setting up VNC, as will the documentation provided by those that created the VNC server you wish to use. If you are going to use RDP to connect to Windows computers, Microsoft (and many others on the internet) provides documentation describing how to set up remote desktop.

Supported distribution versions

The Guacamole project supports all stable versions of Debian, Ubuntu, and Fedora which have not reached end-of-life. The only exception to this is when a particular version cannot be supported because the upstream repository is missing a critical dependency, in which case some or all of the packages built by the Guacamole project will not be available for that distribution.

Packages for all supported versions of Linux distributions are available from the Guacamole web site.

Installing dependencies

Different components of Guacamole depend on different packages provided by your distribution in order to function.

The Guacamole web application depends on a servlet container like Apache Tomcat. This guide assumes you are using Apache Tomcat as your servlet container, but others will work as well. You will need to consult the documentation of your chosen servlet container for any details regarding installation of web applications.

For Debian and Ubuntu, Apache Tomcat is provided by the tomcat6 package, while the VNC library required for VNC support is provided by libvncserver0, and RDP support is provided by libfreerdp1. Support for Ogg Vorbis encoding is provided by libvorbisenc2 which is used by libguac-client-rdp to provide sound to browsers supporting Ogg Vorbis audio.

 Configuring Guacamole

After installing Guacamole, it will be minimally configured to use the default authentication. You can modify this configuration if you need to use a different authentication module (such as the MySQL authentication, which is discussed in a separate chapter) or if you need to veer from the defaults.

Guacamole’s configuration consists of two main pieces: a directory referred to as GUACAMOLE_HOME, which is the primary search location for configuration files, and guacamole.properties, the main configuration file used by Guacamole and its extensions.

images

GUACAMOLE_HOME

As of release 0.8.0, Guacamole now reads files from its own configuration directory by default, resorting to the classpath only when this directory cannot be found. When locating this directory, Guacamole will try, in order:

  1. The directory specified within the system property guacamole.home.
  2. The directory specified within the environment variable GUACAMOLE_HOME.
  3. The directory .guacamole, located within the home directory of the user running the servlet container.

This directory will be referred to as GUACAMOLE_HOME elsewhere in the documentation.

Guacamole uses GUACAMOLE_HOME as the primary search location for configuration file like guacamole.properties.

MySQL authentication

Guacamole 0.8.0 introduced an officially-supported MySQL authentication module that allows users and connections to be managed from within the web application.

Unlike the default, XML-driven authentication module, all changes to users and connections take effect immediately; users need not logout and back in in order to see new connections.

Installing MySQL authentication

The MySQL authentication module is not included in the main Guacamole bundle nor is it enabled by default. You must use the download link provided in the downloads section of the main Guacamole site.

The downloaded .tar.gz file will contain several directories:

lib/

Contains all .jar files required for the MySQL authentication module to work, including the module itself. The MySQL JDBC connector is not included.

schema/

Contains all SQL scripts required to set up the MySQL database.

The contents of lib/ must be copied into the classpath of Guacamole, which is the directory specified by the lib-directory property in guacamole.properties. If this property is not specified, simply add it. On Linux servers, /var/lib/guacamole/classpath is a good choice, but it can be whatever you like.

In addition to the files from lib/, you must also copy .jar file from the MySQL “Connector-J” JDBC archive. The archive containing this .jar can be downloaded from MySQL’s website.

 

Using Guacamole

Logging in

When you visit a Guacamole instance for the first time, you will see the login screen. This screen authenticates you with Guacamole, allowing you to use Guacamole to interact with one or more remote desktops.

Enter your username and password and click “login”. You will then be given a list of available remote desktop connections to choose from. If you have used Guacamole in that specific web browser before, you will also see thumbnails of the screens of recently used connections.

Keep in mind this is the login for Guacamole, and not necessarily the login for the remote desktop you wish to connect to. The username and password you give Guacamole grants you access to the Guacamole system only. The usernames and passwords required for the remote desktops you have access to through Guacamole are independent.