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

> Learn to configure SSL/TLS for Telegraf input and output plugins. This guide covers using ServerConfig and ClientConfig for secure data transmission. Enhance your Telegraf security today.

- Repository: [InfluxData/telegraf](https://github.com/influxdata/telegraf)
- Tags: how-to-guide
- Published: 2026-05-14

---

**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`](https://github.com/influxdata/telegraf/blob/main/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`](https://github.com/influxdata/telegraf/blob/main/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`](https://github.com/influxdata/telegraf/blob/main/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`](https://github.com/influxdata/telegraf/blob/main/plugins/common/tls/utils.go).

The default minimum TLS version is **TLS 1.2** as defined by `TLSMinVersionDefault` in [`plugins/common/tls/common.go`](https://github.com/influxdata/telegraf/blob/main/plugins/common/tls/common.go).

### Example: Secure HTTP Listener

```toml
[[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`](https://github.com/influxdata/telegraf/blob/main/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`](https://github.com/influxdata/telegraf/blob/main/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

```toml
[[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

```toml
[[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`](https://github.com/influxdata/telegraf/blob/main/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`](https://github.com/influxdata/telegraf/blob/main/plugins/common/tls/server.go)) secures input plugins by defining server certificates and client verification policies.
- **`ClientConfig`** ([`plugins/common/tls/client.go`](https://github.com/influxdata/telegraf/blob/main/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`](https://github.com/influxdata/telegraf/blob/main/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`](https://github.com/influxdata/telegraf/blob/main/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`](https://github.com/influxdata/telegraf/blob/main/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`](https://github.com/influxdata/telegraf/blob/main/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`](https://github.com/influxdata/telegraf/blob/main/plugins/common/tls/server.go) to configure the underlying `tls.Config.ClientCAs` and certificate verification logic.