Skip to content
Guides & References

Watch the TLS certificates your devices present

An SIE recipe that records the certificate each device or service presents, so a replaced, re-issued or soon-to-expire certificate shows up in rConfig.

Script Integration EngineUpdated
On this page

Watch the TLS certificates your devices present

Certificates expire and get replaced, and both cause outages: a management interface that suddenly fails, a VPN portal with a certificate nobody expected. This recipe connects to each TLS port on a device, reads the certificate it presents, and stores who it was issued to, who issued it, when it expires and its fingerprint. A replaced certificate shows up as a change, and the expiry date is there to search and report on.


When to use it

  • You want a history of the certificates on management interfaces, VPN portals, load balancer virtual servers or any HTTPS service.
  • You want to find certificates that expire soon by searching stored configs, without a separate tool.

It only reads what the device shows to any client. It needs no login.


What you need

  • openssl 1.1.1 or later on the rConfig server (openssl version). Older releases don’t support -ext.

The template

sie-tls-template.yml
main:
name: "SIE - TLS certificates"
desc: "Records the certificate presented on each TLS port"
connect:
timeout: 120
idletimeout: 60
idleTimeout: 60
protocol: script
# exit_codes is deliberately left out: any non-zero exit fails the run.
failure_criteria:
error_patterns:
- "ERROR:"
success_patterns:
- "SIE-OK: tls"

The command

List the ports to check after the address. The device name is passed too, as the name to ask for (SNI), because servers with several certificates choose one by name:

/bin/bash {script_path}tls-certs.sh {device_ip} {device_name} 443 8443

If the device name in rConfig isn’t the name clients use, put the real name in the command instead of {device_name}.


The script

Save it as tls-certs.sh in the scripts folder.

tls-certs.sh
#!/usr/bin/env bash
#
# Record the TLS certificate presented on each port, for the rConfig Script
# Integration Engine.
#
# Usage: tls-certs.sh <host> <sni_name> <port> [port...]
#
# Certificate details go to stdout. Progress, errors and the success marker go
# to stderr. Exit code 0 when every port answered, 1 otherwise.
set -o pipefail
OPENSSL="/usr/bin/openssl"
fail() { echo "ERROR: $1" >&2; exit 1; }
HOST="${1:-}"; NAME="${2:-}"; shift 2 2>/dev/null
[ -n "$HOST" ] && [ -n "$NAME" ] && [ "$#" -gt 0 ] || fail "usage: tls-certs.sh <host> <sni_name> <port> [port...]"
for port in "$@"; do
echo "checking $HOST:$port (SNI $NAME)" >&2
pem=$(timeout 20 "$OPENSSL" s_client -connect "$HOST:$port" -servername "$NAME" \
-showcerts </dev/null 2>/dev/null \
| sed -n '/-----BEGIN CERTIFICATE-----/,/-----END CERTIFICATE-----/p; /-----END CERTIFICATE-----/q')
[ -n "$pem" ] || fail "no certificate from $HOST:$port"
details=$(printf '%s\n' "$pem" | "$OPENSSL" x509 -noout \
-subject -issuer -serial -enddate -fingerprint -sha256 \
-ext subjectAltName -nameopt RFC2253) \
|| fail "could not read the certificate from $HOST:$port"
expires=$(printf '%s\n' "$pem" | "$OPENSSL" x509 -noout -enddate | cut -d= -f2)
expires_iso=$(date -u -d "$expires" +%Y-%m-%d 2>/dev/null || echo "unknown")
echo "===== $HOST:$port ====="
printf '%s\n' "$details" | sed 's/^ *//'
echo "expires=$expires_iso"
echo
done
echo "SIE-OK: tls $# port(s) on $HOST" >&2

Only the first certificate the server sends (its own, not the chain) is recorded. A change of intermediate certificate on its own doesn’t show as a change.


What gets stored

===== 192.0.2.70:443 =====
subject=CN=vpn.example.com,O=Example Ltd
issuer=CN=Example Issuing CA 2,O=Example Ltd
serial=4F1A2B3C4D5E6F708192A3B4C5D6E7F8
notAfter=Mar 14 23:59:59 2027 GMT
sha256 Fingerprint=3A:4B:5C:6D:7E:8F:90:A1:B2:C3:D4:E5:F6:07:18:29:3A:4B:5C:6D:7E:8F:90:A1:B2:C3:D4:E5:F6:07:18:29
X509v3 Subject Alternative Name:
DNS:vpn.example.com, DNS:remote.example.com
expires=2027-03-14

The expires= line is always YYYY-MM-DD, so a config search for expires=2026-12 finds every certificate that expires in December 2026.


Adapting it

  • Services that start TLS after connecting. For SMTP, LDAP and similar, add -starttls smtp (or ldap, imap, ftp) to the s_client line for those ports.
  • The whole chain. Loop over every certificate between the BEGIN and END lines instead of stopping at the first, and print each under its own heading.
  • Many hosts behind one address. Make one command per name, each with its own SNI name, on the same device.

Type to search.