你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

配置 IoT Edge 设备设置

项目
04/11/2024

本文介绍用于配置 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 其自身的主机名？。

注意

如果未设置 hostname 值，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 个字符的 hostname，这是服务器证书公用名称的字符限制。

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 功能可用于获取 root 访问权限。默认情况下，允许 --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

（可选）启用设备 ID 证书的自动续订

自动续订需要使用已知的证书颁发方法。将 method 设置为 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 ID 证书

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 启动 ID 证书请求的 EST ID 证书

使用 TLS 客户端证书进行身份验证，该证书一次性用于创建初始 EST ID 证书。首次颁发证书后，系统会自动创建 identity_cert 和 identity_pk 并将其用于以后的身份验证和续订。生成的 EST ID 证书的使用者公用名 (CN) 始终与预配部分下的已配置设备 ID 相同。这些文件必须可供用户 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 身份验证密钥。该索引用作与持久对象（例如 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.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 代理监视器

如果需要替代默认的 Edge 代理监视器设置，请使用此部分并将值替换为你自己的值。

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

Edge 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 ID 证书

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 启动 ID 证书请求的 EST ID 证书

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 预配

（可选）启用设备 ID 证书的自动续订

使用 TPM（受信任的平台模块）进行 DPS 预配

云超时和重试行为

证书颁发

通过 EST 颁发证书

设备上已有的 EST ID 证书

通过 EST 启动 ID 证书请求的 EST ID 证书

通过本地 CA 颁发证书

TPM（受信任的平台模块）

PKCS#11

默认 Edge 代理

守护程序管理和工作负载 API 终结点

Edge 代理监视器

Edge CA 证书

从文件加载的 Edge CA 证书

通过 EST 颁发的 Edge CA 证书

用于颁发 Edge CA 证书的可选 EST 配置

设备上已有的 EST ID 证书

通过 EST 启动 ID 证书请求的 EST ID 证书

从本地 CA 证书颁发的 Edge CA 证书

Edge CA 快速启动证书

Edge CA 证书自动续订

映像垃圾回收

Moby 运行时

其他资源