在基于 Debian 的 Linux 系统上安装 Azure IoT Edge 运行时Install the Azure IoT Edge runtime on Debian-based Linux systems

使用 Azure IoT Edge 运行时可将设备转变为 IoT Edge 设备。The Azure IoT Edge runtime is what turns a device into an IoT Edge device. 该运行时可以部署在像 Raspberry Pi 一样小的设备上,也可以部署在像工业服务器一样大的设备上。The runtime can be deployed on devices as small as a Raspberry Pi or as large as an industrial server. 使用 IoT Edge 运行时配置设备后,即可开始从云中部署业务逻辑。Once a device is configured with the IoT Edge runtime, you can start deploying business logic to it from the cloud. 若要了解详细信息,请参阅了解 Azure IoT Edge 运行时及其体系结构To learn more, see Understand the Azure IoT Edge runtime and its architecture.

本文列出了在 X64、ARM32 或 ARM64 Linux 设备上安装 Azure IoT Edge 运行时的步骤。This article lists the steps to install the Azure IoT Edge runtime on an X64, ARM32, or ARM64 Linux device. 我们为 Ubuntu Server 16.04、Ubuntu Server 18.04 和 Raspbian Stretch 提供安装包。We provide installation packages for Ubuntu Server 16.04, Ubuntu Server 18.04, and Raspbian Stretch. 有关支持的 Linux 操作系统和体系结构的列表,请参阅 Azure IoT Edge 支持的系统Refer to Azure IoT Edge supported systems for a list of supported Linux operating systems and architectures.

备注

Linux 软件存储库中的包受到每个包中的许可条款限制 (/usr/share/doc/package-name)。Packages in the Linux software repositories are subject to the license terms located in each package (/usr/share/doc/package-name). 使用程序包之前请阅读许可条款。Read the license terms prior to using the package. 安装和使用程序包即表示接受这些条款。Your installation and use of the package constitutes your acceptance of these terms. 如果不同意许可条款,则不要使用程序包。If you do not agree with the license terms, do not use the package.

安装容器运行时和 IoT EdgeInstall container runtime and IoT Edge

根据以下部分的说明,将最新版 Azure IoT Edge 运行时安装到设备上。Use the following sections to install the most recent version of the Azure IoT Edge runtime onto your device.

备注

对 ARM64 设备的支持为公共预览版。Support for ARM64 devices is in public preview.

注册 Microsoft 密钥和软件存储库源Register Microsoft key and software repository feed

准备设备,以便安装 IoT Edge 运行时。Prepare your device for the IoT Edge runtime installation.

安装存储库配置。Install the repository configuration. 选择与设备操作系统匹配的 16.0418.04 命令:Choose the 16.04 or 18.04 command that matches your device operating system:

  • Ubuntu Server 16.04Ubuntu Server 16.04:

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

    curl https://packages.microsoft.com/config/ubuntu/18.04/multiarch/prod.list > ./microsoft-prod.list
    
  • Raspbian StretchRaspbian Stretch:

    curl https://packages.microsoft.com/config/debian/stretch/multiarch/prod.list > ./microsoft-prod.list
    

复制生成的列表。Copy the generated list.

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

安装 Microsoft GPG 公钥。Install 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/

安装容器运行时Install a container runtime

Azure IoT Edge 依赖于 OCI 兼容的容器运行时。Azure IoT Edge relies on an OCI-compatible container runtime. 对于生产方案,建议使用下面提供的基于 Moby 的引擎。For production scenarios, we recommended that you use the Moby-based engine provided below. Moby 引擎是官方唯一支持用于 Azure IoT Edge 的容器引擎。The Moby engine is the only container engine officially supported with Azure IoT Edge. Docker CE/EE 容器映像与 Moby 运行时兼容。Docker CE/EE container images are compatible with the Moby runtime.

更新设备上的包列表。Update package lists on your device.

sudo apt-get update

安装 Moby 引擎。Install the Moby engine.

sudo apt-get install moby-engine

安装 Moby 命令行接口 (CLI)。Install the Moby command-line interface (CLI). CLI 对开发非常有用,但对生产部署来说是可选的。The CLI is useful for development but optional for production deployments.

sudo apt-get install moby-cli

如果在安装 Moby 容器运行时时出现错误,请按本文后面提供的步骤验证 Linux 内核的 Moby 兼容性If you get errors when installing the Moby container runtime, follow the steps to Verify your Linux kernel for Moby compatibility, provided later in this article.

安装 Azure IoT Edge 安全守护程序Install the Azure IoT Edge Security Daemon

IoT Edge 安全守护程序提供和维护 IoT Edge 设备上的安全标准。The IoT Edge security daemon provides and maintains security standards on the IoT Edge device. 守护程序在每次开机时启动,并通过启动 IoT Edge 运行时的其余部分来启动设备。The daemon starts on every boot and bootstraps the device by starting the rest of the IoT Edge runtime.

更新设备上的包列表。Update package lists on your device.

sudo apt-get update

查看可用的 IoT Edge 版本。Check to see which versions of IoT Edge are available.

apt list -a iotedge

如果要安装最新版本的安全守护程序,请使用以下命令,该命令还会安装最新版本的 libiothsm-std 包:If you want to install the most recent version of the security daemon, use the following command which also installs the latest version of the libiothsm-std package:

sudo apt-get install iotedge

如果要安装特定版本的安全守护程序,请从 apt 列表输出中指定该版本。If you want to install a specific version of the security daemon, specify the version from the apt list output. 还要为 libiothsm-std 包指定同一版本,否则将安装其最新版本。Also specify the same version for the libiothsm-std package, which otherwise would install its latest version. 例如,以下命令将安装最新版本 1.0.8 版本: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 steps in Install runtime using release assets. 此部分说明了如何将 IoT Edge 安全守护程序的任何之前版本或候选发布版本作为目标。That section shows you how to target any previous version of the IoT Edge security daemon, or release candidate versions.

IoT Edge 在 /etc/iotedge/ 成功安装以后,输出会提示你更新配置文件。Once IoT Edge is successfully installed at /etc/iotedge/, the output prompts you to update the configuration file. 继续执行下一部分的步骤,完成设备预配。Continue to the next section to complete device provisioning.

配置安全守护程序Configure the security daemon

配置 IoT Edge 运行时以将物理设备与 Azure IoT 中心中存在的设备标识相链接。Configure the IoT Edge runtime to link your physical device with a device identity that exists in an Azure IoT hub.

可以使用 /etc/iotedge/config.yaml 处的配置文件配置守护程序。The daemon can be configured using the configuration file at /etc/iotedge/config.yaml. 默认情况下,该文件有写保护,你可能需要提升权限才能对其进行编辑。The file is write-protected by default, you might need elevated permissions to edit it.

可以使用 IoT 中心提供的设备连接字符串手动预配单个 IoT Edge 设备。A single IoT Edge device can be provisioned manually using a device connections string provided by IoT Hub. 或者,可以使用设备预配服务自动预配设备,当需要预配多个设备时这会非常有用。Or, you can use the Device Provisioning Service to automatically provision devices, which is helpful when you have many devices to provision. 根据预配选项,选择合适的安装脚本。Depending on your provisioning choice, choose the appropriate installation script.

选项 1:手动预配Option 1: Manual provisioning

若要手动预配设备,需要为其提供设备连接字符串,可以通过在 IoT 中心注册新设备来创建该设备连接字符串。To manually provision a device, you need to provide it with a device connection string that you can create by registering a new device in your IoT hub.

打开配置文件。Open the configuration file.

sudo nano /etc/iotedge/config.yaml

找到文件的预配配置,并取消注释“手动预配配置”节。Find the provisioning configurations of the file and uncomment the Manual provisioning configuration section. 使用 IoT Edge 设备的连接字符串更新 device_connection_string 的值。Update the value of device_connection_string with the connection string from your IoT Edge device. 请确保注释掉任何其他预配部分。请确保 provisioning: 行前面没有空格,并且嵌套项缩进了两个空格。Make sure 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
provisioning:
  source: "manual"
  device_connection_string: "<ADD DEVICE CONNECTION STRING HERE>"

将剪贴板内容粘贴到 Nano Shift+Right Click 或按 Shift+InsertTo paste clipboard contents into Nano Shift+Right Click or press Shift+Insert.

保存并关闭该文件。Save and close the file.

CTRL + X, Y, EnterCTRL + X, Y, Enter

在配置文件中输入预配信息后,重启守护程序:After entering the provisioning information in the configuration file, restart the daemon:

sudo systemctl restart iotedge

选项 2:自动预配Option 2: Automatic provisioning

可以使用 Azure IoT 中心设备预配服务 (DPS) 自动预配 IoT Edge 设备。IoT Edge devices can be automatically provisioned using the Azure IoT Hub Device Provisioning Service (DPS). 目前,使用自动预配时,IoT Edge 支持三种证明机制,但硬件要求会影响你的选择。Currently, IoT Edge supports three attestation mechanisms when using automatic provisioning, but your hardware requirements may impact your choices. 例如,默认情况下,Raspberry Pi 设备不附带受信任的平台模块 (TPM) 芯片。For example, Raspberry Pi devices do not come with a Trusted Platform Module (TPM) chip by default. 有关详细信息,请参阅以下文章:For more information, see the following articles:

这些文章逐步讲解如何在 DPS 中设置注册,并生成适用于证明的证书或密钥。Those articles walk you through setting up enrollments in DPS, and generating the proper certificates or keys for attestation. 无论选择哪种证明机制,都将预配信息添加到 IoT Edge 设备上的 IoT Edge 配置文件中。Regardless of which attestation mechanism you choose, the provisioning information is added to the IoT Edge configuration file on your IoT Edge device.

打开配置文件。Open the configuration file.

sudo nano /etc/iotedge/config.yaml

找到文件的预配配置,并取消注释适用于你的证明机制的部分。Find the provisioning configurations of the file and uncomment the section appropriate for your attestation mechanism. 请确保注释掉任何其他预配部分。provisioning: 行前面应该没有空格,并且嵌套项应该缩进两个空格。Make sure any other provisioning sections are commented out. The provisioning: line should have no preceding whitespace, and nested items should be indented by two spaces. 使用 IoT 中心设备预配服务实例中的值更新 scope_id 的值,并为证明字段提供适当的值。Update the value of scope_id with the value from your IoT Hub Device Provisioning Service instance, and provide the appropriate values for the attestation fields.

TPM 证明:TPM attestation:

# DPS TPM provisioning configuration
provisioning:
  source: "dps"
  global_endpoint: "https://global.azure-devices-provisioning.cn"
  scope_id: "<SCOPE_ID>"
  attestation:
    method: "tpm"
    registration_id: "<REGISTRATION_ID>"

X.509 证明:X.509 attestation:

# DPS X.509 provisioning configuration
provisioning:
  source: "dps"
  global_endpoint: "https://global.azure-devices-provisioning.cn"
  scope_id: "<SCOPE_ID>"
  attestation:
    method: "x509"
#   registration_id: "<OPTIONAL REGISTRATION ID. LEAVE COMMENTED OUT TO REGISTER WITH CN OF identity_cert>"
    identity_cert: "<REQUIRED URI TO DEVICE IDENTITY CERTIFICATE>"
    identity_pk: "<REQUIRED URI TO DEVICE IDENTITY PRIVATE KEY>"

对称密钥证明:Symmetric key attestation:

# DPS symmetric key provisioning configuration
provisioning:
  source: "dps"
  global_endpoint: "https://global.azure-devices-provisioning.cn"
  scope_id: "<SCOPE_ID>"
  attestation:
    method: "symmetric_key"
    registration_id: "<REGISTRATION_ID>"
    symmetric_key: "<SYMMETRIC_KEY>"

将剪贴板内容粘贴到 Nano Shift+Right Click 或按 Shift+InsertTo paste clipboard contents into Nano Shift+Right Click or press Shift+Insert.

保存并关闭该文件。Save and close the file. CTRL + X, Y, EnterCTRL + X, Y, Enter

在配置文件中输入预配信息后,重启守护程序:After entering the provisioning information in the configuration file, restart the daemon:

sudo systemctl restart iotedge

验证是否成功安装Verify successful installation

如果使用了上一部分中的手动配置步骤,则应在设备上成功预配并运行 IoT Edge 运行时。If you used the manual configuration steps in the previous section, the IoT Edge runtime should be successfully provisioned and running on your device. 如果使用了自动配置步骤,则需要完成一些额外的步骤,以便运行时可以代表你向 IoT 中心注册你的设备。If you used the automatic configuration steps, then you need to complete some additional steps so that the runtime can register your device with your IoT hub on your behalf. 有关后续步骤,请参阅在 Linux 虚拟机上创建和预配模拟 TPM IoT Edge 设备For next steps, see Create and provision a simulated TPM IoT Edge device on a Linux virtual machine.

可以检查 IoT Edge 守护程序的状态:You can check the status of the IoT Edge Daemon:

systemctl status iotedge

检查守护程序日志:Examine daemon logs:

journalctl -u iotedge --no-pager --no-full

运行排故障除工具检查最常见的配置和网络错误:Run the troubleshooting tool to check for the most common configuration and networking errors:

sudo iotedge check

在将第一个模块部署到设备上的 IoT Edge 之前, $edgeHub 系统模块不会部署到设备。Until you deploy your first module to IoT Edge on your device, the $edgeHub system module will not be deployed to the device. 因此,自动检查会返回一个针对 Edge Hub can bind to ports on host 连接性检查的错误。As a result, the automated check will return an error for the Edge Hub can bind to ports on host connectivity check. 此错误可以忽略,除非它是在将模块部署到设备后发生的。This error can be ignored unless it occurs after deploying a module to the device.

最后,列出正在运行的模块:Finally, list running modules:

sudo iotedge list

在设备上安装 IoT Edge 后,可以看到其正在运行的唯一模块应该是 edgeAgentAfter installing IoT Edge on your device, the only module you should see running is edgeAgent. 创建第一个部署以后,另一个系统模块 ( $edgeHub) 也会在设备上启动。Once you create your first deployment, the other system module $edgeHub will start on the device as well. 有关详细信息,请参阅部署 IoT Edge 模块For more information, see deploy IoT Edge modules.

提示和故障排除Tips and troubleshooting

需要提升权限才能运行 iotedge 命令。You need elevated privileges to run iotedge commands. 安装运行时后,请从计算机中注销并重新登录以自动更新权限。After installing the runtime, sign out of your machine and sign back in to update your permissions automatically. 在此之前,在任何 iotedge 命令前都要使用 sudoUntil then, use sudo in front of any iotedge the commands.

在资源受限的设备上,强烈建议按照故障排除指南中的说明将 OptimizeForPerformance 环境变量设置为 falseOn resource constrained devices, it is highly recommended that you set the OptimizeForPerformance environment variable to false as per instructions in the troubleshooting guide.

如果设备无法连接到 IoT 中心且网络具有代理服务器,请按照配置 IoT Edge 设备以通过代理服务器进行通信中的步骤进行操作。If your device can't connect to IoT Hub and your network has a proxy server, follow the steps in Configure your IoT Edge device to communicate through a proxy server.

验证 Linux 内核的 Moby 兼容性Verify your Linux kernel for Moby compatibility

许多嵌入式设备制造商寄送的设备映像包含的自定义 Linux 内核没有确保容器运行时兼容所需的功能。Many embedded device manufacturers ship device images that contain custom Linux kernels without the features required for container runtime compatibility. 如果在安装建议的 Moby 容器运行时时遇到问题,则可使用官方 Moby Github 存储库中的 check-config 脚本排查 Linux 内核配置问题。If you encounter issues while installing the recommended Moby container runtime, you may be able to troubleshoot your Linux kernel configuration using the check-config script from the official Moby GitHub repository. 在设备上运行以下命令,检查内核配置:Run the following commands on the device 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

此命令提供一个详细的输出,其中包含 Moby 运行时使用的内核功能的状态。This command provides a detailed output that contains the status of kernel features that are used by the Moby runtime. 需确保启用 Generally NecessaryNetwork Drivers 下的所有项,这样才能确保内核完全兼容 Moby 运行时。You will want to ensure that all items under Generally Necessary and Network Drivers are enabled to ensure that your kernel is fully compatible with the Moby runtime. 如果确定有缺失的功能,请启用它们,方法是:通过源重新构建内核,然后选择关联的模块,将其包括在相应的内核 .config 中。同样,如果使用内核配置生成器(例如 defconfigmenuconfig),请找到并启用相应的功能,然后以相应方式重新构建内核。If you have identified any 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. 部署新修改的内核以后,请再次运行 check-config 脚本,验证是否已成功启用所有必需功能。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 runtime using release assets

如果想要安装特定版本的无法通过 apt-get install 获取的 Azure IoT Edge 运行时,请使用本部分中的步骤。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. Microsoft 包列表仅包含有限的一组最新版本及其子版本,因此,这些步骤适用于想要安装较旧版本或候选发布版本的任何用户。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.

使用 curl 命令,可以直接从 IoT Edge GitHub 存储库将组件文件作为目标。Using curl commands, you can target the component files directly from the IoT Edge GitHub repository. 使用以下步骤安装 libiothsm 和 IoT Edge 安全守护程序。Use the following steps to install libiothsm and the IoT Edge security daemon.

  1. 准备好安装了容器引擎的设备。Have your device prepared with a container engine installed. 如果没有容器引擎,请按照本文的安装容器运行时和 IoT Edge 部分中的步骤注册 Microsoft 存储库并安装 Moby。If you don't have a container engine, follow the steps to register the Microsoft repository and install Moby in the Install container runtime and IoT Edge section of this article.

  2. 导航到 Azure IoT Edge 版本,找到需要将其作为目标的发行版。Navigate to the Azure IoT Edge releases, and find the release version that you want to target.

  3. 展开该版本的“资产”部分。Expand the Assets section for that version.

  4. 每个版本应该都有用于 IoT Edge 安全守护程序和 hsmlib 的新文件。Every release should have new files for the IoT Edge security daemon and the hsmlib. 使用以下命令更新这些组件。Use the following commands to update those components.

    1. 找到与 IoT Edge 设备的体系结构匹配的 libiothsm-std 文件。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. 将复制的链接用在以下命令中,安装该版本的 hsmlib: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. 找到与 IoT Edge 设备的体系结构匹配的 iotedge 文件。Find the iotedge file that matches your IoT Edge device's architecture. 右键单击文件链接并复制链接地址。Right-click on the file link and copy the link address.

    4. 将复制的链接用在以下命令中,安装该版本的 IoT Edge 安全守护程序: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
      

IoT Edge 在 /etc/iotedge 成功安装以后,输出会提示你更新配置文件。Once IoT Edge is successfully installed at /etc/iotedge, the output prompts you to update the configuration file. 执行配置安全守护程序部分的步骤,完成设备预配。Follow the steps in the Configure the security daemon section to complete device provisioning.

卸载 IoT EdgeUninstall IoT Edge

如果要从 Linux 设备中删除 IoT Edge 安装,请从命令行使用以下命令。If you want to remove the IoT Edge installation from your Linux device, use the following commands from the command line.

删除 IoT Edge 运行时。Remove the IoT Edge runtime.

sudo apt-get remove --purge iotedge

删除 IoT Edge 运行时以后,已创建的容器会被停止,但仍存在于设备上。When the IoT Edge runtime is removed, the 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

预配了安装运行时的 IoT Edge 设备后,现在可以部署 IoT Edge 模块Now that you have an IoT Edge device provisioned with the runtime installed, you can deploy IoT Edge modules.

如果无法正确安装 IoT Edge 运行时,请参阅故障排除页。If you are having problems with the IoT Edge runtime installing properly, check out the troubleshooting page.

若要将现有安装更新到最新版本的 IoT Edge,请参阅更新 IoT Edge 安全守护程序和运行时To update an existing installation to the newest version of IoT Edge, see Update the IoT Edge security daemon and runtime.