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 è di 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 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 Why does EdgeGateway need to be told about its own 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 del nome host 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 noto come arco 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, richiede entrambi i parametri.
Sostituire fqdn-parent-device-name-or-ip-address con il nome del dispositivo padre. Usare un nome host più breve di 64 caratteri, ovvero il limite di caratteri per un nome comune del certificato server.
parent_hostname = "fqdn-parent-device-name-or-ip-address"
Per altre informazioni sull'impostazione del parametro parent_hostname, vedere Connessione dispositivi Azure IoT Edge insieme per creare una gerarchia.
Certificato del bundle di attendibilità
Per fornire un certificato dell'autorità di certificazione (CA) personalizzato 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 con il certificato CA radice nel dispositivo.
trust_bundle_cert = "file:///var/aziot/certs/trust-bundle.pem"
Per altre informazioni sul bundle di trust di IoT Edge, vedere Gestire la CA radice attendibile.
Autorizzazioni Docker elevate
Alcune funzionalità di Docker possono essere usate per ottenere l'accesso alla radice. Per impostazione predefinita, il --privileged flag e tutte le funzionalità elencate nel parametro CapAdd di 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 provisioning automatico
Il parametro facoltativo auto_reprovisioning_mode specifica le condizioni che decidono quando un dispositivo tenta di eseguire automaticamente il provisioning con il servizio Device Provisioning. 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 per altre informazioni.
È possibile impostare uno dei valori seguenti:
| Mode | Descrizione |
|---|---|
| Dinamico | Effettuare il reprovisioning quando il dispositivo rileva che potrebbe essere stato spostato da un hub IoT a un altro. Questa modalità è l'impostazione predefinita. |
| AlwaysOnStartup | Il reprovisioning quando il dispositivo viene riavviato o un arresto anomalo causa il riavvio dei daemon. |
| OnErrorOnly | Non attivare mai il provisioning automatico del dispositivo. Il provisioning del dispositivo si verifica solo come fallback, se il dispositivo non è in grado di connettersi a hub IoT durante il provisioning delle identità a causa di errori di connettività. Questo comportamento di fallback è implicito anche nelle modalità Dynamic e AlwaysOnStartup. |
Ad esempio:
auto_reprovisioning_mode = "Dynamic"
Per altre informazioni sul reprovisioning dei dispositivi, vedere hub IoT Concetti relativi al provisioning dei dispositivi.
Provisioning in corso
È 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 chiave 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 in 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 sul 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 sul 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 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
L'autorenewal richiede un metodo di rilascio di certificati noto. Impostare il metodo su est o local_ca.
Importante
Abilitare l'autorenewal solo se questo dispositivo è configurato per la registrazione del servizio Device Provisioning basato su CA. L'uso dell'autorenewal per una registrazione singola fa sì che il dispositivo non sia in grado di eseguire nuovamente il provisioning.
[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 effettuare il provisioning di dispositivi IoT Edge su larga scala con un TPM in Linux.
Timeout cloud e comportamento di ripetizione dei tentativi
Queste impostazioni controllano il timeout e i tentativi per le operazioni cloud, ad esempio la comunicazione con il servizio Device Provisioning durante il provisioning o 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 ha esito negativo come timeout.
Il parametro cloud_retries controlla quante volte può essere ritentata una richiesta dopo il primo tentativo non riuscito. Il client invia sempre 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 effettua 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 CON 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 DELL'ID EST richiesto tramite certificato di bootstrap EST
Autenticazione con un certificato client TLS usato una volta per creare il certificato ID EST iniziale. Dopo il primo rilascio del certificato, un e identity_certidentity_pk vengono creati e usati automaticamente per l'autenticazione e i rinnovi futuri. Il nome comune soggetto (CN) del certificato EST ID generato è sempre uguale all'ID dispositivo configurato nella sezione provisioning. Questi file devono essere leggibili rispettivamente dagli utenti aziotc 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 ca 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 della specifica dell'API TCG TSS 2.0 TPM Command Transmission Interface (TCTI).
Se si imposta su una stringa vuota, la libreria del caricatore TCTI prova 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 0x81000000 esempio 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"
Usare i valori di autorizzazione per le gerarchie di verifica dell'autenticità e del proprietario, se necessario. 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 Edge Agent, usare questa sezione e sostituire i valori con i propri.
Nota
Il agent.config.createOptions parametro viene specificato come tabella inline TOML. Questo formato è JSON, ma non è JSON. 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 del daemon e gestione del carico di lavoro
Se è necessario eseguire l'override degli endpoint api di gestione e carico di lavoro, 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 di Edge Agent, 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 della CA Edge che rilascia tutti i certificati del modulo, usare una di queste sezioni e sostituire i valori con i propri.
Certificato 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 CA Edge rilasciato su EST
[edge_ca]
method = "est"
Per altre informazioni sull'uso di un server EST, vedere Esercitazione: Configurare la registrazione su Secure Transport Server per Azure IoT Edge.
Configurazione EST facoltativa per il rilascio del certificato CA Edge
Se non è impostato, 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 CON 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 DELL'ID EST richiesto tramite certificato di 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 CA Edge emesso da un certificato 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 Edge
Se non si ha il proprio certificato ca Edge usato per rilasciare tutti i certificati del modulo, usare questa sezione e impostare il numero di giorni per la durata del certificato ca Edge autofirmato generato automaticamente. Per impostazione predefinita, la scadenza è 90 giorni.
Attenzione
Questa impostazione non è consigliata per l'utilizzo di produzione. Configurare il proprio certificato CA Edge nelle sezioni del certificato della CA Edge.
[edge_ca]
auto_generated_edge_ca_expiry_days = 90
Autorenewal del certificato CA Edge
Questa impostazione gestisce la firma automatica del certificato della CA Edge. L'autorenewal si applica quando la CA edge è configurata come guida introduttiva o quando l'autorità di certificazione edge ha un set di rilascio method . I certificati CA Edge caricati dai file in genere non possono essere rinuovi automaticamente perché il runtime di Edge non dispone di informazioni sufficienti per rinnovarli.
Importante
Per il rinnovo di un'autorità di certificazione perimetrale è 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 caso d'uso, disabilitare la riattivazione automatica.
[edge_ca.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"
Garbage Collection di immagini
Se è necessario eseguire l'override della configurazione predefinita di Garbage Collection delle immagini, usare questa sezione e sostituire i valori in questa sezione con i propri.
| Parametro | Descrizione |
|---|---|
enabled |
Esegue l'operazione di Garbage Collection delle immagini |
cleanup_recurrence |
Frequenza con cui eseguire l'operazione di Garbage Collection dell'immagine |
image_age_cleanup_threshold |
Età delle immagini inutilizzate. Le immagini precedenti alla soglia 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"
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per