تكوين إعدادات جهاز IoT Edge

ينطبق على: IoT Edge 1.5 IoT Edge 1.4

هام

IoT Edge 1.5 LTS وIoT Edge 1.4 LTS هي إصدارات مدعومة. IoT Edge 1.4 LTS هو نهاية العمر الافتراضي في 12 نوفمبر 2024. إذا كنت تستخدم إصدارا سابقا، فشاهد تحديث IoT Edge.

توضح هذه المقالة الإعدادات والخيارات لتكوين ملف IoT Edge /etc/aziot/config.toml لجهاز IoT Edge. يستخدم IoT Edge ملف config.toml لتهيئة إعدادات الجهاز. يحتوي كل قسم من أقسام ملف config.toml على عدة خيارات. ليست جميع الخيارات إلزامية، لأنها تنطبق على سيناريوهات محددة.

يمكن العثور على قالب يحتوي على جميع الخيارات في ملف config.toml.edge.template داخل الدليل /etc/aziot على جهاز IoT Edge. يمكنك نسخ محتويات القالب بالكامل أو أقسام القالب إلى ملف config.toml. قم بإلغاء التعليق على الأقسام التي تحتاج إليها. كن على علم بعدم النسخ عبر المعلمات التي قمت بتعريفها بالفعل.

إذا قمت بتغيير تكوين الجهاز، فاستخدم sudo iotedge config apply لتطبيق التغييرات.

معلمات عمومية

يجب أن تكون معلمات اسم المضيف parent_hostname trust_bundle_cert allow_elevated_docker_permissions auto_reprovisioning_mode في بداية ملف التكوين قبل أي أقسام أخرى. تضمن إضافة المعلمات قبل مجموعة من الإعدادات تطبيقها بشكل صحيح. لمزيد من المعلومات حول بناء الجملة الصالح، راجع toml.io.

اسم المضيف

لتمكين اكتشاف البوابة، يحتاج كل جهاز بوابة IoT Edge (أصل) إلى تحديد معلمة اسم المضيف التي تستخدمها أجهزته التابعة للعثور عليها على الشبكة المحلية. تستخدم الوحدة النمطية edgeHub أيضا معلمة اسم المضيف لمطابقتها مع شهادة الخادم الخاصة بها. لمزيد من المعلومات، راجع لماذا يحتاج EdgeGateway إلى إخباره عن اسم المضيف الخاص به؟.

إشعار

عندما لا يتم تعيين قيمة اسم المضيف، يحاول IoT Edge العثور عليها تلقائيا. ومع ذلك، قد لا يتمكن العملاء في الشبكة من اكتشاف الجهاز إذا لم يتم تعيينه.

بالنسبة إلى اسم المضيف، استبدل fqdn-device-name-or-ip-address باسم جهازك لتجاوز اسم المضيف الافتراضي للجهاز. يمكن أن تكون القيمة اسم مجال مؤهل بالكامل (FQDN) أو عنوان IP. استخدم هذا الإعداد باعتباره اسم مضيف البوابة على جهاز بوابة IoT Edge.

hostname = "fqdn-device-name-or-ip-address"

اسم المضيف الأصل

يتم استخدام اسم المضيف الأصل عندما يكون جهاز IoT Edge جزءا من التسلسل الهرمي، والمعروف باسم الحافة المتداخلة. يحتاج كل جهاز IoT Edge في المراحل النهائية إلى تحديد معلمة parent_hostname لتحديد الأصل الخاص به. في سيناريو هرمي حيث يكون جهاز IoT Edge واحد هو أحد الأجهزة الأصلية والتابعة على حد سواء، فإنه يحتاج إلى كل من المعلمتين.

استبدل fqdn-parent-device-name-or-ip-address باسم جهازك الأصل. استخدم اسم مضيف أقصر من 64 حرفا، وهو حد الأحرف للاسم الشائع لشهادة الخادم.

parent_hostname = "fqdn-parent-device-name-or-ip-address"

لمزيد من المعلومات حول تعيين المعلمة parent_hostname ، راجع توصيل أجهزة Azure IoT Edge معا لإنشاء تسلسل هرمي.

شهادة حزمة الثقة

لتوفير شهادة مرجع مصدق مخصص (CA) كجذر ثقة ل IoT Edge والوحدات النمطية ، حدد تكوين trust_bundle_cert . استبدل قيمة المعلمة بملف URI إلى شهادة المرجع المصدق الجذر على جهازك.

trust_bundle_cert = "file:///var/aziot/certs/trust-bundle.pem"

لمزيد من المعلومات حول مجموعة ثقة IoT Edge، راجع إدارة المرجع المصدق الجذر الموثوق به.

أذونات Docker غير مقيدة

يمكن استخدام بعض قدرات docker للوصول إلى الجذر. بشكل افتراضي، يسمح بالعلامة --privileged وجميع الإمكانات المدرجة في المعلمة CapAdd ل docker HostConfig .

إذا لم تتطلب أي وحدات نمطية قدرات مميزة أو إضافية، فاستخدم allow_elevated_docker_permissions لتحسين أمان الجهاز.

allow_elevated_docker_permissions = false

وضع إعادة التزويد التلقائي

تحدد معلمة auto_reprovisioning_mode الاختيارية الشروط التي تقرر متى يحاول الجهاز إعادة التزويد تلقائيا باستخدام خدمة تزويد الأجهزة. يتم تجاهل وضع التوفير التلقائي إذا تم توفير الجهاز يدويا. لمزيد من المعلومات حول تعيين وضع توفير DPS، راجع قسم التزويد في هذه المقالة لمزيد من المعلومات.

يمكن تعيين إحدى القيم التالية:

وضع	‏‏الوصف
ديناميكي	إعادة التوفير عندما يكتشف الجهاز أنه ربما تم نقله من مركز IoT إلى آخر. هذا الوضع هو الوضع الافتراضي.
AlwaysOnStartup	إعادة التوفير عند إعادة تشغيل الجهاز أو حدوث عطل يؤدي إلى إعادة تشغيل البرامج الخفية.
OnErrorOnly	لا تقم أبدا بتشغيل إعادة توفير الجهاز تلقائيا. تحدث إعادة توفير الجهاز فقط على أنها احتياطية، إذا كان الجهاز غير قادر على الاتصال ب IoT Hub أثناء توفير الهوية بسبب أخطاء الاتصال. هذا السلوك الاحتياطي ضمني في الوضعين Dynamic و AlwaysOnStartup أيضا.

على سبيل المثال:

auto_reprovisioning_mode = "Dynamic"

لمزيد من المعلومات حول إعادة توفير الجهاز، راجع مفاهيم إعادة توفير جهاز IoT Hub.

التزويد

يمكنك توفير جهاز واحد أو أجهزة متعددة على نطاق واسع، اعتمادا على احتياجات حل IoT Edge الخاص بك. تعتمد الخيارات المتاحة لمصادقة الاتصالات بين أجهزة IoT Edge ومراكز IoT الخاصة بك على طريقة التزويد التي تختارها.

يمكنك التوفير باستخدام سلسلة الاتصال أو مفتاح متماثل أو شهادة X.509 أو مفتاح خاص لشهادة الهوية أو شهادة هوية. يتم تضمين توفير DPS مع خيارات مختلفة. اختر أسلوبا واحدا للتزويد الخاص بك. استبدل قيم العينة بقيمك الخاصة.

التوفير اليدوي مع سلسلة الاتصال

[provisioning]
source = "manual"
connection_string = "HostName=example.azure-devices.net;DeviceId=my-device;SharedAccessKey=<Shared access key>"

لمزيد من المعلومات حول استرداد معلومات التوفير، راجع إنشاء وتوفير جهاز IoT Edge على Linux باستخدام مفاتيح متماثلة.

التوفير اليدوي باستخدام مفتاح متماثل

[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

لمزيد من المعلومات حول استرداد معلومات التوفير، راجع إنشاء وتوفير جهاز IoT Edge على Linux باستخدام مفاتيح متماثلة.

التوفير اليدوي مع شهادة X.509

[provisioning]
source = "manual"
iothub_hostname = "example.azure-devices.net"
device_id = "my-device"

[provisioning.authentication]
method = "x509"

لمزيد من المعلومات حول التوفير باستخدام شهادات X.509، راجع إنشاء وتوفير جهاز IoT Edge على Linux باستخدام شهادات X.509.

توفير DPS باستخدام مفتاح متماثل

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

لمزيد من المعلومات حول توفير DPS باستخدام مفتاح متماثل، راجع إنشاء أجهزة IoT Edge وتوفيرها على نطاق واسع على Linux باستخدام مفتاح متماثل.

تزويد DPS بشهادات 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

(اختياري) تمكين التجديد التلقائي لشهادة معرف الجهاز

يتطلب Autorenewal أسلوب إصدار شهادة معروف. تعيين الأسلوب إلى إما est أو local_ca.

هام

تمكين إعادة التوليد التلقائي فقط إذا تم تكوين هذا الجهاز لتسجيل DPS المستند إلى CA. يؤدي استخدام autorenewal لتسجيل فردي إلى عدم تمكن الجهاز من إعادة التوفير.

[provisioning.attestation.identity_cert.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"

لمزيد من المعلومات حول تزويد DPS بشهادات X.509، راجع إنشاء أجهزة IoT Edge وتوفيرها على نطاق واسع على Linux باستخدام شهادات X.509.

توفير DPS مع TPM (وحدة النظام الأساسي الموثوق بها)

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

إذا كنت تستخدم توفير DPS مع TPM، وتتطلب تكوينا مخصصا، فشاهد قسم TPM .

لمزيد من المعلومات، راجع إنشاء وتوفير أجهزة IoT Edge على نطاق واسع باستخدام TPM على Linux.

مهلة السحابة وسلوك إعادة المحاولة

تتحكم هذه الإعدادات في المهلة وإعادة المحاولة للعمليات السحابية، مثل الاتصال بخدمة توفير الأجهزة (DPS) أثناء التوفير أو IoT Hub لإنشاء هوية الوحدة النمطية.

المعلمة cloud_timeout_sec هي الموعد النهائي في ثوان لطلب الشبكة إلى الخدمات السحابية. على سبيل المثال، طلب HTTP. يجب تلقي استجابة من الخدمة السحابية قبل هذا الموعد النهائي، أو يفشل الطلب كمهلة.

تتحكم المعلمة cloud_retries في عدد المرات التي قد تتم فيها إعادة محاولة الطلب بعد فشل المحاولة الأولى. يرسل العميل دائما مرة واحدة على الأقل، لذلك القيمة هي عدد مرات إعادة المحاولة بعد فشل المحاولة الأولى. على سبيل المثال، cloud_retries = 2 يعني أن العميل يقوم بثلاث محاولات إجمالية.

cloud_timeout_sec = 10
cloud_retries = 1

إصدار الشهادة

إذا قمت بتكوين أي شهادات صادرة ديناميكيا، فاختر أسلوب الإصدار المقابل واستبدل قيم العينة بالقيم الخاصة بك.

إصدار الشهادة عبر EST

[cert_issuance.est]
trusted_certs = ["file:///var/aziot/certs/est-id-ca.pem",]

[cert_issuance.est.auth]
username = "estuser"
password = "estpwd"

شهادة معرف EST بالفعل على الجهاز

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 المطلوبة عبر شهادة معرف EST bootstrap

المصادقة مع شهادة عميل TLS التي يتم استخدامها مرة واحدة لإنشاء شهادة معرف EST الأولية. بعد إصدار الشهادة الأولى، identity_cert يتم إنشاء و identity_pk تلقائيا واستخدامه للمصادقة والتجديدات المستقبلية. الاسم المشترك للموضوع (CN) لشهادة معرف EST الذي تم إنشاؤه هو دائما نفس معرف الجهاز المكون ضمن قسم التوفير. يجب أن تكون هذه الملفات قابلة للقراءة من قبل المستخدمين aziotcs و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"

إصدار الشهادة عبر المرجع المصدق المحلي

[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 (الوحدة النمطية للنظام الأساسي الموثوق به)

إذا كنت بحاجة إلى تكوين خاص ل TPM عند استخدام توفير DPS TPM، فاستخدم إعدادات TPM هذه.

للحصول على سلاسل تحميل TCTI المقبولة، راجع القسم 3.5 من مواصفات واجهة برمجة تطبيقات TCG TSS 2.0 TPM Command Transmission Interface (TCTI).

يؤدي الإعداد إلى سلسلة فارغة إلى محاولة مكتبة محمل TCTI تحميل مجموعة معرفة مسبقا من وحدات TCTI بالترتيب.

[tpm]
tcti = "swtpm:port=2321"

يستمر فهرس TPM في مفتاح مصادقة DPS. يتم أخذ الفهرس كإزاحة من العنوان الأساسي للكائنات الثابتة مثل 0x81000000 ويجب أن يقع في النطاق من 0x00_00_00 إلى 0x7F_FF_FF. القيمة الافتراضية هي 0x00_01_00.

auth_key_index = "0x00_01_00"

استخدم قيم التخويل للمصادقة والتسلسلات الهرمية للمالك، إذا لزم الأمر. بشكل افتراضي، هذه القيم هي سلاسل فارغة.

[tpm.hierarchy_authorization]
endorsement = "hello"
owner = "world"

PKCS#11

إذا استخدمت أي عناوين URL ل PKCS#11، فاستخدم المعلمات التالية واستبدل القيم بتكوين PKCS#11.

[aziot_keys]
pkcs11_lib_path = "/usr/lib/libmypkcs11.so"
pkcs11_base_slot = "pkcs11:slot-id=0?pin-value=1234"

عامل Edge الافتراضي

عندما يبدأ تشغيل IoT Edge في المرة الأولى، فإنه يقوم بتمهيد وحدة نمطية افتراضية ل Edge Agent. إذا كنت بحاجة إلى تجاوز المعلمات المقدمة إلى الوحدة النمطية الافتراضية ل Edge Agent، فاستخدم هذا القسم واستبدل القيم بالقيم الخاصة بك.

إشعار

agent.config.createOptions يتم تحديد المعلمة كجدول مضمن TOML. يبدو هذا التنسيق مثل JSON ولكنه ليس JSON. لمزيد من المعلومات، راجع الجدول المضمن لوثائق 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"

إدارة Daemon ونقاط نهاية API لحمل العمل

إذا كنت بحاجة إلى تجاوز نقاط نهاية واجهة برمجة تطبيقات الإدارة وأحمال العمل، فاستخدم هذا القسم واستبدل القيم بالقيم الخاصة بك.

[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

إذا كنت بحاجة إلى تجاوز إعدادات مراقب عامل Edge الافتراضية، فاستخدم هذا القسم واستبدل القيم بالقيم الخاصة بك.

[watchdog]
max_retries = "infinite"   # the string "infinite" or a positive integer. Defaults to "infinite"

شهادة Edge CA

إذا كان لديك شهادة Edge CA الخاصة بك التي تصدر جميع شهادات الوحدة النمطية الخاصة بك، فاستخدم أحد هذه الأقسام واستبدل القيم بالقيم الخاصة بك.

شهادة المرجع المصدق Edge المحملة من ملف

[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 الصادرة عبر EST

[edge_ca]
method = "est"

لمزيد من المعلومات حول استخدام خادم EST، راجع البرنامج التعليمي: تكوين التسجيل عبر خادم النقل الآمن ل Azure IoT Edge.

تكوين EST الاختياري لإصدار شهادة المرجع المصدق Edge

إذا لم يتم تعيينها، يتم استخدام الإعدادات الافتراضية في [cert_issuance.est].

common_name = "aziot-edge CA"
expiry_days = 90
url = "https://example.org/.well-known/est"

username = "estuser"
password = "estpwd"

شهادة معرف EST بالفعل على الجهاز

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 المطلوبة عبر شهادة معرف EST bootstrap

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 محلية

يتطلب تعيين [cert_issuance.local_ca].

[edge_ca]
method = "local_ca"

# Optional configuration
common_name = "aziot-edge CA"
expiry_days = 90

شهادات التشغيل السريع ل Edge CA

إذا لم يكن لديك شهادة المرجع المصدق Edge الخاصة بك المستخدمة لإصدار جميع شهادات الوحدة النمطية، فاستخدم هذا القسم وقم بتعيين عدد الأيام لمدة بقاء شهادة المرجع المصدق Edge الموقعة ذاتيا التي تم إنشاؤها تلقائيا. يتم تعيين انتهاء الصلاحية افتراضيا إلى 90 يوما.

تنبيه

هذا الإعداد غير مستحسن لاستخدام الإنتاج. يرجى تكوين شهادة المرجع المصدق Edge الخاصة بك في أقسام شهادة المرجع المصدق Edge.

[edge_ca]
auto_generated_edge_ca_expiry_days = 90

شهادة المرجع المصدق Edge autorenewal

يدير هذا الإعداد إعادة التوليد التلقائي لشهادة المرجع المصدق Edge. ينطبق Autorenewal عند تكوين المرجع المصدق Edge كتشغيل سريع أو عندما يكون لدى المرجع المصدق Edge مجموعة إصدارmethod. لا يمكن إعادة كتابة شهادات المرجع المصدق Edge المحملة من الملفات تلقائيا بشكل عام لأن وقت تشغيل Edge لا يحتوي على معلومات كافية لتجديدها.

هام

يتطلب تجديد المرجع المصدق Edge إعادة إنشاء جميع شهادات الخادم الصادرة عن المرجع المصدق هذا. يتم هذا التجديد عن طريق إعادة تشغيل جميع الوحدات النمطية. لا يمكن ضمان وقت تجديد المرجع المصدق ل Edge. إذا كانت عمليات إعادة تشغيل الوحدة النمطية العشوائية غير مقبولة لحالة الاستخدام الخاصة بك، ف قم بتعطيل autorenewal عن طريق عدم تضمين قسم [edge_ca.auto_renew].

[edge_ca.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"

مجموعة البيانات المهملة للصور

إذا كنت بحاجة إلى تجاوز تكوين مجموعة البيانات المهملة للصور الافتراضية، فاستخدم هذا القسم واستبدل القيم الموجودة في هذا القسم بالقيم الخاصة بك.

المعلمة	‏‏الوصف‬
enabled	تشغيل مجموعة البيانات المهملة للصور
cleanup_recurrence	عدد المرات التي تريد فيها تشغيل مجموعة البيانات المهملة للصور
image_age_cleanup_threshold	عمر الصور غير المستخدمة. تتم إزالة الصور الأقدم من الحد
cleanup_time	تنسيق HH:MM على مدار 24 ساعة. عند تشغيل مهمة التنظيف

[image_garbage_collection]
enabled = true
cleanup_recurrence = "1d"
image_age_cleanup_threshold = "7d"
cleanup_time = "00:00"

وقت تشغيل Moby

إذا كنت بحاجة إلى تجاوز تكوين وقت تشغيل Moby الافتراضي، فاستخدم هذا القسم واستبدل القيم بالقيم الخاصة بك.

[moby_runtime]
uri = "unix:///var/run/docker.sock"
network = "azure-iot-edge"