How to Configure SSL/TLS for Telegraf Input and Output Plugins: A Complete Guide

Telegraf implements TLS encryption through two reusable structs—ServerConfig for input plugins and ClientConfig for output plugins—both defined in the plugins/common/tls package and activated by adding a [plugin.tls] table to your configuration.

Configuring SSL/TLS for Telegraf input and output plugins ensures encrypted data transmission between agents and endpoints. The InfluxData Telegraf repository centralizes all TLS logic in the plugins/common/tls package, allowing every plugin to expose identical certificate options through embedded structs. Whether you are securing a listening HTTP input or encrypting output to InfluxDB, you interact with the same consistent configuration schema.

Understanding ServerConfig vs. ClientConfig

Telegraf distinguishes between listening (server) and dialing (client) operations through two distinct configuration structs defined in the common TLS package.

ServerConfig in plugins/common/tls/server.go handles input plugins that accept incoming connections. When you configure a plugin like the HTTP listener, you embed this struct to define how the server presents its identity and verifies clients.

ClientConfig in plugins/common/tls/client.go handles output plugins that initiate outbound connections. Plugins such as influxdb, http, and websocket embed this struct to verify remote servers and optionally present client certificates for mutual TLS.

Both structs expose a TLSConfig() method that builds a Go *tls.Config object used by the underlying transport layer.

Configuring TLS for Input Plugins (ServerConfig)

Input plugins that open listening sockets use ServerConfig to specify certificate paths, allowed CAs, and protocol constraints.

Key fields from plugins/common/tls/server.go include:

• tls_cert – Path to the PEM-encoded server certificate.
• tls_key – Path to the corresponding private key.
• tls_key_pwd – Passphrase for encrypted private keys.
• tls_allowed_cacerts – Array of CA certificate paths to validate client certificates (enables mutual TLS).
• tls_allowed_dns_names – Restrict connections to clients presenting certificates with specific DNS subject names.
• tls_min_version / tls_max_version – Protocol bounds (e.g., "TLS12", "TLS13").
• tls_cipher_suites – Allowed cipher suite names mapped by the ParseCiphers function in plugins/common/tls/utils.go.

The default minimum TLS version is TLS 1.2 as defined by TLSMinVersionDefault in plugins/common/tls/common.go.

Example: Secure HTTP Listener

[[inputs.http]]
  address = ":8086"

  [inputs.http.tls]
    tls_cert = "/etc/telegraf/server.pem"
    tls_key  = "/etc/telegraf/server.key"
    tls_min_version = "TLS12"
    ## Optional: require client certificates

    # tls_allowed_cacerts = ["/etc/telegraf/ca.pem"]

    # tls_allowed_dns_names = ["my-device.local"]

When Telegraf parses this configuration, ServerConfig.TLSConfig() loads the certificate via loadCertificate (defined in plugins/common/tls/utils.go) and returns a configured *tls.Config to the HTTP server.

Configuring TLS for Output Plugins (ClientConfig)

Output plugins embedding ClientConfig secure outbound connections by verifying server identities and presenting client credentials.

Key fields from plugins/common/tls/client.go include:

• tls_ca – Path to the CA bundle for verifying the server certificate.
• tls_cert / tls_key – Client certificate and key for mutual TLS.
• insecure_skip_verify – Boolean to disable server verification (not recommended for production).
• tls_server_name – SNI hostname to send during the handshake.
• tls_renegotiation_method – Controls renegotiation behavior ("never", "once", "freely").
• tls_enable – Explicit boolean to force TLS initialization when no other fields are set.

If no TLS fields are provided, the plugin returns nil and connects unencrypted. Setting tls_enable = true forces TLS using system defaults (OS trust store) even without explicit certificate paths.

Example: Secure InfluxDB Output

[[outputs.influxdb]]
  urls = ["https://influxdb.example.com:8086"]
  database = "metrics"

  [outputs.influxdb.tls]
    tls_ca   = "/etc/telegraf/ca.pem"
    tls_cert = "/etc/telegraf/client.pem"
    tls_key  = "/etc/telegraf/client.key"
    tls_min_version = "TLS12"
    tls_server_name = "influxdb.example.com"

The outputs.influxdb plugin calls ClientConfig.TLSConfig() to construct the TLS configuration used by its underlying HTTP transport.

Enabling Mutual TLS (mTLS)

Mutual TLS requires both parties to present valid certificates. For output plugins, provide tls_cert and tls_key alongside tls_ca. For input plugins, specify tls_allowed_cacerts to validate incoming client certificates.

Example: WebSocket Output with mTLS

[[outputs.websocket]]
  url = "wss://collector.example.com/telegraf"

  [outputs.websocket.tls]
    tls_ca   = "/etc/telegraf/ca.pem"
    tls_cert = "/etc/telegraf/client.pem"
    tls_key  = "/etc/telegraf/client.key"
    tls_min_version = "TLS13"

The outputs.websocket plugin uses ClientConfig to present the client certificate during the TLS handshake while verifying the server against the specified CA.

Advanced TLS Configuration Options

Cipher Suite Selection – The tls_cipher_suites field accepts a list of names (e.g., "TLS_AES_256_GCM_SHA384") mapped to Go constants at runtime by ParseCiphers in plugins/common/tls/utils.go.

Version Constraints – The implementation validates that tls_min_version is not greater than tls_max_version, throwing a configuration error if violated.

System Defaults – Setting tls_enable = true without certificate paths initializes TLS using the operating system's certificate pool, useful for connecting to public endpoints with trusted CAs.

Summary

• ServerConfig (plugins/common/tls/server.go) secures input plugins by defining server certificates and client verification policies.
• ClientConfig (plugins/common/tls/client.go) secures output plugins by defining CA trusts and optional client credentials.
• Both structs expose a TLSConfig() method that generates Go *tls.Config objects used by transport layers.
• Mutual TLS activates automatically when both certificate and key paths are provided.
• The default minimum TLS version is 1.2, enforced across all plugins.
• Use tls_enable = true to force TLS mode using system certificate stores when no explicit paths are configured.

Frequently Asked Questions

How do I enable TLS for a Telegraf output plugin without specifying certificate files?

Set tls_enable = true in the [outputs.plugin.tls] table. According to the implementation in plugins/common/tls/client.go, this boolean forces the creation of a TLS configuration using the operating system's default CA store, allowing encrypted connections to public endpoints without manual certificate management.

What is the difference between tls_cert in ServerConfig versus ClientConfig?

In ServerConfig (plugins/common/tls/server.go), tls_cert identifies the server to connecting clients and is required for any TLS-enabled listener. In ClientConfig (plugins/common/tls/client.go), tls_cert is optional and used for mutual TLS, identifying the client to the remote server when both tls_cert and tls_key are provided.

How does Telegraf validate TLS version compatibility?

The TLSConfig() methods in both structs perform validation ensuring tls_min_version does not exceed tls_max_version. If incompatible values are specified, the configuration fails to load with an error generated during the initialization phase defined in plugins/common/tls/common.go.

Can I restrict which client certificates are accepted by a Telegraf input plugin?

Yes. In ServerConfig, use the tls_allowed_cacerts field to provide CA certificates for validation, and optionally specify tls_allowed_dns_names to restrict connections to clients whose certificates contain matching DNS subject names. These fields are processed by the TLSConfig() method in plugins/common/tls/server.go to configure the underlying tls.Config.ClientCAs and certificate verification logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}