Health Checks

Checking KCM status with automated healthchecks

Keeper Connection Manager includes an automatic healthcheck that runs regularly, checking that the guacd service is reachable, that the authentication subsystem is responsive, and that the KCM license is not expiring soon.

The healthcheck includes a REST API endpoint that can be automatically queried to check the status of the system. The healthcheck endpoint can be reached by issuing a GET request to .../api/ext/healthcheck/full and does not require authentication.

For example, if KCM is hosted at kcm.example.net, the following curl command would retrieve the status of the healthcheck:

curl https://kcm.example.net/api/ext/healthcheck/full

If the KCM server is healthy and the license is valid, this will produce JSON that looks like the following:

{ "licensed": true, "licenseExpiresSoon": false, "healthy" : true }

If unhealthy, or if the license is not valid, the flags shown in the above JSON will have different values. The flags in the healthcheck response JSON are as follows:

Property Name	Description
licensed	Whether the KCM license is currently valid. If the license is valid and unexpired, this will be true. If the license is invalid or has expired, this will be false.
licenseExpiresSoon	Whether the KCM license is currently valid but expiring soon. If the license is not expiring soon, this will be false. If the license is expiring soon and should be renewed as soon as possible, this will be true.The amount of time used to define “soon” for the sake of this check is configurable (see below). By default, the license is considered to be expiring “soon” if it expires within the next week.NOTE: This property will be omitted if licensed is false.
healthy	Whether the KCM server is healthy, based on testing the availability of the guacd service and KCM’s own authentication system. If either guacd or KCM’s authentication system appear to be unresponsive, this will be false. If both appear to be available, this will be true.

The behavior of the healthcheck can be modified using the following configuration properties (RPM installation) or environment variables (Docker installation):

Configuration Property (guacamole.properties)	Environment Variable	Description
healthcheck-interval	HEALTHCHECK_INTERVAL	The number of seconds to wait between each healthcheck. Independent of any requests to the healthcheck endpoint, KCM will perform this healthcheck regularly according to this interval. Requests to the healthcheck endpoint simply return the result of the most recent check.By default, the healthcheck is performed every 5 seconds.
healthcheck-license-grace-period	HEALTHCHECK_LICENSE_GRACE_PERIOD	The number of days to before license expiration to consider the license to be expiring “soon”. Once this period is reached, but the license has not yet expired, licenseExpiresSoon will be true in the healthcheck response.By default, the license will be considered to be expiring “soon” if it expires in the next 7 days.
healthcheck-base-uri	HEALTHCHECK_BASE_URI	The base URI of the KCM server that the healthcheck should use to verify availability of the authentication service. This URI need only be reachable over the local network from KCM itself. By default, http://localhost:8080 is used.