SSL vs. TLS consistency and clarification in documentation (#6414)
* Changed references of SSL to TLS where appropriate * A few more tweaks on SSL->TLS * Fixed whitespace issue from @vlvkobal * Fixing sentence on OpenTSDB for @thiagoftsm
This commit is contained in:
Joel Hans
GitHub
parent
72fa391549
commit
2167a4ac52
|
|
@ -155,7 +155,7 @@ Release v1.16.0 contains 40 bug fixes, 31 improvements and 20 documentation upda
|
|||
- Our stable distributions are at [netdata/netdata @ packagecloud.io](https://packagecloud.io/netdata/netdata)
|
||||
- The nightly builds are at [netdata/netdata-edge @ packagecloud.io](https://packagecloud.io/netdata/netdata-edge)
|
||||
|
||||
**Netdata now supports SSL encryption!** You can secure the communication to the [web server](https://docs.netdata.cloud/web/server/#enabling-tls-support), the [streaming connections from slaves to the master](https://docs.netdata.cloud/streaming/#securing-the-communication) and the connection to an [openTSDB backend](https://docs.netdata.cloud/backends/opentsdb/#https).
|
||||
**Netdata now supports TLS encryption!** You can secure the communication to the [web server](https://docs.netdata.cloud/web/server/#enabling-tls-support), the [streaming connections from slaves to the master](https://docs.netdata.cloud/streaming/#securing-the-communication) and the connection to an [openTSDB backend](https://docs.netdata.cloud/backends/opentsdb/#https).
|
||||
|
||||
**This version also brings two long-awaited features to netdata’s health monitoring:**
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,6 @@
|
|||
# OpenTSDB with HTTP
|
||||
|
||||
Since version 1.16 the Netdata has the feature to communicate with OpenTSDB using HTTP API. To enable this channel
|
||||
it is necessary to set the following options in your netdata.conf
|
||||
Netdata can easily communicate with OpenTSDB using HTTP API. To enable this channel, set the following options in your `netdata.conf`:
|
||||
|
||||
```
|
||||
[backend]
|
||||
|
|
@ -9,13 +8,13 @@ it is necessary to set the following options in your netdata.conf
|
|||
destination = localhost:4242
|
||||
```
|
||||
|
||||
, in this example we are considering that OpenTSDB is running with its default port (4242).
|
||||
In this example, OpenTSDB is running with its default port, which is `4242`. If you run OpenTSDB on a different port, change the `destination = localhost:4242` line accordingly.
|
||||
|
||||
## HTTPS
|
||||
|
||||
Netdata also supports sending the metrics using SSL/TLS, but OpenTDSB does not have support to safety connections,
|
||||
so it will be necessary to configure a reverse-proxy to enable the HTTPS communication. After to configure your proxy the
|
||||
following changes must be done in the netdata.conf:
|
||||
As of [v1.16.0](https://github.com/netdata/netdata/releases/tag/v1.16.0), Netdata can send metrics to OpenTSDB using TLS/SSL. Unfortunately, OpenTDSB does not support encrypted connections, so you will have to configure a reverse proxy to enable HTTPS communication between Netdata and OpenTSBD. You can set up a reverse proxy with [Nginx](../../docs/Running-behind-nginx.md).
|
||||
|
||||
After your proxy is configured, make the following changes to `netdata.conf`:
|
||||
|
||||
```
|
||||
[backend]
|
||||
|
|
@ -23,4 +22,4 @@ following changes must be done in the netdata.conf:
|
|||
destination = localhost:8082
|
||||
```
|
||||
|
||||
In this example we used the port 8082 for our reverse proxy.
|
||||
In this example, we used the port `8082` for our reverse proxy. If your reverse proxy listens on a different port, change the `destination = localhost:8082` line accordingly.
|
||||
|
|
|
|||
|
|
@ -119,10 +119,9 @@ Using the above, you access Netdata on the backend servers, like this:
|
|||
|
||||
### Using TLS communication
|
||||
|
||||
In case the Netdata web server has been [configured to use TLS](../web/server/#enabling-tls-support),
|
||||
you must also encrypt the communication between Nginx and Netdata.
|
||||
In case Netdata's web server has been [configured to use TLS](../web/server/#enabling-tls-support), you must also encrypt the communication between Nginx and Netdata.
|
||||
|
||||
To enable encryption, first [enable SSL on nginx](http://nginx.org/en/docs/http/configuring_https_servers.html) and then put the following in the location section of the Nginx configuration:
|
||||
To enable encryption, first [enable TLS/SSL on Nginx](http://nginx.org/en/docs/http/configuring_https_servers.html) and then put the following in the location section of your Nginx configuration:
|
||||
|
||||
```
|
||||
proxy_set_header X-Forwarded-Proto https;
|
||||
|
|
@ -133,15 +132,15 @@ If nginx is not configured as described here, you will probably receive the erro
|
|||
|
||||
### Enable authentication
|
||||
|
||||
Create an authentication file to enable the nginx basic authentication.
|
||||
Do not use authentication without SSL/TLS!
|
||||
If you haven't one you can do the following:
|
||||
Create an authentication file to enable basic authentication via Nginx. Do not use authentication without having first [enabled TLS](#using-tls-communication)!
|
||||
|
||||
If you don't have an authentication file, you can use the following command:
|
||||
|
||||
```
|
||||
printf "yourusername:$(openssl passwd -apr1)" > /etc/nginx/passwords
|
||||
```
|
||||
|
||||
And enable the authentication inside your server directive:
|
||||
And then enable the authentication inside your server directive:
|
||||
|
||||
```
|
||||
server {
|
||||
|
|
@ -154,7 +153,7 @@ server {
|
|||
|
||||
## limit direct access to Netdata
|
||||
|
||||
If your nginx is on `localhost`, you can use this to protect your Netdata:
|
||||
If your Nginx is on `localhost`, you can use this to protect your Netdata:
|
||||
|
||||
```
|
||||
[web]
|
||||
|
|
|
|||
|
|
@ -138,7 +138,7 @@ headless proxy|`none`|not `none`|`yes`|only for `data source = as collected`|not
|
|||
proxy with db|not `none`|not `none`|`yes`|possible|possible|yes
|
||||
central netdata|not `none`|not `none`|`no`|possible|possible|yes
|
||||
|
||||
For the options to encrypt the data stream between the slave and the master, refer to [securing the communication](#securing-the-communication)
|
||||
For the options to encrypt the data stream between the slave and the master, refer to [securing the communication](#securing-streaming-communications)
|
||||
|
||||
##### options for the receiving node
|
||||
|
||||
|
|
@ -213,20 +213,23 @@ The receiving end (`proxy` or `master`) logs entries like these:
|
|||
|
||||
For netdata v1.9+, streaming can also be monitored via `access.log`.
|
||||
|
||||
### Securing the communication
|
||||
### Securing streaming communications
|
||||
|
||||
Netdata does not activate TLS encryption by default. To encrypt the connection, you first need to [enable TLS support](../web/server/#enabling-tls-support) on the master. With encryption enabled on the receiving side, we need to instruct the slave to use SSL as well. On the slave's `stream.conf`, configure the destination as follows:
|
||||
Netdata does not activate TLS encryption by default. To encrypt streaming connections, you first need to [enable TLS support](../web/server/#enabling-tls-support) on the master. With encryption enabled on the receiving side, you need to instruct the slave to use TLS/SSL as well. On the slave's `stream.conf`, configure the destination as follows:
|
||||
|
||||
```
|
||||
[stream]
|
||||
destination = host:port:SSL
|
||||
```
|
||||
|
||||
The word SSL appended to the end of the destination tells the slave that the connection must be encrypted.
|
||||
The word `SSL` appended to the end of the destination tells the slave that connections must be encrypted.
|
||||
|
||||
??? info "Differences in TLS and SSL terminology"
|
||||
While Netdata uses Transport Layer Security (TLS) 1.2 to encrypt communications rather than the obsolete SSL protocol, it's still common practice to refer to encrypted web connections as `SSL`. Many vendors, like Nginx and even Netdata itself, use `SSL` in configuration files, whereas documentation will always refer to encrypted communications as `TLS` or `TLS/SSL`.
|
||||
|
||||
#### Certificate verification
|
||||
|
||||
When SSL is enabled on the slave, the default behavior will be do not connect with the master unless the server's certificate can be verified via the default chain. In case you want to avoid this check, add to the slave's `stream.conf` the following:
|
||||
When TLS/SSL is enabled on the slave, the default behavior will be to not connect with the master unless the server's certificate can be verified via the default chain. In case you want to avoid this check, add the following to the slave's `stream.conf` file:
|
||||
|
||||
```
|
||||
[stream]
|
||||
|
|
@ -235,18 +238,19 @@ When SSL is enabled on the slave, the default behavior will be do not connect wi
|
|||
|
||||
#### Expected behaviors
|
||||
|
||||
With the introduction of SSL, the master-slave communication behaves as shown in the table below, depending on the following configurations:
|
||||
- Master TLS (Yes/No): Whether the `[web]` section in `netdata.conf` has `ssl key` and `ssl certificate`.
|
||||
- Master port SSL (-/force/optional): Depends on whether the `[web]` section `bind to` contains a `^SSL=force` or `^SSL=optional` directive on the port(s) used for streaming.
|
||||
- Slave TLS (Yes/No): Whether the destination in the slave's `stream.conf` has `:SSL` at the end.
|
||||
- Slave SSL Verification (yes/no): Value of the slave's `stream.conf` `ssl skip certificate verification` parameter (default is no).
|
||||
With the introduction of TLS/SSL, the master-slave communication behaves as shown in the table below, depending on the following configurations:
|
||||
|
||||
- **Master TLS (Yes/No)**: Whether the `[web]` section in `netdata.conf` has `ssl key` and `ssl certificate`.
|
||||
- **Master port TLS (-/force/optional)**: Depends on whether the `[web]` section `bind to` contains a `^SSL=force` or `^SSL=optional` directive on the port(s) used for streaming.
|
||||
- **Slave TLS (Yes/No)**: Whether the destination in the slave's `stream.conf` has `:SSL` at the end.
|
||||
- **Slave TLS Verification (yes/no)**: Value of the slave's `stream.conf` `ssl skip certificate verification` parameter (default is no).
|
||||
|
||||
Master TLS enabled | Master port SSL | Slave TLS | Slave SSL Ver. | Behavior
|
||||
:------:|:-----:|:-----:|:-----:|:--------
|
||||
No | - | No | no | Legacy behavior. The master-slave stream is unencrypted.
|
||||
Yes | force | No | no | The master rejects the slave connection.
|
||||
Yes | -/optional | No | no | The master-slave stream is unencrypted (expected situation for legacy slaves and newer masters)
|
||||
Yes | -/force/optional | Yes | no | The master-slave stream is encrypted, provided that the master has a valid SSL certificate. Otherwise, the slave refuses to connect.
|
||||
Yes | -/force/optional | Yes | no | The master-slave stream is encrypted, provided that the master has a valid TLS/SSL certificate. Otherwise, the slave refuses to connect.
|
||||
Yes | -/force/optional | Yes | yes | The master-slave stream is encrypted.
|
||||
|
||||
## Viewing remote host dashboards, using mirrored databases
|
||||
|
|
|
|||
|
|
@ -59,42 +59,43 @@ The API requests are serviced as follows:
|
|||
|
||||
### Enabling TLS support
|
||||
|
||||
Since v1.16.0, Netdata supports encrypted HTTP connections to the web server, plus encryption of streaming data between a slave and its master, via the TLS 1.2 protocol.
|
||||
|
||||
Netdata since version 1.16 supports encrypted HTTP connections to the web server and encryption of the data stream between a slave and a master.
|
||||
Inbound unix socket connections are unaffected, regardless of the SSL settings.
|
||||
To enable SSL, provide the path to your certificate and private key in the `[web]` section of `netdata.conf`:
|
||||
Inbound unix socket connections are unaffected, regardless of the TLS settings.
|
||||
??? info "Differences in TLS and SSL terminology"
|
||||
While Netdata uses Transport Layer Security (TLS) 1.2 to encrypt communications rather than the obsolete SSL protocol, it's still common practice to refer to encrypted web connections as `SSL`. Many vendors, like Nginx and even Netdata itself, use `SSL` in configuration files, whereas documentation will always refer to encrypted communications as `TLS` or `TLS/SSL`.
|
||||
|
||||
```
|
||||
To enable TLS, provide the path to your certificate and private key in the `[web]` section of `netdata.conf`:
|
||||
|
||||
``` conf
|
||||
[web]
|
||||
ssl key = /etc/netdata/ssl/key.pem
|
||||
ssl certificate = /etc/netdata/ssl/cert.pem
|
||||
```
|
||||
|
||||
Both files must be readable by the netdata user. If any of the two files does not exist or is unreadable, Netdata falls back to HTTP.
|
||||
|
||||
For a master/slave connection, only the master needs these settings.
|
||||
Both files must be readable by the `netdata` user. If either of these files do not exist or are unreadable, Netdata will fall back to HTTP. For a master/slave connection, only the master needs these settings.
|
||||
|
||||
For test purposes, you can generate self-signed certificates with the following command:
|
||||
|
||||
```
|
||||
``` bash
|
||||
$ openssl req -newkey rsa:2048 -nodes -sha512 -x509 -days 365 -keyout key.pem -out cert.pem
|
||||
```
|
||||
|
||||
TIP: If you use 4096 bits for the key and the certificate, netdata will need more CPU to process the whole communication.
|
||||
rsa4096 can be until 4 times slower than rsa2048, so we recommend using 2048 bits. You can verify the difference by running
|
||||
!!! note
|
||||
If you use 4096 bits for your key and the certificate, Netdata will need more CPU to process the communication. `rsa4096` can be up to 4 times slower than `rsa2048`, so we recommend using 2048 bits. You can verify the difference by running:
|
||||
|
||||
```
|
||||
$ openssl speed rsa2048 rsa4096
|
||||
```
|
||||
|
||||
```
|
||||
$ openssl speed rsa2048 rsa4096
|
||||
```
|
||||
|
||||
#### SSL enforcement
|
||||
#### TLS/SSL enforcement
|
||||
|
||||
When the certificates are defined and unless any other options are provided, a Netdata server will:
|
||||
|
||||
- Redirect all incoming HTTP web server requests to HTTPS. Applies to the dashboard, the API, netdata.conf and badges.
|
||||
- Allow incoming slave connections to use both unencrypted and encrypted communications for streaming.
|
||||
|
||||
To change this behavior, you need to modify the `bind to` setting in the `[web]` section of `netdata.conf`.
|
||||
At the end of each port definition, you can append `^SSL=force` or `^SSL=optional`. What happens with these settings differs, depending on whether the port is used for HTTP/S requests, or for streaming.
|
||||
To change this behavior, you need to modify the `bind to` setting in the `[web]` section of `netdata.conf`. At the end of each port definition, you can append `^SSL=force` or `^SSL=optional`. What happens with these settings differs, depending on whether the port is used for HTTP/S requests, or for streaming.
|
||||
|
||||
SSL setting | HTTP requests | HTTPS requests | Unencrypted Streams | Encrypted Streams
|
||||
:------:|:-----:|:-----:|:-----:|:--------
|
||||
|
|
@ -109,12 +110,15 @@ Example:
|
|||
bind to = *=dashboard|registry|badges|management|streaming|netdata.conf^SSL=force
|
||||
```
|
||||
|
||||
For information how to configure the slaves to use TLS, check [securing the communication](../../streaming#securing-the-communication) in the streaming documentation.
|
||||
You will find there additional details on the expected behavior for client and server nodes, when their respective SSL options are enabled.
|
||||
For information how to configure the slaves to use TLS, check [securing the communication](../../streaming#securing-streaming-communications) in the streaming documentation. There you will find additional details on the expected behavior for client and server nodes, when their respective TLS options are enabled.
|
||||
|
||||
#### SSL error
|
||||
#### TLS/SSL errors
|
||||
|
||||
It is possible that when you start to use the Netdata with SSL some erros will be register in the logs, this happens due possible incompatibilities between the browser options related to SSL like Ciphers and TLS/SSL version and the Netdata internal configuration. The most common error would be `error:00000006:lib(0):func(0):EVP lib`. In a near future the Netdata will allow our users to change the internal configuration to avoid errors like this, but until there we are setting the most common and safety options to the communication.
|
||||
When you start using Netdata with TLS, you may find errors in the Netdata log, which is stored at `/var/log/netdata/error.log` by default.
|
||||
|
||||
Most of the time, these errors are due to incompatibilities between your browser's options related to TLS/SSL protocols and Netdata's internal configuration. The most common error is `error:00000006:lib(0):func(0):EVP lib`.
|
||||
|
||||
In the near future, Netdata will allow our users to change the internal configuration to avoid similar errors. Until then, we're recommending only the most common and safe encryption protocols, which you can find above.
|
||||
|
||||
### Access lists
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue