共用方式為

使用 x.509 憑證在 Linux 上建立和佈建 IoT Edge 裝置

  • 發行項

適用於： IoT Edge 1.5 核取記號 IoT Edge 1.5 IoT Edge 1.4 核取記號 IoT Edge 1.4

重要

IoT Edge 1.5 LTS 和 IoT Edge 1.4 LTS 為支援的版本。 IoT Edge 1.4 LTS 於 2024 年 11 月 12 日結束生命週期。 如果您是舊版，請參閱更新 IoT Edge。

本文提供註冊及佈建 Linux IoT Edge 裝置 (包括安裝 IoT Edge) 的端對端指示。

連線到 IoT 中樞的每個裝置都有裝置識別碼，可用來追蹤雲端到裝置或裝置到雲端的通訊。 您可以使用連線資訊來設定裝置，其中包括 IoT 中樞主機名稱、裝置識別碼，以及裝置用來向 IoT 中樞驗證的資訊。

本文中的步驟會帶您完成稱為「手動佈建」的程序，您會在此程序中將單一裝置連線到其 IoT 中樞。 針對手動佈建，您有兩個選項可用來驗證 IoT Edge 裝置：

  • 對稱金鑰：當您在 IoT 中樞中建立新的裝置身分識別時，服務會建立兩個金鑰。 您會在裝置上放置其中一個金鑰，並在驗證時呈現 IoT 中樞的金鑰。

    這個驗證方法上手較為快速，但並非是安全的方法。

  • X.509 自我簽署：您可以建立兩個 X.509 身分識別憑證，並將其置於裝置上。 當您在 IoT 中樞中建立新的裝置身分識別時，您會從這兩個憑證提供指紋。 當裝置向 IoT 中樞進行驗證時，其會顯示一個憑證，而 IoT 中樞會確認憑證符合其指紋。

    此驗證方法較安全，建議用於生產案例。

本文說明如何使用 X.509 憑證做為驗證方法。 如果您想要使用對稱金鑰，請參閱使用對稱金鑰在 Linux 上建立和佈建 IoT Edge 裝置。

注意

如果您有許多裝置可設定，且不想手動佈建每個裝置，請使用下列其中一篇文章來了解 IoT Edge 如何與 IoT 中樞裝置佈建服務搭配運作：

必要條件

本文說明如何註冊 IoT Edge 裝置及在裝置上安裝 IoT Edge。 完成這些工作有不同的必要條件和公用程式。 在繼續之前，請先確定您已準備好所有必要條件。

裝置管理工具

您可以使用 Azure 入口網站、Visual Studio Code 或 Azure CLI 來完成註冊裝置的步驟。 每個公用程式都有自己的必要條件，或可能需要安裝：

Azure 訂閱的免費或標準 IoT 中樞。

裝置需求

X64、ARM32 或 ARM64 Linux 裝置。

Microsoft 發佈各種作業系統的安裝套件。

如需生產情境下，何種 Windows 作業系統可供使用的相關資訊，請參閱 Azure IoT Edge 支援系統。

產生裝置身分識別憑證

使用 X.509 憑證進行手動佈建需要 IoT Edge 1.0.10 版或更新版本。

當您使用 X.509 憑證佈建 IoT Edge 裝置時，您會使用所謂的「裝置身分識別憑證」。 此憑證只能用於佈建 IoT Edge 裝置，以及向 Azure IoT 中樞驗證裝置。 此為不會簽署其他憑證的分葉節點。 裝置身分識別憑證與憑證授權單位 (CA) 憑證不同，IoT Edge 裝置會提供給模組或下游裝置進行驗證。

針對 X.509 憑證驗證，系統會以取自裝置身分識別憑證的指紋形式，提供每個裝置的驗證資訊。 這些指紋會在裝置註冊時提供給 IoT 中樞，使服務在裝置連線時可以辨識裝置。

如需如何在 IoT Edge 裝置中使用 CA 憑證的詳細資訊，請參閱了解 Azure IoT Edge 如何使用憑證。

若要使用 X.509 手動佈建，您需要下列檔案：

  • 兩個裝置身分識別憑證，具有 .cer 或 .pem 格式的相符私密金鑰憑證。 您需要兩個裝置身分識別憑證來進行憑證輪替。 最佳做法是備妥兩種不同的裝置身分識別憑證，且二者的到期日相異。 如果一個憑證到期，另一個仍有效，您就有時間輪替到期的憑證。

    其中一組憑證和金鑰檔案會提供給 IoT Edge 執行階段。 當您建立裝置身分識別憑證時，請將憑證一般名稱 (CN) 設為您希望裝置在 IoT 中樞擁有的裝置識別碼。

  • 取自這兩個裝置身分識別憑證的指紋。 註冊 IoT Edge 裝置時，IoT 中樞需要兩種指紋。 您只能使用一個憑證進行註冊。 若要使用單一憑證，請在註冊裝置時，為主要和次要指紋設定相同的憑證指紋。

    指紋值為 SHA-1 雜湊的 40 十六進位字元，或 SHA-256 雜湊的 64 十六進位字元。 在裝置註冊時，這兩個指紋都會提供給 IoT 中樞。

    從憑證擷取指紋的其中一種方式是使用下列 openssl 命令：

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

    指紋包含在此命令的輸出中。 例如：

    SHA1 Fingerprint=D2:68:D9:04:9F:1A:4D:6A:FD:84:77:68:7B:C6:33:C0:32:37:51:12

如果沒有憑證可以使用，則可建立示範憑證來測試 IoT Edge 裝置功能。 請遵循該文章中的指示來設定憑證建立指令碼、建立根 CA 憑證，以及建立 IoT Edge 裝置身分識別憑證。 若要進行測試，在 IoT 中樞註冊裝置時，您可以為主要和次要指紋值建立單一裝置身分識別憑證，並使用相同的指紋。

登記裝置

您可以根據喜好，使用 Azure 入口網站、Visual Studio Code 或Azure CLI來註冊裝置。

在 Azure 入口網站的 IoT 中樞中，IoT Edge 裝置與未啟用邊緣的 IoT 裝置是分開建立及管理的。

  1. 登入 Azure 入口網站，然後瀏覽至 IoT 中樞。

  2. 在左側窗格中，從功能表中選取 [裝置]，然後選取 [新增裝置]。

  3. 在 [建立裝置] 頁面上，提供下列資訊：

    • 建立描述性裝置識別碼。 記下此裝置識別碼，因為您稍後會用到。
    • 核取 [IoT Edge 裝置] 核取方塊。
    • 選取 [X.509 自我簽署] 作為 [驗證類型]。
    • 提供主要和次要身分識別憑證指紋。 指紋值為 SHA-1 雜湊的 40 十六進位字元，或 SHA-256 雜湊的 64 十六進位字元。 Azure 入口網站僅支援十六進位值。 在入口網站中輸入指紋之前，請先從指紋值中移除資料行分隔符號和空格。 例如，若為 D2:68:D9:04:9F:1A:4D:6A:FD:84:77:68:7B:C6:33:C0:32:37:51:12，請輸入 D268D9049F1A4D6AFD8477687BC633C032375112。

    提示

    如果您要測試並使用一個憑證，可以針對主要和次要指紋使用相同的憑證。

  4. 選取 [儲存]。

現在您已在 IoT 中樞內註冊裝置，接著請擷取用來完成安裝及佈建 IoT Edge 執行階段的資訊。

檢視已註冊的裝置並擷取佈建資訊

使用 X.509 憑證驗證的裝置需要其 IoT 中樞名稱、其裝置名稱和其憑證檔案，才能完成 IoT Edge 執行階段的安裝及佈建。

連線至 IoT 中樞且已啟用 Edge 的裝置都列於 [裝置] 頁面。 您可以依「IoT Edge 裝置」裝置類型篩選清單。

安裝 IoT Edge

在本節中，您將為 IoT Edge 準備 Linux 虛擬機器或實體裝置。 然後，您會安裝 IoT Edge。

執行下列命令以新增套件存放庫，然後將 Microsoft 套件簽署金鑰新增至信任金鑰的清單。

重要

在 2022 年 6 月 30 日，已從第 1 層作業系統支援清單中淘汰 Raspberry Pi OS Stretch。 若要避免潛在的安全性弱點，請將主機作業系統更新為 Bullseye。

對於第 2 層支援的平台作業系統，Azure IoT Edge 版本會提供安裝套件。 請參閱離線或特定版本安裝中的安裝步驟。

您可以使用幾個命令來完成安裝。 開啟終端機，然後執行下列命令：

  • 24.04：

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

  • 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

如需作業系統版本的詳細資訊，請參閱 Azure IoT Edge 支援的平台。

注意

使用 Azure IoT Edge 軟體套件時，必須遵守每個封裝中的授權條款 (usr/share/doc/{package-name} 或 LICENSE 目錄)。 在使用套件之前，請先閱讀授權條款。 安裝及使用套件即表示接受這些授權條款。 如果您不同意授權條款，請勿使用該套件。

安裝容器引擎

Azure IoT Edge 會依賴 OCI 相容的容器執行階段。 針對實際執行案例，建議使用 Moby 引擎。 Moby 引擎是 IoT Edge 正式支援的唯一容器引擎。 Docker CE/EE 容器映像與 Moby 執行階段相容。 如果您使用 Ubuntu Core Snap，則 Docker Span 由 Canonical 提供服務，並支援生產案例。

安裝 Moby 引擎。

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

依預設，容器引擎不會設定容器記錄大小限制。 經過一段時間之後，這可能會導致裝置充滿記錄，並用盡磁碟空間。 不過，您可以將記錄設定為在本機顯示，但這是選擇性的。 若要深入了解記錄設定，請參閱生產部署檢查清單。

下列步驟示範如何將容器設定為使用 local 記錄驅動程式作為記錄機制。

  1. 建立或編輯現有 Docker 精靈的組態檔

    sudo nano /etc/docker/daemon.json

  2. 將預設記錄驅動程式設定為 local 記錄驅動程式，如範例所示。

       {
      "log-driver": "local"
   }

  3. 重新啟動容器引擎，讓變更生效。

    sudo systemctl restart docker

安裝 IoT Edge 執行階段

IoT Edge 服務提供及維護 IoT Edge 裝置的安全性標準。 此服務會在每次開機時啟動，並藉由啟動 IoT Edge 執行階段讓裝置進入啟動程序。

注意

從 1.2 版開始，IoT 識別服務會處理 IoT Edge 以及需要與 IoT 中樞通訊的其他裝置元件的身分識別佈建和管理。

本節中的步驟代表在具有網際網路連線的裝置上安裝最新 IoT Edge 版本的一般程序。 如果您需要安裝特定版本，例如發行前版本，或需要在離線時安裝，請遵循本文稍後的離線或特定版本安裝步驟。

提示

如果您已經有執行舊版且想要升級至最新版本的 IoT Edge 裝置，請使用更新 IoT Edge 安全性精靈和執行階段中的步驟。 較新版本與舊版 IoT Edge 有明顯的不同，因此升級時需要特定步驟。

安裝最新版本的 IoT Edge 和 IoT 識別服務套件 (如果您尚未擁有最新版本)：

  • 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

選用的 defender-iot-micro-agent-edge 套件包含適用於 IoT 的 Microsoft Defender 安全性微代理程式，可讓端點了解安全性態勢管理、弱點、威脅偵測、機群管理等等，以協助您保護您的 IoT Edge 裝置。 建議您使用 Edge 代理程式安裝微代理程式，以啟用 Edge 裝置的安全性監視和強化。 若要深入了解適用於 IoT 的 Microsoft Defender，請參閱對於裝置建置者而言，什麼是適用於 IoT 的 Microsoft Defender。

使用雲端身分識別來佈建裝置

現在，容器引擎和 IoT Edge 執行階段已安裝在您的裝置上，您已準備好使用裝置的雲端身分識別和驗證資訊來設定裝置。

  1. 根據作為安裝 IoT Edge 期間提供的範本檔案，為您的裝置建立組態檔。

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

  2. 在 IoT Edge 裝置上，開啟設定檔。

    sudo nano /etc/aziot/config.toml

  3. 尋找檔案的 [佈建] 區段，並取消使用 X.509 身分識別憑證手動佈建的註解行。 請確定已經標註任何其他佈建區段。

    # 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"

更新下列欄位：

  • iothub_hostname：裝置將連線的 IoT 中樞主機名稱。 例如： {IoT hub name}.azure-devices.net 。
  • device_id：您在註冊裝置時提供的識別碼。
  • identity_cert：裝置上身分識別憑證的 URI，例如：file:///path/identity_certificate.pem。 或者，使用 EST 或本機憑證授權單位單位動態來發行憑證。
  • identity_pk：所提供身分識別憑證私密金鑰檔案的 URI，例如：file:///path/identity_key.pem。 或者，提供 PKCS#11 URI，然後將您的組態資訊提供至

設定檔稍後的 [PKCS#11] 區段。

如需關於憑證的詳細資訊，請參閱管理 IoT Edge 憑證。

儲存並關閉檔案。

CTRL + X、Y、Enter

在組態檔中輸入佈建資訊之後，請套用您的變更：

sudo iotedge config apply

部署模組

若要部署 IoT Edge 模組，請移至 Azure 入口網站中的 IoT 中樞，然後：

  1. 在 [IoT 中樞] 功能表中選取 [裝置]。

  2. 選取您的裝置以開啟其頁面。

  3. 選取 [設定模組] 索引標籤。

  4. 由於我們想要部署 IoT Edge 預設模組 (edgeAgent 和 edgeHub)，所以我們不需要將任何模組新增至此窗格，請選取底部的 [檢閱 + 建立]。

  5. 您會看到模組的 JSON 確認訊息。 選取 [建立] 以部署模組。<

如需詳細資訊，請參閱部署模組。

確認設定成功

確認您的 IoT Edge 裝置上已成功安裝並設定執行階段。

提示

您需要有較高的權限才能執行 iotedge 命令。 當您在安裝 IoT Edge 執行階段之後登出機器，並第一次重新登入時，您的權限將會自動更新。 在那之前，請在這些命令前面使用 sudo。

確認 IoT Edge 系統服務正在執行。

sudo iotedge system status

成功的狀態回應為 Ok。

如果您需要對服務進行疑難排解，請擷取服務記錄。

sudo iotedge system logs

使用 check 工具來驗證裝置的設定和連線狀態。

sudo iotedge check

您可以預期會有一系列回應，包括「正常」(綠色)、「警告」(黃色)，或「錯誤」(紅色)。 如需針對常見錯誤進行疑難排解，請參閱 Azure IoT Edge 常見問題的解決方案。

來自 check 命令的範例回應螢幕擷取畫面。

提示

一律使用 sudo 來執行檢查工具，即使您的權限更新也一樣。 此工具需要較高的權限，才能存取組態檔，以確認組態狀態。

注意

在新佈建的裝置上，您可能會看到與 IoT Edge 中樞相關的錯誤：

× 實際執行整備程度：Edge Hub 的儲存體目錄會保存在主機檔案系統上 - 錯誤

無法檢查 edgeHub 容器的目前狀態

新佈建的裝置上預期會發生此錯誤，因為 IoT Edge 中樞模組未在執行中。 若要解決錯誤，請在 IoT 中樞內設定裝置的模組並建立部署。 建立裝置的部署會啟動裝置上的模組，包括 IoT Edge 中樞模組。

檢視在 IoT Edge 裝置上執行的所有模組。 當服務啟動時，您應該只會看到 edgeAgent 模組正在執行。 edgeAgent 模組預設會執行，且有助於安裝及啟動部署至裝置的任何其他模組。

sudo iotedge list

當您建立新的 IoT Edge 裝置時，其會在 Azure 入口網站中顯示狀態碼 417 -- The device's deployment configuration is not set。 此狀態為正常，表示裝置已就緒可接收模組部署。

離線或特定版本安裝 (選擇性)

本節中的步驟適用於標準安裝步驟未涵蓋的情況。 可能包括：

  • 離線時安裝 IoT Edge
  • 安裝候選版

如果您想要安裝的特定 Azure IoT Edge 執行階段版本無法透過套件管理員取得，請使用本節中的步驟。 Microsoft 套件清單只包含一組有限的最新版本及其子版本，因此這些步驟適用於想要安裝較舊版本或候選版本的任何人員。

如果您使用 Ubuntu Snap，則可以下載 Snap 並將其離線安裝。 如需詳細資訊，請參閱下載 Snap 並離線安裝。

您可以使用 curl 命令，直接從 IoT Edge GitHub 存放庫將元件檔案設為目標。

  1. 瀏覽至 Azure IoT Edge 版本，並尋找您想要設為目標的版本。

  2. 展開該版本的 [資產] 區段。

  3. 每個版本都應該有適用於 IoT Edge 和識別服務的新檔案。 如果您要在離線裝置上安裝 IoT Edge，請事先下載這些檔案。 否則，請使用下列命令來更新這些元件。

    1. 尋找符合您 IoT Edge 裝置架構的 aziot-identity-service 檔案。 以滑鼠右鍵按一下檔案連結，並複製連結位址。

    2. 使用下列命令中的複製連結來安裝該版本的識別服務：

      curl -L <identity service link> -o aziot-identity-service.deb && sudo apt-get install ./aziot-identity-service.deb

    1. 尋找符合您 IoT Edge 裝置架構的 aziot-edge 檔案。 以滑鼠右鍵按一下檔案連結，並複製連結位址。

    2. 使用下列命令中的複製連結來安裝該版本的 IoT Edge。

      curl -L <iotedge link> -o aziot-edge.deb && sudo apt-get install ./aziot-edge.deb

解除安裝 IoT Edge

如果您想要從裝置移除 IoT Edge 安裝，請使用下列命令。

移除 IoT Edge 執行階段。

sudo apt-get autoremove --purge aziot-edge

如果您打算重新安裝 IoT Edge，並在未來使用相同的組態資訊，請省略 --purge 旗標。 --purge 旗標會刪除與 IoT Edge 相關聯的所有檔案，包括您的組態檔。

IoT Edge 執行階段移除後，其所建立的任何容器隨即停止，但仍會存在於您的裝置上。 檢視所有容器以查看哪些容器保留下來。

sudo docker ps -a

刪除您裝置中的容器，包括兩個執行階段容器。

sudo docker rm -f <container name>

最後，移除裝置中的容器執行階段。

sudo apt-get autoremove --purge moby-engine