Mengonfigurasi pengaturan perangkat IoT Edge
Artikel ini memperlihatkan pengaturan dan opsi untuk mengonfigurasi file IoT Edge /etc/aziot/config.toml dari perangkat IoT Edge. IoT Edge menggunakan file config.toml untuk menginisialisasi pengaturan untuk perangkat. Setiap bagian file config.toml memiliki beberapa opsi. Tidak semua opsi bersifat wajib, karena berlaku untuk skenario tertentu.
Templat yang berisi semua opsi dapat ditemukan di file config.toml.edge.template dalam direktori /etc/aziot pada perangkat IoT Edge. Anda dapat menyalin konten seluruh templat atau bagian templat ke dalam file config.toml Anda. Batalkan komentar bagian yang Anda butuhkan. Ketahuilah untuk tidak menyalin parameter yang telah Anda tentukan.
Jika Anda mengubah konfigurasi perangkat, gunakan sudo iotedge config apply untuk menerapkan perubahan.
Parameter global
Parameter hostname, parent_hostname, trust_bundle_cert, allow_elevated_docker_permissions, dan auto_reprovisioning_mode harus berada di awal file konfigurasi sebelum bagian lain. Menambahkan parameter sebelum kumpulan pengaturan memastikannya diterapkan dengan benar. Untuk informasi selengkapnya tentang sintaks yang valid, lihat toml.io .
Nama host
Untuk mengaktifkan penemuan gateway, setiap perangkat gateway IoT Edge (induk) perlu menentukan parameter nama host yang digunakan perangkat anaknya untuk menemukannya di jaringan lokal. Modul edgeHub juga menggunakan parameter nama host untuk mencocokkan dengan sertifikat servernya. Untuk informasi selengkapnya, lihat Mengapa EdgeGateway perlu diberi tahu tentang nama hostnya sendiri?.
Catatan
Saat nilai nama host tidak diatur, IoT Edge mencoba menemukannya secara otomatis. Namun, klien dalam jaringan mungkin tidak dapat menemukan perangkat jika tidak diatur.
Untuk nama host, ganti fqdn-device-name-or-ip-address dengan nama perangkat Anda untuk mengganti nama host default perangkat. Nilainya dapat berupa nama domain yang sepenuhnya memenuhi syarat (FQDN) atau alamat IP. Gunakan pengaturan ini sebagai nama host gateway pada perangkat gateway IoT Edge.
hostname = "fqdn-device-name-or-ip-address"
Nama host induk
Nama host induk digunakan saat perangkat IoT Edge adalah bagian dari hierarki, atau dikenal sebagai tepi berlapis. Setiap perangkat IoT Edge hilir perlu menentukan parameter parent_hostname untuk mengidentifikasi induknya. Dalam skenario hierarkis di mana satu perangkat IoT Edge adalah perangkat induk dan anak, perangkat tersebut memerlukan kedua parameter.
Ganti fqdn-parent-device-name-or-ip-address dengan nama perangkat induk Anda. Gunakan nama host yang lebih pendek dari 64 karakter, yang merupakan batas karakter untuk nama umum sertifikat server.
parent_hostname = "fqdn-parent-device-name-or-ip-address"
Untuk informasi selengkapnya tentang mengatur parameter parent_hostname, lihat Koneksi perangkat Azure IoT Edge bersama-sama untuk membuat hierarki.
Sertifikat bundel kepercayaan
Untuk memberikan sertifikat otoritas sertifikat (CA) kustom sebagai akar kepercayaan untuk IoT Edge dan modul, tentukan konfigurasi trust_bundle_cert . Ganti nilai parameter dengan URI file ke sertifikat OS akar di perangkat Anda.
trust_bundle_cert = "file:///var/aziot/certs/trust-bundle.pem"
Untuk informasi selengkapnya tentang bundel kepercayaan IoT Edge, lihat Mengelola CA akar tepercaya.
Izin Docker yang Ditingkatkan
Beberapa kemampuan docker dapat digunakan untuk mendapatkan akses root. Secara default, --privileged bendera dan semua kemampuan yang tercantum dalam parameter CapAdd dari docker HostConfig diizinkan.
Jika tidak ada modul yang memerlukan kemampuan istimewa atau ekstra, gunakan allow_elevated_docker_permissions untuk meningkatkan keamanan perangkat.
allow_elevated_docker_permissions = false
Mode provisi ulang otomatis
Parameter auto_reprovisioning_mode opsional menentukan kondisi yang memutuskan kapan perangkat mencoba memprovisikan ulang secara otomatis dengan Device Provisioning Service. Mode provisi otomatis diabaikan jika perangkat telah disediakan secara manual. Untuk informasi selengkapnya tentang mengatur mode provisi DPS, lihat bagian Provisi di artikel ini untuk informasi selengkapnya.
Salah satu nilai berikut dapat diatur:
| Mode | Deskripsi |
|---|---|
| Dinamis | Provisi ulang saat perangkat mendeteksi bahwa perangkat mungkin telah dipindahkan dari satu IoT Hub ke IoT Hub lainnya. Mode ini adalah default. |
| AlwaysOnStartup | Provisi ulang saat perangkat di-boot ulang atau crash menyebabkan daemon dimulai ulang. |
| OnErrorOnly | Jangan pernah memicu provisi ulang perangkat secara otomatis. Provisi ulang perangkat hanya terjadi sebagai fallback, jika perangkat tidak dapat terhubung ke IoT Hub selama provisi identitas karena kesalahan konektivitas. Perilaku fallback ini juga implisit dalam mode Dinamis dan AlwaysOnStartup. |
Misalnya:
auto_reprovisioning_mode = "Dynamic"
Untuk informasi selengkapnya tentang provisi ulang perangkat, lihat Konsep provisi ulang Perangkat IoT Hub.
Penyediaan
Anda dapat menyediakan satu perangkat atau beberapa perangkat dalam skala besar, tergantung pada kebutuhan solusi IoT Edge Anda. Opsi yang tersedia untuk mengautentikasi komunikasi antara perangkat IoT Edge dan hub IoT Anda bergantung pada metode provisi apa yang Anda pilih.
Anda dapat menyediakan dengan string koneksi, kunci konten, sertifikat X.509, kunci privat sertifikat identitas, atau sertifikat identitas. Provisi DPS disertakan dengan berbagai opsi. Pilih satu metode untuk provisi Anda. Ganti nilai sampel dengan nilai Anda sendiri.
Provisi manual dengan string koneksi
[provisioning]
source = "manual"
connection_string = "HostName=example.azure-devices.net;DeviceId=my-device;SharedAccessKey=<Shared access key>"
Untuk informasi selengkapnya tentang mengambil informasi provisi, lihat Membuat dan memprovisikan perangkat IoT Edge di Linux menggunakan kunci konten.
Provisi manual dengan kunci konten
[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
Untuk informasi selengkapnya tentang mengambil informasi provisi, lihat Membuat dan memprovisikan perangkat IoT Edge di Linux menggunakan kunci konten.
Provisi manual dengan sertifikat X.509
[provisioning]
source = "manual"
iothub_hostname = "example.azure-devices.net"
device_id = "my-device"
[provisioning.authentication]
method = "x509"
Untuk informasi selengkapnya tentang provisi menggunakan sertifikat X.509, lihat Membuat dan memprovisikan perangkat IoT Edge di Linux menggunakan sertifikat X.509.
Provisi DPS dengan kunci konten
[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" }
Untuk informasi selengkapnya tentang provisi DPS dengan kunci konten, lihat Membuat dan memprovisikan perangkat IoT Edge dalam skala besar di Linux menggunakan kunci konten.
Provisi DPS dengan sertifikat 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
(Opsional) Aktifkan perpanjangan otomatis sertifikat ID perangkat
Autorenewal memerlukan metode penerbitan sertifikat yang diketahui. Atur metode ke atau local_caest .
Penting
Hanya aktifkan autorenewal jika perangkat ini dikonfigurasi untuk pendaftaran DPS berbasis CA. Menggunakan autorenewal untuk pendaftaran individu menyebabkan perangkat tidak dapat melakukan provisi ulang.
[provisioning.attestation.identity_cert.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"
Untuk informasi selengkapnya tentang provisi DPS dengan sertifikat X.509, lihat Membuat dan memprovisikan perangkat IoT Edge dalam skala besar di Linux menggunakan sertifikat X.509.
Provisi DPS dengan TPM (Modul Platform Tepercaya)
[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"
Jika Anda menggunakan provisi DPS dengan TPM, dan memerlukan konfigurasi kustom, lihat bagian TPM .
Untuk informasi selengkapnya, lihat Membuat dan menyediakan perangkat IoT Edge dalam skala besar dengan TPM di Linux.
Batas Waktu Cloud dan Perilaku Coba Lagi
Pengaturan ini mengontrol batas waktu dan percobaan ulang untuk operasi cloud, seperti komunikasi dengan Device Provisioning Service (DPS) selama provisi atau IoT Hub untuk pembuatan identitas modul.
Parameter cloud_timeout_sec adalah tenggat waktu dalam detik untuk permintaan jaringan ke layanan cloud. Misalnya, permintaan HTTP. Respons dari layanan awan harus diterima sebelum tenggat waktu ini, atau permintaan gagal sebagai batas waktu.
Parameter cloud_retries mengontrol berapa kali permintaan dapat dicoba kembali setelah percobaan pertama gagal. Klien selalu mengirim setidaknya sekali, sehingga nilainya adalah jumlah percobaan ulang setelah percobaan pertama gagal. Misalnya, cloud_retries = 2 berarti bahwa klien membuat total tiga upaya.
cloud_timeout_sec = 10
cloud_retries = 1
Penerbitan sertifikat
Jika Anda mengonfigurasi sertifikasi yang dikeluarkan secara dinamis, pilih metode penerbitan yang sesuai dan ganti nilai sampel dengan nilai Anda sendiri.
Penerbitan sertifikasi melalui EST
[cert_issuance.est]
trusted_certs = ["file:///var/aziot/certs/est-id-ca.pem",]
[cert_issuance.est.auth]
username = "estuser"
password = "estpwd"
Sertifikasi ID EST sudah ada di perangkat
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
Sertifikasi ID EST diminta melalui sertifikasi ID bootstrap EST
Autentikasi dengan sertifikat klien TLS yang digunakan sekali untuk membuat sertifikat ID EST awal. Setelah penerbitan sertifikat pertama, identity_cert dan identity_pk secara otomatis dibuat dan digunakan untuk autentikasi dan perpanjangan di masa mendatang. Nama Umum Subjek (CN) dari sertifikat ID EST yang dihasilkan selalu sama dengan ID perangkat yang dikonfigurasi di bawah bagian provisi. File-file ini harus dapat dibaca oleh pengguna aziotcs dan aziotks, masing-masing.
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"
Penerbitan sertifikasi melalui CA lokal
[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 (Modul Platform Tepercaya)
Jika Anda memerlukan konfigurasi khusus untuk TPM saat menggunakan provisi TPM DPS, gunakan pengaturan TPM ini.
Untuk string pemuat TCTI yang dapat diterima, lihat bagian 3.5 spesifikasi API TCG TSS 2.0 TPM Command Transmission Interface (TCTI).
Pengaturan ke string kosong menyebabkan pustaka pemuat TCTI mencoba memuat serangkaian modul TCTI yang telah ditentukan sebelumnya secara berurutan.
[tpm]
tcti = "swtpm:port=2321"
Indeks TPM mempertahankan kunci autentikasi DPS. Indeks diambil sebagai offset dari alamat dasar untuk objek persisten seperti 0x81000000 dan harus terletak dalam rentang dari 0x00_00_00 ke 0x7F_FF_FF. Nilai defaultnya adalah 0x00_01_00.
auth_key_index = "0x00_01_00"
Gunakan nilai otorisasi untuk hierarki dukungan dan pemilik, jika diperlukan. Secara default, nilai-nilai ini adalah string kosong.
[tpm.hierarchy_authorization]
endorsement = "hello"
owner = "world"
PKCS#11
Jika Anda menggunakan URI PKCS#11, gunakan parameter berikut dan ganti nilai dengan konfigurasi PKCS#11 Anda.
[aziot_keys]
pkcs11_lib_path = "/usr/lib/libmypkcs11.so"
pkcs11_base_slot = "pkcs11:slot-id=0?pin-value=1234"
Agen Edge Default
Saat IoT Edge dimulai untuk pertama kalinya, IoT Edge melakukan bootstrap modul Edge Agent default. Jika Anda perlu mengambil alih parameter yang disediakan ke modul Agen Edge default, gunakan bagian ini dan ganti nilai dengan nilai Anda sendiri.
Catatan
Parameter agent.config.createOptions ditentukan sebagai tabel sebaris TOML. Format ini terlihat seperti JSON tetapi bukan JSON. Untuk informasi selengkapnya, lihat Tabel Sebaris dokumentasi 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"
Manajemen daemon dan titik akhir API beban kerja
Jika Anda perlu mengambil alih titik akhir API manajemen dan beban kerja, gunakan bagian ini dan ganti nilai dengan nilai Anda sendiri.
[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"
Pengawas Agen Edge
Jika Anda perlu mengambil alih pengaturan pengawasan Agen Edge default, gunakan bagian ini dan ganti nilai dengan milik Anda sendiri.
[watchdog]
max_retries = "infinite" # the string "infinite" or a positive integer. Defaults to "infinite"
Sertifikat OS Tepi
Jika Anda memiliki sertifikat Edge CA Anda sendiri yang mengeluarkan semua sertifikat modul Anda, gunakan salah satu bagian ini dan ganti nilai dengan milik Anda sendiri.
Sertifikat CA Edge dimuat dari 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
Sertifikat CA Edge yang dikeluarkan melalui EST
[edge_ca]
method = "est"
Untuk informasi selengkapnya tentang menggunakan server EST, lihat Tutorial: Mengonfigurasi Pendaftaran melalui Secure Transport Server untuk Azure IoT Edge.
Konfigurasi EST opsional untuk menerbitkan sertifikat CA Edge
Jika tidak diatur, default dalam [cert_issuance.est] digunakan.
common_name = "aziot-edge CA"
expiry_days = 90
url = "https://example.org/.well-known/est"
username = "estuser"
password = "estpwd"
Sertifikasi ID EST sudah ada di perangkat
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
Sertifikasi ID EST diminta melalui sertifikasi 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
Sertifikat CA Edge yang dikeluarkan dari sertifikat CA lokal
Memerlukan [cert_issuance.local_ca] untuk diatur.
[edge_ca]
method = "local_ca"
# Optional configuration
common_name = "aziot-edge CA"
expiry_days = 90
Sertifikat mulai cepat EDGE CA
Jika Anda tidak memiliki sertifikat Edge CA Anda sendiri yang digunakan untuk menerbitkan semua sertifikat modul, gunakan bagian ini dan atur jumlah hari untuk masa pakai sertifikat Edge CA yang ditandatangani sendiri yang dibuat sendiri. Kedaluwarsa default menjadi 90 hari.
Perhatian
Pengaturan ini TIDAK disarankan untuk penggunaan produksi. Silakan konfigurasikan sertifikat Edge CA Anda sendiri di bagian sertifikat EDGE CA.
[edge_ca]
auto_generated_edge_ca_expiry_days = 90
Telusur otomatis sertifikat CA Edge
Pengaturan ini mengelola autorenewal sertifikat CA Edge. Autorenewal berlaku saat CA Edge dikonfigurasi sebagai mulai cepat atau saat EDGE CA memiliki set penerbitan method . Sertifikat CA Edge yang dimuat dari file umumnya tidak dapat dibuat otomatis karena runtime Edge tidak memiliki informasi yang cukup untuk memperbaruinya.
Penting
Perpanjangan CA Edge mengharuskan semua sertifikat server yang dikeluarkan oleh CA tersebut untuk diregenerasi. Regenerasi ini dilakukan dengan memulai ulang semua modul. Waktu perpanjangan CA Edge tidak dapat dijamin. Jika mulai ulang modul acak tidak dapat diterima untuk kasus penggunaan Anda, nonaktifkan autorenewal.
[edge_ca.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"
Pengumpulan sampah gambar
Jika Anda perlu mengambil alih konfigurasi pengumpulan sampah gambar default, gunakan bagian ini dan ganti nilai di bagian ini dengan milik Anda sendiri.
| Parameter | Deskripsi |
|---|---|
enabled |
Menjalankan pengumpulan sampah gambar |
cleanup_recurrence |
Seberapa sering Anda ingin pengumpulan sampah gambar dijalankan |
image_age_cleanup_threshold |
Usia gambar yang tidak digunakan. Gambar yang lebih lama dari ambang dihapus |
cleanup_time |
Format HH:MM 24 jam. Ketika pekerjaan pembersihan berjalan |
[image_garbage_collection]
enabled = true
cleanup_recurrence = "1d"
image_age_cleanup_threshold = "7d"
cleanup_time = "00:00"
Runtime Moby
Jika Anda perlu mengambil alih konfigurasi runtime Moby default, gunakan bagian ini dan ganti nilai dengan nilai Anda sendiri.
[moby_runtime]
uri = "unix:///var/run/docker.sock"
network = "azure-iot-edge"