# TLS Configuration Guide

## 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

{% hint style="info" %}
For mutual TLS (mTLS) configuration where both server and clients authenticate each other, see the [Mutual TLS Guide](/how-to-guides/security-and-tls/using-tls/mutual-tls.md).
{% endhint %}

## Configuration: UI vs YAML Field Names

{% hint style="warning" %}
**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.
{% endhint %}

## 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                      |

{% hint style="info" %}
**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.
{% endhint %}

### 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

{% hint style="info" %}
**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.
{% endhint %}

### 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:

```yaml
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"
```

{% hint style="info" %}
**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)
  {% endhint %}

### Syslog Receiver with TLS

```yaml
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"
```

{% hint style="info" %}
**Note:** The syslog receiver uses nested `tcp:` or `udp:` blocks instead of a `transport:` parameter.
{% endhint %}

### OTLP Receiver with TLS

{% hint style="info" %}
**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](/how-to-guides/security-and-tls/using-tls/gateway-tls.md).
{% endhint %}

```yaml
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](/how-to-guides/security-and-tls/using-tls/mutual-tls.md).

## Advanced Configuration

### Certificate Reloading

Automatically reload certificates without restarting the collector:

```yaml
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
```

{% hint style="success" %}
**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).
{% endhint %}

### Cipher Suite Configuration

Specify allowed cipher suites for enhanced security:

```yaml
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
```

{% hint style="warning" %}
**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.
{% endhint %}

### TLS Version Restrictions

```yaml
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

{% hint style="success" %}
**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.
{% endhint %}

### 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

{% tabs %}
{% tab title="Linux/macOS" %}

```bash
# 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
```

{% endtab %}

{% tab title="Windows PowerShell" %}

```powershell
# Private key should only be readable by the collector user
icacls C:\certs\server.key /inheritance:r /grant:r "$($env:USERNAME):(R)"

# Certificate can be more permissive (read access for all users)
icacls C:\certs\fullchain.crt /grant:r "Everyone:(R)"
```

{% endtab %}
{% endtabs %}

### 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:

{% tabs %}
{% tab title="Linux/macOS" %}

```bash
# 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
```

{% endtab %}

{% tab title="Windows PowerShell" %}

```powershell
# 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
```

{% endtab %}
{% endtabs %}

For detailed testing instructions, see [Testing and Verification](/how-to-guides/security-and-tls/using-tls/reference/testing-verification.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bindplane.com/how-to-guides/security-and-tls/using-tls/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.