Install or uninstall the Azure IoT Edge runtime

The Azure IoT Edge runtime is what turns a device into an IoT Edge device. The runtime can be deployed on devices as small as a Raspberry Pi or as large as an industrial server. Once a device is configured with the IoT Edge runtime, you can start deploying business logic to it from the cloud. To learn more, see Understand the Azure IoT Edge runtime and its architecture.

There are two steps to setting up an IoT Edge device. The first step is to install the runtime and its dependencies, which is covered by this article. The second step is to connect the device to its identity in the cloud and set up authentication with IoT Hub. Those steps are in the next articles.

This article lists the steps to install the Azure IoT Edge runtime on Linux or Windows devices. For Windows devices, you have an additional choice of using Linux containers or Windows containers. Currently, Windows containers on Windows are recommended for production scenarios. Linux containers on Windows are useful for development and testing scenarios, especially if you're developing on a Windows PC in order to deploy to Linux devices.

Prerequisites

For the latest information about which operating systems are currently supported for production scenarios, see Azure IoT Edge supported systems

Have an X64, ARM32, or ARM64 Linux device. Microsoft provides installation packages for Ubuntu Server 16.04, Ubuntu Server 18.04, and Raspbian Stretch operating systems.

Note

Support for ARM64 devices is in public preview.

Prepare your device to access the Microsoft installation packages.

  1. Install the repository configuration that matches your device operating system.

    • Ubuntu Server 16.04:

      curl https://packages.microsoft.com/config/ubuntu/16.04/multiarch/prod.list > ./microsoft-prod.list
      
    • Ubuntu Server 18.04:

      curl https://packages.microsoft.com/config/ubuntu/18.04/multiarch/prod.list > ./microsoft-prod.list
      
    • Raspberry Pi OS Stretch:

      curl https://packages.microsoft.com/config/debian/stretch/multiarch/prod.list > ./microsoft-prod.list
      
  2. Copy the generated list to the sources.list.d directory.

    sudo cp ./microsoft-prod.list /etc/apt/sources.list.d/
    
  3. Install the Microsoft GPG public key.

    curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg
    sudo cp ./microsoft.gpg /etc/apt/trusted.gpg.d/
    

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 do not agree with the license terms, do not use that package.

Install a container engine

Azure IoT Edge relies on an OCI-compatible container runtime. For production scenarios, we recommended that you use the Moby-based engine. The Moby engine is the only container engine officially supported with Azure IoT Edge. Docker CE/EE container images are compatible with the Moby runtime.

Update package lists on your device.

sudo apt-get update

Install the Moby engine.

sudo apt-get install moby-engine

If you get errors when installing 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 are 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 are using a kernel configuration generator like defconfig or menuconfig, find and enable the respective features and rebuild your kernel accordingly. Once you have 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 security daemon

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 these 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 in the next section.

Update package lists on your device.

sudo apt-get update

Check to see which versions of IoT Edge are available.

apt list -a iotedge

If you want to install the most recent version of the security daemon, use the following command that also installs the latest version of the libiothsm-std package:

sudo apt-get install iotedge

If you want to install a specific version of the security daemon, specify the version from the apt list output. Also specify the same version for the libiothsm-std package, which otherwise would install its latest version. For example, the following command installs the most recent version of the 1.0.8 release:

sudo apt-get install iotedge=1.0.8* libiothsm-std=1.0.8*

If the version that you want to install isn't listed, follow the Offline or specific version installation steps in the next section. That section shows you how to target any previous version of the IoT Edge security daemon, or release candidate versions.

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 register your device with IoT Hub and set up the device with its cloud identity and authentication information.

Choose the next article based on which authentication type you want to use:

Offline or specific version installation

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
  • On Windows, install a version other than the latest

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 apt-get install. 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. 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> -o libiothsm-std.deb && sudo dpkg -i ./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> -o iotedge.deb && sudo dpkg -i ./iotedge.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 Authenticate an IoT Edge device in IoT Hub.

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 remove --purge iotedge

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 remove --purge moby-cli
sudo apt-get remove --purge moby-engine

Next steps

After installing the IoT Edge runtime, configure your device to connect with IoT Hub. The following articles walk through registering a new device in the cloud and then providing the device with its identity and authentication info.

Choose the next article based on which type of authentication you want to use: