You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@guacamole.apache.org by vn...@apache.org on 2019/01/05 03:07:10 UTC
[05/10] guacamole-website git commit: Clarify wording of draft 1.0.0
release notes, fix typos.
Clarify wording of draft 1.0.0 release notes, fix typos.
Project: http://git-wip-us.apache.org/repos/asf/guacamole-website/repo
Commit: http://git-wip-us.apache.org/repos/asf/guacamole-website/commit/6f785e12
Tree: http://git-wip-us.apache.org/repos/asf/guacamole-website/tree/6f785e12
Diff: http://git-wip-us.apache.org/repos/asf/guacamole-website/diff/6f785e12
Branch: refs/heads/master
Commit: 6f785e121b845dc9482e67f6bc8e0d9894c4bccc
Parents: b06f4f8
Author: Michael Jumper <mj...@apache.org>
Authored: Wed Jan 2 01:02:50 2019 -0800
Committer: Michael Jumper <mj...@apache.org>
Committed: Fri Jan 4 11:57:28 2019 -0800
----------------------------------------------------------------------
_releases/1.0.0.md | 405 ++++++++++++++++++++++++++++++------------------
1 file changed, 250 insertions(+), 155 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/guacamole-website/blob/6f785e12/_releases/1.0.0.md
----------------------------------------------------------------------
diff --git a/_releases/1.0.0.md b/_releases/1.0.0.md
index b7c90f6..08f33cc 100644
--- a/_releases/1.0.0.md
+++ b/_releases/1.0.0.md
@@ -119,8 +119,8 @@ providing this ability is equivalent to granting your users those privileges.
### Improved keyboard handling / Support for dead keys
-Multiple improvements have been made to handling keyboards, including bug fixes
-for various clients and support for dead keys.
+Multiple improvements have been made to keyboard handling, including bug fixes
+for Mac and iOS and support for dead keys.
* [GUACAMOLE-161](https://issues.apache.org/jira/browse/GUACAMOLE-161) - Handle CapsLock events properly on Mac OS
* [GUACAMOLE-232](https://issues.apache.org/jira/browse/GUACAMOLE-232) - Stuck keys iPad/Bluetooth keyboard (Return/Backspace/Space)
@@ -129,19 +129,19 @@ for various clients and support for dead keys.
### Automatic connection behavior
-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.
+Guacamole will automatically connect upon login for users that have access to
+only a single connection, skipping the home screen. This feature has been
+tweaked slightly so that it applies only to non-administrative users. Users
+with access to Guacamole's administrative interface will now see the home
+screen and not automatically connected.
* [GUACAMOLE-508](https://issues.apache.org/jira/browse/GUACAMOLE-508) - Automatically connect only if user lacks access to settings
### Support for renaming RDP drive and printer
-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.
+By default, the filesystem and printer made available within RDP connections
+are named "Guacamole Filesystem" and "Guacamole Printer" respectively. Support
+has been added to override these names.
* [GUACAMOLE-445](https://issues.apache.org/jira/browse/GUACAMOLE-445) - Allow RDP printer name to be configured
* [GUACAMOLE-446](https://issues.apache.org/jira/browse/GUACAMOLE-446) - Allow RDP drive name to be configured
@@ -156,25 +156,36 @@ schemes by allowing for the individual colors of a scheme to be customized.
### Optional recording of input events
-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.
+Guacamole has supported session recording for quite some time, but did not
+record input events (mouse movement/clicks, keyboard input, etc.). This meant
+that the mouse cursor could not be rendered in recording playback (as the mouse
+position information from mouse events was not included) and session recording
+could not be used for some auditing purposes that required logging of key
+events.
+
+Options are now available for capturing input events during session
+recording. For security and privacy reasons, only mouse events are captured
+within session recordings by default. Capture of keyboard events can be
+manually enabled, and capture of mouse events can be manually disabled.
* [GUACAMOLE-313](https://issues.apache.org/jira/browse/GUACAMOLE-313) - Allow input events within session recording
### SSH host key verification
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.
+within Guacamole. In the past, Guacamole has not performed any SSH host key
+checking, and version 1.0.0 introduces this capability.
+
+For compatibility with past releases, 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 allow the connection to succeed, though a
+warning will be logged.
+
+If host keys *are* provided (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), host checking
+will be strictly enforced and the connection will only succeed if the host
+matches.
* [GUACAMOLE-527](https://issues.apache.org/jira/browse/GUACAMOLE-527) - Add parameter for specifying known SSH/SFTP server host key
@@ -185,20 +196,23 @@ specific server.
### Support for configuring Guacamole with environment variables
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_HOME/guacamole.properties` file by setting environment variables
+that correspond to those properties. The name of the environment variable for
+any particular property is the name of the property in uppercase with all
+dashes replaced with underscores.
+
+For security reasons, the `enable-environment-properties` property must be set
+to `true` for reading of properties from environment variables to be enabled.
* [GUACAMOLE-464](https://issues.apache.org/jira/browse/GUACAMOLE-464) - Extension configuration properties from the OS environment
### Improvements to `guacamole/guacd` and `guacamole/guacamole` Docker images
-Many 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.
+Many improvements have been made to the Docker support files for building and
+running Guacamole within Docker containers. Most notable among these is that
+the base for the guacd Docker image has been changed from CentOS 7 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.
* [GUACAMOLE-42](https://issues.apache.org/jira/browse/GUACAMOLE-42) - Support setting guacd log level on Docker container
* [GUACAMOLE-407](https://issues.apache.org/jira/browse/GUACAMOLE-407) - Update guacd Docker image to build against more recent dependencies
@@ -207,13 +221,12 @@ of guacd.
### General usability improvements
-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.
+Improvements to usability have been made in order to address issues reported by
+users. Guacamole now supports Ctrl-Alt-End as an alternative shortcut for
+sending Ctrl-Alt-Delete to remote systems. The zoom level of the client display
+can be specified more granularly, connections are easier to select within in
+the web interface, and guacd now provides a flag for printing the build
+version.
* [GUACAMOLE-113](https://issues.apache.org/jira/browse/GUACAMOLE-113) - Add Ctrl+Alt+Del hotkey
* [GUACAMOLE-152](https://issues.apache.org/jira/browse/GUACAMOLE-152) - Difficult to reach specific zoom levels
@@ -222,12 +235,12 @@ outputting the build version.
### General improvements to terminal behavior
-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.
+Compatibility of Guacamole's terminal emulator has been improved, 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
+the control code sent for backspace. The terminal has also been adjusted to hide
+escape sequences and control codes that need not be supported but which were
+previously incorrectly printed to the screen.
* [GUACAMOLE-269](https://issues.apache.org/jira/browse/GUACAMOLE-269) - Add support for alternative backspace/delete control codes
* [GUACAMOLE-564](https://issues.apache.org/jira/browse/GUACAMOLE-564) - Hide APC escape sequence for terminal
@@ -235,19 +248,19 @@ and control codes that were previously outputted to the screen.
### Support for systemd
-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.
+The guacamole-server build now includes an optional systemd init script to
+allow for automatic startup on distributions that have moved from traditional
+init scripts to systemd.
* [GUACAMOLE-30](https://issues.apache.org/jira/browse/GUACAMOLE-30) - Add Systemd init script for guacd-server
### Control of RDP bitmap and glyph caching
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.
+how the RDP protocol behaves for caching bitmaps, glyphs, and other off-screen
+data. The default behavior remains unchanged, with caching of all of these
+items enabled, however these parameters are available to workaround issues if
+your RDP server handles such caching incorrectly.
* [GUACAMOLE-448](https://issues.apache.org/jira/browse/GUACAMOLE-448) - Add parameters for controlling RDP bitmap/glyph/off-screen caching
@@ -256,8 +269,13 @@ Internationalization
### Additional RDP keymaps
-Several keymaps have been added or updated for better support for keyboard
-input on both the Guacamole Client side and on remote systems.
+Several keymaps have been added or updated to better support RDP servers with
+differing keyboard layouts. As always, bear in mind that [the client side of
+Guacamole is always independent of keyboard layout](/faq/#does-guacamole-support-my-keyboard-layout).
+Additional keyboard layouts for RDP are mainly of benefit for enabling the
+typing of certain characters if your RDP server does not support Unicode
+events, and to ensure correct translation of key event to RDP scancode if the
+keyboard layout of the RDP server is not the default (US English).
* [GUACAMOLE-233](https://issues.apache.org/jira/browse/GUACAMOLE-233) - Add Spanish keymap for RDP
* [GUACAMOLE-273](https://issues.apache.org/jira/browse/GUACAMOLE-273) - Add Portuguese Brazilian keymap for RDP
@@ -267,9 +285,11 @@ input on both the Guacamole Client side and on remote systems.
### Spanish translation of web interface
-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.
+The entire web interface has been translated into Spanish, including the
+on-screen keyboard. Spanish will automatically be selected if accessing
+Guacamole from a browser whose default language is set to Spanish. The language
+can also be [manually selected](/doc/gug/using-guacamole.html#display-language)
+within Guacamole's preferences.
* [GUACAMOLE-463](https://issues.apache.org/jira/browse/GUACAMOLE-463) - Spanish translation for Guacamole client
* [GUACAMOLE-530](https://issues.apache.org/jira/browse/GUACAMOLE-530) - Add Spanish on screen keyboard
@@ -279,18 +299,18 @@ Bug fixes
### Hostname / desktop name regression
-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.
+An issue was corrected where the hostname or desktop name of VNC and RDP
+connections replaced the connection name on the tab or window title in the
+browser. The connection name is now always displayed for VNC and RDP.
* [GUACAMOLE-502](https://issues.apache.org/jira/browse/GUACAMOLE-502) - Hostname / desktop name replaces connection name
### General connection stability
-Several fixes address issues with the stability of connections opened
-with Guacamole, either between Guacamole Client and Server, or between
-Server and remote systems.
+Several issues potentially affecting connection stability have been addressed.
+Additional safeguard measures have also been put in place to ensure that
+connection processes are automatically killed and cleaned up if an unknown
+issue causes the process to become unresponsive.
* [GUACAMOLE-324](https://issues.apache.org/jira/browse/GUACAMOLE-324) - Incorrect buffer used in socket write
* [GUACAMOLE-384](https://issues.apache.org/jira/browse/GUACAMOLE-384) - Terminal writes during disconnect may segfault
@@ -311,24 +331,28 @@ Server and remote systems.
### CAS authorization URI derived incorrectly
-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.
+Guacamole's CAS authentication has been corrected to more properly comply with
+the CAS specification. The `/login` portion of the URI used for logins is
+required by the specification but was previously omitted by Guacamole. This is
+tolerated by some CAS implementations, but not by all. CAS implementations
+which require this should now work as expected with Guacamole.
* [GUACAMOLE-457](https://issues.apache.org/jira/browse/GUACAMOLE-457) - CAS authentication provider omits login URI
### Build issues for guacamole-server
-A couple of fixes were introduced for build issues for Guacamole
-server components for various libraries and compilers.
+Issues which broke the guacamole-server build on some platforms have now been
+fixed. In particular, Guacamole should now build correctly on systems having
+GCC 7.
* [GUACAMOLE-485](https://issues.apache.org/jira/browse/GUACAMOLE-485) - pango is required with pango support disabled
* [GUACAMOLE-500](https://issues.apache.org/jira/browse/GUACAMOLE-500) - Terminal build fails against GCC 7
### Fixes for guacenc behavior and protocol implementation
-A few bugs were squashed in the guacenc program that caused error
-messages and erratic behavior under certain conditions.
+Previous releases of the "guacenc" utility (part of guacamole-server) produced
+incorrect error messages and erratic behavior under certain conditions. These
+issues have been corrected.
* [GUACAMOLE-307](https://issues.apache.org/jira/browse/GUACAMOLE-307) - guacenc reports "Layer index out of bounds: -1"
* [GUACAMOLE-482](https://issues.apache.org/jira/browse/GUACAMOLE-482) - Return value of guacenc_video_flush_frame() not handled
@@ -336,9 +360,9 @@ messages and erratic behavior under certain conditions.
### Issues specific to Internet Explorer
-Changes were introduced that fix IE-specific issues that either
-caused problems or had the potential to impact compatibility with
-various versions of IE.
+Several issues specific to Internet Explorer which either caused problems or
+had the potential to impact compatibility across versions of Internet Explorer
+have been fixed.
* [GUACAMOLE-316](https://issues.apache.org/jira/browse/GUACAMOLE-316) - IE Compatibility mode doesn't work
* [GUACAMOLE-347](https://issues.apache.org/jira/browse/GUACAMOLE-347) - IE may lack window.location.origin
@@ -346,22 +370,24 @@ various versions of IE.
### Use of deprecated `navigator.getUserMedia()`
-The navigator.getuserMedia() method has been deprecated, so the
-Guacamole Client code has been adjusted to remove reliance upon
+The `navigator.getUserMedia()` method used by Guacamole's support for audio
+input has been deprecated. Guacamole has been updated to no longer rely upon
that method.
* [GUACAMOLE-237](https://issues.apache.org/jira/browse/GUACAMOLE-237) - navigator.getUserMedia() deprecated
### Incorrect documentation for RDP `load-balance-info` parameter
-Documentation was corrected for the load-balance-info parameter.
+The `load-balance-info` parameter was incorrectly documented as
+`load-balancing-info`. The correct parameter name is indeed
+`load-balance-info`. This has been fixed in the documentation.
* [GUACAMOLE-427](https://issues.apache.org/jira/browse/GUACAMOLE-427) - RDP "load-balance-info" parameter incorrectly documented
### Erroneous inclusion of "guaclog" binary in source tree
-The guaclog binary was accidentally included in one of the source
-code releases and in the git repository. It has been removed.
+The "guaclog" binary was accidentally included in the source tree of the git
+repository. It has been removed.
* [GUACAMOLE-492](https://issues.apache.org/jira/browse/GUACAMOLE-492) - guaclog binary erroneously included in source tree
@@ -370,26 +396,30 @@ Platform / API changes
### **Java 8 or later is now required**
-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.
+As noted in [the compatibility section below](#deprecation--compatibility-notes),
+the Guacamole web application now requires Java version 1.8 or later for both
+the build and at runtime. The core Java library, guacamole-common, remains
+compatible with Java 1.6, however Java 1.8 is still required for the overall
+guacamole-client build.
* [GUACAMOLE-497](https://issues.apache.org/jira/browse/GUACAMOLE-497) - Ensure guacamole-client source is compatible with Java 9
* [GUACAMOLE-635](https://issues.apache.org/jira/browse/GUACAMOLE-635) - Build against and require Java 1.8
### Guacamole no longer uses cookies
-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.
+The Guacamole web application no longer uses cookies at all, instead relying on
+the browser's local storage.
* [GUACAMOLE-549](https://issues.apache.org/jira/browse/GUACAMOLE-549) - Store auth token within localStorage
### Removal of NoAuth and other deprecated components
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.
+removed entirely from the code base. This includes the NoAuth extension,
+several classes and functions, and several old properties. The use of any of
+these components would previously have resulted in warnings. They will no
+longer be available from this point forward, and continuing to use the
+deprecated properties will silently have no effect.
* [GUACAMOLE-493](https://issues.apache.org/jira/browse/GUACAMOLE-493) - Remove the NoAuth extension entirely
* [GUACAMOLE-494](https://issues.apache.org/jira/browse/GUACAMOLE-494) - Remove support for old, deprecated properties
@@ -397,20 +427,14 @@ and several old properties and API endpoints.
### Improvements to extension API
-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 extension API has been updated to make development and maintenance of
+extensions easier and more consistent. The error status codes sent by the REST
+API are now derived from the exceptions thrown, allowing extensions to control
+the exact code sent. Dependency precedence has been updated so that extensions
+always see the classes they bundle, even if the web application bundles a
+different version of the same class. Base implementations of `UserContext` and
+`AuthenticationProvider` interfaces have been provided, removing the need to
+fully implement these interfaces when writing an extension.
* [GUACAMOLE-499](https://issues.apache.org/jira/browse/GUACAMOLE-499) - REST API Error Codes should come from GuacamoleStatus
* [GUACAMOLE-541](https://issues.apache.org/jira/browse/GUACAMOLE-541) - Webapp dependencies take precedence over bundled extension dependencies
@@ -419,20 +443,19 @@ web applicatlon.
### Web application updated to AngularJS 1.6.9
-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.
+The AngularJS library included with the Guacamole web application was updated
+from 1.3.16 to 1.6.9. Several parts of the web application were reworked for
+compatibility with this update, including the handling HTTP requests and
+responses.
* [GUACAMOLE-526](https://issues.apache.org/jira/browse/GUACAMOLE-526) - Update Guacamole-Client Webapp to Angular 1.6.9
-### Improvements to Java / JavaScript tunnel API
+### Improvements to JavaScript tunnel API
-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.
+The tunnel implementations provided by Guacamole's JavaScript API have been
+updated to allow arbitrary HTTP headers to be included in the connection
+request (where supported by the underlying transport), and to allow the same
+instance of the tunnel to be reused following disconnect.
* [GUACAMOLE-431](https://issues.apache.org/jira/browse/GUACAMOLE-431) - Tunnel implementations handles close only once
* [GUACAMOLE-437](https://issues.apache.org/jira/browse/GUACAMOLE-437) - Allow to configure custom headers for Guacamole tunnels
@@ -448,13 +471,13 @@ 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.
+require Java 1.8 for both compile and runtime. This 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 ceased receiving public updates.
+
+The only exception to this is the core Java API, guacamole-common, which
+continues to maintain compatibility with Java 1.6.
Database schema changes
-----------------------
@@ -468,7 +491,7 @@ required to support those within the database modules (including the
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`]
+instructions for this process can be found in the [`JDBC Authentication`]
(http://guacamole.apache.org/doc/gug/jdbc-auth.html) documentation.
Hostname logging within database
@@ -494,20 +517,15 @@ address.
Removal of deprecated NoAuth extension
--------------------------------------
-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 NoAuth extension has been [deprecated since
+0.9.13-incubating](/releases/0.9.13-incubating/#noauth-now-deprecated), and has
+now been removed from Guacamole's codebase.
Removal of deprecated properties
--------------------------------
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.
+have been removed in the 1.0.0 release.
* `basic-user-mapping`
* `mysql-disallow-simultaneous-connections`
@@ -515,29 +533,106 @@ guacamole.properties file.
* `postgresql-disallow-simultaneous-connections`
* `postgresql-disallow-duplicate-connections`
+Prior to the 1.0.0 release a warning would be logged regarding the deprecation
+of these properties. As of this release, these properties will be silently
+ignored.
+
Extension API changes
---------------------
### Support for user groups
-As 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.
+As noted above, one of the major changes in this release is the addition of
+support for user groups. These changes center around the new `UserGroup`
+interface and functions for accessing instances of that interface. Note that if
+you are using the abstract base classes `AbstractUserContext` and
+`AbstractUser`, little to no changes will be necessary as default
+implementations of the required new functions have been provided.
+
+#### Retrieval of user groups
+
+The `UserContext` interface now defines a
+`getUserGroupDirectory()` function which returns a `Directory<UserGroup>`
+providing access to all user groups. If your extension does not provide user
+groups, it can simply return an empty `SimpleDirectory<UserGroup>`:
+
+ @Override
+ public Object getUserGroupDirectory() {
+ return new SimpleDirectory<UserGroup>();
+ }
+
+#### Effective group membership
+
+To allow extensions to take group membership into account, even when that
+membership is dictated by a different extension, the `AuthenticatedUser` class
+now defines `getEffectiveGroups()` function. This function should return the
+identifiers of all user groups that apply to the current user. If support for
+user groups is not implemented by the extension, simply return an empty set of strings:
+
+ @Override
+ public Set<String> getEffectiveUserGroups() {
+ return Collections.<String>emptySet();
+ }
+
+#### Effective permissions
+
+The `User` interface now provides a `getEffectivePermissions()` function which
+should return an implementation of `Permissions` which exposes the permissions
+that apply to the user, including permissions which may be inherited through
+group membership. If inheritence of permissions is not implemented by your
+extension, this function can simply return `this` (as `User` extends
+`Permissions`):
+
+ @Override
+ public Permissions getEffectivePermissions() {
+ return this;
+ }
+
+#### Exposing group membership
+
+The `User` and `UserGroup` interfaces provide multiple functions for retrieving
+parent groups and child objects, if applicable. Existing implementations of the
+`User` interface which do not extend `AbstractUser` will need to implement
+`getUserGroups()`, a function which retrieves the immediate parent groups of
+the user. The returned `RelatedObjectSet` should allow for manipulation of the
+group relationship if the extension allows such manipulation (and if the
+current user has permission to do so). Extensions which do not implement user
+groups can simply return an empty set:
+
+ @Override
+ public RelatedObjectSet getUserGroups() {
+ return RelatedObjectSet.EMPTY_SET;
+ }
### The new decoration API
-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.
+The `AuthenticationProvider` interface now defines `decorate()` and `redecorate()`
+functions which allow an implementation of `AuthenticationProvider` to decorate the
+`UserContext` instances of other extensions. After an extension returns a
+`UserContext` instance, the `decorate()` (if the `UserContext` is for a new
+session) or `redecorate()` (if the `UserContext` has been updated for an
+existing session) functions of all other extensions are invoked to give those
+extensions a chance to wrap the `UserContext`. This allows extensions to add
+functionality to the objects of other extensions which may not otherwise be
+possible.
+
+Implementations of `AuthenticationProvider` which extend `AbstractAuthenticationProvider` need not
+implement these functions as default implementations are provided.
+Implementations which do not extend `AbstractAuthenticationProvider` and which do not
+decorate the `UserContext` of other extensions should simply return the
+original `UserContext`:
+
+ @Override
+ public UserContext decorate(UserContext context,
+ AuthenticationProvider authProvider, Credentials credentials) {
+ return context;
+ }
+
+ @Override
+ public UserContext redecorate(UserContext decorated, UserContext context,
+ AuthenticationProvider authProvider, Credentials credentials) {
+ return decorate(context, authProvider, credentials);
+ }
### Removal of deprecated `GuacamoleHome` and `GuacamoleProperties` classes
@@ -545,11 +640,10 @@ TODO
### Deprecation of `SimpleUserDirectory`, `SimpleConnectionDirectory`, and `SimpleConnectionGroupDirectory` classes
-The SimpleUserDirectory, SimpleConnectionDirectory, and
-SimpleConnectionGroupDirectory classes have been deprecated in favor
-of the SimpleDirectory<T> class. These classes can still be used,
-but will result in deprecation warnings, and will be removed in
-a future release.
+The `SimpleUserDirectory`, `SimpleConnectionDirectory`, and
+`SimpleConnectionGroupDirectory` classes have been deprecated in favor of the
+`SimpleDirectory<T>` class. These classes can still be used, but will result in
+deprecation warnings, and will be removed in a future release.
### Deprecation of `SimpleUser` convenience constructors
@@ -586,13 +680,14 @@ TODO
### Addition of `Guacamole.Tunnel.State.UNSTABLE` state
-In 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.
+In order to support changes to detecting and handling network problems within
+the Guacamole connections, another tunnel state, `UNSTABLE`, has been added.
+The tunnel enters this state when it is still technically connected but the
+network connection appears unstable and may result in disconnection.
+
+Code which handles changes in tunnel state may need to be updated to take this
+additional state into account if it does not currently ignore unknown states,
+or that code would benefit from explicitly handling the unstable condition.
### Internal WebSocket tunnel implementation changes