HTTPS y certificados

Cuando una app en un dispositivo conectado expone una interfaz web, el appliance la hace alcanzable a través de su túnel integrado. Tú eliges cómo llegan los navegadores al appliance — hay tres modos, desde cero configuración hasta totalmente firmado por la empresa. Elige uno y sigue sus pasos.

No es lo mismo que Detrás de un proxy corporativo. Esa página trata sobre que el appliance confíe en tu CA corporativa para el tráfico saliente (appliance → nube, a través de un proxy que intercepta TLS). Esta página es la dirección opuesta — tráfico entrante desde los navegadores de tu red que alcanzan el appliance. Las dos son independientes.

Modo 1 — HTTP simple (predeterminado)

Qué obtienes. Todo por HTTP simple en la dirección del appliance:

Cada UI de app se publica en su propio puerto asignado automáticamente; la UI de IronFlock muestra el enlace exacto de cada una. Las UI de las apps permanecen detrás del inicio de sesión del appliance — abrir una redirige al inicio de sesión a menos que hayas iniciado sesión y estés autorizado para ese dispositivo (un puerto puede marcarse como público por app cuando quieras dejarlo abierto).

Qué tienes que hacer. Nada. Este es el modo predeterminado — solo usa la IP o el nombre de host del appliance en tu red local. Sin DNS, sin certificado, sin intervención de IT corporativo.

Cuándo usarlo. Un appliance en una red segmentada y de confianza — un armario de control en una VLAN de máquina/OT — donde el HTTP simple es la norma y el acceso se controla mediante segmentación de red y seguridad física.

Modo 2 — HTTPS con una CA autoemitida

Qué obtienes. El appliance activa su ingress HTTPS integrado y sirve todo por HTTPS bajo tu dominio — usando un certificado que genera él mismo. No hay ningún proxy inverso que ejecutar ni URL que reconfigurar; el instalador lo conecta todo.

Qué tienes que hacer.

1. Elige un dominio que resuelva al appliance para cada navegador y dispositivo que vaya a usarlo, y establece tanto APPLIANCE_HOST como APPLIANCE_DOMAIN con ese valor. Como el appliance emite el certificado él mismo, cualquier nombre sirve — el único requisito es que resuelva. Para cualquier uso más allá de una prueba rápida usa un dominio interno que controles (por ejemplo, appliance.corp.example.com) con un registro comodín en tu propio DNS: una red de appliance aislada o restringida por DNS normalmente no puede alcanzar el servicio público nip.io del que depende el nombre predeterminado <host-ip>.nip.io. (Ese predeterminado sí funciona cuando la red puede alcanzar internet — por eso funciona en una máquina de desarrollo).

2. Añade DNS comodín para el dominio, con ambos registros apuntando a la IP del host del appliance:

   • *.<APPLIANCE_DOMAIN> — cubre las UI de las apps y cada subdominio de servicio.
   • <APPLIANCE_DOMAIN> (ápice) — la UI principal por su nombre.

   (Un servicio de DNS comodín como nip.io ya resuelve esto automáticamente, así que no hay registros que añadir — pero depende de que ese servicio externo sea alcanzable).

3. Instala con --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 (o define IRONFLOCK_APPLIANCE_HOST / IRONFLOCK_APPLIANCE_DOMAIN para una instalación desatendida). El appliance genera una CA local en /opt/ironflock/certs/ca/rootCA.crt y un certificado comodín firmado por ella.

4. Distribuye la raíz de CA a las máquinas cliente. Envía rootCA.crt a través de tu MDM, o añádelo al almacén de confianza del sistema operativo/navegador de cada máquina. Hasta que una máquina confíe en ella, su navegador avisará.

5. Renueva antes de un año. El certificado del servidor está limitado a ~1 año — los navegadores rechazan los de vida más larga. Para renovar, elimina tls.crt/tls.key en el directorio del certificado y vuelve a ejecutar el instalador; vuelve a firmar un certificado nuevo contra la misma CA, de modo que la confianza que distribuiste sigue funcionando.

Los dispositivos permanecen en la ruta de IP simple. Solo el lado del navegador pasa a HTTPS. Los dispositivos conectados siguen alcanzando el appliance por su IP, así que no tienes que instalar la CA en cada dispositivo.

Cuándo usarlo. Quieres HTTPS en una red compartida pero no tienes (o no quieres esperar) un certificado de IT corporativo, y puedes distribuir una CA raíz a las máquinas que abrirán la UI.

Modo 3 — HTTPS con tu certificado corporativo

Qué obtienes. El mismo HTTPS de appliance completo que el Modo 2 — pero el certificado proviene de la CA de tu organización, cuya raíz ya es de confianza en cada máquina gestionada. Sin avisos del navegador, nada que distribuir. Los dispositivos también pasan al dominio.

Qué tienes que hacer.

1. Elige un dominio interno que controles y establece APPLIANCE_HOST y APPLIANCE_DOMAIN con ese valor (por ejemplo, appliance.corp.example.com). Aquí debe ser tu propio dominio — una CA solo emite certificados para dominios que posees, así que un nombre nip.io no funcionará en este modo.
2. Añade DNS comodín — *.<APPLIANCE_DOMAIN> y el ápice, apuntando a la IP del host del appliance — como en el Modo 2, paso 2.
3. Obtén un certificado comodín para *.<APPLIANCE_DOMAIN> de tu CA interna, como dos archivos PEM: tls.crt (idealmente con cadena completa) y una tls.key sin cifrar.
4. Instala con tu 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. Variables de entorno equivalentes: IRONFLOCK_TLS_CERT / IRONFLOCK_TLS_KEY.
5. Rota según el calendario de tu CA. Coloca los nuevos archivos PEM en el directorio del certificado y reinicia:

   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

   El appliance recarga el certificado automáticamente cuando el archivo cambia; el reinicio solo lo aplica de inmediato. Volver a ejecutar el instalador nunca sobrescribe un certificado existente a menos que pases --tls-cert.

Los dispositivos también pasan al dominio. Como el certificado es de confianza en toda la flota, el tráfico de los dispositivos — el enlace del dispositivo, las descargas de imágenes de contenedor y las actualizaciones del agente de dispositivo — también se ejecuta sobre el dominio vía TLS, y ya no se necesita el rodeo de insecure-registries. Esto se aplica a las imágenes de app creadas después del cambio; las apps instaladas antes conservan la dirección de registro contra la que se compilaron, que el agente 0.21.3 y posteriores resuelven por su cuenta — consulta el requisito 4 más abajo.

Qué necesitan los dispositivos conectados en este modo

Cada dispositivo de borde que se conecte al appliance debe:

1. Resolver el dominio. <APPLIANCE_DOMAIN> y sus subdominios (el registro comodín) deben resolver a la IP del appliance desde la red del dispositivo — los mismos registros DNS que sirven a los navegadores.
2. Alcanzar el appliance en el puerto 443 — el único puerto que los dispositivos necesitan para la conexión con la plataforma, para las actualizaciones del agente de dispositivo (servidas desde https://registry.<APPLIANCE_DOMAIN>/dl — el puerto 15002 no se necesita en este modo) y para las imágenes de app creadas después del cambio (las apps instaladas antes necesitan el requisito 4). Esto es lo que hace del modo 3 la opción correcta para dispositivos en redes restringidas: el 443 de salida está permitido casi en todas partes, y la conexión también funciona a través de un proxy HTTP corporativo (proporciona el proxy al agente como se describe en Detrás de un proxy corporativo → Dispositivos de borde). En el modo simple, en cambio, los dispositivos necesitan acceso directo a varios puertos de servicio del appliance que los firewalls y proxies corporativos bloquean con frecuencia — consulta Conectividad de dispositivos.
3. Confiar en la CA raíz corporativa. El agente y Docker validan el certificado del appliance contra el almacén de confianza del sistema operativo del dispositivo:
   • Máquinas gestionadas (Windows unido al dominio, Linux gestionado por MDM) normalmente ya confían en tu raíz corporativa — no hay nada que hacer.
   • Windows no gestionado: instala la CA raíz en el almacén de la máquina desde un símbolo del sistema con privilegios elevados — certutil -addstore -f Root corporate-root-ca.crt — y después reinicia Docker Desktop (importa las raíces de confianza del almacén de Windows al arrancar) y el servicio del agente (Restart-Service reagent).
   • Linux: sudo cp corporate-root-ca.crt /usr/local/share/ca-certificates/ && sudo update-ca-certificates, y luego reinicia Docker (sudo systemctl restart docker) y el agente.
   • Los contenedores de las apps heredan esa confianza automáticamente (agente 0.21.3 y posteriores). Un contenedor solo lleva el paquete de CA de su imagen base, y ninguna imagen base incluye una raíz interna, por lo que una app que se conecta al appliance por TLS no podía verificarlo. El agente ahora monta el almacén de confianza del propio dispositivo en cada contenedor de app, en modo solo lectura, en /etc/ironflock/certs/ca-bundle.crt, y apunta hacia él los entornos de ejecución habituales (SSL_CERT_FILE, REQUESTS_CA_BUNDLE, NODE_EXTRA_CA_CERTS). No hay nada que configurar, pero el dispositivo sí debe confiar en la raíz, porque es precisamente esa confianza la que transmite el agente. Si una app define su propio SSL_CERT_FILE, este se mantiene.
4. Actualizar el agente de dispositivo a 0.21.3 o posterior — o volver a publicar las apps instaladas antes del cambio. El archivo compose almacenado de una app contiene referencias de imagen completamente cualificadas — <APPLIANCE_IP>:15001/apps/… — fijadas cuando se compiló la app. Esas referencias son datos: mover el appliance a un dominio no reescribe ningún archivo compose. El agente 0.21.3 y posteriores resuelven una referencia así hacia el registro para el que está configurado el propio dispositivo, de modo que una app instalada antes del cambio sigue funcionando sobre el dominio sin hacer nada — el primer arranque tras la actualización descarga cada imagen una vez con su nuevo nombre. Un agente más antiguo usa la referencia tal cual y sigue marcando la IP y el puerto antiguos: su dispositivo seguirá necesitando el puerto del registro (15001) accesible en la red local, y el puerto 443 por sí solo no le basta, hasta que la app se recompile y se vuelva a publicar contra registry.<APPLIANCE_DOMAIN>. El appliance se encarga automáticamente de su propio lado: mientras su propio agente sea anterior a 0.21.3 y exista una referencia así, mantiene el registro accesible en la LAN y enumera los archivos compose afectados en la salida del instalador. Una vez que el agente está al día — o republicadas esas apps — el siguiente sudo ironflock-update no encuentra nada más que esperar y saca el registro de la LAN por su cuenta.

Cuándo usarlo. La ruta corporativa on-prem estándar: tu organización ya opera una CA interna, así que se emite un certificado comodín una vez y es de confianza en todas partes sin configuración por máquina.

Resolución de problemas

Un enlace de UI de app no se abre / conexión rechazada. En modo simple las UI de las apps están en http://<host>:<port> — asegúrate de usar el enlace exacto que se muestra en la UI de IronFlock (el puerto se asigna por app), y de que nada en la red bloquee ese puerto.

El navegador avisa de que el certificado no es de confianza (tras --tls). El cliente aún no confía en la CA del certificado. En el Modo 2, despliega la CA generada por el appliance (/opt/ironflock/certs/ca/rootCA.crt) en el cliente. En el Modo 3, asegúrate de que el cliente confíe en la raíz de tu CA interna.

Certificado caducado (autoemitido). Un certificado de servidor autoemitido es válido durante aproximadamente un año (los navegadores rechazan los de vida más larga). Renuévalo: elimina tls.crt/tls.key en el directorio del certificado y vuelve a ejecutar el instalador para volver a firmar contra la misma CA, aún de confianza — o cambia a un --tls-cert de tu propia CA.

Discrepancia en el nombre del certificado. El certificado no es un comodín para el dominio en uso. Debe cubrir *.<APPLIANCE_DOMAIN>, y el dominio de la URL debe coincidir con APPLIANCE_DOMAIN.

Un subdominio no resuelve (tras --tls). Falta el DNS comodín. Añade un registro A *.<APPLIANCE_DOMAIN> que apunte al host del appliance — cubre las UI de las apps y cada subdominio de servicio.

Una app no arranca o no puede descargar su imagen tras cambiar al modo 3 — “connection refused” en el puerto 15001. El archivo compose de la app sigue referenciando el registro por la dirección IP del appliance, porque eso es contra lo que se compiló, y el agente del dispositivo es anterior a 0.21.3 — a partir de esa versión el agente resuelve una referencia así hacia su propio registro. Actualiza el agente de dispositivo, o recompila y vuelve a publicar la app para que su imagen se resuelva vía registry.<APPLIANCE_DOMAIN>. Hasta entonces el registro tiene que seguir accesible en la red local, algo que el appliance dispone por sí mismo — un simple sudo ironflock-update restaura el enlace a la LAN y nombra los archivos compose que aún conservan una referencia antigua.

Una app se ejecuta pero nunca conecta, y su registro repite el mismo intento de conexión cada pocos segundos. El contenedor de la app no puede verificar el certificado del appliance: el handshake TLS se abandona justo después del certificado del servidor y el SDK reintenta indefinidamente, mientras el dispositivo sigue en línea porque el agente usa el almacén de confianza del sistema operativo y el contenedor no. Actualice el agente del dispositivo a 0.21.3 o posterior, que pasa el almacén de confianza del dispositivo a los contenedores de apps, y confirme que el dispositivo confía en su raíz corporativa (requisito 3 más arriba). docker logs <contenedor> en el dispositivo muestra el error de verificación del certificado. Con un agente anterior la solución es por app: añada la CA raíz a la imagen, o móntela y defina SSL_CERT_FILE en el archivo compose de la app.

Un dispositivo no se conecta tras cambiar al modo 3. Repasa los cuatro requisitos de dispositivo anteriores: el dominio debe resolver desde la red del dispositivo, el puerto 443 del appliance debe ser accesible (directamente o a través del proxy del dispositivo), el dispositivo debe confiar en tu CA raíz corporativa, y las apps instaladas antes del cambio necesitan el agente 0.21.3 o una republicación antes de dejar de necesitar el puerto del registro. En Windows, el log del agente en C:\ProgramData\IronFlock\Reagent\reagent.log (en Linux /var/log/reagent.log) muestra el error de conexión exacto — un fallo de DNS, un tiempo de espera agotado o un error de verificación de certificado apuntan cada uno a uno de los tres primeros.