# Quick Start

## Before You Begin

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

## Quick Format Verification

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

### **Check Certificate Format**

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

```bash
head -5 /path/to/certificate.crt
```

{% endtab %}

{% tab title="Windows PowerShell" %}

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

{% endtab %}
{% endtabs %}

You should see:

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

### **Check Private Key Format**

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

```bash
head -5 /path/to/private.key
```

{% endtab %}

{% tab title="Windows PowerShell" %}

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

{% endtab %}
{% endtabs %}

You should see one of these (unencrypted):

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

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

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

{% hint style="danger" %}
**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](/how-to-guides/security-and-tls/using-tls/requirements.md#encrypted-private-keys-are-not-supported) for instructions.
{% endhint %}

## Minimal Working Configuration

For more detailed information on configuration, see the [Configuration Guide](/how-to-guides/security-and-tls/using-tls/configuration.md).

### For TCP Receiver

```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:**

* 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)
  {% endhint %}

### For Syslog Receiver

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

## File Permissions

Ensure proper file permissions for security:

{% 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 %}

## Test Your Configuration

After configuring TLS, test the connection with OpenSSL:

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

```bash
openssl s_client -connect <collector-hostname>:10514
```

{% endtab %}

{% tab title="Windows PowerShell" %}

```powershell
openssl s_client -connect <collector-hostname>:10514
```

{% endtab %}
{% endtabs %}

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](/how-to-guides/security-and-tls/using-tls/reference/testing-verification.md).

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

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

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

{% endtab %}

{% tab title="Windows PowerShell" %}

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

{% endtab %}
{% endtabs %}

See [Troubleshooting: Certificate Mismatch](/how-to-guides/security-and-tls/using-tls/troubleshooting.md#issue-certificate-and-key-do-not-match-private-key-does-not-match-public-key) 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:

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

```bash
cat server.crt intermediate.crt > fullchain.crt
```

{% endtab %}

{% tab title="Windows PowerShell" %}

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

{% endtab %}
{% endtabs %}

See [Certificate Requirements: Certificate Chain](/how-to-guides/security-and-tls/using-tls/requirements.md#certificate-chain-requirements) for details.

### Issue: Collector won't start

**Cause:** Encrypted private key or wrong format.

**Quick Fix:**

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

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

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

{% endtab %}

{% tab title="Windows PowerShell" %}

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

{% endtab %}
{% endtabs %}

See [Troubleshooting: Failed to Load](/how-to-guides/security-and-tls/using-tls/troubleshooting.md#issue-collector-fails-to-start-with-failed-to-load-tls-cert-and-key-or-similar-error) for details.

## Next Steps

**Verify your setup works:**

* [Testing and Verification Guide](/how-to-guides/security-and-tls/using-tls/reference/testing-verification.md)

**Configure mutual TLS (mTLS):**

* [Mutual TLS Guide](/how-to-guides/security-and-tls/using-tls/mutual-tls.md)

**Having issues?**

* [Troubleshooting Guide](/how-to-guides/security-and-tls/using-tls/troubleshooting.md)

**Want to understand TLS better?**

* [TLS Concepts](/how-to-guides/security-and-tls/using-tls/reference/tls-concepts.md)

**Need to convert certificate formats?**

* [Certificate Conversion Guide](/how-to-guides/security-and-tls/using-tls/reference/certificate-conversion.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/quick-start.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.