Apache Guacamole 0.9.13-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.13-incubating release features new support for CAS single sign-on, automatic failover to connections within the same connection group, and fixes for issues in all supported protocols. The JavaScript API has also been extended to provide for in-browser playback of screen recordings, and the extension API now allows custom REST services to be defined.

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

Support for CAS single sign-on

Central Authentication Service (CAS), is a single sign-on solution commonly used by universities to unify authentication across various web applications which are otherwise independent. The newly-implemented guacamole-auth-cas extension allows Guacamole to delegate authentication to CAS, relying on CAS to determine the identity and validity of each user.

Note that this new extension only deals with determining the identity of users that have authenticated with CAS, and redirecting unauthenticated users to the CAS system to authenticate. The details of the connections available to each user must be provided via another extension, such as the database authentication.

Correction to Duo documentation

The documentation for Guacamole’s Duo extension previously stated that Duo’s “Auth API” was required. This is incorrect; though the “Auth API” will work, Guacamole actually uses the “Web SDK”. This is particularly important, as Duo recently ceased offering the “Auth API” for free, whereas the “Web SDK” is still available for free accounts.

  • GUACAMOLE-219 - Duo documentation should point to “Web SDK”, not “Auth API”

In-browser playback of screen recordings

Guacamole’s screen recordings are actually copies of the same exact data which would be fed to the Guacamole client over the course of the connection, thus the JavaScript API already had much of what was necessary to support in-browser playback of recordings. The main things lacking were a means of reading a Guacamole protocol stream from a static resource, and a means of seeking backward or forward within that stream.

This missing API-level functionality is now provided through the new Guacamole.StaticHTTPTunnel and Guacamole.SessionRecording objects respectively, and an example demonstrating this use, guacamole-playback-example, is provided within the guacamole-client source.

  • GUACAMOLE-250 - Implement support for in-browser playback of screen recordings

NoAuth now deprecated

Over the years since its introduction, the NoAuth extension has grown to become a consistent source of issues for both users and the Guacamole development community, and simply using the extension has become de facto bad practice. As such, the NoAuth extension is now deprecated.

To ease migration away from its use, the extension remains part of the Guacamole source and a convenience binary of the extension is provided with this release, but its continued use is not recommended and it will eventually be removed. Integrations of Guacamole should instead use the extension API, or the core Guacamole API for absolute low-level control.

SSH/telnet support for 256-color console codes

Guacamole has historically supported only the subset of console codes implemented by the Linux kernel’s built-in terminal emulator. As part of a larger, ongoing effort to achieve compatibility with xterm, support for xterm’s 256-color console codes has been added, along with support for the console code which changes the window title.

Automatic failover for connections in groups

In past releases, the database authentication would handle connection attempts to connection groups by selecting the least-used connection, but would otherwise only make one connection attempt. If that connection attempt fails due to an error within the remote desktop, the user must manually reconnect (or wait 15 seconds for the automatic reconnect).

Connection groups provided via the database authentication will now automatically and transparently switch to the next available connection in the group for remote desktop errors that occur early in the connection. If graphical updates are sent prior to the error, automatic failover will not occur.

This functionality has also been added at the Java API level. Extensions and applications leveraging the Guacamole API can use the FailoverGuacamoleSocket class to automatically detect and handle upstream (remote desktop) errors during the connection process.

  • GUACAMOLE-208 - Expand status codes to represent common remote desktop states
  • GUACAMOLE-267 - Support health checks for connections

Fixes for all supported protocols

Several bugs with each supported protocol have been addressed. Most significantly, issues with audio stream stability for recent versions of Windows, and transfer of large files over RDP, the behavior of the “Alt” key for SSH and telnet, and VNC connection stability have all been fixed.

Defining REST services via extensions

Extensions can now define arbitrary REST services by implementing the new getResource() function at either the AuthenticationProvider UserContext levels, returning objects annotated with JAX-RS (JSR-311) annotations.

REST resources exposed at the UserContext level are inherently tied to the user’s session and thus require authentication, while resources exposed at the AuthenticationProvider level do not.

  • GUACAMOLE-289 - Add support for declaring REST services within extensions

User profile attributes

The database authentication now defines additional, arbitrary attributes for users which, if specified, are rendered within Guacamole’s user menu. These attributes are optional - if omitted, the user menu renders as in previous releases.

The additional attributes are standardized at the API level on the User.Attribute object, and thus can be leveraged by any extension, producing the same effect.

Support for filtering LDAP users

Guacamole’s LDAP support now provides an additional ldap-user-search-filter property which, if specified, reduces the users that can log into Guacamole or are displayed to administrators within the user management interface (when combining LDAP with a MySQL or PostgreSQL database).

Note that this filter only affects Guacamole logins if Guacamole has been configured to search for users prior to binding (with the ldap-search-bind-dn property). If a search DN is not being used, Guacamole derives each user’s DN directly, and thus will not apply the search filter to login attempts.

Overriding guacd on a per-connection basis

The connection to guacd is normally defined globally within guacamole.properties, but this is insufficient for deployments involving multiple distinct guacd instances or multiple implementations of the Guacamole protocol.

For cases where different instances of guacd may be spread out across the network of remote desktop servers, or where other applications/drivers may implement their own internal version of guacd (such as the work-in-progress X.Org driver), Guacamole now supports defining/overriding the guacd hostname, port, and encryption method on a per-connection basis.

Miscellaneous fixes/improvements

This latest release of Guacamole also addresses several minor JavaScript issues, addresses potential disconnects due to system clocks which are not monotonic (can run backwards), and fixes the Docker image sanity checks such that database-specific environment variables need not be specified if a custom GUACAMOLE_HOME is being used.

  • GUACAMOLE-40 - Support TS gateway connections to RDP
  • GUACAMOLE-223 - Locking callbacks not set for guacd+SSL
  • GUACAMOLE-229 - Intervals when polling xmlhttprequests are not always cleared
  • GUACAMOLE-239 - Disconnects due to ‘backwards’ running time
  • GUACAMOLE-252 - Display jumps to top in MS Edge when Guacamole menu is opened
  • GUACAMOLE-259 - Log metrics for gauging user experience
  • GUACAMOLE-281 - GUACAMOLE_HOME not taken into account during Docker image sanity checks
  • GUACAMOLE-294 - Incorrectly positioned bracket in guacTouchDrag.js.
  • GUACAMOLE-295 - In Parser.js, the length variable is incorrectly checked for equality against NaN.
  • GUACAMOLE-301 - Login prompt not cleared when visiting unrestricted page

Deprecation / Compatibility notes

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

Database schema changes

The MySQL and PostgreSQL schemas have changed, adding columns to guacamole_connection (for defining the connection to guacd service implementing the Guacamole protocol) and to guacamole_user (for defining optional and arbitrary profile information).

Users of the database authentication will need to run the upgrade-pre-0.9.13.sql script specific to their chosen database.

Deprecation of the NoAuth extension

The NoAuth extension is now deprecated. The extension remains part of the Guacamole source and a convenience binary of the extension is provided with this release, but its continued use is not recommended and it will eventually be removed entirely.

Integrations of Guacamole should instead use the extension API, or the core Guacamole API for absolute low-level control.

Extension API changes

Both the AuthenticationProvider and UserContext interfaces now define a getResource() function. If implemented, the returned object will be served as a REST resource and must be annotated with JAX-RS (JSR-311) annotations. Because this new function is defined at the interface level, implementations of these interfaces will now need to define this function:

If your extension does not need to expose its own REST resources, the function can simply return null, and no such resources will be exposed:

@Override
public Object getResource() {

    // No associated REST resource
    return null;

}