Quick Start

Get TLS configured on your Bindplane collector receiver in minutes.

Before You Begin

Critical Format Requirements

Your certificates and keys MUST meet these requirements:

• Format: PEM only (text files with -----BEGIN CERTIFICATE----- headers)
• Private Key: Must be unencrypted (no password protection)
• Not Supported: DER format (binary), PKCS#12/PFX files (.p12, .pfx)

If your certificates don't meet these requirements, see Certificate Conversion.

Quick Format Verification

Before proceeding, verify your certificate and key files are in the correct format:

Check Certificate Format

Linux/macOS

head -5 /path/to/certificate.crt

Windows PowerShell

Get-Content C:\certs\certificate.crt -First 5

You should see:

-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAKJ3PqGFGNkqMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV
...

Check Private Key Format

Linux/macOS

head -5 /path/to/private.key

Windows PowerShell

Get-Content C:\certs\private.key -First 5

You should see one of these (unencrypted):

-----BEGIN PRIVATE KEY-----

-----BEGIN RSA PRIVATE KEY-----

-----BEGIN EC PRIVATE KEY-----

Do NOT use encrypted keys

If you see -----BEGIN ENCRYPTED PRIVATE KEY----- or Proc-Type: 4,ENCRYPTED, your key is encrypted and will NOT work. See Certificate Requirements: Decrypting Keys for instructions.

Minimal Working Configuration

For more detailed information on configuration, see the Configuration Guide.

For TCP Receiver

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:

• Enables TLS on the TCP receiver listening on port 10514
• Presents your server certificate to connecting clients
• Requires TLS 1.2 or higher
• Clients verify your server's certificate (standard TLS)

For Syslog Receiver

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"

File Permissions

Ensure proper file permissions for security:

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

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

Test Your Configuration

After configuring TLS, test the connection with OpenSSL:

Linux/macOS

openssl s_client -connect <collector-hostname>:10514

Windows PowerShell

openssl s_client -connect <collector-hostname>:10514

You should see:

• Connection established
• Certificate chain displayed
• Verify return code: 0 (ok) or appropriate verification result

For detailed testing instructions, see Testing and Verification.

Common Quick Start Issues

Issue: "Certificate and key do not match"

Cause: The certificate and private key files don't correspond to each other.

Quick Fix:

Linux/macOS

# Verify they match
openssl rsa -in server.key -pubout -out key_public.pem
openssl x509 -in server.crt -pubkey -noout -out cert_public.pem
diff key_public.pem cert_public.pem
# No output = they match

Windows PowerShell

# Verify they match
openssl rsa -in C:\certs\server.key -pubout -out C:\certs\key_public.pem
openssl x509 -in C:\certs\server.crt -pubkey -noout -out C:\certs\cert_public.pem
Compare-Object (Get-Content C:\certs\key_public.pem) (Get-Content C:\certs\cert_public.pem)
# No output = they match

See Troubleshooting: Certificate Mismatch for details.

Issue: "Unknown CA" from clients

Cause: Missing intermediate certificates in the certificate chain.

Quick Fix: Create a fullchain file with your server certificate + intermediates:

Linux/macOS

cat server.crt intermediate.crt > fullchain.crt

Windows PowerShell

Get-Content C:\certs\server.crt, C:\certs\intermediate.crt | Set-Content C:\certs\fullchain.crt

See Certificate Requirements: Certificate Chain for details.

Issue: Collector won't start

Cause: Encrypted private key or wrong format.

Quick Fix:

Linux/macOS

# Check if key is encrypted
head -10 server.key

# If encrypted, decrypt it
openssl rsa -in encrypted-server.key -out server.key

Windows PowerShell

# Check if key is encrypted
Get-Content C:\certs\server.key -First 10

# If encrypted, decrypt it
openssl rsa -in C:\certs\encrypted-server.key -out C:\certs\server.key

See Troubleshooting: Failed to Load for details.

Next Steps

Verify your setup works:

• Testing and Verification Guide

Configure mutual TLS (mTLS):

• Mutual TLS Guide

Having issues?

• Troubleshooting Guide

Want to understand TLS better?

• TLS Concepts

Need to convert certificate formats?

• Certificate Conversion Guide