Apache Guacamole 1.5.4 (Archived)

Apache Guacamole 1.5.4 is an archived release, and was originally released on 2023-12-07. 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.

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 1.5.4 release is a bugfix release that addresses miscellaneous bugs from 1.5.3 and earlier, and updates all dependencies to their latest compatible versions. For a full list of all changes in this release, please see the changelog below.

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

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

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


User interface / platform

  • History Recording Player should show controls when mouse is moved (GUACAMOLE-1872)
  • Control bar doesn’t auto-hide on history recording player (GUACAMOLE-1873)

Docker images

Authentication, integration, and storage

Protocol support / guacd

  • Race condition can cause the first user for a connection to miss updates (GUACAMOLE-1846)
  • Parser reparses same instructions multiple times in some cases (GUACAMOLE-1849)
  • guac_common_cursor_dup() may segfault if cursor is being modified (GUACAMOLE-1850)
  • Add libguac convenience functions for memory management (GUACAMOLE-1867)



  • TOTP Authentication - Add documentation relating to usage with docker (GUACAMOLE-1878)

General housekeeping and cleanup

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.5.4, the following changes have been made which affect compatibility with past releases:

Bulk user join support (join_pending_handler)

When a user joins an established connection via Guacamole’s sharing functionality, that user’s display state must be synchronised with the existing display state of the connection such that future updates will have the expected effects. Historically, this synchronization was done individually for each joining user via a single handler called join_handler.

As of 1.5.4, join_pending_handler has been added to allow all joining users to be synchronized at the same time. If using this new bulk synchronization support, the join_handler will be used primarily to parse user-specific connection parameters, while the join_pending_handler will be used to synchronize the display state to all users that are about to join. Using join_pending_handler avoids having to re-encode the same display state multiple times.

  • Race condition can cause the first user for a connection to miss updates (GUACAMOLE-1846)

Memory management macros

The latest version of libguac provides a series of guac_mem_*() macros for memory management and memory-related calculations that perform checked arithmetic. These macros are intended to replace manual usage of malloc(), calloc(), realloc(), and free() and should be preferred.

The addition of these macros does not itself affect compatibility, however established libguac functions that previously required returned memory to be freed using free() now document that returned memory should be freed with guac_mem_free(). Existing usage of free() instead of guac_mem_free() will continue to work but should be migrated when possible.

  • Add libguac convenience functions for memory management (GUACAMOLE-1867)