SSLCertMonitor

This monitor tests if an SSL certificate a remote network server presents is valid. A certificate is invalid if its initial time is prior to the current time, if the current time is within the configured number of days before the expiration time, or if the common name is valid.

Run a command like this to simulate the behavior:

echo | openssl s_client -connect <site>:<port> 2>/dev/null | openssl x509 -noout -dates

The output indicates that the time range a certificate is valid:

notBefore=Dec 24 14:11:34 2013 GMT
notAfter=Dec 25 10:37:40 2014 GMT

You can configure a threshold in days applied on the notAfter date.

While the monitor is mainly useful for plain SSL sockets, it does provide limited support for STARTTLS protocols. Users can specify a STARTTLS message be sent prior to the SSL negotiation and a regular expression to match to the response received from the server. An additional preliminary message and response regular expression pair is available for protocols that require it (such as XMPP).

Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.SSLCertMonitor

Configuration and use

Table 1. Monitor-specific parameters for the SSLCertMonitor
Parameter	Description	Default
Required
port	TCP port for the service with SSL certificate.	-1
Optional
retry	Number of attempts to get the certificate state.	0
days	Number of days before the certificate expires that we mark the service as failed.	7
server-name `{}`	This is the DNS hostname to send as part of the TLS negotiation, known as server name indication (SNI) (See: RFC3546, section 3.1.)	n/a
starttls-preamble `{}`	Preliminary message to send to server prior to STARTTLS command.	n/a
starttls-preamble-response `{}`	Regular expression that must match response to preliminary message sent to server prior to STARTTLS command.	n/a
starttls-start `{}`	STARTTLS command.	n/a
starttls-start-response `{}`	Regular expression that must match response to STARTTLS command sent to server.	n/a

{} indicates the parameter supports placeholder substitution.

This monitor implements the Common Configuration Parameters.

The monitor has limited support for communicating on other protocol layers above the SSL session layer. The STARTTLS support has been tested only with a single XMPP server. It is not known if the same approach will prove useful for other use cases, like sending a host header for HTTPS, or issue a STARTTLS command for IMAP, POP3, SMTP, FTP, LDAP, or NNTP.

Examples

The following examples show how to monitor SSL certificates on services like IMAPS, SMTPS, and HTTPS, as well as an sample use of the STARTTLS feature for XMPP. If the certificates expire within 30 days, the service goes down and indicates this issue in the reason of the monitor. In this example, the monitoring interval is reduced to test the certificate every two hours (7,200,000 ms).

Note that you must include the monitor section for each service in your definition.

Configuration in poller-configuration.xml is as follows:

<service name="SSL-Cert-IMAPS-993" interval="7200000" user-defined="false" status="on">
    <parameter key="retry" value="2"/> (1)
    <parameter key="timeout" value="2000"/> (2)
    <parameter key="port" value="993"/> (3)
    <parameter key="days" value="30"/> (4)
</service>

<service name="SSL-Cert-SMTPS-465" interval="7200000" user-defined="false" status="on">
    <parameter key="retry" value="2"/> (1)
    <parameter key="timeout" value="2000"/> (2)
    <parameter key="port" value="465"/> (3)
    <parameter key="days" value="30"/> (4)
</service>

<service name="SSL-Cert-HTTPS-443" interval="7200000" user-defined="false" status="on">
    <parameter key="retry" value="2"/> (1)
    <parameter key="timeout" value="3000"/> (2)
    <parameter key="port" value="443"/> (3)
    <parameter key="days" value="30"/> (4)
    <parameter key="server-name" value="${nodelabel}.example.com"/> (5)
</service>

<service name="XMPP-STARTTLS-5222" interval="7200000" user-defined="false" status="on">
    <parameter key="retry" value="2"/> (1)
    <parameter key="timeout" value="3000"/> (2)
    <parameter key="port" value="5222"/> (3)
    <parameter key="days" value="30"/> (4)
    <parameter key="starttls-preamble" value="<stream:stream xmlns:stream='http://etherx.jabber.org/streams' xmlns='jabber:client' to='{ipAddr}' version='1.0'>"/> (6)
    <parameter key="starttls-preamble-response" value="^.*starttls.*$"/> (7)
    <parameter key="starttls-start" value="<starttls xmlns='urn:ietf:params:xml:ns:xmpp-tls'/>"/> (8)
    <parameter key="starttls-start-response" value="^.*starttls.*$"/> (9)
</service>

<monitor service="SSL-Cert-IMAPS-993" class-name="org.opennms.netmgt.poller.monitors.SSLCertMonitor" /> (10)
<monitor service="SSL-Cert-SMTPS-465" class-name="org.opennms.netmgt.poller.monitors.SSLCertMonitor" /> (10)
<monitor service="SSL-Cert-HTTPS-443" class-name="org.opennms.netmgt.poller.monitors.SSLCertMonitor" /> (10)
<monitor service="XMPP-STARTTLS-5222" class-name="org.opennms.netmgt.poller.monitors.SSLCertMonitor" /> (10)

1	Number of attempts to test a service’s status.
2	Timeout for the isReachable method, in milliseconds.
3	TCP port for the service with SSL certificate.
4	Number of days before the certificate expires that we mark the service as failed.
5	The DNS hostname to send as part of the TLS negotiation.
6	Preliminary message to send to the server prior to STARTTLS command.
7	Regular expression that must match response to preliminary message sent to server prior to STARTTLS command.
8	STARTTLS command.
9	Regular expression that must match response to STARTTLS command sent to server.
10	Required monitor section for each service monitor.