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 게이트웨이(부모) 디바이스에서 자식 디바이스가 로컬 네트워크에서 검색하는 데 사용하는 호스트 이름 매개 변수를 지정해야 합니다. 또한 edgeHub 모듈은 호스트 이름 매개 변수를 사용하여 서버 인증서와 일치합니다. 자세한 내용은 EdgeGateway가 자체 호스트 이름에 대해 알려야 하는 이유를 참조 하세요.
참고 항목
호스트 이름 값이 설정되지 않으면 IoT Edge에서 자동으로 찾으려고 시도합니다. 그러나 네트워크에 있는 클라이언트가 설정되지 않은 경우 디바이스를 검색하지 못할 수 있습니다.
호스트 이름의 경우 fqdn-device-name-or-ip-address를 디바이스 이름으로 바꿔 디바이스의 기본 호스트 이름을 재정의합니다. 값은 FQDN(정규화된 do기본 이름) 또는 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 기능을 사용하여 루트 액세스를 얻을 수 있습니다. 기본적으로 Docker HostConfig의 --privileged CapAdd 매개 변수에 나열된 플래그 및 모든 기능이 허용됩니다.
권한 있는 또는 추가 기능이 필요한 모듈이 없는 경우 allow_elevated_docker_permissions 사용하여 디바이스의 보안을 개선합니다.
allow_elevated_docker_permissions = false
자동 다시 프로비전 모드
선택적 auto_reprovisioning_mode 매개 변수는 디바이스가 Device Provisioning Service를 사용하여 자동으로 다시 프로비전을 시도하는 시기를 결정하는 조건을 지정합니다. 디바이스가 수동으로 프로비전된 경우 자동 프로비저닝 모드는 무시됩니다. DPS 프로비저닝 모드 설정에 대한 자세한 내용은 이 문서의 프로비전 섹션을 참조하세요.
다음 값 중 하나를 설정할 수 있습니다.
| Mode | 설명 |
|---|---|
| 동적 | 디바이스가 한 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 인증서의 자동 갱신 사용
Autorenewal에는 알려진 인증서 발급 방법이 필요합니다. 메서드를 둘 중 하나 est 또는 local_ca으로 설정합니다.
Important
이 디바이스가 CA 기반 DPS 등록에 대해 구성된 경우에만 autorenewal을 사용하도록 설정합니다. 개별 등록에 autorenewal을 사용하면 디바이스를 다시 프로비전할 수 없습니다.
[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 클라이언트가 총 세 번의 시도를 했음을 의미합니다.
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_certidentity_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_000x7F_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.4"
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 인증서 autorenewal
이 설정은 Edge CA 인증서의 autorenewal을 관리합니다. Autorenewal은 Edge CA가 빠른 시작으로 구성되거나 Edge CA에 발급 method 집합이 있는 경우에 적용됩니다. 일반적으로 파일에서 로드된 Edge CA 인증서는 Edge 런타임에 갱신할 충분한 정보가 없으므로 자동으로 갱신할 수 없습니다.
Important
Edge CA를 갱신하려면 해당 CA에서 발급한 모든 서버 인증서를 다시 생성해야 합니다. 이 다시 생성은 모든 모듈을 다시 시작하여 수행됩니다. Edge CA 갱신 시간을 보장할 수 없습니다. 사용 사례에 대해 임의 모듈 다시 시작을 허용할 수 없는 경우 autorenewal을 사용하지 않도록 설정합니다.
[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"