Apache Guacamole 1.4.0 (Archived)

Apache Guacamole 1.4.0 is an archived release, and was originally released on 2022-01-01. The latest release of Apache Guacamole is 1.5.5.

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.

You must verify the integrity of any downloaded files using the OpenPGP signatures we provide with each release. The signatures should be verified against the KEYS file, which contains the OpenPGP keys of Apache Guacamole's Release Managers. Checksums of each released file are also provided.

Filename Signatures / Hashes
guacamole-client-1.4.0.tar.gz PGP SHA-256
guacamole-server-1.4.0.tar.gz PGP SHA-256

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.

Filename Signatures / Hashes
guacamole-1.4.0.war PGP SHA-256
guacamole-auth-duo-1.4.0.tar.gz PGP SHA-256
guacamole-auth-header-1.4.0.tar.gz PGP SHA-256
guacamole-auth-jdbc-1.4.0.tar.gz PGP SHA-256
guacamole-auth-json-1.4.0.tar.gz PGP SHA-256
guacamole-auth-ldap-1.4.0.tar.gz PGP SHA-256
guacamole-auth-quickconnect-1.4.0.tar.gz PGP SHA-256
guacamole-auth-sso-1.4.0.tar.gz PGP SHA-256
guacamole-auth-totp-1.4.0.tar.gz PGP SHA-256

Release notes

The 1.4.0 release features support for connection tiling, broadcasting keyboard events across multiple connections, and authentication with encrypted and signed JSON. Established support for single sign-on has been improved, multi-touch support for RDP has been added, and problems with audio input support for RDP have been corrected. For a full list of all changes in this release, please see the changelog.

The 1.4.0 release is compatible with older 1.x components. You should upgrade older components to 1.4.0 when possible, however things should continue to work correctly in the interim:

  • Extensions written for older 1.x releases can be used by 1.4.0.
  • Components written for the version of the Guacamole protocol used by older 1.x releases can be used with components of the 1.4.0 release.

Regardless of inter-component compatibility, there are changes in 1.4.0 which may affect downstream users of Guacamole’s APIs. Please see the deprecation / compatibility notes section for more information.

Connection tiling and keyboard broadcasting

Multiple connections can now be displayed simultaneously within the same browser tab, automatically arranged in an even, tiled layout:

Multiple client displays in a tiled arrangement

The currently-focused connection is indicated by a blue border, and the user can choose to focus any number of these tiled connections at the same time. If multiple connections are focused, keyboard interaction is broadcast across each of those connections.

Major fixes to RDP audio input support

Depending on the application in use within the remote desktop, Guacamole’s audio input support for RDP suffered from quality issues related to variability in audio buffer behavior and size. If the audio backend used by the application could not adjust for occasional bursts of audio packets, any audio packets received by the remote desktop that exceeded the remaining buffer space would be dropped, resulting in audible clicks/pops and faster-than-expected playback.

This has now been corrected. Guacamole will automatically throttle the amount of data it sends to the remote desktop to avoid running out of remote buffer space, ensuring the audio received by applications within the remote desktop is identical to the audio received by Guacamole via the browser.

RDP support for passing through multi-touch events

In addition to Guacamole’s established support for emulating a mouse on touch devices, multi-touch events may now be passed through to the remote desktop server when supported and enabled.

RDP supports multi-touch through its “RDPEI” channel. If touch is enabled on a Guacamole RDP connection, touch interaction with the Guacamole display will directly affect touch-enabled applications within the remote desktop session rather than being turned into mouse events.

Support for secondary SSO providers

Guacamole’s support for single sign-on has historically been all-or-nothing, with either all users using SSO to authenticate or none at all. This is no longer the case: Guacamole may now be configured to allow normal username/password authentication in addition to SSO, and multiple SSO providers may be used at the same time.

Whether an SSO authentication extension automatically takes effect for all users depends on whether that extension has priority, which can now be defined using the extension-priority property. For example, to automatically require SAML for all users, you would give the SAML extension priority above all others:

extension-priority: saml

Or, to allow username/password authentication and simply provide the option for users to use SAML, you would ensure that other extensions have priority:

extension-priority: *, saml

More information on using the extension-priority property and controlling the behavior of the supported SSO extensions can be found in the Guacamole manual:

Support for authentication with encrypted, signed JSON

The “guacamole-auth-json” authentication extension, formerly a third-party project maintained by Glyptodon, has now been brought into Apache Guacamole as one of the project’s own extensions.

guacamole-auth-json allows external software to automatically authenticate and authorize users with an encrypted and signed JSON document. As long as the received JSON has not expired and was encrypted and signed with the correct key, it is accepted as sufficient verification that the user is authorized to access the resources described by that JSON.

For more information, see the documentation covering guacamole-auth-json in the Guacamole manual.

Changelog

User interface / platform

  • Control caching of extension JS/CSS (GUACAMOLE-275)
  • Provide option for broadcasting input events across multiple connections (GUACAMOLE-724)
  • Migrate away from including auth token within REST API URLs (GUACAMOLE-956)
  • Users/groups with identifiers containing slashes cannot be modified (GUACAMOLE-1261)
  • Automatically enforce request size limits independently of reverse proxy (GUACAMOLE-1298)
  • Unexpected errors during session expiration may block further expirations (GUACAMOLE-1299)
  • Connection-specific history sorted in wrong order (GUACAMOLE-1366)
  • Login appears to succeed if the webapp is entirely down (GUACAMOLE-1384)

Docker images

Authentication, integration, and storage

Protocol support / guacd

Internationalization

Documentation

  • Document branding process (GUACAMOLE-747)
  • Add non-nullable modifiers to JSDoc parameter/return types where appropriate (GUACAMOLE-986)
  • Document configuration of client_max_body_size for Nginx (GUACAMOLE-1060)
  • Typo in documentation of mimetype parameter (GUACAMOLE-1185)
  • “Verifying” repeatedly misspelled in libguac documentation (GUACAMOLE-1225)
  • Migrate guacamole-manual away from DocBook (GUACAMOLE-1347)
  • Usage documentation of guacNotification directive is incorrect (GUACAMOLE-1396)

General housekeeping and cleanup

  • Creation of source .tar.gz fails on platforms with large group IDs (GUACAMOLE-503)
  • Update webapp dependencies to latest stable and compatible versions (GUACAMOLE-773)
  • Build fails against libvncclient 0.9.7 (GUACAMOLE-1227)
  • Implement VerifyCertificateEx rather than VerifyCertificate (FreeRDP 2.3.1) (GUACAMOLE-1307)
  • guacamole-client build fails against newer versions of JDK (GUACAMOLE-1317)
  • Translation files contain unnecessary trailing whitespace (GUACAMOLE-1337)

Deprecation / Compatibility notes

Each 1.x release of Apache Guacamole should be compatible with components of older 1.x releases. This compatibility is intended at the Guacamole protocol level and at the extension level, but not necessarily at the API level. This means:

  • Extensions from older 1.x releases should still work in binary form, but may need code changes before their source will build against a newer version of guacamole-ext.
  • Software which uses the Guacamole protocol of an older 1.x release should still work.
  • Software which uses libguac from an older 1.x release should still work by continuing to use the libguac from that release, as newer versions of libguac may not be API/ABI compatible. In the case of third-party protocol support plugins for guacd, this means that the guacd from that release must also be used. Compatibility with respect to libguac is represented by the soname.
  • You should update to newer versions where applicable and when possible.

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

Java API (guacamole-common) changes

GuacamoleHTTPTunnelServlet sessions are now decoupled from the GuacamoleTunnel UUID

The GuacamoleHTTPTunnelServlet internals have been improved to entirely decouple the concept of the tunnel UUID (as returned by getUUID()) from the concept of the HTTP tunnel session. The HTTP tunnel now instead generates its own random session identifier that is independent of the UUID.

Internal, UUID-specific functions of GuacamoleHTTPTunnelServlet like registerTunnel() and deregisterTunnel() have been deprecated in favor of versions of these functions that do not assume the tunnel will be identified by its UUID. It is not common to use these functions in subclasses of GuacamoleHTTPTunnelServlet. Any such usages should continue to work, but should be migrated to the new versions of these functions when possible.

  • GUACAMOLE-956 - Migrate away from including auth token within REST API URLs

Extension API (guacamole-ext) changes

Default LocalEnvironment constructor is now deprecated

To facilitate automatic retrieval of guacamole.properties values from key vaults, the Environment interface has been improved to allow arbitrary sources of properties to be added, and the LocalEnvironment implementation has been updated to be a singleton. New usages should invoke LocalEnvironment.getInstance() instead of manually creating new instances.

Old usages of the default constructor will still work as expected, but will produce a compile-time warning about deprecation. The old default constructor will still create a new LocalEnvironment instance, however this new instance will actually transparently delegate to the LocalEnvironment.getInstance() singleton.

Note that while completion of vault support has been bumped to the next release, this core API improvement is still present on 1.4.0.

  • GUACAMOLE-641 - Support storage of sensitive data within key vaults

libguac API changes

touch_handler added to guac_user structure

To allow multi-touch events to be passed through from client to server where supported, an additional touch instruction has been defined within the Guacamole protocol to represent the state of an individual touch. A new handler, touch_handler, is now present within the guac_user structure to allow this instruction to be handled when received from the client. This change affects the in-memory size of the guac_user structure.

Downstream usages of libguac which make use of guac_user will need to be rebuilt to ensure that the structure sizes and memory offsets used are correct.

guac_wol_wake() now accepts a UDP port parameter

The guac_wol_wake() function now accepts an additional parameter defining the UDP port to be used for the magic packet. This change affects the formal arguments of guac_wol_wake().

Downstream usages of libguac which make use of guac_wol_wake() will need to be updated to include the port number and rebuilt. The UDP port used previously for all calls to guac_wol_wake() was 9, as defined by the GUAC_WOL_PORT constant.