Create and provision an IoT Edge for Linux on Windows device at-scale using a TPM

Applies to: yes icon IoT Edge 1.1

This article provides end-to-end instructions for auto-provisioning an IoT Edge for Linux on Windows device using a Trusted Platform Module (TPM). 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 auto-provisioning, review the provisioning overview before continuing.

This article outlines two methodologies. Select your preference based on the architecture of your solution:

  1. Auto-provision a Linux on Windows device with physical TPM hardware.
  2. Auto-provision a Linux on Windows device using a simulated TPM. This methodology is recommended only as a testing scenario, because a simulated TPM does not offer the same security as a physical TPM.

The tasks are as follows:

  • Install IoT Edge for Linux on Windows.
  • Retrieve the TPM information from your device.
  • Create an individual enrollment for the device.
  • Provision your device with its TPM information.

Prerequisites

Cloud resources:

  • An active IoT Hub.
  • An instance of the IoT Hub Device Provisioning Service in Azure, linked to your IoT hub.

A development machine:

  • A Windows device with the following minimum system requirements:

    • Windows 10 Version 1809 or later; build 17763 or later
    • Professional, Enterprise, or Server editions
    • Minimum Free Memory: 1 GB
    • Minimum Free Disk Space: 10 GB
    • Virtualization support
    • 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.

You can use either PowerShell or Windows Admin Center to manage your IoT Edge devices. Each utility has its own prerequisites:

If you want to use PowerShell, use the following steps to 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.

Note

TPM 2.0 is required when using TPM attestation with DPS.

You can only create individual, not group, DPS enrollments when using a TPM.

Install IoT Edge

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

Install IoT Edge for Linux on Windows onto 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 each of the following commands to download IoT Edge for Linux on Windows.

    $msiPath = $([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))
    $ProgressPreference = 'SilentlyContinue'
    Invoke-WebRequest "https://aka.ms/AzEflowMSI" -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.

  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.

    For example, the command below creates a virtual machine with 4 vCPU cores, 4 GB of RAM, and 20 GB of disk space:

    Deploy-Eflow -cpuCount 4 -memoryInMB 4096 -vmDiskSize 20
    

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

    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.

    A successful deployment will say 'Deployment successful' at the end of the messages, PNG.

Once your deployment is complete, you are ready to provision your device.

Enable TPM passthrough

The IoT Edge for Linux on Windows virtual machine has a TPM feature that can be enabled or disabled. By default, it's disabled. When this feature is enabled, the virtual machine can access the host machine's TPM.

  1. Open PowerShell in an elevated session.

  2. If you haven't already, set the execution policy on your device to AllSigned so that you can run the IoT Edge for Linux on Windows PowerShell functions.

    Set-ExecutionPolicy -ExecutionPolicy AllSigned -Force
    
  3. Turn on the TPM feature.

    Set-EflowVmFeature -feature 'DpsTpm' -enable
    

Retrieve the TPM information from your device

To provision your device, you need to gather information from your TPM chip and provide it to your instance of the Device Provisioning Service (DPS) so that the service can recognize your device when it tries to connect.

First, you need to determine the Endorsement key, which is unique to each TPM chip and is obtained from the TPM chip manufacturer associated with it. Then, you need to provide a Registration ID for your device. You can derive a unique registration ID for your TPM device by, for example, creating an SHA-256 hash of the endorsement key.

IoT Edge for Linux on Windows provides a PowerShell script to help retrieve this information from your TPM. To use the script, follow these steps on your device:

  1. Open PowerShell in an elevated session.

  2. Run the command.

    Get-EflowVmTpmProvisioningInfo
    

Create a DPS enrollment

Use your TPM's provisioning information to create an individual enrollment in the Device Provisioning Service.

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.

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.

  1. In the Azure portal, navigate to your instance of the IoT Hub Device Provisioning Service.

  2. Under Settings, select Manage enrollments.

  3. Select Add individual enrollment, then complete the following steps to configure the enrollment:

    1. For Mechanism, select TPM.

    2. Provide the Endorsement key and Registration ID that you copied from your virtual machine or physical device.

    3. Provide an ID for your device if you'd like. If you don't provide a device ID, the registration ID is used.

    4. Select True to declare that your virtual machine or physical device is an IoT Edge device.

    5. Choose the linked IoT hub that you want to connect your device to, or select Link to new IoT Hub. You can choose multiple hubs, and the device will be assigned to one of them according to the selected assignment policy.

    6. Add a tag value to the Initial Device Twin State if you'd like. You can use tags to target groups of devices for module deployment. For more information, see Deploy IoT Edge modules at scale.

    7. Select Save.

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

Configure the device with provisioning information

  1. Open an elevated PowerShell session on the Windows device.

  2. Provision your device using the Scope ID that you collected from your instance of Device Provisioning Service.

    Provision-EflowVM -provisioningType "DpsTpm" -scopeId "<scope id>"
    

Verify successful configuration

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

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

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.

  1. Connect 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. If you need to troubleshoot the service, retrieve the service logs.

      sudo journalctl -u iotedge
      
    2. Use the check tool to verify configuration and connection status of the device.

      sudo iotedge check
      

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