Create and provision an IoT Edge device on Linux using X.509 certificates

Applies to: yes icon IoT Edge 1.1 Other versions: IoT Edge 1.3, IoT Edge 1.4

Applies to: IoT Edge 1.3 checkmark IoT Edge 1.3 IoT Edge 1.4 checkmark IoT Edge 1.4 Other versions: IoT Edge 1.1

This article provides end-to-end instructions for registering and provisioning a Linux IoT Edge device, including installing IoT Edge.

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 X.509 certificates as your authentication method. If you want to use symmetric keys, see Create and provision an IoT Edge device on Linux using symmetric keys.

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 on it. 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:

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.

Generate device identity certificates

Manual provisioning with X.509 certificates requires IoT Edge version 1.0.10 or newer.

When you provision an IoT Edge device with X.509 certificates, you use what is called a device identity certificate. This certificate is only used for provisioning an IoT Edge device and authenticating the device with Azure IoT Hub. It is a leaf certificate that doesn't sign other certificates. The device identity certificate is separate from the certificate authority (CA) certificates that the IoT Edge device presents to modules or downstream devices for verification.

For X.509 certificate authentication, each device's authentication information is provided in the form of thumbprints taken from your device identity certificates. These thumbprints are given to IoT Hub at the time of device registration so that the service can recognize the device when it connects.

For more information about how the CA certificates are used in IoT Edge devices, see Understand how Azure IoT Edge uses certificates.

You need the following files for manual provisioning with X.509:

  • Two of device identity certificates with their matching private key certificates in .cer or .pem formats.

    One set of certificate/key files is provided to the IoT Edge runtime. When you create device identity certificates, set the certificate common name (CN) with the device ID that you want the device to have in your IoT hub.

  • Thumbprints taken from both device identity certificates.

    Thumbprint values are 40-hex characters for SHA-1 hashes or 64-hex characters for SHA-256 hashes. Both thumbprints are provided to IoT Hub at the time of device registration.

If you don't have certificates available, you can Create demo certificates to test IoT Edge device features. Follow the instructions in that article to set up certificate creation scripts, create a root CA certificate, and then create two IoT Edge device identity certificates.

One way to retrieve the thumbprint from a certificate is with the following openssl command:

openssl x509 -in <certificate filename>.pem -text -fingerprint

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 Devices from the menu, then select Add Device.

  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.
    • Check the IoT Edge Device checkbox.
    • Select X.509 Self-Signed as the authentication type.
    • Provide the primary and secondary identity certificate thumbprints. Thumbprint values are 40-hex characters for SHA-1 hashes or 64-hex characters for SHA-256 hashes.
  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 X.509 certificate authentication need their IoT hub name, their device name, and their certificate files to complete installation and provisioning of the IoT Edge runtime.

The edge-enabled devices that connect to your IoT hub are listed on the Devices page. You can filter the list by type Iot Edge Device.

Screenshot of how to view all IoT Edge devices in your IoT hub.

Install IoT Edge

In this section, you prepare your Linux VM 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.

Installing can be done with a few commands. Open a terminal and run the following commands:

  • 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
    
  • 18.04:

    wget https://packages.microsoft.com/config/ubuntu/18.04/multiarch/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
    sudo dpkg -i packages-microsoft-prod.deb
    rm packages-microsoft-prod.deb
    

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 only container engine officially supported with IoT Edge. Docker CE/EE container images are compatible with the Moby runtime.

Install the Moby engine.

sudo apt-get update; \
  sudo apt-get install moby-engine

Once the Moby engine is successfully installed, configure it to use local logging driver as the logging mechanism. To learn more about logging configuration, see Production Deployment Checklist.

  • Create or open the Docker daemon's config file at /etc/docker/daemon.json.

  • Set the default logging driver to the local logging driver as shown in the example below.

       {
          "log-driver": "local"
       }
    
  • Restart the container engine for the changes to take effect.

    sudo systemctl restart docker
    

    Tip

    If you get errors when you install the Moby container engine, verify your Linux kernel for Moby compatibility. Some embedded device manufacturers ship device images that contain custom Linux kernels without the features required for container engine compatibility. Run the following command, which uses the check-config script provided by Moby, to check your kernel configuration:

    curl -ssl https://raw.githubusercontent.com/moby/moby/master/contrib/check-config.sh -o check-config.sh
    chmod +x check-config.sh
    ./check-config.sh
    

    In the output of the script, check that all items under Generally Necessary and Network Drivers are enabled. If you're missing features, enable them by rebuilding your kernel from source and selecting the associated modules for inclusion in the appropriate kernel .config. Similarly, if you're using a kernel configuration generator like defconfig or menuconfig, find and enable the respective features and rebuild your kernel accordingly. After you've deployed your newly modified kernel, run the check-config script again to verify that all the required features were successfully enabled.

Install the IoT Edge runtime

The IoT Edge security daemon provides and maintains security standards on the IoT Edge device. The daemon starts on every boot and bootstraps the device by starting the rest of the IoT Edge runtime.

The steps in this section represent the typical process to install the latest 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.

Install IoT Edge version 1.1.* along with the libiothsm-std package:

sudo apt-get update; \
  sudo apt-get install iotedge

Note

IoT Edge version 1.1 is the long-term support branch of IoT Edge. If you are running an older version, we recommend installing or updating to the latest patch as older versions are no longer supported.

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.

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

Note

The steps in this section show you how to install the latest IoT Edge version.

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:

sudo apt-get update; \
  sudo apt-get install aziot-edge defender-iot-micro-agent-edge

The 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 for the next step, which is to set up the device with its cloud identity and authentication information.

On the IoT Edge device, open the configuration file.

sudo nano /etc/iotedge/config.yaml

Find the provisioning configurations section of the file and uncomment the Manual provisioning configuration using an X.509 identity certificate section. Make sure that any other provisioning sections are commented out. Make sure the provisioning: line has no preceding whitespace and that nested items are indented by two spaces.

# Manual provisioning configuration using an x.509 identity certificate
provisioning:
  source: "manual"
  authentication:
    method: "x509"
    iothub_hostname: "REQUIRED_IOTHUB_HOSTNAME"
    device_id: "REQUIRED_DEVICE_ID_PROVISIONED_IN_IOTHUB"
    identity_cert: "REQUIRED_URI_TO_DEVICE_IDENTITY_CERTIFICATE"
    identity_pk: "REQUIRED_URI_TO_DEVICE_IDENTITY_PRIVATE_KEY"

Update the following fields:

  • iothub_hostname: Hostname of the IoT hub the device will connect to. For example, {IoT hub name}.azure-devices.net.
  • device_id: The ID that you provided when you registered the device.
  • identity_cert: URI to an identity certificate on the device. For example, file:///path/identity_certificate.pem.
  • identity_pk: URI to the private key file for the provided identity certificate. For example, file:///path/identity_key.pem.

Save and close the file.

CTRL + X, Y, Enter

After entering the provisioning information in the configuration file, restart the daemon:

sudo systemctl restart iotedge

Create the configuration file for your device based on a template file that is provided as part of the IoT Edge installation.

sudo cp /etc/aziot/config.toml.edge.template /etc/aziot/config.toml

On the IoT Edge device, open the configuration file.

sudo nano /etc/aziot/config.toml

Find the Provisioning section of the file and uncomment the lines for manual provisioning with X.509 identity certificate. Make sure that any other provisioning sections are commented out.

# Manual provisioning with x.509 certificates
[provisioning]
source = "manual"
iothub_hostname = "REQUIRED_IOTHUB_HOSTNAME"
device_id = "REQUIRED_DEVICE_ID_PROVISIONED_IN_IOTHUB"

[provisioning.authentication]
method = "x509"

identity_cert = "REQUIRED_URI_OR_POINTER_TO_DEVICE_IDENTITY_CERTIFICATE"

identity_pk = "REQUIRED_URI_TO_DEVICE_IDENTITY_PRIVATE_KEY"

Update the following fields:

  • iothub_hostname: Hostname of the IoT hub the device will connect to. For example, {IoT hub name}.azure-devices.net.
  • device_id: The ID that you provided when you registered the device.
  • identity_cert: URI to an identity certificate on the device, for example: file:///path/identity_certificate.pem. Or, dynamically issue the certificate using EST or a local certificate authority.
  • identity_pk: URI to the private key file for the provided identity certificate, for example: file:///path/identity_key.pem. Or, provide a PKCS#11 URI and then provide your configuration information in the PKCS#11 section later in the config file.

Save and close the file.

CTRL + X, Y, Enter

After entering the provisioning information in the configuration file, apply your changes:

sudo iotedge config apply

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 systemctl status iotedge
sudo iotedge system status

A successful status response is Ok.

If you need to troubleshoot the service, retrieve the service logs.

journalctl -u iotedge
sudo iotedge system logs

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

sudo iotedge check

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

View all the modules running on your IoT Edge device. 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.

sudo iotedge list

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.

Offline or specific version installation (optional)

The steps in this section are for scenarios not covered by the standard installation steps. This may include:

  • Install IoT Edge while offline
  • Install 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.

Using curl commands, you can target the component files directly from the IoT Edge GitHub repository.

  1. Navigate to the Azure IoT Edge releases, and find the release version that you want to target.

  2. Expand the Assets section for that version.

  3. Every release should have new files for the IoT Edge security daemon and the hsmlib. 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.

    1. Find the libiothsm-std file that matches your IoT Edge device's architecture. Right-click on the file link and copy the link address.

    2. Use the copied link in the following command to install that version of the hsmlib:

      curl -L libiothsm-std_link_here -o libiothsm-std.deb && sudo apt-get install ./libiothsm-std.deb
      
    3. Find the iotedge file that matches your IoT Edge device's architecture. Right-click on the file link and copy the link address.

    4. Use the copied link in the following command to install that version of the IoT Edge security daemon.

      curl -L iotedge_link_here -o iotedge.deb && sudo apt-get install ./iotedge.deb
      

Note

If your device is currently running IoT Edge version 1.1 or older, uninstall the iotedge and libiothsm-std packages before following the steps in this section. For more information, see Update from 1.0 or 1.1 to latest release.

  1. Navigate to the Azure IoT Edge releases, and find the release version that you want to target.

  2. Expand the Assets section for that version.

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

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

    2. 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
      
    3. Find the aziot-edge file that matches your IoT Edge device's architecture. Right-click on the file link and copy the link address.

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

Now that the container engine and the IoT Edge runtime are installed on your device, you're ready for the next step, which is to Provision the device with its cloud identity.

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 iotedge
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 flags 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 name>

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.