Skip to content

how-to-provision-single-device-linux-on-windows-symmetric.md

Latest commit

 

History

History
124 lines (83 loc) · 6.66 KB

how-to-provision-single-device-linux-on-windows-symmetric.md

File metadata and controls

124 lines (83 loc) · 6.66 KB
title Create and provision an Azure IoT Edge for Linux on Windows device using symmetric keys
description Create and provision a single IoT Edge for Linux on Windows device in IoT Hub using manual provisioning with symmetric keys
author sethmanheim
ms.author sethm
ms.service azure-iot-edge
services iot-edge
ms.topic how-to
ms.date 03/02/2026
ms.custom
linux-related-content
sfi-ropc-nochange

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

[!INCLUDE iot-edge-version-all-supported]

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 isn't 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 need to set up many devices 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 use different utilities. Make sure you meet all the prerequisites before proceeding.

[!INCLUDE iot-edge-prerequisites-register-device.md]

[!INCLUDE iot-edge-prerequisites-linux-on-windows.md]

[!INCLUDE iot-edge-register-device-symmetric.md]

[!INCLUDE install-iot-edge-linux-on-windows.md]

Provision the device with its cloud identity

Set up your device with its cloud identity and authentication information.

To provision your device using symmetric keys, you need your device 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 is successfully installed and configured on your IoT Edge device.

  1. Sign in to your IoT Edge for Linux on Windows virtual machine by 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. After you sign in, check the list of running IoT Edge modules by 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 might 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 displays 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.

[!INCLUDE uninstall-iot-edge-linux-on-windows.md]

Next steps