Configuración de los ajustes del dispositivo IoT Edge

Se aplica a: IoT Edge 1.5

En este artículo se muestran las configuraciones y opciones para configurar el archivo IoT Edge /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 archivo /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 de puerta de enlace, cada dispositivo de puerta de enlace IoT Edge (dispositivo padre) debe especificar un parámetro de nombre de host que sus dispositivos secundarios usen 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?

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 nested edge. Cada dispositivo IoT Edge descendente debe especificar un parámetro parent_hostname para identificar su padre. En un escenario jerárquico en el que un único dispositivo IoT Edge es un dispositivo primario y 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, consulte Conectar dispositivos Azure IoT Edge para crear una jerarquía.

Certificado de agrupación de confianza

Para proporcionar un certificado de autoridad de certificación (CA) personalizado como raíz de confianza para IoT Edge y 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 paquete de confianza de IoT Edge, consulte Administrar CA raíz de confianza (paquete 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:

Por ejemplo:

auto_reprovisioning_mode = "Dynamic"

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

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 de IoT Edge y los centros de IoT dependen del método de aprovisionamiento que elija.

Usted puede aprovisionar con una cadena de conexión, una clave simétrica, un certificado X.509, un certificado de identidad privado 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, consulte Crear y aprovisionar 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, consulte Crear y aprovisionar 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, consulte Crear y aprovisionar 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, consulte Crear y aprovisionar 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.

[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, consulte Crear y aprovisionar 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, consulte Crear y aprovisionar 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 identidades 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 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 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 perimetral predeterminado

Cuando IoT Edge se inicia por primera vez, inicializa un módulo predeterminado del Agente Edge. 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.

[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 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 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 obtener más información sobre el uso de un servidor EST, vea Tutorial: Configurar 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 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.

[edge_ca]
auto_generated_edge_ca_expiry_days = 90

Autorenewal del certificado de CA perimetral

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.

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

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