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 は、2024 年 11 月 12 日にサポートが終了します。 以前のリリースの場合は、「IoT Edge を更新する」を参照してください。
この記事では、IoT Edge デバイスの IoT Edge /etc/aziot/config.toml ファイルを構成するための設定とオプションについて説明します。 IoT Edge では、config.toml ファイルを使用してデバイスの設定を初期化します。 config.toml ファイルの各セクションには、いくつかのオプションがあります。 特定のシナリオに適用されるため、すべてのオプションが必須なわけではありません。
すべてのオプションを含むテンプレートは、IoT Edge デバイスの /etc/aziot ディレクトリ内の config.toml.edge.template ファイルにあります。 テンプレート全体またはテンプレートのセクションの内容を config.toml ファイルにコピーできます。 必要なセクションをコメント解除します。 既に定義したパラメーターをコピーしないように注意してください。
デバイスの構成を変更する場合、sudo iotedge config apply を使用して変更を適用します。
グローバル パラメーター
hostname、parent_hostname、trust_bundle_cert、allow_elevated_docker_permissions、auto_reprovisioning_mode の各パラメーターは構成ファイルの先頭に、また他のどのセクションよりも前にある必要があります。 パラメーターは、設定のコレクションよりも前に追加すると、確実に正しく適用されます。 有効な構文の詳細については、toml.io に関する記事ををご覧ください。
hostname
ゲートウェイの検出を有効にするには、すべての IoT Edge ゲートウェイ (親) デバイスで、その子デバイスがローカル ネットワーク上でそれを見つけるために用いる hostname パラメーターを指定する必要があります。 さらに、edgeHub モジュールでは、hostname パラメーターを使用してそのサーバー証明書と照合します。 詳細については、「EdgeGateway に自身のホスト名を通知する必要があるのはなぜですか?」を参照してください。
Note
hostname の値が設定されていない場合、IoT Edge は自動検出を試みます。 ただし、設定されていない場合、ネットワーク内のクライアントがデバイスを検出できない可能性があります。
hostname では、fqdn-device-name-or-ip-address を適切なデバイス名に置き換えて、デバイスの既定のホスト名をオーバーライドします。 値には完全修飾ドメイン名 (FQDN) または IP アドレスを指定できます。 IoT Edge ゲートウェイ デバイスでは、この設定をゲートウェイのホスト名として使用します。
hostname = "fqdn-device-name-or-ip-address"
親のホスト名
親のホスト名は、IoT Edge デバイスが、入れ子になったエッジとも呼ばれる階層の一部である場合に使用されます。 すべてのダウンストリーム IoT Edge デバイスでは、その親を識別するために parent_hostname パラメーターを指定する必要があります。 1 つの IoT Edge デバイスが親と子デバイスの両方である階層シナリオの場合は、両方のパラメーターが必要です。
fqdn-parent-device-name-or-ip-address は、適切な親デバイスの名前に置き換えます。 64 文字未満のホスト名を使用します。これは、サーバー証明書共通名の文字数制限です。
parent_hostname = "fqdn-parent-device-name-or-ip-address"
parent_hostname パラメーターの設定の詳細については、「複数の Azure IoT Edge デバイスを接続して階層を作成する」を参照してください。
バンドル証明書を信頼する
IoT Edge とモジュールの信頼のルートとしてカスタム証明機関 (CA) 証明書を提供するには、trust_bundle_cert 構成を指定します。 パラメーターの値をデバイス上のルート CA 証明書のファイル URI に置き換えます。
trust_bundle_cert = "file:///var/aziot/certs/trust-bundle.pem"
IoT Edge 信頼バンドルの詳細については、信頼されたルート CA の管理に関するページを参照してください。
管理者特権での Docker アクセス許可
一部の Docker 機能を使用してルート アクセスを取得できます。 既定では、--privileged フラグと、Docker の HostConfig の CapAdd パラメーターにリストされているすべての機能が許可されます。
特権または追加の機能を必要とするモジュールがない場合は、allow_elevated_docker_permissions を使用してデバイスのセキュリティを強化します。
allow_elevated_docker_permissions = false
自動再プロビジョニング モード
省略可能な auto_reprovisioning_mode パラメーターでは、デバイスで Device Provisioning Service を使用して自動的に再プロビジョニングを試みるタイミングを決定する条件を指定します。 自動プロビジョニング モードは、デバイスが手動でプロビジョニングされている場合は無視されます。 DPS プロビジョニング モードの設定の詳細については、この記事の「プロビジョニング」セクションを参照してください。
次のいずれかの値を設定できます。
| モード | 説明 |
|---|---|
| 動的 | 1 つの IoT Hub から別の IoT Hub にデバイスが移動されたことがデバイスで検出されたときに再プロビジョニングします。 これが既定のモードです。 |
| AlwaysOnStartup | デバイスが再起動されたとき、またはクラッシュによってデーモンが再起動されたときに再プロビジョニングします。 |
| OnErrorOnly | デバイスの再プロビジョニングを自動的にトリガーしません。 デバイスの再プロビジョニングは、接続エラーが原因で ID プロビジョニング中にデバイスが IoT Hub に接続できない場合のフォールバックとしてのみ発生します。 このフォールバック動作は、Dynamic モードと AlwaysOnStartup モードでも暗黙的です。 |
次に例を示します。
auto_reprovisioning_mode = "Dynamic"
デバイスの再プロビジョニングの詳細については、「IoT Hub デバイスの再プロビジョニングの概念」を参照してください。
プロビジョニング
IoT Edge ソリューションのニーズに応じて、単一デバイス、または複数のデバイスを大規模にプロビジョニングすることができます。 IoT Edge デバイスと IoT ハブ間の通信を認証するために使用できるオプションは、選択するプロビジョニング方法によって異なります。
接続文字列、対称キー、X.509 証明書、ID 証明書秘密キー、または ID 証明書を使用してプロビジョニングできます。 DPS プロビジョニングにはさまざまなオプションが含まれています。 いずれかのプロビジョニング方法を選択してください。 サンプル値は独自の値に置き換えてください。
接続文字列を使用した手動プロビジョニング
[provisioning]
source = "manual"
connection_string = "HostName=example.azure-devices.net;DeviceId=my-device;SharedAccessKey=<Shared access key>"
プロビジョニング情報の取得の詳細については、「対称キーを使用して Linux で IoT Edge デバイスを作成およびプロビジョニングする」を参照してください。
対称キーを使用した手動プロビジョニング
[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
プロビジョニング情報の取得の詳細については、「対称キーを使用して Linux で IoT Edge デバイスを作成およびプロビジョニングする」を参照してください。
X.509 証明書を使用した手動プロビジョニング
[provisioning]
source = "manual"
iothub_hostname = "example.azure-devices.net"
device_id = "my-device"
[provisioning.authentication]
method = "x509"
X.509 証明書を使用したプロビジョニングの詳細については、「X.509 証明書を使用して Linux で IoT Edge デバイスを作成およびプロビジョニングする」を参照してください。
対称キーを使用した 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 プロビジョニングの詳細については、「対称キーを使用して Linux で大規模に IoT Edge デバイスを作成およびプロビジョニングする」を参照してください。
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 = "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
(省略可能) デバイス ID 証明書の自動更新を有効にする
自動更新には、既知の証明書発行方法が必要です。 method を est または local_ca に設定します。
重要
自動更新は、このデバイスで CA ベースの DPS 登録が構成されている場合にのみ有効にしてください。 個々の登録に自動更新を使用すると、デバイスを再プロビジョニングできなくなります。
[provisioning.attestation.identity_cert.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"
X.509 証明書を使用した DPS プロビジョニングの詳細については、「X.509 証明書を使用して、Linux 上で IoT Edge デバイスを大規模に作成およびプロビジョニングする」を参照してください。
TPM (トラステッド プラットフォーム モジュール) を使用した 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 = "tpm"
registration_id = "my-device"
TPM を使用した DPS プロビジョニングを使用し、カスタム構成を要求する場合、TPM セクションを設定します。
詳細については、「Linux で TPM を使用して大規模な IoT Edge デバイスを作成およびプロビジョニングする」を参照してください。
クラウドのタイムアウトと再試行の動作
これらの設定は、プロビジョニング中の Device Provisioning Service (DPS) との通信や、モジュール ID 作成のための IoT Hub との通信など、クラウド操作のタイムアウトと再試行を制御します。
cloud_timeout_sec パラメーターは、クラウド サービスへのネットワーク要求の期限 (秒単位) です。 たとえば、HTTP 要求です。 この期限よりも前にクラウド サービスから応答を受信する必要があり、受信しない場合、要求はタイムアウトになって失敗します。
cloud_retries パラメーターは、最初の試行が失敗した後に要求を再試行できる回数を制御します。 クライアントは常に少なくとも 1 回は送信するため、この値は最初の試行が失敗した後の再試行回数です。 たとえば、cloud_retries = 2 はクライアントが合計 3 回試行することを意味します。
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 ID 証明書がデバイス上に既にある
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 証明書を介して要求された EST ID 証明書
最初の EST ID 証明書を作成するために 1 回使用される TLS クライアント証明書を使用した認証。 最初の証明書の発行後、identity_cert と identity_pk が自動的に作成され、将来の認証と更新に使用されます。 生成される EST ID 証明書のサブジェクト共通名 (CN) は、プロビジョニング セクションの構成済みデバイス ID と常に同じです。 これらのファイルは、それぞれユーザー 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"
ローカル 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 (トラステッド プラットフォーム モジュール)
DPS TPM プロビジョニングを使用するときに TPM 用の特別な構成が必要な場合は、次の TPM 設定を使用します。
使用できる TCTI ローダー文字列については、TCG TSS 2.0 TPM コマンド伝送インターフェイス (TCTI) API 仕様のセクション 3.5 を参照してください。
空の文字列に設定すると、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
PKCS#11 URI を使用した場合は、次のパラメーターを使用し、値を適切な 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 エージェント モジュールをブートストラップします。 既定の Edge エージェント モジュールに渡されるパラメーターをオーバーライドする必要がある場合は、このセクションを使用して、値を独自の値に置き換えます。
Note
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"
デーモン管理およびワークロード API エンドポイント
管理およびワークロード 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 CA 証明書
[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
EST 経由で発行された Edge CA 証明書
[edge_ca]
method = "est"
EST サーバーの使用の詳細については、「チュートリアル: Azure IoT Edge 用に Enrollment over Secure Transport サーバーを構成する」を参照してください。
Edge CA 証明書を発行するための省略可能な EST 構成
設定しない場合、[cert_issuance.est] の既定値が使用されます。
common_name = "aziot-edge CA"
expiry_days = 90
url = "https://example.org/.well-known/est"
username = "estuser"
password = "estpwd"
EST ID 証明書がデバイス上に既にある
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 証明書を介して要求された EST ID 証明書
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
ローカル CA 証明書から発行される Edge CA 証明書
[cert_issuance.local_ca] を設定する必要があります。
[edge_ca]
method = "local_ca"
# Optional configuration
common_name = "aziot-edge CA"
expiry_days = 90
Edge CA クイックスタート証明書
すべてのモジュール証明書の発行に使用する独自の Edge CA 証明書がない場合は、このセクションを使用して、自動生成される自己署名 Edge CA 証明書の有効期間の日数を設定します。 有効期限の既定値は 90 日です。
注意事項
この設定は実稼働での使用にはお勧めしません。 Edge CA 証明書セクションで、独自の Edge CA 証明書を構成してください。
[edge_ca]
auto_generated_edge_ca_expiry_days = 90
Edge CA 証明書の自動更新
この設定は Edge CA 証明書の自動更新を管理します。 自動更新は、Edge CA がクイックスタートとして構成されている場合、または Edge CA に発行 method が設定されている場合に適用されます。 ファイルから読み込まれた Edge CA 証明書は通常、更新のための十分な情報が Edge ランタイムにないため、自動更新できません。
重要
Edge CA を更新するには、その CA によって発行されたすべてのサーバー証明書を再生成する必要があります。 この再生成は、すべてのモジュールを再起動することによって行われます。 Edge CA の更新時間を保証することはできません。 モジュールのランダムな再起動を許容できないユース ケースの場合は、自動更新を無効にしてください。
[edge_ca.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"
イメージのガベージ コレクション
既定のイメージ ガベージ コレクション構成をオーバーライドする必要がある場合は、このセクションを使用し、このセクションの値を独自の値に置き換えます。
| パラメーター | 説明 |
|---|---|
enabled |
イメージのガベージ コレクションを実行する |
cleanup_recurrence |
イメージのガベージ コレクションを実行する頻度 |
image_age_cleanup_threshold |
未使用のイメージが作成されてからの時間。 しきい値より古いイメージは削除されます |
cleanup_time |
24 時間の HH:MM 形式。 クリーンアップ ジョブの実行時間 |
[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"