Configurare le impostazioni del dispositivo IoT Edge

Si applica a: IoT Edge 1.5 IoT Edge 1.4

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

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:

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.

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

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

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

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

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