Konfigurowanie ustawień urządzenia usługi IoT Edge
W tym artykule przedstawiono ustawienia i opcje konfigurowania pliku usługi IoT Edge /etc/aziot/config.toml urządzenia usługi IoT Edge. Usługa IoT Edge używa pliku config.toml do inicjowania ustawień urządzenia. Każda z sekcji pliku config.toml ma kilka opcji. Nie wszystkie opcje są obowiązkowe, ponieważ mają zastosowanie do określonych scenariuszy.
Szablon zawierający wszystkie opcje można znaleźć w pliku config.toml.edge.template w katalogu /etc/aziot na urządzeniu usługi IoT Edge. Zawartość całego szablonu lub sekcji szablonu można skopiować do pliku config.toml . Usuń komentarz z potrzebnych sekcji. Pamiętaj, aby nie kopiować parametrów, które zostały już zdefiniowane.
Jeśli zmienisz konfigurację urządzenia, użyj polecenia sudo iotedge config apply , aby zastosować zmiany.
Parametry globalne
Nazwa hosta, parent_hostname, trust_bundle_cert, allow_elevated_docker_permissions i parametry auto_reprovisioning_mode muszą znajdować się na początku pliku konfiguracji przed innymi sekcjami. Dodanie parametrów przed kolekcją ustawień gwarantuje ich poprawne zastosowanie. Aby uzyskać więcej informacji na temat prawidłowej składni, zobacz toml.io .
Hostname (Nazwa hosta)
Aby włączyć odnajdywanie bramy, każde urządzenie bramy usługi IoT Edge (nadrzędne) musi określić parametr nazwy hosta używany przez jego urządzenia podrzędne w celu znalezienia go w sieci lokalnej. Moduł edgeHub używa również parametru nazwa hosta do dopasowania do certyfikatu serwera. Aby uzyskać więcej informacji, zobacz Dlaczego edgeGateway musi być poinformowany o własnej nazwie hosta?.
Uwaga
Gdy wartość nazwy hosta nie jest ustawiona, usługa IoT Edge próbuje znaleźć ją automatycznie. Jednak klienci w sieci mogą nie być w stanie odnaleźć urządzenia, jeśli nie jest ono ustawione.
W polu nazwa hosta zastąp wartość fqdn-device-name-or-ip-address nazwą urządzenia, aby zastąpić domyślną nazwę hosta urządzenia. Wartość może być w pełni kwalifikowaną nazwą domeny (FQDN) lub adresem IP. Użyj tego ustawienia jako nazwy hosta bramy na urządzeniu bramy usługi IoT Edge.
hostname = "fqdn-device-name-or-ip-address"
Nazwa hosta nadrzędnego
Nadrzędna nazwa hosta jest używana, gdy urządzenie usługi IoT Edge jest częścią hierarchii, inaczej nazywanej zagnieżdżonym krawędzią. Każde podrzędne urządzenie usługi IoT Edge musi określić parametr parent_hostname , aby zidentyfikować jego element nadrzędny. W scenariuszu hierarchicznym, w którym pojedyncze urządzenie usługi IoT Edge jest zarówno urządzeniem nadrzędnym, jak i podrzędnym, wymaga obu parametrów.
Zastąp wartość fqdn-parent-device-name-or-ip-address nazwą urządzenia nadrzędnego. Użyj nazwy hosta krótszej niż 64 znaki, która jest limitem znaków dla nazwy pospolitej certyfikatu serwera.
parent_hostname = "fqdn-parent-device-name-or-ip-address"
Aby uzyskać więcej informacji na temat ustawiania parametru parent_hostname, zobacz Połączenie urządzenia usługi Azure IoT Edge razem w celu utworzenia hierarchii.
Certyfikat pakietu zaufania
Aby udostępnić niestandardowy certyfikat urzędu certyfikacji jako główny certyfikat zaufania dla usługi IoT Edge i modułów, określ konfigurację trust_bundle_cert . Zastąp wartość parametru identyfikatorem URI pliku certyfikatem głównego urzędu certyfikacji na urządzeniu.
trust_bundle_cert = "file:///var/aziot/certs/trust-bundle.pem"
Aby uzyskać więcej informacji na temat pakietu zaufania usługi IoT Edge, zobacz Zarządzanie zaufanym głównym urzędem certyfikacji.
Podniesione uprawnienia platformy Docker
Niektóre funkcje platformy Docker mogą służyć do uzyskiwania dostępu do katalogu głównego. Domyślnie flaga --privileged i wszystkie możliwości wymienione w parametrze CapAdd konfiguracji hosta platformy Docker są dozwolone.
Jeśli żadne moduły nie wymagają uprzywilejowanych lub dodatkowych możliwości, użyj allow_elevated_docker_permissions , aby zwiększyć bezpieczeństwo urządzenia.
allow_elevated_docker_permissions = false
Tryb automatycznego ponownego aprowizowania
Opcjonalny parametr auto_reprovisioning_mode określa warunki, które decydują, kiedy urządzenie próbuje automatycznie ponownie aprowizować usługę Device Provisioning Service. Tryb automatycznej aprowizacji jest ignorowany, jeśli urządzenie zostało aprowidowane ręcznie. Aby uzyskać więcej informacji na temat ustawiania trybu aprowizacji usługi DPS, zobacz sekcję Aprowizacja w tym artykule, aby uzyskać więcej informacji.
Można ustawić jedną z następujących wartości:
| Tryb | opis |
|---|---|
| Dynamiczny | Ponowne inicjowanie obsługi administracyjnej, gdy urządzenie wykryje, że mogło zostać przeniesione z jednego centrum IoT Hub do innego. Ten tryb jest domyślny. |
| AlwaysOnStartup | Ponowne inicjowanie obsługi administracyjnej po ponownym uruchomieniu urządzenia lub awaria powoduje ponowne uruchomienie demonów. |
| OnErrorOnly | Nigdy nie wyzwalaj automatycznego ponownego aprowizowania urządzenia. Ponowne aprowizowanie urządzenia odbywa się tylko jako rezerwowe, jeśli urządzenie nie może nawiązać połączenia z usługą IoT Hub podczas aprowizacji tożsamości z powodu błędów łączności. To zachowanie rezerwowe jest niejawne w trybach Dynamic i AlwaysOnStartup. |
Na przykład:
auto_reprovisioning_mode = "Dynamic"
Aby uzyskać więcej informacji na temat ponownej aprowizacji urządzeń, zobacz IoT Hub Device reprovisioning concepts (Pojęcia dotyczące ponownej aprowizacji urządzeń w usłudze IoT Hub).
Inicjowanie obsługi
W zależności od potrzeb rozwiązania usługi IoT Edge można aprowizować jedno urządzenie lub wiele urządzeń na dużą skalę. Dostępne opcje uwierzytelniania komunikacji między urządzeniami usługi IoT Edge a centrum IoT zależą od wybranej metody aprowizacji.
Można aprowizować za pomocą parametry połączenia, klucza symetrycznego, certyfikatu X.509, klucza prywatnego certyfikatu tożsamości lub certyfikatu tożsamości. Aprowizacja usługi DPS jest zawarta w różnych opcjach. Wybierz jedną z metod aprowizacji. Zastąp przykładowe wartości własnymi.
Ręczna aprowizacja przy użyciu parametry połączenia
[provisioning]
source = "manual"
connection_string = "HostName=example.azure-devices.net;DeviceId=my-device;SharedAccessKey=<Shared access key>"
Aby uzyskać więcej informacji na temat pobierania informacji o aprowizacji, zobacz Tworzenie i aprowizowanie urządzenia usługi IoT Edge w systemie Linux przy użyciu kluczy symetrycznych.
Ręczna aprowizacja przy użyciu klucza symetrycznego
[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
Aby uzyskać więcej informacji na temat pobierania informacji o aprowizacji, zobacz Tworzenie i aprowizowanie urządzenia usługi IoT Edge w systemie Linux przy użyciu kluczy symetrycznych.
Ręczna aprowizacja przy użyciu certyfikatu X.509
[provisioning]
source = "manual"
iothub_hostname = "example.azure-devices.net"
device_id = "my-device"
[provisioning.authentication]
method = "x509"
Aby uzyskać więcej informacji na temat aprowizacji przy użyciu certyfikatów X.509, zobacz Tworzenie i aprowizowanie urządzenia usługi IoT Edge w systemie Linux przy użyciu certyfikatów X.509.
Aprowizowanie usługi DPS przy użyciu klucza symetrycznego
[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" }
Aby uzyskać więcej informacji na temat aprowizacji usługi DPS z kluczem symetrycznym, zobacz Tworzenie i aprowizowanie urządzeń usługi IoT Edge na dużą skalę w systemie Linux przy użyciu klucza symetrycznego.
Aprowizowanie usługi DPS przy użyciu certyfikatów 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
(Opcjonalnie) Włączanie automatycznego odnawiania certyfikatu identyfikatora urządzenia
Autorenewal wymaga znanej metody wystawiania certyfikatów. Ustaw metodę na est wartość lub local_ca.
Ważne
Włącz autorenewal tylko wtedy, gdy to urządzenie jest skonfigurowane na potrzeby rejestracji usługi DPS opartej na urzędzie certyfikacji. Użycie autorenewal dla rejestracji indywidualnej powoduje, że urządzenie nie może ponownie aprowizacji.
[provisioning.attestation.identity_cert.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"
Aby uzyskać więcej informacji na temat aprowizacji usługi DPS przy użyciu certyfikatów X.509, zobacz Tworzenie i aprowizowanie urządzeń usługi IoT Edge na dużą skalę w systemie Linux przy użyciu certyfikatów X.509.
Aprowizowanie usługi DPS za pomocą modułu 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"
Jeśli używasz aprowizacji usługi DPS z modułem TPM i wymagasz konfiguracji niestandardowej, zobacz sekcję MODUŁ TPM .
Aby uzyskać więcej informacji, zobacz Tworzenie i aprowizowanie urządzeń usługi IoT Edge na dużą skalę za pomocą modułu TPM w systemie Linux.
Limit czasu chmury i zachowanie ponawiania prób
Te ustawienia kontrolują limit czasu i ponawianie prób dla operacji w chmurze, takich jak komunikacja z usługą Device Provisioning Service (DPS) podczas aprowizacji lub usługi IoT Hub na potrzeby tworzenia tożsamości modułu.
Parametr cloud_timeout_sec to termin ostateczny w sekundach żądania sieciowego do usług w chmurze. Na przykład żądanie HTTP. Odpowiedź z usługi w chmurze musi zostać odebrana przed upływem tego terminu lub żądanie zakończy się niepowodzeniem jako limit czasu.
Parametr cloud_retries określa, ile razy żądanie może zostać ponowione po pierwszym wykonaniu próby. Klient zawsze wysyła co najmniej raz, więc wartość jest liczbą ponownych prób po pierwszym wykonaniu próby kończy się niepowodzeniem. Na przykład oznacza, cloud_retries = 2 że klient wykonuje łącznie trzy próby.
cloud_timeout_sec = 10
cloud_retries = 1
Wystawianie certyfikatów
Jeśli skonfigurowano dowolne dynamicznie wystawiane certyfikaty, wybierz odpowiednią metodę wystawiania i zastąp przykładowe wartości własnymi.
Wystawianie certyfikatu za pośrednictwem est
[cert_issuance.est]
trusted_certs = ["file:///var/aziot/certs/est-id-ca.pem",]
[cert_issuance.est.auth]
username = "estuser"
password = "estpwd"
Certyfikat EST ID już na urządzeniu
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
Certyfikat EST ID żądany za pośrednictwem certyfikatu identyfikatora rozruchu EST
Uwierzytelnianie przy użyciu certyfikatu klienta TLS, który jest używany raz do utworzenia początkowego certyfikatu identyfikatora EST. Po pierwszym wystawieniu certyfikatu element identity_cert i identity_pk jest automatycznie tworzony i używany do przyszłego uwierzytelniania i odnawiania. Nazwa pospolita podmiotu wygenerowanego certyfikatu EST ID jest zawsze taka sama jak skonfigurowany identyfikator urządzenia w sekcji aprowizacji. Te pliki muszą być odczytywane odpowiednio przez użytkowników aziotcs i 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"
Wystawianie certyfikatu za pośrednictwem lokalnego urzędu certyfikacji
[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
Moduł TPM (moduł Trusted Platform Module)
Jeśli potrzebujesz specjalnej konfiguracji modułu TPM podczas korzystania z aprowizacji modułu TPM programu DPS, użyj tych ustawień modułu TPM.
Aby uzyskać akceptowalne ciągi modułu ładującego TCTI, zobacz sekcję 3.5 specyfikacji interfejsu API TCG TSS 2.0 TPM Command Transmission Interface (TCTI).
Ustawienie pustego ciągu powoduje, że biblioteka modułu ładującego TCTI spróbuje załadować wstępnie zdefiniowany zestaw modułów TCTI w kolejności.
[tpm]
tcti = "swtpm:port=2321"
Indeks modułu TPM utrzymuje klucz uwierzytelniania usługi DPS. Indeks jest traktowany jako przesunięcie z adresu podstawowego dla obiektów trwałych, takich jak 0x81000000 i musi znajdować się w zakresie od 0x00_00_00 do 0x7F_FF_FF. Domyślna wartość to 0x00_01_00.
auth_key_index = "0x00_01_00"
W razie potrzeby użyj wartości autoryzacji dla hierarchii poręczenia i właściciela. Domyślnie te wartości są pustymi ciągami.
[tpm.hierarchy_authorization]
endorsement = "hello"
owner = "world"
PKCS#11
Jeśli użyto jakichkolwiek identyfikatorów URI PKCS#11, użyj następujących parametrów i zastąp wartości konfiguracją PKCS#11.
[aziot_keys]
pkcs11_lib_path = "/usr/lib/libmypkcs11.so"
pkcs11_base_slot = "pkcs11:slot-id=0?pin-value=1234"
Domyślny agent usługi Edge
Gdy usługa IoT Edge uruchamia się po raz pierwszy, uruchamia domyślny moduł agenta usługi Edge. Jeśli musisz zastąpić parametry podane w domyślnym module agenta usługi Edge, użyj tej sekcji i zastąp wartości własnymi.
Uwaga
Parametr jest określany jako tabela śródliniowa agent.config.createOptions TOML. Ten format wygląda następująco: JSON, ale nie jest to kod JSON. Aby uzyskać więcej informacji, zobacz wbudowany spis dokumentacji TOML w wersji 1.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"
Punkty końcowe interfejsu API demona i zarządzania nimi
Jeśli musisz zastąpić punkty końcowe interfejsu API zarządzania i obciążenia, użyj tej sekcji i zastąp wartości własnymi.
[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 agenta usługi Edge
Jeśli musisz zastąpić domyślne ustawienia watchdog agenta usługi Edge, użyj tej sekcji i zastąp wartości własnymi.
[watchdog]
max_retries = "infinite" # the string "infinite" or a positive integer. Defaults to "infinite"
Certyfikat urzędu certyfikacji usługi Edge
Jeśli masz własny certyfikat urzędu certyfikacji usługi Edge, który wystawia wszystkie certyfikaty modułu, użyj jednej z tych sekcji i zastąp wartości własnymi.
Certyfikat urzędu certyfikacji usługi Edge załadowany z pliku
[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
Certyfikat urzędu certyfikacji brzegowego wystawiony za pośrednictwem est
[edge_ca]
method = "est"
Aby uzyskać więcej informacji na temat korzystania z serwera EST, zobacz Samouczek: konfigurowanie rejestracji za pośrednictwem bezpiecznego serwera transportu dla usługi Azure IoT Edge.
Opcjonalna konfiguracja est na potrzeby wystawiania certyfikatu urzędu certyfikacji usługi Edge
Jeśli nie zostanie ustawiona, zostaną użyte wartości domyślne w pliku [cert_issuance.est].
common_name = "aziot-edge CA"
expiry_days = 90
url = "https://example.org/.well-known/est"
username = "estuser"
password = "estpwd"
Certyfikat EST ID już na urządzeniu
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
Certyfikat EST ID żądany za pośrednictwem certyfikatu identyfikatora rozruchu 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
Certyfikat urzędu certyfikacji brzegowego wystawiony z lokalnego certyfikatu urzędu certyfikacji
Wymaga ustawienia [cert_issuance.local_ca].
[edge_ca]
method = "local_ca"
# Optional configuration
common_name = "aziot-edge CA"
expiry_days = 90
Certyfikaty szybkiego startu urzędu certyfikacji usługi Edge
Jeśli nie masz własnego certyfikatu urzędu certyfikacji edge używanego do wystawiania wszystkich certyfikatów modułu, użyj tej sekcji i ustaw liczbę dni istnienia automatycznie wygenerowanego certyfikatu urzędu certyfikacji edge z podpisem własnym. Wygaśnięcie domyślnie to 90 dni.
Uwaga
To ustawienie NIE jest zalecane w przypadku użycia produkcyjnego. Skonfiguruj własny certyfikat urzędu certyfikacji edge w sekcjach Certyfikat urzędu certyfikacji usługi Edge.
[edge_ca]
auto_generated_edge_ca_expiry_days = 90
Autorenewal certyfikatu urzędu certyfikacji brzegowego
To ustawienie umożliwia zarządzanie autorenewalem certyfikatu urzędu certyfikacji usługi Edge. Autorenewal ma zastosowanie, gdy urząd certyfikacji usługi Edge jest skonfigurowany jako przewodnik Szybki start lub gdy urząd certyfikacji usługi Edge ma zestaw wystawiania method . Certyfikaty urzędu certyfikacji usługi Edge ładowane z plików zwykle nie mogą być odnawiane automatycznie, ponieważ środowisko uruchomieniowe usługi Edge nie ma wystarczającej ilości informacji, aby je odnowić.
Ważne
Odnowienie urzędu certyfikacji usługi Edge wymaga ponownego wygenerowania wszystkich certyfikatów serwera wystawionych przez ten urząd certyfikacji. Ta ponowna regenerowanie odbywa się przez ponowne uruchomienie wszystkich modułów. Nie można zagwarantować czasu odnowienia urzędu certyfikacji usługi Edge. Jeśli losowe ponowne uruchomienia modułu są niedopuszczalne w przypadku użycia, wyłącz autorenewal.
[edge_ca.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"
Odzyskiwanie pamięci obrazu
Jeśli musisz zastąpić domyślną konfigurację odzyskiwania pamięci obrazu, użyj tej sekcji i zastąp wartości w tej sekcji własnymi wartościami.
| Parametr | Opis |
|---|---|
enabled |
Uruchamia odzyskiwanie pamięci obrazu |
cleanup_recurrence |
Jak często ma być uruchamiane odzyskiwanie pamięci obrazu |
image_age_cleanup_threshold |
Wiek nieużywanych obrazów. Obrazy starsze niż próg są usuwane |
cleanup_time |
24-godzinny format HH:MM. Po uruchomieniu zadania oczyszczania |
[image_garbage_collection]
enabled = true
cleanup_recurrence = "1d"
image_age_cleanup_threshold = "7d"
cleanup_time = "00:00"
Środowisko uruchomieniowe Moby
Jeśli musisz zastąpić domyślną konfigurację środowiska uruchomieniowego Moby, użyj tej sekcji i zastąp wartości własnymi.
[moby_runtime]
uri = "unix:///var/run/docker.sock"
network = "azure-iot-edge"