Health Check

The SignServer Health Check service can be used for health monitoring and is useful for clusters, as it can be checked by load balancers to determine if a node should be active in the cluster (healthy), or taken out of the cluster (unhealthy).

The servlet is located at the URL: http://localhost:8080/signserver/healthcheck/signserverhealth and configured in signserver_deploy.properties.

Configuration Parameters

The following configuration parameters can be set to configure authorization and what the service checks:

Parameter	Default	Description
healthcheck.authorizedips	127.0.0.1.	A semicolon-delimited list of IP addresses authorized to access the healthcheck servlet. If the list contains the keyword "ANY", any IP address is authorized access.
healthcheck.minimumfreememory	1	Number of megabytes of memory that must be free before removing the node out of the cluster.
healthcheck.checkdbstring	`Select count(*)` from signerconfigdata	String used to do a minimal check that the database is working. May differ between databases. The property is not used when running without database.
healthcheck.maintenancefile	Not set	The path to a file containing the maintenance state. This file is a standard Java property file and should have a property (by default named DOWN_FOR_MAINTENANCE). If this property has the value true, none of the standard health checks will be performed, and instead the result will be a string of the form MAINT: DOWN_FOR_MAINTENANCE. If this property is not set (or an invalid file is given), the maintenance functionality is disabled.
healthcheck.maintenancepropertyname	Not set	The property name to be used in the maintenance file. This will also affect the error message returned when in maintenance mode (the part of the string after MAINT: defaults to DOWN_FOR_MAINTENANCE).
healthcheck.customerrormessage	Not set	If this is set to a non-empty value, the value is used for the error message instead of the details describing the errors and, therefore, not exposing internal details.
healthcheck.sendservererror	true	If set to true, HTTP status 500 is returned with an error page containing the error message if health-monitoring fails. If set to false, a plain text result with HTTP status 200 is returned instead.

URL Query Parameters

Parameter	Default	Description
workerId	Not specified	Limit testing workers to the worker with the given ID(s). Can be specified more than once to test several workers. If “none” is specified, no workers are tested. If this parameter is not specified (the default), all non-disabled workers are tested.

Available Tests and Responses

The following lists possible tests and responses:

Workers test

Each (non-disabled) worker is checked for a number of things. If anything failed, one or more error messages are included in an error page returned with the HTTP response code in the 5xx range.

Token offline: Workers having a crypto token can be reported as offline.
Worker status and errors: Each worker implementation can put different requirements on when it is status is considered to be offline.
Signer certificate: Signers requiring a certificate are checked that they have a certificate matching the configured key-pair and that the certificate is valid according to the certificate validity time and the configured minimum remaining validity time.
TimeStampSigner certificate missing EKU: If a TimeStampSigner certificate does not include the required EKU, its status is set to offline.
TimeStampSigner certificate not included in certificate chain If a TimeStampSigner certificate chain property does not include the signer certificate, its status is set to offline.