Apache Guacamole 0.9.10-incubating

Apache Guacamole is split into two subprojects: "guacamole-client", the HTML5 web application which serves the Guacamole client to users, and "guacamole-server", the remote desktop proxy which the web application communicates with. The source code for each of these may be downloaded below.

If you do not wish to build Apache Guacamole entirely from source, pre-built versions of the web application (.war) and all extensions are provided here in binary form for convenience. Please note that guacamole-server must still be built and installed from source.

Release notes

The 0.9.10-incubating release is Apache Guacamole’s first release under the Apache Incubator. It features support for both screen sharing and recording, improved file transfer behavior, and support for LDAP within the Docker images. Local clipboard integration has also been added (for those browsers which support it), as well as audio input for RDP, theming/branding via extensions, and several other improvements.

This release contains changes which break compatibility with past releases. Please see the deprecation / compatibility notes section for more information.

We’re incubating!

The Guacamole project has been accepted into the Apache Incubator, and is thus now Apache Guacamole (incubating). Beyond simply moving the website, this necessitated a number of changes, including switching to the Apache License and migrating Guacamole’s Java API and Maven artifacts from org.glyptodon.guacamole to org.apache.guacamole. If you are simply using the Guacamole web application as-is, the transition should be fairly seamless, but downstream users of the APIs will need to update their source to make use of this release.

  • GUACAMOLE-1 - Update source licenses and LICENSE / NOTICE / DISCLAIMER
  • GUACAMOLE-3 - Contribution guidelines are incorrect
  • GUACAMOLE-93 - Migrate Docker images to build from git
  • GUACAMOLE-97 - Update documentation for Docker images
  • GUACAMOLE-107 - Update documentation with respect to Apache
  • GUACAMOLE-116 - Strip pre-built minified JavaScript libraries from source tarball
  • GUACAMOLE-131 - JavaScript libraries should not be bundled in source

Screen sharing

Guacamole now supports screen sharing for all protocols, even those which do not inherently support it, like RDP and SSH. When granted permission, users can generate temporary share links for their active connections, with those links being invalidated when they disconnect. The degree of access granted by a share link is defined by the “sharing profile” used to generate that link.

Screen recording

All supported protocols (VNC, RDP, SSH, and telnet) can now be configured to record sessions to disk for later playback. These session recordings are actually Guacamole protocol dumps of the graphical updates being sent from the Guacamole server to users of that connection. They can be converted to a normal video stream using the new “guacenc” utility, which is part of the guacamole-server build.

Additionally, text-based protocols (SSH and telnet) can record sessions as text, using the same two-file format used by the script and scriptreplay commands.

Streamlined file transfers

The Guacamole web application now handles file transfers via HTTP. This speeds things up considerably, removes limitations on file size imposed by JavaScript, and removes the need for manually initiating the actual download by clicking a link.

File transfer is still handled via the Guacamole protocol. The streams are dynamically intercepted, stripped, and exposed via HTTP by the web application in response to specific REST API requests. This is strictly a frontend change and does not affect the core Guacamole stack and protocol, which continues to handle file transfer as it always has.

RDP audio input

RDP’s AUDIO_INPUT channel is now supported. If your RDP server supports audio input, corresponding support can be enabled on your RDP connections in Guacamole.

Audio recording only occurs when an application running within the remote desktop requests access, and then only if that access is granted by the user. The user will be prompted by their browser to allow or deny access.

Keyboard improvements

Use of the numeric keypad was broken in version 0.9.9. This should now be fixed.

New keymaps for RDP have also been contributed, including Dutch, Japanese, and fixes for the existing French layout.

Local clipboard integration

Guacamole will now use the W3C Clipboard API (document.execCommand()) to attempt to read the local clipboard. Few browsers allow this in circumstances compatible with remote desktop, IE11 among them. If this fails, things continue to work as they have in past releases (clipboard access via the Guacamole menu/sidebar).

IE11 will prompt the user to allow clipboard access. Other browsers will typically deny access without any sort of prompt. For Chrome, there is a third-party extension, Clipboard Permission Manager, which allows the user to grant unrestricted access to the W3C Clipboard API on a per-domain basis.

Theming extensions

Guacamole’s extension system now supports modification of the HTML structure in addition to the authentication and CSS/JavaScript/translation modification components. This is achieved through specially-formatted HTML “patches”, documented in more detail within the manual.

  • GUACAMOLE-9 - Allow modification of HTML via extensions

Docker improvements

The Guacamole Docker images have been updated to support LDAP, as well as the concurrency limit properties of the database authentication backend.

  • GUACAMOLE-8 - Allow concurrency properties to be configured within Docker
  • GUACAMOLE-21 - Support LDAP within Docker image
  • GUACAMOLE-27 - Bring Docker images into new git repositories
  • GUACAMOLE-50 - Update Docker containers to use Java 8

Improved user management

Support for role-based access control within LDAP via the standard seeAlso attribute has been added, allowing access to connections to be dictated on a per-group basis, rather than strictly per-user.

Guacamole’s administrative interface has also been mildly enhanced, adding a convenient “Clone” button for copying users and their associated permissions (similar to the “Clone” button already available for connections).

  • GUACAMOLE-12 - Allow LDAP role-based access control for guacConfigGroups
  • GUACAMOLE-14 - Add support for cloning existing users

Absolute concurrency limits

Administrators can now restrict the total number of active connections allowed by a Guacamole server. Unlike other existing concurrency limits, this limit ignores connection and user identity; it is a strict absolute limit covering overall use.

Session affinity (“sticky sessions”)

For the cases where balancing groups may route users to any one of several desktops, and it is important that users are consistently routed to the same desktop to avoid losing work, administrators can now enable “session affinity” on those balancing groups. Users of those balancing groups will then be directed to the same underlying connection until they logout from Guacamole.

  • GUACAMOLE-53 - Add support for session affinity within balancing groups

Exposing terminal output to JavaScript

Both SSH and telnet now expose raw text output via the Guacamole protocol’s “pipe streams” (essentially named pipes). Though not leveraged by the Guacamole web application, downstream users of the Guacamole API can grab and handle the data sent along these streams as they see fit using client-side JavaScript.

  • GUACAMOLE-17 - Allow terminal output to be redirected to pipe streams

Miscellaneous bugs

This latest release of Guacamole also includes fixes for minor usability issues in IE11, failures to render errors properly under certain circumstances, and typos in Guacamole’s French translation.

  • GUACAMOLE-10 - Keyboard focus is permanently lost after clicking the URL bar in IE11
  • GUACAMOLE-11 - No error screen during an invalid SSH login in 0.9.8
  • GUACAMOLE-18 - Fix typo in French translation
  • GUACAMOLE-22 - Update missing french translations
  • GUACAMOLE-23 - __guac_socket_fd_select_handler() must always init fd_set
  • GUACAMOLE-35 - Performance flags not handled
  • GUACAMOLE-66 - Remove usage of Apache Commons Codec Library
  • GUACAMOLE-67 - I/O error in WebSocket can cause connection tracking to fail
  • GUACAMOLE-76 - Retrieval of connection group tree too slow
  • GUACAMOLE-112 - Update MessageFormat
  • GUACAMOLE-115 - Client may not cleanly disconnect if tunnel read() is blocking

Deprecation / Compatibility notes

As of 0.9.10-incubating, the following changes have been made which affect compatibility with past releases:

Database schema changes

The MySQL and PostgreSQL schemas have changed to facilitate screen sharing support. Users of the database authentication will need to run the upgrade-pre-0.9.10.sql script specific to their chosen database.

Deprecation of the basic-user-mapping property

The basic-user-mapping property used to specify an alternative location for user-mapping.xml is now deprecated. The property will continue to function as in previous releases, but a warning will be logged advising of its deprecation.

Administrators should instead place their user-mapping.xml files directly within GUACAMOLE_HOME.

Removal of deprecated lib-directory and auth-provider properties

The lib-directory and auth-provider properties have been deprecated since the 0.9.7 release, in favor of a self-contained extension format which does not require their use. From 0.9.7 on, though these properties still functioned as in 0.9.6 and older, a warning was logged advising of their deprecation.

These properties have now been removed, and configurations which rely on these properties will need to use the extensions/ directory within GUACAMOLE_HOME instead.

Rename from org.glyptodon.guacamole to org.apache.guacamole

As Guacamole is now a project operating under the Apache Incubator, its Java classes and Maven artifacts have moved from the org.glyptodon.guacamole package and groupId to org.apache.guacamole. Downstream developers using Guacamole’s APIs will need to update their source code accordingly.

Extension API changes for screen sharing

The Guacamole extension API (guacamole-ext) been changed to provide for storage of sharing profile data, and to allow for extensions to generate temporary credentials for shared connections. If you have written an extension for Guacamole, you may need to implement additional functions in addition to rebuilding your extension against the latest.

These changes center around the addition of the Shareable and SharingProfile interfaces, and primarily affect implementations of the following interfaces:

The updated guacamole-ext overview within the manual covers these changes, particularly the managing/sharing active connections section.

libguac API changes

The libguac API has been extensively modified for the sake of screen sharing. A new guac_user structure has been added to represent each user sharing a logical connection, where that connection is represented by guac_client. This requires a completely new initialization flow for protocol support implementations, and any plugins which provide additional protocol support for guacd will need to be updated.

These changes are documented in more detail in the updated libguac overview within the manual.