HTTPS e certificados

Quando um app em um dispositivo conectado expõe uma interface web, o appliance a torna acessível através do seu túnel embutido. Você escolhe como os navegadores alcançam o appliance — há três modos, do zero de configuração ao totalmente assinado pela empresa. Escolha um e siga seus passos.

Não é o mesmo que Atrás de um Proxy Corporativo. Aquela página trata do appliance confiando na sua CA corporativa para o tráfego de saída (appliance → nuvem, através de um proxy que intercepta TLS). Esta página é a direção oposta — tráfego de entrada de navegadores na sua rede alcançando o appliance. Os dois são independentes.

Modo 1 — HTTP simples (padrão)

O que você obtém. Tudo sobre HTTP simples no endereço do appliance:

Cada UI de app é publicada em sua própria porta atribuída automaticamente; a interface do IronFlock mostra o link exato de cada uma. As UIs dos apps permanecem atrás do login do appliance — abrir uma redireciona para o login, a menos que você esteja autenticado e autorizado para aquele dispositivo (uma porta pode ser marcada como pública por app, onde você quiser deixá-la aberta).

O que você precisa fazer. Nada. Este é o padrão — apenas use o IP ou o hostname do appliance na sua rede local. Sem DNS, sem certificado, sem envolvimento da TI corporativa.

Quando usar. Um appliance em uma rede confiável e segmentada — um painel de controle em uma VLAN de máquina/OT — onde o HTTP simples é a norma e o acesso é controlado por segmentação de rede e segurança física.

Modo 2 — HTTPS com uma CA autoassinada

O que você obtém. O appliance ativa seu ingress HTTPS embutido e serve tudo sobre HTTPS sob o seu domínio — usando um certificado que ele mesmo gera. Não há proxy reverso para executar e nenhuma URL para reconfigurar; o instalador cuida de tudo.

O que você precisa fazer.

1. Escolha um domínio que resolva para o appliance em cada navegador e dispositivo que o usará, e defina tanto APPLIANCE_HOST quanto APPLIANCE_DOMAIN para ele. Como o appliance emite o certificado ele mesmo, qualquer nome funciona — o único requisito é que ele resolva. Para qualquer coisa além de um teste rápido, use um domínio interno que você controla (por exemplo, appliance.corp.example.com) com um registro wildcard no seu próprio DNS: uma rede de appliance isolada ou com DNS restrito geralmente não consegue alcançar o serviço público nip.io do qual depende o nome padrão <host-ip>.nip.io. (Esse padrão funciona onde a rede consegue alcançar a internet — que é por isso que funciona em uma máquina de desenvolvimento.)

2. Adicione DNS wildcard para o domínio, ambos os registros apontando para o IP do host do appliance:

   • *.<APPLIANCE_DOMAIN> — cobre as UIs dos apps e cada subdomínio de serviço.
   • <APPLIANCE_DOMAIN> (apex) — a UI principal pelo nome.

   (Um serviço de DNS wildcard como nip.io já resolve esses registros automaticamente, então não há registros a adicionar — mas depende de esse serviço externo estar acessível.)

3. Instale com --tls:

   curl -fsSL https://instance-registry.ironflock.com/dl/appliance/install_ironflock.sh \
     | sudo bash -s -- <your-instance-key> --interactive --tls

   --interactive solicita APPLIANCE_HOST / APPLIANCE_DOMAIN (ou defina IRONFLOCK_APPLIANCE_HOST / IRONFLOCK_APPLIANCE_DOMAIN para uma instalação não assistida). O appliance gera uma CA local em /opt/ironflock/certs/ca/rootCA.crt e um certificado wildcard assinado por ela.

4. Distribua a raiz da CA para as máquinas cliente. Envie o rootCA.crt via seu MDM, ou adicione-o ao armazenamento de confiança do SO/navegador de cada máquina. Até que uma máquina confie nele, seu navegador exibe avisos.

5. Renove dentro de um ano. O certificado do servidor é limitado a ~1 ano — os navegadores rejeitam certificados de vida mais longa. Para renovar, exclua o tls.crt/tls.key no diretório de certificados e execute o instalador novamente; ele re-assina um certificado novo contra a mesma CA, então a confiança que você distribuiu continua funcionando.

Os dispositivos permanecem no caminho do IP simples. Apenas o lado do navegador muda para HTTPS. Os dispositivos conectados continuam alcançando o appliance pelo seu IP, então você não precisa instalar a CA em cada dispositivo.

Quando usar. Você quer HTTPS em uma rede compartilhada, mas não tem (ou não quer esperar por) um certificado da TI corporativa, e você consegue distribuir uma raiz de CA para as máquinas que abrirão a interface.

Modo 3 — HTTPS com o seu certificado corporativo

O que você obtém. O mesmo HTTPS completo do appliance que o Modo 2 — mas o certificado vem da CA da sua organização, cuja raiz já é confiável em cada máquina gerenciada. Sem avisos do navegador, nada a distribuir. Os dispositivos também passam para o domínio.

O que você precisa fazer.

1. Escolha um domínio interno que você controla e defina APPLIANCE_HOST e APPLIANCE_DOMAIN para ele (por exemplo, appliance.corp.example.com). Aqui ele precisa ser o seu próprio domínio — uma CA só emite certificados para domínios que você possui, então um nome nip.io não funciona neste modo.
2. Adicione DNS wildcard — *.<APPLIANCE_DOMAIN> e o apex, apontando para o IP do host do appliance — como no Modo 2, passo 2.
3. Obtenha um certificado wildcard para *.<APPLIANCE_DOMAIN> da sua CA interna, como dois arquivos PEM: tls.crt (idealmente com a cadeia completa) e um tls.key não criptografado.
4. Instale com o seu certificado:

   curl -fsSL https://instance-registry.ironflock.com/dl/appliance/install_ironflock.sh \
     | sudo bash -s -- <your-instance-key> --interactive \
         --tls-cert /path/to/wildcard.crt \
         --tls-key  /path/to/wildcard.key

   --tls-cert implica --tls. Variáveis de ambiente equivalentes: IRONFLOCK_TLS_CERT / IRONFLOCK_TLS_KEY.
5. Rotacione no cronograma da sua CA. Coloque os novos arquivos PEM no diretório de certificados e reinicie:

   sudo cp wildcard.crt /opt/ironflock/certs/tls.crt
   sudo cp wildcard.key /opt/ironflock/certs/tls.key
   sudo chmod 0600 /opt/ironflock/certs/tls.key
   sudo systemctl restart ironflock.service

   O appliance recarrega o certificado automaticamente quando o arquivo muda; o restart apenas o aplica imediatamente. Executar o instalador novamente nunca sobrescreve um certificado existente, a menos que você passe --tls-cert.

Os dispositivos também passam para o domínio. Como o certificado é confiável em toda a frota, o tráfego dos dispositivos — o link do dispositivo, os downloads de imagens de contêiner e as atualizações do agente de dispositivo — também roda sobre o domínio via TLS, e a solução alternativa insecure-registries deixa de ser necessária. Isso vale para imagens de app construídas depois da mudança; apps instalados antes dela mantêm o endereço de registro contra o qual foram construídos, que o agente 0.21.3 e posteriores resolvem por conta própria — veja o requisito 4 abaixo.

O que os dispositivos conectados precisam neste modo

Cada dispositivo de borda que se conecta ao appliance precisa:

1. Resolver o domínio. <APPLIANCE_DOMAIN> e seus subdomínios (o registro wildcard) precisam resolver para o IP do appliance a partir da rede do dispositivo — os mesmos registros DNS que atendem os navegadores.
2. Alcançar o appliance na porta 443 — a única porta de que os dispositivos precisam para a conexão com a plataforma, para as atualizações do agente de dispositivo (servidas de https://registry.<APPLIANCE_DOMAIN>/dl — a porta 15002 não é necessária neste modo) e para imagens de app construídas depois da mudança (apps instalados antes dela dependem do requisito 4). É isso que torna o modo 3 a escolha certa para dispositivos em redes restritas: a 443 de saída é permitida em praticamente todo lugar, e a conexão também funciona através de um proxy HTTP corporativo (forneça o proxy ao agente conforme descrito em Atrás de um Proxy Corporativo → Dispositivos de Borda). No modo simples, em contraste, os dispositivos precisam de acesso direto a várias portas de serviço do appliance que firewalls e proxies corporativos costumam bloquear — veja Conectividade de dispositivos.
3. Confiar na sua CA raiz corporativa. O agente e o Docker validam o certificado do appliance contra o repositório de confiança do sistema operacional do dispositivo:
   • Máquinas gerenciadas (Windows associado ao domínio, Linux gerenciado por MDM) normalmente já confiam na sua raiz corporativa — nada a fazer.
   • Windows não gerenciado: instale a CA raiz no repositório da máquina a partir de um prompt com privilégios elevados — certutil -addstore -f Root corporate-root-ca.crt — e então reinicie o Docker Desktop (ele importa as raízes confiáveis do repositório do Windows na inicialização) e o serviço do agente (Restart-Service reagent).
   • Linux: sudo cp corporate-root-ca.crt /usr/local/share/ca-certificates/ && sudo update-ca-certificates, depois reinicie o Docker (sudo systemctl restart docker) e o agente.
   • Os contêineres das apps herdam essa confiança automaticamente (agente 0.21.3 e mais recentes). Um contêiner carrega apenas o pacote de CAs da sua imagem base, e nenhuma imagem base inclui uma raiz interna — portanto, uma app que se conecta ao appliance por TLS não conseguia verificá-lo. O agente agora monta o repositório de confiança do próprio dispositivo em cada contêiner de app, somente leitura, em /etc/ironflock/certs/ca-bundle.crt, e aponta os runtimes habituais para ele (SSL_CERT_FILE, REQUESTS_CA_BUNDLE, NODE_EXTRA_CA_CERTS). Não há nada a configurar, mas o dispositivo em si precisa confiar na raiz, porque é exatamente essa confiança que o agente repassa. Se uma app define o seu próprio SSL_CERT_FILE, ele é mantido.
4. Atualizar o agente de dispositivo para 0.21.3 ou posterior — ou republicar apps instalados antes da mudança. O arquivo compose armazenado de um app carrega referências de imagem totalmente qualificadas — <APPLIANCE_IP>:15001/apps/… — gravadas quando o app foi construído. Essas referências são dados: mover o appliance para um domínio não reescreve nenhum arquivo compose. O agente 0.21.3 e posteriores resolvem uma referência dessas para o registro que o próprio dispositivo tem configurado, de modo que um app instalado antes da mudança continua funcionando sobre o domínio sem nada a fazer — o primeiro início após a atualização puxa cada imagem uma vez sob o novo nome. Um agente mais antigo usa a referência como está e continua discando o IP e a porta antigos: seu dispositivo ainda precisa da porta do registro (15001) acessível na rede local, e a porta 443 sozinha não basta para ele, até que o app seja reconstruído e republicado contra registry.<APPLIANCE_DOMAIN>. O appliance cuida do próprio lado automaticamente: enquanto o agente dele for anterior a 0.21.3 e existir uma referência assim, ele mantém o registro acessível na LAN e lista os arquivos compose afetados na saída do instalador. Depois que o agente estiver em dia — ou esses apps forem republicados — o próximo sudo ironflock-update não encontra mais nada pelo que esperar e retira o registro da LAN por conta própria.

Quando usar. O caminho corporativo on-prem padrão: sua organização já opera uma CA interna, então um certificado wildcard é emitido uma vez e confiável em todos os lugares, sem configuração por máquina.

Solução de problemas

Um link de UI de app não abre / conexão recusada. No modo simples, as UIs dos apps ficam em http://<host>:<port> — certifique-se de estar usando o link exato mostrado na interface do IronFlock (a porta é atribuída por app) e de que nada na rede bloqueia aquela porta.

O navegador avisa que o certificado não é confiável (após --tls). O cliente ainda não confia na CA do certificado. No Modo 2, implante a CA gerada pelo appliance (/opt/ironflock/certs/ca/rootCA.crt) no cliente. No Modo 3, certifique-se de que o cliente confia na raiz da sua CA interna.

Certificado expirado (autoassinado). Um certificado de servidor autoassinado é válido por cerca de um ano (os navegadores rejeitam certificados de vida mais longa). Renove-o: exclua o tls.crt/tls.key no diretório de certificados e execute o instalador novamente para re-assinar contra a mesma CA, ainda confiável — ou mude para um --tls-cert da sua própria CA.

Incompatibilidade de nome do certificado. O certificado não é um wildcard para o domínio em uso. Ele precisa cobrir *.<APPLIANCE_DOMAIN>, e o domínio da URL precisa corresponder a APPLIANCE_DOMAIN.

Um subdomínio não resolve (após --tls). Falta o DNS wildcard. Adicione um registro A *.<APPLIANCE_DOMAIN> apontando para o host do appliance — ele cobre as UIs dos apps e cada subdomínio de serviço.

Um app não inicia ou não consegue puxar sua imagem depois da mudança para o modo 3 — “connection refused” na porta 15001. O arquivo compose do app ainda referencia o registro pelo endereço IP do appliance, porque foi contra isso que ele foi construído, e o agente do dispositivo é anterior a 0.21.3 — a partir dessa versão o agente resolve uma referência dessas para o próprio registro. Atualize o agente de dispositivo, ou reconstrua e republique o app para que sua imagem seja resolvida via registry.<APPLIANCE_DOMAIN>. Até então o registro precisa continuar acessível na rede local, o que o appliance providencia por conta própria — um simples sudo ironflock-update restaura o vínculo com a LAN e nomeia os arquivos compose que ainda guardam uma referência antiga.

Uma app executa mas nunca conecta, e o log dela repete a mesma tentativa de conexão a cada poucos segundos. O contêiner da app não consegue verificar o certificado do appliance: o handshake TLS é abandonado logo após o certificado do servidor e o SDK tenta indefinidamente, enquanto o dispositivo permanece online porque o agente usa o repositório de confiança do sistema operacional e o contêiner não. Atualize o agente do dispositivo para 0.21.3 ou mais recente, que repassa o repositório de confiança do dispositivo aos contêineres de apps, e confirme que o dispositivo confia na sua raiz corporativa (requisito 3 acima). docker logs <contêiner> no dispositivo mostra o erro de verificação do certificado. Em um agente mais antigo a solução é por app: adicione a CA raiz à imagem, ou monte-a e defina SSL_CERT_FILE no arquivo compose da app.

Um dispositivo não conecta depois da mudança para o modo 3. Percorra os quatro requisitos de dispositivo acima: o domínio precisa resolver a partir da rede do dispositivo, a porta 443 no appliance precisa estar acessível (diretamente ou via proxy do dispositivo), o dispositivo precisa confiar na sua CA raiz corporativa, e apps instalados antes da mudança precisam do agente 0.21.3 ou de uma republicação antes de deixarem de precisar da porta do registro. No Windows, o log do agente em C:\ProgramData\IronFlock\Reagent\reagent.log (no Linux /var/log/reagent.log) mostra o erro exato de conexão — uma falha de DNS, um tempo esgotado ou um erro de verificação de certificado apontam, cada um, para um dos três primeiros.