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

  • 發行項

適用於：IoT Edge 1.4 checkmark IoT Edge 1.4

重要

支援的版本是 IoT Edge 1.4。 如果您是舊版，請參閱更新 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 會發佈各種操作系統的安裝套件。

如需生產案例目前支援哪些操作系統的最新資訊，請參閱 Azure IoT Edge 支援的系統。

產生裝置身分識別憑證

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

當您使用 X.509 憑證布建 IoT Edge 裝置時，您可以使用所謂的 裝置身分識別憑證。 此憑證僅用於布建IoT Edge裝置，並使用 Azure IoT 中樞驗證裝置。 它是未簽署其他憑證的分葉憑證。 裝置身分識別憑證與IoT Edge裝置向模組或下游裝置呈現以進行驗證的證書頒發機構單位 （CA） 憑證不同。

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

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

您需要下列檔案，才能使用 X.509 手動布建：

  • 兩個裝置身分識別憑證及其相符的私鑰憑證，格式為 .cer 或 .pem 格式。 您需要兩個裝置身分識別憑證來進行憑證輪替。 最佳做法是準備兩個不同的裝置身分識別憑證，其到期日不同。 如果一個憑證過期，另一個憑證仍然有效，並讓您有時間輪替過期的憑證。

    一組憑證和金鑰檔案會提供給 IoT Edge 執行時間。 當您建立裝置身分識別憑證時，請使用您希望裝置在IoT中樞擁有的裝置識別碼來設定憑證通用名稱 （CN）。

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

    指紋值是 SHA-1 哈希的 40-hex 字元，SHA-256 哈希為 64-hex 字元。 這兩個指紋都會提供給裝置註冊時 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-hex 字元，SHA-256 哈希為 64-hex 字元。 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 中樞的邊緣裝置會列在 [裝置 ] 頁面上。 您可以依裝置類型 IoT Edge 裝置來篩選清單。

安裝IoT Edge

在本節中，您會準備適用於IoT Edge的Linux虛擬機或實體裝置。 然後，您會安裝IoT Edge。

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

重要

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

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

  • 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 執行階段相容。

安裝 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 for Device Builder。

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

既然容器引擎和 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、 、 YEnter

在組態檔中輸入布建信息之後，請套用您的變更：

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

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

Screenshot of sample responses from the check command.

提示

一律使用 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 嵌入式管理單元，您可以下載貼齊並將其離線安裝。 如需詳細資訊，請參閱 下載快照集並離線安裝。

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

注意

如果您的裝置目前執行 IoT Edge 1.1 版或更新版本，請先卸載 iotedge 和 libiothsm-std 套件，再遵循本節中的步驟。 如需詳細資訊，請參閱 從1.0或1.1更新至最新版本。

  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