Edge Agent and Edge Hub Environment Variables

Use the following environment variables to configure the Edge Agent and Edge Hub services. These variables are used in the deployment manifest to configure the Edge Agent and Edge Hub modules.

You can set Edge Agent and Edge Hub environment variables in the Azure portal. In the details page for your IoT Edge device, select Set Modules. In the IoT Edge Modules section, select Runtime Settings. Choose the Edge Agent or Edge Hub tab for the module's environment variable you want to set. Add the variable detail in the Environment Variables section. Apply and create the deployment for the device.

Edge Agent

Variable	Description	Value Range	Default Value
BackupConfigFilePath	Path to put the backup deployment config file	string
CloseCloudConnectionOnIdleTimeout	Whether the upstream connection should be closed when CloudConnectionIdleTimeoutSecs is reached	bool	false
CloudConnectionIdleTimeoutSecs	If there are no IoT operations, time span to wait before the upstream connection is considered idle	int32	300
ConfigRefreshFrequencySecs	Interval at which the Edge Agent config is refreshed from upstream	int32	3600
ConfigSource	twin / local, specifies where the deployment config should be read from	twin, local	twin
CoolOffTimeUnitInSeconds	Time span to wait between restart attempts on a module	0-300	10
DisableDeviceAnalyticsMetadata	Whether to disable sending basic metadata about the device to Microsoft.	bool	false
EnableK8sServiceCallTracing	Whether to enable logging for K8s requests that the Agent makes	bool	false
EnableOrphanedIdentityCleanup	Whether to enable removal of any orphaned identities NOTE: There is an issue with the managedBy tag for module identities that WILL cause this logic to remove Host-Level modules (i.e. managed by something other than IotEdge)	bool	false
EnableSdkDebugLogs	If set, emits SDK client events to logs. Note that this method will substantially slow down execution.	bool	false
Https_Proxy	Address of the proxy to use for outbound HTTPS requests	string
IntensiveCareTimeInMinutes	Time span for a module to be running before considered completely healthy (restart time / count cleared)	int32
K8sNamespace	K8s namespace to use for deploying modules	string
LocalConfigPath	Path to local .json file containing Agent config	string	.\config.json
ManagementApiTimeoutSecs	Time span to wait before the connection to managament api times out	int32	300
MaxRestartCount	Max number of restarts allowed before a module is considered to have failed	int32
MetricsEnabled	Whether to enable metrics listener	bool	true
MetricsHistogramMaxAge	Time interval for the metrics histogram	TimeSpan string	01:00:00 (1 hour)
MetricScrapeInterval	Interval at which diagnostic metrics are sampled	TimeSpan string	01:00:00 (1 hour)
MetricUploadInterval	Interval at which diagnostic metrics are uploaded	TimeSpan string	1.00:00:00 (1 day)
ModuleUpdateMode	Behavior for module updates. Either wait for all images to be downloaded, or make a best effort.	NonBlocking, WaitForAllPulls	NonBlocking
PerformanceMetricsUpdateFrequency	Interval to sample system performance metrics from host. These include CPU, RAM and Disk Space measurements.	TimeSpan string	00:05:00 (5 minutes)
Mode	specifies the mode for module deployment	iotedged, docker, kubernetes	iotedged
PersistentVolumeClaimDefaultSizeInMb	Size of the PersistedVolumeClaim, must be used with StorageClassName	int32
RequestTimeoutSecs	Timeout for handling ping and GetTaskStatus direct methods	int32	600
RocksDB_MaxOpenFiles	Max number of files to be concurrently opened by RocksDB	int32
RocksDB_MaxTotalWalSize	Max size to be used by RocksDB's write-ahead-log	ulong
RocksDB_MaxManifestFileSize	Max size of a RocksDB MANIFEST file before it's rolled over	ulong
RunAsNonRoot	If set, runs at user = 1000 instead of root	bool	false
RuntimeLogLevel	Runtime diagnostic logging level	fatal, error, warning, info, debug, verbose	info
SendRuntimeQualityTelemetry	Whether to enable sending runtime diagnostics metric	bool	true
Storage_LogLevel	RocksDB diagnostic log level	NONE, FATAL, HEADER, ERROR, WARN, INFO, DEBUG	NONE
StorageClassName	StorageClassName to be used when creating a PersistedVolumeClaim	string
StorageFolder	Path to place the Edge Agent database directory	string	TempPath of the current OS
UpstreamProtocol	Protocol used to for upstream connections	Amqp, AmqpWs, Mqtt, MqttWs	Amqp w/ fallback to AmqpWs
UseMountSourceForVolumeName	If set, the k8s conversion will use the volume mount source as persistent volume name	bool	false
UseOfflineCheck	If set, activate additional logic that can help Edge Agent start without network connectivity	bool	false
UsePersistentStorage	Whether to save deployment config and module states to disk	bool	true
UseServerHeartbeat	Sets the client-side heartbeat interval to 60sec for the Agent's upstream AMQP connection	bool	true

Edge Hub

Variable	Description	Values	Default
AmqpSettings__Enabled	Whether the AMQP protocol head should be enabled	bool	true
AmqpSettings__Port	The port for the AMQP protocol head to listen on	int32	5671
AmqpSettings__DelayedBatchingEnabled	Enable to wait for subsequent packets to batch them, similar to Nagle for TCP	bool	false
AuthenticationMode	Determines who performs authentication	Scope, Cloud, CloudAndScope (Cloud AuthenticationMode not supported in production)	Scope
BackupFolder	Path to place the backup Edge Hub database directory	string	TempPath of the current OS
CacheTokens	Whether client authentication tokens are saved to disk	bool	false
CheckEntireQueueOnCleanup	Periodically check all pending messages for TTL expiry, incurs more I/O but saves more storage	bool	false
ClientCertAuthEnabled	Allows dev certificates to be used during SSL handshake with upstream and bypass cert validation	bool	false
CloseCloudConnectionOnDeviceDisconnect	If a leaf device disconnections, immediately closes the corresponding upstream connection	bool	true
CloseCloudConnectionOnIdleTimeout	Whether the upstream connection should be closed when CloudConnectionIdleTimeoutSecs is reached	bool	true
CloudConnectionHangingTimeoutSecs	Time span to wait before the upstream IOT operation is set to timeout in case CloudOperationTimeoutSecs is not honored	int32	50
CloudConnectionIdleTimeoutSecs	If there are no IoT operations, time span to wait before the upstream connection is considered idle	int32	3600
CloudOperationTimeoutSecs	Time out for any upstream IoT operation	int32	20
ConfigRefreshFrequencySecs	Interval at which the Edge Hub config is refreshed from upstream	int32	3600
ConfigSource	Uses config from either Edge Hub twin, or a local config source	twin, local	twin
ConnectivityCheckFrequencySecs	Interval at which Edge Hub will ping upstream to ensure connectivity is still present	int32	300
DeviceScopeCacheRefreshRateSecs	Interval at which leaf and module identities are refreshed from upstream	int32	3600
EnableRoutingLogging	Whether message routing logs should be enabled	bool	false
EnableSdkDebugLogs	If set, emits SDK client events to logs. Note that this method will substantially slow down execution.	bool	false
EncryptTwinStore	Whether to encrypt the twin data before persisting to disk	bool	true
Https_Proxy	Address of the proxy to use for outbound HTTPS requests	string
HttpSettings__Enabled	Whether the HTTP server should be enabled	bool	true
HttpSettings__Port	The port for the HTTP protocol head to listen on	int32	443
ApiProxyModuleId	This is the ApiProxy module name that is authorized to forward the client certificate for client CA certificate authentication	string	IoTEdgeAPIProxy
IotHubConnectionPoolSize	Pool size for upstream AMQP connection	int32
MaxConnectedClients	Maximum number of downstream clients allowed to connect	int32	101 (100 clients + 1 Edge Hub)
MaxUpstreamBatchSize	Max number of messages to concurrently send upstream	int32	10
MessageAckTimeoutSecs	Time span to wait for sending a message downstream to a leaf device	int32	30
MessageCleanupIntervalSecs	This setting defines the time interval for a task that cleans up messages in Edge Hub's store. Note that messages are only removed from the store when this task runs. If you use a Time To Live that is shorter than the default cleanup interval, please adjust the cleanup interval accordingly to ensure timely message removal.	int32	1800
Metrics__Listener__Host	Hostname of the metrics listener, used to construct the metrics listener URL	string	*
Metrics__Listener__MetricsEnabled	Whether to enable metrics listener	bool	true
Metrics__Listener__MetricsHistogramMaxAge	Time interval for the metrics histogram	TimeSpan string	00:01:00 (1 hour)
Metrics__Listener__Port	Port of the metrics listener, used to construct the metrics listener URL	int32	9600
Metrics__Listener__Suffix	Appended to the metrics listener URL	string	metrics
MinTwinSyncPeriodSecs	Maximum frequency for pull any device/module twin	int32	120
ModuleRequestThrottleTimeout	Time in seconds for how long internal module request timeout should be, -1 indicates infinite timeout (i.e., the request might never return, use with caution), numbers less than -1 are invalid	int 32	240s
MqttSettings__Enabled	Whether the MQTT broker should be enabled	bool	true
MqttSettings__UsePooledBuffers	Whether MQTT protocol head should use pooled buffers	bool	false
OptimizeForPerformance	Increase RocksDB file I/O usage to speed up message storage	bool	true
ReportedPropertiesSyncFrequencySecs	Maximum frequency for pushing reported properties upstream	int32	5
RocksDB_MaxOpenFiles	Max number of files to be concurrently opened by RocksDB	int32
RocksDB_MaxTotalWalSize	Max size to be used by RocksDB's write-ahead-log	ulong
RocksDB_MaxManifestFileSize	Max size of a RocksDB MANIFEST file before it's rolled over	ulong
RuntimeLogLevel	Runtime diagnostic logging level	fatal, error, warning, info, debug, verbose	info
ShutdownWaitPeriod	Seconds to wait on shutdown before hard termination	int32	60
SslProtocols	TLS protocol(s) to be supported	any of: tls1.2, tls1.3 (comma separated)	tls1.2,tls1.3
Storage_LogLevel	RocksDB diagnostic log level	NONE, FATAL, HEADER, ERROR, WARN, INFO, DEBUG	NONE
StorageFolder	Path to place the Edge Hub databases directory	string	TempPath of the current OS
UpstreamFanOutFactor	Max number of message groups to concurrently process for sending, grouped by sender	int32	10
UpstreamProtocol	Protocol used to for upstream connections	Amqp, AmqpWs, Mqtt, MqttWs	Amqp w/ fallback to AmqpWs
UseServerHeartbeat	Sets the client-side heartbeat interval to 60sec for upstream AMQP connections	bool	true
UsePersistentStorage	If set, will enable directly persisting messages / twins into the local database before forwarding/processing	bool	true
EnableNonPersistentStorageBackup	If messages / twins are not directly persisted, this will backup twins and any unprocessed messages on shutdown so Edge can resume on next startup	bool	false
ServerCertificateRenewAfterInMs	Maximum time duration after which the Edge Hub server certificate will be renewed, irrespective of certificate expiry time	int32	int32.max
MaxCheckCertExpiryInMs	Maximum time duration after which Edge Hub server certificate expiry should be checked, irrespective of certificate expiry time	int32	n/a

Cloud AuthenticationMode not supported in production

Cloud authentication is not supported in production because of several known limitations:

• Does not work for clients with x509 certitificate authentication (thumbprint or CA)
• Does not work in offline mode
• When a device sends telemetry and disconnects before Edge Hub, there is no way for Edge Hub to drain those messages to IoT Hub
• Token refresh or validation requires dropping connection to the device and may cause stability issues.