Apache Guacamole 0.9.13-incubating is an archived release, and was originally released on 2017-07-30. The latest release of Apache Guacamole is 1.5.4.
Apache Guacamole 0.9.13-incubating
Release documentation
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.
guacamole-client-0.9.13-incubating.tar.gz | [ MD5 ] | [ SHA ] | [ PGP ] |
guacamole-server-0.9.13-incubating.tar.gz | [ MD5 ] | [ SHA ] | [ PGP ] |
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.
guacamole-0.9.13-incubating.war | [ MD5 ] | [ SHA ] | [ PGP ] |
guacamole-auth-cas-0.9.13-incubating.tar.gz | [ MD5 ] | [ SHA ] | [ PGP ] |
guacamole-auth-duo-0.9.13-incubating.tar.gz | [ MD5 ] | [ SHA ] | [ PGP ] |
guacamole-auth-jdbc-0.9.13-incubating.tar.gz | [ MD5 ] | [ SHA ] | [ PGP ] |
guacamole-auth-header-0.9.13-incubating.tar.gz | [ MD5 ] | [ SHA ] | [ PGP ] |
guacamole-auth-ldap-0.9.13-incubating.tar.gz | [ MD5 ] | [ SHA ] | [ PGP ] |
guacamole-auth-noauth-0.9.13-incubating.tar.gz | [ MD5 ] | [ SHA ] | [ PGP ] |
Release notes
The 0.9.13-incubating release features new support for CAS single sign-on, automatic failover to connections within the same connection group, and fixes for issues in all supported protocols. The JavaScript API has also been extended to provide for in-browser playback of screen recordings, and the extension API now allows custom REST services to be defined.
This release contains changes which break compatibility with past releases. Please see the deprecation / compatibility notes section for more information.
Support for CAS single sign-on
Central Authentication Service (CAS), is a single sign-on solution commonly used by universities to unify authentication across various web applications which are otherwise independent. The newly-implemented guacamole-auth-cas extension allows Guacamole to delegate authentication to CAS, relying on CAS to determine the identity and validity of each user.
Note that this new extension only deals with determining the identity of users that have authenticated with CAS, and redirecting unauthenticated users to the CAS system to authenticate. The details of the connections available to each user must be provided via another extension, such as the database authentication.
- GUACAMOLE-204 - Support CAS Single Sign On
Correction to Duo documentation
The documentation for Guacamole’s Duo extension previously stated that Duo’s “Auth API” was required. This is incorrect; though the “Auth API” will work, Guacamole actually uses the “Web SDK”. This is particularly important, as Duo recently ceased offering the “Auth API” for free, whereas the “Web SDK” is still available for free accounts.
- GUACAMOLE-219 - Duo documentation should point to “Web SDK”, not “Auth API”
In-browser playback of screen recordings
Guacamole’s screen recordings are actually copies of the same exact data which would be fed to the Guacamole client over the course of the connection, thus the JavaScript API already had much of what was necessary to support in-browser playback of recordings. The main things lacking were a means of reading a Guacamole protocol stream from a static resource, and a means of seeking backward or forward within that stream.
This missing API-level functionality is now provided through the new
Guacamole.StaticHTTPTunnel
and Guacamole.SessionRecording
objects respectively,
and an example demonstrating this use, guacamole-playback-example, is provided within the guacamole-client source.
- GUACAMOLE-250 - Implement support for in-browser playback of screen recordings
NoAuth now deprecated
Over the years since its introduction, the NoAuth extension has grown to become a consistent source of issues for both users and the Guacamole development community, and simply using the extension has become de facto bad practice. As such, the NoAuth extension is now deprecated.
To ease migration away from its use, the extension remains part of the Guacamole source and a convenience binary of the extension is provided with this release, but its continued use is not recommended and it will eventually be removed. Integrations of Guacamole should instead use the extension API, or the core Guacamole API for absolute low-level control.
- GUACAMOLE-256 - Deprecate the NoAuth extension
SSH/telnet support for 256-color console codes
Guacamole has historically supported only the subset of console codes implemented by the Linux kernel’s built-in terminal emulator. As part of a larger, ongoing effort to achieve compatibility with xterm, support for xterm’s 256-color console codes has been added, along with support for the console code which changes the window title.
- GUACAMOLE-265 - Support OSC 0 for changing SSH/telnet window title
- GUACAMOLE-278 - Add support for xterm’s 256-color control codes
- GUACAMOLE-280 - Add support for the “faint” SGR flag
Automatic failover for connections in groups
In past releases, the database authentication would handle connection attempts to connection groups by selecting the least-used connection, but would otherwise only make one connection attempt. If that connection attempt fails due to an error within the remote desktop, the user must manually reconnect (or wait 15 seconds for the automatic reconnect).
Connection groups provided via the database authentication will now automatically and transparently switch to the next available connection in the group for remote desktop errors that occur early in the connection. If graphical updates are sent prior to the error, automatic failover will not occur.
This functionality has also been added at the Java API level. Extensions and
applications leveraging the Guacamole API can use the
FailoverGuacamoleSocket
class to automatically detect
and handle upstream (remote desktop) errors during the connection process.
- GUACAMOLE-208 - Expand status codes to represent common remote desktop states
- GUACAMOLE-267 - Support health checks for connections
Fixes for all supported protocols
Several bugs with each supported protocol have been addressed. Most significantly, issues with audio stream stability for recent versions of Windows, and transfer of large files over RDP, the behavior of the “Alt” key for SSH and telnet, and VNC connection stability have all been fixed.
- GUACAMOLE-194 - Double free() in guac_common_ssh_destroy_user()
- GUACAMOLE-205 - libguac_common_ssh build fails with OpenSSL 1.1
- GUACAMOLE-206 - Alt key combinations broken in SSH and telnet
- GUACAMOLE-218 - Audio stops playing on Windows Server 2016
- GUACAMOLE-222 - SFTP file handles not closed for downloads
- GUACAMOLE-257 - Segfault in on VNC/SSH file upload if SFTP is disabled
- GUACAMOLE-262 - Cannot connect to ESXi 6.5 VNC server
- GUACAMOLE-268 - RDPDR file size may be truncated to 32 bits
- GUACAMOLE-282 - Common surface transfer functions incorrect with respect to alpha channel
- GUACAMOLE-306 - VNC may segfault during the connection process
Defining REST services via extensions
Extensions can now define arbitrary REST services by implementing the new
getResource()
function at either the
AuthenticationProvider
UserContext
levels, returning objects annotated with JAX-RS (JSR-311) annotations.
REST resources exposed at the UserContext
level are inherently tied to the
user’s session and thus require authentication, while resources exposed at the
AuthenticationProvider
level do not.
- GUACAMOLE-289 - Add support for declaring REST services within extensions
User profile attributes
The database authentication now defines additional, arbitrary attributes for users which, if specified, are rendered within Guacamole’s user menu. These attributes are optional - if omitted, the user menu renders as in previous releases.
The additional attributes are standardized at the API level on the
User.Attribute
object, and thus can be leveraged by any extension, producing the same effect.
- GUACAMOLE-292 - Add support for user profiles
Support for filtering LDAP users
Guacamole’s LDAP support now provides an additional ldap-user-search-filter
property which, if specified, reduces the users that can log into Guacamole or
are displayed to administrators within the user management interface (when
combining LDAP with a MySQL or PostgreSQL database).
Note that this filter only affects Guacamole logins if Guacamole has been
configured to search for users prior to binding (with the ldap-search-bind-dn
property). If a search DN is not being used, Guacamole derives each user’s DN
directly, and thus will not apply the search filter to login attempts.
- GUACAMOLE-101 - Allow arbitrary filtering of LDAP users
- GUACAMOLE-244 - Allow configuration of LDAP alias dereferencing
Overriding guacd on a per-connection basis
The connection to guacd is normally defined globally within
guacamole.properties
, but this is insufficient for deployments involving
multiple distinct guacd instances or multiple implementations of the Guacamole
protocol.
For cases where different instances of guacd may be spread out across the network of remote desktop servers, or where other applications/drivers may implement their own internal version of guacd (such as the work-in-progress X.Org driver), Guacamole now supports defining/overriding the guacd hostname, port, and encryption method on a per-connection basis.
- GUACAMOLE-189 - Add support for per-connection guacd
Miscellaneous fixes/improvements
This latest release of Guacamole also addresses several minor JavaScript
issues, addresses potential disconnects due to system clocks which are not
monotonic (can run backwards), and fixes the Docker image sanity checks such
that database-specific environment variables need not be specified if a custom
GUACAMOLE_HOME
is being used.
- GUACAMOLE-40 - Support TS gateway connections to RDP
- GUACAMOLE-223 - Locking callbacks not set for guacd+SSL
- GUACAMOLE-229 - Intervals when polling xmlhttprequests are not always cleared
- GUACAMOLE-239 - Disconnects due to ‘backwards’ running time
- GUACAMOLE-252 - Display jumps to top in MS Edge when Guacamole menu is opened
- GUACAMOLE-259 - Log metrics for gauging user experience
- GUACAMOLE-281 - GUACAMOLE_HOME not taken into account during Docker image sanity checks
- GUACAMOLE-294 - Incorrectly positioned bracket in
guacTouchDrag.js
. - GUACAMOLE-295 - In Parser.js, the
length
variable is incorrectly checked for equality against NaN. - GUACAMOLE-301 - Login prompt not cleared when visiting unrestricted page
Deprecation / Compatibility notes
As of 0.9.13-incubating, the following changes have been made which affect compatibility with past releases:
Database schema changes
The MySQL and PostgreSQL schemas have changed, adding columns to
guacamole_connection
(for defining the connection to guacd service
implementing the Guacamole protocol) and to guacamole_user
(for defining
optional and arbitrary profile information).
Users of the database authentication will need to run the
upgrade-pre-0.9.13.sql
script specific to their chosen database.
Deprecation of the NoAuth extension
The NoAuth extension is now deprecated. The extension remains part of the Guacamole source and a convenience binary of the extension is provided with this release, but its continued use is not recommended and it will eventually be removed entirely.
Integrations of Guacamole should instead use the extension API, or the core Guacamole API for absolute low-level control.
Extension API changes
Both the
AuthenticationProvider
and
UserContext
interfaces now define a getResource()
function. If implemented, the returned
object will be served as a REST resource and must be annotated with JAX-RS
(JSR-311) annotations. Because this new function is defined at the interface
level, implementations of these interfaces will now need to define this
function:
If your extension does not need to expose its own REST resources, the function
can simply return null
, and no such resources will be exposed:
@Override
public Object getResource() {
// No associated REST resource
return null;
}