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

Description

healthcheck.authorizedips

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. Defaults to 127.0.0.1.

healthcheck.minimumfreememory

Number of megabytes of memory that must be free before removing the node out of the cluster. Defaults to 1.

healthcheck.checkdbstring

String used to do a minimal check that the database is working. May differ between databases. Defaults to Select count(*) from signerconfigdata, the property is not used when running without database.

healthcheck.maintenancefile

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

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

If this is set to a non-empty value, the value is used for the error message instead of the details describing the errors (thus not exposing internal details).

healthcheck.sendservererror

If set to true (default), 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.

 Available tests and responses


  • No errors: If all tests passed the HTTP result code is "200 OK" and page contains only the text "ALLOK".

  • Down for maintenance: If the down for maintenance file indicates that the server is down for maintenance an HTTP response code in 5xx range is returned with an error page containing "MAINT: " followed of the name of the maintenance property as configured. No further checks are performed.

  • Database test: A test is performed that SignServer is able to query the database. When running without database a check is made that the configured directory is initialized correctly and is not empty. If anything failed one or more error messages are included in an error page returned with the HTTP response code in the 5xx range.

  • Memory test: Checks the available free memory. If anything failed, an error message is included in an error page returned with the HTTP response code in the 5xx range.

  • 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.
  • Disabled workers: Workers that are disabled by having the worker property DISABLED=true are not considered in the Health Check report.