Skip to content

Commit 00765d1

Browse files
jstirnamanjstirnaman
committed
fix(oss): Update TLS example using openssl and including Subject Alternative Name (SAN)
- Example uses Subject Alternative Name extension required by modern clients. - Updated example is more verbose, but should work cross-platform. - Added troubleshooting steps. - Passes tests. - Reformatted to headings and remove list nesting.
1 parent 90674c7 commit 00765d1

File tree

2 files changed

+206
-72
lines changed

2 files changed

+206
-72
lines changed

‎content/influxdb/v2/admin/security/enable-tls.md

Lines changed: 190 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,8 @@ To set up TLS over HTTPS, do the following:
2323
- [Self-signed certificates](#self-signed-certificates)
2424
- [Configure InfluxDB to use TLS](#configure-influxdb-to-use-tls)
2525
- [Connect Telegraf to a secured InfluxDB instance](#connect-telegraf-to-a-secured-influxdb-instance)
26-
- [Example configuration](#example-configuration)
26+
- [Example Telegraf configuration](#example-telegraf-configuration)
27+
- [Troubleshoot TLS](#troubleshoot-tls)
2728

2829
{{% warn %}}
2930
InfluxData **strongly recommends** enabling HTTPS, especially if you plan on sending requests to InfluxDB over a network.
@@ -58,86 +59,164 @@ You can generate a self-signed certificate on your own machine.
5859

5960
## Configure InfluxDB to use TLS
6061

61-
1. **Download or generate certificate files**
62+
1. [Download or generate certificate files](#1-download-or-generate-certificate-files)
63+
2. [Set certificate file permissions](#2-set-certificate-file-permissions)
64+
3. [Run `influxd` with TLS flags](#3-run-influxd-with-tls-flags)
65+
4. [Verify TLS connection](#4-verify-tls-connection)
6266

63-
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.
64-
Note the location where certificate files are installed, and then continue to [set certificate file permissions](#set-certificate-file-permissions).
67+
### 1. Download or generate certificate files
6568

66-
{{% note %}}
67-
#### Where are my certificates?
69+
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.
70+
Note the location where certificate files are installed, and then continue to [set certificate file permissions](#set-certificate-file-permissions).
6871

69-
The location of your certificate files depends on your system, domain, and certificate authority.
72+
{{% note %}}
73+
#### Where are my certificates?
7074

71-
For example, if [Let's Encrypt](https://letsencrypt.org/) is your CA and you use [certbot](https://certbot.eff.org/) to install certificates, the default location is
72-
`/etc/letsencrypt/live/$domain`. For more information about Let's Encrypt certificate paths, see [Where are my certificates?](https://eff-certbot.readthedocs.io/en/latest/using.html#where-are-my-certificates)
73-
{{% /note %}}
75+
The location of your certificate files depends on your system, domain, and certificate authority.
7476

75-
To generate [self-signed certificates](#self-signed-certificates), use the `openssl` command on your system.
77+
For example, if [Let's Encrypt](https://letsencrypt.org/) is your CA and you use [certbot](https://certbot.eff.org/) to install certificates, the default location is
78+
`/etc/letsencrypt/live/$domain`. For more information about Let's Encrypt certificate paths, see [Where are my certificates?](https://eff-certbot.readthedocs.io/en/latest/using.html#where-are-my-certificates)
79+
{{% /note %}}
7680

77-
The following example shows how to generate certificates located in `/etc/ssl`.
78-
Files remain valid for the specified `NUMBER_OF_DAYS`.
79-
The `openssl` command prompts you for optional fields that you can fill out or leave blank; both actions generate valid certificate files.
81+
To generate [self-signed certificates](#self-signed-certificates), use the `openssl` command on your system.
8082

81-
```bash
82-
sudo openssl req -x509 -nodes -newkey rsa:2048 \
83-
-keyout /etc/ssl/influxdb-selfsigned.key \
84-
-out /etc/ssl/influxdb-selfsigned.crt \
85-
-days <NUMBER_OF_DAYS>
86-
```
83+
The following example shows how to generate certificates located in `/etc/ssl`
84+
on Unix-like systems and Windows.
85+
_For example purposes only, the code creates an unencrypted private key._
8786

88-
1. **Set certificate file permissions**
89-
<span id="set-certificate-file-permissions"><span>
87+
{{% warn %}}
88+
#### Encrypt private keys
89+
90+
Use encrypted keys to enhance security.
91+
If you must use an unencrypted key, ensure it's stored securely and has appropriate file permissions.
92+
{{% /warn %}}
93+
94+
```bash
95+
# Create a temporary configuration file that defines properties for
96+
# the Subject Alternative Name (SAN) extension
97+
cat > san.cnf <<EOF
98+
[req]
99+
distinguished_name = req_distinguished_name
100+
req_extensions = v3_req
101+
prompt = no
102+
103+
[req_distinguished_name]
104+
C = US
105+
ST = California
106+
L = San Francisco
107+
O = Example Company
108+
OU = IT Department
109+
CN = example.com
110+
111+
[v3_req]
112+
keyUsage = keyEncipherment, dataEncipherment
113+
extendedKeyUsage = serverAuth
114+
subjectAltName = @alt_names
115+
116+
[alt_names]
117+
DNS.1 = example.com
118+
DNS.2 = www.example.com
119+
EOF
120+
121+
# Generate a private key and certificate signing request (CSR)
122+
# using the configuration file
123+
openssl req -new -newkey rsa:2048 -nodes \
124+
-keyout /etc/ssl/influxdb-selfsigned.key \
125+
-out /etc/ssl/influxdb-selfsigned.csr \
126+
-config san.cnf
127+
128+
# Generate the self-signed certificate
129+
openssl x509 -req -in /etc/ssl/influxdb-selfsigned.csr \
130+
-signkey /etc/ssl/influxdb-selfsigned.key \
131+
-out /etc/ssl/influxdb-selfsigned.crt \
132+
-days NUMBER_OF_DAYS \
133+
-extensions v3_req -extfile san.cnf
134+
135+
# Remove the temporary configuration file
136+
rm san.cnf
137+
```
138+
139+
Replace the following with your own values:
140+
141+
- {{% code-placeholder-key %}}`NUMBER_OF_DAYS`{{% /code-placeholder-key %}}: the number of days for files to remain valid
142+
- {{% code-placeholder-key %}}`/etc/ssl`{{% /code-placeholder-key %}}: the SSL configurations directory for your system
143+
- Configuration field values in `req_distinguished_name` and `alt_names`
144+
145+
### 2. Set certificate file permissions
146+
147+
The user running InfluxDB must have read permissions on the TLS certificate files.
148+
149+
{{% note %}}You may opt to set up multiple users, groups, and permissions.
150+
Ultimately, make sure all users running InfluxDB have read permissions for the TLS certificate.
151+
{{% /note %}}
152+
153+
In your terminal, run `chmod` to set permissions on your installed certificate files--for example:
154+
The following example shows how to set read permissions on the self-signed
155+
certificate and key files generated in [the preceding step](#1-download-or-generate-certificate-files):
90156

91-
The user running InfluxDB must have read permissions on the TLS certificate files.
157+
```bash
158+
sudo chmod 644 /etc/ssl/influxdb-selfsigned.crt
159+
sudo chmod 600 /etc/ssl/influxdb-selfsigned.key
160+
```
161+
162+
### 3. Verify certificate and key files
92163

93-
{{% note %}}You may opt to set up multiple users, groups, and permissions.
94-
Ultimately, make sure all users running InfluxDB have read permissions for the TLS certificate.
95-
{{% /note %}}
164+
To ensure that the certificate and key files are correct and match each other,
165+
enter the following commands in your terminal:
96166

97-
In your terminal, run `chmod` to set permissions on your installed certificate files--for example:
167+
```bash
168+
openssl x509 -noout -modulus -in /etc/ssl/influxdb-selfsigned.crt | openssl md5
169+
openssl rsa -noout -modulus -in /etc/ssl/influxdb-selfsigned.key | openssl md5
170+
```
98171

99-
```bash
100-
sudo chmod 644 <path/to/crt>
101-
sudo chmod 600 <path/to/key>
102-
```
172+
### 4. Run `influxd` with TLS flags
103173

104-
The following example shows how to set read permissions on the self-signed certificate files saved in `/etc/ssl`:
174+
To start InfluxDB with TLS command line flags, enter the following command with
175+
paths to your key and certificate files:
105176

106-
```bash
107-
sudo chmod 644 /etc/ssl/influxdb-selfsigned.crt
108-
sudo chmod 600 /etc/ssl/influxdb-selfsigned.key
109-
```
177+
```bash
178+
influxd \
179+
--tls-cert="/etc/ssl/influxdb-selfsigned.crt" \
180+
--tls-key="/etc/ssl/influxdb-selfsigned.key" > /var/log/influxdb.log 2>&1 &
181+
```
110182

111-
2. **Run `influxd` with TLS flags**
183+
If successful, InfluxDB runs in the background and logs to `influxdb.log`.
112184

113-
Start InfluxDB with TLS command line flags:
185+
### 4. Verify TLS connection
114186

115-
```bash
116-
influxd \
117-
--tls-cert="<path-to-crt>" \
118-
--tls-key="<path-to-key>"
119-
```
187+
To test your certificates, access InfluxDB using the `https://` protocol--for example, using cURL:
120188

121-
3. **Verify TLS connection**
189+
<!--pytest-codeblocks:cont-->
122190

123-
To test your certificates, access InfluxDB using the `https://` protocol--for example, using cURL:
191+
<!--test:nextblock
192+
```bash
193+
# Wait...
194+
sleep 1 && curl --verbose --insecure https://localhost:8086/api/v2/ping
195+
```
196+
-->
124197

125-
```bash
126-
curl --verbose https://localhost:8086/api/v2/ping
127-
```
198+
<!--pytest.mark.skip-->
128199

129-
If using a self-signed certificate, skip certificate verification--for example, in a cURL command,
130-
pass the `-k, --insecure` flag:
200+
```bash
201+
curl --verbose https://localhost:8086/api/v2/ping
202+
```
131203

132-
```bash
133-
curl --verbose --insecure https://localhost:8086/api/v2/ping
134-
```
204+
If using a self-signed certificate, skip certificate verification--for example, in a cURL command,
205+
pass the `-k, --insecure` flag:
135206

136-
If successful, the `curl --verbose` output shows a TLS handshake--for example:
207+
<!--pytest.mark.skip-->
137208

138-
```bash
139-
* [CONN-0-0][CF-SSL] TLSv1.3 (IN), TLS handshake
140-
```
209+
```bash
210+
curl --verbose --insecure https://localhost:8086/api/v2/ping
211+
```
212+
213+
If successful, the `curl --verbose` output shows a TLS handshake--for example:
214+
215+
<!--pytest.mark.skip-->
216+
217+
```bash
218+
* [CONN-0-0][CF-SSL] TLSv1.3 (IN), TLS handshake
219+
```
141220

142221
You can further configure TLS settings using
143222
[`tls-min-version`](/influxdb/v2/reference/config-options/#tls-min-version)
@@ -152,7 +231,7 @@ update the following `influxdb_v2` output settings in your Telegraf configuratio
152231
- Update URLs to use HTTPS instead of HTTP.
153232
- If using a self-signed certificate, uncomment and set `insecure_skip_verify` to `true`.
154233

155-
### Example configuration
234+
### Example Telegraf configuration
156235

157236
```toml
158237
###############################################################################
@@ -176,3 +255,56 @@ update the following `influxdb_v2` output settings in your Telegraf configuratio
176255
```
177256

178257
Restart Telegraf using the updated configuration file.
258+
259+
## Troubleshoot TLS
260+
261+
### 1. Check InfluxDB logs
262+
263+
Review the InfluxDB logs for any error messages or warnings about the issue.
264+
265+
#### Example TLS error
266+
267+
```text
268+
msg="http: TLS handshake error from [::1]:50476:
269+
remote error: tls: illegal parameter" log_id=0rqN8H_0000 service=http
270+
```
271+
272+
### 2. Verify certificate and key Files
273+
274+
To ensure that the certificate and key files are correct and match each other,
275+
enter the following command in your terminal:
276+
277+
```bash
278+
openssl x509 -noout -modulus -in /etc/ssl/influxdb-selfsigned.crt | openssl md5
279+
openssl rsa -noout -modulus -in /etc/ssl/influxdb-selfsigned.key | openssl md5
280+
```
281+
282+
### 3. Check file permissions
283+
284+
Ensure that the InfluxDB process has read access to the certificate and key
285+
files--for example, enter the following command to set file permissions:
286+
287+
```bash
288+
sudo chmod 644 /etc/ssl/influxdb-selfsigned.crt
289+
sudo chmod 600 /etc/ssl/influxdb-selfsigned.key
290+
```
291+
292+
### 4. Verify TLS configuration
293+
294+
Ensure that the TLS configuration in InfluxDB is correct.
295+
Check the paths to the certificate and key files in the InfluxDB configuration
296+
or command line flags.
297+
298+
### 5. Test with OpenSSL
299+
300+
Use OpenSSL to test the server's certificate and key--for example, enter the
301+
following command in your terminal:
302+
303+
```bash
304+
openssl s_client -connect localhost:8086 -CAfile /etc/ssl/influxdb-selfsigned.crt
305+
```
306+
307+
### 6. Update OpenSSL and InfluxDB
308+
309+
Ensure that you are using the latest versions of OpenSSL and InfluxDB, as
310+
updates may include fixes for TLS-related issues.

‎test/scripts/prepare-content.sh

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ function substitute_placeholders {
3535
yesterday_timestamp=$(date -u -d "$yesterday_datetime" +%s)
3636

3737
# Replace the extracted timestamp with `yesterday_timestamp`
38-
sed -i "s|$specific_timestamp|$yesterday_timestamp|g;" $file
38+
sed -i "s|$specific_timestamp|$yesterday_timestamp|g;" $file
3939
fi
4040
done
4141

@@ -66,8 +66,8 @@ function substitute_placeholders {
6666
# Shell-specific replacements.
6767
## In JSON Heredoc
6868
sed -i 's|"orgID": "ORG_ID"|"orgID": "$INFLUX_ORG"|g;
69-
s|"name": "BUCKET_NAME"|"name": "$INFLUX_DATABASE"|g;' \
70-
$file
69+
s|"name": "BUCKET_NAME"|"name": "$INFLUX_DATABASE"|g;
70+
' $file
7171

7272
# Replace remaining placeholders with variables.
7373
# If the placeholder is inside of a Python os.getenv() function, don't replace it.
@@ -89,39 +89,41 @@ function substitute_placeholders {
8989
/os.getenv("ORG_ID")/! s/ORG_ID/$INFLUX_ORG/g;
9090
/os.getenv("PASSWORD")/! s/PASSWORD/$INFLUX_PASSWORD/g;
9191
/os.getenv("ORG_ID")/! s/ORG_ID/$INFLUX_ORG/g;
92-
/os.getenv("RETENTION_POLICY")/! s/RETENTION_POLICY_NAME\|RETENTION_POLICY/$INFLUX_RETENTION_POLICY/g;
92+
/os.getenv("RETENTION_POLICY")/! s/RETENTION_POLICY_NAME/$INFLUX_RETENTION_POLICY/g;
93+
/os.getenv("RETENTION_POLICY")/! s/RETENTION_POLICY/$INFLUX_RETENTION_POLICY/g;
9394
/os.getenv("USERNAME")/! s/USERNAME/$INFLUX_USERNAME/g;
9495
s/exampleuser@influxdata.com/$INFLUX_EMAIL_ADDRESS/g;
9596
s/CONFIG_NAME/CONFIG_$(shuf -i 0-100 -n1)/g;
9697
s/TEST_RUN/TEST_RUN_$(date +%s)/g;
98+
s|NUMBER_OF_DAYS|365|g;
9799
s|@path/to/line-protocol.txt|data/home-sensor-data.lp|g;
98-
s|/path/to/custom/assets-dir|/app/custom-assets|g;' \
99-
$file
100+
s|/path/to/custom/assets-dir|/app/custom-assets|g;
101+
' $file
100102

101103
# v2-specific replacements.
102104
sed -i 's|https:\/\/us-west-2-1.aws.cloud2.influxdata.com|$INFLUX_HOST|g;
103105
s|influxdb2-{{< latest-patch >}}|influxdb2-${influxdb_latest_patches_v2}|g;
104106
s|{{< latest-patch cli=true >}}|${influxdb_latest_cli_v2}|g;
105107
s|influxdb2-{{% latest-patch %}}|influxdb2-${influxdb_latest_patches_v2}|g;
106-
s|{{% latest-patch cli=true %}}|${influxdb_latest_cli_v2}|g;' \
107-
$file
108+
s|{{% latest-patch cli=true %}}|${influxdb_latest_cli_v2}|g;
109+
' $file
108110

109111
# Telegraf-specific replacements
110112
sed -i 's|telegraf-{{< latest-patch >}}|telegraf-${telegraf_latest_patches_v1}|g;
111113
s|telegraf-{{% latest-patch %}}|telegraf-${telegraf_latest_patches_v1}|g;
112114
s/--input-filter <INPUT_PLUGIN_NAME>\[:<INPUT_PLUGIN_NAME>\]/--input-filter cpu:influxdb/g;
113-
s/--output-filter <OUTPUT_PLUGIN_NAME>\[:<OUTPUT_PLUGIN_NAME>\]/--output-filter influxdb_v2:file/g;' \
114-
$file
115+
s/--output-filter <OUTPUT_PLUGIN_NAME>\[:<OUTPUT_PLUGIN_NAME>\]/--output-filter influxdb_v2:file/g;
116+
' $file
115117

116118
# Skip package manager commands.
117119
sed -i 's|sudo dpkg.*$||g;
118-
s|sudo yum.*$||g;' \
119-
$file
120+
s|sudo yum.*$||g;
121+
' $file
120122

121123
# Environment-specific replacements.
122124
# You can't use sudo with Docker.
123-
sed -i 's|sudo ||g;' \
124-
$file
125+
sed -i 's|sudo ||g;
126+
' $file
125127
fi
126128
done
127129
}

0 commit comments

Comments
 (0)