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.

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.

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	Seconds to wait for the gRPC channel to shut down when Edge disconnects.
CLOUD_RECONNECT_TIMEOUT	3000	Milliseconds to wait before the first reconnect attempt after a dropped connection. The delay grows exponentially with each failed attempt. During this time, events continue to accumulate in the cloud event queue.
CLOUD_RECONNECT_MAX_TIMEOUT	180000	Upper bound, in milliseconds, of the reconnect delay.
CLOUD_RECONNECT_JITTER_FACTOR	0.15	Randomizes each reconnect delay by up to ± this fraction, so that many Edges do not reconnect at the same moment. 0 disables it.
CLOUD_UPLINK_PACK_TIMEOUT_SEC	60	Seconds to wait for an uplink acknowledgement from the server before timing out.

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.

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.

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.

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 wait before retrying a batch that failed to deliver.
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	Look-back window, in milliseconds, subtracted from the start timestamp when Edge reads cloud events, so that events whose creation time and sequence number are out of order are not skipped.

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.

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	30	Retention period for stats data, in days.