Skip to main content

TLS for web and OpAMP traffic

FleetAMP can encrypt both externally visible transports:

TrafficSecure URLAuthentication
Browser to FleetAMPhttps://fleetamp.example.comAdministrator session
OTel Supervisor to FleetAMPwss://fleetamp.example.com/v1/opampBearer token, optionally mTLS

Use certificates issued by the enterprise PKI or a public CA. Never commit a private key, bearer token, server pepper, generated database, or local certificate workspace to Git.

Default certificate locations​

The user installer creates ~/.config/fleetamp/tls with mode 0700. A system-wide installation uses /etc/fleetamp/tls. When TLS is enabled, FleetAMP looks for these default filenames:

  • server.crt — web and OpAMP server certificate
  • server.key — web and OpAMP private key
  • agent-ca.crt — optional CA used to verify OpAMP client certificates

Customers can change the directory with FLEETAMP_TLS_DIR, or independently override any path with the listener-specific certificate variables. Paths must be absolute in service environment files; shell shortcuts such as ~ are not expanded by systemd.

Native TLS​

Configure native HTTPS for the web UI/API:

FLEETAMP_HTTP_ADDR=0.0.0.0:8443
FLEETAMP_TLS_DIR=/etc/fleetamp/tls
FLEETAMP_HTTP_TLS_ENABLED=true
FLEETAMP_SECURE_COOKIES=true
FLEETAMP_ALLOWED_ORIGINS=https://fleetamp.example.com:8443

Configure secure WebSockets for OpAMP:

FLEETAMP_OPAMP_ADDR=0.0.0.0:4320
FLEETAMP_OPAMP_TOKEN=<at-least-32-random-characters>
FLEETAMP_OPAMP_TLS_ENABLED=true
# Optional overrides when OpAMP uses a different certificate:
# FLEETAMP_OPAMP_TLS_CERT_FILE=/custom/path/opamp.crt
# FLEETAMP_OPAMP_TLS_KEY_FILE=/custom/path/opamp.key

FleetAMP requires TLS 1.2 or newer and validates the certificate/key pair during startup. A remote listener fails closed when neither native TLS nor trusted TLS termination is configured.

Give the service account read access to the certificate and private key, and no other account access to the key:

sudo install -d -o fleetamp -g fleetamp -m 0700 /etc/fleetamp/tls
sudo install -o fleetamp -g fleetamp -m 0644 server.crt /etc/fleetamp/tls/
sudo install -o fleetamp -g fleetamp -m 0600 server.key /etc/fleetamp/tls/

Restart FleetAMP after certificate renewal. Native certificate hot reload is not currently implemented.

OpAMP mutual TLS​

mTLS makes the Supervisor prove possession of a client private key signed by a trusted agent CA. Keep the bearer token enabled as an additional control.

FLEETAMP_OPAMP_TLS_REQUIRE_CLIENT_CERT=true
# Optional override; defaults to $FLEETAMP_TLS_DIR/agent-ca.crt
# FLEETAMP_OPAMP_TLS_CLIENT_CA_FILE=/custom/path/agent-ca.crt

Each Supervisor needs its own certificate and private key. Configure its OpAMP client for the secure wss:// endpoint, the server CA bundle, its client certificate/key, and the bearer authorization header. Exact field names depend on the Supervisor release; verify them against that release's configuration reference.

mTLS currently establishes trusted transport identity. FleetAMP does not yet map certificate subjects to agent-level authorization policy, so certificates must not be treated as RBAC identities.

Trusted TLS termination​

A reverse proxy or load balancer may terminate TLS instead. Keep FleetAMP on a private interface reachable only from that proxy, then declare termination:

FLEETAMP_HTTP_TLS_TERMINATED=true
FLEETAMP_OPAMP_TLS_TERMINATED=true
FLEETAMP_SECURE_COOKIES=true

Do not enable these flags merely to bypass startup validation. They assert that the full client-facing path is protected by HTTPS/WSS. Restrict backend ports with host and cloud firewalls.

For an AWS ALB proof of concept, use an ACM certificate on the HTTPS listener, enable WebSocket forwarding for /v1/opamp, and allow the EC2 instance ports only from the ALB security group. End-to-end mTLS to individual Supervisors normally requires native TLS or a proxy that preserves and verifies client certificates.

Fedora test certificate​

For a local-only test, create an ignored certificate directory outside the repository:

install -d -m 0700 ~/.config/fleetamp/tls
openssl req -x509 -newkey rsa:3072 -sha256 -nodes -days 30 \
  -keyout ~/.config/fleetamp/tls/server.key \
  -out ~/.config/fleetamp/tls/server.crt \
  -subj "/CN=localhost" \
  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"
chmod 0600 ~/.config/fleetamp/tls/server.key

Reference those absolute paths in ~/.config/fleetamp/fleetamp.env. Browsers will warn about this self-signed certificate until it is explicitly trusted; enterprise testing should use a certificate issued by the approved CA.

Verification​

After a controlled restart:

systemctl --user status fleetamp
journalctl --user -u fleetamp --since "10 minutes ago"
curl --cacert ~/.config/fleetamp/tls/server.crt https://localhost:8443/health
openssl s_client -connect localhost:4320 -servername localhost </dev/null

Confirm the UI uses HTTPS, its session cookie contains Secure, and the Supervisor connects to wss:// without disabling certificate verification. A plain http:// or ws:// request to a native TLS port must fail.