Definir configurações de dispositivo IoT Edge
Este artigo mostra as configurações e opções para configurar o arquivo IoT Edge /etc/aziot/config.toml de um dispositivo IoT Edge. O IoT Edge usa o arquivo config.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, uma vez que se aplicam a cenários específicos.
Um modelo contendo todas as opções pode ser encontrado no arquivo config.toml.edge.template dentro do diretório /etc/aziot em um dispositivo IoT Edge. Você pode copiar o conteúdo de todo o modelo ou seções do modelo para seu arquivo config.toml . Descomente as seções que você precisa. Esteja ciente de não copiar parâmetros que você já definiu.
Se você alterar a configuração de um dispositivo, use sudo iotedge config apply para aplicar as alterações.
Parâmetros globais
Os parâmetros hostname, 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 quaisquer outras seções. Adicionar parâmetros antes de uma coleção de configurações garante que eles sejam aplicados corretamente. Para obter mais informações sobre sintaxe válida, consulte toml.io .
Hostname (Nome do anfitrião)
Para habilitar a descoberta de gateway, cada dispositivo de gateway de Borda IoT (pai) precisa especificar um parâmetro de nome de host que seus dispositivos filho usam para localizá-lo na rede local. O módulo edgeHub também usa o parâmetro hostname 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?.
Nota
Quando o valor do nome do host não está definido, o IoT Edge tenta localizá-lo automaticamente. No entanto, os clientes na rede podem não ser capazes de descobrir o dispositivo se ele não estiver definido.
Para hostname, substitua fqdn-device-name-or-ip-address pelo nome do dispositivo para substituir o nome de host padrão do dispositivo. O valor pode ser um nome de domínio totalmente qualificado (FQDN) ou um endereço IP. Use essa configuração como o nome de host do gateway em um dispositivo de gateway 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 IoT Edge downstream precisa especificar um parâmetro parent_hostname para identificar seu pai. Em um cenário hierárquico em que um único dispositivo IoT Edge é um dispositivo pai e um dispositivo filho, ele precisa de ambos os parâmetros.
Substitua fqdn-parent-device-name-or-ip-address pelo nome do dispositivo pai. Use um nome de host menor que 64 caracteres, que é o limite de caracteres para um nome comum de certificado de 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 autoridade de certificação (CA) personalizado como uma raiz de confiança para o IoT Edge e módulos, especifique uma configuração 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 CA raiz confiável.
Permissões elevadas do Docker
Alguns recursos do docker podem ser usados para obter acesso root. Por padrão, o --privileged sinalizador e todos os recursos listados no parâmetro CapAdd do docker HostConfig 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 auto_reprovisioning_mode opcional especifica as condições que decidem quando um dispositivo tenta reprovisionar automaticamente com o Serviço de Provisionamento de Dispositivo. 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 | Description |
|---|---|
| Dinâmica | Reprovisionamento quando o dispositivo detetar que pode ter sido movido de um Hub IoT para outro. Este modo é o padrão. |
| AlwaysOnStartup | Reprovisionamento quando o dispositivo é reinicializado ou uma falha faz com que os daemons sejam reiniciados. |
| OnErrorOnly | Nunca acione o reprovisionamento de dispositivos automaticamente. O reprovisionamento de dispositivo ocorre apenas como fallback, se o dispositivo não conseguir 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 Dynamic e AlwaysOnStartup. |
Por exemplo:
auto_reprovisioning_mode = "Dynamic"
Para obter mais informações sobre o reprovisionamento de dispositivos, consulte Conceitos de reprovisionamento de dispositivos do Hub IoT.
Aprovisionamento
Você pode provisionar um único dispositivo ou vários dispositivos em escala, dependendo das necessidades de sua solução 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.
Você pode provisionar 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 do DPS está incluído com várias opções. Escolha um método para seu provisionamento. Substitua os valores de amostra pelos seus.
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 provisionamento usando certificados X.509, consulte Criar e provisionar um dispositivo IoT Edge no Linux usando certificados X.509.
Provisionamento de 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 de DPS com chave simétrica, consulte Criar e provisionar dispositivos IoT Edge em escala no Linux usando chave simétrica.
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) Ativar a renovação automática do certificado de identificação do dispositivo
A renovação automática requer um método de emissão de certificado conhecido. Defina o método como um est ou local_ca.
Importante
Habilite a renovação automática somente se este dispositivo estiver configurado para registro DPS baseado em CA. O uso da renovação automática para um registro individual faz com que o dispositivo não possa ser reprovisionado.
[provisioning.attestation.identity_cert.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"
Para obter mais informações sobre o provisionamento de DPS com certificados X.509, consulte Criar e provisionar dispositivos IoT Edge em escala no Linux usando certificados X.509.
Provisionamento de 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"
Se você usar o provisionamento do DPS com o TPM e precisar de uma configuração personalizada, consulte a seção TPM .
Para obter mais informações, consulte Criar e provisionar dispositivos IoT Edge em escala com um TPM no Linux.
Tempo limite na nuvem e comportamento de repetição
Essas configurações controlam o tempo limite e as novas tentativas para operações na nuvem, como a comunicação com o Serviço de Provisionamento de Dispositivo (DPS) 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 para serviços em nuvem. Por exemplo, uma solicitação HTTP. Uma resposta do serviço de nuvem deve ser recebida antes desse prazo, 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 novas tentativas 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 certificados
Se você configurou qualquer certificado emitido dinamicamente, escolha o método de emissão correspondente e substitua os valores de amostra pelo seu.
Emissão de certificados via EST
[cert_issuance.est]
trusted_certs = ["file:///var/aziot/certs/est-id-ca.pem",]
[cert_issuance.est.auth]
username = "estuser"
password = "estpwd"
EST ID cert 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
EST ID cert solicitado via EST bootstrap ID cert
Autenticação com um certificado de cliente TLS que é usado uma vez para criar o certificado de ID EST inicial. Após a primeira emissão do certificado, um identity_cert e são automaticamente criados e usados para futuras autenticações e identity_pk renovações. O CN (Nome Comum da Entidade) do certificado de ID EST gerado é sempre o mesmo que o ID do dispositivo configurado na seção de provisionamento. Esses 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 certificados através da autoridade de certificação 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)
Se você precisar de uma configuração especial para o TPM ao usar o provisionamento TPM do DPS, use estas configurações do TPM.
Para obter cadeias de caracteres aceitáveis do carregador TCTI, consulte a seção 3.5 da Especificação da API TCG TSS 2.0 TPM Command Transmission Interface (TCTI).
A configuração como uma cadeia de caracteres vazia faz com que a biblioteca do carregador TCTI tente carregar um conjunto predefinido de módulos TCTI em ordem.
[tpm]
tcti = "swtpm:port=2321"
O índice TPM persiste a chave de autenticação DPS. O índice é tomado 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 predefinido é 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
Se você usou qualquer URI PKCS#11, use os seguintes parâmetros e substitua os valores pela configuração PKCS#11.
[aziot_keys]
pkcs11_lib_path = "/usr/lib/libmypkcs11.so"
pkcs11_base_slot = "pkcs11:slot-id=0?pin-value=1234"
Agente de Borda Padrão
Quando o IoT Edge é iniciado pela primeira vez, ele inicializa um módulo padrão do Agente de Borda. Se você precisar substituir os parâmetros fornecidos ao módulo padrão do Agente de Borda, use esta seção e substitua os valores pelos seus próprios.
Nota
O agent.config.createOptions parâmetro é especificado como uma tabela embutida TOML. Este formato parece JSON, mas não é JSON. Para obter mais informações, consulte 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 gerenciamento e carga de trabalho do Daemon
Se você precisar substituir os pontos de extremidade da API de gerenciamento e carga de trabalho, use esta seção e substitua os valores pelos seus.
[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"
Cão de guarda do Edge Agent
Se você precisar substituir as configurações padrão do cão de guarda do Agente de Borda, use esta seção e substitua os valores pelos seus.
[watchdog]
max_retries = "infinite" # the string "infinite" or a positive integer. Defaults to "infinite"
Certificado de AC do Edge
Se você tiver seu próprio certificado de CA de Borda que emite todos os certificados de módulo, use uma dessas seções e substitua os valores por seus próprios.
Certificado de autoridade de certificação de borda 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 de borda emitido sobre EST
[edge_ca]
method = "est"
Para obter mais informações sobre como usar um servidor EST, consulte Tutorial: Configurar o registro no Servidor de Transporte Seguro para o Azure IoT Edge.
Configuração EST opcional para emissão do certificado de CA de Borda
Se não estiver 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"
EST ID cert 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
EST ID cert solicitado via EST bootstrap ID cert
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 autoridade de certificação de borda emitido a partir de um certificado de autoridade de certificação 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 autoridade de certificação de borda
Se você não tiver seu próprio certificado de CA de Borda 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 CA de Borda auto-assinado gerado automaticamente. O padrão de expiração é de 90 dias.
Atenção
Essa configuração NÃO é recomendada para uso em produção. Configure seu próprio certificado de CA de Borda nas seções de certificado de CA de Borda.
[edge_ca]
auto_generated_edge_ca_expiry_days = 90
Renovação automática do certificado de CA de borda
Essa configuração gerencia a renovação automática do certificado da autoridade de certificação de borda. A renovação automática aplica-se quando a AC de Borda é configurada como início rápido ou quando a AC de Borda tem um conjunto de method emissão. Os certificados de CA de Borda carregados de arquivos geralmente não podem ser renovados automaticamente, pois o tempo de execução da Borda não tem informações suficientes para renová-los.
Importante
A renovação de uma autoridade de certificação de borda exige que todos os certificados de servidor emitidos por essa autoridade de certificação sejam regenerados. Esta regeneração é feita reiniciando todos os módulos. O tempo de renovação da AC de Borda não pode ser garantido. Se reinicializações aleatórias de módulos forem inaceitáveis para o seu caso de uso, desative a autorenewal.
[edge_ca.auto_renew]
rotate_key = true
threshold = "80%"
retry = "4%"
Recolha de lixo de imagem
Se você precisar substituir a configuração de coleta de lixo de imagem padrão, use esta seção e substitua os valores nesta seção por seus próprios.
| Parâmetro | Description |
|---|---|
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 era das imagens não utilizadas. As imagens mais antigas do que o limite são removidas |
cleanup_time |
Formato HH:MM de 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"
Tempo de execução do Moby
Se você precisar substituir a configuração padrão do tempo de execução do Moby, use esta seção e substitua os valores pelos seus próprios.
[moby_runtime]
uri = "unix:///var/run/docker.sock"
network = "azure-iot-edge"