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

Applies to: IoT Edge 1.4

Important

IoT Edge 1.4 is the supported release. If you are on an earlier release, see Update IoT Edge.

This article provides end-to-end instructions for registering and provisioning an IoT Edge for Linux on Windows device.

Every device that connects to an IoT hub has a device ID that's used to track cloud-to-device or device-to-cloud communications. You configure a device with its connection information, which includes the IoT hub hostname, the device ID, and the information the device uses to authenticate to IoT Hub.

The steps in this article walk through a process called manual provisioning, where you connect a single device to its IoT hub. For manual provisioning, you have two options for authenticating IoT Edge devices:

• Symmetric keys: When you create a new device identity in IoT Hub, the service creates two keys. You place one of the keys on the device, and it presents the key to IoT Hub when authenticating.

  This authentication method is faster to get started, but not as secure.

• X.509 self-signed: You create two X.509 identity certificates and place them on the device. When you create a new device identity in IoT Hub, you provide thumbprints from both certificates. When the device authenticates to IoT Hub, it presents one certificate and IoT Hub verifies that the certificate matches its thumbprint.

  This authentication method is more secure and recommended for production scenarios.

This article covers using symmetric keys as your authentication method. If you want to use X.509 certificates, see Create and provision an IoT Edge for Linux on Windows device using X.509 certificates.

Note

If you have many devices to set up and don't want to manually provision each one, use one of the following articles to learn how IoT Edge works with the IoT Hub device provisioning service:

• Create and provision IoT Edge devices at scale using X.509 certificates
• Create and provision IoT Edge devices at scale with a TPM
• Create and provision IoT Edge devices at scale using symmetric keys

Prerequisites

This article covers registering your IoT Edge device and installing IoT Edge for Linux on Windows. These tasks have different prerequisites and utilities used to accomplish them. Make sure you have all the prerequisites covered before proceeding.

Device management tools

You can use the Azure portal, Visual Studio Code, or Azure CLI for the steps to register your device. Each utility has its own prerequisites or may need to be installed:

Portal

A free or standard IoT hub in your Azure subscription.

Visual Studio Code

• 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

Azure CLI

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

Device requirements

A Windows device with the following minimum requirements:

• System Requirements

  • Windows 10¹/11 (Pro, Enterprise, IoT Enterprise)
  • Windows Server 2019¹/2022
    _{¹ Windows 10 and Windows Server 2019 minimum build 17763 with all current cumulative updates installed.}

• Hardware requirements

  • Minimum Free Memory: 1 GB
  • Minimum Free Disk Space: 10 GB

• Virtualization support

  • On Windows 10, enable Hyper-V. For more information, see Install Hyper-V on Windows 10.
  • On Windows Server, install the Hyper-V role and create a default network switch. For more information, see Nested virtualization for Azure IoT Edge for Linux on Windows.
  • On a virtual machine, configure nested virtualization. For more information, see nested virtualization.

• Networking support

  • Windows Server does not come with a default switch. Before you can deploy EFLOW to a Windows Server device, you need to create a virtual switch. For more information, see Create virtual switch for Linux on Windows.
  • Windows Desktop versions come with a default switch that can be used for EFLOW installation. If needed, you can create your own custom virtual switch.

Tip

If you want to use GPU-accelerated Linux modules in your Azure IoT Edge for Linux on Windows deployment, there are several configuration options to consider.

You will need to install the correct drivers depending on your GPU architecture, and you may need access to a Windows Insider Program build. To determine your configuration needs and satisfy these prerequisites, see GPU acceleration for Azure IoT Edge for Linux on Windows.

Make sure you take the time to satisfy the prerequisites for GPU acceleration now. You will need to restart the installation process if you decide you want GPU acceleration during installation.

Developer tools

Prepare your target device for the installation of Azure IoT Edge for Linux on Windows and the deployment of the Linux virtual machine:

1. Set the execution policy on the target device to AllSigned. You can check the current execution policy in an elevated PowerShell prompt using the following command:

   Get-ExecutionPolicy -List
   

   If the execution policy of local machine is not AllSigned, you can set the execution policy using:

   Set-ExecutionPolicy -ExecutionPolicy AllSigned -Force
   

For more information on the Azure IoT Edge for Linux on Windows PowerShell module, see the PowerShell functions reference.

Register your device

You can use the Azure portal, Visual Studio Code, or Azure CLI to register your device, depending on your preference.

Portal

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.

Visual Studio Code

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. Click on the ... in the Azure IoT Hub section header. If you don't see the ellipsis, click on 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.

Note

If your device is not listed, you may need to choose your IoT Hub from the link Select IoT Hub provided under Azure IoT Hub and then follow the prompts. The prompts will ask you to choose your subscription first and then your IoT Hub. This process lets Visual Studio Code know about your IoT Hub (and all devices in it). Refresh Visual Studio Code and your device should show.

Azure CLI

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.

Now that you have a device registered in IoT Hub, you can retrieve provisioning information used to complete the installation and provisioning of the IoT Edge runtime in the next step.

View registered devices and retrieve provisioning information

Devices that use symmetric key authentication need their connection strings to complete installation and provisioning of the IoT Edge runtime. The connection string gets generated for your IoT Edge device when you create the device. For Visual Studio Code and Azure CLI, the connection string is in the JSON output. If you use the Azure portal to create your device, you can find the connection string from the device itself. When you select your device in your IoT hub, it's listed as Primary connection string on the device page.

Portal

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 will work.

Visual Studio Code

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.

Azure CLI

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 will have 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=my-iot-hub.azure-devices.net;DeviceId=my-edge-device-1;SharedAccessKey=saQ52bt6BBUlRfusqWuxPMAx4ysQwWEb5+1eidwzHPY="
}

Tip

The connection-string show command was introduced in version 0.9.8 of the Azure IoT extension, replacing the deprecated show-connection-string command. If you get an error running this command, make sure your extension version is updated to 0.9.8 or later. For more information and the latest updates, see Microsoft Azure IoT extension for Azure CLI.

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

Install IoT Edge

Deploy Azure IoT Edge for Linux on Windows on your target device.

Note

The following PowerShell process outlines how to deploy IoT Edge for Linux on Windows onto the local device. To deploy to a remote target device using PowerShell, you can use Remote PowerShell to establish a connection to a remote device and run these commands remotely on that device.

1. In an elevated PowerShell session, run either of the following commands depending on your target device architecture to download IoT Edge for Linux on Windows.

   • X64/AMD64

     $msiPath = $([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))
     $ProgressPreference = 'SilentlyContinue'
     Invoke-WebRequest "https://aka.ms/AzEFLOWMSI_1_4_LTS_X64" -OutFile $msiPath
     

   • ARM64

     $msiPath = $([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))
     $ProgressPreference = 'SilentlyContinue'
     Invoke-WebRequest "https://aka.ms/AzEFLOWMSI_1_4_LTS_ARM64" -OutFile $msiPath
     

2. Install IoT Edge for Linux on Windows on your device.

   Start-Process -Wait msiexec -ArgumentList "/i","$([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))","/qn"
   

   You can specify custom IoT Edge for Linux on Windows installation and VHDX directories by adding INSTALLDIR="<FULLY_QUALIFIED_PATH>" and VHDXDIR="<FULLY_QUALIFIED_PATH>" parameters to the install command. For example, if you want to use the D:\EFLOW folder for installation and the D:\EFLOW-VHDX for the VHDX, you can use the following PowerShell cmdlet.

   Start-Process -Wait msiexec -ArgumentList "/i","$([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))","/qn","INSTALLDIR=D:\EFLOW", "VHDXDIR=D:\EFLOW-VHDX"
   

3. Set the execution policy on the target device to AllSigned if it is not already. See the PowerShell prerequisites for commands to check the current execution policy and set the execution policy to AllSigned.

4. Create the IoT Edge for Linux on Windows deployment. The deployment creates your Linux virtual machine and installs the IoT Edge runtime for you.

   Deploy-Eflow
   

   Tip

   By default, the Deploy-Eflow command creates your Linux virtual machine with 1 GB of RAM, 1 vCPU core, and 16 GB of disk space. However, the resources your VM needs are highly dependent on the workloads you deploy. If your VM does not have sufficient memory to support your workloads, it will fail to start.

   You can customize the virtual machine's available resources using the Deploy-Eflow command's optional parameters. This is required to deploy EFLOW on a device with the minimum hardware requirements.

   For example, the command below creates a virtual machine with 1 vCPU core, 1 GB of RAM (represented in MB), and 2 GB of disk space:

   Deploy-Eflow -cpuCount 1 -memoryInMB 1024 -vmDataSize 2
   

   For information about all the optional parameters available, see PowerShell functions for IoT Edge for Linux on Windows.

   Warning

   By default, the EFLOW Linux virtual machine has no DNS configuration. Deployments using DHCP will try to obtain the DNS configuration propagated by the DHCP server. Please check your DNS configuration to ensure internet connectivity. For more information, see AzEFLOW-DNS.

   You can assign a GPU to your deployment to enable GPU-accelerated Linux modules. To gain access to these features, you will need to install the prerequisites detailed in GPU acceleration for Azure IoT Edge for Linux on Windows.

   To use a GPU passthrough, add the gpuName, gpuPassthroughType, and gpuCount parameters to your Deploy-Eflow command. For information about all the optional parameters available, see PowerShell functions for IoT Edge for Linux on Windows.

   Warning

   Enabling hardware device passthrough may increase security risks. Microsoft recommends a device mitigation driver from your GPU's vendor, when applicable. For more information, see Deploy graphics devices using discrete device assignment.

5. Enter 'Y' to accept the license terms.

6. Enter 'O' or 'R' to toggle Optional diagnostic data on or off, depending on your preference.

7. Once the deployment is complete, the PowerShell window reports Deployment successful.

   

   After a successful deployment, you are ready to provision your device.

Provision the device with its cloud identity

You're ready to set up your device with its cloud identity and authentication information.

To provision your device using symmetric keys, you will need your device's connection string.

Run the following command in an elevated PowerShell session on your target device. Replace the placeholder text with your own values.

Provision-EflowVm -provisioningType ManualConnectionString -devConnString "PASTE_DEVICE_CONNECTION_STRING_HERE"

For more information about the Provision-EflowVM command, see PowerShell functions for IoT Edge for Linux on Windows.

Verify successful configuration

Verify that IoT Edge for Linux on Windows was successfully installed and configured on your IoT Edge device.

1. Log in to your IoT Edge for Linux on Windows virtual machine using the following command in your PowerShell session:

   Connect-EflowVm
   

   Note

   The only account allowed to SSH to the virtual machine is the user that created it.

2. Once you are logged in, you can check the list of running IoT Edge modules using the following Linux command:

   sudo iotedge list
   

3. If you need to troubleshoot the IoT Edge service, use the following Linux commands.

   1. Retrieve the service logs.

      sudo iotedge system logs
      

   2. Use the check tool to verify configuration and connection status of the device.

      sudo iotedge check
      

   Note

   On a newly provisioned device, you may see an error related to IoT Edge Hub:

   × production readiness: Edge Hub's storage directory is persisted on the host filesystem - Error

   Could not check current state of edgeHub container

   This error is expected on a newly provisioned device because the IoT Edge Hub module isn't running. To resolve the error, in IoT Hub, set the modules for the device and create a deployment. Creating a deployment for the device starts the modules on the device including the IoT Edge Hub module.

When you create a new IoT Edge device, it will display the status code 417 -- The device's deployment configuration is not set in the Azure portal. This status is normal, and means that the device is ready to receive a module deployment.

Uninstall IoT Edge for Linux on Windows

If you want to remove the Azure IoT Edge for Linux on Windows installation from your device, use the following commands.

1. Open Settings on Windows
2. Select Add or Remove Programs
3. Select Azure IoT Edge app
4. Select Uninstall

Next steps

• Continue to deploy IoT Edge modules to learn how to deploy modules onto your device.
• Learn how to manage certificates on your IoT Edge for Linux on Windows virtual machine and transfer files from the host OS to your Linux virtual machine.
• Learn how to configure your IoT Edge devices to communicate through a proxy server.