Before proceeding with upgrading a Glyptodon Enterprise 1.x installation to 2.x, be sure to consider the following changes which may affect compatibility:
- The default security mode for RDP connections is now "any" (negotiation). This should make configuring new connections more straightforward, but may cause problems for connections that expect legacy RDP encryption and a graphical login screen to be used by default.
- Connections to the consoles of Hyper-V VMs through Hyper-V's built-in RDP server now need to specify the "vmconnect" security mode. RDP connections to the consoles of Hyper-V VMs will not work without this security mode specified.
- The base API version of Glyptodon Enterprise 2.x is 1.1.0. This version of the API is incompatible with the base API version of Glyptodon Enterprise 1.x (0.9.12-incubating). If you have custom or third-party extensions which have been written for Glyptodon Enterprise 1.x or Apache Guacamole 0.9.12-incubating, they will need to be updated to use the Apache Guacamole 1.1.0 API before they will work.
The update process should be also planned for a time that the service can safely be taken down, ideally a scheduled maintenance window. This is because upgrading between major releases always requires that both Tomcat and guacd are offline during the upgrade.
Updating an installation of Glyptodon Enterprise from the 1.x major release to the 2.x major release is slightly more complex than simply updating between minor releases and will involve the following steps:
- Stop Tomcat and guacd services
- Update your .repo file to point to the 2.x release (rather than 1.x)
- Update your installed packages using
- Force Tomcat to redeploy Guacamole (it may not automatically recognize the new
- If you are using a database: Update your database schema
- If using SSL termination: Update Tomcat's
server.xmlto trust "
X-Forwarded-For" from your proxy
- Start Tomcat and guacd services
Stop Tomcat and guacd
Before upgrading the Glyptodon Enterprise packages, both Tomcat and guacd must be taken offline. By definition, the components of different major releases are incompatible with each other, and these components will be replaced during the upgrade process. It is not safe to perform a major release upgrade while components of Guacamole are running.
Update the Glyptodon Enterprise
.repo file within
Each major release of Glyptodon Enterprise is located within its own, isolated repository. To upgrade between major releases, the
.repo file pointing to the older Glyptodon Enterprise repository must be updated to point to the repository of the new major release.
Just as with Glyptodon Enterprise 1.x, the necessary repository definition file for 2.x is distribution-specific and can be viewed within your account information on the Glyptodon Enterprise website. Locate your Linux distribution within the "downloads" section of your Glyptodon Enterprise account, copy the contents of the file shown, and use a text editor to replace the contents of your old
.repo file within
The only difference between the 1.x and 2.x files is the version number following "
release/" within the base URL, with the relevant part of the base URL changing from "
release/1/" to "
release/2/". Once updated, your
.repo file should ultimately look like:
where “USERNAME” and “PASSWORD” are the repository credentials which were generated for you when your organization’s Glyptodon Enterprise account was created.
Apply updates using yum
Once the .repo file has been updated to point to the Glyptodon Enterprise 2.x repository, the software components can be upgraded to their 2.x versions by simply running
As mentioned above, be sure that Tomcat and guacd are both stopped prior to running
yum upgrade. If you encounter errors during the upgrade process, double-check that both Tomcat and guacd have indeed been stopped, and re-run the
yum upgrade command.
Force Tomcat to redeploy Guacamole
Tomcat may not automatically recognize that the new
guacamole.war is indeed new, and may continue to use its cached copy of the older version. To ensure that the new version of Guacamole is deployed, you should remove the directory created by Tomcat when it originally deployed
guacamole.war, thus forcing Tomcat to redeploy the .war during startup:
Apply database schema changes
If using MySQL, MariaDB, or PostgreSQL for connection storage and/or authentication, the database schema of your existing database will be that of Apache Guacamole 0.9.12-incubating. It will need to be brought up-to-date with the base version of Apache Guacamole provided by Glyptodon Enterprise 2.x by running the appropriate SQL script against the database in question:
|Database||Upgrade SQL script|
|MySQL / MariaDB|
If using PostgreSQL, you will additionally need to re-run the permission grants to ensure the Guacamole database user has sufficient permissions to execute queries against new tables and sequences, as PostgreSQL does not automatically extend the permissions already granted when new tables/sequences are created.
guacamole_db" is the name of your Guacamole database:
If using MySQL or MariaDB, the permissions granted during original setup of the Guacamole database will automatically extend to new tables. You do not need to re-run the permission grants.
guacamole_db" is the name of your Guacamole database:
If using PostgreSQL, the permissions granted during original setup of the Guacamole database will not automatically extend to new tables and sequences added through the upgrade script. You will need to re-run the permission grants to ensure the Guacamole database user has sufficient permissions to execute queries against the new tables:
server.xml to trust "
X-Forwarded-For" from known proxies
From Apache Guacamole 1.0.0 onward, logging of client IP addresses now relies on Tomcat configuration to determine whether the "
X-Forwarded-For" header can be trusted. This includes Glyptodon Enterprise 2.x, which is based off Apache Guacamole 1.1.0. If you are using a reverse proxy like Nginx or Apache for SSL termination, you will need to add a "
RemoteIpValve" entry to
The easiest way to add the required entry is to copy the example
server.xml file provided with the
glyptodon-guacamole package, replacing the old
The example server.xml file defines:
- A single HTTP connector listening on port 8080.
RemoteIpValvewith all settings at their default values.
By default, the
RemoteIpValve will trust "
X-Forwarded-For" from all private networks (
169.254.0.0/16, and both IPv4 and IPv6 localhost). If you need this range to be narrowed, or if you have already made manual edits to
server.xml, you will need to make these changes manually.
server.xml manually (rather than using the example
<Valve> which trusts "
X-Forwarded-For" from most common private addresses would be specified as:
<Valve> must be added within the relevant
<Host> section. In most cases, the easiest place to add this is simply toward the end of the
If needed, this can be narrowed by providing your own value for the
internalProxies attribute specifies a regular expression which matches the IP addresses of any proxies whose "
X-Forwarded-For" headers should be trusted. For example, to trust only "
X-Forwarded-For" received from localhost:
Start Tomcat and guacd
yum upgrade completes, and any needed changes to the database and Tomcat's
server.xml have been made, the system has been updated and it is safe to start Tomcat and guacd back up:
Your Glyptodon Enterprise installation should now be working and up-to-date with the 2.x release.