dom
/
telegraf
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Update TLS documentation

This commit is contained in:
Daniel Nelson 2019-08-19 17:40:32 -07:00
parent 149d221191
commit d5b41cfc9a
No known key found for this signature in database
GPG Key ID: CAAD59C9444F6155
2 changed files with 114 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/CONFIGURATION.md
View File

@ -550,6 +550,10 @@ output. The tag is removed in the outputs before writing.
influxdb_database = "other" influxdb_database = "other"
``` ```
### Transport Layer Security (TLS)
Reference the detailed [TLS][] documentation.
[TOML]: https://github.com/toml-lang/toml#toml [TOML]: https://github.com/toml-lang/toml#toml
[global tags]: #global-tags [global tags]: #global-tags
[interval]: #intervals [interval]: #intervals
@ -561,3 +565,4 @@ output. The tag is removed in the outputs before writing.
[aggregators]: #aggregator-plugins [aggregators]: #aggregator-plugins
[metric filtering]: #metric-filtering [metric filtering]: #metric-filtering
[telegraf.conf]: /etc/telegraf.conf [telegraf.conf]: /etc/telegraf.conf
[TLS]: /docs/TLS.md

149
docs/TLS.md
View File

@ -1,44 +1,113 @@
# TLS settings # Transport Layer Security
TLS for output plugin will be used if you provide options `tls_cert` and `tls_key`. There is an ongoing effort to standardize TLS options across plugins. When
Settings that can be used to configure TLS: possible, plugins will provide the standard settings described below. With the
exception of the advanced configuration available TLS settings will be
documented in the sample configuration.
- `tls_cert` - path to certificate. Type: `string`. Ex. `tls_cert = "/etc/ssl/telegraf.crt"` ### Client Configuration
- `tls_key` - path to key. Type: `string`, Ex. `tls_key = "/etc/ssl/telegraf.key"`
- `tls_allowed_cacerts` - Set one or more allowed client CA certificate file names to enable mutually authenticated TLS connections. Type: `list`. Ex. `tls_allowed_cacerts = ["/etc/telegraf/clientca.pem"]`
- `tls_cipher_suites`- Define list of ciphers that will be supported. If wasn't defined default will be used. Type: `list`. Ex. `tls_cipher_suites = ["TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305", "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305", "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256", "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256", "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA", "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256", "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA", "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA", "TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA", "TLS_RSA_WITH_AES_128_GCM_SHA256", "TLS_RSA_WITH_AES_256_GCM_SHA384", "TLS_RSA_WITH_AES_128_CBC_SHA256", "TLS_RSA_WITH_AES_128_CBC_SHA", "TLS_RSA_WITH_AES_256_CBC_SHA"]`
- `tls_min_version` - Minimum TLS version that is acceptable. If wasn't defined default (TLS 1.0) will be used. Type: `string`. Ex. `tls_min_version = "TLS11"`
- `tls_max_version` - Maximum SSL/TLS version that is acceptable. If not set, then the maximum version supported is used, which is currently TLS 1.2 (for go < 1.12) or TLS 1.3 (for go == 1.12). Ex. `tls_max_version = "TLS12"`
tls ciphers are supported: For client TLS support we have the following options:
- TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 ```toml
- TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305 ## Root certificates for verifying server certificates encoded in PEM format.
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 # tls_ca = "/etc/telegraf/ca.pem"
- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
- TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
- TLS_RSA_WITH_AES_128_GCM_SHA256
- TLS_RSA_WITH_AES_256_GCM_SHA384
- TLS_RSA_WITH_AES_128_CBC_SHA256
- TLS_RSA_WITH_AES_128_CBC_SHA
- TLS_RSA_WITH_AES_256_CBC_SHA
- TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
- TLS_RSA_WITH_3DES_EDE_CBC_SHA
- TLS_RSA_WITH_RC4_128_SHA
- TLS_ECDHE_RSA_WITH_RC4_128_SHA
- TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
- TLS_AES_128_GCM_SHA256 (only if version go1.12 was used for make build)
- TLS_AES_256_GCM_SHA384 (only if version go1.12 was used for make build)
- TLS_CHACHA20_POLY1305_SHA256 (only if version go1.12 was used for make build)
TLS versions are supported: ## The public and private keypairs for the client encoded in PEM format. May
- TLS10 ## contain intermediate certificates.
- TLS11 # tls_cert = "/etc/telegraf/cert.pem"
- TLS12 # tls_key = "/etc/telegraf/key.pem"
- TLS13 (only if version go1.12 was used for make build) ## Skip TLS verification.
# insecure_skip_verify = false
```
#### Advanced Configuration
For plugins using the standard client configuration you can also set several
advanced settings. These options are not included in the sample configuration
for the interest of brevity.
```toml
## Define list of allowed ciphers suites. If not defined the default ciphers
## supported by Go will be used.
## ex: tls_cipher_suites = [
## "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305",
## "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305",
## "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
## "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
## "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
## "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
## "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256",
## "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA",
## "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256",
## "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA",
## "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA",
## "TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA",
## "TLS_RSA_WITH_AES_128_GCM_SHA256",
## "TLS_RSA_WITH_AES_256_GCM_SHA384",
## "TLS_RSA_WITH_AES_128_CBC_SHA256",
## "TLS_RSA_WITH_AES_128_CBC_SHA",
## "TLS_RSA_WITH_AES_256_CBC_SHA"
# ]
# tls_cipher_suites = []
## Minimum TLS version that is acceptable.
# tls_min_version = "TLS10"
## Maximum SSL/TLS version that is acceptable.
# tls_max_version = "TLS12"
```
Cipher suites for use with `tls_cipher_suites`:
- `TLS_RSA_WITH_RC4_128_SHA`
- `TLS_RSA_WITH_3DES_EDE_CBC_SHA`
- `TLS_RSA_WITH_AES_128_CBC_SHA`
- `TLS_RSA_WITH_AES_256_CBC_SHA`
- `TLS_RSA_WITH_AES_128_CBC_SHA256`
- `TLS_RSA_WITH_AES_128_GCM_SHA256`
- `TLS_RSA_WITH_AES_256_GCM_SHA384`
- `TLS_ECDHE_ECDSA_WITH_RC4_128_SHA`
- `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`
- `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`
- `TLS_ECDHE_RSA_WITH_RC4_128_SHA`
- `TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA`
- `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`
- `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`
- `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`
- `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`
- `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`
- `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`
- `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`
- `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`
- `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305`
- `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305`
TLS 1.3 cipher suites require Telegraf 1.12 and Go 1.12 or later:
- `TLS_AES_128_GCM_SHA256`
- `TLS_AES_256_GCM_SHA384`
- `TLS_CHACHA20_POLY1305_SHA256`
TLS versions for use with `tls_min_version` or `tls_max_version`:
- `TLS10`
- `TLS11`
- `TLS12`
- `TLS13` (Telegraf 1.12 and Go 1.12 required, must enable TLS 1.3 using environment variables)
### TLS 1.3
TLS 1.3 is available only on an opt-in basis in Go 1.12. To enable it, set the
GODEBUG environment variable (comma-separated key=value options) such that it
includes "tls13=1".
### Server Configuration
The server TLS configuration provides support for TLS mutual authentication:
```toml
## Set one or more allowed client CA certificate file names to
## enable mutually authenticated TLS connections.
# tls_allowed_cacerts = ["/etc/telegraf/clientca.pem"]
## Add service certificate and key.
# tls_cert = "/etc/telegraf/cert.pem"
# tls_key = "/etc/telegraf/key.pem"
```