Create and provision an IoT Edge device on Linux using symmetric keys

A free or standard IoT hub in your Azure subscription.

• A free or standard IoT hub in your Azure subscription
• Visual Studio Code
• Azure IoT Edge extension. The Azure IoT Edge tools for Visual Studio Code extension is in maintenance mode.
• Azure IoT Hub extension

• A free or standard IoT hub in your Azure subscription

• Azure CLI in your environment

  At a minimum, your Azure CLI version must be 2.0.70 or newer. Use az --version to validate. This version supports az extension commands and introduces the Knack command framework.

In your IoT hub in the Azure portal, IoT Edge devices are created and managed separately from IoT devices that are not edge enabled.

1. Sign in to the Azure portal and navigate to your IoT hub.

2. In the left pane, select Devices from the menu, then select Add Device.

3. On the Create a device page, provide the following information:

   • Create a descriptive Device ID, for example my-edge-device-1 (all lowercase). Copy this Device ID, as you'll use it later.
   • Check the IoT Edge Device checkbox.
   • Select Symmetric key as the authentication type.
   • Use the default settings to auto-generate authentication keys, which connect the new device to your hub.

4. Select Save.

You should see your new device listed in your IoT hub.

Sign in to Azure

You can use the Azure IoT extensions for Visual Studio Code to perform operations with your IoT hub. Make sure you have installed the Azure IoT extension prerequisites.

Once Azure IoT Edge and Azure IoT Hub extensions are installed, you notice an Azure icon gets added to the left icon menu. You can sign in to your Azure account through Visual Studio Code by selecting the Azure icon and then select Sign in to Azure.

Register a new device with Visual Studio Code

Registering a new device is akin to creating an IoT Edge device in the Azure portal. This virtual device is one of the twins, whereas the real world device is the other twin. Visual Studio Code can set this up for you through the following steps.

1. In the Visual Studio Code Explorer menu, expand the Azure IoT Hub section.
2. Select on the ... in the Azure IoT Hub section header. If you don't see the ellipsis, select or hover over the header.
3. Select Create IoT Edge Device.
4. In the text box that opens, give your device an ID, for example my-edge-device-1 (all lowercase), then press enter.

In the output console of Visual Studio Code, you see the result of the command: a JSON printout. The device information includes the deviceId that you provided and generates a connectionString that you can use to connect your physical device to your IoT hub. The output console also shows your keys and other device identifying information.

You can now see your device listed under the Azure IoT Hub > Devices section of the Explorer menu.

Use the az iot hub device-identity create command to create a new device identity in your IoT hub. Replace device_id_here with your own new and unique device ID, for example my-edge-device-1 (all lowercase). Replace hub_name_here with your existing IoT hub.

This command includes three parameters:

• --device-id or -d: Provide a descriptive name that's unique within your IoT hub.

• --hub-name or -n: Provide the name of your IoT hub.

• --edge-enabled or --ee: Declare that the device is an IoT Edge device.

  az iot hub device-identity create --device-id device_id_here --hub-name hub_name_here --edge-enabled
  

If your CLI says The command requires the extension azure-iot. Do you want to install it now?, then type Y and press Enter to initiate the download to create your device.

The edge-enabled devices that connect to your IoT hub are listed on the Devices page of your IoT hub. If you have multiple devices, you can filter the list by selecting the type Iot Edge Devices, then select Apply.

When you're ready to set up your device, you need the connection string that links your physical device with its identity in the IoT hub. Devices that authenticate with symmetric keys have their connection strings available to copy in the portal. To find your connection string in the portal:

1. From the Devices page, select the IoT Edge device ID from the list.
2. Copy the value of either Primary Connection String or Secondary Connection String. Either key works.

All the devices that connect to your IoT hub are listed in the Azure IoT Hub section of the Visual Studio Code Explorer. IoT Edge devices are distinguishable from non-Edge devices because they have a different icon and you see the $edgeAgent and $edgeHub modules are deployed to each IoT Edge device.

When you're ready to set up your device, you need the connection string that links your physical device with its identity in the IoT hub. Here's how to get your connection string from Visual Studio Code.

1. Right-click on the ID (name) of your device in the Azure IoT Hub section.

2. Select Copy Device Connection String.

   The connection string is copied to your clipboard.

You can also select Get Device Info from the right-click menu to see all the device info, including the connection string, in the output window.

To see all devices in your IoT hub, use the az iot hub device-identity list command. Replace hub_name_here with your own IoT hub name.

az iot hub device-identity list --hub-name hub_name_here

Any device that is registered as an IoT Edge device has the property capabilities.iotEdge set to true. You see a lot of other metadata as JSON output as well, including your device IDs.

When you're ready to set up your device, you need its connection string that links your physical device with its identity in the IoT hub. Use the following az iot hub device-identity connection-string show command to return the connection string for a single device. Replace [device_id] and [hub_name] with your own values. The value for the device-identity parameter is case-sensitive.

az iot hub device-identity connection-string show --device-id [device_id] --hub-name [hub_name]

You should see JSON output in the console, similar to the following:

{
  "connectionString": "HostName=[hub_name].azure-devices.net;DeviceId=[device_id];SharedAccessKey=[device_key]"
}

When copying the connection string to use on a device, don't include the quotation marks around the connection string.

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

• 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:

• 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
  

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
  

You install IoT Edge runtime from the snap store in a later step. Continue to the next section.

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

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

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.

1. Create or edit the existing Docker daemon's config file

   sudo nano /etc/docker/daemon.json
   

2. Set the default logging driver to the local logging driver as shown in the example.

      {
         "log-driver": "local"
      }
   

3. Restart the container engine for the changes to take effect.

   sudo systemctl restart docker
   

Currently, the local logging driver setting is not supported for the Docker snap.

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

You can configure your IoT Edge device with symmetric key authentication using the following command:

sudo iotedge config mp --connection-string 'PASTE_DEVICE_CONNECTION_STRING_HERE'

This iotedge config mp command creates a configuration file on the device and enters your connection string in the configuration file.

1. Apply the configuration changes.

   sudo iotedge config apply
   

2. To view the configuration file, you can open it:

   sudo nano /etc/aziot/config.toml
   

1. Create a config.toml file in your home directory and configure your IoT Edge device with a symmetric key authentication for the snap.

   sudo nano ~/config.toml
   

2. You can manually provision with a connection string using the following provisioning settings:

   [provisioning]
   source = "manual"
   connection_string = "REPLACE_WITH_DEVICE_CONNECTION_STRING"
   

   For more information about provisioning configuration settings, see Configure IoT Edge device settings.

3. Set the configuration for IoT Edge and the Identity Service using the following command:

   sudo snap set azure-iot-edge raw-config="$(cat ~/config.toml)"
   

sudo apt-get autoremove --purge aziot-edge

Leave out the --purge flag if you plan to reinstall IoT Edge and use the same configuration information in the future. The --purge flag deletes all the files associated with IoT Edge, including your configuration files.

sudo yum remove aziot-edge

Remove the IoT Edge runtime:

sudo snap remove azure-iot-edge

Remove Azure Identity Service:

sudo snap remove azure-iot-identity

sudo apt-get autoremove --purge moby-engine

sudo yum remove moby-cli
sudo yum remove moby-engine

sudo snap remove docker