Konfigurera enhetsinställningar för IoT Edge
Den här artikeln visar inställningar och alternativ för att konfigurera filen IoT Edge /etc/aziot/config.toml för en IoT Edge-enhet. IoT Edge använder filen config.toml för att initiera inställningarna för enheten. Var och en av avsnitten i filen config.toml har flera alternativ. Alla alternativ är inte obligatoriska eftersom de gäller för specifika scenarier.
En mall som innehåller alla alternativ finns i filen config.toml.edge.template i katalogen /etc/aziot på en IoT Edge-enhet. Du kan kopiera innehållet i hela mallen eller avsnitten i mallen till filen config.toml . Ta bort kommentaren till de avsnitt du behöver. Tänk på att inte kopiera över parametrar som du redan har definierat.
Om du ändrar en enhets konfiguration använder sudo iotedge config apply du för att tillämpa ändringarna.
Globala parametrar
Parametrarna hostname, parent_hostname, trust_bundle_cert, allow_elevated_docker_permissions och auto_reprovisioning_mode måste finnas i början av konfigurationsfilen före andra avsnitt. Genom att lägga till parametrar före en samling inställningar ser du till att de tillämpas korrekt. Mer information om giltig syntax finns i toml.io .
Värdnamn
För att aktivera gatewayidentifiering måste varje IoT Edge-gateway (överordnad) enhet ange en värdnamnsparameter som dess underordnade enheter använder för att hitta den i det lokala nätverket. EdgeHub-modulen använder också parametern värdnamn för att matcha med dess servercertifikat. Mer information finns i Varför behöver EdgeGateway få information om sitt eget värdnamn?.
Kommentar
När värdet för värdnamnet inte har angetts försöker IoT Edge hitta det automatiskt. Klienter i nätverket kanske dock inte kan identifiera enheten om den inte har angetts.
Som värdnamn ersätter du fqdn-device-name-or-ip-address med enhetsnamnet för att åsidosätta enhetens standardvärdnamn. Värdet kan vara ett fullständigt domännamn (FQDN) eller en IP-adress. Använd den här inställningen som gatewayens värdnamn på en IoT Edge-gatewayenhet.
hostname = "fqdn-device-name-or-ip-address"
Överordnat värdnamn
Överordnat värdnamn används när IoT Edge-enheten ingår i en hierarki, även kallad kapslad kant. Varje underordnade IoT Edge-enhet måste ange en parent_hostname parameter för att identifiera dess överordnade. I ett hierarkiskt scenario där en enda IoT Edge-enhet är både en överordnad och en underordnad enhet behöver den båda parametrarna.
Ersätt fqdn-parent-device-name-or-ip-address med namnet på den överordnade enheten. Använd ett värdnamn som är kortare än 64 tecken, vilket är teckengränsen för ett gemensamt servercertifikatnamn.
parent_hostname = "fqdn-parent-device-name-or-ip-address"
Mer information om hur du anger parametern parent_hostname finns i Anslut Azure IoT Edge-enheter tillsammans för att skapa en hierarki.
Betrodda paketcertifikat
Om du vill ange ett certifikat för anpassad certifikatutfärdare (CA) som en rot av förtroende för IoT Edge och moduler anger du en trust_bundle_cert konfiguration. Ersätt parametervärdet med fil-URI:n till rotcertifikatutfärdarcertifikatet på enheten.
trust_bundle_cert = "file:///var/aziot/certs/trust-bundle.pem"
Mer information om IoT Edge-förtroendepaketet finns i Hantera betrodd rotcertifikatutfärdare.
Utökade Docker-behörigheter
Vissa docker-funktioner kan användas för att få rotåtkomst. Som standard tillåts --privileged flaggan och alla funktioner som anges i parametern CapAdd i docker HostConfig .
Om inga moduler kräver privilegierade eller extra funktioner kan du använda allow_elevated_docker_permissions för att förbättra enhetens säkerhet.
allow_elevated_docker_permissions = false
Läge för automatisk ometablering
Den valfria parametern auto_reprovisioning_mode anger de villkor som avgör när en enhet försöker etablera om automatiskt med Device Provisioning Service. Läget för automatisk etablering ignoreras om enheten har etablerats manuellt. Mer information om hur du ställer in DPS-etableringsläge finns i avsnittet Etablering i den här artikeln för mer information.
Ett av följande värden kan anges:
| Läge | beskrivning |
|---|---|
| Dynamisk | Återskapa när enheten upptäcker att den kan ha flyttats från en IoT Hub till en annan. Det här läget är standard. |
| AlwaysOnStartup | Ometablering när enheten startas om eller en krasch gör att daemonerna startas om. |
| OnErrorOnly | Utlös aldrig enhetens ometablering automatiskt. Ometablering av enheter sker endast som reserv om enheten inte kan ansluta till IoT Hub under identitetsetablering på grund av anslutningsfel. Det här återställningsbeteendet är också implicit i lägena Dynamisk och AlwaysOnStartup. |
Till exempel:
auto_reprovisioning_mode = "Dynamic"
Mer information om ometablering av enheter finns i Begrepp för ometablering av IoT Hub-enheter.
Etablerar
Du kan etablera en enskild enhet eller flera enheter i stor skala, beroende på behoven i din IoT Edge-lösning. Vilka alternativ som är tillgängliga för autentisering av kommunikation mellan dina IoT Edge-enheter och dina IoT-hubbar beror på vilken etableringsmetod du väljer.
Du kan etablera med en anslutningssträng, symmetrisk nyckel, X.509-certifikat, identitetscertifikat privat nyckel eller ett identitetscertifikat. DPS-etablering ingår i olika alternativ. Välj en metod för etableringen. Ersätt exempelvärdena med dina egna.
Manuell etablering med anslutningssträng
[provisioning]
source = "manual"
connection_string = "HostName=example.azure-devices.net;DeviceId=my-device;SharedAccessKey=<Shared access key>"
Mer information om hur du hämtar etableringsinformation finns i Skapa och etablera en IoT Edge-enhet i Linux med symmetriska nycklar.
Manuell etablering med symmetrisk nyckel
[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
Mer information om hur du hämtar etableringsinformation finns i Skapa och etablera en IoT Edge-enhet i Linux med symmetriska nycklar.
Manuell etablering med X.509-certifikat
[provisioning]
source = "manual"
iothub_hostname = "example.azure-devices.net"
device_id = "my-device"
[provisioning.authentication]
method = "x509"
Mer information om etablering med X.509-certifikat finns i Skapa och etablera en IoT Edge-enhet i Linux med X.509-certifikat.
DPS-etablering med symmetrisk nyckel
[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" }
Mer information om DPS-etablering med symmetrisk nyckel finns i Skapa och etablera IoT Edge-enheter i stor skala i Linux med symmetrisk nyckel.
DPS-etablering med X.509-certifikat
[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
(Valfritt) Aktivera automatisk förnyelse av enhets-ID-certifikatet
Autorenewal kräver en känd certifikatutfärdningsmetod. Ange metoden till antingen est eller local_ca.
Viktigt!
Aktivera endast autorenewal om den här enheten har konfigurerats för CA-baserad DPS-registrering. Om du använder autorenewal för en enskild registrering kan enheten inte återskapas.
[provisioning.attestation.identity_cert.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"
Mer information om DPS-etablering med X.509-certifikat finns i Skapa och etablera IoT Edge-enheter i stor skala i Linux med X.509-certifikat.
DPS-etablering med 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"
Om du använder DPS-etablering med TPM och kräver anpassad konfiguration läser du avsnittet TPM .
Mer information finns i Skapa och etablera IoT Edge-enheter i stor skala med en TPM i Linux.
Beteende för tidsgräns och återförsök i molnet
De här inställningarna styr tidsgränsen och återförsöken för molnåtgärder, till exempel kommunikation med Device Provisioning Service (DPS) under etableringen eller IoT Hub för att skapa modulidentiteter.
Parametern cloud_timeout_sec är tidsgränsen i sekunder för en nätverksbegäran till molntjänster. Till exempel en HTTP-begäran. Ett svar från molntjänsten måste tas emot före den här tidsgränsen, annars misslyckas begäran som en tidsgräns.
Parametern cloud_retries styr hur många gånger en begäran kan göras om när det första försöket misslyckas. Klienten skickar alltid minst en gång, så värdet är antalet återförsök när det första försöket misslyckas. Innebär till exempel cloud_retries = 2 att klienten gör totalt tre försök.
cloud_timeout_sec = 10
cloud_retries = 1
Utfärdande av certifikat
Om du har konfigurerat några dynamiskt utfärdade certifikat väljer du motsvarande utfärdandemetod och ersätter exempelvärdena med dina egna.
Utfärdande av certifikat 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-certifikat redan på enheten
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-certifikat som begärs via EST bootstrap ID-certifikat
Autentisering med ett TLS-klientcertifikat som används en gång för att skapa det första EST ID-certifikatet. Efter det första certifikatutfärdandet skapas och används en identity_cert och identity_pk automatiskt för framtida autentisering och förnyelser. Ämnesnamnet (CN) för det genererade EST ID-certifikatet är alltid detsamma som det konfigurerade enhets-ID:t under etableringsavsnittet. Dessa filer måste vara läsbara av användarna aziotcs respektive 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"
Certifikatutfärding via lokal certifikatutfärdarcertifikatutfärdarcertifikat
[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)
Om du behöver särskild konfiguration för TPM när du använder DPS TPM-etablering använder du dessa TPM-inställningar.
För acceptabla TCTI-inläsningssträngar, se avsnitt 3.5 i TCG TSS 2.0 TPM API Specification (TCTI).
Om du anger en tom sträng kan TCTI-inläsningsbiblioteket försöka läsa in en fördefinierad uppsättning TCTI-moduler i ordning.
[tpm]
tcti = "swtpm:port=2321"
TPM-indexet bevarar DPS-autentiseringsnyckeln. Indexet tas som en förskjutning från basadressen för beständiga objekt som 0x81000000 och måste ligga i intervallet från 0x00_00_00 till 0x7F_FF_FF. Standardvärdet är 0x00_01_00.
auth_key_index = "0x00_01_00"
Använd auktoriseringsvärden för bekräftelse- och ägarhierarkier om det behövs. Som standard är dessa värden tomma strängar.
[tpm.hierarchy_authorization]
endorsement = "hello"
owner = "world"
PKCS#11
Om du har använt PKCS#11-URI:er använder du följande parametrar och ersätter värdena med PKCS#11-konfigurationen.
[aziot_keys]
pkcs11_lib_path = "/usr/lib/libmypkcs11.so"
pkcs11_base_slot = "pkcs11:slot-id=0?pin-value=1234"
Standard edge-agent
När IoT Edge startar första gången startar den en Edge Agent-standardmodul. Om du behöver åsidosätta de parametrar som anges i standardmodulen för Edge Agent använder du det här avsnittet och ersätter värdena med dina egna.
Kommentar
Parametern agent.config.createOptions anges som en infogad TOML-tabell. Det här formatet ser ut som JSON, men det är inte JSON. Mer information finns i Infogad tabell i TOML v1.0.0-dokumentationen.
[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"
Api-slutpunkter för daemonhantering och arbetsbelastning
Om du behöver åsidosätta API-slutpunkterna för hantering och arbetsbelastning använder du det här avsnittet och ersätter värdena med dina egna.
[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-vakthund
Om du behöver åsidosätta standardinställningarna för Edge Agent-övervakning använder du det här avsnittet och ersätter värdena med dina egna.
[watchdog]
max_retries = "infinite" # the string "infinite" or a positive integer. Defaults to "infinite"
Edge CA-certifikat
Om du har ett eget Edge CA-certifikat som utfärdar alla dina modulcertifikat använder du ett av dessa avsnitt och ersätter värdena med dina egna.
Edge CA-certifikat som lästs in från en fil
[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-certifikat utfärdat via EST
[edge_ca]
method = "est"
Mer information om hur du använder en EST-server finns i Självstudie: Konfigurera registrering över säker transportserver för Azure IoT Edge.
Valfri EST-konfiguration för utfärdande av Edge CA-certifikatet
Om inte anges används standardvärdena i [cert_issuance.est].
common_name = "aziot-edge CA"
expiry_days = 90
url = "https://example.org/.well-known/est"
username = "estuser"
password = "estpwd"
EST ID-certifikat redan på enheten
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-certifikat som begärs via EST bootstrap ID-certifikat
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-certifikat utfärdat från ett lokalt CA-certifikat
Kräver att [cert_issuance.local_ca] anges.
[edge_ca]
method = "local_ca"
# Optional configuration
common_name = "aziot-edge CA"
expiry_days = 90
Snabbstartscertifikat för Edge CA
Om du inte har ett eget Edge CA-certifikat som används för att utfärda alla modulcertifikat använder du det här avsnittet och anger antalet dagar för livslängden för det automatiskt genererade självsignerade Edge CA-certifikatet. Förfallodatum är som standard 90 dagar.
Varning
Den här inställningen rekommenderas INTE för produktionsanvändning. Konfigurera ditt eget Edge CA-certifikat i avsnittet Edge CA-certifikat.
[edge_ca]
auto_generated_edge_ca_expiry_days = 90
Autorenewal för Edge CA-certifikat
Den här inställningen hanterar autorenewal av Edge CA-certifikatet. Autorenewal gäller när Edge CA konfigureras som snabbstart eller när Edge CA har en utfärdandeuppsättning method . Edge CA-certifikat som läses in från filer kan vanligtvis inte återställas automatiskt eftersom Edge-körningen inte har tillräckligt med information för att förnya dem.
Viktigt!
Förnyelse av en Edge CA kräver att alla servercertifikat som utfärdats av certifikatutfärdare återskapas. Den här regenereringen görs genom att starta om alla moduler. Tiden för förnyelse av Edge CA kan inte garanteras. Om slumpmässiga modulomstarter är oacceptabla för ditt användningsfall inaktiverar du autorenewal.
[edge_ca.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"
Avbildningsavfallsinsamling
Om du behöver åsidosätta standardkonfigurationen för skräpinsamling av avbildningar använder du det här avsnittet och ersätter värdena i det här avsnittet med dina egna.
| Parameter | Description |
|---|---|
enabled |
Kör skräpinsamling för avbildningar |
cleanup_recurrence |
Hur ofta du vill att avbildningens skräpinsamling ska köras |
image_age_cleanup_threshold |
Åldern för oanvända bilder. Bilder som är äldre än tröskelvärdet tas bort |
cleanup_time |
24-timmars HH:MM-format. När rensningsjobbet körs |
[image_garbage_collection]
enabled = true
cleanup_recurrence = "1d"
image_age_cleanup_threshold = "7d"
cleanup_time = "00:00"
Moby-körning
Om du behöver åsidosätta standardkonfigurationen för Moby-körning använder du det här avsnittet och ersätter värdena med din egen.
[moby_runtime]
uri = "unix:///var/run/docker.sock"
network = "azure-iot-edge"