Create and provision IoT Edge devices at scale on Linux using symmetric key

Article
05/20/2024

Applies to: IoT Edge 1.5 IoT Edge 1.4

Important

IoT Edge 1.5 LTS and IoT Edge 1.4 LTS are supported releases. IoT Edge 1.4 LTS is end of life on November 12, 2024. If you are on an earlier release, see Update IoT Edge.

This article provides end-to-end instructions for autoprovisioning one or more Linux IoT Edge devices using symmetric keys. You can automatically provision Azure IoT Edge devices with the Azure IoT Hub device provisioning service (DPS). If you're unfamiliar with the process of autoprovisioning, review the provisioning overview before continuing.

The tasks are as follows:

Create either an individual enrollment for a single device or a group enrollment for a set of devices.
Install the IoT Edge runtime and connect to the IoT Hub.

Tip

For a simplified experience, try the Azure IoT Edge configuration tool. This command-line tool, currently in public preview, installs IoT Edge on your device and provisions it using DPS and symmetric key attestation.

Symmetric key attestation is a simple approach to authenticating a device with a device provisioning service instance. This attestation method represents a "Hello world" experience for developers who are new to device provisioning, or do not have strict security requirements. Device attestation using a X.509 certificates is more secure, and should be used for more stringent security requirements.

Prerequisites

Cloud resources

An active IoT hub
An instance of the IoT Hub device provisioning service in Azure, linked to your IoT hub
- If you don't have a device provisioning service instance, you can follow the instructions in the Create a new IoT Hub device provisioning service and Link the IoT hub and your device provisioning service sections of the IoT Hub device provisioning service quickstart.
- After you have the device provisioning service running, copy the value of ID Scope from the overview page. You use this value when you configure the IoT Edge runtime.

Device requirements

A physical or virtual Linux device to be the IoT Edge device.

You will need to define a unique registration ID to identify each device. You can use the MAC address, serial number, or any unique information from the device. For example, you could use a combination of a MAC address and serial number forming the following string for a registration ID: sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6. Valid characters are lowercase alphanumeric and dash (-).

Create a DPS enrollment

Create an enrollment to provision one or more devices through DPS.

If you are looking to provision a single IoT Edge device, create an individual enrollment. If you need multiple devices provisioned, follow the steps for creating a DPS group enrollment.

When you create an enrollment in DPS, you have the opportunity to declare an initial device twin state. In the device twin, you can set tags to group devices by any metric you need in your solution, like region, environment, location, or device type. These tags are used to create automatic deployments.

For more information about enrollments in the device provisioning service, see How to manage device enrollments.

Individual enrollment
Group enrollment

Create a DPS individual enrollment

Tip

The steps in this article are for the Azure portal, but you can also create individual enrollments using the Azure CLI. For more information, see az iot dps enrollment. As part of the CLI command, use the edge-enabled flag to specify that the enrollment is for an IoT Edge device.

In the Azure portal, navigate to your instance of IoT Hub device provisioning service.
Under Settings, select Manage enrollments.
Select Add individual enrollment then complete the following steps to configure the enrollment:
1. For Mechanism, select Symmetric Key.
2. Provide a unique Registration ID for your device.
3. Optionally, provide an IoT Hub Device ID for your device. You can use device IDs to target an individual device for module deployment. If you don't provide a device ID, the registration ID is used.
4. Select True to declare that the enrollment is for an IoT Edge device.
5. Optionally, add a tag value to the Initial Device Twin State. You can use tags to target groups of devices for module deployment. For example:
```
{
   "tags": {
      "environment": "test"
   },
   "properties": {
      "desired": {}
   }
}
```
6. Select Save.
Copy the individual enrollment's Primary Key value to use when installing the IoT Edge runtime.

Now that an enrollment exists for this device, the IoT Edge runtime can automatically provision the device during installation.

Create a DPS group enrollment

Tip

The steps in this article are for the Azure portal, but you can also create group enrollments using the Azure CLI. For more information, see az iot dps enrollment-group. As part of the CLI command, use the edge-enabled flag to specify that the enrollment is for IoT Edge devices. For a group enrollment, all devices must be IoT Edge devices or none of them can be.

In the Azure portal, navigate to your instance of IoT Hub device provisioning service.
Under Settings, select Manage enrollments.
Select Add individual enrollment then complete the following steps to configure the enrollment:
1. Provide a Group name.
2. Select Symmetric Key as the attestation type.
3. Select True to declare that the enrollment is for an IoT Edge device. For a group enrollment, all devices must be IoT Edge devices or none of them can be.
4. Optionally, add a tag value to the Initial Device Twin State. You can use tags to target groups of devices for module deployment. For example:
```
{
   "tags": {
      "environment": "test"
   },
   "properties": {
      "desired": {}
   }
}
```
5. Select Save.
Copy your enrollment group's Primary Key value to use when creating device keys for use with a group enrollment.

Now that an enrollment group exists, the IoT Edge runtime can automatically provision devices during installation.

Derive a device key

Each device that is provisioned as part of a group enrollment needs a derived device key to perform symmetric key attestation with the enrollment during provisioning.

To generate a device key, use the key that you copied from your DPS enrollment group to compute an HMAC-SHA256 of the unique registration ID for the device and convert the result into Base64 format.

Important

Do not include your enrollment's primary or secondary key in your device code.

On Windows, you can use PowerShell to generate your derived device key as shown in the following example.

Replace the value of KEY with the Primary Key you noted earlier.

Replace the value of REG_ID with your device's registration ID.

$KEY='PASTE_YOUR_ENROLLMENT_KEY_HERE'
$REG_ID='PASTE_YOUR_REGISTRATION_ID_HERE'

$hmacsha256 = New-Object System.Security.Cryptography.HMACSHA256
$hmacsha256.key = [Convert]::FromBase64String($KEY)
$sig = $hmacsha256.ComputeHash([Text.Encoding]::ASCII.GetBytes($REG_ID))
$derivedkey = [Convert]::ToBase64String($sig)
echo "`n$derivedkey`n"

Below is a sample output of a derived device key:

Jsm0lyGpjaVYVP2g3FnmnmG9dI/9qU24wNoykUmermc=

Install IoT Edge

In this section, you prepare your Linux virtual machine or physical device for IoT Edge. Then, you install IoT Edge.

Run the following commands to add the package repository and then add the Azure package signing key to your list of trusted keys.

Important

On June 30, 2022 Raspberry Pi OS Stretch was retired from the Tier 1 OS support list. To avoid potential security vulnerabilities update your host OS to Bullseye.

For tier 2 supported platform operating systems, installation packages are made available at Azure IoT Edge releases. See the installation steps in Offline or specific version installation.

Installing can be done with a few commands. Open a terminal and run the following commands:

24.04:

wget https://packages.microsoft.com/config/ubuntu/24.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

22.04:

wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

20.04:

wget https://packages.microsoft.com/config/ubuntu/20.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

Installing with APT can be done with a few commands. Open a terminal and run the following commands:

12 - Bookworm (arm32v7):

curl https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb > ./packages-microsoft-prod.deb
sudo apt install ./packages-microsoft-prod.deb

11 - Bullseye (arm32v7):

curl https://packages.microsoft.com/config/debian/11/packages-microsoft-prod.deb > ./packages-microsoft-prod.deb
sudo apt install ./packages-microsoft-prod.deb

Tip

If you gave the "root" account a password during the OS install, you will not need 'sudo' and can run the above command by starting with 'apt'.

Installing can be done with a few commands. Open a terminal and run the following commands:

9.x (amd64):

  wget https://packages.microsoft.com/config/rhel/9.0/packages-microsoft-prod.rpm -O packages-microsoft-prod.rpm
  sudo yum localinstall packages-microsoft-prod.rpm
  rm packages-microsoft-prod.rpm

8.x (amd64):

  wget https://packages.microsoft.com/config/rhel/8/packages-microsoft-prod.rpm -O packages-microsoft-prod.rpm
  sudo yum localinstall packages-microsoft-prod.rpm
  rm packages-microsoft-prod.rpm

For more information about operating system versions, see Azure IoT Edge supported platforms.

Note

Azure IoT Edge software packages are subject to the license terms located in each package (usr/share/doc/{package-name} or the LICENSE directory). Read the license terms prior to using a package. Your installation and use of a package constitutes your acceptance of these terms. If you don't agree with the license terms, don't use that package.

Install a container engine

Azure IoT Edge relies on an OCI-compatible container runtime. For production scenarios, we recommend that you use the Moby engine. The Moby engine is the container engine officially supported with IoT Edge. Docker CE/EE container images are compatible with the Moby runtime. If you are using Ubuntu Core snaps, the Docker snap is serviced by Canonical and supported for production scenarios.

Install the Moby engine.

sudo apt-get update; \
  sudo apt-get install moby-engine

Install the Moby engine.

sudo apt-get update; \
  sudo apt-get install moby-engine

Install the Moby engine and CLI.

sudo yum install moby-engine moby-cli

Tip

If you get errors when you install the Moby container engine, verify your Linux kernel for Moby compatibility. Some embedded device manufacturers ship device images that contain custom Linux kernels without the features required for container engine compatibility. Run the following command, which uses the check-config script provided by Moby, to check your kernel configuration:

curl -ssl https://raw.githubusercontent.com/moby/moby/master/contrib/check-config.sh -o check-config.sh
chmod +x check-config.sh
./check-config.sh

In the output of the script, check that all items under Generally Necessary and Network Drivers are enabled. If you're missing features, enable them by rebuilding your kernel from source and selecting the associated modules for inclusion in the appropriate kernel .config. Similarly, if you're using a kernel configuration generator like defconfig or menuconfig, find and enable the respective features and rebuild your kernel accordingly. After you've deployed your newly modified kernel, run the check-config script again to verify that all the required features were successfully enabled.

IoT Edge has dependencies on Docker and IoT Identity Service. Install the dependencies using the following commands:

sudo snap install docker
sudo snap install azure-iot-identity

The Docker snap is serviced by Canonical and supported for production scenarios.

By default, the container engine doesn't set container log size limits. Over time, this can lead to the device filling up with logs and running out of disk space. However, you can configure your log to show locally, though it's optional. To learn more about logging configuration, see Production Deployment Checklist.

The following steps show you how to configure your container to use local logging driver as the logging mechanism.

Ubuntu / Debian / RHEL
Ubuntu Core snaps

Create or edit the existing Docker daemon's config file
```
sudo nano /etc/docker/daemon.json
```
Set the default logging driver to the local logging driver as shown in the example.
```
   {
      "log-driver": "local"
   }
```
Restart the container engine for the changes to take effect.
```
sudo systemctl restart docker
```

Install the IoT Edge runtime

The IoT Edge service provides and maintains security standards on the IoT Edge device. The service starts on every boot and bootstraps the device by starting the rest of the IoT Edge runtime.

Note

Beginning with version 1.2, the IoT identity service handles identity provisioning and management for IoT Edge and for other device components that need to communicate with IoT Hub.

The steps in this section represent the typical process to install the latest IoT Edge version on a device that has internet connection. If you need to install a specific version, like a pre-release version, or need to install while offline, follow the Offline or specific version installation steps later in this article.

Tip

If you already have an IoT Edge device running an older version and want to upgrade to the latest release, use the steps in Update the IoT Edge security daemon and runtime. Later versions are sufficiently different from previous versions of IoT Edge that specific steps are necessary to upgrade.

Install the latest version of IoT Edge and the IoT identity service package (if you're not already up-to-date):

22.04:

sudo apt-get update; \
   sudo apt-get install aziot-edge

20.04:

sudo apt-get update; \
   sudo apt-get install aziot-edge defender-iot-micro-agent-edge

The optional defender-iot-micro-agent-edge package includes the Microsoft Defender for IoT security micro-agent that provides endpoint visibility into security posture management, vulnerabilities, threat detection, fleet management and more to help you secure your IoT Edge devices. It's recommended to install the micro agent with the Edge agent to enable security monitoring and hardening of your Edge devices. To learn more about Microsoft Defender for IoT, see What is Microsoft Defender for IoT for device builders.

Install the latest version of IoT Edge and the IoT identity service package (if you're not already up-to-date):

sudo apt-get update; \
  sudo apt-get install aziot-edge defender-iot-micro-agent-edge

The optional defender-iot-micro-agent-edge package includes the Microsoft Defender for IoT security micro-agent that provides endpoint visibility into security posture management, vulnerabilities, threat detection, fleet management and more to help you secure your IoT Edge devices. It's recommended to install the micro agent with the Edge agent to enable security monitoring and hardening of your Edge devices. To learn more about Microsoft Defender for IoT, see What is Microsoft Defender for IoT for device builders.

Install the latest version of IoT Edge and the IoT identity service package (if you're not already up-to-date):

sudo yum install aziot-edge

Install IoT Edge from the snap store:

sudo snap install azure-iot-edge

Connect snaps

By default, snaps are dependency-free, untrusted, and strictly confined. Hence, snaps must be connected to other snaps and system resources after installation. Use the following commands to connect the IoT Identity Service and IoT Edge snaps to each other and to system resources. To get started, snaps need to be manually connected. For production deployments, they can be configured to automatically connect to reduce the provisioning workload.

#------------------------
# IoT Identity Service
#------------------------

# Connect the Identity Service snap to the logging system
# and grant permission to query system info

sudo snap connect azure-iot-identity:log-observe
sudo snap connect azure-iot-identity:mount-observe
sudo snap connect azure-iot-identity:system-observe
sudo snap connect azure-iot-identity:hostname-control

# If using a TPM, enable TPM access

sudo snap connect azure-iot-identity:tpm

#------------
# IoT Edge
#------------

# Connect to your /home directory to enable writing support bundles

sudo snap connect azure-iot-edge:home

# Connect to logging and grant permission to query system info

sudo snap connect azure-iot-edge:log-observe
sudo snap connect azure-iot-edge:mount-observe
sudo snap connect azure-iot-edge:system-observe
sudo snap connect azure-iot-edge:hostname-control
# Allow IoT Edge to connect to the /var/run/iotedge folder and use sockets

sudo snap connect azure-iot-edge:run-iotedge

# Connect IoT Edge to Docker

sudo snap connect azure-iot-edge:docker docker:docker-daemon

Provision the device with its cloud identity

Once the runtime is installed on your device, configure the device with the information it uses to connect to the device provisioning service and IoT Hub.

Have the following information ready:

The DPS ID Scope value
The device Registration ID you created
Either the Primary Key from an individual enrollment, or a derived key for devices using a group enrollment.

Create a configuration file for your device based on a template file that is provided as part of the IoT Edge installation.

Ubuntu / Debian / RHEL
Ubuntu Core snaps

sudo cp /etc/aziot/config.toml.edge.template /etc/aziot/config.toml

Open the configuration file on the IoT Edge device.

sudo nano /etc/aziot/config.toml

If using a snap installation of IoT Edge, the template file is located at /snap/azure-iot-edge/current/etc/aziot/config.toml.edge.template. Create a copy of the template file in your home directory and name it config.toml. For example:

cp /snap/azure-iot-edge/current/etc/aziot/config.toml.edge.template ~/config.toml

Open the configuration file in your home directory on the IoT Edge device.

nano ~/config.toml

Find the Provisioning section of the file. Uncomment the lines for DPS provisioning with symmetric key, and make sure any other provisioning lines are commented out.

# DPS provisioning with symmetric key
[provisioning]
source = "dps"
global_endpoint = "https://global.azure-devices-provisioning.net"
id_scope = "PASTE_YOUR_SCOPE_ID_HERE"

# Uncomment to send a custom payload during DPS registration
# payload = { uri = "PATH_TO_JSON_FILE" }

[provisioning.attestation]
method = "symmetric_key"
registration_id = "PASTE_YOUR_REGISTRATION_ID_HERE"

symmetric_key = { value = "PASTE_YOUR_PRIMARY_KEY_OR_DERIVED_KEY_HERE" }

# auto_reprovisioning_mode = Dynamic

Update the values of id_scope, registration_id, and symmetric_key with your DPS and device information.

The symmetric key parameter can accept a value of an inline key, a file URI, or a PKCS#11 URI. Uncomment just one symmetric key line, based on which format you're using. When using an inline key, use a base64-encoded key like the example. When using a file URI, your file should contain the raw bytes of the key.

If you use any PKCS#11 URIs, find the PKCS#11 section in the config file and provide information about your PKCS#11 configuration.

For more information about provisioning configuration settings, see Configure IoT Edge device settings.
Optionally, find the auto reprovisioning mode section of the file. Use the auto_reprovisioning_mode parameter to configure your device's reprovisioning behavior. Dynamic - Reprovision when the device detects that it may have been moved from one IoT Hub to another. This is the default. AlwaysOnStartup - Reprovision when the device is rebooted or a crash causes the daemons to restart. OnErrorOnly - Never trigger device reprovisioning automatically. Each mode has an implicit device reprovisioning fallback if the device is unable to connect to IoT Hub during identity provisioning due to connectivity errors. For more information, see IoT Hub device reprovisioning concepts.
Optionally, uncomment the payload parameter to specify the path to a local JSON file. The contents of the file is sent to DPS as additional data when the device registers. This is useful for custom allocation. For example, if you want to allocate your devices based on an IoT Plug and Play model ID without human intervention.
Save and close the file.
Apply the configuration changes that you made on the device.
- Ubuntu / Debian / RHEL
- Ubuntu Core snaps
```
sudo iotedge config apply
```
```
sudo snap set azure-iot-edge raw-config="$(cat ~/config.toml)"
```

Verify successful installation

If the runtime started successfully, you can go into your IoT Hub and start deploying IoT Edge modules to your device.

Individual enrollment
Group enrollment

You can verify that the individual enrollment that you created in device provisioning service was used. Navigate to your device provisioning service instance in the Azure portal. Open the enrollment details for the individual enrollment that you created. Notice that the status of the enrollment is assigned and the device ID is listed.

Use the following commands on your device to verify that the IoT Edge installed and started successfully.

Check the status of the IoT Edge service.

sudo iotedge system status

Examine service logs.

sudo iotedge system logs

List running modules.

sudo iotedge list

Next steps

The device provisioning service enrollment process lets you set the device ID and device twin tags at the same time as you provision the new device. You can use those values to target individual devices or groups of devices using automatic device management. Learn how to Deploy and monitor IoT Edge modules at scale using the Azure portal or using Azure CLI.

Create and provision IoT Edge devices at scale on Linux using symmetric key

Prerequisites

Cloud resources

Device requirements

Create a DPS enrollment

Create a DPS individual enrollment

Install IoT Edge

Install a container engine

Install the IoT Edge runtime

Provision the device with its cloud identity

Verify successful installation

Next steps

Additional resources