TLS Configuration Guide

Configure TLS encryption on Bindplane collector receivers with examples and parameter reference.

Understanding TLS Direction in Receivers

When configuring TLS for receivers (TCP, Syslog, OTLP, etc.), the collector acts as a TLS server, accepting encrypted connections from clients sending telemetry data.

Key Concepts

Server Certificate (cert_file / key_file)

• The certificate the collector presents to connecting clients

• Must include the private key file

• Can contain a certificate chain (server cert + intermediates)

Client Verification (ca_file / client_ca_file)

• Used to verify client certificates in mutual TLS (mTLS)

• NOT used for the server's own certificate

• ca_file: Provides CA certificates for client verification (does not enforce mTLS)

• client_ca_file: Explicitly requires and verifies client certificates (enforces mTLS)

• Optional unless you require client authentication

Trust Store Updates

• Updating the collector's system trust store affects outbound connections only

• Does not change what certificates the collector presents to clients

• Does not help clients verify the collector's certificate

For mutual TLS (mTLS) configuration where both server and clients authenticate each other, see the Mutual TLS Guide.

Configuration: UI vs YAML Field Names

Important: The YAML configuration examples in this guide use the underlying OpenTelemetry Collector parameter names, which differ from the field names shown in the Bindplane UI.

Field Name Mapping

When configuring TLS through the Bindplane UI, field names are presented in a user-friendly format. These map to YAML parameters as follows:

Bindplane UI Field Name	YAML Parameters	Description
Enable TLS	enable_tls or nested tls: block	Enable TLS encryption
TLS Certificate Path / Cert File	tls_certificate_path or cert_file	Server certificate file (can include full chain)
TLS Private Key Path / Key File	tls_private_key_path or key_file	Server private key file (must be unencrypted)
CA File	ca_file	CA certificate for optional client verification
Client CA File	client_ca_file	CA certificate that enforces mTLS
TLS Min Version	tls_min_version or min_version	Minimum TLS version ("1.2" or "1.3")
Enable Mutual TLS	enable_mutual_tls	Syslog-specific mTLS toggle

Note: Different receivers may use flat (e.g., tls_certificate_path) or nested (e.g., tls.cert_file) structures. Both are valid. This guide uses the nested tls: block structure which follows the OpenTelemetry Collector standard.

Why Field Names Differ

• Bindplane UI: Uses human-readable field names for better user experience

• YAML Configuration: Uses OpenTelemetry Collector's native parameter names

• Documentation: May show either style depending on context

When copying configurations from this guide into the Bindplane UI, the UI will automatically map the field names. When editing YAML directly or using the API, use the parameter names shown in the examples below.

Configuring TLS in the Bindplane UI

UI Navigation

TLS configuration options are located in the Advanced section when configuring a source or destination in the Bindplane UI. You may need to expand the Advanced section to see these options.

Important UI Notes

1. Enabling TLS: You must first check the "Enable TLS" checkbox before other TLS-related fields become visible or active.

2. Mutual TLS (mTLS): There is no separate "Enable mTLS" checkbox in the UI for most receivers. Instead:

   • mTLS is implied when you provide a CA certificate file in the appropriate field

   • For TCP/Syslog sources: Providing a value in "CA File" or "Client CA File" enables client certificate verification

   • The behavior depends on the specific field:

     • CA File → Optional client verification (clients can connect with or without certificates)

     • Client CA File → Required client verification (mTLS enforced, clients must present valid certificates)

3. Finding mTLS Settings: Look for fields named:

   • "CA File"

   • "Client CA File"

   • "Enable Mutual TLS" (available on some receivers like Syslog)

Example UI Workflow for TCP Source with mTLS

1. Select TCP source

2. Configure basic settings (listen address, etc.)

3. Expand the Advanced section

4. Check "Enable TLS"

5. Fill in "TLS Certificate Path" (your server certificate)

6. Fill in "TLS Private Key Path" (your server private key)

7. Fill in "Client CA File" (to enforce mTLS and verify client certificates)

8. Optionally set "TLS Min Version" to "1.2" or higher

Basic Configuration Examples

TCP Receiver with TLS

Basic TLS configuration where the server presents a certificate, but no client verification is performed:

receivers:
  tcplog:
    listen_address: "0.0.0.0:10514"
    tls:
      cert_file: /path/to/fullchain.crt
      key_file: /path/to/server.key
      min_version: "1.2"

What this does:

• Collector listens on port 10514 with TLS enabled

• Presents the server certificate to clients

• Requires TLS 1.2 or higher

• Clients verify the server's certificate (standard TLS)

• No client certificate verification (not mTLS)

Syslog Receiver with TLS

receivers:
  syslog:
    protocol: rfc5424
    tcp:
      listen_address: "0.0.0.0:6514"
      tls:
        cert_file: /path/to/fullchain.crt
        key_file: /path/to/server.key
        min_version: "1.2"

Note: The syslog receiver uses nested tcp: or udp: blocks instead of a transport: parameter.

OTLP Receiver with TLS

Bindplane Gateway Source

The Bindplane Gateway Source uses the OTLP receiver under the hood. The TLS configuration below applies to both the OTLP Source and the Bindplane Gateway Source — the same parameters and behavior apply. For a complete walkthrough of configuring TLS between collectors and gateways, see Encrypting Traffic Between Collectors and Gateways.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
        tls:
          cert_file: /path/to/fullchain.crt
          key_file: /path/to/server.key
          min_version: "1.2"
      http:
        endpoint: 0.0.0.0:4318
        tls:
          cert_file: /path/to/fullchain.crt
          key_file: /path/to/server.key
          min_version: "1.2"

Configuration Parameters Reference

Common TLS Parameters (All Receivers)

Parameter	Type	Default	Description
cert_file	string	-	Path to server certificate file (PEM format). Can contain full certificate chain (leaf cert + intermediates). Must be paired with key_file.
key_file	string	-	Path to server private key file (PEM format). Must be unencrypted (no passphrase). Must be paired with cert_file.
min_version	string	"1.2"	Minimum TLS version accepted. Valid values: "1.0", "1.1", "1.2", "1.3". TLS 1.0 and 1.1 are deprecated.
max_version	string	-	Maximum TLS version (empty = use latest, currently TLS 1.3)
cipher_suites	[]string	-	List of allowed cipher suites (empty = use safe defaults)
reload_interval	duration	-	Automatically reload certificates at interval (e.g., "24h")

Client Verification (Mutual TLS)

Parameter	Type	Default	Description
ca_file	string	-	Path to CA certificate(s) for optional client verification. If clients present certificates, they'll be verified against this CA. Does not require or enforce client certificates.
client_ca_file	string	-	Path to CA certificate(s) that enforces mutual TLS. When set, the server requires all clients to present valid certificates signed by this CA. Sets ClientAuth to RequireAndVerifyClientCert.
client_ca_file_reload	bool	false	Automatically reload client CA file when modified (useful for CA rotation)

For detailed mTLS configuration, see the Mutual TLS Guide.

Advanced Configuration

Certificate Reloading

Automatically reload certificates without restarting the collector:

receivers:
  tcplog:
    listen_address: "0.0.0.0:10514"
    tls:
      cert_file: /path/to/fullchain.crt
      key_file: /path/to/server.key
      min_version: "1.2"
      reload_interval: 24h  # Check for certificate updates every 24 hours

Best Practice

Use reload_interval for production deployments to enable certificate rotation without service interruption. This is especially useful for automated certificate renewal (e.g., Let's Encrypt).

Cipher Suite Configuration

Specify allowed cipher suites for enhanced security:

receivers:
  tcplog:
    listen_address: "0.0.0.0:10514"
    tls:
      cert_file: /path/to/fullchain.crt
      key_file: /path/to/server.key
      min_version: "1.2"
      cipher_suites:
        - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
        - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

Cipher Suite Compatibility

Only specify cipher suites if you have specific security requirements. The default cipher suite list is secure and broadly compatible. Custom lists may break connectivity with some clients.

TLS Version Restrictions

receivers:
  tcplog:
    listen_address: "0.0.0.0:10514"
    tls:
      cert_file: /path/to/fullchain.crt
      key_file: /path/to/server.key
      min_version: "1.3"  # Only allow TLS 1.3
      max_version: "1.3"

Security Recommendations

TLS Version

Recommended: Use TLS 1.2 as minimum (min_version: "1.2")

TLS 1.0 and 1.1 are deprecated and should not be used. TLS 1.3 is preferred where client compatibility allows.

Certificate Management

• Keep certificates updated before expiration

• Use certificate chains with intermediate certificates for broader client compatibility

• Implement certificate rotation using reload_interval

• Monitor certificate expiration dates proactively

File Permissions

Linux/macOS

# Private key should only be readable by the collector user
chmod 600 /path/to/server.key
chown <collector-user>:<collector-group> /path/to/server.key

# Certificate can be more permissive
chmod 644 /path/to/fullchain.crt

Windows PowerShell

Cipher Suites

• Use default cipher suites unless you have specific security requirements

• Prefer ECDHE (Ephemeral Diffie-Hellman) for forward secrecy

• Prefer AES-GCM over AES-CBC

• Avoid deprecated algorithms (RC4, 3DES, MD5)

Testing Your Configuration

After configuring TLS, verify it works correctly:

Linux/macOS

# Test basic connectivity
openssl s_client -connect collector.example.com:10514

# View certificate chain
openssl s_client -connect collector.example.com:10514 -showcerts

# Test specific TLS version
openssl s_client -connect collector.example.com:10514 -tls1_2

Windows PowerShell

For detailed testing instructions, see Testing and Verification.