Configuración de la configuración del dispositivo IoT Edge
En este artículo se muestran las configuraciones y opciones para configurar la /etc/aziot/config.toml archivo 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 que ya ha definido.
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 de host
Para habilitar la detección de puerta de enlace, todos los dispositivos de puerta de enlace de IoT Edge (primarios) deben especificar un parámetro de nombre de host que sus dispositivos secundarios usan para encontrarlo 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, vea ¿Por qué se necesita EdgeGateway sobre 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 obtener más información sobre cómo establecer el parámetro parent_hostname, vea Conexión conjunta de dispositivos de Azure IoT Edge para crear una jerarquía.
Certificado de agrupación de confianza
Para proporcionar un certificado de entidad de certificación (CA) personalizado como raíz de confianza para IoT Edge y los módulos, especifique una configuración de trust_bundle_cert. Reemplace el valor del parámetro por el URI del archivo en el certificado de entidad de certificación raíz del 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, vea Administración de ca raíz 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 ha aprovisionado manualmente. Para obtener más información sobre cómo establecer el modo de aprovisionamiento de DPS, vea la sección Aprovisionamientode este artículo para obtener más información.
Se puede establecer uno de los siguientes valores:
| Mode | Descripción |
|---|---|
| Dinámica | Vuelva a aprovisionar cuando el dispositivo detecte que puede haberse movido de una instancia de IoT Hub a otra. Este modo es la predeterminada. |
| AlwaysOnStartup | Volver a aprovisionar cuando se reinicia el dispositivo o un bloqueo hace que los demonios se reinicien. |
| 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 reserva también está implícito 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 obtener más información sobre el aprovisionamiento de DPS con clave simétrica, vea Creación y aprovisionamiento de dispositivos IoT Edge a escala en Linux mediante la clave simétrica.
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
Solo habilite autorenewal si este dispositivo está configurado para la inscripción de DPS basada en CA. El uso de autorenewal para una inscripción individual hace que el dispositivo no pueda volver a aprovisionar.
[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 id. 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 firmante (CN) del certificado de id. EST generado siempre es el mismo que el identificador de 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 de TPM de DPS, use esta configuración de 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 establece en una cadena vacía, la biblioteca del cargador de TCTI intenta cargar un conjunto predefinido de módulos TCTI en orden.
[tpm]
tcti = "swtpm:port=2321"
El índice de TPM conserva 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 perimetral predeterminado
Cuando IoT Edge se inicia la primera vez, arranca un módulo de agente perimetral predeterminado. 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 insertada 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.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"
Puntos de conexión de API de administración y carga de trabajo de demonio
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 guardián del agente perimetral, 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 id. 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 que se establezca [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 entidad de certificación perimetral
Si no tiene su propio certificado de CA perimetral usado para emitir todos los certificados de módulo, use esta sección y establezca el número de días durante la vigencia del certificado de CA perimetral autogenerado. 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 entidad de certificación perimetral en las secciones Certificado de CA perimetral.
[edge_ca]
auto_generated_edge_ca_expiry_days = 90
Autorenewal del certificado de CA perimetral
Esta configuración administra la autorenewal del certificado de entidad perimetral. Autorenewal se aplica cuando la Edge de CA está configurada como inicio rápido o cuando la Edge de CA tiene un 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 de CA requiere que se vuelvan a generar todos los certificados de servidor emitidos por esa CA de certificación. Esta regeneración se realiza reiniciando todos los módulos. No se puede garantizar la hora de renovación de Edge de CA. Si los reinicios aleatorios del módulo son inaceptables para su caso de uso, deshabilite autorenewal.
[edge_ca.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"
Recolección de elementos no utilizados de imagen
Si necesita invalidar la configuración predeterminada de recolección de elementos no utilizados de imagen, use esta sección y reemplace los valores de esta sección por los suyos propios.
| Parámetro | Descripción |
|---|---|
enabled |
Ejecuta la recolección de elementos no utilizados de imagen |
cleanup_recurrence |
Frecuencia con la que desea que se ejecute la recolección de elementos no utilizados de la imagen |
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"