Upgrading

Updating Keeper Connection Manager when using the Advanced Linux Install method

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.

Major releases (the only releases which may break API compatibility) are intentionally isolated from each other such that each major release uses a different base URL within its .repo file. Updates to an existing install of Keeper Connection Manager are always minor releases and will not break compatibility.

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

Updates to Keeper Connection Manager are brief and can be expected to take only a few minutes, however the update process should be planned for a time that the service can safely be taken down, ideally a scheduled maintenance window. This is because the upgrade procedure generally requires that both Tomcat and guacd are restarted.

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

If you do not have a standalone "guacamole" service

You will not have a standalone "guacamole" service if you have not deployed Guacamole automatically with the "keeper-guacamole-standalone" package. This will be the case if:

• You have chosen to manually deploy Guacamole under your own install of Apache Tomcat or JBoss, rather than use the provided version of Tomcat.

• You are maintaining a deployment of Keeper Connection Manager that was originally installed before the 2.5 release (2021-09-16).

You will instead need to manually stop your install of Tomcat:

$ 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