
= SSLCertMonitor
:description: Learn how to configure and use the SSLCertMonitor in OpenNMS {page-component-title} to test if an SSL certificate a remote network server presents is valid.

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

[cols="1,7"]
|===
| Class Name
| `org.opennms.netmgt.poller.monitors.SSLCertMonitor`
|===

== Configuration and use

.Monitor-specific parameters for the SSLCertMonitor
[options="header"]
[cols="1,3,2"]
|===
| Parameter
| Description
| Default

3+|*Required*

| port
| TCP port for the service with SSL certificate.
| -1

3+|*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 kbd:[{}]
| This is the DNS hostname to send as part of the TLS negotiation, known as server name indication (SNI) (See: link:https://www.ietf.org/rfc/rfc3546.txt[RFC3546], section 3.1.)
| n/a

| resolve-server-name
| Attempt to resolve the `server-name` string to an IP address, and use that IP for TLS negotiation.
| false

| starttls-preamble kbd:[{}]
| Preliminary message to send to server prior to STARTTLS command.
| n/a

| starttls-preamble-response kbd:[{}]
| Regular expression that must match response to preliminary message sent to server prior to STARTTLS command.
| n/a

| starttls-start kbd:[{}]
| STARTTLS command.
| n/a

| starttls-start-response kbd:[{}]
| Regular expression that must match response to STARTTLS command sent to server.
| n/a
|===

kbd:[{}] _indicates the parameter supports <<reference:service-assurance/introduction.adoc#ref-service-assurance-monitors-placeholder-substitution-parameters, placeholder substitution>>._

This monitor implements the <<reference:service-assurance/introduction.adoc#ref-service-assurance-monitors-common-parameters, Common Configuration Parameters>>.

WARNING: 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:

[source, xml]
----
<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.
