X.509 certificate

Plugin: go.d.plugin Module: x509check

Overview

This collector tracks how long X.509 (SSL/TLS) certificates remain valid and whether they have been revoked.

It reads the certificate that a website or any other TLS service presents, including mail servers that use STARTTLS, or a certificate stored in a local file. It charts the time left until the certificate expires and, optionally, the expiration of every certificate in the chain and the revocation status of the server certificate. Stock alerts fire before a certificate expires and when it is revoked.

Every collection interval, each job connects to its source and completes a TLS handshake, after a STARTTLS command for smtp:// sources, to read the certificates the server presents. A file:// source is read from disk instead. The collector never requests a page or sends mail.

With check_revocation_status enabled, the collector also downloads the CRLs and queries the OCSP responders listed in the server certificate, and fetches the issuer certificate listed in it to verify the CRL and build the OCSP request. These requests go to the HTTP or HTTPS URLs in the certificate, so the Agent host needs outbound access to them. Each request times out after 10 seconds; timeout does not apply to them. Each job reuses a CRL's result for a certificate until the next update time the CRL states.

This collector is supported on all platforms.

This collector supports collecting metrics from multiple instances of this integration.

Permission	Needed when
The netdata user can read the file	tls_ca, tls_cert or tls_key is set

Default Behavior

Auto-Detection

This integration doesn't support auto-detection.

Limits

• The handshake verifies the certificate like any TLS client. A certificate that is expired, self-signed, or issued for another name fails collection: a running job's charts show gaps instead of the time left, and a job that starts in this state stays stopped unless autodetection_retry is set. Set tls_ca for a private CA, or tls_skip_verify to read such certificates anyway.
• A file:// source provides only the first certificate in the file, so check_full_chain has no effect there.
• Revocation status is checked for the server certificate only. A certificate that lists no CRL or OCSP URL is always reported as not revoked (LDAP CRL URLs are skipped), and an OCSP unknown answer is reported as revoked. When the issuer certificate cannot be downloaded, a CRL is used without checking its signature.
• With an smtp:// source, timeout covers the whole SMTP exchange. A mail server that delays its greeting, a common anti-spam measure on port 25, needs a timeout longer than that delay.

Performance Impact

The default configuration for this integration is not expected to impose a significant performance impact on the system.

Setup

You can configure the x509check collector in two ways:

Method	Best for	How to
UI	Fast setup without editing files	Go to Nodes → Configure this node → Collectors → Jobs, search for x509check, then click + to add a job.
File	If you prefer configuring via file, or need to automate deployments (e.g., with Ansible)	Edit go.d/x509check.conf and add a job.

important

UI configuration requires paid Netdata Cloud plan.

Prerequisites

No action required.

Configuration

Options

The following options can be defined globally: update_every, autodetection_retry.

Config options

Group	Option	Description	Default	Required
Target	source	Where to read the certificate, as a URL: https, tcp, tcp4 or tcp6 for a TLS server, smtp for an SMTP server with STARTTLS, file for a local PEM file.		yes
	timeout	Certificate retrieval timeout, in seconds. Covers the connection, the SMTP exchange and the TLS handshake.	2	no
TLS	tls_server_name	Host name sent to the server (SNI) and checked against the certificate, instead of the host in source. Leave empty to use the host in source.		no
	tls_skip_verify	Skip TLS certificate and hostname verification, so certificates that are self-signed, expired or issued for another name are still read.	no	no
	tls_ca	Path to a CA bundle used to verify the server certificate. Leave empty to use the system trust store.		no
	tls_cert	Path to a client certificate file for mutual TLS. Requires a client key.		no
	tls_key	Path to the client key file for mutual TLS. Requires a client certificate.		no
Checks	check_full_chain	Report the expiration time of every certificate the server sends, such as intermediates, not only the server certificate.	no	no
	check_revocation_status	Check whether the server certificate has been revoked, using the CRL and OCSP endpoints listed in it.	no	no
Collection	update_every	Data collection interval, in seconds.	60	no
	autodetection_retry	How often to retry the initial connection when the job fails to start, in seconds. Zero disables retries.	0	no
Virtual Node	vnode	Associates this job with a Virtual Node.		no

source

Network sources need a port. The host name is sent for SNI and, unless tls_skip_verify is set, checked against the certificate. To use another name for both while connecting to the same address, set tls_server_name.

Scheme	Use for	Example
https, tcp	Websites and services that start TLS on connect (LDAPS, IMAPS, SMTPS on port 465)	https://example.com:443
tcp4, tcp6	The same, over IPv4 or IPv6 only	tcp6://example.com:443
smtp	SMTP servers that upgrade with STARTTLS (ports 25 and 587)	smtp://smtp.example.com:587
file	A PEM file on the Agent host; note the three slashes before an absolute path	file:///etc/ssl/certs/example.com.pem

tls_server_name

The job still connects to the host and port in source, so it can read the certificate issued for one name from a server reached at another address:

• each site hosted on one IP address and port, with one job per site;
• an origin server behind a load balancer or CDN, reached at its own address;
• each node of a pool, reached at its address and verified against the shared host name.

A host name set here is sent as SNI even when source is an IP address. An IP address set here sends no SNI and is checked against the IP addresses listed in the certificate. A file:// source does not accept this option.

check_full_chain

Servers usually leave the root certificate out of the chain they send, so it is charted only when the server includes it.

check_revocation_status

The revocation status chart exists only for the server certificate (depth 0). It appears with the first check that determines a status.

via UI

Configure the x509check collector from the Netdata web interface:

1. Go to Nodes.
2. Select the node where you want the x509check data-collection job to run and click the ⚙ (Configure this node). That node will run the data collection.
3. The Collectors → Jobs view opens by default.
4. In the Search box, type x509check (or scroll the list) to locate the x509check collector.
5. Click the + next to the x509check collector to add a new job.
6. Fill in the job fields, then click Test to verify the configuration and Submit to save.
   • Test validates the provided settings and checks the collector's startup prerequisites. Successful validation does not guarantee that every metric will be available during collection.
   • If it fails, an error message appears with details (for example, connection refused, timeout, or command execution errors), so you can adjust and retest.

via File

The configuration file name for this integration is go.d/x509check.conf.

The file format is YAML. Generally, the structure is:

update_every: 1
autodetection_retry: 0
jobs:
  - name: some_name1
  - name: some_name2

You can edit the configuration file using the edit-config script from the Netdata config directory.

cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config go.d/x509check.conf

Examples

Website

The certificate of an HTTPS website.

Config

jobs:
  - name: example_com
    source: https://example.com:443

Other TLS service

A service that starts TLS on connect, such as LDAPS, IMAPS or SMTPS on port 465.

Config

jobs:
  - name: ldap_example_com
    source: tcp://ldap.example.com:636

SMTP server with STARTTLS

A mail server that upgrades the connection with STARTTLS.

Config

jobs:
  - name: smtp_example_com
    source: smtp://smtp.example.com:587

Local certificate file

A PEM certificate file on the Agent host.

Config

jobs:
  - name: example_com_file
    source: file:///etc/ssl/certs/example.com.pem

Full chain and revocation status

Also track the intermediate certificates the server sends, and check whether the server certificate has been revoked.

Config

jobs:
  - name: example_com
    source: https://example.com:443
    check_full_chain: yes
    check_revocation_status: yes

Self-signed certificate

A certificate the Agent host does not trust. To verify it against your own CA instead, set tls_ca.

Config

jobs:
  - name: internal_example
    source: https://internal.example.com:443
    tls_skip_verify: yes

Several sites on one address

A server that hosts several sites on one IP address and port, checked locally: every job connects to the same address and asks for a different site.

Config

jobs:
  - name: site_a_local
    source: https://127.0.0.1:443
    tls_server_name: site-a.example.com

  - name: site_b_local
    source: https://127.0.0.1:443
    tls_server_name: site-b.example.com

Multi-instance

Note: When you define multiple jobs, their names must be unique.

Certificates of several websites.

Config

jobs:
  - name: example_com
    source: https://example.com:443

  - name: example_org
    source: https://example.org:443

  - name: example_net
    source: https://example.net:443

Alerts

The following alerts are available:

Alert name	On metric	Description
Alert name x509check_days_until_expiration	On metricx509check.time_until_expiration	DescriptionSSL cert expiring soon (${label:source} cn:${label:common_name})
Alert name x509check_revocation_status	On metricx509check.revocation_status	DescriptionSSL cert revoked (${label:source})

Metrics

Metrics grouped by scope.

The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.

When a certificate cannot be read, or its revocation status cannot be determined, the affected charts show gaps rather than zeros.

Per certificate

One certificate presented by the source; only the server certificate unless check_full_chain is enabled.

Labels:

Label	Description
source	The source option of the job.
common_name	Common name (CN) of the certificate subject, for example example.com.
depth	Position of the certificate in the chain, 0 for the server certificate and higher values for its issuers toward the root.

Metrics:

Metric	Description	Dimensions	Unit
x509check.time_until_expiration	Time Until Certificate Expiration	expiry	seconds
x509check.revocation_status	Revocation Status	not_revoked, revoked	boolean

Troubleshooting

Diagnostics

Debug Mode

Important: Debug mode is not supported for data collection jobs created via the UI using the Dyncfg feature.

To troubleshoot issues with the x509check collector, run the go.d.plugin with the debug option enabled. The output should give you clues as to why the collector isn't working.

• Navigate to the plugins.d directory, usually at /usr/libexec/netdata/plugins.d/. If that's not the case on your system, open netdata.conf and look for the plugins setting under [directories].

  cd /usr/libexec/netdata/plugins.d/

• Switch to the netdata user.

  sudo -u netdata -s

• Run the go.d.plugin to debug the collector:

  ./go.d.plugin -d -m x509check

  To debug a specific job:

  ./go.d.plugin -d -m x509check -j jobName

Getting Logs

If you're encountering problems with the x509check collector, follow these steps to retrieve logs and identify potential issues:

• Run the command specific to your system (systemd, non-systemd, or Docker container).
• Examine the output for any warnings or error messages that might indicate issues. These messages should provide clues about the root cause of the problem.

System with systemd

Use the following command to view logs generated since the last Netdata service restart:

journalctl _SYSTEMD_INVOCATION_ID="$(systemctl show --value --property=InvocationID netdata)" --namespace=netdata --grep x509check

System without systemd

Locate the collector log file, typically at /var/log/netdata/collector.log, and use grep to filter for collector's name:

grep x509check /var/log/netdata/collector.log

Note: This method shows logs from all restarts. Focus on the latest entries for troubleshooting current issues.

Docker Container

If your Netdata runs in a Docker container named "netdata" (replace if different), use this command:

docker logs netdata 2>&1 | grep x509check

Known Errors

config validation: source is not set

Cause

The job has no source option.

Fix

Set source to the URL of the certificate, for example https://example.com:443.

config validation: timeout must be greater than zero

Cause

timeout is zero or negative.

Fix

Set timeout to a positive number of seconds, or remove it to use the default.

certificate provider init: unsupported scheme scheme in source source

Cause

source does not start with a supported scheme. A plain http:// URL, a udp:// URL (TLS does not run over UDP), or a host name and port without a scheme produce this error.

Fix

Use one of the schemes listed for the source option, for example https://example.com:443.

certificate provider init: source parse: parse source: first path segment in URL cannot contain colon

Cause

source is an IP address and port without a scheme.

Fix

Add the scheme, for example tcp://192.0.2.10:443.

certificate provider init: tls_server_name cannot be used with a file:// source

Cause

tls_server_name is set on a job whose source is a local file, which has no server to ask for a certificate.

Fix

Remove tls_server_name from the job, or point source at the server that presents the certificate.

error on dial to host: dial tcp: address host: missing port in address

Cause

A network source has no port; the collector does not assume one from the scheme.

Fix

Add the port, for example https://example.com:443 or smtp://smtp.example.com:587.

error on dial to host:port: dial tcp: lookup host: no such host

When

The resolver address can appear after the host name, as in lookup example.com on 127.0.0.53:53.

Cause

The host name in source does not resolve from the Agent host.

Fix

Check the host name, and the DNS configuration of the Agent host.

error on dial to host:port: dial tcp address: connect: connection refused

Cause

Nothing listens on that port, or a firewall rejects the connection from the Agent host.

Fix

Check the host and port in source, and that the Agent host can reach them.

error on dial to host:port: dial tcp address: i/o timeout

Cause

The connection was not established within timeout, usually because a firewall drops it silently.

Fix

Check that the Agent host can reach the host and port in source. Otherwise raise timeout.

error on SSL handshake with host:port: context deadline exceeded

Cause

The server did not complete the TLS handshake within timeout. The port may expect a STARTTLS protocol first, or the server is slow or filtered.

Fix

Check that the port starts TLS on connect. For SMTP on ports 25 or 587, use an smtp:// source. Otherwise raise timeout.

error on creating SMTP client: read tcp address: i/o timeout

Cause

The server sent no SMTP greeting within timeout. A port that starts TLS on connect, such as SMTPS on port 465, never sends a plain greeting, and some mail servers delay their greeting to slow down spam.

Fix

For a port that starts TLS on connect, use tcp:// instead of smtp://. Otherwise raise timeout.

error on startTLS with host:port: reply

Cause

The SMTP server rejected the STARTTLS command, usually because it does not offer STARTTLS on that port.

Fix

Check that the server offers STARTTLS on that port. For a port that starts TLS on connect, such as 465, use tcp:// instead of smtp://.

tls: first record does not look like a TLS handshake

Cause

The port answers in plain text, for example HTTP on port 80 or SMTP before STARTTLS.

Fix

Point source at the TLS port, or use an smtp:// source for SMTP with STARTTLS.

tls: server selected unsupported protocol version version

Cause

The server offers only TLS 1.0 or 1.1, which the collector does not accept.

Fix

Enable TLS 1.2 or later on the server. Until then, monitor the certificate file with a file:// source on a host that can read it.

tls: failed to verify certificate: x509: certificate signed by unknown authority

Cause

The certificate is self-signed or issued by a CA that the Agent host does not trust.

Fix

Set tls_ca to the CA certificate that issued it, or set tls_skip_verify: yes.

tls: failed to verify certificate: x509: certificate has expired or is not yet valid: current time now is after not_after

Cause

The certificate has expired, or the clock of the Agent host is wrong. While verification fails, a running job's charts show gaps instead of the time left.

Fix

Renew the certificate, or correct the clock. To keep charting an expired certificate, set tls_skip_verify: yes.

tls: failed to verify certificate: x509: certificate is valid for names, not host

Cause

The host name in source, or tls_server_name when it is set, is not one of the names in the certificate.

Fix

Use a host name the certificate covers, in source or in tls_server_name, or set tls_skip_verify: yes.

tls: failed to verify certificate: x509: cannot validate certificate for ip because it doesn't contain any IP SANs

Cause

The certificate is checked against an IP address, from source or tls_server_name, and lists only host names.

Fix

Use the host name of the service in source, or keep the address in source and set tls_server_name to that host name.

tls: failed to verify certificate: x509: certificate relies on legacy Common Name field, use SANs instead

Cause

The certificate names its host only in the Common Name and has no Subject Alternative Names.

Fix

Reissue the certificate with Subject Alternative Names, or set tls_skip_verify: yes.

error on reading path: open path: permission denied

Cause

The collector cannot read the certificate file or one of its parent directories.

Fix

Grant the netdata user read access to the file, for example setfacl -m u:netdata:r /etc/ssl/certs/example.com.pem.

error on reading path: open path: no such file or directory

Cause

The file does not exist at that path. A file:// URL with two slashes before an absolute path, such as file://etc/ssl/cert.pem, drops the first directory.

Fix

Use three slashes before an absolute path, for example file:///etc/ssl/certs/example.com.pem.

error on decoding path: PEM decode failed (not a valid PEM file)

Cause

The file is not in PEM format, for example a binary DER certificate.

Fix

Convert it to PEM: openssl x509 -inform der -in cert.der -out cert.pem.

error on parsing certificate path: invalid X.509 certificate

Cause

The first PEM block in the file is not a certificate, for example a private key.

Fix

Point source at a file whose first PEM block is the certificate.

create tls config: could not read certificate path: reason

Cause

The file set in tls_ca or tls_cert does not exist, or the netdata user cannot read it.

Fix

Check the path, and grant the netdata user read access to the file.

create tls config: could not read key path: reason

Cause

The file set in tls_key does not exist, or the netdata user cannot read it.

Fix

Check the path, and grant the netdata user read access to the file.

create tls config: could not parse any PEM certificates path

Cause

The file set in tls_ca contains no PEM certificate.

Fix

Point tls_ca at a PEM file with the CA certificates.

create tls config: could not parse keypair cert:key

Cause

The files set in tls_cert and tls_key are not a matching PEM certificate and private key.

Fix

Point tls_cert and tls_key at the certificate and the private key of the same pair.

revocation status check for source failed: reason

When

check_revocation_status is enabled.

Cause

A CRL listed in the certificate could not be downloaded, parsed or verified (reason names the URL; only version 2 CRLs up to 64 MiB are accepted), or the certificate is expired or not yet valid. The revocation status chart shows a gap.

Fix

Check that the Agent host can reach the CRL URLs listed in the certificate, and renew an expired certificate. For an unsupported crl version reason, have the CA issue version 2 CRLs (with OpenSSL, set crlnumber in the CA configuration).

revocation status of source could not be determined

When

check_revocation_status is enabled.

Cause

No OCSP responder listed in the certificate returned a usable answer, or the issuer certificate needed for the OCSP request is not listed or could not be downloaded. The revocation status chart shows a gap.

Fix

Check that the Agent host can reach the OCSP and issuer certificate URLs listed in the certificate.