Apache Guacamole 1.1.0, Hacker News

Apache Guacamole 1.1.0 has not yet been released! The artifacts and release notes below are drafts for a proposed release of Apache Guacamole which has not yet occurred.

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.

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.

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 the Apache 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:

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 the deprecation / compatibility notes section 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 also necessitated dropping support for any version of FreeRDP older than 2.0.0 .

GUACAMOLE – – Sometimes session is not initialized on Full screen

GUACAMOLE – – Update RDP plugin support to 2.0. .0 releases

GUACAMOLE – – RDP NLA fails when username contains accented characters

GUACAMOLE – – Docker image missing support for RD connection broker / display update

GUACAMOLE – – Memory leak when using RDP with audio data

GUACAMOLE – – 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 the Apache Directory API . This migration also inherently fixed issues with LDAP result handling and error logging.

GUACAMOLE- 413 – Migrate from JLDAP to Apache Directory LDAP API

GUACAMOLE – LDAP error details not properly logged

GUACAMOLE – LDAP authentication fails if search result count exceeds ldap-max-search-result

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 – () – 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 dynamically adjusted based on performance measurements of the connected client.

Support for connecting to Kubernetes pods

Similar to Guacamole’s support for SSH and telnet , Guacamole can now provide terminal access to Kubernetes 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 –

– 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 –

– Finer control of the tomcat context path in Docker )

(GUACAMOLE -) – Duo in docker image

GUACAMOLE – – Add support for Docker secrets to startup.sh

(GUACAMOLE -) – Pass-through LDAP member attribute env variable in Docker start script

GUACAMOLE – – Add option to build client docker with RADIUS support

(GUACAMOLE -) – Openid support for docker

GUACAMOLE – – Docker Version ldap-user-search-filter is missing

(GUACAMOLE -) – guacd docker container can’t validate RDP certificate

GUACAMOLE – – LDAP Follow Referrals for Docker Container

(GUACAMOLE -) – Add configuration setting for logback logging verbosity level

GUACAMOLE – – 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 -) – 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 – – Allow deselection of text in terminal by single clicking

(GUACAMOLE -) – guacd ssh plugin segfault when copy text to clipboard



GUACAMOLE – – Allow selection of text in terminal while scrolling



GUACAMOLE – – Allow terminal input to be read from an inbound pipe stream



GUACAMOLE – 626 – Allow fine-grained control of terminal output redirection via pipe streams



GUACAMOLE – – 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 – – Add support for the “none” SSH authentication method

GUACAMOLE – – 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 as parameter 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 – – 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 – 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- – 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:

Your RDP server does not support Unicode events. .

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 – – 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 be manually selected within Guacamole’s preferences.

GUACAMOLE – – 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 – 713 – Connection Error when permissions assigned to user and to group user is in

GUACAMOLE – 728 – 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 -)

– Clarify ASF header within Makefile.am, etc. regarding build system output

GUACAMOLE – – Compile error: ‘strncpy’ output may be truncated copying 7 bytes from a string of length 7

(GUACAMOLE -) – Compile error: ‘avcodec_register_all’ is deprecated

GUACAMOLE – – 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 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 ). Since that time, the nest instruction has become unnecessary, and is actually no longer used in practice.

The the nest instruction is now marked as deprecate d. 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 – – Deprecate “nest ”Instruction

Miscellaneous fixes / improvements

GUACAMOLE –

– Nested socket index is not initialized

(GUACAMOLE -) – Typo in homeController loading rootConnectionGroups

GUACAMOLE – – guacamole-server README says “test-based protocol” instead of “text-based protocol”

(GUACAMOLE -) – Manual still references Glyptodon JIRA

GUACAMOLE 623 – Dead code in JavaScript formField module

(GUACAMOLE -) – Make Member attribute customizable

GUACAMOLE – Include user profile attributes within search filter

(GUACAMOLE -)

– RDP mapping for Right Ctrl incorrect

GUACAMOLE – – Add installation of libtool-bin for Debian / Ubuntu

GUACAMOLE – – Multiple fixes and improvements for the german translation

GUACAMOLE – – Grammatical error in TOTP two-factor authentication manual.

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 Guacamole protocol switched over instructions with actual stream semantics around the 0.9.0 release (back in . Since that time, the nest instruction has become unnecessary, and is actually no longer used in practice.

The 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 –

– 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 – – 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 / lib / 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=(option when running) configure , where 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-rc1

2.0.0-rc2

2.0.0-rc3

2.0.0-rc4

Current (master

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

Ubuntu . (“Bionic Beaver”)

The FreeRDP 2.0.0 packages provided by Ubuntu 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 146 (“Disco Dingo”) , and Ubuntu 191. (“Eoan Ermine”)

The FreeRDP 2.0.0 packages provided by Debian stable, Debian testing, Ubuntu 146 , and Ubuntu

Fedora , Fedora , and Fedora 234



The FreeRDP 2.0.0 packages provided by Fedora , , and are builds of commit , a snapshot of git master which is more recent than 2.0.0-rc4 (commit date is – – 125).