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 na configuração do appliance, e a plataforma o usa automaticamente. 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:password@proxy.your-company.com:3128.

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.

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.

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 é armazenado no ambiente do serviço e 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"

O Docker Desktop não lê essa configuração: configure o proxy dele separadamente em Settings → Resources → Proxies para que os pulls de imagens também funcionem.

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 para:

Isentar o tráfego de download do IronFlock da varredura de conteúdo de antivírus / malware e do bloqueio de downloads de arquivos para o componente do frp — a opção mais limpa é adicionar os endpoints do IronFlock à lista de não descriptografar (bypass de inspeção TLS) do proxy.
Tratar a detecção do frp como uma exceção aprovada: é um falso positivo bem conhecido para o uso legítimo dessa biblioteca de código aberto.

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. 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.

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.