released: false title: 1.6.0 date: 2024-05-02 14:05:35 -0700 summary: > Improved rendering performance, improved Docker support, configurable case sensitivity, batch connection import, support for FreeRDP 3.x and Duo v4.

artifact-url: “https://dist.apache.org/repos/dist/dev/{}” checksum-url: “https://dist.apache.org/repos/dist/dev/{}” download-path: “guacamole/1.6.0-RC1/” checksum-suffixes: “PGP” : “.asc” “SHA-256” : “.sha256”

source-dist: - “source/guacamole-client-1.6.0.tar.gz” - “source/guacamole-server-1.6.0.tar.gz”

binary-dist: - “binary/guacamole-1.6.0.war” - “binary/guacamole-auth-duo-1.6.0.tar.gz” - “binary/guacamole-auth-header-1.6.0.tar.gz” - “binary/guacamole-auth-jdbc-1.6.0.tar.gz” - “binary/guacamole-auth-json-1.6.0.tar.gz” - “binary/guacamole-auth-ldap-1.6.0.tar.gz” - “binary/guacamole-auth-quickconnect-1.6.0.tar.gz” - “binary/guacamole-auth-sso-1.6.0.tar.gz” - “binary/guacamole-auth-totp-1.6.0.tar.gz” - “binary/guacamole-history-recording-storage-1.6.0.tar.gz” - “binary/guacamole-vault-1.6.0.tar.gz”

documentation: “Manual” : “/doc/1.6.0/gug” “guacamole-common” : “/doc/1.6.0/guacamole-common” “guacamole-common-js” : “/doc/1.6.0/guacamole-common-js” “guacamole-ext” : “/doc/1.6.0/guacamole-ext” “libguac” : “/doc/1.6.0/libguac” “libguac-terminal” : “/doc/1.6.0/libguac-terminal”

The 1.6.0 release features improved rendering performance, improved Docker support, configurable case sensitivity, and support for newer upstream library releases like Duo v4 and FreeRDP 3.x. For a full list of all changes in this release, please see the changelog below.

The 1.6.0 release is compatible with older 1.x components. You should upgrade older components to 1.6.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.6.0.
  • Components written for the version of the Guacamole protocol used by older 1.x releases can be used with components of the 1.6.0 release.

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

Highlights

Improved rendering performance

This latest release of Guacamole includes a major rewrite of the established server-side protocol optimizer that has been part of guacd. Combined with corresponding enhancements to the web application, the new rendering pipeline is better able to leverage the server's processing power to increase responsiveness while reducing the required network bandwidth.

Guacamole has nearly always had a built-in optimizer that used cost estimation to rewrite and reorder graphical updates in a more efficient way. The new optimizer builds on that basis, adding real time detection of scrolling/movement, better heuristics for combining/splitting updates, and automatic parallelization of the encoding process:

These improvements have been incorporated into the public API of libguac as guac_display and have been made without requiring the use of a GPU. Instead, they leverage a pool of worker threads, careful pipelining (to avoid encoding blocking further processing of data), and a 2D variant of Rabin-Karp combined with a purpose-built hash function.

  • Improve efficiency of streaming complex/large changes (Graphics Pipeline Extension, RemoteFX) (GUACAMOLE-377)

Improved containerized deployment options

The guacamole/guacamole Docker image has historically required manual mapping of all environment variables that correspond to the configuration properties used by guacamole.properties. This is now done automatically for all properties, including any properties defined by third-party extensions. Every property supported by Guacamole is now automatically pulled from an environment variable within the provided Docker image.

For cases where third-party extensions are used, the GUACAMOLE_HOME environment variable supported by the Docker image has been made more flexible, with the standard /etc/guacamole usable by default without requiring GUACAMOLE_HOME to be set at all.

Builds of the Docker image have also been expanded to support ARM CPUs, not just x86.

Dedicated audit permission

For cases where otherwise unprivileged users must see the usage history for Guacamole without having full system-level administration permissions, a new AUDIT permission has been added to cover read-only access to history. Granting this permission to a user allows them to see past usage without implying any other permissions.

  • Add the ability to specify separate permissions for “History” and “Active sessions” tabs (GUACAMOLE-538)

Points of interest in session recordings

To allow administrators to more easily see where interesting parts of session recordings might be, the in-browser session recording player now includes a histogram above the playback timeline/bar that represents areas of greater activity with peaks. If the recording contains key events, an additional histogram that shows areas of keyboard activity is also included.

A screenshot of Guacamole's in-browser session recording player showingcombined histograms of on-screen activity and keyboard activity.

  • History Recording Player should indicate points of interest (GUACAMOLE-1876)

Batch import of connections from CSV, JSON, and YAML

Guacamole's administrative interface now includes an “Import” button within the “Connections” tab. Users with permission to create connections within Guacamole can now use this button to import a batch of connections from CSV, JSON, or YAML files that conform to the documented format, rather than manually create each connection.

Configurable case sensitivity

Whether Guacamole handles usernames and group names in a case-sensitive or manner is now configurable globally using the case-sensitivity property (or CASE_SENSITIVITY environment variable). This is particularly aimed at cases where multiple authentication providers are involved that do not agree on whether usernames are case-sensitive, such as when combining LDAP (typically case-insensitive) with a PostgreSQL database (case-sensitive).

For sake of compatibility and not changing established behavior, Guacamole defaults to case-sensitive username and group name handling.

Complex access restrictions

Similar to the access restrictions provided by the database support, a separate extension is now provided that allows time-based and host-based restrictions to be enforced on users, user groups, connections, and balancing connection groups. These restrictions can be used to determine the conditions required to log into Guacamole or to limit when specific connections may be accessed.

  • Broadly configurable time limits for user logins and connection usage (GUACAMOLE-1020)

Migration to Duo Web SDK v4

Duo ceased supporting the previous version of their Web SDK (v2) and implementations are required to migrate to the newer version (v4) or request continued access to v2 on a limited basis. Guacamole has now migrated to v4 of the Duo Web SDK.

This new version of Duo's service is fundamentally incompatible with Duo v2 and uses different configuration options. Users that have been using Guacamole with Duo by requesting continued access to v2 will need to move forward with switching to v4 and migrating their configuration. If necessary, it is possible to continue using the old version of the Duo extension to continue using Duo v2 until migration is possible.

Hidden clipboard contents

To better serve cases where private data may be copied into the clipboard, the contents of the clipboard editor in the Guacamole menu are now hidden by default. Clicking the clipboard editor reveals its contents, which will remain visible until the Guacamole menu is closed.

  • Ensure clipboard contents are visible/accessible in Guacamole only when desired (GUACAMOLE-1740)

Support for FreeRDP 3.x

The guacamole-server build now supports FreeRDP 3.x in addition to FreeRDP 2.x. While the FreeRDP 3.x release is incompatible with 2.x, it is not so different that support for 2.x needed to be dropped, and support for both is being maintained.

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

Migration to Duo v4

The new version of Duo's service uses different underlying mechanisms and requires different configuration options. If using Duo, you will need to take manual steps to update your configuration.

If you have been using the previous version of Guacamole's Duo integration, you can continue to use that integration until you can safely migrate.

When ready to migrate, please read through the updated documentation for using Duo with Guacamole. You will need to switch to new configuration options, and the proper values for the new options will need to be pulled from Duo's administrative interface. Do not rely on simply renaming the previous options without first checking whether the old values are still valid.

New AUDIT permission in database schema

The new audit-specific permission requires a new entry in the guacamole_system_permission_type enum used by the various Guacamole database implementations, which requires schema changes. To upgrade your database to the latest version, run the relevant upgrade-pre-1.6.0.sql script against your database.

Schema upgrade scripts are included for each database within the guacamole-auth-jdbc-1.6.0.tar.gz archive provided above in the list of downloads for this release.

  • Add the ability to specify separate permissions for “History” and “Active sessions” tabs (GUACAMOLE-538)

Deprecation of Docker links

The --link flag previously supported by Docker is considered deprecated. Guacamole's Docker documentation has been updated to reflect this, and the environment variables that result from using --link will now produce deprecation warnings. If you have been using Docker links, you should migrate away from that usage when possible.

Deprecation of GUACD_LOG_LEVEL and LOGBACK_LEVEL environment variables

The environment variables used by the guacamole/guacd and guacamole/guacamole images were previously inconsistent with each other (GUACD_LOG_LEVEL and LOGBACK_LEVEL respectively). These variables are now both, simply, LOG_LEVEL. Continuing to use the old variables will produce deprecation warnings.

Deprecation of Credentials getters/setters related to HttpServletRequest

As it is not reliable to attempt to access an HttpServletRequest outside the scope of the handling of that actual request, the getRequest() and setRequest() functions of the Credentials object have been deprecated. Also deprecated are the setters that directly relate to HTTP request details: setRemoteAddress(), setRemoteHostname(), and setSession().

Extensions that use these functions of the Credentials object should migrate to the getRequestDetails() and setRequestDetails() when possible.

  • {:.bug} Logging of request details fails with recent Tomcat (GUACAMOLE-2052)

guac_protocol_send_sync() now requires an additional parameter

Rendered frames may sometimes be combined into a single frame to compensate for any client-side lag, such as a browser being unable to process a frame as quickly as it was generated. To allow remote frame rate to be tracked in addition to the client frame rate, a new parameter has been added to guac_protocol_send_sync() which accepts the logical number of frames that went into the current frame.

  • Improve efficiency of streaming complex/large changes (Graphics Pipeline Extension, RemoteFX) (GUACAMOLE-377)

guac_recording_create() and guac_terminal_create_typescript() now require an additional parameter

To serve use cases where session recordings or typescripts need to be written to files that already exist, such as a named pipe or FIFO, the guac_recording_create() and guac_terminal_create_typescript() functions have been updated to require an additional parameter dictating whether this is permitted. Previously, attempting to write to an existing file would result in a numeric suffix being appended to the filename to resolve the filename collision.

guac_client structure size change

Internal members of the guac_client structure have changed, affecting its overall size and offsets of established, non-internal structure members.

All code using guac_client will need to be recompiled to be compatible.

  • Improve efficiency of streaming complex/large changes (Graphics Pipeline Extension, RemoteFX) (GUACAMOLE-377)

guac_socket structure size change

Internal members of the guac_socket structure have changed, affecting its overall size. Offsets of established, non-internal structure members are not affected.

It is unlikely that any external code manually allocates instances of this structure and passes those instances back to libguac, but any such code would need to be rebuilt to be compatible.

  • Base64 encoding of image/binary data results in excessive syscalls that can degrade performance (GUACAMOLE-1776)

Changelog

User interface / platform

  • Add the ability to specify separate permissions for “History” and “Active sessions” tabs (GUACAMOLE-538)
  • Support batch import of connections from CSV (GUACAMOLE-926)
  • Add parameter token for connection name (GUACAMOLE-1177)
  • Provide audit log for system modifications (GUACAMOLE-1224)
  • Configurable username case sensitivity (GUACAMOLE-1239)
  • Provide chunked file upload mechanism (GUACAMOLE-1320)
  • Display whether user groups are disabled in group list (GUACAMOLE-1479)
  • Support for true fullscreen mode and keyboard lock (GUACAMOLE-1525)
  • Allow branding/customization of the section headers on the user home page (GUACAMOLE-1584)
  • Add support for specifying VNC “encodings” parameter in webapp UI (GUACAMOLE-1642)
  • Automatically clear view if session expires in background (GUACAMOLE-1744)
  • Base64 encoding of image/binary data results in excessive syscalls that can degrade performance (GUACAMOLE-1776)
  • Update session recording playback progress during large frame gaps (GUACAMOLE-1803)
  • Enable viewing / searching of key events in session recording playback (GUACAMOLE-1820)
  • Improvements to the “Recent connections” section (GUACAMOLE-1866)
  • History Recording Player should indicate points of interest (GUACAMOLE-1876)
  • Enhance client custom field functionality (GUACAMOLE-1904)
  • Provide notification, jump-to-top of page for a clone operation (GUACAMOLE-1916)
  • {:.bug} Logging of request details fails with recent Tomcat (GUACAMOLE-2052)

Docker images

Authentication, integration, and storage

  • Ensure GUAC_DATE/GUAC_TIME tokens match connection startDate (GUACAMOLE-61)
  • Add Proxy Hostname and Port to LDAP Extension (GUACAMOLE-577)
  • Add webapp support for smart card authentication (GUACAMOLE-839)
  • Enforce rate limit on authentication attempts (GUACAMOLE-990)
  • Broadly configurable time limits for user logins and connection usage (GUACAMOLE-1020)
  • Randomize generation of TOTP key until enrollment is confirmed (GUACAMOLE-1068)
  • Allow TOTP to be disabled by group membership (GUACAMOLE-1219)
  • Update guacamole-auth-duo to “Duo Web v4 SDK” (GUACAMOLE-1289)
  • SAML module should be able to encrypt and sign requests (GUACAMOLE-1372)
  • Allow LDAP extension to configure TLS level (GUACAMOLE-1488)
  • Clarify TOTP reset/status logic (GUACAMOLE-1550)
  • Allow JDBC Auth Extensions to track history for external connections (GUACAMOLE-1616)
  • Allow extraction of “domain” token from vault extensions (GUACAMOLE-1623)
  • Enable more granular vault associations (GUACAMOLE-1629)
  • Allow use of KSM one-time tokens in guacamole-vault-ksm extension (GUACAMOLE-1643)
  • Allow per-user KSM Vault configurations (GUACAMOLE-1656)
  • KSM vault extension should allow searching records by domain (GUACAMOLE-1661)
  • Allow user to configure Keeper Secrets Manager call frequency (GUACAMOLE-1722)
  • Enforce user access windows even when already logged in (GUACAMOLE-1723)
  • Add SSO providers list to UI at most once (GUACAMOLE-1757)
  • Allow TOTP and SAML auth to be used together (GUACAMOLE-1780)
  • {:.bug} KSM Vault extension doesn't support private key from “PAM User” record type (GUACAMOLE-1795)
  • Map JWT claims from OpenID Connect as parameter tokens (GUACAMOLE-1844)
  • Allow MFA to be bypassed or enforced based on client IP (GUACAMOLE-1855)
  • Add parameter token for domain of LDAP user (GUACAMOLE-1881)
  • Disable autofill on TOTP verification code field (GUACAMOLE-1946)
  • Provide a comprehensive error message for input exceeding database column (GUACAMOLE-1948)

Protocol support / guacd

  • Allow selection of whole words by double-clicking (GUACAMOLE-192)
  • Improve efficiency of streaming complex/large changes (Graphics Pipeline Extension, RemoteFX) (GUACAMOLE-377)
  • Allow specifying connection timeout (GUACAMOLE-600)
  • Add support for FreeRDP 3.0.0 (GUACAMOLE-1026)
  • {:.bug} Connecting to unpublished RemoteApp results in black screen (GUACAMOLE-1084)
  • {:.bug} Add support for right modifier keys to SSH/Telnet (GUACAMOLE-1113)
  • Add auto resize to VNC sessions (GUACAMOLE-1196)
  • RemoteApp windows become inaccessible after being minimized (GUACAMOLE-1231)
  • {:.bug} Lines of file gets broken when navigating back and forth using a text editor (GUACAMOLE-1256)
  • Add option to the vnc protocol to disable remote input (GUACAMOLE-1267)
  • Add support for SSH certificates (GUACAMOLE-1290)
  • Add parameter for specifying known RDP server certificate/fingerprint (GUACAMOLE-1332)
  • {:.bug} “AltGr” received as “Alt” if remote keyboard layout lacks “AltGr” (GUACAMOLE-1473)
  • {:.bug} Terminal emulator adds newlines when copying a wrapped line of text (GUACAMOLE-1586)
  • Add small margins to SSH sessions (GUACAMOLE-1622)
  • {:.bug} Text copied from terminal emulator may incorrectly omit indentation (GUACAMOLE-1632)
  • Add terminal support for alternate screen buffer (GUACAMOLE-1633)
  • {:.bug} SFTP+VNC broken when built with OpenSSL versions >= 1.1.0 (GUACAMOLE-1652)
  • Clipboard normalization support for SSH connections (GUACAMOLE-1682)
  • Test machine availability when sending Wake-on-LAN packet (GUACAMOLE-1686)
  • {:.bug} Japanese characters display garbled in terminal when using guacd docker image (GUACAMOLE-1726)
  • Add parameters for VNC compression and quality levels (GUACAMOLE-1760)
  • Terminal protocols should support mac-style cmd+v paste shortcut (GUACAMOLE-1804)
  • Ignore Ctrl+Shift+C within terminal emulator (GUACAMOLE-1805)
  • Allow writing recordings to existing files (GUACAMOLE-1931)
  • {:.bug} RDP connection fails when microphone input is enabled (GUACAMOLE-1940)
  • {:.bug} Selected text in SSH is offset from cursor position (GUACAMOLE-1944)
  • {:.bug} Multiple wheel events per mouse wheel tick (GUACAMOLE-1967)
  • {:.bug} FreeRDP may invoke EndPaint without BeginPaint as of 3.8.0 (GUACAMOLE-1997)

Internationalization

Documentation

  • Docker instructions shall stop using --link to link containers (GUACAMOLE-531)
  • Add missing WEBAPP_CONTEXT variable in docker setup documentation (GUACAMOLE-1680)
  • Document RemoteIPValve to cover IPv4 and IPv6 (GUACAMOLE-1861)

General housekeeping and cleanup

  • Provide GuacamoleProperty List Implementations (GUACAMOLE-1006)
  • Expose client state enum values (GUACAMOLE-1402)
  • Guacamole manual: Makefile: “find” uses non-POSIX arguments (GUACAMOLE-1501)
  • {:.bug} Phantomjs build issues on ubuntu 22.04 (GUACAMOLE-1614)
  • Remove usage of AccessController (GUACAMOLE-1716)
  • {:.bug} Correct autoconf issues that result in odd build results (GUACAMOLE-1719)
  • Stop storing unnecessary auth response data in local storage (GUACAMOLE-1721)
  • {:.bug} Projects outside scope of 1.5.0 fail to build following merge of version number bump (GUACAMOLE-1731)
  • Automatically test pull requests using Github Actions (GUACAMOLE-1754)
  • {:.bug} Projects outside scope of 1.5.1 fail to build following merge of version number bump (GUACAMOLE-1767)
  • {:.bug} SQLSERVER_BATCH_SIZE defined twice in SQLServerGuacamoleProperties (GUACAMOLE-1789)
  • {:.bug} Projects outside scope of 1.5.2 fail to build following merge of version number bump (GUACAMOLE-1790)
  • {:.bug} Projects outside scope of 1.5.3 fail to build following merge of version number bump (GUACAMOLE-1829)
  • {:.bug} Merge conflict markers left in guacamole-manual source (GUACAMOLE-1833)
  • KSM Vault extension should support new PAM Hostname field type (GUACAMOLE-1868)
  • Align libraries on “Library status” output (GUACAMOLE-1869)
  • Check return values of WebP API functions (GUACAMOLE-1875)
  • {:.bug} Projects outside scope of 1.5.4 fail to build following merge of version number bump (GUACAMOLE-1887)
  • Bump versions for projects outside the 1.5.5 scope (GUACAMOLE-1915)
  • Add support for FFmpeg 7.0 (GUACAMOLE-1952)
  • Update dependencies to latest stable and compatible versions (GUACAMOLE-1956)
  • Bump versions to 1.6.0 (GUACAMOLE-1980)
  • {:.bug} Compile error in src/protocols/rdp/channels/rail.c (GUACAMOLE-1982)
  • Upgrade KSM SDK to latest (v16.6.5) (GUACAMOLE-1984)