Conectar Dispositivos
O IronFlock oferece várias maneiras de conectar dispositivos, dependendo do hardware e do sistema operacional. Não tem hardware à mão? Você pode simular um dispositivo no seu notebook em poucos minutos.
Pré-requisitos
Antes de conectar um dispositivo, certifique-se de ter:
- Um projeto criado no IronFlock
- Uma entrada de dispositivo criada dentro desse projeto (clique em NEW DEVICE no painel Settings -> Devices do projeto.)
- O arquivo de configuração do dispositivo (
.flock) baixado
Perdeu o arquivo
.flock? Você pode baixá-lo novamente a qualquer momento: abra o dispositivo na barra lateral do projeto, vá em Manutenção e clique em Baixar arquivo de configuração. É a mesma configuração, não um novo dispositivo. Você precisa do privilégio Manter no dispositivo. Veja Manutenção.
Dispositivo em uma rede corporativa restrita? Planeje a configuração de rede antes da instalação — ela é o motivo mais comum para um dispositivo recém-instalado continuar offline:
- Firewall ou proxy com reconhecimento de identidade: a regra que libera o dispositivo precisa estar vinculada ao próprio dispositivo, nunca a um usuário com sessão iniciada — caso contrário, o dispositivo sai da rede sempre que a sessão desse usuário expira. Veja Firewalls e Proxies com Reconhecimento de Identidade.
- Proxy HTTP corporativo: o agente e o Docker precisam ser informados sobre ele explicitamente — veja Atrás de um Proxy Corporativo → Dispositivos de Borda.
- Conexão a um Appliance local: o dispositivo precisa alcançar diretamente as portas de serviço do appliance — ou, quando o appliance usa HTTPS com o seu certificado corporativo, apenas a porta
443, com o dispositivo confiando na sua CA raiz corporativa. Veja Conectividade dos dispositivos no guia do Appliance.- Desvio do relógio: firewalls corporativos costumam bloquear os servidores de horário públicos que acompanham um sistema recém-instalado, e o relógio do dispositivo se desvia silenciosamente — configure o seu servidor NTP interno. Veja Sincronização de horário (NTP).
Firewalls e Proxies com Reconhecimento de Identidade
Cada dispositivo de borda executa o agente IronFlock como um serviço do sistema sem supervisão. Ele inicia com o boot, permanece conectado o tempo todo e continua instalando apps, baixando imagens e se atualizando — haja ou não alguém com sessão iniciada no dispositivo. Isso vale onde quer que a sua plataforma rode: na nuvem IronFlock, na sua nuvem privada ou em um appliance local.
Redes OT são cada vez mais protegidas por firewalls e proxies com reconhecimento de identidade (identity-aware), que concedem acesso pela identidade no diretório em vez de pelo endereço de rede. Se a regra que libera um dispositivo de borda estiver vinculada ao usuário que tem uma sessão iniciada nele, o dispositivo perde a rede sempre que a sessão desse usuário expira:
- As conexões já abertas continuam funcionando, então o dispositivo continua aparecendo como online.
- Cada conexão nova é descartada silenciosamente — instalações de apps, downloads de imagens, atualizações do agente e reconexões falham.
- Após o próximo reinício do agente ou do dispositivo, ele não consegue mais se reconectar e permanece offline até que alguém volte a iniciar sessão no dispositivo ou a regra seja alterada.
Peça à sua equipe de rede que vincule a regra ao dispositivo, nunca a uma pessoa:
| Dispositivo | Identidade a usar na regra |
|---|---|
| Dispositivo Windows associado ao seu domínio | A conta de computador do dispositivo — o objeto de computador, ou um grupo como IronFlock Edge Devices |
| Dispositivo Linux ou IronFlockOS, ou Windows fora do domínio | Um objeto de host nomeado com um endereço IP reservado, ou a identidade atribuída pelo seu controle de acesso à rede (802.1X ou autenticação por MAC) |
Como isso se traduz nos produtos mais comuns:
- Check Point Identity Awareness: na Access Role, selecione a máquina (objeto de computador ou grupo) em vez de usuários. As identidades de máquina são renovadas pela própria atividade do computador no domínio; se elas puderem expirar no seu gateway, use um objeto de rede em vez disso.
- Palo Alto Networks User-ID: contas de computador não geram mapeamentos de IP para usuário, então use um objeto de endereço, uma tag ou o Device-ID.
- Fortinet FSSO e firewalls semelhantes baseados em diretório: use um objeto de endereço para o dispositivo, ou o endereço dinâmico atribuído pelo seu controle de acesso à rede.
- Zscaler, Prisma Access e outros gateways de segurança em nuvem: registre a rede dos dispositivos como um local de IoT ou de servidor (uma origem confiável), para que o tráfego dos dispositivos seja identificado pelo local e não pelo usuário.
Isso não é uma isenção da sua política de identidade — apenas identifica o dispositivo pela identidade que ele realmente tem. Se você opera um appliance local, o mesmo vale para o host do appliance: veja Identidade de rede para hosts do IronFlock.
Como reconhecer a falha. Um dispositivo que continua online enquanto instalações de apps, downloads de imagens ou atualizações do agente falham por tempo esgotado — e os pings continuam funcionando — indica uma regra de identidade expirada, e não um problema no dispositivo. Não reinicie o agente nem o dispositivo até que uma conexão nova a partir do dispositivo volte a ter sucesso: a sessão que ainda está aberta é a única que funciona, e ela mantém o dispositivo gerenciável remotamente enquanto isso.
Teste Primeiro: Simule um Dispositivo no Seu Notebook
Você não precisa de hardware físico para explorar o IronFlock. O app FlockFlasher pode executar o agente IronFlock diretamente no seu notebook, fazendo com que ele se passe por um dispositivo real dentro do seu projeto — perfeito para testar apps e dashboards antes de partir para o hardware de verdade.
- Instale o Docker Desktop (ou o Docker Engine no Linux) e certifique-se de que ele está em execução.
- Baixe e instale o app FlockFlasher para o seu SO.
- Clique duas vezes no arquivo
.flockbaixado do seu dispositivo — ele abre no FlockFlasher e o dispositivo aparece na lista. (Alternativamente, abra o FlockFlasher e adicione o arquivo pelo botão +.) - Clique em Test Device (▶) (testar dispositivo) na entrada do dispositivo. O FlockFlasher baixa automaticamente o agente IronFlock no primeiro uso e o inicia com a configuração do seu dispositivo.
Seu notebook agora atua como esse dispositivo dentro do seu projeto IronFlock: ele aparece online, e você pode instalar e executar apps nele exatamente como em um dispositivo real. Os apps rodam como contêineres Docker no seu notebook.
Quando terminar, pare o teste no FlockFlasher. Mais tarde, você pode usar o mesmo arquivo .flock para provisionar o dispositivo real — apenas certifique-se de que somente uma máquina execute uma determinada configuração de dispositivo por vez.
Método 1: Gravar um Cartão SD
Ideal para Raspberry Pi e outros dispositivos ARM que inicializam a partir de cartões SD.
- Baixe o app FlockFlasher para o seu SO.
- Insira um cartão SD (16 GB no mínimo) no seu computador.
- Abra o FlockFlasher e clique no botão + para carregar o arquivo
.flock. - Selecione a unidade do cartão SD (o FlockFlasher detecta unidades externas automaticamente).
- Escolha a imagem correta para o seu dispositivo (Raspberry Pi 3/4, Zero, etc.).
- Opcionalmente, configure o WiFi para que o dispositivo possa se conectar no destino.
- Clique em Flash e aguarde a conclusão da gravação, validação e configuração.
- Insira o cartão SD no dispositivo e ligue-o.
O dispositivo deve ficar online em até 20 minutos.
Aviso: O processo de gravação apaga todos os dados da unidade selecionada. O FlockFlasher oculta as unidades internas por padrão, mas sempre verifique novamente a sua seleção.
Método 2: Instalador USB para PCs Industriais
Para dispositivos AMD64 com boot EFI (por exemplo, Siemens SIMATIC Box IPC).
- Insira um pen drive USB (16 GB no mínimo) e abra o FlockFlasher.
- Carregue o arquivo
.flocke selecione a unidade USB. - Selecione a imagem Industrial PC x86_64 (EFI).
- Clique em Flash e aguarde a conclusão.
- Se necessário, altere a ordem de boot na BIOS do dispositivo para inicializar a partir do USB.
- Insira o pen drive USB e ligue o dispositivo.
O dispositivo deve ficar online em até 60 minutos.
Gravar pela Linha de Comando
O IronFlock CLI prepara as unidades dos métodos 1 e 2 sem o app de desktop. Ele roda no Linux, no macOS e no Windows e grava o IronFlockOS para Raspberry Pi 4, 400, 5, CM4 e CM5, e para PCs e máquinas ARM com UEFI. Os passos abaixo são para Linux e macOS; no Windows, instale-o com o PowerShell e indique a unidade como o ironflock os drives a lista lá (Instalação, Gravar o IronFlockOS em uma unidade).
- Instale o comando
ironflockno seu computador:curl -fsSL https://instance-registry.ironflock.com/dl/cli/install.sh | sudo bash - Insira o cartão SD ou o pen drive USB e descubra o nome da unidade:
ironflock os drives - Grave o IronFlockOS e o arquivo
.flockna unidade. Substitua/dev/sdbpela sua unidade:Para um PC industrial, adicionesudo ironflock os flash -c mydevice.flock -d /dev/sdb--installer. O pen drive então instala o IronFlockOS no disco interno do PC que inicializa a partir dele:sudo ironflock os flash -c mydevice.flock -d /dev/sdb --installer
O comando baixa a imagem para o hardware indicado no arquivo .flock e a verifica. Ele mostra o que vai gravar e pergunta antes de apagar a unidade. Depois, grava a unidade e a relê. Para dar ao dispositivo uma rede WiFi diferente da que está no arquivo .flock, adicione --wifi-ssid e --wifi-password-file. Veja Gravar o IronFlockOS em uma unidade para todas as opções.
A máquina já roda Linux e você não consegue iniciá-la a partir de um pen drive? O
ironflock os installsubstitui o Linux em execução pelo IronFlockOS no mesmo disco, também em uma máquina remota via SSH. Tudo o que está nesse disco é perdido. Veja Substituir o Linux pelo IronFlockOS.
Método 3: Instalação Personalizada
Para dispositivos que mantêm seu sistema operacional Linux existente. Ideal para NVIDIA Jetson e hardware personalizado.
Nota: Este método de instalação manual é destinado a hardware de produção real, como PCs industriais, gateways e dispositivos embarcados — não a notebooks. Se você só quer experimentar o IronFlock no seu notebook, siga Teste Primeiro: Simule um Dispositivo no Seu Notebook — nenhuma instalação manual do agente é necessária.
Dispositivos Linux / Unix
- Conecte-se ao dispositivo via SSH.
- Copie o arquivo
.flockdo seu computador para o dispositivo:scp mydevice.flock user@device-ip:/home/user/ - Baixe e execute o instalador:
curl -fsSL https://instance-registry.ironflock.com/dl/cli/install.sh | sudo bash -s -- agent install -c mydevice.flockEm um appliance IronFlock? Os comandos são os mesmos. O
ironflock agent installobtém o agente do dispositivo do espelho de downloads do appliance que o arquivo.flockindica, e da internet o que o espelho não tem. O script de instalação, oironflock, os pacotes da distribuição e o Docker continuam vindo da internet, então o dispositivo precisa de acesso à internet durante a instalação. Depois disso, só precisa alcançar o appliance (veja Dispositivos de borda). - Responda às perguntas do instalador. Quando ele termina, o agente está em execução e o dispositivo aparece online no IronFlock em até um minuto. Não é preciso reiniciar.
O dispositivo precisa rodar um Linux baseado em Debian ou Ubuntu com systemd.
O install.sh baixa o ironflock, a ferramenta de linha de comando da IronFlock, para a CPU do dispositivo. Ele verifica a assinatura do download com a chave da IronFlock embutida no script, instala a ferramenta como /usr/local/bin/ironflock e a executa com os argumentos que você passar. Sem argumentos, ele apenas instala a ferramenta; conecte o dispositivo depois com sudo ironflock agent install -c mydevice.flock.
O ironflock agent install primeiro verifica se a instalação pode ser concluída. Depois, instala o Docker (se ele estiver faltando) e o agente do dispositivo e configura:
- um usuário SSH para o proprietário do projeto — login somente por chave (a chave do dispositivo) e
sudosem senha; - o WiFi a partir do arquivo
.flock, via NetworkManager; - um banner de login.
Ele diz o que vai instalar e pergunta antes de agir. Ele não mexe nas atualizações de segurança automáticas e não reinicia o dispositivo, a menos que você passe --reboot. Tudo o que ele altera é registrado em /opt/ironflock/device-init/installed.json, de modo que o agent remove desfaz exatamente isso:
sudo ironflock agent removeOutras opções do ironflock agent install:
--yes— usar os padrões, sem perguntas--disable-suspend— impede que o dispositivo entre em suspensão--reboot— reinicia o dispositivo ao fim da instalação--http-proxy,--https-proxy,--no-proxy,--proxy-password-file— passam a instalação, o Docker e o agente por um proxy--download-base— baixa de outro servidor (veja Base de download)
Para dar outro arquivo .flock a um dispositivo instalado, execute sudo ironflock agent configure -c new.flock. Comandos do agente do dispositivo descreve todos os comandos e opções.
No dispositivo, o agente fica em /opt/ironflock/device-agent e é executado como o serviço systemd ironflock-device-agent. Verifique-o com sudo ironflock status ou systemctl status ironflock-device-agent. Leia o log dele com sudo ironflock agent logs; ele também está em journalctl -u ironflock-device-agent e em /var/log/ironflock/device-agent.log. A configuração é /opt/ironflock/device-agent/device-config.flock (legível apenas pelo root — não há mais cópia em /boot), o Docker guarda seus dados em /opt/ironflock/device-agent/docker-apps e os dados dos apps continuam em /apps.
O agente se atualiza sozinho — não há um gerenciador de atualizações separado. As atualizações são assinadas e verificadas, e uma atualização que falha é revertida automaticamente. Elas só são aplicadas quando o agente inicia, quando um usuário inicia a atualização no Studio ou quando você executa sudo ironflock agent update no dispositivo.
Dispositivos instalados antes de outubro de 2026 usavam
/opt/reagente o serviçoreagent.service. Assim que um desses dispositivos executa o agente 1.3.x, ele passa sozinho para o layout descrito acima — o Docker e os apps reiniciam uma vez — e/opt/reagentpermanece como um link.
Atrás de um proxy corporativo? Informe o proxy também no download do instalador e adicione
--http-proxy/--https-proxyaos argumentos do passo 3 para que oironflock agent installconfigure o Docker e o agente para você. Veja Atrás de um Proxy Corporativo para o comando completo e as etapas da CA corporativa.
Instalar a partir do seu computador via SSH
Com o ironflock instalado no seu próprio computador Linux ou macOS, você conecta um dispositivo sem fazer login nele antes. O --host executa o comando no dispositivo via SSH e leva o arquivo .flock junto, então não há nada para copiar:
ironflock --host user@device-ip agent install -c mydevice.flockO usuário de login precisa ser root ou ter permissão para usar sudo no dispositivo. O --host usa o ssh do seu computador, com as suas chaves e o seu ~/.ssh/config. Ele não deixa nenhum comando ironflock no dispositivo; os comandos seguintes rodam do seu computador da mesma forma, por exemplo ironflock --host user@device-ip status. Veja Máquinas remotas via SSH.
Opcional: verifique o instalador antes
Para inspecionar o script antes de ele ser executado como root, baixe-o junto com a assinatura e verifique-o com a chave bootstrap da IronFlock:
curl -fsSLO https://instance-registry.ironflock.com/dl/cli/install.sh
curl -fsSLO https://instance-registry.ironflock.com/dl/cli/install.sh.asc
curl -fsSL https://instance-registry.ironflock.com/dl/cli/ironflock-bootstrap.asc | gpg --import
gpg --verify install.sh.asc install.shO gpg deve informar uma assinatura válida de IronFlock Bootstrap <[email protected]> com a impressão digital F6C9 4D96 CE31 5377 ACA7 C8EA 4990 5433 7321 2788. Depois, execute o script verificado:
sudo bash install.sh agent install -c mydevice.flockDispositivos Windows
-
Instale o Docker Desktop no dispositivo e ative Start Docker Desktop when you sign in nas configurações do Docker Desktop. Para dispositivos sem supervisão, configure também o início de sessão automático do Windows para que o Docker fique disponível após uma reinicialização sem ninguém iniciar sessão.
-
Baixe o device-agent.exe no dispositivo. O navegador salva o arquivo na pasta Downloads.
-
Copie o arquivo
.flockpara o dispositivo e coloque-o na mesma pasta Downloads. -
Abra o PowerShell com direitos de administrador: abra o menu Iniciar, digite
PowerShell, selecione Executar como administrador e confirme o aviso do Controle de Conta de Usuário com Sim. O título da janela deve começar com Administrador:. Em uma janela normal do PowerShell, a instalação é interrompida com a mensagem this command must be run from an elevated (Administrator) prompt. -
Um PowerShell de administrador abre em
C:\Windows\System32. Vá para a sua pasta Downloads e confirme que os dois arquivos estão lá:cd $env:USERPROFILE\Downloads dir device-agent.exe, *.flock -
Instale e inicie o agente como um serviço do Windows:
.\device-agent.exe service install -config .\myaccount_myproject_mydevice.flockSubstitua
myaccount_myproject_mydevice.flockpelo nome do seu arquivo — o Studio o nomeia a partir do proprietário do projeto, do projeto e do dispositivo. Digite as primeiras letras do nome e pressione Tab para completá-lo. Não omita o.\antes dedevice-agent.exe: sem ele, o PowerShell não executa um programa da pasta atual.O serviço
ironflock-device-agentinicia imediatamente e depois a cada arranque do sistema, reinicia automaticamente em caso de falha e mantém o agente atualizado. Adicione-noStartpara instalá-lo sem iniciá-lo. O instalador copia odevice-agent.exee o arquivo.flockpara a pasta do agente, então depois você pode excluir os dois da sua pasta Downloads.
No dispositivo, o agente fica em %ProgramData%\IronFlock\DeviceAgent: device-agent.exe, a configuração device.flock, o log device-agent.log e os dados dos apps em apps\. As atualizações são assinadas e verificadas, e uma atualização que falha é revertida automaticamente; elas só são aplicadas quando o agente inicia ou quando um usuário inicia a atualização no Studio.
Verificar o agente e ler o log
A pasta do agente só pode ser lida por administradores, então execute estes comandos também em um PowerShell de administrador. Veja se o serviço está em execução:
Get-Service ironflock-device-agentStatus deve ser Running. Mostre as últimas 100 linhas do log do agente e continue exibindo as novas linhas à medida que o agente as grava:
Get-Content "$env:ProgramData\IronFlock\DeviceAgent\device-agent.log" -Tail 100 -WaitPressione Ctrl+C para parar de acompanhar o log. Para procurar apenas erros no log:
Select-String -Path "$env:ProgramData\IronFlock\DeviceAgent\device-agent.log" -Pattern "error" | Select-Object -Last 20Para reiniciar o agente, use os próprios comandos dele. O dispositivo fica offline até o agente voltar a rodar:
& "$env:ProgramData\IronFlock\DeviceAgent\device-agent.exe" service stop
& "$env:ProgramData\IronFlock\DeviceAgent\device-agent.exe" service startNão use Restart-Service para o agente. O agente pode levar até 15 segundos para parar, e o Restart-Service pode desistir antes disso e deixar o serviço parado.
Dispositivos Windows instalados antes do agente 1.4.0 usavam
%ProgramData%\IronFlock\Reagente o serviçoreagent. O agente 1.4.0 move um dispositivo assim para a estrutura acima: o agente e seus apps reiniciam uma vez.
Atrás de um proxy corporativo? Adicione
-proxy http://proxy.example.com:3128ao comandoservice installe configure o proxy do Docker Desktop em Settings → Resources → Proxies. Consulte Atrás de um Proxy Corporativo para detalhes e os passos da CA corporativa.
Dispositivo Windows associado ao seu domínio? O serviço do agente é executado como LocalSystem, haja ou não alguém com sessão iniciada, então uma regra de firewall vinculada ao usuário que iniciou a sessão não o cobre. Peça que a regra seja vinculada à conta de computador do dispositivo — veja Firewalls e Proxies com Reconhecimento de Identidade.
Sincronização de horário (NTP)
O agente do dispositivo precisa de um relógio exato. O handshake TLS com a plataforma, os tokens que autorizam o download de imagens e o carimbo de tempo de cada ponto de dado publicado pelo dispositivo dependem dele. Um dispositivo cujo relógio esteja mais de 15 minutos fora de sincronia também é recusado pelo armazenamento de arquivos com CLOCK_SKEW.
Em uma rede corporativa isso é um passo de configuração, não algo garantido: o NTP de saída na porta UDP 123 costuma estar bloqueado, então os servidores de horário públicos que acompanham o sistema operacional ficam inalcançáveis e o relógio se desvia sem nenhum erro visível. Peça ao seu departamento de TI o servidor de horário interno e configure-o no dispositivo, ou peça que liberem o UDP 123 de saída para a rede dos dispositivos.
Linux
Com systemd-timesyncd (padrão no Debian e no Ubuntu):
sudo mkdir -p /etc/systemd/timesyncd.conf.d
sudo tee /etc/systemd/timesyncd.conf.d/corporate.conf > /dev/null <<'EOF'
[Time]
NTP=ntp.your-company.com
EOF
sudo systemctl restart systemd-timesyncd
timedatectl statusCom chrony:
echo "server ntp.your-company.com iburst" | sudo tee -a /etc/chrony/chrony.conf
sudo systemctl restart chrony
chronyc sourcestimedatectl status deve informar System clock synchronized: yes.
Windows
Em um prompt elevado (Administrador):
w32tm /config /manualpeerlist:"ntp.your-company.com" /syncfromflags:manual /update
w32tm /resync
w32tm /query /statusDispositivos gravados com uma imagem IronFlock pronta (métodos 1 e 2) sincronizam por padrão com servidores de horário públicos. Em uma rede que os bloqueia, libere o UDP
123de saída para a sub-rede dos dispositivos, ou configure o servidor de horário interno por SSH após o primeiro boot, exatamente como mostrado acima para Linux.
Verificando a Conexão
Depois de conectar, verifique o status do dispositivo no seu projeto:
- Indicador verde — O dispositivo está online e se comunicando com o IronFlock.
- Indicador vermelho — O dispositivo está offline. Verifique a conexão de rede e certifique-se de que o agente está em execução.
- Verde, mas instalações de apps, downloads de imagens ou atualizações do agente atingem o tempo limite — uma regra de firewall pode ter deixado de liberar novas conexões do dispositivo. Leia Firewalls e Proxies com Reconhecimento de Identidade antes de reiniciar qualquer coisa.
A visualização em mapa de dispositivos mostra a localização geográfica de todos os dispositivos do projeto.