IoT Edge-apparaatinstellingen configureren
Dit artikel bevat instellingen en opties voor het configureren van het IoT Edge-bestand /etc/aziot/config.toml-bestand van een IoT Edge-apparaat. IoT Edge maakt gebruik van het bestand config.toml om instellingen voor het apparaat te initialiseren. Elk van de secties van het bestand config.toml heeft verschillende opties. Niet alle opties zijn verplicht, omdat ze van toepassing zijn op specifieke scenario's.
Een sjabloon met alle opties vindt u in het bestand config.toml.edge.template in de map /etc/aziot op een IoT Edge-apparaat. U kunt de inhoud van de hele sjabloon of secties van de sjabloon kopiëren naar het bestand config.toml . Verwijder opmerkingen bij de secties die u nodig hebt. Houd er rekening mee dat u niet kopieert over parameters die u al hebt gedefinieerd.
Als u de configuratie van een apparaat wijzigt, gebruikt sudo iotedge config apply u deze om de wijzigingen toe te passen.
Globale parameters
De parameters hostnaam, parent_hostname, trust_bundle_cert, allow_elevated_docker_permissions en auto_reprovisioning_mode moeten zich vóór andere secties aan het begin van het configuratiebestand bevinden. Door parameters toe te voegen voordat een verzameling instellingen wordt toegepast, wordt deze correct toegepast. Zie toml.io voor meer informatie over geldige syntaxis.
Hostnaam
Als u gatewaydetectie wilt inschakelen, moet elk IoT Edge-gatewayapparaat (bovenliggend) een hostnaamparameter opgeven die de onderliggende apparaten gebruiken om het op het lokale netwerk te vinden. De edgeHub-module gebruikt ook de hostnaamparameter om overeen te komen met het servercertificaat. Zie Waarom moet EdgeGateway over zijn eigen hostnaam worden verteld voor meer informatie.
Notitie
Wanneer de waarde van de hostnaam niet is ingesteld, probeert IoT Edge deze automatisch te vinden. Clients in het netwerk kunnen het apparaat mogelijk niet detecteren als het niet is ingesteld.
Vervang voor hostnaam fqdn-device-name-or-ip-address door uw apparaatnaam om de standaardhostnaam van het apparaat te overschrijven. De waarde kan een FQDN (Fully Qualified Domain Name) of een IP-adres zijn. Gebruik deze instelling als de hostnaam van de gateway op een IoT Edge-gatewayapparaat.
hostname = "fqdn-device-name-or-ip-address"
Bovenliggende hostnaam
Bovenliggende hostnaam wordt gebruikt wanneer het IoT Edge-apparaat deel uitmaakt van een hiërarchie, ook wel een geneste rand genoemd. Elk downstream IoT Edge-apparaat moet een parent_hostname parameter opgeven om het bovenliggende apparaat te identificeren. In een hiërarchisch scenario waarbij één IoT Edge-apparaat zowel een bovenliggend als een onderliggend apparaat is, heeft het beide parameters nodig.
Vervang fqdn-parent-device-name-or-ip-address door de naam van het bovenliggende apparaat. Gebruik een hostnaam die korter is dan 64 tekens. Dit is de tekenlimiet voor een algemene naam van een servercertificaat.
parent_hostname = "fqdn-parent-device-name-or-ip-address"
Zie Verbinding maken Azure IoT Edge-apparaten samen om een hiërarchie te maken voor meer informatie over het instellen van de parameter parent_hostname.
Vertrouwensbundelcertificaat
Als u een aangepast CA-certificaat (certificate authority) wilt opgeven als basis voor vertrouwen voor IoT Edge en modules, geeft u een trust_bundle_cert-configuratie op. Vervang de parameterwaarde door de bestands-URI naar het basis-CA-certificaat op uw apparaat.
trust_bundle_cert = "file:///var/aziot/certs/trust-bundle.pem"
Zie Vertrouwde basis-CA beheren voor meer informatie over de IoT Edge-vertrouwensbundel.
Docker-machtigingen met verhoogde bevoegdheid
Sommige docker-mogelijkheden kunnen worden gebruikt om toegang te krijgen tot de hoofdmap. Standaard zijn de --privileged vlag en alle mogelijkheden die worden vermeld in de CapAdd-parameter van de docker HostConfig toegestaan.
Als er geen modules bevoegde of extra mogelijkheden nodig hebben, gebruikt u allow_elevated_docker_permissions om de beveiliging van het apparaat te verbeteren.
allow_elevated_docker_permissions = false
Modus voor automatisch opnieuw inrichten
De optionele auto_reprovisioning_mode parameter geeft de voorwaarden aan die bepalen wanneer een apparaat probeert automatisch opnieuw te inrichten met Device Provisioning Service. De automatische inrichtingsmodus wordt genegeerd als het apparaat handmatig is ingericht. Zie de sectie Inrichten in dit artikel voor meer informatie over het instellen van de DPS-inrichtingsmodus .
Een van de volgende waarden kan worden ingesteld:
| Modus | Beschrijving |
|---|---|
| Dynamisch | Opnieuw inrichten wanneer het apparaat detecteert dat het mogelijk is verplaatst van de ene IoT Hub naar het andere. Deze modus is de standaardinstelling. |
| AlwaysOnStartup | Opnieuw inrichten wanneer het apparaat opnieuw wordt opgestart of een crash zorgt ervoor dat de daemons opnieuw worden opgestart. |
| OnErrorOnly | Activeer het opnieuw inrichten van apparaten nooit automatisch. Het opnieuw inrichten van apparaten treedt alleen op als terugval, als het apparaat geen verbinding kan maken met IoT Hub tijdens het inrichten van identiteiten vanwege connectiviteitsfouten. Dit terugvalgedrag is ook impliciet in dynamische en AlwaysOnStartup-modi. |
Voorbeeld:
auto_reprovisioning_mode = "Dynamic"
Zie concepten voor het opnieuw inrichten van IoT Hub-apparaten voor meer informatie over het opnieuw inrichten van apparaten.
Inrichting
U kunt één apparaat of meerdere apparaten op schaal inrichten, afhankelijk van de behoeften van uw IoT Edge-oplossing. Welke opties beschikbaar zijn voor het verifiëren van communicatie tussen uw IoT Edge-apparaten en uw IoT-hubs, is afhankelijk van de inrichtingsmethode die u kiest.
U kunt inrichten met een verbindingsreeks, symmetrische sleutel, X.509-certificaat, persoonlijke sleutel voor identiteitscertificaten of een identiteitscertificaat. DPS-inrichting is opgenomen in verschillende opties. Kies één methode voor uw inrichting. Vervang de voorbeeldwaarden door uw eigen waarden.
Handmatig inrichten met verbindingsreeks
[provisioning]
source = "manual"
connection_string = "HostName=example.azure-devices.net;DeviceId=my-device;SharedAccessKey=<Shared access key>"
Zie Een IoT Edge-apparaat in Linux maken en inrichten met behulp van symmetrische sleutels voor meer informatie over het ophalen van inrichtingsgegevens.
Handmatig inrichten met symmetrische sleutel
[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
Zie Een IoT Edge-apparaat in Linux maken en inrichten met behulp van symmetrische sleutels voor meer informatie over het ophalen van inrichtingsgegevens.
Handmatig inrichten met X.509-certificaat
[provisioning]
source = "manual"
iothub_hostname = "example.azure-devices.net"
device_id = "my-device"
[provisioning.authentication]
method = "x509"
Zie Een IoT Edge-apparaat in Linux maken en inrichten met X.509-certificaten voor meer informatie over het inrichten met X.509-certificaten.
DPS-inrichting met symmetrische sleutel
[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" }
Zie IoT Edge-apparaten op schaal maken en inrichten in Linux met behulp van een symmetrische sleutel voor meer informatie over DPS-inrichting met een symmetrische sleutel.
DPS-inrichting met X.509-certificaten
[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
(Optioneel) Automatische verlenging van het apparaat-id-certificaat inschakelen
Autorenewal vereist een bekende certificaatuitgiftemethode. Methode instellen op of estlocal_ca.
Belangrijk
Schakel autorenewal alleen in als dit apparaat is geconfigureerd voor OP CA gebaseerde DPS-inschrijving. Als u autorenewal gebruikt voor een afzonderlijke inschrijving, kan het apparaat de inrichting niet opnieuw inrichten.
[provisioning.attestation.identity_cert.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"
Zie IoT Edge-apparaten op schaal maken en inrichten met X.509-certificaten voor meer informatie over DPS-inrichting met X.509-certificaten.
DPS-inrichting met 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"
Als u DPS-inrichting met TPM gebruikt en aangepaste configuratie vereist, raadpleegt u de sectie TPM .
Zie IoT Edge-apparaten op schaal maken en inrichten met een TPM op Linux voor meer informatie.
Gedrag van time-out en opnieuw proberen in de cloud
Deze instellingen bepalen de time-out en nieuwe pogingen voor cloudbewerkingen, zoals communicatie met Device Provisioning Service (DPS) tijdens het inrichten of IoT Hub voor het maken van module-identiteiten.
De parameter cloud_timeout_sec is de deadline in seconden voor een netwerkaanvraag voor cloudservices. Bijvoorbeeld een HTTP-aanvraag. Een reactie van de cloudservice moet vóór deze deadline worden ontvangen of de aanvraag mislukt als een time-out.
De cloud_retries parameter bepaalt hoe vaak een aanvraag opnieuw kan worden geprobeerd nadat de eerste poging is mislukt. De client verzendt altijd ten minste één keer, dus de waarde is het aantal nieuwe pogingen nadat de eerste poging is mislukt. Betekent bijvoorbeeld cloud_retries = 2 dat de client in totaal drie pogingen uitvoert.
cloud_timeout_sec = 10
cloud_retries = 1
Certificaatuitgifte
Als u dynamisch uitgegeven certificaten hebt geconfigureerd, kiest u de bijbehorende uitgiftemethode en vervangt u de voorbeeldwaarden door uw eigen certificaatwaarden.
Certificaatuitgifte via EST
[cert_issuance.est]
trusted_certs = ["file:///var/aziot/certs/est-id-ca.pem",]
[cert_issuance.est.auth]
username = "estuser"
password = "estpwd"
EST ID-certificaat al op apparaat
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
EST ID-certificaat aangevraagd via EST bootstrap ID-certificaat
Verificatie met een TLS-clientcertificaat dat eenmaal wordt gebruikt om het oorspronkelijke EST ID-certificaat te maken. Na de eerste certificaatuitgifte worden een identity_cert en identity_pk automatisch gemaakt en gebruikt voor toekomstige verificatie en verlengingen. De algemene naam van het onderwerp (CN) van het gegenereerde EST ID-certificaat is altijd hetzelfde als de geconfigureerde apparaat-id in de sectie voor het inrichten. Deze bestanden moeten respectievelijk leesbaar zijn voor de gebruikers aziotcs en 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"
Certificaatuitgifte via lokale CA
[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)
Als u speciale configuratie voor de TPM nodig hebt bij het gebruik van DPS TPM-inrichting, gebruikt u deze TPM-instellingen.
Zie sectie 3.5 van TCG TSS 2.0 TPM Command Transmission Interface (TCTI) API-specificatie voor acceptabele TCTI-laadreeksen.
Als u een lege tekenreeks instelt, kan de TCTI-laadprogrammabibliotheek een vooraf gedefinieerde set TCTI-modules in volgorde laden.
[tpm]
tcti = "swtpm:port=2321"
De TPM-index blijft de DPS-verificatiesleutel behouden. De index wordt genomen als een verschuiving van het basisadres voor permanente objecten, zoals 0x81000000 en moet liggen in het bereik van 0x00_00_00 tot 0x7F_FF_FF. De standaardwaarde is 0x00_01_00.
auth_key_index = "0x00_01_00"
Gebruik indien nodig autorisatiewaarden voor goedkeurings- en eigenaarhiërarchieën. Deze waarden zijn standaard lege tekenreeksen.
[tpm.hierarchy_authorization]
endorsement = "hello"
owner = "world"
PKCS#11
Als u PKCS#11 URI's hebt gebruikt, gebruikt u de volgende parameters en vervangt u de waarden door uw PKCS#11-configuratie.
[aziot_keys]
pkcs11_lib_path = "/usr/lib/libmypkcs11.so"
pkcs11_base_slot = "pkcs11:slot-id=0?pin-value=1234"
StandaardRandagent
Wanneer IoT Edge de eerste keer wordt gestart, wordt er een standaardmodule van de Edge-agent opgestart. Als u de parameters die zijn opgegeven in de standaardmodule van de Edge-agent wilt overschrijven, gebruikt u deze sectie en vervangt u de waarden door uw eigen waarden.
Notitie
De agent.config.createOptions parameter wordt opgegeven als een inline-TOML-tabel. Deze indeling ziet eruit als JSON, maar dit is geen JSON. Zie de inlinetabel van de toml v1.0.0-documentatie voor meer informatie.
[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"
Daemon-beheer- en workload-API-eindpunten
Als u de API-eindpunten voor beheer en workload wilt overschrijven, gebruikt u deze sectie en vervangt u de waarden door uw eigen waarden.
[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"
Edge Agent-watchdog
Als u de standaardinstellingen van de Edge Agent-watchdog wilt overschrijven, gebruikt u deze sectie en vervangt u de waarden door uw eigen waarden.
[watchdog]
max_retries = "infinite" # the string "infinite" or a positive integer. Defaults to "infinite"
Edge CA-certificaat
Als u uw eigen Edge CA-certificaat hebt dat al uw modulecertificaten uitgeeft, gebruikt u een van deze secties en vervangt u de waarden door uw eigen.
Edge CA-certificaat geladen vanuit een bestand
[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
Edge CA-certificaat uitgegeven via EST
[edge_ca]
method = "est"
Zie zelfstudie: Inschrijving configureren via Secure Transport Server voor Azure IoT Edge voor meer informatie over het gebruik van een EST-server.
Optionele EST-configuratie voor het uitgeven van het Edge-CA-certificaat
Als deze niet is ingesteld, worden de standaardwaarden in [cert_issuance.est] gebruikt.
common_name = "aziot-edge CA"
expiry_days = 90
url = "https://example.org/.well-known/est"
username = "estuser"
password = "estpwd"
EST ID-certificaat al op apparaat
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
EST ID-certificaat aangevraagd via EST bootstrap ID-certificaat
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
Edge CA-certificaat uitgegeven vanuit een lokaal CA-certificaat
[cert_issuance.local_ca] moet worden ingesteld.
[edge_ca]
method = "local_ca"
# Optional configuration
common_name = "aziot-edge CA"
expiry_days = 90
Quickstartcertificaten voor Edge-CA
Als u geen eigen Edge CA-certificaat hebt gebruikt om alle modulecertificaten uit te geven, gebruikt u deze sectie en stelt u het aantal dagen in voor de levensduur van het automatisch gegenereerde zelfondertekende Edge-CA-certificaat. Vervaldatum is standaard ingesteld op 90 dagen.
Let op
Deze instelling wordt NIET aanbevolen voor productiegebruik. Configureer uw eigen Edge CA-certificaat in de secties voor Edge-CA-certificaten.
[edge_ca]
auto_generated_edge_ca_expiry_days = 90
Edge CA-certificaat autorenewal
Met deze instelling beheert u automatischrenewal van het Edge-CA-certificaat. Autorenewal is van toepassing wanneer de Edge-CA is geconfigureerd als quickstart of wanneer de Edge-CA een uitgifteset method heeft. Edge-CA-certificaten die vanuit bestanden worden geladen, kunnen over het algemeen niet automatisch worden vernieuwd omdat de Edge-runtime niet voldoende informatie heeft om ze te vernieuwen.
Belangrijk
Voor het vernieuwen van een Edge-CA moeten alle servercertificaten die door die CA zijn uitgegeven, opnieuw worden gegenereerd. Deze regeneratie wordt uitgevoerd door alle modules opnieuw op te starten. De verlenging van de Edge-CA kan niet worden gegarandeerd. Als willekeurige module opnieuw wordt opgestart, is dit onaanvaardbaar voor uw use-case, schakelt u autorenewal uit.
[edge_ca.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"
Garbagecollection van installatiekopieën
Als u de standaardconfiguratie voor de garbagecollection van de installatiekopieën wilt overschrijven, gebruikt u deze sectie en vervangt u de waarden in deze sectie door uw eigen waarden.
| Parameter | Description |
|---|---|
enabled |
Uitvoering van garbagecollection van installatiekopieën |
cleanup_recurrence |
Hoe vaak u wilt dat de garbagecollection van de installatiekopieën wordt uitgevoerd |
image_age_cleanup_threshold |
De leeftijd van ongebruikte afbeeldingen. Afbeeldingen die ouder zijn dan de drempelwaarde, worden verwijderd |
cleanup_time |
24-uurs HH:MM formaat. Wanneer de opschoontaak wordt uitgevoerd |
[image_garbage_collection]
enabled = true
cleanup_recurrence = "1d"
image_age_cleanup_threshold = "7d"
cleanup_time = "00:00"
Moby-runtime
Als u de standaardconfiguratie van Moby-runtime wilt overschrijven, gebruikt u deze sectie en vervangt u de waarden door uw eigen waarden.
[moby_runtime]
uri = "unix:///var/run/docker.sock"
network = "azure-iot-edge"