Definir configurações de dispositivo do IoT Edge
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?.
Observação
Quando o valor do nome do host não é definido, o IoT Edge tenta encontrá-lo automaticamente. No entanto, os clientes na rede podem não conseguir descobrir o dispositivo se ele não estiver definido.
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:
| Modo | Descrição |
|---|---|
| Dinâmico | Reprovisionar quando o dispositivo detectar que ele pode ter sido movido de um Hub IoT para outro. Este modo é o padrão. |
| AlwaysOnStartup | Reprovisionar quando o dispositivo é reinicializado ou uma falha faz com que os daemons sejam reiniciados. |
| OnErrorOnly | Nunca dispare o reprovisionamento de dispositivo automaticamente. O reprovisionamento do dispositivo ocorre apenas como fallback, se o dispositivo não puder se conectar ao Hub IoT durante o provisionamento de identidade devido a erros de conectividade. Esse comportamento de fallback também está implícito nos modos Dinâmico e AlwaysOnStartup. |
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.
Importante
Habilite a renovação automática somente se esse dispositivo estiver configurado para registro de DPS baseado em AC. O uso de renovação automática para um registro individual faz com que o dispositivo não consiga reprovisionar.
[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.
Observação
O parâmetro agent.config.createOptions é especificado como uma tabela embutida do TOML. Esse formato se parece com JSON, mas não é JSON. Para obter mais informações, consulte a Tabela Embutida da documentação do 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"
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.
Cuidado
Esta configuração NÃO é recomendada para uso de produção. Configure seu próprio certificado de AC do Edge nas seções de certificado de AC do Edge.
[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.
Importante
A renovação de uma AC do Edge requer que todos os certificados de servidor emitidos por esta AC sejam regenerados. Essa regeneração é feita reiniciando todos os módulos. O tempo de renovação da AC do Edge não pode ser garantido. Se as reinicializações aleatórias do módulo forem inaceitáveis para seu caso de uso, desabilite a renovação automática.
[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.
| Parâmetro | Descrição |
|---|---|
enabled |
Executa a coleta de lixo de imagem |
cleanup_recurrence |
Com que frequência você deseja que a coleta de lixo de imagem seja executada |
image_age_cleanup_threshold |
A duração das imagens não utilizados. Imagens mais antigas que o limite, são removidas |
cleanup_time |
Formato HH:MM 24 horas. Quando o trabalho de limpeza é executado |
[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"