Release documentation

• Manual
• guacamole-common
• guacamole-common-js
• guacamole-ext
• libguac
• libguac-terminal

Release notes

The 1.5.0 release features support for in-browser playback of session recordings, retrieving secrets from key vaults, SSH support for elliptic-curve cryptography (ECC) keys, and support for authenticating against multiple LDAP or Active Directory servers. Users also will now automatically receive notification of users joining a shared connection, including when administrators join an active connection via the “Active Sessions” screen.

For a full list of all changes in this release, please see the changelog.

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

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

In-application playback of recordings

Guacamole now supports playback of session recordings directly within the web application. An extension is provided that, if installed, defines a standard location and naming convention for session recordings that allows those recordings to be associated with connection history entries:

Any user with sufficient permissions to see those history entries will then be able to directly open the recording in an in-browser player by clicking a link next to the history entry in the “History” screen of the administration interface:

Support for retrieving secrets from key vaults

Secrets for both connection parameters and properties within guacamole.properties can now be retrieved from key vaults, with initial support for Keeper Secrets Manager (KSM). Leveraging parameter tokens, the administrator can configure connections to automatically pull secrets like passwords or private keys from the vault based on the connection’s username, the hostname, or other criteria. Custom tokens can also be defined for arbitrary secrets in the vault.

Notification when users join a session

As of 1.5.0, users of a connection that is shared with other users will receive a notification when those users join the connection, and will see a counter of the number of other users currently present in the upper-right corner of the display:

This notification and counter displays both users that have joined due to a share link and administrators that have joined by clicking on the connection within the “Active Sessions” screen. Users can at any time hover the mouse over the counter to see which users are currently present:

SSH support for ECC keys

As long as libssh2 1.9.0 or later is installed, Guacamole supports using elliptic curve cryptography (ECC) private keys for SSH and SFTP connections, including keys in OpenSSH format. This support relies on libssh2’s support for the same capability, so the libssh2 version must be at least 1.9.0. If your distribution does not provide a libssh2 package that is recent enough, you will need to either build libssh2 from source or use the guacamole/guacd Docker image.

Multiple LDAP servers

Guacamole can now consider multiple LDAP or Active Directory servers for authentication, attempting to authenticate the user against each defined LDAP server until authentication is successful or no servers remain.

The specific LDAP server that applies can also be narrowed before trying any servers at all by using username patterns, if part of the username can reasonably be used to determine this. An example where this might be the case would be usernames of the form DOMAIN\user or user@DOMAIN.

Changelog

User interface / platform

• See recordings by clicking on history record (GUACAMOLE-462)
• web browser could not play large size of session recording file as 1G size. (GUACAMOLE-896)
• Additional permissions from groups do not affect user home screen (GUACAMOLE-1275)
• Alert users when admins connect to their session (GUACAMOLE-1293)
• Allow bundling of library .jar files within extensions (GUACAMOLE-1508)
• Provide better CSS/structural context for branding and theming extensions (GUACAMOLE-1509)
• Automatically trim trailing whitespace from guacamole.properties values (GUACAMOLE-1511)
• Cannot copy/paste into admin fields if local clipboard integration is unavailable (GUACAMOLE-1523)
• SessionRecording “onload” event fires twice (GUACAMOLE-1545)

Docker images

• Docker: Allow configuring Tomcat's RemoteIPValve (GUACAMOLE-1005)
• SAML environment variables (GUACAMOLE-1322)
• Support setting “openid-groups-claim-type” property via Docker environment variable (GUACAMOLE-1394)
• Add support of SQL Server JDBC plugin in Docker Image (GUACAMOLE-1418)
• Docker implementation, The authentication type 10 is not supported. (GUACAMOLE-1433)
• Make api-session-timeout adaptable in Docker(GUACAMOLE-1475)
• Fix environment name of GUACD_PORT (GUACAMOLE-1491)
• Enable configuration of of the ‘extension-priority’ parameter via environment variable (GUACAMOLE-1507)
• “FATAL: No authentication configured” when using the auth-json extension (GUACAMOLE-1539)
• Update libssh2 version within guacd Docker image to fix SSH key extraction problems (GUACAMOLE-1540)

Authentication, integration, and storage

• Support storage of sensitive data within key vaults (GUACAMOLE-641)
• Add support for querying multiple LDAP servers (GUACAMOLE-957)
• SSL communication by mariadb connector/J is not possible (GUACAMOLE-1453)

Protocol support / guacd

• Add support for OpenSSH private key format (GUACAMOLE-745)
• Add support for ED25519 SSH keys (GUACAMOLE-746)
• RDP “reconnect” resizing breaks RDPDR (GUACAMOLE-876)
• RDP print process may hang (GUACAMOLE-1115)
• An improper locking bug (e.g., resource leak) due to unreleased lock (GUACAMOLE-1416)
• FreeRDP DVCPluginEntry returns UINT for all 2.0 versions (GUACAMOLE-1435)
• SSH public key authentication fails with “Unable to extract public key from private key” (GUACAMOLE-1504)
• libguac-terminal should be a shared library (GUACAMOLE-1538)
• Shared recording functionality should be public (GUACAMOLE-1543)

Internationalization

• Polish keyboard layout (GUACAMOLE-1495)

Documentation

• Documentation inconsistency regarding Docker setup (environment) (GUACAMOLE-1406)

General housekeeping and cleanup

• guacenc build fails against FFmpeg 4.4 (GUACAMOLE-1330)
• Some typo mistakes in some source files (GUACAMOLE-1446)
• Update Java/JavaScript dependencies for 1.5.0 (GUACAMOLE-1594)

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

libguac API changes

name added to guac_user_info structure

A new name member has been added to guac_user_info to allow implementations to retrieve the optional human-readable name received during the connection handshake, affecting the size of this structure.

Additionally, because guac_user_info forms a part of guac_user, this change also affects the memory offsets of members of the guac_user structure which follow the info member, such as data and various instruction handlers.

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

• GUACAMOLE-1293 - Alert users when admins connect to their session