設定IoT Edge裝置設定

發行項
04/11/2024

本文說明設定 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 來套用變更。

全域參數

主機名、parent_hostname、trust_bundle_cert、allow_elevated_docker_permissions和auto_reprovisioning_mode參數必須位於組態檔的開頭，才能執行任何其他區段。在設定集合之前新增參數可確保它們已正確套用。如需有效語法的詳細資訊，請參閱 toml.io 。

主機名稱

若要啟用閘道探索，每個IoT Edge閘道（父代）裝置都必須指定其子裝置用來在局域網路上尋找它的主機名參數。 edgeHub 模組也會使用主機名參數與其伺服器證書相符。如需詳細資訊，請參閱 EdgeGateway為何必須被告知自己的主機名？。

注意

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

針對主機名，將 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 功能可用來取得根存取權。根據預設，--privileged允許 docker HostConfig 的 CapAdd 參數中列出的旗標和所有功能。

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

allow_elevated_docker_permissions = false

自動重新佈建模式

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

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

[模式]	描述
動態	當裝置偵測到裝置可能已從一個 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"

如果您使用 DPS 布建搭配 TPM，而且需要自訂設定，請參閱 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 和 aziotk 分別讀取。

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 驗證金鑰。索引會作為永續性物件的基位址位移，例如 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 模組的參數，請使用本節並將值取代為您自己的值。

注意

參數 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.4"
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 Agent 監視程式

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

[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]
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 Agent 監視程式

邊緣 CA 憑證

從檔案載入的Edge CA 憑證

透過 EST 發行的 Edge CA 憑證

用來發行 Edge CA 憑證的選擇性 EST 組態

裝置上已經有 EST 識別符憑證

透過 EST 啟動程式識別碼憑證要求的 EST 識別符憑證

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

Edge CA 快速入門憑證

Edge CA 憑證自動重新更新

影像垃圾收集

Moby 運行時間

其他資源

使用連接字串手動布建