Adding offline capabilities to your IoT Edge device

Azure IoT Edge makes it possible to send messages to your IoT Hub using the extremely flexible IoT Edge runtime and modules.

The runtime also supports temporary offline capabilities in case the IoT Hub is unreachable.

Starting with runtime 1.0.5, it is possible to set a custom location (folder) in which messages are stored before they are sent to the IoTHub.

Let’s see how this turns out.

The IoT Edge always supported the temporary storage of message using a simple setting in the Module Twin of the EdgeHub module.

Default this desired property, the setting storeAndForwardConfiguration-timeToLiveSecs is set to 7200 seconds. But you are able to update it to your needs. Eg. 172800 is enough for two days of storing messages.

The new custom location makes it possible to reserve a folder or even an additional disk on your Edge device with the sole purpose of storing messages.

Combined with the default behavior of flushing messages, you are in full control of the offline storage and you are able to prevent the disk from running out of space.

In the original documentation, the settings for Linux are explained:

You have to repeat these settings to both the EdgeAgent and the EdgeHub modules!

You have to create the local folder named /etc/iotedge/storage/!

You have to give it elevated rights so the modules can access it:

  • sudo chown $( whoami ):iotedge /etc/iotedge/storage/
  • sudo sudo chmod 775 /etc/iotedge/storage/

Note: These names are coming from the original documentation. For testing purposes, please deviate a bit. I change the container path to /iotedge/constorage/ so I was sure to see in the logging which path (the host path or the container path) is referred.

Note: Microsoft Learn has a training available about this topic.

These are the settings using Windows 10 IoT Enterprise 1809:

Create options:

“HostConfig”: {
“PortBindings”: {
“8883/tcp”: [
{“HostPort”: “8883”}
“443/tcp”: [
{“HostPort”: “443”}
“5671/tcp”: [
{“HostPort”: “5671”}
“Binds”: [

Environment variable:

storageFolder = C:\contemp

Note: the number of backslashes differs in the container temp folder.

In the Azure portal, Microsoft already provides some extra UI for the time-to-live value in the EdheHub module.

But the settings for the folder are a combination of the Bind in the create options and an environment variable.

The host operating exposes the folder C:\temp. This is mapped inside the container as c:\contemp. The edgeHub knows the location of the folder inside the container using the ‘storageFolder’ variable.

Once set, the IoT Edge picks up these settings and resets the EdgeHub module. The folder edgeHub is created in c:\temp:

The folder is filled with several files:


I tested the offline storage by disabling the Wifi connection for several times and checked the messages arriving at the IoT Hub and the size of the ‘edgeHub’ folder on disk.

The outcome was as expected, after a disconnect, the message stopped arriving at the IoT Hub. My test message contained a counter so I was able to see the message expected to follow the last message arrived at the IoT Hub once the wifi connection was repaired again.

Regarding the size of the folder, the behavior seems a bit unclear. I have seen the growth of the folder during offline state and I have seen how the folder shrunk once the device was online again. But the decrease in size was not always clear; at one time, the folder still kept growing although the connection was repaired.

You can check the size of the folder in Linux using the command line ‘du’ (disk usage) command.

Reboot during offline mode

In the past, there were some reports the offline storage is sensitive to rebooting during offline mode which could result in the loss of messages.

I have no experience with stability problems. I can just recommend to test this yourself and report your issues on GitHub.


Offline storage is a key feature of Azure IoT Edge.

Microsoft keeps improving the quality of the IoT Edge parts and offline storage is one of their focus areas.