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:

• Obtain requirements
• Configure InfluxDB to use TLS
• Connect Telegraf to a secured InfluxDB instance
• Troubleshoot TLS

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
• Generate self-signed certificates

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.

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.

# Create a temporary configuration file that defines properties for
# the Subject Alternative Name (SAN) extension
cat > san.cnf <<EOF
   [req]
   distinguished_name = req_distinguished_name
   req_extensions = v3_req
   prompt = no

   [req_distinguished_name]
   C = US
   ST = California
   L = San Francisco
   O = Example Company
   OU = IT Department
   CN = example.com

   [v3_req]
   keyUsage = keyEncipherment, dataEncipherment
   extendedKeyUsage = serverAuth
   subjectAltName = @alt_names

   [alt_names]
   DNS.1 = example.com
   DNS.2 = www.example.com
   IP.1 = 10.1.2.3
EOF

# Generate a private key and certificate signing request (CSR)
# using the configuration file 
openssl req -new -newkey rsa:2048 -nodes \
  -keyout /etc/ssl/influxdb-selfsigned.key \
  -out /etc/ssl/influxdb-selfsigned.csr \
  -config san.cnf

# Generate the self-signed certificate
openssl x509 -req -in /etc/ssl/influxdb-selfsigned.csr \
  -signkey /etc/ssl/influxdb-selfsigned.key \
  -out /etc/ssl/influxdb-selfsigned.crt \
  -days NUMBER_OF_DAYS \
  -extensions v3_req -extfile san.cnf

# Remove the temporary configuration file
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.

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:

sudo chown influxdb: /etc/ssl/influxdb-selfsigned.crt /etc/ssl/influxdb-selfsigned.key
sudo chmod 644 /etc/ssl/influxdb-selfsigned.crt
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:

openssl x509 -noout -modulus -in /etc/ssl/influxdb-selfsigned.crt | openssl md5
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:

influxd \
  --tls-cert="/etc/ssl/influxdb-selfsigned.crt" \
  --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:

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:

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

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

* [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

###############################################################################
#                            OUTPUT PLUGINS                                   #
###############################################################################

# Configuration for sending metrics to InfluxDB
[[outputs.influxdb_v2]]
  ## The URLs of the InfluxDB cluster nodes.
  ##
  ## Multiple URLs can be specified for a single cluster, only ONE of the
  ## urls will be written to each interval.
  urls = ["https://127.0.0.1:8086"]

  [...]

  ## Optional TLS Config for use on HTTP connections.
  [...]
  ## Use TLS but skip chain & host verification
  insecure_skip_verify = true

Restart Telegraf using the updated configuration file.

Troubleshoot TLS

Identify and resolve issues after activating TLS.

• Check InfluxDB logs
• Verify certificate and key files
• Test with OpenSSL
• Check file permissions
• Verify TLS configuration
• Update OpenSSL and InfluxDB

Check InfluxDB logs

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

Example TLS error

msg="http: TLS handshake error from [::1]:50476:
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:

openssl x509 -noout -modulus -in /etc/ssl/influxdb-selfsigned.crt | openssl md5
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:

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:

sudo chmod 644 /etc/ssl/influxdb-selfsigned.crt
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>

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"
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.