Configurer les paramètres de l’appareil IoT Edge
S’applique à :
IoT Edge 1.5 IoT Edge 1.4
Important
IoT Edge 1.5 LTS et IoT Edge 1.4 LTS sont des versions prises en charge. IoT Edge 1.4 LTS sera en fin de vie le 12 novembre 2024. Si vous utilisez une version antérieure, consultez l’article Mettre à jour IoT Edge.
Cet article présente les paramètres et les options de configuration de IoT Edge /etc/aziot/config.toml d’un appareil IoT Edge. IoT Edge utilise le fichier config.toml pour initialiser les paramètres de l’appareil. Chacune des sections du fichier config.toml a plusieurs options. Toutes les options ne sont pas obligatoires, car elles s’appliquent à des scénarios spécifiques.
Vous trouverez un modèle contenant toutes les options dans le fichier config.toml.edge.template dans le répertoire /etc/aziot sur un appareil IoT Edge. Vous pouvez copier le contenu de l’ensemble du modèle ou des sections du modèle dans votre fichier config.toml. Supprimez les marques de commentaire des sections dont vous avez besoin. N’oubliez pas de ne pas copier sur les paramètres que vous avez déjà définis.
Si vous modifiez la configuration d’un appareil, utilisez sudo iotedge config apply pour appliquer les modifications.
Paramètres globaux
Le nom d’hôte, parent_hostname, trust_bundle_cert, allow_elevated_docker_permissionset les paramètres auto_reprovisioning_mode doivent être au début du fichier config avant les autres sections. L’ajout de paramètres avant un ensemble de paramètres permet de s’assurer qu’ils sont appliqués correctement. Pour plus d’informations sur la syntaxe valide, consultez toml.io.
Nom d’hôte
Pour activer la découverte de passerelle, chaque appareil de passerelle IoT Edge (parent) doit spécifier un paramètre de nom d’hôte permettant à ses appareils enfants de le trouver sur le réseau local. Le module edgeHub utilise également le paramètre nom d’hôte pour correspondre à son certificat de serveur. Pour plus d’informations, voir Pourquoi EdgeGateway doit-il être informé de son propre nom d’hôte ?
Remarque
Lorsque la valeur du nom d’hôte n’est pas définie, IoT Edge tente de la trouver automatiquement. Toutefois, les clients du réseau peuvent ne pas être en mesure de découvrir l’appareil s’il n’est pas défini.
Pour nom d’hôte, remplacez fqdn-device-name-or-ip-address par le nom de votre appareil pour remplacer le nom d’hôte par défaut de l’appareil. La valeur peut être un nom de domaine complet (FQDN) ou une adresse IP. Utilisez ce paramètre comme nom d’hôte de passerelle sur un appareil de passerelle IoT Edge.
hostname = "fqdn-device-name-or-ip-address"
Nom d’hôte parent
Le nom d’hôte parent est utilisé lorsque l’appareil IoT Edge fait partie d’une hiérarchie, sinon appelée périphérie imbriquée. Chaque appareil IoT Edge en aval doit spécifier un paramètre parent_hostname pour identifier son parent. Dans un scénario hiérarchique où un seul appareil IoT Edge est à la fois parent et enfant, il a besoin des deux paramètres.
Remplacez fqdn-parent-device-name-or-ip-address par le nom de votre appareil parent. Utilisez un nom d’hôte inférieur à la limite de caractères d’un nom commun de certificat de serveur, soit 64 caractères.
parent_hostname = "fqdn-parent-device-name-or-ip-address"
Pour plus d’informations sur la définition du paramètre parent_hostname, consultez Connecter des appareils Azure IoT Edge ensemble pour créer une hiérarchie.
Certificat d’offre groupée de confiance
Pour fournir un certificat d’autorité de certification personnalisée comme racine d’approbation pour IoT Edge et les modules, spécifiez une configuration trust_bundle_cert . Remplacez la valeur du paramètre avec l’URI du fichier pour qu’il pointe vers le certificat d’autorité de certification racine sur votre appareil.
trust_bundle_cert = "file:///var/aziot/certs/trust-bundle.pem"
Pour plus d’informations sur l’offre groupée de confiance IoT Edge, consultez Gérer l’autorité de certification racine de confiance.
Autorisations Docker élevées
Certaines fonctionnalités docker peuvent être utilisées pour obtenir un accès racine. Par défaut, l’indicateur --privileged et toutes les fonctionnalités répertoriées dans le paramètre CapAdd du dockerHostConfig sont autorisés.
Si aucun module ne nécessite de fonctionnalités privilégiées ou supplémentaires, utilisez allow_elevated_docker_permissions pour améliorer la sécurité de l’appareil.
allow_elevated_docker_permissions = false
Mode de provisionnement automatique
Le paramètre facultatif auto_reprovisioning_mode spécifie les conditions qui déterminent quand un appareil tente de se provisionner automatiquement avec le service de provisionnement des appareils. Le mode d’approvisionnement automatique est ignoré si l’appareil a été approvisionné manuellement. Pour plus d’informations sur la définition du mode d’approvisionnement DPS, consultez la section Approvisionnement dans cet article pour plus d’informations.
L’une des valeurs suivantes peut être définie :
| Mode | Description |
|---|---|
| Dynamique | L’approvisionnement a lieu quand l’appareil détecte qu’il a peut-être été déplacé d’un IoT Hub vers un autre IoT Hub. Il s’agit du mode par défaut. |
| AlwaysOnStartup | L’approvisionnement a lieu quand l’appareil est redémarré ou qu’un incident entraîne le redémarrage des démons. |
| OnErrorOnly | L’approvisionnement automatique de l’appareil n’est jamais déclenché. L’approvisionnement de l’appareil n’intervient qu’en tant que solution de repli, si l’appareil n’est pas en mesure de se connecter à l’IoT Hub lors de l’approvisionnement de l’identité en raison d’erreurs de connectivité. Ce comportement de secours est implicite dans les modes Dynamic et AlwaysOnStartup. |
Par exemple :
auto_reprovisioning_mode = "Dynamic"
Pour plus d’informations sur l’approvisionnement des appareils, voir IoT Hub Concepts de l’approvisionnement des appareils.
Approvisionnement
Vous pouvez approvisionner un seul appareil ou plusieurs à la fois, en fonction des besoins de votre solution IoT Edge. Les options disponibles pour authentifier les communications entre les appareils IoT Edge et vos hubs IoT dépendent de la méthode d’approvisionnement choisie.
Vous pouvez approvisionner une chaîne de connexion, une clé de contenu, un certificat X.509, une clé privée de certificat d’identité ou un certificat d’identité. L’approvisionnement DPS est inclus avec différentes options. Choisissez une méthode pour votre approvisionnement. Remplacez les valeurs d’exemple par vos propres valeurs.
Approvisionnement manuel avec la chaîne de connexion
[provisioning]
source = "manual"
connection_string = "HostName=example.azure-devices.net;DeviceId=my-device;SharedAccessKey=<Shared access key>"
Pour plus d’informations sur la récupération des informations de l’approvisionnement, consultez Créer et approvisionner un appareil IoT Edge sur Linux à l’aide de clés de contenu.
Approvisionnement manuel avec clé symétrique
[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
Pour plus d’informations sur la récupération des informations de l’approvisionnement, consultez Créer et approvisionner un appareil IoT Edge sur Linux à l’aide de clés de contenu.
Approvisionnement manuel avec un certificat X.509
[provisioning]
source = "manual"
iothub_hostname = "example.azure-devices.net"
device_id = "my-device"
[provisioning.authentication]
method = "x509"
Pour plus d’informations sur l’approvisionnement à l’aide de certificats X.509, voir Créer et approvisionner un appareil IoT Edge sous Linux à l’aide de certificats X.509.
Approvisionnement DPS avec clé de contenu
[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" }
Pour plus d’informations sur l’approvisionnement DPS avec une clé symétrique, voir Créer et approvisionner des appareils IoT Edge à l’échelle sur Linux à l’aide d’une clé de contenu.
Approvisionnement du DPS avec des certificats 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
(Facultatif) Activer le renouvellement automatique du certificat d’ID d’appareil
Le renouvellement automatique nécessite une méthode d’émission de certificat connue. Définissez méthode sur est ou local_ca.
Important
Activez uniquement le renouvellement automatique si cet appareil est configuré pour l’inscription DPS basée sur l’autorité de certification. L’utilisation du renouvellement automatique pour une inscription individuelle entraîne l’impossibilité pour l’appareil de réapprovisionner l’appareil.
[provisioning.attestation.identity_cert.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"
Pour plus d’informations sur l’approvisionnement DPS avec des certificats X.509, voir Créer et approvisionner des appareils IoT Edge à l’échelle sur Linux à l’aide de certificats X.509.
Approvisionnement DPS avec TPM (module de plateforme approuvée)
[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 vous utilisez l’approvisionnement DPS avec TPM et que vous avez besoin d’une configuration personnalisée, consultez la section TPM.
Pour plus d’informations, voir Créer et approvisionner des appareils IoT Edge à l’échelle avec un TPM sur Linux.
Délai d’expiration du cloud et comportement de nouvelle tentative
Ces paramètres contrôlent le délai d’attente et les nouvelles tentatives pour les opérations dans le cloud, telles que la communication avec le service de provisionnement des appareils (DPS) pendant l’approvisionnement ou avec IoT Hub pour la création de l’identité du module.
Le paramètre cloud_timeout_sec est l’échéance en secondes pour une requête réseau adressée aux services cloud. Par exemple, une requête HTTP. Une réponse du service cloud doit être reçue avant cette échéance, ou la requête échoue en tant que délai d’expiration.
Le paramètre cloud_retries contrôle le nombre de fois qu’une requête peut être retentée après l’échec de la première tentative. Le client envoie toujours au moins une fois, de sorte que la valeur est le nombre de nouvelles tentatives après l’échec de la première tentative. Par exemple, cloud_retries = 2 signifie que le client effectue un total de trois tentatives.
cloud_timeout_sec = 10
cloud_retries = 1
Émission du certificat
Si vous avez configuré des certificats émis dynamiquement, choisissez votre méthode d’émission correspondante et remplacez les échantillons de valeurs par vos propres certificats.
Émission de certificat via EST
[cert_issuance.est]
trusted_certs = ["file:///var/aziot/certs/est-id-ca.pem",]
[cert_issuance.est.auth]
username = "estuser"
password = "estpwd"
Certificat d’ID EST déjà sur l’appareil
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
Certificat d’ID EST demandé via le certificat d’ID de démarrage EST
Authentification avec un certificat client TLS utilisé une fois pour créer le certificat d’ID EST initial. Après la première émission de certificat, une identity_cert et identity_pk sont automatiquement créées et utilisées pour les futures authentifications et renouvellements. Le nom commun de l’objet du certificat d’ID EST généré est toujours identique à l’ID d’appareil configuré dans la section d’approvisionnement. Ces fichiers doivent être lisibles par les utilisateurs aziotcs et aziotks, respectivement.
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"
Émission de certificat via l’autorité de certification locale
[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 (module de plateforme sécurisée)
Si vous avez besoin d’une configuration spéciale pour le TPM lorsque vous utilisez l’approvisionnement DPS TPM, utilisez ces paramètres TPM.
Pour connaître les chaînes de chargeur TCTI acceptables, consultez la section 3.5 de TCG TSS 2.0 TPM Command Transmission Interface (TCTI) Spécification de l’API.
La définition d’une chaîne vide entraîne le chargement d’une bibliothèque de chargeur TCTI ensemble prédéfini de modules TCTI dans l’ordre.
[tpm]
tcti = "swtpm:port=2321"
L’index TPM conserve la clé d’authentification DPS. L’index est pris comme offset de l’adresse de base pour les objets persistants tels que 0x81000000 et doit se trouver dans la plage de 0x00_00_00 à 0x7F_FF_FF. La valeur par défaut est 0x00_01_00.
auth_key_index = "0x00_01_00"
Utilisez des valeurs d’autorisation pour les hiérarchies d’approbation et de propriétaire, si nécessaire. Par défaut, ces valeurs sont des chaînes vides.
[tpm.hierarchy_authorization]
endorsement = "hello"
owner = "world"
PKCS#11
Si vous avez utilisé des URI PKCS#11, utilisez les paramètres suivants et remplacez les valeurs par votre configuration PKCS#11.
[aziot_keys]
pkcs11_lib_path = "/usr/lib/libmypkcs11.so"
pkcs11_base_slot = "pkcs11:slot-id=0?pin-value=1234"
Agent(e) Edge par défaut
Quand IoT Edge démarre la première fois, il démarre un module d’agent(e) Edge par défaut. Si vous devez remplacer les paramètres fournis au module de l’agent(e) Edge par défaut, utilisez cette section et remplacez les valeurs par vos propres valeurs.
Remarque
Le paramètre agent.config.createOptions est spécifié en tant que table inlined TOML. Ce format ressemble à JSON, mais il n’est pas JSON. Pour plus d’informations, consultez table inlined de la documentation 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"
Gestion des démons et points de terminaison d’API de charge de travail
Si vous devez remplacer les points de terminaison de l’API de gestion et de charge de travail, utilisez cette section et remplacez les valeurs par vos propres valeurs.
[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"
Agent(e) Edge surveillance
Si vous devez remplacer les paramètres de surveillance par défaut de l’Agent(e) Edge, utilisez cette section et remplacez les valeurs par vos propres paramètres.
[watchdog]
max_retries = "infinite" # the string "infinite" or a positive integer. Defaults to "infinite"
Certificat d'autorité de certification Edge
Si vous avez votre propre autorité de certification Edge certificat qui émet tous vos certificats de module, utilisez l’une de ces sections et remplacez les valeurs par vos propres.
Certificat d’autorité de certification Edge chargé à partir d’un fichier
[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
Certificat d’autorité de certification Edge émis via l’EST
[edge_ca]
method = "est"
Pour plus d’informations sur l’utilisation d’un serveur EST, consultez Tutoriel : Configurer un serveur EST pour Azure IoT Edge.
Configuration EST facultative pour l’émission du certificat d’autorité de certification Edge
Si ce n’est pas le cas, les valeurs par défaut dans [cert_issuance.est] sont utilisées.
common_name = "aziot-edge CA"
expiry_days = 90
url = "https://example.org/.well-known/est"
username = "estuser"
password = "estpwd"
Certificat d’ID EST déjà sur l’appareil
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
Certificat d’ID EST demandé via le certificat d’ID de démarrage 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
Certificat d’autorité de certification Edge émis à partir d’un certificat d’autorité de certification locale
Nécessite que [cert_issuance.local_ca] soit défini.
[edge_ca]
method = "local_ca"
# Optional configuration
common_name = "aziot-edge CA"
expiry_days = 90
Certificats de démarrage rapide de l’autorité de certification Edge
Si vous ne disposez pas de votre propre certificat Edge CA utilisé pour émettre tous les certificats de module, utilisez cette section et définissez le nombre de jours pour la durée de vie du certificat Edge CA autogénéré et auto-signé. L’expiration est fixée par défaut à 90 jours.
Attention
Ce réglage n’est PAS recommandé pour une utilisation en production. Veuillez configurer votre propre certificat d’autorité de certification Edge dans les sections relatives au certificat d’autorité de certification Edge.
[edge_ca]
auto_generated_edge_ca_expiry_days = 90
Renouvellement du certificat de l autorité de certification Edge
Ce paramètre gère la récupération automatique du certificat d’autorité de certification Edge. La récupération automatique s’applique lorsque l’autorité de certification Edge est configurée en tant que démarrage rapide ou lorsque l’autorité de certification Edge dispose d’un method d’émission défini. Les certificats d’autorité de certification Edge chargés à partir de fichiers ne peuvent généralement pas être renouvelés automatiquement, car le moteur d’exécution Edge ne dispose pas de suffisamment d’informations pour les renouveler.
Important
Le renouvellement d’une autorité de certification Edge nécessite la régénération de tous les certificats de serveur émis par cette autorité de certification. Cette régénération est effectuée en redémarrant tous les modules. L’heure du renouvellement de l’autorité de certification Edge ne peut pas être garantie. Si les redémarrages aléatoires de modules sont inacceptables pour votre cas d’utilisation, désactivez le renouvellement automatique.
[edge_ca.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"
Garbage collection d’images
Si vous devez modifier la configuration par défaut du garbage collection d’images, utilisez cette section et remplacez les valeurs qu’elle contient par les vôtres.
| Paramètre | Description |
|---|---|
enabled |
Exécute Garbage collection d’images |
cleanup_recurrence |
Fréquence à laquelle vous souhaitez que le garbage collection d’images s’exécute |
image_age_cleanup_threshold |
L’âge des images inutilisées. Les images antérieures au seuil sont supprimées |
cleanup_time |
Format HH :MM de 24 heures. Lorsque la tâche de nettoyage est exécutée |
[image_garbage_collection]
enabled = true
cleanup_recurrence = "1d"
image_age_cleanup_threshold = "7d"
cleanup_time = "00:00"
Série de tests Moby
Si vous devez remplacer la configuration par défaut de Moby de série de tests, utilisez cette section et remplacez les valeurs par les vôtres.
[moby_runtime]
uri = "unix:///var/run/docker.sock"
network = "azure-iot-edge"