Apache Guacamole 1.2.0

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.2.0 release features support for SAML 2.0, Wake-on-LAN, and a new interface for easily switching between multiple active connections. The general behavior of the login interface has also been improved, as has the flexibility of the TOTP support, which may now be used even with user accounts that do not yet exist in the database.

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

New features and improvements

Single sign-on with SAML 2.0

Similar to existing support for CAS and OpenID Connect, Guacamole now provides support for SAML 2.0, allowing any identity provider implementing this standard to function as a source of identity.

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

Wake-on-LAN

Automatically activating machines using Wake-on-LAN is now supported for VNC, RDP, SSH, and telnet connections. Additional connection parameters are available which define how the Wake-on-LAN “Magic Packet” should be broadcast. If enabled on a connection, the “Magic Packet” will be sent before attempting to connect, signaling the desired machine to power up.

Easy switching between multiple connections

Users with access to multiple connections may now select from those connections within the Guacamole menu while already using another connection. The connection name that is displayed at the top of the Guacamole menu functions as a drop-down menu from which any accessible connection may be selected.

Once multiple connections are running, connections that are running in the background appear as thumbnails in a collapsible panel on the lower-right corner of the screen. These thumbnails update in real-time, and clicking on a thumbnail will switch to that connection without disconnecting.

  • GUACAMOLE-723 - Support display of multiple connections within same tab

Improved login behavior

When the Guacamole login dialog is displayed, the first blank login field will now automatically be focused, allowing failed logins to be more easily retried.

In deployments where the login process may be lengthy, such as when dependent on a response from a relatively slow database or LDAP server, the login form will now disable itself and fade out to indicate that the form has been submitted and the login attempt is being processed.

  • GUACAMOLE-302 - Refocus relevant in-progress login fields after auth failure
  • GUACAMOLE-742 - Display feedback while waiting for login

Using TOTP with non-database user accounts

Guacamole’s TOTP support can now be used alongside extensions like LDAP, so long as a database is also configured. The former caveat that TOTP users must have “Change own password” permission within the database no longer applies, and Guacamole’s various supported databases can now be configured to automatically create user accounts for users that have successfully authenticated.

  • GUACAMOLE-708 - Allow database storage of arbitrary attributes for non-database users

VNC support for usernames

Guacamole now supports username/password authentication for VNC in addition to the standard password-only authentication. VNC servers that require a username in addition to a password should now be accessible using Guacamole.

  • GUACAMOLE-514 - Implement additional authentication methods for VNC

Granular control of clipboard and file transfer

Copy and paste can now be individually disabled by the administrator on a per-connection basis, allowing data transfer through the clipboard to be tightly restricted.

File transfer has always been disabled unless explicitly enabled, however this support can now be enabled while also disabling download or upload, allowing file transfer to be restricted to a single direction.

Improved control of LDAP group object structure

Guacamole’s LDAP support now allows configuration of the type of groups used to dictate access. While Guacamole previously assumed use of the groupOfNames object class and its member attribute, other object classes like posixGroup may now be used, and their corresponding member attributes may be defined.

  • GUACAMOLE-300 - Support posixGroup in LDAP Authentication and Group-based Session Admission

guacenc support for MPEG-4 containers

The optional guacenc utility that is part of guacamole-server will now produce video within MPEG-4 container files, not just raw, containerless MPEG-4 video streams.

Support for SSL/TLS database connections

For MySQL and PostgreSQL servers that require SSL/TLS connections, Guacamole now provides options to configure this. Additional properties within guacamole.properties may be specified to allow/require use of SSL, as well as to configure the level of certificate validation.

  • GUACAMOLE-728 - Docker image unable to connect to MySQL8 docker: Public Key Retrieval Not Allowed

Support for the MariaDB JDBC driver

While MySQL and MariaDB share a common origin and are generally compatible, their corresponding JDBC drivers have diverged, and Guacamole’s MySQL/MariaDB support previously assumed that the MySQL driver would be used.

Guacamole now supports the MariaDB version of “Connector/J” in addition to the MySQL version.

Support for SQL Server instance names

SQL Server supports deploying multiple instances on the same server, with each additional instance identified by its own unique name. If using SQL Server, and your deployment uses named instances, the name of the instance containing the Guacamole database can now be specified using the sqlserver-instance property.

Internationalization

Czech and Japanese translations of the web interface

The web interface of Guacamole has been translated into Czech and Japanese. These languages will now be automatically selected if accessing Guacamole from a browser where either is set as the preferred language, and can be manually selected within Guacamole’s preferences.

Belgian French, Hungarian, and Latin American keymaps for RDP

Keymaps have been added to better support RDP servers which use the Belgian French, Hungarian, or Latin American keyboard layouts. As always, bear in mind that the client side of Guacamole is independent of keyboard layout. Additional keyboard layouts for RDP are mainly of benefit if:

  1. Your RDP server does not support Unicode events.
  2. Your RDP server is set to a keyboard layout which is not the default (US English).

If your RDP server is set to US English and supports Unicode events, it should not be necessary to select a specific layout. The user’s local keyboard should simply work, regardless of whether it matches the layout of the RDP server.

Updates to the French translation of the web interface

The existing French translation has been updated to take into account recent changes to the web interface, adding French translations for portions of text which previously would have been displayed in English as a fallback.

  • GUACAMOLE-759 - update translation fr.json for guacamole-client

Bug fixes

Regressions due to FreeRDP 2.0.0 migration

Several regressions were identified following the Apache Guacamole 1.1.0 release which were due to the massive migration from FreeRDP 1.x to FreeRDP 2.0.0 and primarily affected use of RemoteApp, Hyper-V, and VirtualBox. These regressions have now been fixed, and RDP connections involving these technologies should work as expected.

  • GUACAMOLE-947 - Clipboard error message when connected to the RDP server
  • GUACAMOLE-952 - Preconnection PDU support no longer works following migration to FreeRDP 2.0.0
  • GUACAMOLE-962 - Cannot connect to VirtualBox RDP following migration to FreeRDP 2.0.0
  • GUACAMOLE-978 - RemoteApp session to Windows Server 2016 closes after roughly 2-3 minutes
  • GUACAMOLE-979 - RDP settings strings may be double-freed
  • GUACAMOLE-1053 - guacd segfaults when user actively presses keys at RDP disconnect time
  • GUACAMOLE-1076 - Another copy of RemoteApp is launched in case of session reconnect

Audio input behavior

Following changes to the JavaScript API exposed by browsers for accessing audio input streams, support for audio input within Guacamole ceased to function correctly. This was due to:

  • A change in the return type of the navigator.mediaDevices.getUserMedia() function
  • Changes in Chrome’s autoplay policy

Both causes have been addressed, and audio input should now function correctly.

iPad and iOS 13 support

Users of iOS and iPadOS mobile devices reported erratic behavior of the Guacamole interface following a system update, ultimately resulting in inability to interact with remote desktops using touch mouse emulation. These issues were determined to be due to changes in iOS Safari’s handling of the browser viewport, and have been corrected by updating Guacamole’s interface to be independent of the aspects that changed.

  • GUACAMOLE-810 - Ipad screen jumps upwards while user focuses on Text Input.
  • GUACAMOLE-883 - Touch mouse emulation no longer works as of iOS 13

Login screen behavior on Firefox

When logging into Guacamole using Firefox, the “Enter” key could become effectively stuck if used to submit the login form. This was due to the lack of a corresponding keyup event for the key used to submit the form. This issue has been corrected such that any tracked keyboard state will not be maintained when Guacamole navigates between any of its pages.

  • GUACAMOLE-817 - “Enter” key may repeat following login with Firefox

RDP keyboard behavior

Guacamole’s RDP support relies on dynamic keymap translation to ensure that keyboard behavior is always dictated by the user’s own keyboard layout, not the keyboard layout of the RDP server. This translation did not function correctly when Shift and Caps Lock were combined, as the remote state of Caps Lock was not properly tracked.

This has been corrected, and Guacamole will now automatically take Caps Lock into account when determining whether additional modifiers need to be pressed (and whether any pressed modifiers need to be released).

The German keymap has also been corrected to include a definition for the non-dead tilde key.

  • GUACAMOLE-518 - Shift incorrectly sent for uppercase letters while Caps Lock is active
  • GUACAMOLE-859 - Incorrect Caps Lock keysym sent to Windows via RDP
  • GUACAMOLE-917 - Key mapping for German keyboards: ~ does not work

VNC support for TLS

While Guacamole will automatically use TLS for VNC servers that require it, the proper locking callbacks required for multithreaded use of TLS were not set, resulting in unstable behavior. These callbacks are now correctly specified, and connections to VNC servers requiring TLS should function correctly.

Beware that these callbacks are only supported in newer versions of libvncclient. If the version of libvncclient installed lacks support for these callbacks, a warning will be displayed when building guacamole-server noting that TLS may not work correctly:

checking for rfbClient.LockWriteToTLS... no
checking for rfbClient.UnlockWriteToTLS... no
configure: WARNING:
      --------------------------------------------
       This version of libvncclient lacks support
       for TLS locking.  VNC connections that use
       TLS may experience instability as documented
       in GUACAMOLE-414
  • GUACAMOLE-414 - Certain VNC servers result in disconnection due to TLS errors

Rendering of balancing groups

Guacamole is intended to render empty balancing groups as if they were connections, keeping the balancing nature of those groups opaque to non-administrative users. A regression in the 0.9.10-incubating release broke this behavior, causing empty balancing groups to render as any empty non-balancing group would. This has been corrected, and empty balancing groups should now appear identical to normal connections.

  • GUACAMOLE-823 - Empty balancing group does not render as connection

SQL Server connection history query

A bug in the query used by Guacamole’s SQL Server support caused searches against the connection history to fail, instead producing the following error in the logs:

com.microsoft.sqlserver.jdbc.SQLServerException: Incorrect syntax near 'username'.

The error in the relevant SQL query has been corrected, and searches against the connection history should now work as expected.

  • GUACAMOLE-870 - Connection history query fails against SQL Server

OpenID redirection loop

In certain cases, Guacamole’s OpenID support would redirect the user back to their IDP in a loop, despite the OpenID support being correctly configured and the IDP behaving correctly. This was due to incorrect handling of the id_token parameter within the URL, causing Guacamole to behave as if the id_token were not present at all. This handling has been corrected, and users should not encounter a redirect loop if OpenID is correctly configured.

  • GUACAMOLE-805 - OpenID authentication may redirect to IDP in a loop

RADIUS challenge rendering

A bug in Guacamole’s RADIUS support resulted in the Reply-Message = portion of the RADIUS challenge being presented to the user as if it were part of the actual challenge message. This has been fixed. Only the challenge message itself should now be displayed.

RADIUS support for MS-CHAPv1 and MS-CHAPv2

Guacamole’s RADIUS support was intended to support for MS-CHAPv1 and MS-CHAPv2 authentication protocols, however this would fail if the JVM in use lacked support for the MD4 digest algorithm:

No such RADIUS algorithm: MD4 MessageDigest not available

An implementation of MD4 is now bundled with the RADIUS support, and both MS-CHAPv1 and MS-CHAPv2 should work as expected.

  • GUACAMOLE-774 - RADIUS support for MS-CHAPv1 and MS-CHAPv2 fails

Miscellaneous fixes/improvements

  • GUACAMOLE-678 - And new UriGuacamoleProperty
  • GUACAMOLE-684 - Insufficient Credentials Should Take Precedence over Invalid Credentials
  • GUACAMOLE-734 - Update logback-classic version
  • GUACAMOLE-736 - guacamole-auth-cas build fails against JDK 11
  • GUACAMOLE-740 - Spanish translation contains hard-coded version number
  • GUACAMOLE-741 - Spanish translation duplicates “APP.NAME” string
  • GUACAMOLE-749 - Filter affects only the first level of the connection permission editor tree
  • GUACAMOLE-764 - RDPDR file read/write may be truncated to 32 bits
  • GUACAMOLE-772 - Reducing image Docker size for Guacd
  • GUACAMOLE-783 - REST API responses are cached in IE 11
  • GUACAMOLE-784 - Tolerate port number within X-Forwarded-For header
  • GUACAMOLE-818 - Missing some files in the sftp file system
  • GUACAMOLE-820 - Filters containing IP addresses do not match connection properties/parameters
  • GUACAMOLE-846 - tunnel.uuid not initialized if tunnel becomes UNSTABLE
  • GUACAMOLE-861 - Drive Redirection: WINDOWS_TIME wrong calculation
  • GUACAMOLE-871 - Support cursor visiblity flag (DECTECM) in the terminal emulator
  • GUACAMOLE-884 - Avoid Image where possible without performance penalty
  • GUACAMOLE-889 - Mismatching attribute names in the LDAP schema
  • GUACAMOLE-897 - Docker support for restricting authentication to database users only
  • GUACAMOLE-955 - Untranslated error strings from extensions must not be interpreted as HTML
  • GUACAMOLE-958 - Race in guacd client termination
  • GUACAMOLE-1059 - Tolerate RDP protocol violations where possible