Apache Guacamole 0.9.14

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.14 release features new support for OpenID Connect, SQL Server databases, pass-through of user credentials for CAS, and tracking of user login/logout history. Various fixes and improvements for RDP, clipboard, file transfer, and terminal emulation have also been implemented.

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

Support for OpenID Connect

OpenID Connect, a single sign-on (SSO) solution built atop the OAuth 2.0 framework, is now supported by Guacamole as a source of user identity. Similar to the support for CAS added in 0.9.13-incubating, this new extension allows Guacamole to delegate authentication to the identity provider implementing OpenID Connect.

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

Support for SQL Server

In addition to MySQL and PostgreSQL, Guacamole now supports using SQL Server as a database backend. This support is built off the same core that drives the MySQL and PostgreSQL support, and thus includes the same screen sharing, administration, connection tracking, etc. features.

CAS credential pass-through with “ClearPass”

The support for CAS added in 0.9.13-incubating now supports credential pass-through using CAS’ “ClearPass” feature. If the CAS system in use has “ClearPass” enabled, and Guacamole has been provided with the key necessary to decrypt received credentials, Guacamole will automatically make user credentials available for inclusion within connection parameters via the ${GUAC_USERNAME} and ${GUAC_PASSWORD} parameter tokens.

Tracking of user login/logout history

While Guacamole has always logged user login/logout events, overall user access history has only been tracked at the database level on a per-connection basis. Guacamole now provides support for tracking the times that each user logs into or out of Guacamole, recording this information within a dedicated database table. The last time that each user was active is also exposed within the user administration interface, allowing inactive/stale user accounts to be more easily identified.

Export connection history to CSV

For the sake of using connection history data within external tools, Guacamole now supports exporting the connection history data shown within the admininstration interface to a CSV file. The exported data takes the current sort order and filter into account.

  • GUACAMOLE-334 - Provide connection history export from admin UI

/etc/guacamole as default GUACAMOLE_HOME

Historically, GUACAMOLE_HOME has been a consistent source of confusion for users, with many unnecessarily setting the GUACAMOLE_HOME environment variable or going to extreme lengths to try to force the location to /etc/guacamole, rather than simply using the default location. This confusion was compounded by documentation which described GUACAMOLE_HOME from the perspective of the system, rather than from the perspective of the user.

In an effort to make things less confusing, Guacamole now includes /etc/guacamole as one of the default locations of GUACAMOLE_HOME, and the wording of the documentation covering GUACAMOLE_HOME has been clarified to avoid further confusion.

  • GUACAMOLE-335 - Add /etc/guacamole to default search paths for GUACAMOLE_HOME

Clipboard behavior fixes

Recent changes adding support for direct integration of the local clipboard resulted in a pair of regressions which stripped newline characters from clipboard contents and caused performance issues under Internet Explorer. These issues have now been fixed.

Restoration of support for event listeners

In order to provide a simpler mechanism for extensions to monitor and react to user actions, the event listener API previously provided by Guacamole has been restored. This API had been removed as part of the the migration to a new, self-contained format for Guacamole extensions, however the new extension format has been augmented to allow event listeners to once again be defined.

  • GUACAMOLE-364 - Add support for authentication and tunnel event listeners

Connection load balancing and dynamic failover

Guacamole’s extension API defines the concept of “balancing groups” to cover cases where what appears to be a single connection to a user must actually be dynamically routed to one of several underlying ocnnections based on overall load. Within the database authentication extension, the determination of load has been based purely on the number of active connections to each underlying connection. The database authentication extension has now been updated to implement a weighted balancing algorithm, allowing the relative performance of each connection to be manually specified or dynamically updated.

The behavior of balancing groups within the database extension has also been updated to allow pecific connections may also be designated as failover-only, reserving those connections for use only if no other connections are working.

Docker multi-stage builds

Guacamole’s Docker images have been updated to leverage multi-stage builds. For users simply pulling the Docker images from Docker Hub, this has no real effect other than slightly smaller images. For users building the Docker images themselves, you will now need to use a recent version of Docker CE. Older versions of Docker lack support for multi-stage builds, and will fail to build the images.

SSH/SFTP improvements

Guacamole’s support for SSH has been updated to include support for keep-alive packets, allowing the connection to be kept alive despite lack of user input when the SSH server is set to otherwise terminate such connections. Problems with connecting to SSH servers at IPv6 addresses and with proper handling of incorrect private keys have also been addressed.

If SFTP is being used for file transfer, whether for SSH, VNC, or RDP, the directory used as the top-level (root) directory can now be configured, isolating access to a particular directory and its subdirectories rather than exposing the entire filesystem.

  • GUACAMOLE-203 - Implementing ServerAliveInterval to keep SSH session alive
  • GUACAMOLE-303 - Allow SFTP root directory to be configured
  • GUACAMOLE-396 - guacd cannot connect to ssh servers with IPv6 addresses
  • GUACAMOLE-400 - Connection segfaults when SSH private key fails to load

LDAP improvements

Previously, if Guacamole was configured to use LDAP for authentication, and the LDAP server required following referrals for queries involved in Guacamole’s authentication process, authentication against LDAP would fail. This issue has been addressed, and Guacamole can now be configured to follow LDAP referrals.

An issue with handling of database account restrictions when users are authenticated through LDAP has also been addressed. As long as the database authentication is configured to require database accounts for all users, database-specific access restrictions will be enforced.

  • GUACAMOLE-243 - LDAP auth fails when search results include an LDAP referral
  • GUACAMOLE-284 - Database “Account Restrictions” not applied when using LDAP

Fixes for CAS support

With the recent addition of support for single sign-on using CAS, it was discovered that the ${GUAC_USERNAME} parameter token will not be populated in cases where the user was authenticated against the CAS extension. This has now been fixed, and the ${GUAC_USERNAME} token will always be populated for all users that have successfully authenticated through any mechanism.

Issues with the behavior of the Guacamole settings/preferences screen when the CAS extension is installed, and with overall error handling and logging with respect to CAS, have also been addressed. The settings/preferences screen should now function normally, and errors from the CAS server should now be correctly logged.

Extension hooks for logout and shutdown

Functions which are invoked upon user logout, session expiration, and/or server shutdown have been added to the applicable interfaces of the Guacamole extension API, allowing extensions to hook into these events to handle cleanup of resources, synchronization of user signout, etc.

Note that because these new functions are defined at the interface level, all extensions which implement these interfaces will need to implement these functions. Please see the deprecation / compatibility notes section for more information.

  • GUACAMOLE-393 - Allow extensions to hook into logout / server shutdown

Restoration of Windows support for libguac

Although guacd has hard dependencies on Linux- or UNIX-specific features, Guacamole historically supported Windows builds at least at the library level. This support continued until recently, when changes resulted in libguac failing to build on Windows platforms. Support for Windows builds of libguac has now been restored, allowing development of Windows applications which leverage the Guacamole protocol.

Miscellaneous fixes/improvements

Among several other minor changes and fixes, this latest release of Guacamole also addresses several low-impact memory leaks within guacamole-server, adds support for redefining the terminal color palette SSH and telnet through the console codes used by xterm, and fixes the behavior of file downloads for RDP where the desired file contains multiple alternative streams.

  • GUACAMOLE-279 - Add support for redefining the terminal color palette
  • GUACAMOLE-326 - Alternative streams on Windows 10 result in multiple file downloads
  • GUACAMOLE-328 - Documentation omits that libssl is required for ssh support
  • GUACAMOLE-338 - Always display selected connections/groups within admin UI
  • GUACAMOLE-339 - Add Remote Host IP to Guacamole Connection History table
  • GUACAMOLE-345 - Ensure SQL scripts are compatible with PostgreSQL 8
  • GUACAMOLE-346 - Improve performance of in-browser recording playback
  • GUACAMOLE-357 - Update documentation for libjpeg-turbo dependency with respect to Ubuntu
  • GUACAMOLE-383 - Failures to open guacd.conf, read RDP clipboard data, or load terminal font may leak memory
  • GUACAMOLE-385 - HTTP tunnel uses incorrect content type for write operations
  • GUACAMOLE-391 - guacd_conf_load() leaks structure if config file fails to parse
  • GUACAMOLE-395 - User “expired” column not actually queried for MySQL
  • GUACAMOLE-398 - guac_common_ssh_create_session() potentially leaks address info
  • GUACAMOLE-402 - Out-of-tree build doesn’t compile
  • GUACAMOLE-411 - guacd_send_fd call’s sendmsg with uninitialized buffer

Deprecation / Compatibility notes

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

Database schema changes

The MySQL and PostgreSQL schemas have changed, adding new columns to the guacamole_connection table for specifying connection weight (for use in weighted balancing) and for designating connections as failover-only, adding a new column to guacamole_connnection_history for tracking the remote address of each connecting user, and adding a new guacamole_user_history table for tracking user login and logout.

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

Extension API changes

Session and server shutdown hooks

The AuthenticatedUser and UserContext interfaces now define an invalidate() function which is invoked when the associated user session is being terminated due to logout, expiration, or server shutdown. Because these new functions are defined at the interface level, implementations of these interfaces will now need to define these functions:

Similarly, the AuthenticationProvider interface now defines a shutdown() function which is invoked upon server shutdown. As with the new invalidate() function, this function is defined at the interface level and will need to be implemented by all classes implementing AuthenticationProvider:

Deprecation of ConnectionRecordSet

The ConnectionRecordSet interface and SimpleConnectionRecordSet class have been deprecated, replaced by the more generic ActivityRecordSet interface and SimpleActivityRecordSet class. Extensions using the old interface or class will continue to build, but should be migrated over to the newer API as soon as possible.

Additional history functions for Connection and User

The Connection and User interfaces now define essentially the same pair of getLastActive() and getHistory() functions, as both types of objects now have associated history within the extension API. For Connection, the only new function here is getLastActive():

History tracking of users is entirely new, however, and implementations of User will need to define both functions:

Note that extensions are not required to implement history tracking; if the extension will not implement or expose such tracking, the implementations of these functions can simply return nothing.