Overview

This guide covers two approaches for generating TLS certificates for use in the communication between Sensor Agents / Telemetry Collector and the Sensor Collector:

1. Self-Signed TLS Certificate - A single certificate that signs itself

2. CA-Signed TLS Certificate - A TLS certificate signed by a self-signed Certificate Authority

Key Differences

Self-Signed TLS Certificate:

• Simpler and faster to generate (single command)

• The certificate acts as its own authority

• Best for: Simple testing, development environments, single-server deployments

• Maintains backward compatibility with existing Sensor Agents configurations

CA-Signed TLS Certificate:

• More complex setup (multiple steps)

• Separate CA certificate can sign multiple TLS certificates

• Best for: Production environments, managing multiple servers/certificates, following enterprise PKI practices

• Sensor Agents must be provided the CA certificate in PEM format to validate the Sensor Collector’s certificate

Certificate Chain Comparison

With a self-signed TLS certificate, the certificate signs itself and is used directly by the Sensor Collector. There is no separate authority — the TLS certificate is its own trust anchor.

With a CA-signed TLS certificate, a self-signed Certificate Authority (CA) acts as the trust anchor. The CA signs the TLS certificate, which is then used by the Sensor Collector. Sensor Agents are configured to trust the CA certificate, which allows them to validate any TLS certificate signed by that CA.

Trust Model

In the self-signed approach, each client or Sensor Agent must explicitly trust the individual TLS certificate. If the certificate is replaced, all clients must be updated with the new certificate.

In the CA-signed approach, clients trust the CA certificate once. Any TLS certificate signed by that CA is then automatically validated. This means you can issue or rotate TLS certificates without updating the Sensor Agents, as long as the CA certificate remains the same.

Typical Certificate Expiration Periods

Informational: The table below outlines industry-standard certificate expiration periods. These are general guidelines — adjust based on your organization's security policies.

Note: For internal self-signed deployments, a common approach is to set the CA certificate to 10 years and TLS certificates to 1–2 years. The CA is harder to rotate (all Sensor Agents must be updated), while TLS certificates only require updating the Sensor Collector.

Generate a Self-Signed TLS Certificate

If you need a simple self-signed TLS certificate without a separate CA (useful for testing or development), you can create one with a single command:

# generate a self-signed TLS certificate and private key
openssl req -x509 -newkey rsa:2048 -keyout tls.key -out tls.crt -outform DER -days 3650 -nodes

File Reference

Note: Self-signed TLS certificates are not signed by a trusted CA, so clients will show security warnings unless the certificate is explicitly trusted.

Generate a Self-Signed CA and CA-Signed TLS Certificate

Note: The same CA certificate can and should be used to sign multiple TLS certificates (e.g., for different servers or services). This approach requires distributing only a single CA certificate (in PEM format) to all Sensor Agents, which can then validate all TLS certificates signed by that CA. This significantly simplifies certificate management in environments with multiple Sensor Collector or services.

To generate a self-signed CA certificate and use it to sign a TLS certificate, execute the following commands in a terminal on a machine with OpenSSL installed:

# generate CA DER certificate and private key
openssl req -x509 -newkey rsa:2048 -keyout myNewCa.key -out myNewCa.crt -outform DER -days 3650 -nodes

# generate TLS private key
openssl genpkey -algorithm RSA -outform DER -out tls.key -pkeyopt rsa_keygen_bits:2048

# generate certificate request for TLS certificates
openssl req -new -key tls.key -out myNewCa.csr -outform DER

# sign TLS certificate with CA certificate
openssl x509 -req -inform DER -in myNewCa.csr -CA myNewCa.crt -CAkey myNewCa.key -CAcreateserial -out tls.crt -days 3650 -outform DER

# convert certificates to PEM format needed to add to other systems trusted certificate store
openssl x509 -in myNewCa.crt -inform DER -out myNewCa.pem -outform PEM
openssl x509 -in tls.crt -inform DER -out tls.pem -outform PEM

File Reference

Loading Local Certificates in Sensor Agents and Telemetry Collectors

For Sensor Agents and Telemetry Collectors to accept connections with the CA-Signed TLS Certificate, the Self-Signed CA must be added to their trusted CA certificate store.

The CA certificate (myNewCa.pem) is mounted into /usr/local/share/ca-certificates/ inside the container. At startup, the agent runs update-ca-certificates which adds it to the system trust store.

Command

docker run --rm -it \
      -e AGENT_MANAGEMENT_PROXY=198.51.100.1 \
      --log-driver json-file --log-opt max-size=10m --log-opt max-file=3 \
      --mount type=bind,source=./secrets.yaml,target=/run/secrets/secrets.yaml \
      --mount type=bind,source=./myNewCa.pem,target=/usr/local/share/ca-certificates/myNewCa.pem \
      <IMAGE>

Docker Compose Example

services:
  sensor-agent:
    image: <IMAGE>
    environment:
      - AGENT_MANAGEMENT_PROXY=198.51.100.1
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    volumes:
      - type: bind
        source: ./secrets.yaml
        target: /run/secrets/secrets.yaml
      - type: bind
        source: ./myNewCa.pem
        target: /usr/local/share/ca-certificates/myNewCa.pem

Using a Named Volume for Multiple Sensor Agents and Telemetry Collectors

When deploying multiple Sensor Agents and Telemetry Collectors on the same host, consider using a Docker named volume to share the CA certificate(s) across all containers. This avoids duplicating bind mounts and keeps the certificate source in a single, managed location.

Setup

Create the named volume and populate it with the CA certificate:

# create the named volume
docker volume create ca-certificates

# copy the CA certificate into the volume using a temporary container
docker run --rm \
      -v ca-certificates:/certs \
      -v ./myNewCa.pem:/tmp/myNewCa.pem:ro \
      alpine cp /tmp/myNewCa.pem /certs/myNewCa.pem

Docker Compose Example

volumes:
  ca-certificates:
    external: true

services:
  sensor-agent-1:
    image: <AGENT_IMAGE>
    environment:
      - AGENT_MANAGEMENT_PROXY=198.51.100.1
    volumes:
      - type: bind
        source: ./secrets.yaml
        target: /run/secrets/secrets.yaml
      - type: volume
        source: ca-certificates
        target: /usr/local/share/ca-certificates/custom
        read_only: true

  sensor-agent-2:
    image: <AGENT_IMAGE>
    environment:
      - AGENT_MANAGEMENT_PROXY=198.51.100.2
    volumes:
      - type: bind
        source: ./secrets.yaml
        target: /run/secrets/secrets.yaml
      - type: volume
        source: ca-certificates
        target: /usr/local/share/ca-certificates/custom
        read_only: true

  telemetry-collector:
    image: <COLLECTOR_IMAGE>
    volumes:
      - type: bind
        source: ./secrets.yaml
        target: /run/secrets/secrets.yaml
      - type: volume
        source: ca-certificates
        target: /usr/local/share/ca-certificates/custom
        read_only: true

Advantages

• Single source of truth — The CA certificate is stored once in the named volume. All containers reference the same data, eliminating inconsistencies from separate bind mounts.

• Simplified certificate rotation — Update the certificate in the volume once and restart the containers. No need to update paths or files in multiple locations.

• No host path dependency — Named volumes are managed by Docker and do not depend on a specific file path on the host. This makes deployments portable across hosts.

• Read-only access — Mounting the volume as read_only: true prevents containers from accidentally modifying the shared certificates.