Atrás de um Proxy Corporativo

Muitas redes de fábrica e corporativas só alcançam a internet através de um proxy HTTP corporativo (por exemplo, um proxy Squid na porta 3128). O IronFlock Appliance instala e roda sem problemas nesse cenário — você informa o seu proxy no comando de instalação, e o ironflock appliance install configura todo o resto para você.

Esta página assume que o host do appliance não tem variáveis de ambiente de proxy definidas — você fornece o proxy explicitamente. Ela explica o que a instalação trata automaticamente e o passo extra necessário para proxies que interceptam TLS.

Este é o complemento sobre proxy da seção Configuração de firewall do guia do Appliance. Os mesmos endpoints do IronFlock precisam estar acessíveis — a diferença é que aqui eles são alcançados através do seu proxy.

Por que um proxy exige atenção

As imagens da plataforma IronFlock são baixadas pelo daemon do Docker — um serviço em segundo plano com sua própria configuração de rede, separada do seu shell. Mesmo em um host que de outra forma consegue alcançar a internet através do proxy, o daemon não sabe disso a menos que seja informado explicitamente. Sem configuração, ele tenta se conectar diretamente, a rede bloqueia, e a instalação para na etapa de login com um timeout:

Error response from daemon: Get "https://instance-registry.ironflock.com/v2/":
net/http: request canceled while waiting for connection (Client.Timeout exceeded)

O que a instalação trata para você

Quando você informa um proxy no comando de instalação, o ironflock appliance install configura o daemon do Docker e o agente do dispositivo do host para você — ele guarda as configurações de proxy em /etc/ironflock/proxy.env, que só o root pode ler, aponta o Docker e o agente para esse arquivo e reinicia o Docker para que ele consiga alcançar o registro do IronFlock. Esse passo é:

• Sem intervenção — você informa o proxy uma vez (veja abaixo); a instalação grava a configuração e reinicia o Docker para você, sem configuração manual do daemon.
• Totalmente ignorado quando nenhum proxy é informado — instalações com internet direta não são afetadas.

A instalação também roteia a própria conexão do appliance com a nuvem através do proxy — a validação de licença e o uplink de gerenciamento remoto que permite alcançar a sua instância a partir de ironflock.com. Ele registra o seu proxy no arquivo de configuração central do appliance, /opt/ironflock/.env, e a plataforma o usa automaticamente. Cada atualização posterior o mantém (veja Alterando ou removendo o proxy mais tarde). Nenhuma configuração separada é necessária para que o appliance fique online.

Executando a instalação atrás de um proxy

O proxy é necessário em dois lugares: o script de instalação precisa dele para baixar o ironflock, e o ironflock appliance install precisa dele para configurar o Docker. Defina a URL do proxy uma vez, passe-a ao curl com --proxy e ao script de instalação como variáveis de ambiente, e depois ao ironflock appliance install com --http-proxy / --https-proxy:

# Seu proxy corporativo — edite esta linha
PROXY="http://proxy.your-company.com:3128"
 
curl -fsSL --proxy "$PROXY" https://instance-registry.ironflock.com/dl/cli/install.sh \
  | sudo env HTTP_PROXY="$PROXY" HTTPS_PROXY="$PROXY" bash
 
sudo ironflock appliance install --license-file license.txt \
  --http-proxy "$PROXY" --https-proxy "$PROXY"

Substitua a URL do proxy pela sua, e license.txt pelo arquivo que contém a sua Instance Key (veja Instalação). Se o seu proxy exigir login, veja Autenticação no proxy: a senha não vai na URL.

As flags de proxy do ironflock appliance install:

O sudo não repassa as variáveis de proxy do seu shell para o ironflock, então informe o proxy com as flags. As outras flags do comando estão descritas em ironflock appliance install.

O tráfego local sempre ignora o proxy

Você não precisa gerenciar o NO_PROXY manualmente. A instalação sempre mantém localhost, 127.0.0.1 e o próprio endereço do host do appliance fora do proxy (qualquer coisa que você passe com --no-proxy é mantida e mesclada). Isso garante que a loja de apps e o registro locais do appliance sejam alcançados diretamente, nunca roteados através do proxy corporativo.

Autenticação no proxy

Se o seu proxy exige login, dê ao appliance uma conta de serviço própria, e não a conta de uma pessoa. Assim, o tráfego dele aparece nos logs do proxy sob um nome que a sua equipe de rede controla: ela pode limitar o que essa conta alcança e desativá-la ou rotacionar suas credenciais sem mexer no login pessoal de ninguém. Este é o lado do proxy de Identidade de rede para hosts do IronFlock.

• Suportado: autenticação Basic. Indique o usuário na URL do proxy e informe a senha com --proxy-password-file, um arquivo que a contém em uma linha (ou /dev/stdin). O ironflock recusa uma URL de proxy que contém uma senha, porque todo usuário do host pode ler as linhas de comando. O appliance guarda a senha em arquivos que só o root pode ler, então você pode excluir o arquivo depois:

  sudo ironflock appliance install --license-file license.txt \
    --https-proxy "http://[email protected]:3128" \
    --proxy-password-file proxy-password.txt

• Ainda não suportado: autenticação integrada do Windows (Kerberos, NTLM). Se o seu proxy não aceitar nenhuma outra, peça à sua equipe de rede que permita a conta de serviço com autenticação Basic, ou que libere o endereço do appliance sem autenticação, como um host nomeado.

O que informar à sua equipe de rede sobre o tráfego:

• Ele vai apenas para os endpoints da lista de Configuração de firewall, via HTTPS na porta 443. O relay de e-mail na porta 2525 nunca usa o proxy.
• A conexão de gerenciamento remoto com cbw.ironflock.com é um WebSocket de longa duração, com tráfego de keep-alive a cada poucos segundos. Se o proxy encerra conexões de longa duração após um tempo fixo, o appliance se reconecta sozinho em segundos, mas os usuários remotos podem notar uma breve interrupção a cada vez — sempre que possível, isente essa conexão dos limites de duração de conexões.

Alterando ou removendo o proxy mais tarde

O proxy é registrado no arquivo de configuração central do appliance, /opt/ironflock/.env, e cada atualização o mantém. Para alterá-lo em um appliance instalado, use o ironflock appliance configure. Ele aplica as configurações ao daemon do Docker, aos serviços da plataforma e ao agente do dispositivo, e só reinicia o appliance quando algo mudou:

# Mudar para outro proxy
sudo ironflock appliance configure --https-proxy "http://proxy2.your-company.com:3128"
 
# Alterar os hosts que ignoram o proxy
sudo ironflock appliance configure --no-proxy "buildserver.corp.example.com"

Cada configuração é independente: uma configuração que você não informa mantém o que o appliance tem, então passar apenas --https-proxy mantém a sua lista NO_PROXY existente intocada.

Para remover o proxy — por exemplo, após mover o appliance para uma rede com acesso direto à internet — passe um proxy vazio:

sudo ironflock appliance configure --http-proxy "" --https-proxy ""

A configuração de proxy é removida novamente do daemon do Docker e do agente do dispositivo, e o appliance volta a usar conexões diretas. Sua lista NO_PROXY é mantida para uma reativação posterior.

Um proxy que exige login não pode ser definido com o configure por enquanto: o ironflock appliance configure não aceita senha de proxy. Só o ironflock appliance install aceita --proxy-password-file. Executado em um appliance instalado, o appliance install o leva às opções informadas e mantém os seus segredos e configurações (Executar de novo), então ele pode definir o novo proxy com a sua senha:

sudo ironflock appliance install --version <version> \
  --https-proxy "http://[email protected]:3128" \
  --proxy-password-file proxy-password.txt

Informe em --version a versão que o appliance executa (o ironflock status a mostra); sem ela, a execução também atualiza o appliance para a versão mais nova do seu canal. O appliance instalado mantém a sua Instance Key, então a execução não precisa de --license-file.

Dispositivos de Borda

Tudo o que foi descrito acima se aplica igualmente aos dispositivos de borda conectados com o ironflock agent install. Ele aceita as mesmas flags de proxy — passe o proxy ao executá-lo, e ele roteia seus downloads (gerenciador de pacotes, instalação do Docker, download do agente), o daemon do Docker e o agente do dispositivo através do proxy para você:

sudo ironflock agent install -c mydevice.flock \
  --http-proxy "$PROXY" --https-proxy "$PROXY"

O script de instalação que baixa o ironflock é executado antes dele, então informe o proxy também nessa etapa. O sudo não repassa por padrão as variáveis de proxy do seu shell; passe-as explicitamente e repasse as flags de proxy ao ironflock agent install:

curl -fsSL --proxy "$PROXY" https://instance-registry.ironflock.com/dl/cli/install.sh \
  | sudo env HTTP_PROXY="$PROXY" HTTPS_PROXY="$PROXY" bash -s -- agent install -c mydevice.flock \
      --http-proxy "$PROXY" --https-proxy "$PROXY"

Se o dispositivo baixa imagens de apps de uma loja de apps de um appliance local em vez da nuvem, adicione o host desse registro com --no-proxy para que esses downloads permaneçam na rede local.

Se o proxy exigir login, a senha não vai na URL do proxy em um dispositivo. O ironflock recusa uma flag de proxy cuja URL contenha uma senha, porque todo usuário do dispositivo pode ler as linhas de comando. Indique o usuário na URL e coloque a senha em um arquivo que a contenha em uma linha:

sudo ironflock agent install -c mydevice.flock \
  --https-proxy "http://[email protected]:3128" \
  --proxy-password-file proxy-password.txt

O dispositivo guarda a senha em /etc/ironflock/proxy.env, que só o root pode ler, então você pode excluir o arquivo depois.

Em dispositivos Windows o agente é executado como um serviço do Windows. Passe o proxy ao instalador do serviço — ele cobre a conexão com a plataforma e as autoatualizações do agente:

.\device-agent.exe service install -config .\myaccount_myproject_mydevice.flock -proxy "http://proxy.example.com:3128"

Quais hosts ignoram o proxy

NO_PROXY aplica-se ao nome de host que o cliente disca, nunca ao endereço para o qual esse nome é resolvido. Um appliance que o dispositivo alcança pelo nome — ou seja, qualquer appliance em modo domínio, veja Interfaces de apps e HTTPS — precisa portanto ser nomeado explicitamente, caso contrário o agente envia sua conexão ao appliance local através do proxy corporativo. Como a maioria dos proxies se recusa a rotear de volta para a rede interna, o dispositivo nunca fica online.

O instalador deduz isso do próprio .flock do dispositivo. Ao lado de localhost e 127.0.0.1, ele adiciona o domínio do appliance — tanto na forma simples quanto na forma com ponto inicial — e qualquer host de registry acessado sem TLS. Dispositivos em nuvem não recebem nada além das duas entradas de loopback, porque seus endpoints são públicos e realmente precisam do proxy.

Tudo o mais que sua instalação exigir vai em -no-proxy, a contraparte da flag --no-proxy do ironflock agent install:

.\device-agent.exe service install -config .\myaccount_myproject_mydevice.flock `
  -proxy "http://proxy.example.com:3128" `
  -no-proxy "buildserver.corp.example,10.0.0.0/8"

Alterar as configurações depois

O resultado é gravado em %ProgramData%\IronFlock\DeviceAgent\proxy.env, e a partir daí é esse arquivo que vale:

HTTP_PROXY=http://proxy.example.com:3128
HTTPS_PROXY=http://proxy.example.com:3128
NO_PROXY=localhost,127.0.0.1,appliance.corp.example,.appliance.corp.example

Edite-o e execute .\device-agent.exe service install novamente para aplicar a alteração. Uma instalação posterior nunca sobrescreve o arquivo, e service uninstall mantém o diretório do agente — portanto suas configurações sobrevivem ao ciclo de desinstalação/instalação que reinstalar o serviço exige. Use -force-proxy para substituir deliberadamente o arquivo pelos valores das flags.

Em dispositivos Windows instalados antes do agente 1.4.0, a pasta continua sendo %ProgramData%\IronFlock\Reagent até que o agente tenha movido o dispositivo para a nova estrutura.

Remova uma entrada se esta instalação alcança o appliance através do proxy. Os dois cenários são reais: um appliance na mesma LAN da fábrica é alcançado diretamente, enquanto um hospedado centralmente pode ser acessível apenas pelo proxy corporativo. O instalador não consegue distingui-los, por isso grava os hosts literalmente — remova os que não se aplicam à sua rede.

O Docker é configurado separadamente

O Docker Desktop não lê nem o proxy.env nem o ambiente do serviço. As imagens são baixadas pelo daemon do Docker, que tem configurações próprias em Settings → Resources → Proxies, incluindo sua própria lista de exceções — e essa lista também precisa do host do appliance. Um proxy corrigido do lado do agente não resolve o docker pull.

Dispositivos Linux

O ironflock agent install aceita --no-proxy diretamente, então o appliance pode ser nomeado já na instalação:

sudo ironflock agent install -c mydevice.flock \
  --http-proxy "$PROXY" --https-proxy "$PROXY" \
  --no-proxy "appliance.corp.example.com"

localhost, 127.0.0.1 e ::1 sempre ignoram o proxy. O mesmo vale para o servidor de atualizações indicado no arquivo .flock do dispositivo quando ele não é um host da nuvem IronFlock, o que é o caso dos dispositivos de um appliance.

As configurações ficam em /etc/ironflock/proxy.env, que só o root pode ler. O Docker e o agente do dispositivo as leem dali. Para ajustá-las depois, use ironflock agent configure. Cada flag que você informar substitui a configuração correspondente, e as outras permanecem:

# Alterar os hosts que ignoram o proxy
sudo ironflock agent configure --no-proxy "appliance.corp.example.com,buildserver.corp.example"
 
# Mudar para outro proxy
sudo ironflock agent configure --https-proxy "http://proxy2.your-company.com:3128"
 
# Tirar o dispositivo do proxy
sudo ironflock agent configure --remove-proxy

O comando mostra as configurações antes e depois da alteração. O Docker precisa reiniciar para aplicá-las, o que para os apps do dispositivo por um momento, por isso o comando pergunta antes. Uma variável de proxy em um drop-in do systemd criado por você (systemctl edit) deixa de ter efeito quando o arquivo de configurações define a mesma variável; o comando avisa sobre um drop-in assim. Veja ironflock agent configure para os detalhes.

Dispositivos configurados antes do ironflock mantêm o proxy em um drop-in do systemd chamado http-proxy.conf, onde todo usuário do dispositivo pode lê-lo, inclusive uma senha. A primeira execução do ironflock agent configure move as configurações para /etc/ironflock/proxy.env.

Em dispositivos instalados antes de outubro de 2026, a unit ainda se chama reagent.service (com o diretório de drop-ins reagent.service.d) até o agente mover o dispositivo para o novo layout.

Proxies que Interceptam TLS (CA Corporativa)

Muitos proxies corporativos inspecionam o tráfego HTTPS re-assinando-o com uma autoridade certificadora (CA) da empresa. Para esses, configurar o proxy é necessário, mas não suficiente — o host do appliance também precisa confiar nessa CA, ou toda conexão com a nuvem (download de imagens, validação de licença, o uplink de gerenciamento) é rejeitada.

Aqui se trata de o appliance confiar na sua CA — não de servir HTTPS aos navegadores. Aqui você faz as conexões de saída do appliance com a nuvem funcionarem através de um proxy que intercepta TLS. Servir as interfaces web dos apps aos navegadores na sua rede é a direção oposta — veja Interfaces de apps e HTTPS.

Instale a CA uma única vez, no armazenamento de confiança do sistema do host. O appliance monta esse armazenamento de confiança em todos os seus contêineres, então o Docker e todos os serviços do IronFlock captam a CA — não há nada a configurar por contêiner ou por serviço. Como os contêineres a leem na inicialização, reinicie a stack após adicionar ou alterar a CA (passo 3 abaixo).

1. Obtenha a CA corporativa

Peça à sua equipe de rede a CA raiz de “inspeção SSL” / “interceptação TLS” do proxy — o mesmo certificado já implantado nas máquinas corporativas gerenciadas — como um arquivo .crt. Essa é a fonte mais limpa.

Instale a CA emissora, não o certificado de um único host. O erro comum é salvar o certificado re-assinado pelo proxy para um hostname (por exemplo, apenas instance-registry.ironflock.com). Isso faz apenas aquele host funcionar e deixa todos os outros hosts da nuvem falhando. Você precisa da CA que assina esses certificados.

Se você não conseguir obter o arquivo diretamente, mas o proxy apresentar sua cadeia completa, você pode extrair a CA da conexão — substitua <PROXY_HOST>:<PROXY_PORT> pelo seu proxy:

# Captura a cadeia, um PEM por certificado. c1 é o leaf por host (ignore-o);
# c2..cN são a cadeia da CA corporativa a confiar.
echo quit | openssl s_client -connect instance-registry.ironflock.com:443 \
  -proxy <PROXY_HOST>:<PROXY_PORT> -showcerts 2>/dev/null \
  | awk '/BEGIN CERTIFICATE/{n++; c=1} c{print > ("/tmp/proxy-c" n ".pem")} /END CERTIFICATE/{c=0}'
 
# Opcional — inspecione o que retornou:
for f in /tmp/proxy-c*.pem; do echo "== $f =="; openssl x509 -in "$f" -noout -subject -issuer; done

2. Instale-a e reconstrua o armazenamento de confiança

Se sua equipe de TI forneceu o .crt diretamente:

sudo cp corporate-root-ca.crt /usr/local/share/ca-certificates/corporate-proxy-ca.crt
sudo update-ca-certificates

Se você a extraiu da cadeia acima, confie em todos os certificados exceto o leaf (c1):

i=0; for f in $(ls -v /tmp/proxy-c*.pem | tail -n +2); do
  i=$((i+1)); sudo cp "$f" "/usr/local/share/ca-certificates/corporate-proxy-ca-$i.crt"
done
sudo update-ca-certificates

3. Verifique

Todo host da nuvem do IronFlock agora deve validar através do proxy — um status HTTP, não um erro de TLS:

for H in instance-registry.ironflock.com web.ironflock.com cbw.ironflock.com \
         registry.ironflock.com regauth.ironflock.com; do
  curl -x http://<PROXY_HOST>:<PROXY_PORT> -sS -o /dev/null -w "$H -> %{http_code}\n" "https://$H/"
done

Um código como 200, 401 ou 404 para os cinco significa que a CA está correta. Em seguida, reinicie o appliance para que os serviços a considerem. Se a instalação tinha parado na etapa de login, execute em vez disso o mesmo comando de instalação novamente: ele continua de onde parou.

sudo ironflock appliance restart

Acesso remoto às interfaces de usuário dos dispositivos

O IronFlock permite que você abra uma interface de usuário que roda em um dispositivo ou máquina de borda — uma HMI de máquina, uma página de PLC, uma tela de configuração ou dashboard no próprio dispositivo — diretamente dentro do IronFlock, de qualquer lugar. Este é um facilitador essencial para serviço e suporte remotos: um engenheiro pode alcançar a interface de uma máquina sem estar no local ou na rede local. O acesso é sempre mediado e protegido pelo sistema de privilégios do IronFlock, de modo que apenas usuários autorizados alcancem um determinado dispositivo.

Esse túnel de acesso remoto é construído sobre o frp (Fast Reverse Proxy), uma tecnologia de código aberto madura e amplamente utilizada. O IronFlock a usa exclusivamente para fornecer o acesso às interfaces de dispositivos descrito acima.

Por que um proxy corporativo pode atrapalhar

O frp tem capacidades poderosas de travessia de rede e, por essa razão, produtos de segurança de antivírus e proxy frequentemente o marcam genericamente como riskware — mesmo que, sendo um componente de código aberto com um longo histórico, seja seguro e usado aqui apenas para o recurso sancionado de acesso remoto. Quando isso acontece, o proxy bloqueia o download do componente do IronFlock que contém o frp.

Isso não quebra o seu appliance: o túnel de acesso remoto é um recurso opcional, então, se esse componente for bloqueado, a plataforma instala e roda normalmente e simplesmente opera sem acesso às interfaces dos dispositivos. No dashboard, os controles de acesso remoto de um dispositivo então indicam que o acesso remoto não está disponível neste appliance.

O que a TI corporativa precisa liberar

Se a sua organização quer se beneficiar dos recursos de serviço remoto do IronFlock, o componente do IronFlock que contém o frp precisa ter permissão para ser baixado através do proxy corporativo. Peça à sua equipe de rede/segurança duas coisas específicas:

• Uma exceção de varredura para downloads de imagens de instance-registry.ironflock.com, para que a classificação genérica como riskware não bloqueie o componente do túnel. Isso é mais restrito do que excluir todo o tráfego do IronFlock da inspeção TLS — o restante do tráfego do appliance pode continuar sendo inspecionado.
• O registro da detecção como um falso positivo conhecido. O frp é um proxy reverso de código aberto amplamente utilizado; o IronFlock o usa apenas para o recurso de acesso remoto com controle de acesso descrito acima.

Os mesmos endpoints do IronFlock já listados para o appliance se aplicam — veja Configuração de firewall; trata-se de não varrer/bloquear esse tráfego, além de meramente roteá-lo.

Uma vez que o frp esteja liberado, a próxima atualização tenta o download novamente, e o recurso é ativado assim que ele for bem-sucedido, sem nenhuma outra alteração. Para tentar de imediato, execute a instalação novamente com a versão que o appliance executa (o ironflock status a mostra); ela mantém os segredos e as configurações do appliance:

sudo ironflock appliance install --version <version>

Rodando sem acesso remoto

Se você não precisa de acesso às interfaces dos dispositivos — ou quer uma instalação limpa enquanto a exceção no proxy é providenciada — você pode desabilitar o túnel explicitamente. Todo o resto instala normalmente:

# no momento da instalação
sudo ironflock appliance install --license-file license.txt --no-tunnel
 
# ou em um appliance já instalado
sudo ironflock appliance configure --no-tunnel

A escolha é lembrada entre atualizações. Reative-o mais tarde (uma vez que o frp esteja liberado) com --tunnel:

sudo ironflock appliance configure --tunnel

Solução de problemas

A instalação para no login em instance-registry.ironflock.com com um erro Client.Timeout. O daemon do Docker não consegue alcançar o registro. Execute o ironflock appliance install novamente e informe seu proxy com --http-proxy / --https-proxy, como mostrado acima.

O login ainda falha após configurar o proxy. Seu proxy provavelmente intercepta TLS. Instale a CA corporativa conforme descrito em Proxies que Interceptam TLS, e então execute o comando de instalação novamente.

Verifique se o daemon do Docker enxerga o proxy:

sudo docker info | grep -i proxy
sudo docker login instance-registry.ironflock.com

O docker info mostra o proxy que o Docker usa, com a senha mascarada. Se o docker login for bem-sucedido por conta própria, a instalação do appliance conseguirá passar da etapa que falha.

Um único componente falha ao ser baixado, enquanto todo o resto instala normalmente. Isso geralmente é o componente de acesso remoto baseado em frp sendo bloqueado pelo seu proxy ou antivírus como riskware. A instalação ainda é concluída — apenas o acesso às interfaces dos dispositivos fica indisponível. Para habilitá-lo, peça à sua equipe de proxy para liberar esse tráfego conforme descrito em Acesso remoto às interfaces de usuário dos dispositivos, e então execute sudo ironflock appliance install --version <version> com a versão que o appliance executa. Para instalar deliberadamente sem ele, passe --no-tunnel.

Atualizações

Uma vez que um appliance é instalado atrás de um proxy, suas configurações de proxy são lembradas em /opt/ironflock/.env e reaplicadas em cada atualização. As atualizações pela UI do appliance e com ironflock appliance update continuam funcionando através do proxy sem nenhuma ação extra — veja Manutenção no guia do Appliance. Para apontar o appliance para um proxy diferente — ou tirá-lo do proxy completamente — veja Alterando ou removendo o proxy mais tarde.

Se o acesso remoto às interfaces dos dispositivos foi bloqueado no momento da instalação, cada atualização o tenta novamente de forma automática — então, assim que o seu proxy liberar o frp, a próxima atualização ativa o recurso sem passos extras.