Criar e provisionar um dispositivo IoT Edge no Linux usando certificados X.509

Aplica-se a: IoT Edge 1.1

Este artigo fornece instruções completas para registrar e provisionar um dispositivo Linux IoT Edge, incluindo a instalação do IoT Edge.

Cada dispositivo que se conecta a um hub IoT tem um ID de dispositivo que é usado para rastrear comunicações de nuvem para dispositivo ou de dispositivo para nuvem. Você configura um dispositivo com suas informações de conexão, que incluem o nome do host do hub IoT, o ID do dispositivo e as informações que o dispositivo usa para autenticar no Hub IoT.

As etapas neste artigo percorrem um processo chamado provisionamento manual, em que você conecta um único dispositivo ao seu hub IoT. Para provisionamento manual, você tem duas opções para autenticar dispositivos IoT Edge:

• Chaves simétricas: quando você cria uma nova identidade de dispositivo no Hub IoT, o serviço cria duas chaves. Você coloca uma das chaves no dispositivo e ela apresenta a chave para o Hub IoT ao autenticar.

  Este método de autenticação é mais rápido para começar, mas não tão seguro.

• X.509 autoassinado: você cria dois certificados de identidade X.509 e os coloca no dispositivo. Ao criar uma nova identidade de dispositivo no Hub IoT, você fornece impressões digitais de ambos os certificados. Quando o dispositivo se autentica no Hub IoT, ele apresenta um certificado e o Hub IoT verifica se o certificado corresponde à sua impressão digital.

  Esse método de autenticação é mais seguro e recomendado para cenários de produção.

Este artigo aborda o uso de certificados X.509 como método de autenticação. Se você quiser usar chaves simétricas, consulte Criar e provisionar um dispositivo IoT Edge no Linux usando chaves simétricas.

Pré-requisitos

Este artigo aborda o registro do dispositivo IoT Edge e a instalação do IoT Edge nele. Essas tarefas têm diferentes pré-requisitos e utilitários usados para realizá-las. Certifique-se de ter todos os pré-requisitos cobertos antes de prosseguir.

Ferramentas de gestão de dispositivos

Você pode usar o portal do Azure, o Visual Studio Code ou a CLI do Azure para as etapas de registro do dispositivo. Cada utilidade tem os seus próprios pré-requisitos.

Requisitos do dispositivo

Um dispositivo Linux X64, ARM32 ou ARM64.

A Microsoft publica pacotes de instalação para uma variedade de sistemas operacionais.

Para obter as informações mais recentes sobre quais sistemas operacionais são suportados atualmente para cenários de produção, consulte Sistemas com suporte do Azure IoT Edge.

Gerar certificados de identidade de dispositivo

O provisionamento manual com certificados X.509 requer o IoT Edge versão 1.0.10 ou mais recente.

Ao provisionar um dispositivo IoT Edge com certificados X.509, você usa o que é chamado de certificado de identidade de dispositivo . Esse certificado é usado apenas para provisionar um dispositivo IoT Edge e autenticar o dispositivo com o Hub IoT do Azure. É um certificado de folha que não assina outros certificados. O certificado de identidade do dispositivo é separado dos certificados da autoridade de certificação (CA) que o dispositivo IoT Edge apresenta aos módulos ou dispositivos downstream para verificação.

Para autenticação de certificado X.509, as informações de autenticação de cada dispositivo são fornecidas na forma de impressões digitais retiradas dos certificados de identidade do dispositivo. Essas impressões digitais são fornecidas ao Hub IoT no momento do registro do dispositivo para que o serviço possa reconhecer o dispositivo quando ele se conecta.

Para obter mais informações sobre como os certificados de CA são usados em dispositivos IoT Edge, consulte Entender como o Azure IoT Edge usa certificados.

Você precisa dos seguintes arquivos para provisionamento manual com X.509:

• Dois dos certificados de identidade do dispositivo com seus certificados de chave privada correspondentes nos formatos .cer ou .pem.

  Um conjunto de ficheiros de certificados/chave é fornecido ao runtime do IoT Edge. Ao criar certificados de identidade de dispositivo, defina o nome comum (CN) do certificado com a ID do dispositivo que você deseja que o dispositivo tenha em seu hub IoT.

• Impressões digitais retiradas dos certificados de identidade de ambos os dispositivos.

  Os valores de impressão digital são caracteres hexadecimais de 40 hex para hashes SHA-1 ou caracteres de 64 hex para hashes SHA-256. Ambas as impressões digitais são fornecidas ao Hub IoT no momento do registro do dispositivo.

Se você não tiver certificados disponíveis, poderá Criar certificados de demonstração para testar os recursos do dispositivo IoT Edge. Siga as instruções nesse artigo para configurar scripts de criação de certificados, criar um certificado de autoridade de certificação raiz e, em seguida, criar dois certificados de identidade de dispositivo IoT Edge.

Uma maneira de recuperar a impressão digital de um certificado é com o seguinte comando openssl:

openssl x509 -in <certificate filename>.pem -text -fingerprint

Registar o seu dispositivo

Você pode usar o portal do Azure, o Visual Studio Code ou a CLI do Azure para registrar seu dispositivo, dependendo de sua preferência.

az iot hub device-identity create --device-id device_id_here --hub-name hub_name_here --edge-enabled --auth-method x509_thumbprint --primary-thumbprint primary_SHA_thumbprint_here --secondary-thumbprint secdonary_SHA_thumbprint_here

Agora que você tem um dispositivo registrado no Hub IoT, recupere as informações usadas para concluir a instalação e o provisionamento do tempo de execução do IoT Edge.

Exibir dispositivos registrados e recuperar informações de provisionamento

Os dispositivos que usam autenticação de certificado X.509 precisam do nome do hub IoT, do nome do dispositivo e dos arquivos de certificado para concluir a instalação e o provisionamento do tempo de execução do IoT Edge.

az iot hub device-identity list --hub-name hub_name_here

Instalar o IoT Edge

Nesta seção, você prepara sua VM Linux ou dispositivo físico para o IoT Edge. Em seguida, instale o IoT Edge.

Execute os seguintes comandos para adicionar o repositório de pacotes e, em seguida, adicione a chave de assinatura do pacote Microsoft à sua lista de chaves confiáveis.

Instalar um motor de contentor

O Azure IoT Edge depende de um tempo de execução de contêiner compatível com OCI. Para cenários de produção, recomendamos que você use o mecanismo Moby. O mecanismo Moby é o único mecanismo de contêiner oficialmente suportado com o IoT Edge. As imagens de contêiner do Docker CE/EE são compatíveis com o tempo de execução do Moby.

sudo apt-get update; \
  sudo apt-get install moby-engine

sudo apt-get update; \
  sudo apt-get install moby-engine

sudo yum install moby-engine moby-cli

Depois que o mecanismo Moby for instalado com êxito, configure-o para usar local driver de registro como o mecanismo de registro. Para saber mais sobre a configuração de registos, consulte Lista de Verificação de Implantação de Produção.

• Crie ou abra o arquivo de configuração do daemon do Docker em /etc/docker/daemon.json.

• Defina o driver de log padrão para o driver de log local, conforme mostrado no exemplo abaixo.

     {
        "log-driver": "local"
     }
  

• Reinicie o motor do contentor para que as alterações tenham efeito.

  sudo systemctl restart docker
  

  Sugestão

  Se você receber erros ao instalar o mecanismo de contêiner Moby, verifique se o kernel Linux é compatível com Moby. Alguns fabricantes de equipamentos incorporados fornecem imagens de dispositivos que contêm kernels Linux personalizados sem as funcionalidades necessárias para a compatibilidade do motor de contentores. Execute o seguinte comando, que usa o script check-config fornecido pelo Moby, para verificar a configuração do kernel:

  curl -ssl https://raw.githubusercontent.com/moby/moby/master/contrib/check-config.sh -o check-config.sh
  chmod +x check-config.sh
  ./check-config.sh
  

  Na saída do script, verifique se todos os itens em Generally Necessary e Network Drivers estão habilitados. Se você estiver faltando recursos, habilite-os reconstruindo seu kernel a partir do código-fonte e selecionando os módulos associados para inclusão no .config do kernel apropriado. Da mesma forma, se você estiver usando um gerador de configuração do kernel como defconfig ou menuconfig, encontre e habilite os respetivos recursos e reconstrua seu kernel de acordo. Depois de implantar seu kernel recém-modificado, execute o script check-config novamente para verificar se todos os recursos necessários foram habilitados com êxito.

Instalar o runtime do IoT Edge

O daemon de segurança do IoT Edge fornece e mantém padrões de segurança no dispositivo IoT Edge. O serviço é iniciado em cada arranque e prepara o dispositivo iniciando o restante do ambiente de execução do IoT Edge.

As etapas nesta seção representam o processo típico para instalar a versão mais recente em um dispositivo que tenha conexão com a Internet. Se você precisar instalar uma versão específica, como uma versão de pré-lançamento, ou precisar instalar offline, siga as etapas de instalação Offline ou versão específica mais adiante neste artigo.

Instale a versão 1.1.* do IoT Edge junto com o pacote libiothsm-std.

sudo apt-get update; \
  sudo apt-get install iotedge

sudo apt-get update; \
  sudo apt-get install iotedge

Provisionar o dispositivo com sua identidade na nuvem

Agora que o mecanismo de contêiner e o tempo de execução do IoT Edge estão instalados em seu dispositivo, você está pronto para a próxima etapa, que é configurar o dispositivo com sua identidade na nuvem e informações de autenticação.

No dispositivo IoT Edge, abra o arquivo de configuração.

sudo nano /etc/iotedge/config.yaml

Localize a seção de configurações de provisionamento do arquivo e remova o comentário da seção Configuração de provisionamento manual usando um certificado de identidade X.509. Certifique-se de que todas as outras seções de provisionamento sejam comentadas. Verifique se a linha de provisionamento : não tem espaço em branco anterior e que os itens aninhados estão recuados por dois espaços.

# Manual provisioning configuration using an x.509 identity certificate
provisioning:
  source: "manual"
  authentication:
    method: "x509"
    iothub_hostname: "REQUIRED_IOTHUB_HOSTNAME"
    device_id: "REQUIRED_DEVICE_ID_PROVISIONED_IN_IOTHUB"
    identity_cert: "REQUIRED_URI_TO_DEVICE_IDENTITY_CERTIFICATE"
    identity_pk: "REQUIRED_URI_TO_DEVICE_IDENTITY_PRIVATE_KEY"

Atualize os seguintes campos:

• iothub_hostname: Nome do host do hub IoT ao qual o dispositivo se conectará. Por exemplo, {IoT hub name}.azure-devices.net.
• device_id: O ID que forneceu quando registou o dispositivo.
• identity_cert: URI para um certificado de identidade no dispositivo. Por exemplo, file:///path/identity_certificate.pem.
• identity_pk: URI para o arquivo de chave privada para o certificado de identidade fornecido. Por exemplo, file:///path/identity_key.pem.

Salve e feche o arquivo.

CTRL + X, Y, Enter

Depois de inserir as informações de provisionamento no arquivo de configuração, reinicie o daemon:

sudo systemctl restart iotedge

Verificar a configuração bem-sucedida

Verifique se o runtime foi instalado e configurado com êxito no seu dispositivo IoT Edge.

Verifique se o serviço do sistema IoT Edge está em execução.

sudo systemctl status iotedge

Se você precisar solucionar problemas do serviço, recupere os logs de serviço.

journalctl -u iotedge

Use a check ferramenta para verificar o estado da configuração e da conexão do dispositivo.

sudo iotedge check

Veja todos os módulos em execução no seu dispositivo IoT Edge. Quando o serviço for iniciado pela primeira vez, você verá apenas o módulo edgeAgent em execução. O módulo edgeAgent é executado por padrão e ajuda a instalar e iniciar quaisquer módulos adicionais que você implantar em seu dispositivo.

sudo iotedge list

Quando você cria um novo dispositivo IoT Edge, ele exibirá o código 417 -- The device's deployment configuration is not set de status no portal do Azure. Esse status é normal e significa que o dispositivo está pronto para receber uma implantação de módulo.

Instalação offline ou de versão específica (opcional)

As etapas nesta seção são para cenários não cobertos pelas etapas de instalação padrão. Isto pode incluir:

• Instalar o IoT Edge enquanto estiver offline
• Instalar uma versão candidata a lançamento

Use as etapas nesta seção se quiser instalar uma versão específica do tempo de execução do Azure IoT Edge que não esteja disponível por meio do gerenciador de pacotes. A lista de pacotes da Microsoft contém apenas um conjunto limitado de versões recentes e suas subversões, portanto, essas etapas são para quem deseja instalar uma versão mais antiga ou uma versão candidata a lançamento.

Usando comandos curl, você pode direcionar os arquivos de componentes diretamente do repositório GitHub do IoT Edge.

1. Navegue até às versões do Azure IoT Edge e localize a versão de lançamento que pretende.

2. Expanda a seção Ativos dessa versão.

3. Cada versão deve ter novos arquivos para o daemon de segurança do IoT Edge e o hsmlib. Se você vai instalar o IoT Edge em um dispositivo offline, baixe esses arquivos com antecedência. Caso contrário, use os seguintes comandos para atualizar esses componentes.

   1. Encontre o arquivo de libiothsm-std que corresponda à arquitetura do seu dispositivo IoT Edge. Clique com o botão direito do mouse no link do arquivo e copie o endereço do link.

   2. Use o link copiado no comando a seguir para instalar essa versão do hsmlib:

      curl -L libiothsm-std_link_here -o libiothsm-std.deb && sudo apt-get install ./libiothsm-std.deb
      

   3. Encontre o arquivo iotedge que corresponda à arquitetura do seu dispositivo IoT Edge. Clique com o botão direito do mouse no link do arquivo e copie o endereço do link.

   4. Use o link copiado no comando a seguir para instalar essa versão do daemon de segurança do IoT Edge.

      curl -L iotedge_link_here -o iotedge.deb && sudo apt-get install ./iotedge.deb
      

Agora que o mecanismo de contêiner e o tempo de execução do IoT Edge estão instalados em seu dispositivo, você está pronto para a próxima etapa, que é Provisionar o dispositivo com sua identidade de nuvem.

Desinstalar o IoT Edge

Se quiser remover a instalação do IoT Edge do seu dispositivo, use os seguintes comandos.

Remova o runtime do IoT Edge.

sudo apt-get autoremove iotedge

Quando o tempo de execução do IoT Edge é removido, todos os contêineres criados por ele são interrompidos, mas ainda existem no seu dispositivo. Veja todos os contêineres para ver quais permanecem.

sudo docker ps -a

Exclua os contentores do seu dispositivo, incluindo os dois contentores de runtime.

sudo docker rm -f <container name>

Finalmente, remova o tempo de execução do contêiner do seu dispositivo.

sudo apt-get autoremove --purge moby-engine

Próximos passos

Continue a implantar módulos do IoT Edge para saber como implantar módulos no seu dispositivo.