IoT Edge 디바이스 설정 구성
적용 대상:
IoT Edge 1.5 IoT Edge 1.4
Important
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를 사용하여 변경 내용을 적용합니다.
글로벌 매개 변수
호스트 이름, parent_hostname, trust_bundle_cert, allow_elevated_docker_permissions 및 auto_reprovisioning_mode 매개 변수는 다른 섹션보다 먼저 구성 파일의 시작 부분에 있어야 합니다. 설정 컬렉션 앞에 매개 변수를 추가하면 매개 변수가 올바르게 적용됩니다. 유효한 구문에 대한 자세한 내용은 toml.io를 참조하세요.
Hostname
게이트웨이 검색을 사용하도록 설정하려면 모든 IoT Edge 게이트웨이(부모) 디바이스는 자식 디바이스가 로컬 네트워크에서 찾을 때 사용할 hostname 매개 변수를 지정해야 합니다. 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 구성을 지정합니다. 매개 변수 값을 디바이스의 루트 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 프로비전 모드 설정에 대한 자세한 내용은 이 문서의 프로비전 섹션을 참조하세요.
다음 값 중 하나를 설정할 수 있습니다.
| 모드 | 설명 |
|---|---|
| 동적 | 디바이스가 한 IoT Hub에서 다른 IoT Hub로 이동되었을 수 있음을 검색할 때 다시 프로비전합니다. 이 모드가 기본값입니다. |
| AlwaysOnStartup | 디바이스가 다시 부팅되거나 크래시로 인해 디먼이 다시 시작되면 다시 프로비전합니다. |
| OnErrorOnly | 디바이스 다시 프로비전을 자동으로 트리거하지 마세요. 디바이스 다시 프로비전은 연결 오류로 인해 ID 프로비전 중에 디바이스가 IoT Hub에 연결할 수 없는 경우에만 대체로 발생합니다. 이 대체 동작은 동적 및 AlwaysOnStartup 모드에서도 내포되어 있습니다. |
예시:
auto_reprovisioning_mode = "Dynamic"
디바이스 다시 프로비전에 대한 자세한 내용은 IoT Hub 디바이스 다시 프로비전 개념을 참조하세요.
프로비저닝
IoT Edge 솔루션의 요구 사항에 따라 대규모로 단일 디바이스 또는 여러 디바이스를 프로비저닝할 수 있습니다. IoT Edge 디바이스와 IoT Hub 간의 통신을 인증하는 데 사용할 수 있는 옵션은 선택한 프로비저닝 방법에 따라 달라집니다.
연결 문자열, 대칭 키, 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 인증서 자동 갱신 사용
자동 갱신에는 알려진 인증서 발급 방법이 필요합니다. 방법을 est 또는 local_ca로 설정합니다.
Important
이 디바이스가 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 디바이스 만들기 및 프로비전을 참조하세요.
클라우드 제한 시간 및 다시 시도 동작
이러한 설정은 프로비전 중 DPS(Device Provisioning Service)와의 통신 또는 모듈 ID 만들기를 위한 IoT Hub와 같은 클라우드 작업에 대한 제한 시간 및 다시 시도를 제어합니다.
cloud_timeout_sec 매개 변수는 클라우드 서비스에 대한 네트워크 요청의 기한(초)입니다. 예를 들어, HTTP 요청입니다. 이 기한 전에 클라우드 서비스의 응답을 받아야 합니다. 그렇지 않으면 요청이 시간 제한으로 실패합니다.
cloud_retries 매개 변수는 첫 번째 시도가 실패한 후 요청을 다시 시도할 수 있는 횟수를 제어합니다. 클라이언트는 항상 최소 한 번 전송하므로 값은 첫 번째 시도 실패 후 다시 시도 횟수입니다. 예를 들어, 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 인증서를 만드는 데 한 번 사용되는 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 설정을 사용합니다.
TCG TSS 2.0 TCTI(TPM 명령 전송 인터페이스) API 사양의 섹션 3.5에서 허용되는 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
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 에이전트 모듈에 제공된 매개 변수를 재정의해야 하는 경우 이 섹션을 사용하고 해당 값을 고유의 값으로 바꿉니다.
참고 항목
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 에이전트 Watchdog
기본 Edge 에이전트 Watchdog 설정을 재정의해야 하는 경우 이 섹션을 사용하여 값을 고유의 값으로 바꿉니다.
[watchdog]
max_retries = "infinite" # the string "infinite" or a positive integer. Defaults to "infinite"
에지 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용 보안 전송 서버를 통한 등록 구성을 참조하세요.
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 런타임에 갱신할 정보가 충분하지 않으므로 자동 갱신할 수 없습니다.
Important
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"