Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #5616 from influxdata/fix-enable-tls 

fix(oss): Update TLS example using openssl and including Subject Alte…
pull/5615/head^2
Jason Stirnaman 2024-09-25 09:25:54 -05:00 committed by GitHub
parent 4f2262a1ff db42ace4ec
commit e4f348e797
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 216 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

185
content/influxdb/v2/admin/security/enable-tls.md
View File

@ -23,7 +23,8 @@ To set up TLS over HTTPS, do the following:
- [Self-signed certificates](#self-signed-certificates)
- [Configure InfluxDB to use TLS](#configure-influxdb-to-use-tls)
- [Connect Telegraf to a secured InfluxDB instance](#connect-telegraf-to-a-secured-influxdb-instance)
- [Example configuration](#example-configuration)
- [Example Telegraf configuration](#example-telegraf-configuration)
- [Troubleshoot TLS](#troubleshoot-tls)
{{% warn %}}
InfluxData **strongly recommends** enabling HTTPS, especially if you plan on sending requests to InfluxDB over a network.
@ -58,7 +59,12 @@ You can generate a self-signed certificate on your own machine.
## Configure InfluxDB to use TLS
1. **Download or generate certificate files**
1. [Download or generate certificate files](#1-download-or-generate-certificate-files)
2. [Set certificate file permissions](#2-set-certificate-file-permissions)
3. [Run `influxd` with TLS flags](#3-run-influxd-with-tls-flags)
4. [Verify TLS connection](#4-verify-tls-connection)
### 1. Download or generate certificate files
If using a [certificate signed by a CA](#single-domain-certificates-signed-by-a-certificate-authority-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](#set-certificate-file-permissions).
@ -74,19 +80,69 @@ You can generate a self-signed certificate on your own machine.
To generate [self-signed certificates](#self-signed-certificates), use the `openssl` command on your system.
The following example shows how to generate certificates located in `/etc/ssl`.
Files remain valid for the specified `NUMBER_OF_DAYS`.
The `openssl` command prompts you for optional fields that you can fill out or leave blank; both actions generate valid certificate files.
The following example shows how to generate certificates located in `/etc/ssl`
on Unix-like systems and Windows.
_For example purposes only, the code creates an unencrypted private key._
{{% warn %}}
#### 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.
{{% /warn %}}
```bash
sudo openssl req -x509 -nodes -newkey rsa:2048 \
# 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
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>
-days NUMBER_OF_DAYS \
-extensions v3_req -extfile san.cnf
# Remove the temporary configuration file
rm san.cnf
```
1. **Set certificate file permissions**
<span id="set-certificate-file-permissions"><span>
Replace the following with your own values:
- {{% code-placeholder-key %}}`NUMBER_OF_DAYS`{{% /code-placeholder-key %}}: the number of days for files to remain valid
- {{% code-placeholder-key %}}`/etc/ssl`{{% /code-placeholder-key %}}: the SSL configurations directory for your system
- Configuration field values in `req_distinguished_name` and `alt_names`
### 2. Set certificate file permissions
The user running InfluxDB must have read permissions on the TLS certificate files.
@ -95,33 +151,52 @@ You can generate a self-signed certificate on your own machine.
{{% /note %}}
In your terminal, run `chmod` to set permissions on your installed certificate files--for example:
```bash
sudo chmod 644 <path/to/crt>
sudo chmod 600 <path/to/key>
```
The following example shows how to set read permissions on the self-signed certificate files saved in `/etc/ssl`:
The following example shows how to set read permissions on the self-signed
certificate and key files generated in [the preceding step](#1-download-or-generate-certificate-files):
```bash
sudo chmod 644 /etc/ssl/influxdb-selfsigned.crt
sudo chmod 600 /etc/ssl/influxdb-selfsigned.key
```
2. **Run `influxd` with TLS flags**
### 3. Verify certificate and key files
Start InfluxDB with TLS command line flags:
To ensure that the certificate and key files are correct and match each other,
enter the following commands in your terminal:
```bash
openssl x509 -noout -modulus -in /etc/ssl/influxdb-selfsigned.crt | openssl md5
openssl rsa -noout -modulus -in /etc/ssl/influxdb-selfsigned.key | openssl md5
```
### 4. 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:
```bash
influxd \
--tls-cert="<path-to-crt>" \
--tls-key="<path-to-key>"
--tls-cert="/etc/ssl/influxdb-selfsigned.crt" \
--tls-key="/etc/ssl/influxdb-selfsigned.key" > /var/log/influxdb.log 2>&1 &
```
3. **Verify TLS connection**
If successful, InfluxDB runs in the background and logs to `influxdb.log`.
### 4. Verify TLS connection
To test your certificates, access InfluxDB using the `https://` protocol--for example, using cURL:
<!--pytest-codeblocks:cont-->
<!--test:nextblock
```bash
# Wait...
sleep 1 && curl --verbose --insecure https://localhost:8086/api/v2/ping
```
-->
<!--pytest.mark.skip-->
```bash
curl --verbose https://localhost:8086/api/v2/ping
```
@ -129,12 +204,16 @@ You can generate a self-signed certificate on your own machine.
If using a self-signed certificate, skip certificate verification--for example, in a cURL command,
pass the `-k, --insecure` flag:
<!--pytest.mark.skip-->
```bash
curl --verbose --insecure https://localhost:8086/api/v2/ping
```
If successful, the `curl --verbose` output shows a TLS handshake--for example:
<!--pytest.mark.skip-->
```bash
* [CONN-0-0][CF-SSL] TLSv1.3 (IN), TLS handshake
```
@ -152,7 +231,7 @@ update the following `influxdb_v2` output settings in your Telegraf configuratio
- Update URLs to use HTTPS instead of HTTP.
- If using a self-signed certificate, uncomment and set `insecure_skip_verify` to `true`.
### Example configuration
### Example Telegraf configuration
```toml
###############################################################################
@ -176,3 +255,65 @@ update the following `influxdb_v2` output settings in your Telegraf configuratio
```
Restart Telegraf using the updated configuration file.
## Troubleshoot TLS
Identify and resolve issues after activating TLS.
- [Check InfluxDB logs](#check-influxdb-logs)
- [Verify certificate and key files](#verify-certificate-and-key-files)
- [Test with OpenSSL](#test-with-openssl)
- [Check file permissions](#check-file-permissions)
- [Verify TLS configuration](#verify-tls-configuration)
- [Update OpenSSL and InfluxDB](#update-openssl-and-influxdb)
### Check InfluxDB logs
Review the InfluxDB logs for any error messages or warnings about the issue.
#### Example TLS error
```text
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:
```bash
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:
```bash
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:
```bash
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.
### 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.

30
test/scripts/prepare-content.sh
View File

@ -66,8 +66,8 @@ function substitute_placeholders {
# Shell-specific replacements.
## In JSON Heredoc
sed -i 's|"orgID": "ORG_ID"|"orgID": "$INFLUX_ORG"|g;
s|"name": "BUCKET_NAME"|"name": "$INFLUX_DATABASE"|g;' \
$file
s|"name": "BUCKET_NAME"|"name": "$INFLUX_DATABASE"|g;
' $file
# Replace remaining placeholders with variables.
# If the placeholder is inside of a Python os.getenv() function, don't replace it.
@ -89,39 +89,41 @@ function substitute_placeholders {
/os.getenv("ORG_ID")/! s/ORG_ID/$INFLUX_ORG/g;
/os.getenv("PASSWORD")/! s/PASSWORD/$INFLUX_PASSWORD/g;
/os.getenv("ORG_ID")/! s/ORG_ID/$INFLUX_ORG/g;
/os.getenv("RETENTION_POLICY")/! s/RETENTION_POLICY_NAME\|RETENTION_POLICY/$INFLUX_RETENTION_POLICY/g;
/os.getenv("RETENTION_POLICY")/! s/RETENTION_POLICY_NAME/$INFLUX_RETENTION_POLICY/g;
/os.getenv("RETENTION_POLICY")/! s/RETENTION_POLICY/$INFLUX_RETENTION_POLICY/g;
/os.getenv("USERNAME")/! s/USERNAME/$INFLUX_USERNAME/g;
s/exampleuser@influxdata.com/$INFLUX_EMAIL_ADDRESS/g;
s/CONFIG_NAME/CONFIG_$(shuf -i 0-100 -n1)/g;
s/TEST_RUN/TEST_RUN_$(date +%s)/g;
s|@path/to/line-protocol.txt|data/home-sensor-data.lp/g;
s|/path/to/custom/assets-dir|/app/custom-assets|g;' \
$file
s|NUMBER_OF_DAYS|365|g;
s|@path/to/line-protocol.txt|data/home-sensor-data.lp|g;
s|/path/to/custom/assets-dir|/app/custom-assets|g;
' $file
# v2-specific replacements.
sed -i 's|https:\/\/us-west-2-1.aws.cloud2.influxdata.com|$INFLUX_HOST|g;
s|influxdb2-{{< latest-patch >}}|influxdb2-${influxdb_latest_patches_v2}|g;
s|{{< latest-patch cli=true >}}|${influxdb_latest_cli_v2}|g;
s|influxdb2-{{% latest-patch %}}|influxdb2-${influxdb_latest_patches_v2}|g;
s|{{% latest-patch cli=true %}}|${influxdb_latest_cli_v2}|g;' \
$file
s|{{% latest-patch cli=true %}}|${influxdb_latest_cli_v2}|g;
' $file
# Telegraf-specific replacements
sed -i 's|telegraf-{{< latest-patch >}}|telegraf-${telegraf_latest_patches_v1}|g;
s|telegraf-{{% latest-patch %}}|telegraf-${telegraf_latest_patches_v1}|g;
s/--input-filter <INPUT_PLUGIN_NAME>\[:<INPUT_PLUGIN_NAME>\]/--input-filter cpu:influxdb/g;
s/--output-filter <OUTPUT_PLUGIN_NAME>\[:<OUTPUT_PLUGIN_NAME>\]/--output-filter influxdb_v2:file/g;' \
$file
s/--output-filter <OUTPUT_PLUGIN_NAME>\[:<OUTPUT_PLUGIN_NAME>\]/--output-filter influxdb_v2:file/g;
' $file
# Skip package manager commands.
sed -i 's|sudo dpkg.*$||g;
s|sudo yum.*$||g;' \
$file
s|sudo yum.*$||g;
' $file
# Environment-specific replacements.
# You can't use sudo with Docker.
sed -i 's|sudo ||g;' \
$file
sed -i 's|sudo ||g;
' $file
fi
done
}