Definir configurações de dispositivo do IoT Edge

Aplica-se a: IoT Edge 1.5 IoT Edge 1.4

Este artigo mostra as configurações e as opções para configurar o arquivo /etc/aziot/config.toml do IoT Edge de um dispositivo do IoT Edge. O IoT Edge usa o arquivoconfig.toml, para inicializar as configurações do dispositivo. Cada uma das seções do arquivo config.toml tem várias opções. Nem todas as opções são obrigatórias, pois se aplicam a cenários específicos.

Um modelo que contém todas as opções pode ser encontrado no arquivo config.toml.edge.template no diretório /etc/aziot, em um dispositivo do IoT Edge. Copie o conteúdo de todo o modelo ou seções do modelo no arquivo config.toml. Remover marca de comentário das seções necessárias. Lembre-se de não copiar os parâmetros que você já definiu.

Caso altere a configuração de um dispositivo, use sudo iotedge config apply para aplicar as alterações.

Parâmetros globais

Os parâmetros nome do host, parent_hostname, trust_bundle_cert, allow_elevated_docker_permissions e auto_reprovisioning_mode, devem estar no início do arquivo de configuração antes de qualquer outra seção. Adicionar parâmetros antes de uma coleção de configurações garante que eles sejam aplicados corretamente. Para obter mais informações sobre a sintaxe válida, consulte toml.io.

Nome do host

Para habilitar a descoberta de gateway, cada dispositivo (pai) de gateway do IoT Edge precisa especificar um parâmetro nome do host que os respectivos dispositivos filho usam para encontrá-lo na rede local. O módulo edgeHub também usa o parâmetro nome do host para corresponder ao certificado do servidor. Para obter mais informações, consulte Por que o EdgeGateway precisa ser informado sobre seu próprio nome de host?.

Para o nome do host, substitua fqdn-device-name-or-ip-address pelo nome do dispositivo para substituir o nome do host padrão do dispositivo. O valor pode ser um FQDN (nome de domínio totalmente qualificado) ou um endereço IP. Use esta configuração como o nome do host do gateway em um dispositivo de gateway do IoT Edge.

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

Nome do host pai

O nome do host pai é usado quando o dispositivo IoT Edge faz parte de uma hierarquia, também conhecida como borda aninhada. Cada dispositivo do IoT Edge downstream precisa especificar um parâmetro parent_hostname para identificar o respectivo pai. Se um mesmo dispositivo do IoT Edge for um dispositivo pai e filho simultaneamente, ele precisará dos dois parâmetros.

Substitua fqdn-parent-device-name-or-ip-address pelo nome do seu dispositivo pai. Use um nome de host com menos de 64 caracteres, que é o limite para o nome comum do certificado de um servidor.

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

Para obter mais informações sobre como definir o parâmetro parent_hostname, consulte Conectar dispositivos do Azure IoT Edge juntos para criar uma hierarquia.

Certificado de pacote de confiança

Para fornecer um certificado de AC (autoridade de certificação) personalizado como uma raiz de confiança para o IoT Edge e módulos, especifique uma configuração de trust_bundle_cert. Substitua o valor do parâmetro pelo URI do arquivo para o certificado de autoridade de certificação raiz no dispositivo.

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

Para obter mais informações sobre o pacote de confiança do IoT Edge, consulte Gerenciar a AC raiz confiável.

Permissões elevadas do Docker

Alguns recursos do Docker podem ser usados para obter acesso à raiz. Por padrão, o sinalizador --privileged e todos os recursos listados no parâmetro CapAdd de HostConfig do Docker, são permitidos.

Se nenhum módulo exigir recursos privilegiados ou extras, use allow_elevated_docker_permissions, para melhorar a segurança do dispositivo.

allow_elevated_docker_permissions = false

Modo de reprovisionamento automático

O parâmetro opcional auto_reprovisioning_mode especifica as condições que decidem quando um dispositivo tenta reprovisionar automaticamente com o Serviço de Provisionamento de Dispositivos. O modo de provisionamento automático será ignorado se o dispositivo tiver sido provisionado manualmente. Para obter mais informações sobre como definir o modo de provisionamento do DPS, consulte a seção Provisionamento, neste artigo para obter mais informações.

Um dos seguintes valores pode ser definido:

Por exemplo:

auto_reprovisioning_mode = "Dynamic"

Para obter mais informações sobre o reprovisionamento de dispositivos, consulte os Conceitos de reprovisionamento de dispositivos do Hub IoT.

Provisionamento

Você pode provisionar um único dispositivo ou vários dispositivos em escala, dependendo das necessidades de sua solução de IoT Edge. As opções disponíveis para autenticar comunicações entre seus dispositivos IoT Edge e seus hubs IoT dependem do método de provisionamento escolhido.

Provisione com uma cadeia de conexão, chave simétrica, certificado X.509, chave privada de certificado de identidade ou um certificado de identidade. O provisionamento DPS está incluído com várias opções. Escolha um método para o provisionamento. Substitua os valores de amostra pelos seus próprios.

Provisionamento manual com cadeia de conexão

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

Para obter mais informações sobre como recuperar informações de provisionamento, consulte Criar e provisionar um dispositivo IoT Edge no Linux usando chaves simétricas.

Provisionamento manual com chave simétrica

[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

Para obter mais informações sobre como recuperar informações de provisionamento, consulte Criar e provisionar um dispositivo IoT Edge no Linux usando chaves simétricas.

Provisionamento manual com certificado X.509

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

[provisioning.authentication]
method = "x509"

Para obter mais informações sobre o provisionamento usando certificados X.509, consulte Criar e provisionar um dispositivo IoT Edge no Linux usando certificados X.509.

Provisionamento DPS com chave simétrica

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

Para obter mais informações sobre o provisionamento DPS com a chave simétrica, consulte Criar e provisionar dispositivos IoT Edge em escala no Linux usando as chaves simétricas.

Provisionamento DPS com certificados 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

(Opcional) Habilitar a renovação automática do certificado de ID do dispositivo

A renovação automática requer um método de emissão de certificado conhecido. Definir o método como local_ca ou est.

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

Para obter mais informações sobre o provisionamento DPS com certificados X.509, consulte Criar e provisionar dispositivos IoT Edge em escala no Linux usando os certificados X.509.

Provisionamento DPS com TPM (Trusted Platform Module)

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

Caso use o provisionamento DPS com o TPM e exigir configuração personalizada, consulte a seção do TPM.

Para obter mais informações, consulte Criar e provisionar dispositivos do IoT Edge em escala com um TPM no Linux.

Tempo limite de nuvem e comportamento de repetição

As seguintes configurações controlam o tempo limite e as novas tentativas de operações de nuvem, como comunicação com o DPS (Serviço de Provisionamento de Dispositivos) durante o provisionamento ou o Hub IoT para criação de identidade de módulo.

O parâmetro cloud_timeout_sec é o prazo em segundos para uma solicitação de rede aos serviços de nuvem. Por exemplo, uma solicitação HTTP. Uma resposta do serviço de nuvem deve ser recebida antes dessa data limite ou a solicitação falha como um tempo limite.

O parâmetro cloud_retries controla quantas vezes uma solicitação pode ser repetida após a primeira tentativa falhar. O cliente sempre envia pelo menos uma vez, portanto, o valor é o número de repetições após a primeira tentativa falhar. Por exemplo, cloud_retries = 2 significa que o cliente faz um total de três tentativas.

cloud_timeout_sec = 10
cloud_retries = 1

Emissão de certificado

Se você configurou quaisquer certificados emitidos dinamicamente, escolha o método de emissão correspondente e substitua os valores de amostra pelos seus próprios.

Emissão de certificado por meio do EST

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

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

Certificado de ID do EST já no dispositivo

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

Certificado de ID do EST solicitado por meio do certificado de ID de inicialização do EST

Autenticação com um certificado de cliente do TLS que é usado uma vez para criar o certificado de ID do EST inicial. Após a primeira emissão de certificado, um identity_cert e identity_pk são criados e usados automaticamente para autenticação e renovações futuras. O CN (Nome Comum) da Entidade do certificado de ID do EST gerado é sempre o mesmo que a ID do dispositivo configurada na seção de provisionamento. Estes arquivos devem ser legíveis pelos usuários aziotcs e aziotks, respectivamente.

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"

Emissão de certificado por meio da AC local

[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 (Trusted Platform Module)

Caso precise de uma configuração especial para o TPM ao usar o provisionamento do TPM do DPS, use essas configurações do TPM.

Para obter cadeias de caracteres de carregador TCTI aceitáveis, consulte a seção 3.5 da Especificação da API da TCTI (Interface de Transmissão de Comando) do TCG TSS 2.0 TPM.

A configuração para uma cadeia de caracteres vazia faz com que a biblioteca de carregadores da TCTI tente carregar um conjunto predefinido de módulos da TCTI em ordem.

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

O índice de TPM mantém a chave de autenticação do DPS. O índice é usado como um deslocamento do endereço base para objetos persistentes, como 0x81000000 e deve estar no intervalo de 0x00_00_00 até 0x7F_FF_FF. O valor padrão é 0x00_01_00.

auth_key_index = "0x00_01_00"

Use valores de autorização para endosso e hierarquias de proprietário, se necessário. Por padrão, esses valores são cadeias de caracteres vazias.

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

PKCS#11

Caso usou qualquer URIs PKCS nº 11, use os parâmetros a seguir e substitua os valores pela configuração PKCS nº 11.

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

Agente de Edge Padrão

Quando o IoT Edge é iniciado pela primeira vez, ele inicializa um módulo padrão do Agente de Edge. Caso precise substituir os parâmetros fornecidos para o módulo padrão do Agente de Edge, use esta seção e substitua os valores pelos seus próprios.

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

Pontos de extremidade da API de carga de trabalho e gerenciamento do Daemon

Caso precise substituir os pontos de extremidade da API de gerenciamento e carga de trabalho, use esta seção e substitua os valores pelos seus próprios.

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

Watchdog do Agente do Edge

Caso precise substituir as configurações padrão de watchdog do Agente de Edge, use esta seção e substitua os valores pelos seus próprios.

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

Certificado de Autoridade de Certificação de borda

Caso tenha seu próprio certificado de AC do Edge que emita todos os certificados do módulo, use uma dessas seções e substitua os valores pelos seus próprios.

Certificado de CA do Edge carregado de um arquivo

[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

Certificado de CA do Edge emitido através de EST

[edge_ca]
method = "est"

Para obter mais informações sobre como usar um servidor EST, confira Tutorial: configurar o servidor de registro de transporte seguro para o Azure IoT Edge.

Configuração opcional de EST para emissão do certificado de AC do Edge

Se não for definido, os padrões em [cert_issuance.est] serão usados.

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

username = "estuser"
password = "estpwd"

Certificado de ID do EST já no dispositivo

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

Certificado de ID do EST solicitado por meio do certificado de ID de inicialização do 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

Certificado de CA do Edge emitido de um certificado de AC local

Requer que [cert_issuance.local_ca] seja definido.

[edge_ca]
method = "local_ca"

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

Certificados de início rápido da AC do Edge

Caso não tenha seu próprio certificado de AC do Edge usado para emitir todos os certificados de módulo, use esta seção e defina o número de dias para o tempo de vida do certificado de AC do Edge autoassinado. O padrão de expiração é de 90 dias.

[edge_ca]
auto_generated_edge_ca_expiry_days = 90

Renovação automática do certificado de CA do Edge

Essa configuração gerencia a renovação automática do certificado de AC do Edge. A renovação automática aplica-se quando a AC do Edge é configurada como início rápido ou quando a AC do Edge tem um conjunto method de emissões. Os certificados de AC do Edge carregados de arquivos geralmente não podem ser renovados automaticamente, pois o runtime do Edge não tem informações suficientes para renová-los.

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

Coleta de lixo de imagens

Caso precise substituir a configuração de coleta de lixo de imagem padrão, use esta seção e substitua os valores nesta seção pelos seus próprios valores.

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

Runtime do Moby

Caso precise substituir a configuração de runtime padrão do Moby, use esta seção e substitua os valores por seus próprios.

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