Configurare le impostazioni del dispositivo IoT Edge
Si applica a: 
IoT Edge 1.5 IoT Edge 1.4
Importante
IoT Edge 1.5 LTS e IoT Edge 1.4 LTS sono versioni supportate. IoT Edge 1.4 LTS raggiungerà il fine vita il 12 novembre 2024. Se si usa una versione precedente, vedere Aggiornare IoT Edge.
Questo articolo illustra le impostazioni e le opzioni per la configurazione del file di IoT Edge /etc/aziot/config.toml di un dispositivo IoT Edge. IoT Edge usa il file config.toml per inizializzare le impostazioni per il dispositivo. Ognuna delle sezioni del file config.toml include diverse opzioni. Non tutte le opzioni sono obbligatorie perché si applicano a scenari specifici.
Un modello contenente tutte le opzioni è disponibile nel file config.toml.edge.template all’interno della directory /etc/aziot in un dispositivo IoT Edge. È possibile copiare il contenuto dell’intero modello o delle sezioni del modello nel file config.toml. Rimuovere il commento dalle sezioni necessarie. Tenere presente che non copiare i parametri già definiti.
Se si modifica la configurazione di un dispositivo, usare sudo iotedge config apply per applicare le modifiche.
Parametri globali
I parametri hostname, parent_hostname, trust_bundle_cert, allow_elevated_docker_permissions e auto_reprovisioning_mode devono essere all’inizio del file di configurazione prima di qualsiasi altra sezione. L’aggiunta di parametri prima di una raccolta di impostazioni garantisce che vengano applicate correttamente. Per altre informazioni sulla sintassi valida, vedere toml.io.
Hostname (Nome host)
Per abilitare l’individuazione del gateway, ogni dispositivo gateway IoT Edge (padre) deve specificare un parametro hostname usato dai dispositivi figlio per trovarlo nella rete locale. Il modulo edgeHub usa anche il parametro hostname per trovare la corrispondenza con il relativo certificato server. Per altre informazioni, vedere Perché a EdgeGateway deve essere indicato il proprio hostname?.
Nota
Quando il valore hostname non è impostato, IoT Edge tenta di trovarlo automaticamente. Tuttavia, i client nella rete potrebbero non essere in grado di individuare il dispositivo se non è impostato.
Per hostname, sostituire fqdn-device-name-or-ip-address con il nome del dispositivo per eseguire l’override dell’hostname predefinito del dispositivo. Il valore può essere un nome di dominio completo (FQDN) o un indirizzo IP. Usare questa impostazione come nome host del gateway in un dispositivo gateway IoT Edge.
hostname = "fqdn-device-name-or-ip-address"
Nome host padre
Il nome host padre viene usato quando il dispositivo IoT Edge fa parte di una gerarchia, altrimenti nota come edge annidato. Ogni dispositivo IoT Edge downstream deve specificare un parametro parent_hostname per identificare il relativo elemento padre. In uno scenario gerarchico in cui un singolo dispositivo IoT Edge è sia un dispositivo padre che un dispositivo figlio, sono necessari entrambi i parametri.
Sostituire fqdn-parent-device-name-or-ip-address con il nome del dispositivo padre. Usare un nome host di lunghezza inferiore a 64 caratteri, ovvero il limite di caratteri per un nome comune del certificato del server.
parent_hostname = "fqdn-parent-device-name-or-ip-address"
Per altre informazioni sull’impostazione del parametro parent_hostname, vedere Connettere i dispositivi Azure IoT Edge insieme per creare una gerarchia.
Certificato del bundle di attendibilità
Per fornire un’Autorità di certificazione (CA) personalizzata come radice di attendibilità per IoT Edge e i moduli, specificare una configurazione trust_bundle_cert. Sostituire il valore del parametro con l’URI del file nel certificato della CA radice nel dispositivo.
trust_bundle_cert = "file:///var/aziot/certs/trust-bundle.pem"
Per altre informazioni sul bundle di attendibilità di IoT Edge, vedere Gestire l’autorità di certificazione radice attendibile.
Autorizzazioni Docker elevate
Alcune funzionalità di Docker possono essere usate per ottenere accesso alla radice. Per impostazione predefinita, il flag --privileged e tutte le funzionalità elencate nel parametro CapAdd del Docker HostConfig sono consentite.
Se nessun modulo richiede funzionalità privilegiate o aggiuntive, usare allow_elevated_docker_permissions per migliorare la sicurezza del dispositivo.
allow_elevated_docker_permissions = false
Modalità di reprovisioning automatico
Il parametro facoltativo auto_reprovisioning_mode specifica le condizioni che decidono quando un dispositivo tenta di eseguire automaticamente il reprovisioning con il servizio di provisioning di dispositivi. La modalità di provisioning automatico viene ignorata se il provisioning del dispositivo è stato effettuato manualmente. Per altre informazioni sull’impostazione della modalità di provisioning DPS, vedere la sezione Provisioning in questo articolo.
È possibile impostare uno dei valori seguenti:
| Modalità | Descrizione |
|---|---|
| Dinamico | Effettuare il reprovisioning quando il dispositivo rileva che potrebbe essere stato spostato da un hub IoT a un altro. Questa modalità è la predefinita. |
| AlwaysOnStartup | Effettuare il reprovisioning quando il dispositivo viene riavviato o un arresto anomalo causa il riavvio dei daemon. |
| OnErrorOnly | Non attivare mai il reprovisioning automatico del dispositivo. Il reprovisioning del dispositivo si verifica solo come fallback, se il dispositivo non è in grado di connettersi all’hub IoT durante il provisioning delle identità a causa di errori di connettività. Questo comportamento di fallback è implicito anche nelle modalità Dinamico e AlwaysOnStartup. |
Ad esempio:
auto_reprovisioning_mode = "Dynamic"
Per altre informazioni sul reprovisioning dei dispositivi, vedere Concetti relativi al reprovisioning dei dispositivi dell’hub IoT.
Provisioning
È possibile effettuare il provisioning di un singolo dispositivo o di più dispositivi su larga scala, a seconda delle esigenze della soluzione IoT Edge. Le opzioni disponibili per l’autenticazione delle comunicazioni tra i dispositivi IoT Edge e gli hub IoT dipendono dal metodo di provisioning scelto.
È possibile eseguire il provisioning con una stringa di connessione, una chiave simmetrica, un certificato X.509, una chiave privata del certificato di identità o un certificato di identità. Il provisioning DPS è incluso con varie opzioni. Scegliere un metodo per il provisioning. Sostituire i valori di esempio con i propri.
Provisioning manuale con stringa di connessione
[provisioning]
source = "manual"
connection_string = "HostName=example.azure-devices.net;DeviceId=my-device;SharedAccessKey=<Shared access key>"
Per altre informazioni sul recupero delle informazioni di provisioning, vedere Creare ed effettuare il provisioning di un dispositivo IoT Edge in Linux usando chiavi simmetriche.
Provisioning manuale con chiave simmetrica
[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
Per altre informazioni sul recupero delle informazioni di provisioning, vedere Creare ed effettuare il provisioning di un dispositivo IoT Edge in Linux usando chiavi simmetriche.
Provisioning manuale con certificato X.509
[provisioning]
source = "manual"
iothub_hostname = "example.azure-devices.net"
device_id = "my-device"
[provisioning.authentication]
method = "x509"
Per altre informazioni sul provisioning con i certificati X.509, vedere Creare ed effettuare il provisioning di un dispositivo IoT Edge in Linux usando certificati X.509.
Provisioning DPS con chiave simmetrica
[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" }
Per altre informazioni sul provisioning DPS con chiave simmetrica, vedere Creare ed effettuare il provisioning di dispositivi IoT Edge su larga scala in Linux usando la chiave simmetrica.
Provisioning DPS con certificati 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
(Facoltativo) Abilitare il rinnovo automatico del certificato ID dispositivo
Il rinnovo automatico richiede un metodo di rilascio di certificati noto. Impostare metodo su est o local_ca.
Importante
Abilitare il rinnovo automatico solo se questo dispositivo è configurato per la registrazione DPS basata su Autorità di certificazione. L’uso del rinnovo automatico per una registrazione singola fa in modo che il dispositivo non sia in grado di eseguire il reprovisioning.
[provisioning.attestation.identity_cert.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"
Per altre informazioni sul provisioning DPS con certificati X.509, vedere Creare ed effettuare il provisioning di dispositivi IoT Edge su larga scala in Linux usando certificati X.509.
Provisioning DPS con TPM (Trusted Platform Module)
[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"
Se si usa il provisioning DPS con TPM e si richiede una configurazione personalizzata, vedere la sezione TPM.
Per altre informazioni, vedere Creare ed eseguire il provisioning di dispositivi IoT Edge su larga scala con un TPM in Linux.
Timeout e comportamento di ripetizione dei tentativi cloud
Queste impostazioni controllano il timeout e la ripetizione dei tentativi per le operazioni cloud, ad esempio la comunicazione con il DPS (servizio Device Provisioning) durante il provisioning o la creazione dell’hub IoT per la creazione dell’identità del modulo.
Il parametro cloud_timeout_sec è la scadenza in secondi per una richiesta di rete ai servizi cloud. Ad esempio, una richiesta HTTP. Una risposta dal servizio cloud deve essere ricevuta prima di questa scadenza oppure la richiesta avrà esito di timeout negativo.
Il parametro cloud_retries controlla quante volte può essere ritentata una richiesta dopo il primo tentativo non riuscito. Il client effettua sempre un invio almeno una volta, quindi il valore è il numero di tentativi dopo il primo tentativo non riuscito. Ad esempio, cloud_retries = 2 significa che il client esegue un totale di tre tentativi.
cloud_timeout_sec = 10
cloud_retries = 1
Rilascio di certificati
Se sono stati configurati certificati rilasciati dinamicamente, scegliere il metodo di rilascio corrispondente e sostituire i valori di esempio con i propri.
Rilascio di certificati tramite EST
[cert_issuance.est]
trusted_certs = ["file:///var/aziot/certs/est-id-ca.pem",]
[cert_issuance.est.auth]
username = "estuser"
password = "estpwd"
Certificato di ID EST già nel 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
Certificato di ID EST richiesto tramite certificato di ID bootstrap EST
Autenticazione con un certificato client TLS usato una volta per creare il certificato di ID EST iniziale. Dopo il primo rilascio di certificati, vengono creati automaticamente identity_cert e identity_pk per l’autenticazione e i rinnovi futuri. Il nome comune soggetto del certificato di ID EST generato è sempre uguale all’ID dispositivo configurato nella sezione provisioning. Questi file devono essere leggibili rispettivamente dagli utenti aziotcs e 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"
Rilascio di certificati tramite Autorità di certificazione 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 (Trusted Platform Module)
Se è necessaria una configurazione speciale per il TPM quando si usa il provisioning TPM DPS, usare queste impostazioni TPM.
Per le stringhe del caricatore TCTI accettabili, vedere la sezione 3.5 di Specifiche dell’API TCG TSS 2.0 TPM Command Transmission Interface (TCTI).
Se si imposta su una stringa vuota, la libreria del caricatore TCTI proverà a caricare un set predefinito di moduli TCTI in ordine.
[tpm]
tcti = "swtpm:port=2321"
L’indice TPM mantiene la chiave di autenticazione DPS. L’indice viene considerato come offset dall’indirizzo di base per oggetti persistenti, ad esempio 0x81000000 e deve trovarsi nell’intervallo compreso tra 0x00_00_00 e 0x7F_FF_FF. Il valore predefinito è 0x00_01_00.
auth_key_index = "0x00_01_00"
Se necessario, usare i valori di autorizzazione per le gerarchie di approvazione e del proprietario. Per impostazione predefinita, questi valori sono stringhe vuote.
[tpm.hierarchy_authorization]
endorsement = "hello"
owner = "world"
PKCS#11
Se sono stati usati URI PKCS#11, usare i parametri seguenti e sostituire i valori con la configurazione PKCS#11.
[aziot_keys]
pkcs11_lib_path = "/usr/lib/libmypkcs11.so"
pkcs11_base_slot = "pkcs11:slot-id=0?pin-value=1234"
Agente Edge predefinito
Quando IoT Edge viene avviato per la prima volta, esegue il bootstrap di un modulo predefinito dell’agente Edge. Se è necessario eseguire l’override dei parametri forniti al modulo predefinito di agente Edge, usare questa sezione e sostituire i valori con i propri.
Nota
Il parametro agent.config.createOptions viene specificato come tabella inline TOML. Questo formato sembra JSON ma non lo è. Per altre informazioni, vedere tabella inline della documentazione di 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"
Endpoint dell’API dei carichi di lavoro e gestione del daemon
Se è necessario eseguire l’override degli endpoint dell’API dei carichi di lavoro e la gestione, usare questa sezione e sostituire i valori con i propri.
[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"
Watchdog dell’agente Edge
Se è necessario eseguire l’override delle impostazioni predefinite del watchdog dell’agente Edge, usare questa sezione e sostituire i valori con i propri.
[watchdog]
max_retries = "infinite" # the string "infinite" or a positive integer. Defaults to "infinite"
Certificato della CA perimetrale
Se si dispone di un certificato Autorità di certificazione Edge che rilascia tutti i certificati del modulo, usare una di queste sezioni e sostituire i valori con i propri.
Certificato della CA Edge caricato da un file
[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
Certificato della CA Edge rilasciato tramite EST
[edge_ca]
method = "est"
Per altre informazioni sull’uso di un server EST, vedere Esercitazione: configurare la registrazione tramite server di trasporto sicuro per Azure IoT Edge.
Configurazione EST facoltativa per il rilascio del certificato della CA Edge
Se non è impostata, vengono usate le impostazioni predefinite in [cert_issuance.est].
common_name = "aziot-edge CA"
expiry_days = 90
url = "https://example.org/.well-known/est"
username = "estuser"
password = "estpwd"
Certificato di ID EST già nel 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
Certificato di ID EST richiesto tramite certificato di ID bootstrap 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
Certificato della CA Edge emesso da un certificato della CA locale
È necessario impostare [cert_issuance.local_ca].
[edge_ca]
method = "local_ca"
# Optional configuration
common_name = "aziot-edge CA"
expiry_days = 90
Certificati di avvio rapido della CA
Se non si dispone del proprio certificato della CA Edge usato per rilasciare tutti i certificati del modulo, usare questa sezione e impostare il numero di giorni per la durata del certificato della CA Edge autofirmato e generato automaticamente. Per impostazione predefinita, la scadenza è 90 giorni.
Attenzione
Questa impostazione NON è consigliata per l’uso in produzione. Configurare il proprio certificato della CA Edge nelle sezioni del certificato della CA Edge.
[edge_ca]
auto_generated_edge_ca_expiry_days = 90
Rinnovo automatico del certificato della CA Edge
Questa impostazione gestisce il rinnovo automatico del certificato della CA Edge. Il rinnovo automatico si applica quando la CA Edge è configurata come avvio rapido o quando la CA Edge ha un rilascio impostato su method. I certificati della CA Edge caricati dai file in genere non possono essere rinnovati automaticamente perché il runtime di Edge non dispone di informazioni sufficienti per rinnovarli.
Importante
Per il rinnovo di una CA Edge è necessario rigenerare tutti i certificati server rilasciati dalla CA. Questa rigenerazione viene eseguita riavviando tutti i moduli. Il tempo di rinnovo della CA Edge non può essere garantito. Se i riavvii casuali del modulo non sono accettabili per il proprio caso d’uso, disabilitare il rinnovo automatico senza includere la sezione [edge_ca.auto_renew].
[edge_ca.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"
GC delle immagini
Se è necessario eseguire l’override della configurazione predefinita GC delle immagini, usare questa sezione e sostituire i valori in questa sezione con i propri.
| Parametro | Descrizione |
|---|---|
enabled |
Esegue l’operazione GC delle immagini |
cleanup_recurrence |
Frequenza con cui eseguire la GC delle immagini |
image_age_cleanup_threshold |
L’età di immagini inutilizzate. Le immagini che superano la soglia d’età vengono rimosse |
cleanup_time |
Formato HH:MM di 24 ore. Quando viene eseguito il processo di pulizia |
[image_garbage_collection]
enabled = true
cleanup_recurrence = "1d"
image_age_cleanup_threshold = "7d"
cleanup_time = "00:00"
Runtime Moby
Se è necessario eseguire l’override della configurazione predefinita del runtime Moby, usare questa sezione e sostituire i valori con i propri.
[moby_runtime]
uri = "unix:///var/run/docker.sock"
network = "azure-iot-edge"