Apache Guacamole 1.1.0

Release documentation

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

Release notes

The 1.1.0 release features support for dynamic image quality and for connecting directly to the terminals of Kubernetes pods. Issues with user group support discovered following the 1.0.0 release have been fixed, issues with LDAP support have been resolved through migrating to theApache Directory API, and issues with RDP support have been resolved through migrating to FreeRDP 2.0.0.

The 1.1.0 release is compatible with 1.0.0 components.Version numbering from 1.0.0 onward is intended to indicate backward compatibility, with changes to the major (leftmost) version number being made only when compatibility with previous releases has been broken. You should upgrade 1.0.0 components to 1.1.0 when possible, however things should continue to work correctly in the interim:

• Extensions written for 1.0.0 can be used by 1.1.0.
• Components written for the version of the Guacamole protocol used by 1.0.0 can be used with components of the 1.1.0 release.

Regardless of inter-component compatibility, there are changes in 1.1.0 which may affect downstream packagers of guacamole-server and downstream users of libguac or the Guacamole protocol . Please see thedeprecation / compatibility notessection for more information.

New features and improvements

Migration to FreeRDP 2.0.0

Guacamole has historically supported FreeRDP’s 1.0 and 1.1 branches, as well as several pre-release 1.2.x tags made over time. With these versions of FreeRDP no longer being actively maintained, and with support for these versions being removed from most Linux distributions, Guacamole’s RDP support has been migrated to FreeRDP 2.0.0.

This migration inherently fixed several issues with RDP support, but alsonecessitated dropping support for any version of FreeRDP older than 2.0.0.

• GUACAMOLE-125 - Sometimes session is not initialised on Full screen
• GUACAMOLE-249 - Update RDP plugin support to 2.0.0 releases
• GUACAMOLE-413 - RDP NLA fails when username contains accented characters
• GUACAMOLE-707 - Docker image missing support for RD connection broker / display update
• GUACAMOLE-847 - Memory leak when using RDP with audio data
• GUACAMOLE-900 - RDPDR fails after resizing when “resize-method” is “reconnect”

Migration to the Apache Directory API

Older versions of Guacamole used the JLDAP library to provide LDAP support. This library is unmaintained, and Guacamole’s LDAP support has now migrated to theApache Directory API. This migration also inherently fixed issues with LDAP result handling and error logging.

• GUACAMOLE-234 - Migrate from JLDAP to Apache Directory LDAP API
• GUACAMOLE-309 - LDAP error details not properly logged
• GUACAMOLE-717 - LDAP authentication fails if search result count exceeds ldap-max-search-result

Accessing active sessions without share links

When using an extension which supports active connection tracking, such as the various supported databases , users can join active connections to which they have access without having to generate share links, even if those active connections were established from a different machine. Non-administrative users can join their own connections, while administrative users can join any active connection.

• GUACAMOLE-360 - Autoreconnect only most recent session

Dynamic image quality adjustment

Since the 0.9.9 release, Guacamole has automatically used JPEG or WebP compression when heuristics detect that doing so is appropriate. The quality of JPEG and WebP compression is now also adjusted dynamically based on performance measurements of the connected client.

• GUACAMOLE-632 - Dynamically adjust JPEG/WebP quality

Support for connecting to Kubernetes pods

Similar to Guacamole’s support forSSH andtelnet, Guacamole can now provide terminal access toKubernetes pods using the same mechanism as kubectl attach . This allows Guacamole to be used to interact with Kubernetes pods without requiring that those pods host an SSH or telnet service.

• GUACAMOLE-623 - Add support for attaching to Kubernetes pods

Improvements to Docker images

Additional configuration options are now available for the Docker images, including additional authentication extensions and the ability to change the web application’s log level. An issue which prevented validation of RDP certificates by the guacd image has been corrected, and environment variables have been added for all LDAP properties that were previously missing corresponding variables.

• GUACAMOLE-146 - Finer control of the tomcat context path in Docker
• GUACAMOLE-271 - Duo in docker image
• GUACAMOLE-626 - Add support for Docker secrets to startup.sh
• GUACAMOLE-674 - Pass-through LDAP member attribute env variable in Docker start script
• GUACAMOLE-682 - Add option to build client docker with RADIUS support
• GUACAMOLE-683 - Openid support for docker
• GUACAMOLE-688 - Docker Version ldap-user-search-filter is missing
• GUACAMOLE-694 - guacd docker container can’t validate RDP certificate
• GUACAMOLE-704 - LDAP Follow Referrals for Docker Container
• GUACAMOLE-713 - Add configuration setting for logback logging verbosity level
• GUACAMOLE-716 - Add all LDAP properties to Docker start script

Changing terminal color scheme of active connections

The parameters of Guacamole connections generally can only be changed prior to establishing the connection. This restriction continues to hold true for sensitive parameters, but has been relaxed for parameters which control the appearance of Guacamole’s terminal emulator.

The Guacamole protocol has been updated to define a means of temporarily applying connection parameter changes to an active connection, while restricting the parameters that can be changed such that the nature of the connection is still controlled by the administrator. These changes to the protocol are leveraged by the Guacamole webapp to present a terminal color scheme editor within the Guacamole menu that can be used to change the terminal appearance while the connection is active.

• GUACAMOLE-629 - Stream protocol argument values
• GUACAMOLE-630 - Allow terminal color scheme to be changed while connection is running

Terminal emulator improvements

The general behavior of Guacamole’s terminal emulator has been improved to more closely match the behavior of native terminal emulators with respect to how text is selected and deselected, and the maximum scrollback buffer size can now be configured.

For the sake of automating interaction with terminal sessions, the behavior of terminal output that has been redirected to pipe streams can now be forced to flush immediately and/or to additionally render within the terminal, and user input can be supplied using a pipe stream , independent of key events.

• GUACAMOLE-191 - Allow deselection of text in terminal by single clicking
• GUACAMOLE-441 - guacd ssh plugin segfault when copy text to clipboard
• GUACAMOLE-573 - Allow selection of text in terminal while scrolling
• GUACAMOLE-574 - Allow terminal input to be read from an inbound pipe stream
• GUACAMOLE-597 - Allow fine-grained control of terminal output redirection via pipe streams
• GUACAMOLE-610 - Allow scrollback buffer size to be configured

Improvements to SSH and telnet support

The “none” authentication method for SSH is now supported, as may be required by some SSH servers, and the locale of the SSH session can now be set via the LANG environment variable. Handling of SSH and telnet connection errors is also improved, allowing balancing connection groups containing SSH and telnet connections to transparently fail over without user-visible errors.

• GUACAMOLE-622 - Allow webapp-side handling of connection errors for SSH and telnet
• GUACAMOLE-547 - Add support for the “none” SSH authentication method
• GUACAMOLE-649 - Allow SSH locale to be explicitly set

LDAP and CAS attributes as parameter tokens

Attributes associated with LDAP and CAS user accounts can now be passed through asparameter tokens. The names of these tokens are derived from the names of the attributes and can be used to alter the behavior of a connection dynamically depending on which user is connecting.

• GUACAMOLE-524 - Allow LDAP attributes to be used as token
• GUACAMOLE-579 - Allow CAS attributes to be used as tokens

Improved authentication backend error handling

In past versions of Guacamole, a broken authentication configuration would typically result in the Guacamole interface not rendering at all, resulting in a blank, white page. Guacamole will now display a generic error message if authentication is impossible due to a server failure, and supports falling through to other extensions as backups when explicitly configured to do so.

• GUACAMOLE-598 - Fail cleanly if authentication backend is down / misconfigured
• GUACAMOLE-611 - Selectively fall through to other extensions when authentication fails

Timezone redirection for SSH and RDP

Automatic pass-through of the user’s timezone is now supported for both SSH and RDP. In the case of SSH, which doesn’t natively support timezone redirection, this is accomplished through remotely setting the TZ environment variable.

• GUACAMOLE-422 - Timezone Redirection

Internationalization

Swiss-German and Danish keymaps for RDP

Keymaps have been added to better support RDP servers which use the Swiss-German or Danish 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.

• GUACAMOLE-354 - Add Swiss-German keymap for RDP
• GUACAMOLE-712 - Add Danish keymap

Simplified Chinese translation of web interface

The web interface of Guacamole has been translated into Simplified Chinese. Simplified Chinese will now automatically be selected if accessing Guacamole from a browser whose default language is set to Chinese. The language can also bemanually selected within Guacamole’s preferences.

• GUACAMOLE-569 - Add translation for Simplified Chinese

Bug fixes

Group permission behavior

Issues with the new support for user groups were identified following the 1.0.0 release which resulted in permissions not taking effect if granted via user groups from different authentication extensions. These issues have now been fixed. User group permissions should be inherited as expected, regardless of whether user group membership is dictated by a different extension than the permissions granted to that group.

• GUACAMOLE-696 - Apply database groups if authenticated user matches database user
• GUACAMOLE-697 - Connection Error when permissions assigned to user and to group user is in
• GUACAMOLE-715 - Permission management based on LDAP groups not working as documented

Build issues

The guacamole-server build for the 1.0.0 release and older would fail with newer compilers due to additional warnings and with newer versions of FFmpeg due to functions becoming deprecated. These issues have been corrected, and the guacamole-server build should now succeed on affected platforms.

• GUACAMOLE-353 - Clarify ASF header within Makefile.am, etc. regarding build system output
• GUACAMOLE-637 - Compile error: ‘strncpy’ output may be truncated copying 7 bytes from a string of length 7
• GUACAMOLE-638 - Compile error: ‘avcodec_register_all’ is deprecated
• GUACAMOLE-662 - Failing unit tests for guacamole-server not triggering build failure

Platform / API changes

Deprecation of the nest instruction

The nest instruction was created in the early days of the Guacamole protocol as a means of splitting up large instructions. At the time, this was necessary because images and audio were transmitted within instructions that required the entire block of data to be available at once. The nest instruction thus provided a means of streaming data for instructions that otherwise did not support it.

The Guacamole protocol switched over to instructions with actual stream semantics around the 0.9.0 release (back in 2014). Since that time, the nest instruction has become unnecessary, and is actually no longer used in practice.

The nest instruction is now marked as deprecated. It is still supported by the JavaScript Guacamole client, but support can be expected to be removed in a future release. Downstream usages of the Guacamole protocol which still use the nest instruction should cease using it.

• GUACAMOLE-661 - Deprecate “nest” instruction

Miscellaneous fixes/improvements

• GUACAMOLE-510 - Nested socket index is not initialized
• GUACAMOLE-571 - Typo in homeController loading rootConnectionGroups
• GUACAMOLE-572 - guacamole-server README says “test-based protocol” instead of “text-based protocol”
• GUACAMOLE-582 - Manual still references Glyptodon JIRA
• GUACAMOLE-585 - Dead code in JavaScript formField module
• GUACAMOLE-593 - Make Member attribute customizable
• GUACAMOLE-624 - Include user profile attributes within search filter
• GUACAMOLE-628 - RDP mapping for Right Ctrl incorrect
• GUACAMOLE-639 - Add installation of libtool-bin for Debian/Ubuntu
• GUACAMOLE-699 - Multiple fixes and improvements for the german translation
• GUACAMOLE-718 - Grammatical error in TOTP two-factor authentication manual.

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

Guacamole protocol changes

Deprecation of the nest instruction

The nest instruction was created in the early days of the Guacamole protocol as a means of splitting up large instructions. At the time, this was necessary because images and audio were transmitted within instructions that required the entire block of data to be available at once. The nest instruction thus provided a means of streaming data for instructions that otherwise did not support it.

The Guacamole protocol switched over instructions with actual stream semantics around the 0.9.0 release (back in 2014). Since that time, the nest instruction has become unnecessary, and is actually no longer used in practice.

The nest instruction is now marked as deprecated. It is still supported by the JavaScript Guacamole client, but support can be expected to be removed in a future release. Downstream usages of the Guacamole protocol which still use the nest instruction should cease using it.

• GUACAMOLE-661 - Deprecate “nest” instruction

Changes to the Guacamole protocol handshake

The Guacamole protocol handshake has been expanded with a new timezone instruction to allow the Guacamole client to forward the user’s local timezone through to the remote desktop. As the addition of a new handshake instruction would normally make the new version of the protocol incompatible with older versions, the handshake has also been modified to allow the Guacamole protocol version to be negotiated, and to allow flexibility in the overall handshake: handshake-specific instructions may now be sent in any order or omitted entirely.

As these changes were made such that compatibility is preserved, downstream usages of the Guacamole protocol should continue to work, however such usages should be brought up to date when possible.

• GUACAMOLE-422 - Timezone Redirection
• GUACAMOLE-629 - Stream protocol argument values

Changes to guacamole-server build process / dependencies

Install location for FreeRDP plugins is now detected by configure

The configure script will now automatically determine the correct install location for FreeRDP plugins based on the location that the FreeRDP libraries are installed. This location will be printed at the end of the summary displayed when configure has finished running:

...

   FreeRDP plugins: /usr/lib64/freerdp2
   Init scripts: no
   Systemd units: no

Type "make" to compile guacamole-server.

If the install location of FreeRDP plugins should not be automatically detected, this behavior can be overridden by specifying the --with-freerdp-plugins-dir=<path> option when running configure , where <path> is the path to the desired install location.

FreeRDP 2.0.0 requires a writable home directory

The initialization process of the FreeRDP 2.0.0 library requires that the current user have a valid, writable home directory. Attempts to connect using RDP will fail if this is not the case, as FreeRDP will refuse to complete initialization.

For Guacamole’s RDP support, this means that the user running guacd must have a valid, writable home directory, and that RDP connections which worked as expected in past Guacamole releases may begin failing if the user running guacd does not have a valid home directory.

Sanity checks have been added to Guacamole’s RDP support which will log warnings if these conditions are not met.

FreeRDP 2.0.0 or later is now required for RDP support

With the addition of support for FreeRDP 2.0.0, support for older releases of FreeRDP has been dropped . The extent of the API differences with older versions of FreeRDP is simply too great to maintain. Downstream builds of guacamole-server which are intended to include RDP support will need to be updated to build against FreeRDP 2.0.0.

Beware that “FreeRDP 2.0.0” is currently a misnomer.All versions of FreeRDP 2.0.0 as of this writing are actually release candidates (2.0.0-rc0, 2.0.0-rc4, etc.) or git snapshots. There are incompatible API differences and incompatible internal behavior differences between these release candidates and between git snapshots, despite each having the same version number and soname . The FreeRDP 2.0.0 packages provided by various distributions may not actually provide the same API, and library functions with the same API may not actually behave in a compatible manner, even though they otherwise appear identical to users of that distribution.

The guacamole-server build has been tested against builds of FreeRDP from source at:

2.0.0-rc0
2.0.0-rc1
2.0.0-rc2
2.0.0-rc3
2.0.0-rc4
master

The guacamole-server build has also been tested against the builds of FreeRDP packaged by the following specific Linux distributions:

• Ubuntu 18.04 (“Bionic Beaver”)

  The FreeRDP 2.0.0 packages provided by Ubuntu 18.04 are builds of 2.0.0-rc0 .

• CentOS 7

  The FreeRDP 2.0.0 packages provided by CentOS 7 are builds of 2.0.0-rc4 .

• Debian stable (“Buster”), Debian testing (“Bullseye”) , Ubuntu 19.04 (“Disco Dingo”) , and Ubuntu 19.10 (“Eoan Ermine”)

  The FreeRDP 2.0.0 packages provided by Debian stable, Debian testing, Ubuntu 19.04, and Ubuntu 19.10 are builds of commit 2693389 , a snapshot of git master which is more recent than 2.0.0-rc4 (commit date is 2019-02-01).

• Fedora 29, Fedora 30 , and Fedora 31

  The FreeRDP 2.0.0 packages provided by Fedora 29, 30, and 31 are builds of commit 6015229 , a snapshot of git master which is more recent than 2.0.0-rc4 (commit date is 2019-08-12).

It is intended that RDP support will resume tracking and supporting FreeRDP master , however it is possible that the frequency of API changes will require support to again be restricted to releases and git tags.

• GUACAMOLE-249 - Update RDP plugin support to 2.0.0 releases

libguac API changes

New members added to guac_user and guac_user_info structures

New members have been added to guac_user and guac_user_info which affect the size of these structures. 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-422 - Timezone Redirection
• GUACAMOLE-629 - Stream protocol argument values