Install or uninstall Azure IoT Edge for Linux

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.

This article lists the steps to install the Azure IoT Edge runtime on Linux devices.

Prerequisites

  • A registered device ID

    If you registered your device with symmetric key authentication, have the device connection string ready.

    If you registered your device with X.509 self-signed certificate authentication, have at least one of the identity certificates that you used to register the device and its matching private key available on your device.

  • A Linux device

    Have an X64, ARM32, or ARM64 Linux device. Azure provides installation packages for Ubuntu Server 18.04 and Raspberry Pi OS Stretch operating systems.

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

    Note

    Support for ARM64 devices is in public preview.

  • Prepare your device to access the Azure installation packages.

    Install the repository configuration that matches your device operating system.

    • 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
      

    Copy the generated list to the sources.list.d directory.

    sudo cp ./microsoft-prod.list /etc/apt/sources.list.d/
    

    Install the Azure 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 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 IoT Edge

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.

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

Option 1: Authenticate with symmetric keys

At this point, the IoT Edge runtime is installed on your Linux device, and you need to provision the device with its cloud identity and authentication information.

This section walks through the steps to provision a device with symmetric key authentication. You should have registered your device in IoT Hub, and retrieved the connection string from the device information. If not, follow the steps in Register an IoT Edge device in IoT Hub.

Option 2: Authenticate with X.509 certificates

At this point, the IoT Edge runtime is installed on your Linux device, and you need to provision the device with its cloud identity and authentication information.

This section walks through the steps to provision a device with X.509 certificate authentication. You should have registered your device in IoT Hub, providing thumbprints that match the certificate and private key located on your IoT Edge device. If not, follow the steps in Register an IoT Edge device in IoT Hub.

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.

If you need to troubleshoot the service, retrieve the service 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.

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 apt-get install. The Azure 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.

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.

Use the --purge flag if you want to delete all the files associated with IoT Edge, including your configuration files. Leave this flag out if you want to reinstall IoT Edge and use the same configuration information in the future.

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

Continue to deploy IoT Edge modules to learn how to deploy modules onto your device.