Connect Edge behind a proxy — Debian-based

Running ThingsBoard Edge behind a proxy server means all outbound communication — specifically the gRPC connection to the ThingsBoard server on port 17100 — is routed through the proxy instead of going directly to the internet.

This setup is common in restricted network environments where direct internet access is deliberately blocked. Proxies also add a security layer by filtering and monitoring outbound traffic, and can cache resources to reduce bandwidth usage.

• A proxy server (HTTP or HTTPS) with its host, port, and credentials if required.
• A list of addresses that should bypass the proxy (e.g., internal resources). Note that the Debian configuration uses | as the separator, not commas.
• Java 17 must be installed on the Edge device.
• ThingsBoard Edge must be installed and running.

Edit /etc/tb-edge/conf/tb-edge.conf to enable the proxy:

sudo tee -a /etc/tb-edge/conf/tb-edge.conf > /dev/null <<EOL
#Enable the proxy
export CLOUD_RPC_PROXY_ENABLED=true

#Set the proxy server host and port
export CLOUD_RPC_PROXY_HOST="proxy_host"
export CLOUD_RPC_PROXY_PORT="proxy_port"
EOL

Replace proxy_host and proxy_port with your proxy’s hostname and port.

If certain hosts should bypass the proxy (e.g., local network addresses), add a NO_PROXY variable:

export NO_PROXY="localhost|127.0.0.1|yourdomain.com"

If your proxy requires authentication, append the following to the same file:

export CLOUD_RPC_PROXY_USERNAME="proxy_username"
export CLOUD_RPC_PROXY_PASSWORD="proxy_password"

Replace proxy_username and proxy_password with your actual credentials.

cat /etc/tb-edge/conf/tb-edge.conf

Confirm that CLOUD_RPC_PROXY_ENABLED, CLOUD_RPC_PROXY_HOST, and CLOUD_RPC_PROXY_PORT appear with the correct values.

sudo service tb-edge restart

Once restarted, open the Edge UI at http://localhost:8080 and log in with your tenant credentials. Go to Edge → Status and confirm the Status field shows Connected — this confirms Edge is reaching the server through the proxy.

Check Edge logs for errors:

cat /var/log/tb-edge/tb-edge.log | grep ERROR

Test connectivity through the proxy:

curl -x http://proxy_host:proxy_port https://your_tb_cloud_url

Confirm the proxy host is reachable:

ping proxy_host
traceroute proxy_host