Encrypting Traffic Between Collectors and Gateways
Configure TLS encryption between downstream collectors and gateway hosts.
OTLP Source and Destination
The Bindplane Gateway Source and Destination are OTLP-based. The TLS configuration described in this guide applies equally to the OTLP Source and OTLP Destination — the same UI fields, parameters, and behavior apply to both.
For certificate format requirements, see Certificate and Key Requirements. For mutual TLS details, see the Mutual TLS Guide.
Overview
In this architecture, downstream collectors send telemetry data to one or more gateway hosts:
Downstream Collector(s) Gateway Host(s)
┌─────────────────────┐ ┌─────────────────────┐
│ Bindplane Gateway │── TLS ──────>│ Bindplane Gateway │
│ Destination │ │ Source │
│ (TLS Client) │ │ (TLS Server) │
└─────────────────────┘ └─────────────────────┘The Gateway Source acts as a TLS server, presenting a certificate to incoming connections. The Gateway Destination acts as a TLS client, verifying the server's certificate.
Prerequisites
Before configuring TLS, ensure you have the following files ready on the appropriate hosts:
On the gateway host(s):
Server certificate in PEM format (can include the full certificate chain)
Server private key in PEM format, unencrypted
On the downstream collector(s):
CA certificate that signed the gateway's server certificate (not needed if using a publicly trusted CA)
For mutual TLS (optional):
Client certificate and key on each downstream collector
Client CA certificate on the gateway host
Certificate Requirements
Only PEM format is supported (not DER or PKCS#12/PFX)
Private keys must be unencrypted (no password protection)
If your CA uses intermediates, create a fullchain file with the leaf cert first:
cat server.crt intermediate.crt > fullchain.crt
See Certificate and Key Requirements for details.
Step 1: Configure the Gateway Source (Server Side)
The gateway host runs a configuration with the Bindplane Gateway Source, which listens for incoming telemetry over OTLP (gRPC on port 4317, HTTP on port 4318 by default).
Using the Bindplane UI
Edit the configuration used by your gateway host(s)
Select the Bindplane Gateway source
Expand the Advanced section
Check Enable TLS
Set TLS Certificate Path to the path of your server certificate or fullchain file (e.g.,
/etc/collector/certs/fullchain.crt)Set TLS Private Key Path to the path of your unencrypted private key (e.g.,
/etc/collector/certs/server.key)
UI Field Reference
Enable TLS
Enables TLS on the Gateway Source listener
TLS Certificate Path
Server certificate file (can include full chain)
TLS Private Key Path
Server private key file (must be unencrypted)
CA File
CA for optional client verification (does not enforce mTLS)
Client CA File
CA that enforces mTLS (rejects clients without valid certs)
File Permissions
Set appropriate permissions on the gateway host:
Step 2: Configure the Gateway Destination (Client Side)
Each downstream collector runs a configuration with the Bindplane Gateway Destination, which connects to the gateway host over OTLP.
Using the Bindplane UI
Edit the configuration used by your downstream collector(s)
Select the Bindplane Gateway destination
Set Enable TLS to true
Set TLS Certificate Authority File to the CA certificate that signed the gateway's server certificate (e.g.,
/etc/collector/certs/ca.crt)
When is the CA file needed?
Private/internal CA: You must provide the CA certificate file so the downstream collector can verify the gateway's certificate.
Publicly trusted CA (e.g., Let's Encrypt, DigiCert): The system trust store already contains the root CA, so you may not need to specify a CA file.
UI Field Reference
Enable TLS
Enables TLS for the outbound connection to the gateway
Skip TLS Certificate Verification
Skips server certificate validation (not recommended for production)
TLS Certificate Authority File
CA certificate to verify the gateway's server certificate
Server Name Override
Override the expected server hostname in the certificate (useful when connecting by IP)
Mutual TLS
Enables client certificate authentication
Mutual TLS Client Certificate File
Client certificate presented to the gateway
Mutual TLS Client Private Key File
Client private key (must be unencrypted)
Hostname and Certificate Matching
The hostname configured in the Gateway Destination must match either the Common Name (CN) or a Subject Alternative Name (SAN) in the gateway's TLS certificate.
If you need to connect by IP address but your certificate uses a hostname, set the Server Name Override field to the hostname in the certificate.
Step 3: Verify the Connection
After deploying the updated configurations, verify TLS is working from a downstream collector host:
You should see:
The gateway's certificate chain displayed
Verify return code: 0 (ok)
If using a private CA, specify the CA file:
Optional: Adding Mutual TLS (mTLS)
Standard TLS only verifies the gateway's identity to the downstream collectors. Mutual TLS adds the reverse — the gateway also verifies each downstream collector's identity.
When to Use mTLS
You need to restrict which collectors can send data to the gateway
Compliance requires two-way authentication
You want to authenticate collectors by certificate rather than IP address
Gateway Source (Server Side)
Add the Client CA File to enforce mTLS. This causes the gateway to reject any connection that does not present a valid client certificate signed by this CA.
In the Bindplane UI:
Edit the gateway configuration's source
In the Advanced section, set Client CA File to the CA certificate that signed your client certificates (e.g.,
/etc/collector/certs/client-ca.crt)
ca_file vs client_ca_file
CA File (
ca_file): Optional client verification — collectors without certificates can still connectClient CA File (
client_ca_file): Enforced mTLS — all collectors must present valid certificates
Use Client CA File if you want to enforce mTLS. See the Mutual TLS Guide for details.
Gateway Destination (Client Side)
On each downstream collector, enable mutual TLS and provide the client certificate:
Edit the downstream configuration's destination
Enable Mutual TLS
Set Mutual TLS Client Certificate File to the client certificate (e.g.,
/etc/collector/certs/client.crt)Set Mutual TLS Client Private Key File to the client private key (e.g.,
/etc/collector/certs/client.key)
Verify mTLS
Test that the gateway accepts connections with a valid client certificate:
Test that the gateway rejects connections without a client certificate:
Troubleshooting
"Unknown CA" from downstream collectors
Missing intermediate certificates in the gateway's cert file
Create a fullchain: cat server.crt intermediate.crt > fullchain.crt and use it as the TLS Certificate Path on the gateway source
"Failed to load TLS cert and key" on the gateway
Encrypted private key or non-PEM format
Decrypt with openssl rsa -in encrypted.key -out decrypted.key, or convert from DER with openssl x509 -inform DER -in cert.der -out cert.pem
"Certificate and key do not match" on the gateway
Wrong key file paired with the certificate
Verify they match: openssl x509 -noout -modulus -in server.crt | openssl md5 and openssl rsa -noout -modulus -in server.key | openssl md5 — hashes must be identical
TLS handshake timeout
TLS version incompatibility
Ensure both sides support TLS 1.2+; check min_version on the gateway source
Downstream collectors connect without certs when mTLS is expected
Using ca_file instead of client_ca_file on the gateway source
Switch to Client CA File (client_ca_file) to enforce mTLS
"Certificate required" errors from downstream collectors
mTLS is enforced but the destination doesn't have client certs configured
Enable Mutual TLS on the Gateway Destination and provide the client certificate and key
For additional troubleshooting, see the TLS Troubleshooting Guide.
Related Resources
Last updated
Was this helpful?