Create and provision an IoT Edge device on Linux using symmetric keys
Applies to: IoT Edge 1.5
IoT Edge 1.4
Important
IoT Edge 1.5 LTS and IoT Edge 1.4 LTS are supported releases. IoT Edge 1.4 LTS is end of life on November 12, 2024. If you are on an earlier release, see Update IoT Edge.
This article provides end-to-end instructions for registering and provisioning a Linux IoT Edge device that includes installing IoT Edge.
Each 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:
- IoT hub hostname
- Device ID
- Authentication details to connect 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 device on Linux 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 shows how to register your IoT Edge device and install IoT Edge (also called IoT Edge runtime) on your device. Make sure you have the device management tool of your choice, for example Azure CLI, and device requirements before you register and install your device.
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:
A free or standard IoT hub in your Azure subscription.
Device requirements
An X64, ARM32, or ARM64 Linux device.
Microsoft publishes installation packages for a variety of operating systems.
For the latest information about which operating systems are currently supported for production scenarios, see Azure IoT Edge supported systems.
Visual Studio Code extensions
If you are using Visual Studio Code, there are helpful Azure IoT extensions that make the device creation and management process easier.
Install both the Azure IoT Edge and Azure IoT Hub extensions:
Azure IoT Edge. The Azure IoT Edge tools for Visual Studio Code extension is in maintenance mode.
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.
Sign in to the Azure portal and navigate to your IoT hub.
In the left pane, select Devices from the menu, then select Add Device.
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.
- Create a descriptive Device ID, for example
Select Save.
You should see your new device listed in your IoT hub.
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.
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:
- From the Devices page, select the IoT Edge device ID from the list.
- Copy the value of either Primary Connection String or Secondary Connection String. Either key works.
Install IoT Edge
In this section, you prepare your Linux virtual machine or physical device for IoT Edge. Then, you install IoT Edge.
Run the following commands to add the package repository and then add the Microsoft package signing key to your list of trusted keys.
Important
On June 30, 2022 Raspberry Pi OS Stretch was retired from the Tier 1 OS support list. To avoid potential security vulnerabilities update your host OS to Bullseye.
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
For more information about operating system versions, see Azure IoT Edge supported platforms.
Note
Azure IoT Edge software packages are subject to the license terms located in each package (usr/share/doc/{package-name}
or the LICENSE
directory). Read the license terms prior to using a package. Your installation and use of a package constitutes your acceptance of these terms. If you don't agree with the license terms, don't use that package.
Install a container engine
Azure IoT Edge relies on an OCI-compatible container runtime. For production scenarios, we recommend that you use the Moby engine. The Moby engine is the container engine officially supported with IoT Edge. Docker CE/EE container images are compatible with the Moby runtime. If you are using Ubuntu Core snaps, the Docker snap is serviced by Canonical and supported for production scenarios.
Install the Moby engine.
sudo apt-get update; \
sudo apt-get install moby-engine
By default, the container engine doesn't set container log size limits. Over time, this can lead to the device filling up with logs and running out of disk space. However, you can configure your log to show locally, though it's optional. To learn more about logging configuration, see Production Deployment Checklist.
The following steps show you how to configure your container to use local
logging driver as the logging mechanism.
Create or edit the existing Docker daemon's config file
sudo nano /etc/docker/daemon.json
Set the default logging driver to the
local
logging driver as shown in the example.{ "log-driver": "local" }
Restart the container engine for the changes to take effect.
sudo systemctl restart docker
Install the IoT Edge runtime
The IoT Edge service provides and maintains security standards on the IoT Edge device. The service starts on every boot and bootstraps the device by starting the rest of the IoT Edge runtime.
Note
Beginning with version 1.2, the IoT identity service handles identity provisioning and management for IoT Edge and for other device components that need to communicate with IoT Hub.
The steps in this section represent the typical process to install the latest IoT Edge version on a device that has internet connection. If you need to install a specific version, like a pre-release version, or need to install while offline, follow the Offline or specific version installation steps later in this article.
Tip
If you already have an IoT Edge device running an older version and want to upgrade to the latest release, use the steps in Update the IoT Edge security daemon and runtime. Later versions are sufficiently different from previous versions of IoT Edge that specific steps are necessary to upgrade.
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.
Provision the device with its cloud identity
Now that the container engine and the IoT Edge runtime are installed on your device, you're ready to set up the device with its cloud identity and authentication information.
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.
Apply the configuration changes.
sudo iotedge config apply
To view the configuration file, you can open it:
sudo nano /etc/aziot/config.toml
Deploy modules
To deploy your IoT Edge modules, go to your IoT hub in the Azure portal, then:
Select Devices from the IoT Hub menu.
Select your device to open its page.
Select the Set Modules tab.
Since we want to deploy the IoT Edge default modules (edgeAgent and edgeHub), we don't need to add any modules to this pane, so select Review + create at the bottom.
You see the JSON confirmation of your modules. Select Create to deploy the modules.
For more information, see Deploy a module.
Verify successful configuration
Verify that the runtime was successfully installed and configured on your IoT Edge device.
Tip
You need elevated privileges to run iotedge
commands. Once you sign out of your machine and sign back in the first time after installing the IoT Edge runtime, your permissions are automatically updated. Until then, use sudo
in front of the commands.
Check to see that the IoT Edge system service is running.
sudo iotedge system status
A successful status response shows the
aziot
services as running or ready.If you need to troubleshoot the service, retrieve the service logs.
sudo iotedge system logs
Use the
check
tool to verify configuration and connection status of the device.sudo iotedge check
You can expect a range of responses that may include OK (green), Warning (yellow), or Error (red). For troubleshooting common errors, see Solutions to common issues for Azure IoT Edge.
Tip
Always use
sudo
to run the check tool, even after your permissions are updated. The tool needs elevated privileges to access the config file to verify configuration status.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 is not yet running. Be sure your IoT Edge modules were deployed in the previous steps. Deployment resolves this error.
Alternatively, you may see a status code as
417 -- The device's deployment configuration is not set
. Once your modules are deployed, this status will change.When the service starts for the first time, you should only see the edgeAgent module running. The edgeAgent module runs by default and helps to install and start any additional modules that you deploy to your device.
Check that your device and modules are deployed and running, by viewing your device page in the Azure portal.
Once your modules are deployed and running, list them in your device or virtual machine with the following command:
sudo iotedge list
Offline or specific version installation (optional)
The steps in this section are for scenarios not covered by the standard installation steps. This may include:
- Installing IoT Edge while offline
- Installing a release candidate version
Use the steps in this section if you want to install a specific version of the Azure IoT Edge runtime that isn't available through your package manager. The Microsoft package list only contains a limited set of recent versions and their sub-versions, so these steps are for anyone who wants to install an older version or a release candidate version.
If you are using Ubuntu snaps, you can download a snap and install it offline. For more information, see Download snaps and install offline.
Using curl commands, you can target the component files directly from the IoT Edge GitHub repository.
Navigate to the Azure IoT Edge releases, and find the release version that you want to target.
Expand the Assets section for that version.
Every release should have new files for IoT Edge and the identity service. If you're going to install IoT Edge on an offline device, download these files ahead of time. Otherwise, use the following commands to update those components.
Find the aziot-identity-service file that matches your IoT Edge device's architecture. Right-click on the file link and copy the link address.
Use the copied link in the following command to install that version of the identity service:
curl -L <identity service link> -o aziot-identity-service.deb && sudo apt-get install ./aziot-identity-service.deb
Find the aziot-edge file that matches your IoT Edge device's architecture. Right-click on the file link and copy the link address.
Use the copied link in the following command to install that version of IoT Edge.
curl -L <iotedge link> -o aziot-edge.deb && sudo apt-get install ./aziot-edge.deb
Uninstall IoT Edge
If you want to remove the IoT Edge installation from your device, use the following commands.
Remove the IoT Edge runtime.
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.
When the IoT Edge runtime is removed, any containers that it created are stopped but still exist on your device. View all containers to see which ones remain.
sudo docker ps -a
Delete the containers from your device, including the two runtime containers.
sudo docker rm -f <container ID>
Finally, remove the container runtime from your device.
sudo apt-get autoremove --purge moby-engine
Next steps
Continue to deploy IoT Edge modules to learn how to deploy modules onto your device.
Обратна връзка
https://aka.ms/ContentUserFeedback.
Очаквайте скоро: През цялата 2024 г. постепенно ще отстраняваме проблемите в GitHub като механизъм за обратна връзка за съдържание и ще го заменим с нова система за обратна връзка. За повече информация вижте:Подаване и преглед на обратна връзка за