Updating From 1.x

Upgrading from older versions

Keeper Connection Manager was previously Glyptodon Enterprise prior to version 2.8

Before proceeding with upgrading a Glyptodon 1.x installation to Glyptodon 2.x or Keeper Connection Manager (v2.8+), 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 Keeper Connection Manager 2.x is 1.1.0. This version of the API is incompatible with the base API version of Keeper Connection Manager 1.x (0.9.12-incubating). If you have custom or third-party extensions which have been written for Keeper Connection Manager 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.

Process overview

Updating an installation of Glyptodon from the 1.x major release to the 2.x major release or to Keeper Connection Manager (releases of version 2.8 and greater) is slightly more complex than simply updating between minor releases and will involve the following steps:

1. Stop Tomcat and guacd services

2. Update your .repo file to point to the 2.x release (rather than 1.x)

3. Update your installed packages using yum upgrade

4. Force Tomcat to redeploy Guacamole (it may not automatically recognize the new guacamole.war as new)

5. If you are using a database: Update your database schema

6. If using SSL termination: Update Tomcat's server.xml to trust "X-Forwarded-For" from your proxy

7. 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.

$ sudo systemctl stop tomcat guacd

Update the .repo file within /etc/yum.repos.d

Each major release of Keeper Connection Manager is located within its own, isolated repository. To upgrade to a major release after 1.X, remove the current .repo file and use the following command to automatically create an updated version:

sudo yum install "https://keepersecurity.com/kcm/2/`rpm -E%{suffix:%dist}`/kcm-release.rpm"

Alternatively the .repo file can be updated manually. To do this, use a text editor to replace the contents of your old .repo file within /etc/yum.repos.d:

$ sudo vi /etc/yum.repos.d/kcm.repo

The only difference between the 1.x and 2.x files is in the baseurl, with the relevant part of the base URL changing from "release/1/" to "kcm/2/". Once updated, your .repo file should ultimately look like:

[kcm]
name=Keeper Connection Manager 2.x
baseurl=https://keepersecurity.com/kcm/2/el/$releasever/$basearch/
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://keepersecurity.com/kcm/RPM-GPG-KEY-kcm-release

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 yum upgrade:

$ sudo yum upgrade "kcm-*"

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:

$ sudo rm -r /var/lib/tomcat/webapps/guacamole/

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	/opt/keeper/share/guacamole-auth-jdbc-mysql/schema/upgrade/upgrade-GLEN-1.x.sql
PostgreSQL	/opt/keeper/share/guacamole-auth-jdbc-postgresql/schema/upgrade/upgrade-GLEN-1.x.sql

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.

MySQL / MariaDB

Where "guacamole_db" is the name of your Guacamole database:

$ mysql -u root -p guacamole_db < /opt/keeper/share/guacamole-auth-jdbc-mysql/schema/upgrade/upgrade-GLEN-1.x.sql

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.

PostgresSQL

Where "guacamole_db" is the name of your Guacamole database:

$ psql -d guacamole_db -f /opt/keeper/share/guacamole-auth-jdbc-postgresql/schema/upgrade/upgrade-GLEN-1.x.sql

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:

GRANT SELECT,INSERT,UPDATE,DELETE ON ALL TABLES IN SCHEMA public TO guacamole_user;
GRANT SELECT,USAGE ON ALL SEQUENCES IN SCHEMA public TO guacamole_user;

Update 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 /etc/tomcat/server.xml.

Using the provided example server.xml

The easiest way to add the required entry is to copy the example server.xml file provided with the kcm-guacamole package, replacing the old /etc/tomcat/server.xml:

$ sudo cp /opt/keeper/share/guacamole/server.xml /etc/tomcat/

The example server.xml file defines:

• A single HTTP connector listening on port 8080.

• A RemoteIpValve with all settings at their default values.

By default, the RemoteIpValve will trust "X-Forwarded-For" from all private networks (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 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.

Editing server.xml manually

If editing server.xml manually (rather than using the example server.xml), a <Valve> which trusts "X-Forwarded-For" from most common private addresses would be specified as:

<Valve className="org.apache.catalina.valves.RemoteIpValve"/>

This <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 server.xml file:

        ...

        <Valve className="org.apache.catalina.valves.RemoteIpValve"/>

      </Host>
    </Engine>
  </Service>
</Server>

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:

<Valve className="org.apache.catalina.valves.RemoteIpValve"
       internalProxies="127\.\d{1,3}\.\d{1,3}\.\d{1,3}|0:0:0:0:0:0:0:1|::1"/>

Start Tomcat and guacd

After 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:

$ sudo systemctl start tomcat guacd

Your Keeper Connection Manager installation should now be working and up-to-date with the 2.x release.