Configuration reference
All Edge-specific configuration is set via environment variables in /etc/tb-edge/conf/tb-edge.conf. The sections below cover every cloud.* variable — credentials, server connection, keepalive, SSL/TLS, cloud event delivery, proxy, and stats.
Credentials
Section titled “Credentials”These two variables identify the Edge instance to the server. Generate them by creating an Edge instance on the server and copying the key and secret from the Edge details page.
| Variable | Default | Description |
|---|---|---|
CLOUD_ROUTING_KEY | (empty) | The Edge routing key generated when the Edge instance was provisioned on the server. |
CLOUD_ROUTING_SECRET | (empty) | The Edge secret generated alongside the routing key. |
Both values are required. Edge will not connect to the server if either is missing or incorrect — the server returns BAD_CREDENTIALS and the Cloud Manager retries after CLOUD_RECONNECT_TIMEOUT.
Server connection
Section titled “Server connection”| Variable | Default | Description |
|---|---|---|
CLOUD_RPC_HOST | localhost | Hostname or IP address of the ThingsBoard server. |
CLOUD_RPC_PORT | 7070 | gRPC port on the ThingsBoard server. Open this port in your firewall rules. |
CLOUD_RPC_TIMEOUT | 5 | gRPC call timeout in seconds. |
CLOUD_RECONNECT_TIMEOUT | 3000 | Milliseconds to wait before reconnecting after a dropped connection. During this interval, events continue to accumulate in the cloud event queue. |
CLOUD_UPLINK_PACK_TIMEOUT_SEC | 60 | Seconds to wait for an uplink acknowledgement from the server before timing out. |
Keepalive
Section titled “Keepalive”HTTP/2 keepalive pings detect silent TCP failures and unresponsive servers. The default values work well on stable LANs. Tighten them on unreliable links.
| Variable | Default | Description |
|---|---|---|
CLOUD_RPC_KEEP_ALIVE_TIME_SEC | 10 | Seconds between keepalive pings sent to the server. |
CLOUD_RPC_KEEP_ALIVE_TIMEOUT_SEC | 5 | Seconds to wait for a keepalive response before treating the connection as dead. |
For guidance on tuning these values for unstable networks, see gRPC keep-alive.
Message size
Section titled “Message size”| Variable | Default | Description |
|---|---|---|
CLOUD_RPC_MAX_INBOUND_MESSAGE_SIZE | 4194304 | Maximum gRPC message size Edge will accept, in bytes. The default is 4 MB. Increase this if you receive RESOURCE_EXHAUSTED errors when receiving large downlink messages, such as dashboards with many widgets. |
SSL/TLS
Section titled “SSL/TLS”By default, the Edge-to-server gRPC connection is unencrypted. Enable TLS when Edge connects to the server over an untrusted network.
| Variable | Default | Description |
|---|---|---|
CLOUD_RPC_SSL_ENABLED | false | Enables TLS for the Edge-to-server gRPC connection. |
CLOUD_RPC_SSL_CERT | (empty) | Path to the server certificate file. Required only when the server uses a self-signed certificate. Leave empty when the server certificate is issued by a trusted CA. |
Cloud event delivery
Section titled “Cloud event delivery”These variables control how the Cloud Manager reads from the cloud event queue and sends uplink batches to the server.
| Variable | Default | Description |
|---|---|---|
CLOUD_RPC_STORAGE_MAX_READ_RECORDS_COUNT | 50 | Maximum events per uplink batch. Increase on high-throughput deployments to reduce round-trips. |
CLOUD_RPC_SLEEP_BETWEEN_BATCHES | 1000 | Milliseconds to pause between consecutive uplink batches. |
CLOUD_RPC_NO_READ_RECORDS_SLEEP | 1000 | Milliseconds to wait before polling the queue again when it is empty. |
CLOUD_RPC_MISORDERING_COMPENSATION_MILLIS | 60000 | Extra wait time in milliseconds before sending events that may have arrived out of order. Reduce this value only if you are certain events are always written in order. |
When Edge runs behind an HTTP CONNECT proxy, configure these variables to route gRPC traffic through it.
| Variable | Default | Description |
|---|---|---|
CLOUD_RPC_PROXY_ENABLED | false | Enables proxy routing for the gRPC connection. |
CLOUD_RPC_PROXY_HOST | (empty) | Proxy hostname or IP address. |
CLOUD_RPC_PROXY_PORT | 0 | Proxy port. |
CLOUD_RPC_PROXY_USERNAME | (empty) | Proxy username, if the proxy requires authentication. |
CLOUD_RPC_PROXY_PASSWORD | (empty) | Proxy password, if the proxy requires authentication. |
For a step-by-step setup guide, see Connect Edge behind a proxy.
Stats reporting
Section titled “Stats reporting”Edge periodically reports connection and message-processing statistics back to the server as telemetry on the Edge entity.
| Variable | Default | Description |
|---|---|---|
CLOUD_STATS_ENABLED | true | Enables stats telemetry reporting. |
CLOUD_STATS_REPORT_INTERVAL_MS | 60000 | Milliseconds between stats reports. |
CLOUD_STATS_TTL | 2592000 | Retention period for stats data in seconds. The default is 30 days. |