Skip to main content

TLS and certificates for a Praxis Gateway collector installation

This page explains which files exist, what each one is for, and how to create them when you are not using a public certificate authority (typical lab or private-PKI setup). It complements Configuration, which maps these ideas onto the OTLP Source (on the Praxis Gateway collector) and OTLP Destination (on other Praxis collectors that send to the Praxis Gateway collector).

Throughout this page, <TLS_DIRECTORY> means an absolute path on that specific host where PEM files live. You choose it (for example /etc/praxis-collector/tls on Linux, a Kubernetes Secret mount path, or another path your security team mandates). The Praxis management plane persists the path strings you enter in pipeline configuration (it is the control and insights surface, not a telemetry export destination in your pipeline graph). Nothing requires a fixed directory name.

What each role needs on disk​

RoleTypical PEM filesPurpose
Praxis Gateway collector (TLS server)Server certificate + matching private keyProves Praxis Gateway collector identity to clients; enables encrypted session.
Praxis Gateway collector (mTLS only)CA certificate (public) referenced as client_ca_fileTrust anchor used to verify client certificates presented by collectors.
Praxis collector (TLS client)CA certificate (public) referenced as ca_fileTrust anchor used to verify the Praxis Gateway collector’s server certificate.
Praxis collector (mTLS only)Client certificate + matching private keyProves Praxis collector identity to the Praxis Gateway collector when it requests a client cert.

Important: the CA private key (ca.key in the examples below) is used only when issuing or rotating certificates. It should not be copied onto collector hosts unless you have a deliberate operational reason (for example a dedicated signing host). Collectors only need public CA material (ca.crt) for verification.

TLS terminology (short)​

  • CA (certificate authority) — a key pair whose public half (ca.crt) is distributed as a trust anchor. The private half signs server and client certificates.
  • Server certificate — binds a public key to names (DNS and/or IP in Subject Alternative Name, SAN). Signed by the CA. Presented by the Praxis Gateway collector during the TLS handshake.
  • One-way TLS — clients verify the server; the server does not use client certificates.
  • mTLS (mutual TLS) — both sides present certificates. The Praxis Gateway collector sets client_ca_file so it only accepts clients whose cert chains to that CA.

Create a private CA and certificates with OpenSSL​

The commands below are suitable for labs and internal networks. For production, many teams use an existing PKI (HashiCorp Vault, step-ca, cloud CA, or corporate Microsoft AD CS) instead of manual OpenSSL; the same PEM artifacts (ca.crt, server cert+key, client cert+key) are what the pipeline fields reference.

Set a working directory on a secure machine (often your laptop or a jump host), not on production servers:

export TLS_LAB=~/praxis-tls-ca
mkdir -p "$TLS_LAB" && cd "$TLS_LAB"

1. Create the CA​

openssl genrsa -out ca.key 4096
openssl req -x509 -new -nodes -key ca.key -sha256 -days 3650 \
  -subj "/CN=praxis-test-ca" -out ca.crt
  • ca.key — CA private key (keep offline or in a vault; do not ship to collectors).
  • ca.crt — CA public certificate; clients use this as ca_file to trust the Praxis Gateway collector; the Praxis Gateway collector uses the same file (or another CA bundle) as client_ca_file if that same CA signed the client certs.

2. Create a server key and CSR for the Praxis Gateway collector​

Replace SAN entries with the DNS names and/or IPs your Praxis collectors actually use in grpc_endpoint / http_endpoint. A mismatch is the most common cause of x509: certificate is valid for ... errors.

openssl genrsa -out gateway.key 4096

cat > gateway.cnf <<'EOF'
[ req ]
default_bits       = 4096
prompt             = no
default_md         = sha256
distinguished_name = dn
req_extensions     = v3_req

[ dn ]
CN = praxis-gateway

[ v3_req ]
subjectAltName = @alt_names

[ alt_names ]
DNS.1 = gateway.internal.example
IP.1 = 10.0.0.10
EOF

openssl req -new -key gateway.key -out gateway.csr -config gateway.cnf

Edit gateway.cnf so DNS.* / IP.* match your real Praxis Gateway collector hostname and/or IP.

3. Sign the Praxis Gateway collector certificate with your CA​

openssl x509 -req -in gateway.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out gateway.crt -days 825 -sha256 -extensions v3_req -extfile gateway.cnf
  • gateway.crt + gateway.key — install on the Praxis Gateway collector host only; point the OTLP Source cert_file / key_file at these paths (under whatever <TLS_DIRECTORY> you use).

4. Create a client key and CSR (for mTLS)​

openssl genrsa -out client.key 4096
openssl req -new -key client.key -out client.csr -subj "/CN=praxis-internal-collector"

For per-host client identity, repeat with a different CN (or SANs) per VM and sign separate certs.

5. Sign the client certificate​

openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out client.crt -days 825 -sha256

Confirm the chain:

openssl verify -CAfile ca.crt gateway.crt
openssl verify -CAfile ca.crt client.crt

Install PEM files on hosts​

  1. Copy gateway.crt and gateway.key to the Praxis Gateway collector’s <TLS_DIRECTORY> (and lock down permissions on the private key, typically 600).
  2. Copy ca.crt to every Praxis collector that sends to the Praxis Gateway collector — into each host’s <TLS_DIRECTORY> (mode 644 is typical for public certs).
  3. For mTLS, copy client.crt and client.key to every such Praxis collector (or distinct pairs per host). Protect client.key like any secret (600).
  4. On the Praxis Gateway collector, client_ca_file must point at the public CA that signed client.crt (often the same ca.crt as in the verify commands above).

In the Praxis management plane, every cert_file, key_file, ca_file, and client_ca_file field must use the absolute path on that host where the file actually lives after installation.

Roll out mTLS without a long outage​

If you enable client_ca_file on the Praxis Gateway collector before collectors are configured to present cert_file / key_file, new handshakes can fail until clients catch up.

Practical order:

  1. Install client.crt / client.key on each host and configure each Praxis collector OTLP destination with cert_file / key_file (and existing ca_file, enabled: true, insecure: false).
  2. Restart those Praxis collectors so they begin offering a client certificate when the server asks.
  3. Add client_ca_file on the Praxis Gateway collector OTLP Source and restart the Praxis Gateway collector.

Reverse order when turning off mTLS: remove client_ca_file from the Praxis Gateway collector first, restart the Praxis Gateway collector, then remove client certs from collectors if desired.

Verify TLS from the command line​

Server TLS only (checks the Praxis Gateway collector presents a cert your CA trusts):

openssl s_client -connect <GATEWAY_HOST>:4317 -CAfile ca.crt </dev/null

mTLS (also presents a client cert):

openssl s_client -connect <GATEWAY_HOST>:4317 -CAfile ca.crt \
  -cert client.crt -key client.key </dev/null

Look for Verify return code: 0 (ok) in the output. Run the same style of check from an internal host if firewalls treat laptop traffic differently.

Operational notes​

  • Rotation — when you renew the Praxis Gateway collector's server certificate, Praxis collectors that trust that CA in ca_file usually need no change if the new cert is still signed by the same CA. When you rotate the CA, update ca_file on all clients and client_ca_file on the Praxis Gateway collector before retiring the old issuer.
  • Hostname checks — clients validate that the name they dial matches the certificate SAN. Connecting by IP requires an IP SAN on the server cert, or configure the exporter’s authority/SNI settings per your collector and cert layout.
  • Never set client insecure: true when grpc_tls.enabled / http_tls.enabled is true in production; that combination disables server certificate verification and defeats TLS for authentication (encryption may still occur against an untrusted peer).
  • Configuration — Praxis Gateway collector and Praxis collector OTLP settings, bearer token, pitfalls.
  • OTLP Source — receiver TLS field reference.
  • OTLP Destination — exporter TLS field reference.