LibreNMS Integration

Wire CertTracker into LibreNMS so certificate health appears alongside the rest of your monitoring — same alert console, same on-call rotation, same dashboards.

Plan required. This recipe uses the CertTracker API, which is a Business and Enterprise plan feature. See API access for token creation.

The integration is pull-based: LibreNMS runs a small check_certtracker script per service, which calls a CertTracker API endpoint, parses the response, and emits a nagios-format status line. CertTracker never originates connections to LibreNMS, so there is no inbound firewall change required on the LibreNMS side.

Architecture

+--------------------------+         +-----------------------+
|  LibreNMS server         |         |  CertTracker          |
|                          |         |                       |
|  Services                |  HTTPS  |  /api/v1/integrations |
|   check_certtracker --------------->|     /librenms/check  |
|   (per host)             |         |                       |
|        |                 |         +-----------------------+
|        v                 |
|  alerts.php -> notifiers |
+--------------------------+

Step 1: Mint an API token in CertTracker

1. Sign into CertTracker as an admin.
2. Administration → API Tokens → Create token.
3. Name it something obvious like librenms-prod.
4. Copy the raw token now — it is shown exactly once.

Step 2: Drop the check script on your LibreNMS host

Save the following as /usr/lib/nagios/plugins/check_certtracker (or wherever your LibreNMS install keeps its custom plugins). The script is dependency-free apart from curl.

#!/bin/bash
# /usr/lib/nagios/plugins/check_certtracker
#
# LibreNMS service-check plugin that calls CertTracker's API and
# emits nagios-format output. Drives an alerting model where each
# monitor in CertTracker becomes a service in LibreNMS.
#
# Usage:
#   check_certtracker <base_url> <fqdn:port>
#
# Example:
#   check_certtracker https://certtracker.12squared.com www.example.com:443
#
# Required environment:
#   CERTTRACKER_TOKEN   bearer token from Administration -> API Tokens

set -u

BASE_URL="${1:?usage: check_certtracker <base_url> <fqdn:port>}"
LABEL="${2:?usage: check_certtracker <base_url> <fqdn:port>}"
TOKEN="${CERTTRACKER_TOKEN:?CERTTRACKER_TOKEN env var required}"

# Trim trailing slash from base URL so the path concat is clean.
BASE_URL="${BASE_URL%/}"

TMP="$(mktemp)"
trap 'rm -f "$TMP"' EXIT

HTTP_STATUS=$(curl -sS -o "$TMP" -w '%{http_code}' \
    -H "Authorization: Bearer ${TOKEN}" \
    -D - \
    "${BASE_URL}/api/v1/integrations/librenms/check?label=${LABEL}" \
    | head -n -1 > /dev/null; echo "${PIPESTATUS[0]}")

# The header dump + body interleaving above is finicky; redo cleanly
# with two-pass: one for headers, one for body, since LibreNMS plugins
# benefit from straightforward shell.
HEADERS=$(curl -sSI -H "Authorization: Bearer ${TOKEN}" \
    "${BASE_URL}/api/v1/integrations/librenms/check?label=${LABEL}")
BODY=$(curl -sS -H "Authorization: Bearer ${TOKEN}" \
    "${BASE_URL}/api/v1/integrations/librenms/check?label=${LABEL}")

EXIT_CODE=$(printf '%s\n' "$HEADERS" \
    | awk 'tolower($1) == "x-nagios-exit-code:" {print $2}' \
    | tr -d '\r')

if [[ -z "$EXIT_CODE" ]]; then
    echo "UNKNOWN - CertTracker returned no X-Nagios-Exit-Code header"
    exit 3
fi

printf '%s\n' "$BODY"
exit "$EXIT_CODE"

Make it executable:

sudo chmod +x /usr/lib/nagios/plugins/check_certtracker

Quick smoke test from the LibreNMS host:

export CERTTRACKER_TOKEN='ct_live_...'
/usr/lib/nagios/plugins/check_certtracker \
    https://certtracker.12squared.com \
    www.example.com:443
echo "exit=$?"

Expected output for a healthy monitor:

OK - TLSv1.3 · Certificate valid for 49d|days_to_expiry=49;30;7;; advisories=0;1;1;0; response_ms=87;;;0;
exit=0

Step 3: Store the token

LibreNMS plugins are typically invoked by its scheduler with a clean environment. Add the token export to /etc/default/librenms (Debian/Ubuntu) or wherever your installation reads global env from:

echo 'CERTTRACKER_TOKEN=ct_live_...' | sudo tee -a /etc/default/librenms
sudo systemctl restart librenms-cron  # or whatever your install uses

Alternatively, hardcode the token into the check command in LibreNMS — but the env-var pattern keeps secrets out of the LibreNMS DB.

Step 4: Register the check command in LibreNMS

In the LibreNMS web UI:

1. Services → Service Templates → +
2. Name: CertTracker
3. Description: SSL certificate + TLS posture from CertTracker
4. Check command:
   /usr/lib/nagios/plugins/check_certtracker https://certtracker.12squared.com $1
5. Parameter $1: the monitor label (e.g. www.example.com:443)
6. Save

Step 5: Attach the service to your hosts

For each host that CertTracker monitors:

1. Devices → (host) → Services → +
2. Pick the CertTracker template you just made.
3. Set the parameter to <fqdn>:<port> matching the CertTracker monitor.
4. Save.

LibreNMS will start scheduling the check on the same cadence as your other services — typically every 5 minutes.

Step 6: Alerting

LibreNMS's standard alert rules work directly on the exit code. Two recommended rules:

service_status = 1 fires when a cert is within 30 days of expiry, a TLS handshake is failing, or there is at least one open advisory (weak cipher, deprecated protocol, weak key, etc.). service_status = 2 fires when a cert has expired, is within 7 days, or the endpoint is unreachable.

Optional: bulk discovery

If you have many monitors, fetch them with a one-shot script instead of manually adding services:

curl -sSH "Authorization: Bearer $CERTTRACKER_TOKEN" \
    https://certtracker.12squared.com/api/v1/integrations/librenms/services \
    | jq -r '.services[].label'

Pipe the labels into your own automation that uses the LibreNMS API to attach services in batch.

Troubleshooting

What's covered, what's not

This integration surfaces cert expiry, TLS reachability, and the seven advisory categories (weak cipher, deprecated protocol, weak signature, weak public-key size, excessive validity, hostname mismatch, modern-client-incompatible, OCSP, HSTS) as a single LibreNMS service status per monitor.

It does not export full TLS audit data (every cipher in the offer list, the chain walk, CAA records) — for those, point a dashboard at the JSON endpoints directly. See API access.