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 instalador 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 o instalador 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 o instalador trata para você

Quando você informa um proxy no comando de instalação, o instalador configura o daemon do Docker para você — ele grava um drop-in de proxy em /etc/systemd/system/docker.service.d/http-proxy.conf e reinicia o Docker uma vez para que ele consiga alcançar o registro do IronFlock. Esse passo é:

Sem intervenção — você informa o proxy uma vez (veja abaixo); o instalador grava a configuração e reinicia o Docker para você, sem configuração manual do daemon.
Idempotente — em atualizações posteriores, ele só reinicia o Docker se o proxy realmente mudou, para que seus apps em execução não sejam perturbados.
Totalmente ignorado quando nenhum proxy é informado — instalações com internet direta não são afetadas.

O instalador 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 — esse arquivo permanece a fonte autoritativa em cada atualização posterior (veja Alterando ou removendo o proxy mais tarde). Nenhuma configuração separada é necessária para que o appliance fique online.

Executando o instalador atrás de um proxy

O proxy é necessário em dois lugares: o curl precisa dele para baixar o instalador, e o instalador precisa dele para configurar o Docker. Forneça-o a ambos em um único comando — defina a URL do proxy uma vez, passe-a ao curl com --proxy, e ao instalador 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/appliance/install_ironflock.sh \
  | sudo bash -s -- <your-instance-key> --http-proxy "$PROXY" --https-proxy "$PROXY"

Substitua a URL do proxy e <your-instance-key> pelos seus próprios valores. Se o seu proxy exigir autenticação, inclua as credenciais na URL: http://user:[email protected]:3128 — veja Autenticação no proxy para saber qual conta usar.

Flags de proxy do instalador:

Flag	Finalidade
`--http-proxy <url>`	Proxy para tráfego HTTP simples do daemon do Docker.
`--https-proxy <url>`	Proxy para tráfego HTTPS (o que importa para o download das imagens).
`--no-proxy <list>`	Hosts adicionais, separados por vírgula, que devem ignorar o proxy.

Os mesmos valores podem ser fornecidos como variáveis de ambiente IRONFLOCK_HTTP_PROXY, IRONFLOCK_HTTPS_PROXY e IRONFLOCK_NO_PROXY.

Se o host já exportar HTTP_PROXY / HTTPS_PROXY, você pode, em vez disso, executar sudo -E bash (sem as flags) e o instalador as detectará automaticamente — mas em um appliance recém-instalado essas variáveis geralmente não estão definidas, então passá-las explicitamente como acima é o caminho confiável. As variáveis de ambiente do shell só alimentam a primeira instalação: uma vez que o appliance esteja instalado, a configuração registrada nele prevalece (veja Alterando ou removendo o proxy mais tarde).

O tráfego local sempre ignora o proxy

Você não precisa gerenciar o NO_PROXY manualmente. O instalador 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. Coloque a conta na URL do proxy — http://user:[email protected]:3128 — no comando de instalação, ou em /opt/ironflock/.env seguido de sudo ironflock-update. Codifique em URL os caracteres especiais da senha (por exemplo, @ → %40).
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. Esse arquivo é a fonte autoritativa: o que ele contém é o que cada atualização aplica. Portanto, reconfigurar o proxy em um appliance instalado leva dois passos:

Edite as entradas HTTP_PROXY, HTTPS_PROXY e NO_PROXY em /opt/ironflock/.env.
Execute sudo ironflock-update.

A atualização reaplica as configurações em todos os lugares em uma única passada — o daemon do Docker, os serviços da plataforma, o agente do dispositivo e o túnel de acesso remoto — reiniciando apenas o que realmente mudou.

Como alternativa, passe os novos valores como flags — elas sobrescrevem o arquivo e são gravadas de volta nele:


sudo ironflock-update --https-proxy "http://user:[email protected]:3128"

Cada configuração é independente: passar apenas --https-proxy mantém a sua lista NO_PROXY existente intocada (o esquema HTTP ausente é espelhado automaticamente).

Para remover o proxy — por exemplo, após mover o appliance para uma rede com acesso direto à internet — esvazie as entradas em /opt/ironflock/.env (HTTP_PROXY=, HTTPS_PROXY=), ou passe flags explicitamente vazias, e então atualize:


sudo ironflock-update --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.

Dispositivos de Borda

Tudo o que foi descrito acima se aplica igualmente aos dispositivos de borda configurados com a ferramenta de configuração de dispositivos (ironflock-init). Ela aceita as mesmas flags de proxy e se configura da mesma forma — passe o proxy ao executá-la, e ela roteia seus downloads (gerenciador de pacotes, instalação do Docker, download do agente) e o daemon do Docker através do proxy para você:


sudo ./ironflock-init -c mydevice.flock \
  --http-proxy "$PROXY" --https-proxy "$PROXY"

O script de bootstrap que baixa a ferramenta de configuração roda antes dela, então informe o proxy a esse passo também — exporte-o primeiro no shell para que o download seja bem-sucedido:


export HTTP_PROXY="$PROXY"
export HTTPS_PROXY="$PROXY"
curl -sSL --proxy "$PROXY" https://instance-registry.ironflock.com/dl/reswarmify/install.sh | bash

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.

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:


reagent.exe service install -config path\to\config.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 homônima do ironflock-init:


reagent.exe service install -config path\to\config.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\Reagent\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 reagent.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.

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-init aceita --no-proxy diretamente, então o appliance pode ser nomeado já na instalação:


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

Isso cria um drop-in do systemd em /etc/systemd/system/reagent.service.d/http-proxy.conf. Não edite esse arquivo para ajustar as configurações depois — a ferramenta de instalação o reescreve. Use systemctl edit reagent, que cria um override.conf aplicado pelo systemd depois do drop-in do instalador e no qual o IronFlock nunca mexe:


sudo systemctl edit reagent


[Service]
Environment="NO_PROXY=localhost,127.0.0.1,appliance.corp.example.com"


sudo systemctl restart reagent

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.

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 a stack para que os serviços a considerem (ou execute o instalador novamente):


sudo systemctl restart ironflock.service

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, basta executar a atualização novamente — o recurso é ativado automaticamente assim que o download for bem-sucedido, sem nenhuma outra alteração:


sudo ironflock-update

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, anexado ao comando de instalação
... | sudo bash -s -- <your-instance-key> --no-tunnel
 
# ou em um appliance já instalado
sudo ironflock-update --no-tunnel

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


sudo ironflock-update --tunnel

Solução de problemas

A instalação para em “Logging in to instance-registry.ironflock.com” com um erro Client.Timeout. O daemon do Docker não consegue alcançar o registro. Execute o instalador 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 novamente.

Verifique se o daemon do Docker enxerga o proxy:


sudo systemctl show --property=Environment docker
sudo docker login instance-registry.ironflock.com

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 ironflock-update novamente. 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. Tanto as atualizações manuais quanto as atualizações automáticas em segundo plano 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.