Настройка параметров устройства 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 пытается найти его автоматически. Однако клиенты в сети могут не обнаруживать устройство, если оно не задано.

Для имени узла замените 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 можно использовать для получения корневого доступа. По умолчанию флаг и все возможности, перечисленные в параметре CapAdd docker HostConfig, --privileged разрешены.

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

allow_elevated_docker_permissions = false

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

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

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

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

Например:

auto_reprovisioning_mode = "Dynamic"

Дополнительные сведения о повторной подготовке устройств см. в Центр Интернета вещей концепциях повторной подготовки устройств.

Подготовка

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

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

Подготовка вручную с помощью строка подключения

[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 на основе ЦС. Использование autorenewal для отдельной регистрации приводит к невозможности повторной подготовки устройства.

[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) во время подготовки или Центр Интернета вещей для создания удостоверения модуля.

Параметр 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 в порядке.

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

Сертификат ЦС 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 см. в руководстве по настройке регистрации по протоколу 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

Сертификат пограничного ЦС autorenewal

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

Важно!

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

[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"