設定 IoT Edge 裝置設定

文章
07/17/2024

適用於： IoT Edge 1.5 IoT Edge 1.4

重要

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

本文說明用於設定 IoT Edge 裝置 IoT Edge /etc/aziot/config.toml 檔案的設定和選項。 IoT Edge 會使用 config.toml 檔案來初始化裝置設定。 config.toml 檔案的每個區段都有數個選項。其並非全是必要選項，因為這些選項適用於特定案例。

您可以在 IoT Edge 裝置上 /etc/aziot 目錄內的 config.toml.edge.template 檔案中找到包含所有選項的範本。您可以將整個範本或範本區段的內容複製到 config.toml 檔案中。將您需要的區段取消註解。請注意不要複製您已定義的參數。

如果您變更裝置的設定，請使用 sudo iotedge config apply 來套用變更。

全域參數

hostname、parent_hostname、trust_bundle_cert、allow_elevated_docker_permissions 和 auto_reprovisioning_mode 參數必須位於設定檔開頭處任何其他區段之前。在設定集合的前面新增參數可確保其會正確套用。如需有效語法的詳細資訊，請參閱 toml.io (英文)。

主機名稱

若要啟用閘道探索，每個 IoT Edge 閘道 (父) 裝置都必須指定其子裝置用來在區域網路上找到它的 hostname 參數。 edgeHub 模組也會使用 hostname 參數來與其伺服器憑證相匹配。如需詳細資訊，請參閱為什麼 EdgeGateway 需要得知自己的主機名稱？(部分機器翻譯)。

注意

未設定主機名稱值時，IoT Edge 會自動嘗試尋找該值。不過，如果未設定該值，網路中的用戶端可能無法探索該裝置。

針對 hostname，請將 fqdn-device-name-or-ip-address 取代為您的裝置名稱，以覆寫裝置的預設主機名稱。該值可以是完整網域名稱 (FQDN) 或 IP 位址。請使用此設定作為 IoT Edge 閘道裝置上的閘道主機名稱。

hostname = "fqdn-device-name-or-ip-address"

父主機名稱

當 IoT Edge 裝置是階層的一部分時，會使用父主機名稱，否則會稱為巢狀邊緣。每個下游 IoT Edge 裝置都必須指定 parent_hostname 參數來識別其父代。在單一 IoT Edge 裝置同時為父裝置和子裝置的階層式案例中，其需要這兩個參數。

將 fqdn-parent-device-name-or-ip-address 取代為父裝置的名稱。使用少於 64 個字元的主機名稱，這是伺服器憑證通用名稱的字元限制。

parent_hostname = "fqdn-parent-device-name-or-ip-address"

如需如何設定 parent_hostname 參數的詳細資訊，請參閱將 Azure IoT Edge 裝置連接在一起以建立階層 (部分機器翻譯)。

信任套件組合憑證

若要提供自訂憑證授權單位 (CA) 憑證來作為 IoT Edge 和模組的信任根源，請指定 trust_bundle_cert 設定。將參數值取代為裝置上根 CA 憑證的檔案 URI。

trust_bundle_cert = "file:///var/aziot/certs/trust-bundle.pem"

如需 IoT Edge 信任套件組合的詳細資訊，請參閱管理受信任的根 CA (部分機器翻譯)。

較高的 Docker 權限

某些 Docker 功能可用來取得根存取權。根據預設，系統會允許 docker HostConfig 的 CapAdd 參數中列出的 --privileged 旗標和所有功能。

如果沒有模組需要特殊權限功能或額外功能，請使用 allow_elevated_docker_permissions 來改善裝置的安全性。

allow_elevated_docker_permissions = false

自動重新佈建模式

選擇性的 auto_reprovisioning_mode 參數會指定條件，以決定裝置何時要嘗試使用裝置佈建服務來自動重新佈建。如果裝置已透過手動方式佈建，則會忽略自動佈建模式。如需如何設定 DPS 佈建模式的詳細資訊，請參閱本文中的佈建一節以取得詳細資訊。

您可以設定下列其中一個值：

[模式]	描述
動態	當裝置偵測到自身可能已從某個 IoT 中樞移至另一個 IoT 中樞時，便重新佈建。此為「預設」模式。
AlwaysOnStartup	裝置重新開機或因為當機而導致精靈重新啟動時，便重新佈建。
OnErrorOnly	永遠不會自動觸發裝置重新佈建。只有在裝置因為連線錯誤而無法在身分識別佈建期間連線至 IoT 中樞，才會重新佈建裝以作為後援。 Dynamic 和 AlwaysOnStartup 模式中也隱含此後援行為。

例如：

auto_reprovisioning_mode = "Dynamic"

如需裝置重新佈建的詳細資訊，請參閱 IoT 中樞裝置重新佈建概念 (部分機器翻譯)。

佈建

您可以根據 IoT Edge 解決方案的需求，大規模佈建單一或多個裝置。可用來驗證 IoT Edge 裝置與 IoT 中樞之間通訊之選項，取決於您所選擇的佈建方法。

您可以使用連接字串、對稱金鑰、X.509 憑證、身分識別憑證私密金鑰或身分識別憑證進行佈建。各種選項皆隨附 DPS 佈建。請為您的佈建選擇某個方法。將範例值取代為您自己的值。

使用連接字串進行手動佈建

[provisioning]
source = "manual"
connection_string = "HostName=example.azure-devices.net;DeviceId=my-device;SharedAccessKey=<Shared access key>"

如需如何擷取佈建資訊的詳細資訊，請參閱使用對稱金鑰在 Linux 上建立及佈建 IoT Edge 裝置 (部分機器翻譯)。

使用對稱金鑰進行手動佈建

[provisioning]
source = "manual"
iothub_hostname = "example.azure-devices.net"
device_id = "my-device"

[provisioning.authentication]
method = "sas"

device_id_pk = { value = "<Shared access key>" }     # inline key (base64), or...
device_id_pk = { uri = "file:///var/aziot/secrets/device-id.key" }            # file URI, or...
device_id_pk = { uri = "pkcs11:slot-id=0;object=device%20id?pin-value=1234" } # PKCS#11 URI

如需如何擷取佈建資訊的詳細資訊，請參閱使用對稱金鑰在 Linux 上建立及佈建 IoT Edge 裝置 (部分機器翻譯)。

使用 X.509 憑證進行手動佈建

[provisioning]
source = "manual"
iothub_hostname = "example.azure-devices.net"
device_id = "my-device"

[provisioning.authentication]
method = "x509"

如需使用 X.509 憑證來進行佈建的詳細資訊，請參閱使用 x.509 憑證在 Linux 上建立和佈建 IoT Edge 裝置 (部分機器翻譯)。

使用對稱金鑰進行 DPS 佈建

[provisioning]
source = "dps"
global_endpoint = "https://global.azure-devices-provisioning.net"
id_scope = "<DPS-ID-SCOPE>"

# (Optional) Use to send a custom payload during DPS registration
payload = { uri = "file:///var/secrets/aziot/identityd/dps-additional-data.json" }

[provisioning.attestation]
method = "symmetric_key"
registration_id = "my-device"

symmetric_key = { value = "<Device symmetric key>" } # inline key (base64), or...
symmetric_key = { uri = "file:///var/aziot/secrets/device-id.key" }                                                          # file URI, or...
symmetric_key = { uri = "pkcs11:slot-id=0;object=device%20id?pin-value=1234" }

如需使用對稱金鑰進行 DPS 佈建的詳細資訊，請參閱使用對稱金鑰在 Linux 上大規模建立和佈建 IoT Edge 裝置 (部分機器翻譯)。

使用 X.509 憑證進行 DPS 佈建

[provisioning]
source = "dps"
global_endpoint = "https://global.azure-devices-provisioning.net/"
id_scope = "<DPS-ID-SCOPE>"

# (Optional) Use to send a custom payload during DPS registration
 payload = { uri = "file:///var/secrets/aziot/identityd/dps-additional-data.json" }

[provisioning.attestation]
method = "x509"
registration_id = "my-device"

# Identity certificate private key
identity_pk = "file:///var/aziot/secrets/device-id.key.pem"        # file URI, or...
identity_pk = "pkcs11:slot-id=0;object=device%20id?pin-value=1234" # PKCS#11 URI

# Identity certificate
identity_cert = "file:///var/aziot/certs/device-id.pem"     # file URI, or...
[provisioning.authentication.identity_cert]                 # dynamically issued via...
method = "est"                                              # - EST
method = "local_ca"                                         # - a local CA
common_name = "my-device"                                   # with the given common name, or...
subject = { L = "AQ", ST = "Antarctica", CN = "my-device" } # with the given DN fields

(選擇性) 啟用裝置身分識別憑證的自動更新

自動更新需要已知的憑證發行方法。請將「方法」設定為 est 或 local_ca。

重要

只有在此裝置設定為 CA 型 DPS 註冊時，才啟用自動更新。針對個別註冊使用自動更新會導致裝置無法重新佈建。

[provisioning.attestation.identity_cert.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"

如需使用 X.509 憑證進行 DPS 佈建的詳細資訊，請參閱使用 X.509 憑證在 Linux 上大規模地建立和佈建 IoT Edge 裝置 (部分機器翻譯)。

使用 TPM (信賴平台模組) 進行 DPS 佈建

[provisioning]
source = "dps"
global_endpoint = "https://global.azure-devices-provisioning.net"
id_scope = "<DPS-ID-SCOPE>"

# (Optional) Use to send a custom payload during DPS registration
payload = { uri = "file:///var/secrets/aziot/identityd/dps-additional-data.json" }

[provisioning.attestation]
method = "tpm"
registration_id = "my-device"

如果您使用 TPM 進行 DPS 佈建，且需要自訂設定，請參閱 TPM 一節。

如需詳細資訊，請參閱在 Linux 上使用 TPM 來大規模建立和佈建 IoT Edge 裝置 (部分機器翻譯)。

雲端逾時和重試行為

這些設定可控制雲端作業 (例如，在佈建期間使用裝置佈建服務 (DPS) 進行通訊，或使用 IoT 中樞建立模組身分識別) 的逾時和重試。

cloud_timeout_sec 參數是雲端服務網路要求的逾時期限 (以秒為單位)。例如，HTTP 要求。必須在此期限之前收到來自雲端服務的回應，否則要求會因為逾時而失敗。

cloud_retries 參數可控制第一次嘗試失敗之後，可以重試要求的次數。用戶端一律會傳送至少一次，因此這個值是第一次嘗試失敗後的重試次數。例如，cloud_retries = 2 表示用戶端總共會嘗試三次。

cloud_timeout_sec = 10
cloud_retries = 1

憑證發行

如果您已設定任何動態發行的憑證，請選擇對應的發行方法，並將範例值取代為您自己的值。

透過 EST 的憑證發行

[cert_issuance.est]
trusted_certs = ["file:///var/aziot/certs/est-id-ca.pem",]

[cert_issuance.est.auth]
username = "estuser"
password = "estpwd"

裝置上已經有 EST 身分識別憑證

identity_cert = "file:///var/aziot/certs/est-id.pem"

identity_pk = "file:///var/aziot/secrets/est-id.key.pem"      # file URI, or...
identity_pk = "pkcs11:slot-id=0;object=est-id?pin-value=1234" # PKCS#11 URI

透過 EST 啟動程序身分識別憑證所要求的 EST 身分識別憑證

會使用一次來建立初始 EST 身分識別憑證的 TLS 用戶端憑證驗證。在第一個憑證發行之後，會自動建立 identity_cert 和 identity_pk 並用於之後的驗證和更新。所產生 EST 身分識別憑證的主體通用名稱 (CN) 一律會與佈建區段下所設定的裝置身分識別相同。這些檔案必須可分別由使用者 aziotcs 和 aziotks 讀取。

bootstrap_identity_cert = "file:///var/aziot/certs/est-bootstrap-id.pem"

bootstrap_identity_pk = "file:///var/aziot/secrets/est-bootstrap-id.key.pem"      # file URI, or...
bootstrap_identity_pk = "pkcs11:slot-id=0;object=est-bootstrap-id?pin-value=1234" # PKCS#11 URI

# The following parameters control the renewal of EST identity certs. These certs are issued by the EST server after initial authentication with the bootstrap cert and managed by Certificates Service.

[cert_issuance.est.identity_auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"

[cert_issuance.est.urls]
default = "https://example.org/.well-known/est"

透過本機 CA 的憑證發行

[cert_issuance.local_ca]
cert = "file:///var/aziot/certs/local-ca.pem"

pk = "file:///var/aziot/secrets/local-ca.key.pem"      # file URI, or...
pk = "pkcs11:slot-id=0;object=local-ca?pin-value=1234" # PKCS#11 URI

TPM (信賴平台模組)

如果您在使用 DPS TPM 佈建時需要特殊的 TPM 設定，請使用這些 TPM 設定。

如需可接受的 TCTI 載入器字串，請參閱 TCG TSS 2.0 TPM 命令傳輸介面 (TCTI) API 規格 (英文) 的 3.5 節。

設定為空字串會導致 TCTI 載入器程式庫嘗試依序載入一組預先定義的 TCTI 模組 (英文)。

[tpm]
tcti = "swtpm:port=2321"

TPM 索引會保存 DPS 驗證金鑰。此索引會作為永續性物件的基底位址 (Base Address) 位移 (例如 0x81000000)，而且必須位於從 0x00_00_00 到 0x7F_FF_FF 的範圍中。預設值是 0x00_01_00。

auth_key_index = "0x00_01_00"

如有需要，請使用授權值作為簽署和擁有者階層。根據預設，這些值是空字串。

[tpm.hierarchy_authorization]
endorsement = "hello"
owner = "world"

PKCS#11

如果您使用任何 PKCS#11 URI，請使用下列參數，並將值取代為您的 PKCS#11 設定。

[aziot_keys]
pkcs11_lib_path = "/usr/lib/libmypkcs11.so"
pkcs11_base_slot = "pkcs11:slot-id=0?pin-value=1234"

預設 Edge 代理程式

當 IoT Edge 第一次啟動時，其會啟動預設的 Edge 代理程式模組。如果您需要覆寫提供給預設 Edge 代理程式模組的參數，請使用本節，並將值取代為您自己的值。

注意

agent.config.createOptions 參數會指定為 TOML 內嵌資料表。此格式看起來像 JSON，但其不是 JSON。如需詳細資訊，請參閱 TOML v1.0.0 文件的內嵌資料表 (英文)。

[agent]
name = "edgeAgent"
type = "docker"
imagePullPolicy = "..."   # "on-create" or "never". Defaults to "on-create"

[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"
createOptions = { HostConfig = { Binds = ["/iotedge/storage:/iotedge/storage"] } }

[agent.config.auth]
serveraddress = "example.azurecr.io"
username = "username"
password = "password"

[agent.env]
RuntimeLogLevel = "debug"
UpstreamProtocol = "AmqpWs"
storageFolder = "/iotedge/storage"

精靈管理和工作負載 API 端點

如果您需要覆寫管理和工作負載 API 端點，請使用本節，並將值取代為您自己的值。

[connect]
workload_uri = "unix:///var/run/iotedge/workload.sock"
management_uri = "unix:///var/run/iotedge/mgmt.sock"

[listen]
workload_uri = "unix:///var/run/iotedge/workload.sock"
management_uri = "unix:///var/run/iotedge/mgmt.sock"

Edge 代理程式監視程式

如果您需要覆寫預設的 Edge 代理程式監視程式設定，請使用本節，並將值取代為您自己的值。

[watchdog]
max_retries = "infinite"   # the string "infinite" or a positive integer. Defaults to "infinite"

邊緣 CA 憑證

如果您有會發行您所有模組憑證的自有 Edge CA (部分機器翻譯) 憑證，請使用下列其中一節，並將值取代為您自己的值。

從檔案載入的 Edge CA 憑證

[edge_ca]
cert = "file:///var/aziot/certs/edge-ca.pem"            # file URI

pk = "file:///var/aziot/secrets/edge-ca.key.pem"        # file URI, or...
pk = "pkcs11:slot-id=0;object=edge%20ca?pin-value=1234" # PKCS#11 URI

透過 EST 發行的 Edge CA 憑證

[edge_ca]
method = "est"

如需如何使用 EST 伺服器的詳細資訊，請參閱教學課程：針對 Azure IoT Edge 設定透過安全傳輸伺服器的註冊 (部分機器翻譯)。

用於發行 Edge CA 憑證的選擇性 EST 設定

如果未設定，則會使用 [cert_issuance.est] 中的預設值。

common_name = "aziot-edge CA"
expiry_days = 90
url = "https://example.org/.well-known/est"

username = "estuser"
password = "estpwd"

裝置上已經有 EST 身分識別憑證

identity_cert = "file:///var/aziot/certs/est-id.pem"

identity_pk = "file:///var/aziot/secrets/est-id.key.pem"      # file URI, or...
identity_pk = "pkcs11:slot-id=0;object=est-id?pin-value=1234" # PKCS#11 URI

透過 EST 啟動程序身分識別憑證所要求的 EST 身分識別憑證

bootstrap_identity_cert = "file:///var/aziot/certs/est-bootstrap-id.pem"

bootstrap_identity_pk = "file:///var/aziot/secrets/est-bootstrap-id.key.pem"      # file URI, or...
bootstrap_identity_pk = "pkcs11:slot-id=0;object=est-bootstrap-id?pin-value=1234" # PKCS#11 URI

從本機 CA 憑證發行的 Edge CA 憑證

需要設定 [cert_issuance.local_ca]。

[edge_ca]
method = "local_ca"

# Optional configuration
common_name = "aziot-edge CA"
expiry_days = 90

Edge CA 快速入門憑證

如果您沒有用來發行所有模組憑證的自有 Edge CA 憑證，請使用本節，並為自動產生的自我簽署 Edge CA 憑證設定存留期天數。到期時間預設為 90 天。

警告

此設定「不建議用於生產環境」。請在 Edge CA 憑證區段中設定您自己的 Edge CA 憑證。

[edge_ca]
auto_generated_edge_ca_expiry_days = 90

Edge CA 憑證自動更新

此設定會管理 Edge CA 憑證的自動更新。當 Edge CA 設定為「快速入門」，或 Edge CA 已設定發行 method 時，就會套用自動更新。從檔案載入的 Edge CA 憑證通常無法自動更新，因為 Edge 執行階段沒有足夠的資訊，因此無法更新這些憑證。

重要

Edge CA 的更新需要重新產生該 CA 所發行的所有伺服器憑證。此重新產生會藉由重新啟動所有模組來進行。無法保證 Edge CA 的更新時間。如果您的使用案例無法接受模組隨機地重新啟動，請透過不包含 [edge_ca.auto_renew] 區段來停用自動更新。

[edge_ca.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"

映像記憶體回收

如果您需要覆寫預設的映像記憶體回收設定，請使用本節，並將本節中的值取代為您自己的值。

參數	描述
`enabled`	執行映像記憶體回收
`cleanup_recurrence`	您希望的映像記憶體回收執行頻率
`image_age_cleanup_threshold`	未使用映像的「存留期」。存留時間超過閾值的映像會遭到移除
`cleanup_time`	24 小時 HH:MM 格式。清除作業的執行時間

[image_garbage_collection]
enabled = true
cleanup_recurrence = "1d"
image_age_cleanup_threshold = "7d"
cleanup_time = "00:00"

Moby 執行階段

如果您需要覆寫預設的 Moby 執行階段設定，請使用本節，並將值取代為您自己的值。

[moby_runtime]
uri = "unix:///var/run/docker.sock"
network = "azure-iot-edge"

分享方式：

設定 IoT Edge 裝置設定

全域參數

主機名稱

父主機名稱

信任套件組合憑證

較高的 Docker 權限

自動重新佈建模式

佈建

使用連接字串進行手動佈建

使用對稱金鑰進行手動佈建

使用 X.509 憑證進行手動佈建

使用對稱金鑰進行 DPS 佈建

使用 X.509 憑證進行 DPS 佈建

(選擇性) 啟用裝置身分識別憑證的自動更新

使用 TPM (信賴平台模組) 進行 DPS 佈建

雲端逾時和重試行為

憑證發行

透過 EST 的憑證發行

裝置上已經有 EST 身分識別憑證

透過 EST 啟動程序身分識別憑證所要求的 EST 身分識別憑證

透過本機 CA 的憑證發行

TPM (信賴平台模組)

PKCS#11

預設 Edge 代理程式

精靈管理和工作負載 API 端點

Edge 代理程式監視程式

邊緣 CA 憑證

從檔案載入的 Edge CA 憑證

透過 EST 發行的 Edge CA 憑證

用於發行 Edge CA 憑證的選擇性 EST 設定

裝置上已經有 EST 身分識別憑證

透過 EST 啟動程序身分識別憑證所要求的 EST 身分識別憑證

從本機 CA 憑證發行的 Edge CA 憑證

Edge CA 快速入門憑證

Edge CA 憑證自動更新

映像記憶體回收

Moby 執行階段

意見反映

意見反映

更多資源