Guacamole on Fedora and CentOS/RHEL 6

slaanesh Fedora, Guacamole, How to

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.

26 thoughts to “Guacamole on Fedora and CentOS/RHEL 6”

  1. I had to add a few steps in order to get this to work on my RHEL6 server…

    1 – yum install tomcat6-webapps (not sure if this is required, but it helped me when debugging…)
    2 – http://server-address:8080/guacamole-0.8.3/ (unless I missed the creation of a symbolic link above, I had to append the version string to the URL…)
    3 – Install, then edit the required configuration files…
    3a – wget https://github.com/glyptodon/guacamole-client/blob/master/guacamole/doc/example/guacamole.properties -O /etc/guacamole/guacamole.properties
    3b – wget https://github.com/glyptodon/guacamole-client/blob/master/guacamole/doc/example/user-mapping.xml -O /etc/guacamole/user-mapping.xml

    Much thanks to Simone!

    Reply

    1. Hello, a couple of points regarding your additional steps.

      2 – is required if you just park the war without unpacking or renaming it as depicted in this guide. I would suggest renaming it as described here otherwise the url would change between each update.
      3a and 3b are required, I summarized those by pointing people to the Guacamole manual. By downloading those, you’re actually downloading template configuration files from the yet to be released Guacamole 0.9.1. Fortunately they have not changed between releases, but my suggestion is to read the manual and create files compatible with the version you are using.

      In Fedora, configuration files are already installed and the web application has a fixed name.

      Regards,
      –Simone

      Reply

      2. This would be great, specially because with 0.8.3 it’s not possible to access windows 7 / 2008 via RDP due to protocol changes (seems FreeRDP 1.0.2 has already support)

        Reply

        1. Hello, here I am using 0.8.3 on CentOS and Fedora 20 and both are able to connect fine to Windows 2008 systems.

          Guacamole 0.9.0 has now been built on Fedora 21; there are many things in 0.9.0 that will be fixed in 0.9.1; so I’m waiting on that for the other branches.

          Reply

          1. It looks like 0.9.1 is out. Are you planning on packing the 0.9.1 release for CentOS?

  3. The error in log is

    Dec 13, 2013 3:29:21 p.m. org.apache.catalina.core.StandardWrapperValve invoke
    SEVERE: Allocate exception for servlet Connections
    java.io.IOException: guacamole.properties not loaded from /etc/guacamole (not a directory), and guacamole.properties could not be found as a resource in the classpath.
    at org.glyptodon.guacamole.properties.GuacamoleProperties.(GuacamoleProperties.java:126)
    […]
    Dec 13, 2013 3:29:28 p.m. org.apache.catalina.core.StandardWrapperValve invoke
    SEVERE: Allocate exception for servlet Login
    java.io.IOException: guacamole.properties not loaded from /etc/guacamole (not a directory), and guacamole.properties could not be found as a resource in the classpath.
    at org.glyptodon.guacamole.properties.GuacamoleProperties.(GuacamoleProperties.java:126)
    […]

    Reply

  4. I created a new VPS and followed the steps exactly and configured Guacamole as given in http://guac-dev.org/doc/gug/configuring-guacamole.html by creating files in /etc/guacamole

    But I am getting invalid login error – kindly guide

    Steps done..

    yum -y install guacd libguac-client-*
chkconfig guacd on

yum -y install tomcat6
chkconfig tomcat6 on

wget -q http://garr.dl.sourceforge.net/project/guacamole/current/binary/guacamole-0.8.3.war

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

    Create and put the files guacamole.properties and user-mapping.xml in /etc/guacamole/

    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.*

service guacd start
service tomcat6 start
    Reply

    1. The error “invalid login” is thrown out on the interface every time the configuration is not right.

      Regarding the last part of your setup, the chcon stuff is not present in my guide, permissions are inherited from default contexts when new files are created; so the chcon command is redundant. You can check that files in /etc/guacamole have the same permissions/context as in the rpms:

      # ls -alZ /etc/guacamole/
drwxr-xr-x. root root unconfined_u:object_r:etc_t:s0   .
drwxr-xr-x. root root system_u:object_r:etc_t:s0       ..
-rw-r--r--. root root unconfined_u:object_r:etc_t:s0   guacamole.properties
-rw-r--r--. root root unconfined_u:object_r:etc_t:s0   user-mapping.xml
-rw-r--r--. root root unconfined_u:object_r:etc_t:s0   user-mapping.xml.old
# ls -alZ /etc/profile.d/guacamole.*
-rw-r--r--. root root system_u:object_r:bin_t:s0       /etc/profile.d/guacamole.csh
-rw-r--r--. root root system_u:object_r:bin_t:s0       /etc/profile.d/guacamole.sh

      The best place you can look for the correct content of the configuration files is Google.

      Reply

  5. Followed instructions to install guacamole as in https://www.weblab360.com/User:xltran/App/Guacamole/Installation/CentOS_6.4 and http://guac-dev.org/doc/gug/installing-guacamole.html

    but getting errors like this..

    guacamole.properties has this
    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

    User mapping has this

    ssh vnc
    localhost
    localhost
    22

    catalina.out has this

    Dec 25, 2013 2:52:23 p.m. org.apache.jk.common.MsgAjp processHeader
    SEVERE: BAD packet signature 18245
    Dec 25, 2013 2:52:23 p.m. org.apache.jk.common.ChannelSocket processConnection
    SEVERE: Error, processing connection
    java.lang.IndexOutOfBoundsException
    at java.io.BufferedInputStream.read(libgcj.so.10)
    […]

    catalina.log has this

    […]
    Dec 13, 2013 6:15:23 a.m. org.apache.catalina.startup.TldConfig lifecycleEvent
    SEVERE: Error processing TLD files for context path /guacamole
    java.lang.IllegalArgumentException: URI “file:./” is not hierarchical
    at java.io.File.(libgcj.so.10)
    […]

    Reply

    1. Your installation is screwed up, please clear your environment and start again with the web application following my post. Also use the default paths for the web application unless you want to adjust your SELinux policies.

      Reply

    2. Hello ! I have the same exact issue!! If you could help me by posting what you did after that would AWESOME ! 🙂

      Reply

      1. replying to myself: yum install java-1.6.0 !!

        then I’m having an issue about the login: I can’t pass the registration
        “SEVERE: Allocate exception for servlet Login
        org.glyptodon.guacamole.GuacamoleException: /var/lib/guacamole/classpath is not a directory.” are in the log
        but I do have nothing in /var/lib/guacamole/classpath and in your guide I don’t see where it could come… Could you check what’s in yours ?

        Reply

        1. okay If I could edit my comment… just comment in the options
          # Location to read extra .jar’s from
          #lib-directory: /var/lib/guacamole/classpath
          thx for them for providing such a stupid example config…

          now struggling with “Connection Error”

          Reply

          1. As in the previous reply that’s wrong, please check all your configuration. The default upstream provided configuration is perfect and works fine.

        2. Hello, you’ve made some mistake in the installation. Please start again and following the guide. /var/lib/guacamole/classpath is not a valid directory where Tomcat searches for apps; where did you get that from?

          Have you done this step?

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

          Reply

    3. Try to install java 1.6, and edit /etc/tomcat6/tomcat6.conf.
      set JAVA_HOME for the java 1.6 folder.

      /usr/lib/jvm/java-1.6.0-openjdk-1.6.0.0.x86_64/

      Reply

      1. This could happen only if you are trying to use a Java runtime which is different than your system default one.

        Reply

    1. Never tried, but I think you can simply move the folder of the deployed app from guacamole to desktop. I’m usually working on it locally for testing or accessing it through a web proxy (Apache).

      Reply

Leave a Reply