Configuración de la configuración del dispositivo IoT Edge

Se aplica a: IoT Edge 1.5

Importante

IoT Edge 1.5 LTS es la versión compatible. IoT Edge 1.4 LTS finaliza su ciclo de vida el 12 de noviembre de 2024. Si está usando una versión anterior, consulte Actualización de IoT Edge.

En este artículo se muestran las configuraciones y opciones para configurar el archivo /etc/aziot/config.toml de un dispositivo IoT Edge. IoT Edge usa el archivo config.toml para inicializar la configuración del dispositivo. Cada una de las secciones del archivo config.toml tiene varias opciones. No todas las opciones son obligatorias, ya que se aplican a escenarios específicos.

Puede encontrar una plantilla que contenga todas las opciones en el archivo config.toml.edge.template dentro del directorio /etc/aziot en un dispositivo IoT Edge. Puede copiar el contenido de toda la plantilla o secciones de la plantilla en el archivo config.toml. Quite la marca de comentario de las secciones que necesita. Tenga en cuenta que no debe copiar los parámetros definidos anteriormente.

Si cambia la configuración de un dispositivo, use sudo iotedge config apply para aplicar los cambios.

Parámetros globales

El nombre de host, parent_hostname, trust_bundle_cert, allow_elevated_docker_permissions, y auto_reprovisioning_mode parámetros debe estar al principio del archivo de configuración antes de cualquier otra sección. Agregar parámetros antes de una colección de valores garantiza que se aplican correctamente. Para obtener más información sobre la sintaxis válida, vea toml.io.

Nombre del host

Para habilitar el descubrimiento del gateway, cada dispositivo gateway de IoT Edge (padre) necesita especificar un parámetro de nombre de host que sus dispositivos hijos usan para localizarlo en la red local. El módulo edgeHub también usa el parámetro hostname para que coincida con su certificado de servidor. Para obtener más información, consulte ¿Por qué es necesario informar a EdgeGateway acerca de su propio nombre de host?

Nota:

Cuando no se establece el valor de nombre de host, IoT Edge intenta encontrarlo automáticamente. Sin embargo, es posible que los clientes de la red no puedan detectar el dispositivo si no está establecido.

Para nombre de host, reemplace fqdn-device-name-or-ip-address por el nombre del dispositivo para invalidar el nombre de host predeterminado del dispositivo. El valor puede ser un nombre de dominio completo (FQDN) o una dirección IP. Use esta configuración como nombre de host de puerta de enlace en un dispositivo de puerta de enlace de IoT Edge.

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

Nombre de host primario

El nombre de host primario se usa cuando el dispositivo IoT Edge forma parte de una jerarquía, lo que se conoce como un borde anidado. Cada dispositivo IoT Edge de nivel inferior debe especificar el parámetro parent_hostname para identificar a su dispositivo primario. En un escenario jerárquico, en el que un único dispositivo IoT Edge es tanto un dispositivo primario como uno secundario, necesita ambos parámetros.

Reemplace fqdn-parent-device-name-or-ip-address por el nombre del dispositivo primario. Use un nombre de host de menos de 64 caracteres, que es el límite de caracteres de un nombre común del certificado de servidor.

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

Para más información sobre cómo establecer el parámetro parent_hostname, consulte "Conectar dispositivos Azure IoT Edge para crear una jerarquía".

Certificado de agrupación de confianza

Para proporcionar un certificado personalizado de autoridad de certificación (CA) como raíz de confianza para IoT Edge y sus módulos, debe especificar una configuración de trust_bundle_cert. Reemplace el valor del parámetro por el URI del archivo al certificado de la CA raíz en su dispositivo.

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

Para obtener más información sobre el conjunto de confianza de IoT Edge, consulte Administración de ca raíz de confianza (agrupación de confianza).

Permisos elevados de Docker

Algunas funcionalidades de Docker se pueden usar para obtener acceso raíz. De forma predeterminada, se permiten la marca --privileged y todas las funcionalidades enumeradas en el parámetroCapAdd del HostConfig de docker.

Si ningún módulo requiere funcionalidades con privilegios o adicionales, use allow_elevated_docker_permissions para mejorar la seguridad del dispositivo.

allow_elevated_docker_permissions = false

Modo de reaprovisionamiento automático

El parámetro opcional auto_reprovisioning_mode especifica las condiciones que deciden cuándo un dispositivo intenta volver a aprovisionar automáticamente con Device Provisioning Service. El modo de aprovisionamiento automático se omite si el dispositivo se aprovisiona manualmente. Para obtener más información sobre cómo establecer el modo de aprovisionamiento de DPS, consulte la sección Aprovisionamiento de este artículo.

Se puede establecer uno de los siguientes valores:

Modo	Descripción
Dinámica	Vuelva a aprovisionar cuando el dispositivo detecte que podría haberse movido de una instancia de IoT Hub a otra. Este modo es la predeterminada.
AlwaysOnStartup	Volver a aprovisionar cuando el dispositivo se reinicie o un bloqueo haga que se reinicien los daemons.
OnErrorOnly	Nunca desencadene el reaprovisionamiento de dispositivos automáticamente. El reaprovisionamiento de dispositivos solo se produce como reserva, si el dispositivo no puede conectarse a IoT Hub durante el aprovisionamiento de identidades debido a errores de conectividad. Este comportamiento de respaldo está implícito también en los modos Dinámico y AlwaysOnStartup.

Por ejemplo:

auto_reprovisioning_mode = "Dynamic"

Para obtener más información sobre el reaprovisionamiento de dispositivos, vea conceptos de reaprovisionamiento de dispositivos de IoT Hub.

Aprovisionamiento

Puede aprovisionar un único dispositivo o varios dispositivos a escala, en función de las necesidades de la solución de IoT Edge. Las opciones disponibles para autenticar las comunicaciones entre los dispositivos IoT Edge y los centros de IoT dependen del método de aprovisionamiento que elija.

Puede aprovisionar con una cadena de conexión, una clave simétrica, un certificado X.509, una clave privada de certificado de identidad o un certificado de identidad. El aprovisionamiento de DPS se incluye con varias opciones. Elija un método para el aprovisionamiento. Reemplace los valores de ejemplo por los suyos propios.

Aprovisionamiento manual con cadena de conexión

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

Para obtener más información sobre cómo recuperar información de aprovisionamiento, vea Creación y aprovisionamiento de un dispositivo IoT Edge en Linux mediante claves simétricas.

Aprovisionamiento manual con clave simétrica

[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

Para obtener más información sobre cómo recuperar información de aprovisionamiento, vea Creación y aprovisionamiento de un dispositivo IoT Edge en Linux mediante claves simétricas.

Aprovisionamiento manual con certificado X.509

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

[provisioning.authentication]
method = "x509"

Para obtener más información sobre el aprovisionamiento mediante certificados X.509, vea Creación y aprovisionamiento de un dispositivo IoT Edge en Linux mediante certificados X.509.

Aprovisionamiento de DPS con clave simétrica

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

Para más información sobre el aprovisionamiento de DPS con clave simétrica, consulte Creación y aprovisionamiento de dispositivos IoT Edge a escala en Linux mediante claves simétricas.

Aprovisionamiento de DPS con certificados 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

(Opcional) Habilitación de la renovación automática del certificado de identificador de dispositivo

Autorenewal requiere un método de emisión de certificados conocido. Establezca método en est o local_ca.

Importante

Active la renovación automática solo si este dispositivo está configurado para la inscripción de DPS basada en una autoridad de certificación (CA). El uso de renovación automática para una inscripción individual hace que el dispositivo no pueda volver a configurar.

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

Para obtener más información sobre el aprovisionamiento de DPS con certificados X.509, vea Creación y aprovisionamiento de dispositivos IoT Edge a escala en Linux mediante certificados X.509.

Aprovisionamiento de DPS con TPM (módulo de plataforma segura)

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

Si usa el aprovisionamiento de DPS con TPM y requiere una configuración personalizada, vea la sección TPM.

Para obtener más información, vea Creación y aprovisionamiento de dispositivos IoT Edge a escala con un TPM en Linux.

Comportamiento de tiempo de espera y reintento en la nube

Esta configuración controla el tiempo de espera y los reintentos para las operaciones en la nube, como la comunicación con Device Provisioning Service (DPS) durante el aprovisionamiento o IoT Hub para la creación de la identidad del módulo.

El parámetro cloud_timeout_sec es la fecha límite en segundos para una solicitud de red a los servicios en la nube. Por ejemplo, una solicitud HTTP. Se debe recibir una respuesta del servicio en la nube antes de esta fecha límite o se produce un error en la solicitud como tiempo de espera.

El parámetro cloud_retries controla cuántas veces se puede reintentar una solicitud después de que se produzca un error en el primer intento. El cliente siempre envía al menos una vez, por lo que el valor es el número de reintentos después de que se produzca un error en el primer intento. Por ejemplo, cloud_retries = 2 significa que el cliente realiza un total de tres intentos.

cloud_timeout_sec = 10
cloud_retries = 1

Emisión de certificados

Si configuró certificados emitidos dinámicamente, elija el método de emisión correspondiente y reemplace los valores de ejemplo por los suyos propios.

Emisión de certificados a través de EST

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

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

Certificado de identificación EST ya en el dispositivo

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

Certificado de ID EST solicitado a través del certificado de ID de arranque EST

Autenticación con un certificado de cliente TLS que se usa una vez para crear el certificado de identificador EST inicial. Después de la primera emisión de certificados, se crea automáticamente una identity_cert y identity_pk para futuras autenticaciones y renovaciones. El Nombre Común del Sujeto (CN) del certificado de ID EST generado siempre es el mismo que el ID del dispositivo configurado en la sección de aprovisionamiento. Estos archivos deben ser legibles por los usuarios aziotcs y aziotks , respectivamente.

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"

Emisión de certificados a través de una entidad de certificación local

[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 (módulo de plataforma segura)

Si necesita una configuración especial para el TPM al usar el aprovisionamiento TPM de DPS, aplique estas configuraciones del TPM.

Para obtener cadenas de cargador TCTI aceptables, vea la sección 3.5 de TCG TSS 2.0 TPM Command Transmission Interface (TCTI) API Specification.

Si se configura en una cadena vacía, la biblioteca del cargador de TCTI intenta cargar en orden un conjunto predefinido de módulos TCTI.

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

El índice de TPM almacena la clave de autenticación de DPS. El índice se toma como un desplazamiento de la dirección base para objetos persistentes como 0x81000000 y debe estar en el intervalo de 0x00_00_00 a 0x7F_FF_FF. El valor predeterminado es 0x00_01_00.

auth_key_index = "0x00_01_00"

Use valores de autorización para las jerarquías de aprobación y propietario, si es necesario. De forma predeterminada, estos valores son cadenas vacías.

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

PKCS#11

Si ha usado cualquier URI PKCS#11, use los parámetros siguientes y reemplace los valores por la configuración de PKCS#11.

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

Agente de borde predeterminado

Cuando IoT Edge se inicia por primera vez, inicia un módulo predeterminado del Edge Agent. Si necesita invalidar los parámetros proporcionados en el módulo predeterminado del agente perimetral, use esta sección y reemplace los valores por los suyos propios.

Nota:

El parámetro agent.config.createOptions se especifica como una tabla insertada TOML. Este formato es similar a JSON, pero no es JSON. Para obtener más información, vea Tabla en línea de la documentación de 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"

Puntos de conexión de API para la administración de demonios y carga de trabajo

Si necesita invalidar los puntos de conexión de API de administración y carga de trabajo, use esta sección y reemplace los valores por los suyos propios.

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

Guardián del Agente de Edge

Si necesita invalidar la configuración predeterminada del supervisor del Agente Edge, use esta sección y reemplace los valores por los suyos propios.

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

Certificado de CA perimetral

Si tiene su propio certificado CA de Edge que emite todos los certificados de módulo, use una de estas secciones y reemplace los valores por los suyos propios.

Certificado de CA de Edge cargado desde un archivo

[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

Certificado de CA de Edge emitido a través de EST

[edge_ca]
method = "est"

Para más información sobre el uso de un servidor EST, vea Tutorial: Configuración de la inscripción a través del servidor de transporte seguro para Azure IoT Edge.

Configuración EST opcional para emitir el certificado de CA perimetral

Si no se establece, se usan los valores predeterminados de [cert_issuance.est].

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

username = "estuser"
password = "estpwd"

Certificado de identificación EST ya en el dispositivo

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

Certificado de ID EST solicitado a través del certificado de ID de arranque 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

Certificado de CA de Edge emitido desde un certificado de CA local

Requiere establecer [cert_issuance.local_ca].

[edge_ca]
method = "local_ca"

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

Certificados de inicio rápido de la Autoridad de Certificación de Borde

Si no tiene su propio certificado de Entidad de Certificación (CA) perimetral usado para emitir todos los certificados de módulo, utilice esta sección y establezca el número de días de vigencia del certificado de CA perimetral autofirmado generado automáticamente. El valor predeterminado de expiración es de 90 días.

Precaución

Esta configuraciónNo se recomienda para el uso de producción. Configure su propio certificado de CA perimetral en las secciones Certificado de ca perimetral.

[edge_ca]
auto_generated_edge_ca_expiry_days = 90

Renovación automática del certificado CA del perímetro

Esta configuración administra la renovación automática del certificado CA de Edge. La renovación automática se aplica cuando el Edge CA está configurado como inicio rápido o cuando el Edge CA tiene un conjunto de emisión method establecido. Por lo general, los certificados de Edge de CA cargados desde archivos no se pueden cambiar automáticamente, ya que el entorno de ejecución de Edge no tiene suficiente información para renovarlos.

Importante

La renovación de una Edge CA requiere que se vuelvan a generar todos los certificados de servidor emitidos por esa CA. Esta regeneración se realiza reiniciando todos los módulos. No se puede garantizar la hora de renovación del CA de Edge. Si los reinicios aleatorios del módulo son inaceptables para su caso de uso, deshabilite la renovación automática sin incluir la sección [edge_ca.auto_renew].

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

Recolección de basura de imágenes

Si necesita anular la configuración predeterminada de recolección de basura de imágenes, use esta sección y reemplace los valores con los suyos propios.

Parámetro	Descripción
enabled	Ejecuta la limpieza de basura de imágenes
cleanup_recurrence	Con qué frecuencia desea que se ejecute la recolección de basura de imágenes
image_age_cleanup_threshold	La antigüedad de las imágenes sin usar. Las imágenes anteriores al umbral se quitan
cleanup_time	Formato HH:MM de 24 horas. Cuando se ejecuta el trabajo de limpieza

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

Tiempo de ejecución de Moby

Si necesita invalidar la configuración predeterminada del entorno de ejecución de Moby, use esta sección y reemplace los valores por los suyos propios.

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