Apache Guacamole 1.1.0 is an archived release, and was originally released on 2020-01-29. The latest release of Apache Guacamole is 1.5.5.
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.
| Filename | Signatures / Hashes |
|---|---|
| guacamole-client-1.1.0.tar.gz | PGP SHA-256 |
| guacamole-server-1.1.0.tar.gz | PGP SHA-256 |
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
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.
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.
nest instructionThe 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.
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:
As of 1.1.0, the following changes have been made which affect compatibility with past releases:
nest instructionThe 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.
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.
configureThe 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.
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.
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-rc02.0.0-rc12.0.0-rc22.0.0-rc32.0.0-rc4masterThe 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.
guac_user and guac_user_info structuresNew 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.