Enable TLS encryption

Enabling TLS encrypts the communication between clients and the InfluxDB server. When configured with a signed certificate, TLS also allows clients to verify the authenticity of the InfluxDB server.

Follow steps to set up TLS over HTTPS, connect to your server, and troubleshoot problems:

InfluxData strongly recommends enabling HTTPS, especially if you plan on sending requests to InfluxDB over a network.

Obtain requirements

To enable HTTPS with InfluxDB, you need a Transport Layer Security (TLS) certificate, also known as a Secured Sockets Layer (SSL) certificate. InfluxDB supports three types of TLS certificates:

Single domain certificates signed by a Certificate Authority (CA)

Single domain certificates provide cryptographic security to HTTPS requests and allow clients to verify the identity of the InfluxDB server. These certificates are signed and issued by a trusted, third-party Certificate Authority (CA). With this certificate option, every InfluxDB instance requires a unique single domain certificate.

Wildcard certificates signed by a Certificate Authority

Wildcard certificates provide cryptographic security to HTTPS requests and allow clients to verify the identity of the InfluxDB server. Wildcard certificates can be used across multiple InfluxDB instances on different servers.

Self-signed certificates

Self-signed certificates are not signed by a trusted, third-party CA. Unlike CA-signed certificates, self-signed certificates only provide cryptographic security to HTTPS requests. They do not allow clients to verify the identity of the InfluxDB server. With this certificate option, every InfluxDB instance requires a unique self-signed certificate. You can generate a self-signed certificate on your own machine.

Configure InfluxDB to use TLS

  1. Download or generate certificate files
  2. Set certificate file permissions
  3. Run influxd with TLS flags
  4. Verify TLS connection

Download or generate certificate files

Choose one of the following:

Download and install CA certificate files

If using a certificate signed by a CA, follow their instructions to download and install the certificate files. Note the location where certificate files are installed, and then continue to set certificate file permissions.

Where are my certificates?

The location of your certificate files depends on your system, domain, and certificate authority.

For example, if Let’s Encrypt is your CA and you use certbot to install certificates, the default location is /etc/letsencrypt/live/$domain. For more information about Let’s Encrypt certificate paths, see Where are my certificates?

Generate self-signed certificates

To generate self-signed certificates, use the openssl command on your system.

The following example:

  1. Configures Subject Alternative Name (subjectAltName, SAN) for your TLS certificate.
  2. Generates certificates located in /etc/ssl for Unix-like and Windows systems.

For example purposes only, the code creates an unencrypted private key.

Encrypt private keys

Use encrypted keys to enhance security. If you must use an unencrypted key, ensure it’s stored securely and has appropriate file permissions.

  1. # Create a temporary configuration file that defines properties for
  2. # the Subject Alternative Name (SAN) extension
  3. cat > san.cnf <<EOF
  4.    [req]
  5.    distinguished_name = req_distinguished_name
  6.    req_extensions = v3_req
  7.    prompt = no
  9.    [req_distinguished_name]
  10.    C = US
  11.    ST = California
  12.    L = San Francisco
  13.    O = Example Company
  14.    OU = IT Department
  15.    CN = example.com
  17.    [v3_req]
  18.    keyUsage = keyEncipherment, dataEncipherment
  19.    extendedKeyUsage = serverAuth
  20.    subjectAltName = @alt_names
  22.    [alt_names]
  23.    DNS.1 = example.com
  24.    DNS.2 = www.example.com
  25.    IP.1 = 10.1.2.3
  26. EOF
  28. # Generate a private key and certificate signing request (CSR)
  29. # using the configuration file 
  30. openssl req -new -newkey rsa:2048 -nodes \
  31.   -keyout /etc/ssl/influxdb-selfsigned.key \
  32.   -out /etc/ssl/influxdb-selfsigned.csr \
  33.   -config san.cnf
  35. # Generate the self-signed certificate
  36. openssl x509 -req -in /etc/ssl/influxdb-selfsigned.csr \
  37.   -signkey /etc/ssl/influxdb-selfsigned.key \
  38.   -out /etc/ssl/influxdb-selfsigned.crt \
  39.   -days NUMBER_OF_DAYS \
  40.   -extensions v3_req -extfile san.cnf
  42. # Remove the temporary configuration file
  43. rm san.cnf

Replace the following with your own values:

  • NUMBER_OF_DAYS: the number of days for files to remain valid
  • /etc/ssl: the SSL configurations directory for your system
  • Configuration field values in req_distinguished_name and alt_names–for example, in the [alt_names] section, set the domain names and IP addresses you use to access your InfluxDB server.

The output is a private key and a CSR that includes the specified domain names and IP address in the Subject Alternative Name SAN extension. The resulting certificate is valid for example.com, www.example.com, and the IP address 10.1.2.3.

Set certificate file permissions

The user running InfluxDB must have read permissions on the TLS certificate files.

You may opt to set up multiple users, groups, and permissions. Ultimately, make sure all users running InfluxDB have read permissions for the TLS certificate.

In your terminal, run chown to set the owner and chmod to set permissions on your installed certificate files.

The following example shows how to transfer the ownership to the user and group influxdb and set read permissions on the self-signed certificate and key files generated in the preceding step:

  1. sudo chown influxdb: /etc/ssl/influxdb-selfsigned.crt /etc/ssl/influxdb-selfsigned.key
  2. sudo chmod 644 /etc/ssl/influxdb-selfsigned.crt
  3. sudo chmod 600 /etc/ssl/influxdb-selfsigned.key

Verify certificate and key files

To ensure that the certificate and key files are correct and match each other, enter the following commands in your terminal:

  1. openssl x509 -noout -modulus -in /etc/ssl/influxdb-selfsigned.crt | openssl md5
  2. openssl rsa -noout -modulus -in /etc/ssl/influxdb-selfsigned.key | openssl md5

Run influxd with TLS flags

To start InfluxDB with TLS command line flags, enter the following command with paths to your key and certificate files:

  1. influxd \
  2.   --tls-cert="/etc/ssl/influxdb-selfsigned.crt" \
  3.   --tls-key="/etc/ssl/influxdb-selfsigned.key" > /var/log/influxdb.log 2>&1 &

If successful, InfluxDB runs in the background and logs to influxdb.log.

Verify TLS connection

To test your certificates, access InfluxDB using the https:// protocol–for example, using cURL:

  1. curl --verbose https://localhost:8086/api/v2/ping

If using a self-signed certificate, skip certificate verification–for example, in a cURL command, pass the -k, --insecure flag:

  1. curl --verbose --insecure https://localhost:8086/api/v2/ping

If successful, the curl --verbose output shows a TLS handshake–for example:

  1. * [CONN-0-0][CF-SSL] TLSv1.3 (IN), TLS handshake

You can further configure TLS settings using tls-min-version and tls-strict-ciphers.

Connect Telegraf to a secured InfluxDB instance

To connect Telegraf to an InfluxDB 2.7 instance with TLS enabled, update the following influxdb_v2 output settings in your Telegraf configuration file:

  • Update URLs to use HTTPS instead of HTTP.
  • If using a self-signed certificate, uncomment and set insecure_skip_verify to true.

Example Telegraf configuration

  1. ###############################################################################
  2. #                            OUTPUT PLUGINS                                   #
  3. ###############################################################################
  5. # Configuration for sending metrics to InfluxDB
  6. [[outputs.influxdb_v2]]
  7.   ## The URLs of the InfluxDB cluster nodes.
  8.   ##
  9.   ## Multiple URLs can be specified for a single cluster, only ONE of the
  10.   ## urls will be written to each interval.
  11.   urls = ["https://127.0.0.1:8086"]
  13.   [...]
  15.   ## Optional TLS Config for use on HTTP connections.
  16.   [...]
  17.   ## Use TLS but skip chain & host verification
  18.   insecure_skip_verify = true

Restart Telegraf using the updated configuration file.

Troubleshoot TLS

Identify and resolve issues after activating TLS.

Check InfluxDB logs

Review the InfluxDB logs for any error messages or warnings about the issue.

Example TLS error

  1. msg="http: TLS handshake error from [::1]:50476:
  2. remote error: tls: illegal parameter" log_id=0rqN8H_0000 service=http

Verify certificate and key Files

To ensure that the certificate and key files are correct and match each other, enter the following command in your terminal:

  1. openssl x509 -noout -modulus -in /etc/ssl/influxdb-selfsigned.crt | openssl md5
  2. openssl rsa -noout -modulus -in /etc/ssl/influxdb-selfsigned.key | openssl md5

Test with OpenSSL

Use OpenSSL to test the server’s certificate and key–for example, enter the following command in your terminal:

  1. openssl s_client -connect localhost:8086 -CAfile /etc/ssl/influxdb-selfsigned.crt

Check file permissions

Ensure that the InfluxDB process has read access to the certificate and key files–for example, enter the following command to set file permissions:

  1. sudo chmod 644 /etc/ssl/influxdb-selfsigned.crt
  2. sudo chmod 600 /etc/ssl/influxdb-selfsigned.key

Verify TLS configuration

Ensure that the TLS configuration in InfluxDB is correct. Check the paths to the certificate and key files in the InfluxDB configuration or command line flags.

Example error: cannot validate certificate for <IP_ADDRESS>

  1. Sep 25 14:00:02 host influxd-systemd-start.sh[11782]: ts=2024-09-25T12:00:02.055617Z lvl=error msg="Unable to gather" log_id=0rr6jG30000 service=scraper scraper-name="new target" error="Get \"https://10.1.2.3:8086/metrics\": tls: failed to verify certificate: x509: cannot validate certificate for 10.1.2.3 because it doesn't contain any IP SANs"
  2. Sep 25 14:00:02 host influxd-systemd-start.sh[11782]: ts=2024-09-25T12:00:02.055397Z lvl=info msg="http: TLS handshake error from 10.1.2.3:46380: remote error: tls: bad certificate" log_id=0rr6jG30000 service=http

If you access your InfluxDB server via IP address, then include the address in your subjectAltName configuration.

Update OpenSSL and InfluxDB

Ensure that you are using the latest versions of OpenSSL and InfluxDB, as updates may include fixes for TLS-related issues.

security authentication tls https ssl