released: false title: 1.0.0 date: 2018-12-20 22:00:00 -0800 summary: > User groups, improved clipboard integration, TOTP (Google Authenticator), RADIUS, dead keys.
artifact-root: “https://dist.apache.org/repos/dist/dev/” checksum-root: “https://dist.apache.org/repos/dist/dev/” download-path: “guacamole/1.0.0-RC1/”
source-dist: - “source/guacamole-client-1.0.0.tar.gz” - “source/guacamole-server-1.0.0.tar.gz”
binary-dist: - “binary/guacamole-1.0.0.war” - “binary/guacamole-auth-cas-1.0.0.tar.gz” - “binary/guacamole-auth-duo-1.0.0.tar.gz” - “binary/guacamole-auth-header-1.0.0.tar.gz” - “binary/guacamole-auth-jdbc-1.0.0.tar.gz” - “binary/guacamole-auth-ldap-1.0.0.tar.gz” - “binary/guacamole-auth-openid-1.0.0.tar.gz” - “binary/guacamole-auth-quickconnect-1.0.0.tar.gz” - “binary/guacamole-auth-totp-1.0.0.tar.gz”
documentation: “Manual” : “/doc/1.0.0/gug” “guacamole-common” : “/doc/1.0.0/guacamole-common” “guacamole-common-js” : “/doc/1.0.0/guacamole-common-js” “guacamole-ext” : “/doc/1.0.0/guacamole-ext” “libguac” : “/doc/1.0.0/libguac”
The 1.0.0 release features support for user groups, improved clipboard integration leveraging the Asynchronous Clipboard API, as well as support for TOTP (Google Authenticator), RADIUS, and dead keys.
This release contains changes which break compatibility with past releases. Please see the deprecation / compatibility notes section for more information.
Guacamole now supports granting permissions based on group membership. While this has been supported to a degree for some time via LDAP and the seeAlso attribute, groups can now be defined and used within a database, with LDAP and a database combined, or within other extensions using Guacamole's extension API.
For browsers which implement the Asynchronous Clipboard API, Guacamole will now automatically synchronize the local and remote clipboards. Users will be prompted to grant clipboard access upon opening Guacamole, and Guacamole will synchronize the clipboard if access is granted.
This API has been implemented in Google Chrome since version 66, and other browsers will likely follow suit. The legacy synchronous clipboard API will continue to be used as a fallback for browsers that support clipboard access but lack support for the newer API (Internet Explorer).
Guacamole now has support for TOTP as an additional authentication factor. TOTP (Time-based One-Time Password) is a standardized algorithm used for multi-factor authentication. With this new support, Guacamole may be used with any application or authentication device which supports the TOTP standard, including the popular Google Authenticator.
RADIUS support has been added, allowing Guacamole to delegate authentication to a RADIUS service like FreeRADIUS for validating credentials, enforcing multiple authentication factors, etc.
Because the RADIUS library used by this support is licensed under the LGPL, a convenience binary for this extension is not provided. If you wish to use the RADIUS support, you will need to build guacamole-client from source and explicitly enable that part of the build with -P:
mvn package -Plgpl-extensions
Instructions for building this support are provided in the manual.
An extension is now provided which allows users to create arbitrary, temporary connections through entering a URL. This ability can be quite convenient, as users need not create new connections through the administrative interface in order to quickly access a particular machine.
Be sure you understand the security implications of providing this level of access. A Guacamole connection implicitly has network and filesystem access to the Guacamole server, thus providing this ability is equivalent to granting your users those privileges.
Multiple improvements have been made to handling keyboards, including bug fixes for various clients and support for dead keys.
Guacamole has a feature that, if a user has access to only a single connection, they will be automatically connected to it and skip the home screen. This feature has been tweaked slightly so that users with elevated access to the Guacamole Client (Administrative, ability to create connections) will be taken to the home screen and not automatically taken to the connection.
A handful of changes allow for changing how the RDP protocol handles naming of the RDP client and redirected filesystem and printers passed through via Guacmaole.
The Guacamole terminal now allows for finer control of terminal color schemes by allowing for the individual colors of a scheme to be customized.
Guacamole has supported recording sessions for quite some time, but input events were not recorded (mouse movement, mouse clicks, keyboard input, etc.). Options are now present for capturing the input events during session recording. These events are disabled by default, for security and privacy reasons, but can be enabled if desired.
SSH host key verification is now implemented and can be enabled and configured within Guacamole. In the past, Guacamole has not done any host key checking, and version 1.0.0 introduces that capability. It is important to note that this functionality is still disabled by default - if known host keys are not provided, Guacamole will continue to behave as it has in the past and will not perform host key checking. If host keys are provided, however, either in a known_hosts file within the GUACAMOLE_HOME directory on the server running guacd, or by passing in a parameter to the connection with the key of the specific server.
Support has been added for specifying any of the properties supported in the GUACAMOLE_HOME/guacamole.properties file by setting environment variables that resemble the names of the parameters. The variables are all caps and replace dashes with underscores.
guacamole/guacd and guacamole/guacamole Docker imagesMany improvments have been made to the Docker support files for building and running Guacamole within Docker containers. Most notable among these is that the default image for Guacamole Server has been changed from CentOS7 to the latest Debian stable. This allows for more recent, but still stable, versions of libraries to be used to support the various protocols and features of guacd.
A few changes address the usability of both the client and the server by adding functionality that addresses issues reported by users. Guacamoel now supports Ctrl-Alt-End as a hotkey for sending Ctrl-Alt-Delete to remote systems, which is a widely-used hotkey among remote desktop clients. The zoom level of the client can be specified more granularly, connections are easier to click on in the web interface, and guacd now provides a flag for outputting the build version.
A few updates address improving compatibility of the terminal across different connections, particularly when dealing with non-Linux operating systems. Parameters have been added for configuring the terminal type reported to the remote system, and for adjusting what code the backspace key sends. The terminal has also been adjusted to hide escape sequences and control codes that were previously outputted to the screen.
A template systemd init script has been provided and can be built with Guacamole Server to allow for xyxtem startup on distributions that have moved from init scripts to systemd.
Parameters have been added to RDP connections that allow for controlling how the RDP protocol behaves for caching bitmaps, glyphs, and off-screen data. The default behavior remains un-changed, with caching of all of these items enabled, but, for certain scenarios where it may be desirable to change this behavior the parameters are present.
Several keymaps have been added or updated for better support for keyboard input on both the Guacamole Client side and on remote systems.
The entire web interface has been translated into Spanish, including section and field headers on the web interface, on-screen keyboard, and remote system support.
An issue was corrected where the hostname or desktop name replaced the connection name on the tab or window title in the browser. The behavior has been reverted to the desired behavior, where the connection name is displayed.
Several fixes address issues with the stability of connections opened with Guacamole, either between Guacamole Client and Server, or between Server and remote systems.
To ensure comptability across CAS various implementations of the CAS protocol, the “/login” portion of the URI has been added to the code that performs the CAS login.
A couple of fixes were introduced for build issues for Guacamole server components for various libraries and compilers.
A few bugs were squashed in the guacenc program that caused error messages and erratic behavior under certain conditions.
Changes were introduced that fix IE-specific issues that either caused problems or had the potential to impact compatibility with various versions of IE.
navigator.getUserMedia()The navigator.getuserMedia() method has been deprecated, so the Guacamole Client code has been adjusted to remove reliance upon that method.
load-balance-info parameterDocumentation was corrected for the load-balance-info parameter.
The guaclog binary was accidentally included in one of the source code releases and in the git repository. It has been removed.
As noted in the compatibility section below, the Guacamole Client code has been updated such that Java 1.8 is required for both build and runtime.
The Guacamole Client has been updated such that cookies are no longer used to store the authentication information, and it is, instead, stored in the localStorage of the local browser.
Several components that were previously marked as deprecated have been removed entirely from the code base. This includes the NoAuth extension and several old properties and API endpoints.
The extension API has been updated with several changes designed to streamline functionality and make development and maintenance of extensions easier and more consistent. The error codes sent by the REST API are now derived from the GuacamoleStatus data structure rather than being separately calculated. Dependency precendence has been updated so that the dependencies bundled with the WebApp are preferred over the ones bundled with the extensions. Base implementations of UserContext and AuthenticationProvider modules have been provided and current extensions updated to make use of those, reducing the overall amount of code to maintain and making implementation of future modules more straight-forward. Finally, the RESTExceptionMapper class was replaced by the RESTExceptionWrapper class, which also makes it possible for extensions to generate their own exceptions that can be handled by the web applicatlon.
The AngularJS code was updated from the 1.3.x code to the latest available 1.x code, which was 1.6.9 at the time of the update. Several portion of the code were reworked for compatibility with this, including significant portions of the HTTP request code and how exceptions are handled within those requests.
Changes were introduced to improve how the tunnel is handled between the Java and JavaScript portions of the code, including allowing custom headers to be configured for the tunnels and insuring that the tunnels are not closed more than once.
As of 1.0.0, the following changes have been made which affect compatibility with past releases:
Most of the Java components of the Guacamole Client have been updated to require Java 1.8 for both compile and runtime. The decision was made based on the fact that many support libraries are moving toward requiring later versions of Java, that Java 1.8 has been out and stable for many years, and that Java 1.6 and 1.7 have not been updated in several years. The only exception to this is the base API, the guacamole-common code, which continues to maintain compatibility with Java 1.6.
Significant changes have been made to the schemas for all of the JDBC authentication modules (MySQL, PostgreSQL, and SQL Server). Among those changes are the addition of support for user groups and the changes required to support those within the database modules (including the “entity” as an overall type for both users and groups).
Users of any of the database authentication modules will need to run the upgrade-pre-1.0.0.sql script specific to their chosen database as part of the move from earlier versions of Guacamole to 1.0.0. More thorough instructions for this process can be found in the [JDBC Authentcation] (http://guacamole.apache.org/doc/gug/jdbc-auth.html) documentation.
The hostname/address of users logged by the database authentication backend is now determined entirely by the servlet container. The database authentication will not manually parse the X-Forwarded-For header, and will instead rely on the servlet container to perform any such parsing.
If proxying Guacamole, the configuration of your servlet container should be updated to handle the headers set by your proxy. For Apache Tomcat, this is accomplished with a RemoteIpValve in your server.xml.
Logging of hostnames/addresses by Guacamole during the authentication process (as would be parsed by tools like fail2ban) is unchanged, however you will need to update the pattern if RemoteIpValve or similar are used, as the address of interest will likely be the rightmost address. If the user is not behind any additional, untrusted proxies, the address of interest will be the only address.
The NoAuth extension has been deprecated for a couple of major releases of Guacamole, and has been entirely removed from the code base in this release, both source and binary releases. If you are currently using this extension you will need to move to a different authentication extension during the upgrade process, as the NoAuth extension will no longer work.
The following properties have been deprecated for quite some time, and are completely removed in the 1.0.0 release. Prior to the 1.0.0 release a warning would be logged regarding the deprecation of these properties; as of this release they will be completely ignored if present in the guacamole.properties file.
basic-user-mappingmysql-disallow-simultaneous-connectionsmysql-disallow-duplicate-connectionspostgresql-disallow-simultaneous-connectionspostgresql-disallow-duplicate-connectionsAs noted above, one of the major changes in this version of the Guacamole Client is the addition of support for user groups across all authentication modules. This includes changes in the core Extension API (guacamole-ext) that supports the user groups and allows for those groups to be processed across various stacked modules and implemented in newer modules. The AbstractUserGroup, DelegatingUserGroup, SimpleUserGroup, and UserGroup classes have been added to the Extension API to be implemented within various extension modules.
The 1.0.0 version of the Guacamole Client introduces several classes that allow extension modules to decorate other modules, providing the ability to modules to build on top of other modules and store data in other modules. This was key in allowing the TOTP module to function by allowing it to store arbitrary data in the databases provided by the JDBC module, and paves the way for future expansion on how modules leverage data and functionality from other modules.
GuacamoleHome and GuacamoleProperties classesTODO
SimpleUserDirectory, SimpleConnectionDirectory, and SimpleConnectionGroupDirectory classesThe SimpleUserDirectory, SimpleConnectionDirectory, and SimpleConnectionGroupDirectory classes have been deprecated in favor of the SimpleDirectory class. These classes can still be used, but will result in deprecation warnings, and will be removed in a future release.
SimpleUser convenience constructorsTODO
guac_protocol_send_mouse() now requires additional parametersTODO
GUAC_INSTRUCTION_MAX_ELEMENTS macro definition changedTODO (Affects size of guac_parser as well as any code referencing that macro)
GuacamoleSession classTODO
GuacamoleHTTPTunnelServler.sendError()TODO
GuacamoleClient.setClipboard() functionTODO
Guacamole.Tunnel.State.UNSTABLE stateIn order to support changes to detecting and handling network problems within the Guacamole connections, another tunnel state, UNSTABLE, has been added. Custom code that leverages the Guacamole.Tunnel.State type may need to be refactored to take this additional state into account if it does not currently ignore unknown states, or the code needs to handle unstable connections.
TODO (New use of internal tunnel opcode for connection stability “ping” will affect third-party reimplementations of Guacamole's WebSocket tunnel)