Guacamole is an HTML5 remote desktop gateway. Guacamole provides access to desktop environments using remote desktop protocols like VNC and RDP. A centralized server acts as a tunnel and proxy, allowing access to multiple desktops through a web browser.

No browser plugins are needed, and no client software needs to be installed. The client requires nothing more than a web browser supporting HTML5 and AJAX.

More information at the Guacamole homepage.

Components

There are two parts of which the Guacamole suite is made of; the native server components that should go on the system making the connections to the target machines and the client component (the web interface) that can reside on the same system of the server components or on a separate system.

The proxy required by the web application, guacd, is part of guacamole-server and built along with libguac and all protocol support by the guacamole-server package.

When a user connects to the Guacamole web application using their browser, they are served the JavaScript client for Guacamole.

Both guacamole-server and guacamole-client must be installed for Guacamole to work. No software needs to be installed on any client machine.

RHEL/CentOS and Fedora package status

All Guacamole components are already available in the main Fedora repositories and can be easily installed without any additional repository.

RHEL/CentOS needs the EPEL repository to be enabled and only contain the server components as the full Maven stack required to build the web application is not available in Fedora. For this reason, installing on RHEL/CentOS requires you to put the war package in the appropriate folder on the system.

Supported disitribution summary:

• Proxy daemon (CentOS/RHEL 6 and Fedora)
• SSH plugin (CentOS/RHEL 6 and Fedora)
• RDP plugin with sound and printing support (CentOS/RHEL 6 and Fedora)
• VNC plugin (CentOS/RHEL 6) with VNC repeater support (Fedora)
• Web application (CentOS/RHEL 6 from the upstream provided war file, Fedora from the repositories)

All supported desktop protocols can be installed all together or separate from each other. Examples below assume you want to install all Guacamole software (client & server) on the same system with all the protocols available.

Installing the server components

This applies to both Fedora and CentOS/RHEL. Launch the following commands to install the server components; this will pull in all server components:

yum -y install guacd libguac-client-*

Do not forget to enable the services. On Fedora:

systemctl enable guacd

On CentOS/RHEL:

chkconfig guacd on

Installing the client components (web application)

Fedora

In Fedora, launch the following commands to install the main Guacamole web application. This will pull in Tomcat and all the required Java dependencies:

yum -y install guacamole

Enable it at boot:

systemctl enable tomcat

And then configure it. In Fedora, all configuration files are stored in the /etc/guacamole/ path. Just edit those files following the explanation in the configuring Guacamole manual section.

CentOS/RHEL

Launch the following commands to install Tomcat. This will pull in all the required Java dependencies:

yum -y install tomcat6

Enable it at boot:

chkconfig tomcat6 on

Then you need to download the main Guacamole web application archive from the Guacamole homepage. Place the downloaded war file in /var/libt/tomcat6/webapps for Tomcat consumption.

mv guacamole-0.8.3.war /var/lib/tomcat6/webapps/guacamole.war

Then you need to find a place to put the configuration files according to the configuring Guacamole manual section. This can be time consuming and quite tricky until you get the configuration right; but after a while it’s very easy.

My personal preference would be to put the files guacamole.properties and user-mapping.xml in /etc/guacamole/ like in Fedora and make sure that the Tomcat service can find the files according to the manual. To do so; issue the following commands:

mkdir -p /etc/guacamole
echo "export GUACAMOLE_HOME=/etc/guacamole" > /etc/profile.d/guacamole.sh
echo "setenv GUACAMOLE_HOME /etc/guacamole" > /etc/profile.d/guacamole.csh
chcon system_u:object_r:bin_t:s0 /etc/profile.d/guacamole.*

Running Guacamole

Once all it’s configured, running it it’s pretty simple. First of all, start all the services.

In Fedora:

systemctl start guacd
systemctl start tomcat

In CentOS/RHEL:

service guacd start
service tomcat6 start

Then point your browser to the Tomcat deployed application. If you’ve not modified Tomcat default configuration the URL is:

http://localhost:8080/guacamole/

Try to login; if you get an “Invalid user” error just look at the Tomcat logs. From my experience it’s usually a configuration problem.