Guacamole Introduction

Apache Guacamole is a clientless remote access gateway. At CyVerse, we use it to provide web-based VNC and SSH connections to user instances.


The Guacamole setup at CyVerse consists of a few components:

  1. Tomcat7 Java web-servlet to run the webapp (Within the webapp, there is an authentication plugin and a theming plugin)

  2. Nginx reverse proxy with SSL

  3. guacd is the daemon that handles Guacamole operations


CyVerse's Guacamole deployment for Atmosphere uses the guacamole-auth-hmac plugin. Additional information about how this plugin works and how it is built, see the project's README.

Relationship with Atmosphere

Additional documentation is provided in the repositories mentioned above.


Relevant Troposphere code can be found here: - JavaScript UI - Django Python API

The Django Python API part will just make a request to the Atmosphere backend and redirect to the Web Desktop page.


Relevant Atmosphere code can be found here

In this file, the guacamole_token function is the most important since it uses the HMAC method to create and verify a signature and generate the URL for the instance's connection. The fields used here allow us to configure specific connection parameters.


Relevant Atmosphere-Ansible can be found here: - Playbook for VNC - Tasks for Guacamole VNC - This task will configure the Guacamole-specific settings for the VNC Server - These settings specify that this instance of the server can only be access from the Guacamole server's IP address - Runs on port 5905 - Playbook for SSH/WebShell - Role for SSH/WebShell - Since Guacamole will need a keypair to connect the the instance's SSH server, atmosphere-ansible will connect to the Guacamole server and create a keypair (if it does not exist) and save it on the server - The public key is added to the instance's authorized_keys - The HMAC auth plugin will then read from the filesystem on the Guacamole server to find the private key necessary for SSH access when initiating a connection # Guacamole Installation at CyVerse

This guide will help you to understand and re-create the installation of Apache Guacamole at CyVerse. See Apache's official install guide and configuration guide.

Things to know

Guacamole webapp is located at /var/lib/tomcat7/webapps/guacamole.war.

Guacamole configuration files are located in /usr/share/tomcat7/.guacamole which is linked to /etc/guacamole. Extensions (hmac auth, CyVerse theme), are located in the subdirectory extensions.

Guacamole is proxied through Nginx with the config file in /etc/nginx/sites-available/nginx-guacamole.conf.

Create the cyverse-theme.jar file by zipping the extensions contents, not the directory: zip -r theme.jar *. For Jetstream, checkout the 'jetstream' branch and create the jar.

guacd logs can be found in /var/log/syslog

tomcat logs can be found at /var/log/tomcat7/catalina.out. Some additional logging may be at /var/log/tomcat7/localhost.out


  1. Follow the official documentation to setup Guacamole webapp and guacd daemon. Use the default /usr/share/tomcat7/.guacamole GUACAMOLE_HOME linked to /etc/guacamole/

  2. Get the guacamole-auth-hmac jar file by either downloading from the releases page or building from source and put it in /etc/guacamole/extensions/

  3. Get the guac-cyverse-theme jar file by either downloading from the releases page or building from source and put it in /etc/guacamole/extensions/

  4. Create /etc/guacamole/keys directory and make sure it is owned by the system's tomcat user

  5. Make sure /etc/guacamole/ looks something like this: guacd-hostname: localhost guacd-port: 4822 guacd-ssl: False secret-key: <secret_from_atmosphere_secrets> timestamp-age-limit: 600000 use-local-privkey: True key-directory: /etc/guacamole/keys/

  6. Configure Nginx: ``` ## location: /etc/nginx/sites-available ## link to sites-enabled: ln -s /etc/nginx/sites-enabled/nginx-guacamole /etc/nginx/sites-available/nginx-guacamole

    server { listen 80; return 301 https://$host$request_uri; }

    server { listen 443;

    root /var/lib/tomcat7/webapps/guacamole;

    server_name {{ SERVER_ADDRESS }};

    ssl_certificate /{{ SSL_DIRECTORY }}/fullchain.pem; ssl_certificate_key /{{ SSL_DIRECTORY }}/privkey.pem;

    ssl on; ssl_session_cache builtin:1000 shared:SSL:10m; ssl_protocols TLSv1 TLSv1.1 TLSv1.2; ssl_ciphers HIGH:!aNULL:!eNULL:!EXPORT:!CAMELLIA:!DES:!MD5:!PSK:!RC4; ssl_prefer_server_ciphers on;

    location / { proxy_pass http://localhost:8080/guacamole/; proxy_buffering off; proxy_http_version 1.1; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $http_connection; access_log off; } } ```

  7. Restart services systemctl restart tomcat7 systemctl restart guacd systemctl restart nginx

  8. In order to connect with Atmosphere, make sure to fill out the following variables in atmosphere-docker-secrets:
    • inis/atmosphere.ini: ini GUACAMOLE_ENABLED = True GUACAMOLE_SECRET_KEY = "big-secret" GUACAMOLE_SERVER_URL = ""
    • inis/troposphere.ini: ini GUACAMOLE_ENABLED = True
    • atmosphere-ansible/hosts: guac_server ansible_host=<ip_or_domain> ansible_port=<port>
    • atmosphere-ansible/group_vars/all: yaml SETUP_GUACAMOLE: true GUACAMOLE_SERVER_IP: <ip_address>


Additional information can be gathered from this ansible repository:

However, it may not be completely up-to-date

Notes for future Docker setup

As mentioned above, there is an ansible role and playbook for setting up the server, but this is pretty out-of-date and the preferred method for future deployments should be using docker-compose. An example of this can be found in the atmosphere-docker repository: - docker-compose file - directory with additional files/configurations

Basically, this will consist of two containers: guacd and guacamole webapp. Depending on setup, there could also be an Nginx container or non-containerized Nginx with this configuration.

The guacamole webapp container will need a volume mount to give it access to a file and an extensions directory containing JAR files for the theme and auth plugins. This volume or a separate volume should mount the user SSH keys (to the path specified in

Instructions for creating the JAR files can be found in the READMEs of each plugin repository.

Troubleshooting Guacamole

These are a few common problems we see with Guacamole on Atmosphere. See Apache Guacamole's troubleshooting guide for additional troubleshooting help.

Assisting Users

Tips for troubleshooting problems that users experience.

Problem: "Connection Error - closed the connection" when attempting a connection.

The user was successfully authenticated by the Guacamole server, but the Guacamole server could not connect to the instance. Therefore, this is most likely a problem with the instance, not the server.


If it is a VNC connection, the instance's VNC server is messed up. To fix it:

# Kill the Guacamole-specific VNC server
# If you get an error, that means the server is already killed
vncserver -kill :5

# Restart the VNC server
vncserver -config ~/.vnc/config.guac :5

Server-side Troubleshooting

Tips for troubleshooting issues on the Guacamole server.

Problem: "Unable to bind socket to any addresses." error from guacd

This error may appear in the syslog when trying to restart the guacd process. This error occurs when you try to start guacd while it is already running.


Manually kill the guacd process.

pkill -f guacd