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.
| 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 EdgeAgent 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 EdgeAgent 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 |
| 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 |
| 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 EdgeHub 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 EdgeHub config is refreshed from upstream | int32 | 3600 |
| ConfigSource | Uses config from either EdgeHub twin, or a local config source | twin, local | twin |
| ConnectivityCheckFrequencySecs | Interval at which EdgeHub 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 EdgeHub) |
| 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 EdgeHub'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 |
| 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 | tls1.2, tls1.3, or any combination thereof separated by comma | tls1.2,tls1.3 |
| Storage_LogLevel | RocksDB diagnostic log level | NONE, FATAL, HEADER, ERROR, WARN, INFO, DEBUG | NONE |
| StorageFolder | Path to place the EdgeHub 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 EdgeHub server certificate will be renewed, irrespective of certificate expiry time | int32 | int32.max |
| MaxCheckCertExpiryInMs | Maximum time duration after which EdgeHub server certificate expiry should be checked, irrespective of certificate expiry time | int32 | n/a |
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 EdgeHub, there is no way for EdgeHub to drain those messages to IoT Hub
- Token refresh or validation requires dropping connection to the device and may cause stability issues.