Настройка параметров устройства IoT Edge

Применимо к: IoT Edge 1.5

Внимание

IoT Edge 1.5 LTS — это поддерживаемый выпуск. IoT Edge 1.4 LTS достиг срока окончания службы 12 ноября 2024 года. Если вы используете более ранний выпуск, ознакомьтесь с Update IoT Edge.

В этой статье показаны параметры и опции для настройки IoT Edge файла /etc/aziot/config.toml устройства IoT Edge. IoT Edge использует файл config.toml для инициализации параметров для устройства. Каждый из разделов файла config.toml имеет несколько параметров. Не все параметры являются обязательными, так как они применяются к определенным сценариям.

Шаблон, содержащий все параметры, можно найти в файле config.toml.edge.template в файле /etc/aziot на устройстве IoT Edge. Вы можете скопировать содержимое всего шаблона или разделов шаблона в файл config.toml . Раскомментируйте нужные разделы. Не следует копировать параметры, которые вы ранее определили.

При изменении конфигурации устройства используйте sudo iotedge config apply для применения изменений.

Глобальные параметры

Имя узла, parent_hostname, trust_bundle_cert, allow_elevated_docker_permissions и auto_reprovisioning_mode должны находиться в начале файла конфигурации перед любыми другими разделами. Добавление параметров перед коллекцией параметров гарантирует правильность их применения. Дополнительные сведения о допустимом синтаксисе см. в toml.io.

Hostname (Имя узла)

Чтобы включить поиск шлюза, каждому устройству шлюза IoT Edge (родительскому) необходимо указать параметр имени узла, который дочерние устройства используют для его нахождения в локальной сети. Модуль EdgeHub также использует параметр имени узла для сопоставления с сертификатом сервера. Дополнительные сведения см. в статье "Почему 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 для создания иерархии.

Сертификат пакета доверия

Чтобы предоставить пользовательский сертификат центра сертификации (ЦС) в качестве корневого центра доверия для IoT Edge и модулей, установите конфигурацию trust_bundle_cert. Замените значение параметра на URI файла, указывающий на корневой сертификат удостоверяющего центра на вашем устройстве.

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

Дополнительные сведения о пакете доверия IoT Edge см. в разделе Управление доверенным корневым ЦС (пакет доверенных сертификатов).

Повышенные разрешения Docker

Некоторые возможности docker можно использовать для получения корневого доступа. По умолчанию --privileged флаг и все возможности, перечисленные в параметре CapAdd в HostConfig docker, разрешены.

Если модули не требуют привилегированных или дополнительных возможностей, используйте allow_elevated_docker_permissions для повышения безопасности устройства.

allow_elevated_docker_permissions = false

Режим автоматической повторной подготовки

Необязательный параметр auto_reprovisioning_mode указывает условия, определяющие, когда устройство пытается автоматически повторно подготовиться с помощью службы подготовки устройств. Режим автоматической подготовки игнорируется, если устройство подготовлено вручную. Дополнительные сведения о настройке режима подготовки DPS см. в разделе " Подготовка " в этой статье.

Можно задать одно из следующих значений:

Режим	Описание
Динамический	Перепрофилирование, когда устройство обнаруживает, что оно могло быть перемещено из одного IoT Hub в другой. Этот режим используется по умолчанию.
AlwaysOnStartup	Повторная инициализация при перезагрузке устройства или сбое, приводящем к перезапуску демонов.
OnErrorOnly	Никогда не активируйте повторную подготовку устройства автоматически. Повторное создание устройства происходит только в качестве резервной меры, если устройство не может подключиться к IoT Hub во время настройки удостоверения по причине ошибок подключения. Это резервное поведение по умолчанию присутствует в режимах Dynamic и AlwaysOnStartup.

Например:

auto_reprovisioning_mode = "Dynamic"

Дополнительные сведения о повторной подготовке устройств см. в разделе IoT Hub концепции повторной подготовки устройств.

Подготовка

Вы можете предоставить одно устройство или несколько устройств в больших масштабах в зависимости от потребностей вашего решения IoT Edge. Параметры, доступные для аутентификации связи между устройствами IoT Edge и центрами IoT, зависят от выбранного метода настройки.

Вы можете подготовить строку подключения, симметричный ключ, сертификат X.509, закрытый ключ сертификата идентификации или сертификат идентификации. Конфигурирование DPS доступно с различными вариантами. Выберите один способ настройки. Замените примеры значений собственными.

Подготовка вручную с помощью connection string

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

Дополнительные сведения о получении сведений о подготовке см. статью Создание и подготовка устройства IoT Edge в Linux с помощью симметричных ключей.

Ручное конфигурирование с симметричным ключом

[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

Дополнительные сведения о получении информации для настройки см. в Создание и настройка устройства IoT Edge в Linux с помощью симметричных ключей.

Ручная настройка с использованием сертификата X.509

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

[provisioning.authentication]
method = "x509"

Дополнительные сведения о подготовке с помощью сертификатов X.509 см. в статье Создание и обеспечение работы устройства IoT Edge в Linux с помощью сертификатов 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 = "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 с симметричным ключом см. в статье Создание и провиженинг устройств IoT Edge в большом масштабе на Linux с использованием симметричных ключей.

Подготовка DPS с помощью сертификатов X.509

[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

(Необязательно) Включение автоматического продления сертификата идентификатора устройства

Autorenewal требует известного метода выдачи сертификата. Задайте для метода значение est или local_ca.

Внимание

Включите автоматическое обновление, если это устройство настроено для регистрации DPS на основе ЦС. Использование автоматического обновления для отдельной регистрации не дает устройству вновь пройти подготовку.

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

Для получения дополнительных сведений о подготовке DPS с помощью сертификатов X.509 см. в статье Создание и подготовка устройств IoT Edge в масштабе на Linux с использованием сертификатов 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 = "tpm"
registration_id = "my-device"

Если вы используете настраивание DPS с TPM и если вам требуется пользовательская конфигурация, ознакомьтесь с разделом TPM.

Дополнительные сведения см. в разделе Создание и настройка устройств IoT Edge в больших масштабах с использованием доверенного платформенного модуля на Linux.

Время ожидания облака и поведение повторных попыток

Эти параметры управляют тайм-аутом и количеством попыток для облачных операций, таких как взаимодействие со службой предоставления устройств (DPS) во время предоставления или с IoT Hub для создания идентификатора модуля.

Параметр 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

Проверка подлинности с помощью сертификата клиента TLS, который используется один раз для создания начального сертификата идентификатора EST. После первой выдачи сертификата identity_cert и identity_pk создаются и используются автоматически для последующей аутентификации и продления. Общее имя субъекта (CN) созданного сертификата идентификатора EST всегда совпадает с настроенным идентификатором устройства в разделе подготовки. Эти файлы должны быть доступны для чтения пользователями 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"

Выдача сертификата через локальный центр сертификации

[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, используйте эти параметры доверенного платформенного модуля.

Допустимые строки для загрузки TCTI смотрите в разделе 3.5 спецификации API Интерфейса передачи команд TCG TSS 2.0 TPM (TCTI).

Установка пустой строки приводит к тому, что библиотека загрузчика 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

Если вы использовали любые URI PKCS#11, используйте следующие параметры и замените значения на соответствующие параметры конфигурации 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 версии 1.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"

Сертификат УЦ Edge

Если у вас есть собственный сертификат Edge CA, который выдает все сертификаты для ваших модулей, используйте один из этих разделов и замените значения на свои.

Сертификат удостоверяющего центра (ЦС) Edge загружен из файла

[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]
method = "est"

Дополнительные сведения об использовании сервера EST см. в разделе Tutorial: настройка регистрации по протоколу Secure Transport Server для Azure IoT Edge.

Необязательная конфигурация EST для выдачи сертификата ЦС Edge

Если не задано, используются значения по умолчанию в [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

Сертификат ЦС Edge, выданный локальным удостоверяющим центром

Необходимо задать [cert_issuance.local_ca].

[edge_ca]
method = "local_ca"

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

Сертификаты быстрого запуска УЦ Edge

Если у вас нет собственного сертификата ЦС Edge, используемого для выдачи всех сертификатов модуля, воспользуйтесь этим разделом и задайте количество дней для срока действия самозаверяющего сертификата ЦС Edge, созданного автоматически. Срок действия по умолчанию — 90 дней.

Внимание

Этот параметр не рекомендуется использовать для рабочей среды. Настройте собственный сертификат ЦС Edge в разделах сертификатов ЦС Edge.

[edge_ca]
auto_generated_edge_ca_expiry_days = 90

Автоматическое обновление сертификата Edge CA

Этот параметр управляет автоматическим обновлением сертификата ЦС Edge. Автоматическое обновление применяется, если ЦС Edge настроен как быстрый запуск или когда у ЦС Edge установлен method набор для выпуска. Сертификаты ЦС Edge, загруженные из файлов, обычно не могут быть автоматически восстановлены, так как среда выполнения Edge не имеет достаточно сведений для их продления.

Внимание

Для обновления пограничного ЦС требуется повторно создать все сертификаты сервера, выданные этим ЦС. Это восстановление выполняется путем перезапуска всех модулей. Время обновления ЦС Edge не может быть гарантировано. Если перезапуск случайного модуля неприемлем для вашего варианта использования, отключите автоматическое обновление, не включив раздел [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"