Keeper produces new minor releases of Keeper Connection Manager (1.1, 1.2, 1.3, etc.) roughly every 3 months following the first general availability release. Minor releases are updates to an existing major release which add new features and fix bugs, and will always maintain strict API compatibility. The details of upcoming and past releases can be found in the changelog.

Checking for updates

To check whether updates are available for Keeper Connection Manager packages without actually applying those updates, you can use the yum list updates command. Providing the "kcm-*" pattern to yum list updates restricts the packages checked to only those packages provided by Keeper Connection Manager:

sudo yum list updates "kcm-*"

If the above command lists one or more packages, then there are newer versions of Keeper Connection Manager packages available, and you should proceed with upgrading when a maintenance window permits.

Performing the upgrade

Stop Guacamole and guacd services

Before upgrading the Keeper Connection Manager packages, both Guacamole and guacd should be taken offline:

sudo systemctl stop guacamole guacd

$ sudo systemctl stop tomcat guacd

This is because:

• If both the Guacamole web application and one of its extensions are being updated, the package manager may update the web application first. The running Tomcat service may then redeploy and restart the web application before the extension is updated, resulting in inconsistency.

• If protocol support for guacd is being updated, older versions of that support may be cached by the system linker until the guacd service has been restarted.

• If the guacd service is being updated, those updates cannot take effect until the guacd service is restarted. The running process will continue to use the older, cached binary.

The system should remain stable if the upgrade is performed without stopping Tomcat and guacd, however it is best practice to do so. An upgrade to the web application will always result in the web application being restarted, and any updates being applied will likely not take effect until after services are restarted. With updates to the web application inherently causing a service restart, and updates in general requiring a service restart in order to take effect, it's best to plan this restart as a controlled part of the process.

Apply updates using yum

Once Tomcat and guacd are stopped, the Keeper Connection Manager packages can be upgraded using the yum utility, just like the other packages in the system. The upgrade can be restricted to only Keeper Connection Manager packages by specifying the "kcm-*" pattern:

sudo yum upgrade "kcm-*"

Start the Guacamole and guacd services

After yum upgrade completes, the system has been updated and it is safe to start Guacamole and guacd back up:

sudo systemctl start guacamole guacd

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:

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 -u root -p guacamole_db < /opt/keeper/share/guacamole-auth-jdbc-mysql/schema/upgrade/upgrade-GLEN-1.x.sql

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

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.

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

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

        ...

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

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

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