Jan 192013

This is a new and interesting project that could be really useful both for companies that for private users, Guacamole is an HTML5 remote desktop gateway that 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.

Be aware that Guacamole is only 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, it’s a java based program so it’s distributed as a .war package.

The client requires nothing more than a web browser supporting HTML5 and AJAX.

Why Guacamole ?

1) To provide an easy access to a group

Guacamole allows you to centralize access to a large group of machines, and specify on a per-user basis which machines are accessible. Rather than remember a list of machines and credentials, users need only to log into a central server and click on one of the connections listed.

If you have multiple computers which you would like to access remotely, or you are part of a group where each person has a set of machines that they need remote access to, Guacamole is a good way to provide that access while also ensuring that access is available from anywhere.

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

You could have a firewall or network that prevent a direct access from the net to some of your machines, as a true web application whose communication is over HTTP or HTTPS only, Guacamole allows you to access your machines from anywhere.

3) Adding HTML5 remote access to your existing infrastructure

Maybe you already have a web infrastructure with a single sign-on for your users, to access their webmail or other resources, and you have also some VNC server and remote desktop that you’d like to “publish” on the net for these users, Guacamole is the perfect solution that integrates an HTML5 remote desktop gateway for managing your computers.



Pre-built bundles of packages and installation instructions are available for Debian, Ubuntu, and Fedora. On Ubuntu 12.10, Mint 14 and Debian on the repository it’s present the version 0.6 that you can easily install with the command:

sudo apt-get install guacamole
Reading package lists... Done
Building dependency tree       
Reading state information... Done
The following extra packages will be installed:
  guacd libguac-client-vnc0 libguac3 vnc4server xbase-clients
Suggested packages:
  tomcat6 jetty vnc-java
The following NEW packages will be installed:
  guacamole guacd libguac-client-vnc0 libguac3 vnc4server xbase-clients
0 upgraded, 6 newly installed, 0 to remove and 0 not upgraded.
Need to get 2,464 kB of archives.
After this operation, 6,140 kB of additional disk space will be used.

If you prefer a newer version you can install the requisites by hand with the command:

sudo apt-get install tomcat6 libvncserver0 libfreerdp1

Download the latest version for Ubuntu (this is the 64 Bit version) and install the packages with the following commands:

$ tar -zxvf guacamole-0.7.1-ubuntu-12.04-amd64.tar.gz
$ cd guacamole-0.7.1-ubuntu-12.04-amd64/
$ ls
guacamole_0.7.0-1_all.deb         guacd_0.7.0-2_amd64.deb     libguac-client-rdp0_0.7.1-1_amd64.deb  libguac-dev_0.7.0-1_amd64.deb
guacamole-tomcat_0.7.0-1_all.deb  libguac4_0.7.0-1_amd64.deb  libguac-client-vnc0_0.7.0-1_amd64.deb
$ sudo dpkg -i *.deb

Configuration of Guacamole

The Guacamole web application uses one main configuration file called guacamole.properties which must be in the classpath of your servlet container. This file is the common location for all configuration properties read by Guacamole or any extension of Guacamole, including authentication providers.

In Ubuntu this file is located in /etc/guacamole/guacamole.properties, and this is a minimal example:

# Hostname and port of guacamole proxy
guacd-hostname: localhost
guacd-port:     4822
# Location to read extra .jar's from
lib-directory:  /var/lib/guacamole/classpath
# Authentication provider class
auth-provider: net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider
# Properties used by BasicFileAuthenticationProvider
basic-user-mapping: /etc/guacamole/user-mapping.xml

Authentication of users and mapping to Remote Desktop

Guacamole’s authentication model is simple and consists of a mapping of usernames to configurations.
Each username has a corresponding password and associated set of configurations, and each configuration has a protocol and protocol-specific set of parameters, this configuration is done in the file user-mapping.xml, in Ubuntu this file is located in /etc/guacamole/user-mapping.xml

Here is a sample configuration with parameters for VNC connections:

<user -mapping>
    <!-- Per-user authentication and config information -->
    <authorize username="USERNAME" password="PASSWORD">
        <param name="hostname"/>localhost
        <param name="port"/>5900
        <param name="password"/>VNCPASS
    <!-- Another user, but using md5 to hash the password
         (example below uses the md5 hash of "PASSWORD") -->
    <authorize username="USERNAME2"
        <!-- First authorized connection -->
		<connection name="localhost">
            <param name="hostname"/>localhost
            <param name="port"/>5901
            <param name="password"/>VNCPASS
        <!-- Second authorized connection -->
   		<connection name="otherhost">
            <param name="hostname"/>otherhost
            <param name="port"/>5900
            <param name="password"/>VNCPASS


After editing the file you should be able to use your Guacamole server, just restart your tomcat and use a browser to open the url http://yourIPaddress:8080 this should show a login page, and once you have logged in you should be able to choose which remote server you want to use clicking on its name, and if everything is correct you’ll find your remote desktop into your browser.

Popular Posts:

Flattr this!

  3 Responses to “A taste of Guacamole on Linux”

  1. Very nice review you posted here Ricardo.

    Just like to note that Guacamole is working on an SSH proxy / HTML 5 based SSH client combination too.
    It’s kept out of the version 0.7.1 because of some issues and because the RDP / VNC combination was ready.

    I’ve been able to connect to my Windows 2003 machine without issues using Firefox, Safari and Google Chrome.
    Somehow IE9 however tends to give issues not displaying correctly.

    Connecting to my iPAD was working fine too. (Enable the mouse cursor when using Veency)

    Connecting to my Windows 8 machine failed though…
    Looking at the logs this might be due to the FreeRDP lib not supporting the proper security level.


    Eric aka Genotix

  2. Ciao! Il programma in oggetto lo conosco bene e funziona su Tomcat.

    Sto provando a configurarlo su Jetty ma ho problemi.

    Saresti in grado di scrivere una guida per installarlo e configurarlo con Jetty invece che tomcat?

 Leave a Reply

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>