Monitoring and Healthcheck

In EJBCA there exists a health check service that can be used for health monitoring. It is also useful for cluster, 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 in the URL: http://localhost:8080/ejbca/publicweb/healthcheck/ejbcahealth and is configured using conf/

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

  • healthcheck.amountfreemem, default: '1' - The number of Mb of memory that must be free.

  • healthcheck.dbquery, default: 'select 1' - Parameter indicating the string that should be used to do a minimal check that the database is working.

  • healthcheck.authorizedips, default: '' - Specifies which remote IPs that may call this healthcheck servlet. Use ';' between multiple IPs.

  • healthcheck.catokensigntest; default: 'false' - if the check of CA tokens should actually perform a signature test on the CA token, or it should only see if the token status is active.

  • healthcheck.publisherconnections, default: 'false' - Defines if a connections test to all configured publisers should be performed.

By editing a maintenance file on the server, you can make the service return an error message stating that the server is down for mainenance. This is very useful in a cluster when you can take cluster nodes in and out of rotation by editing a simple text file.

  • healthcheck.maintenancefile, default: not set - location of file containing information about maintenance.

  • healthcheck.maintenancepropertyname, default: DOWN_FOR_MAINTENANCE - the healthcheck.maintenancefile should contain a single line like this 'DOWN_FOR_MAINTENANCE=true'.

The following parameters configure what message or HTTP error code the health service returns.

  • healthcheck.okmessage, default: 'ALLOK' - Text string used to say that every thing is ok with this node.

  • healthcheck.sendservererror, default: 'true' - if a HTTP errorcode 500 should be sent in case of error.

  • healthcheck.customerrormessage, default: null - Set this parameter if you want a static error message instead of one generated by the HealthChecker.

If an error is detected one or several of the following error messages is reported.

  • "MEM: Error Virtual Memory is about to run out, currently free memory : number" - The JVM is about to run out of memory.

  • "DB: Error creating connection to database" - JDBC Connection to the database failed, this might occur if DB craches or network is down.

  • "CA: Error CA Token is disconnected: CAName" - This is a sign of hardware problems with one or several of the hard ca tokens in the node.

  • "MAINT: DOWN_FOR_MAINTENANCE" - This is reported when the healthcheck.maintenancefile is used and the node is set to be off line.

  • "Error when testing the connection with publisher: PublisherName" - This is reported when a test connection to one of the publishers failed.

Which CAs that are checked by the health check service can be configured in the admin web on the CA Activation page as well as in the Edit CA page.

To be fully Common Criteria compliant, a different key for signature tests than certificate signing should be used in the CA's HSM token configuration (the "testKey" alias should point to a key with no other uses).