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

Applies to: yes icon IoT Edge 1.1

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:

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 registration

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

A free or standard IoT hub in your Azure subscription.

IoT Edge for Linux on Windows installation

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.

Register your device

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

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 IoT Edge from the menu, then select Add an IoT Edge device.

    Add an IoT Edge device from the Azure portal

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

    • Create a descriptive device ID. Make a note of this device ID, as you'll use it later.
    • Select Symmetric key as the authentication type.
    • Use the default settings to auto-generate authentication keys and connect the new device to your hub.
  4. Select Save.

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

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.

All the edge-enabled devices that connect to your IoT hub are listed on the IoT Edge page.

Use the Azure portal to view all IoT Edge devices in your IoT hub

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.

  1. From the IoT Edge page in the portal, click on the device ID from the list of IoT Edge devices.
  2. Copy the value of either Primary Connection String or Secondary Connection String.

Install IoT Edge for Linux on Windows

You can use either PowerShell or Windows Admin Center to install IoT Edge for Linux on Windows.

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.

  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.

Configure the device with provisioning information

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.

You can use the Windows Admin Center or an elevated PowerShell session to provision your devices.

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 "<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 journalctl -u iotedge
      
    2. Use the check tool to verify configuration and connection status of the device.

      sudo iotedge check
      

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.

Next steps