Detrás de un proxy corporativo

Muchas redes de fábrica y empresariales solo alcanzan internet a través de un proxy HTTP corporativo (por ejemplo, un proxy Squid en el puerto 3128). El IronFlock Appliance se instala y funciona sin problemas en esta configuración — tú proporcionas tu proxy en el comando de instalación y ironflock appliance install configura todo lo demás por ti.

Esta página asume que el host del appliance no tiene definidas variables de entorno de proxy — tú proporcionas el proxy de forma explícita. Explica lo que la instalación gestiona automáticamente y el único paso adicional necesario para los proxies que interceptan TLS.

Este es el complemento sobre proxies de la sección Configuración del cortafuegos de la guía del Appliance. Deben ser alcanzables los mismos endpoints de IronFlock — la diferencia es que aquí se alcanzan a través de tu proxy.

Por qué un proxy requiere atención

Las imágenes de la plataforma IronFlock las descarga el demonio de Docker — un servicio en segundo plano con su propia configuración de red, separada de tu shell. Incluso en un host que por lo demás puede alcanzar internet a través del proxy, el demonio no lo conoce a menos que se le indique explícitamente. Si se deja sin configurar, intenta conectarse directamente, la red lo bloquea y la instalación se detiene en el paso de inicio de sesión con un timeout:


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

Qué gestiona la instalación por ti

Cuando proporcionas un proxy en el comando de instalación, ironflock appliance install configura por ti el demonio de Docker y el agente de dispositivo del host — guarda la configuración de proxy en /etc/ironflock/proxy.env, que solo root puede leer, hace que Docker y el agente usen ese archivo y reinicia Docker para que pueda alcanzar el registro de IronFlock. Este paso es:

Sin intervención — proporcionas el proxy una vez (ver más abajo); la instalación escribe la configuración y reinicia Docker por ti, sin configuración manual del demonio.
Omitido por completo cuando no se proporciona ningún proxy — las instalaciones con internet directo no se ven afectadas.

La instalación también enruta la propia conexión del appliance a la nube a través del proxy — la validación de la licencia y el enlace de gestión remota que te permite alcanzar tu instancia desde ironflock.com. Registra tu proxy en el archivo de configuración central del appliance, /opt/ironflock/.env, y la plataforma lo usa automáticamente. Cada actualización posterior lo conserva (consulta Cambiar o eliminar el proxy más adelante). No se necesita ninguna configuración adicional para que el appliance se conecte.

Ejecutar la instalación detrás de un proxy

El proxy se necesita en dos lugares: el script de instalación lo necesita para descargar ironflock, y ironflock appliance install lo necesita para configurar Docker. Define la URL del proxy una vez, pásala a curl con --proxy y al script de instalación como variables de entorno, y después a ironflock appliance install con --http-proxy / --https-proxy:


# Tu proxy corporativo — edita esta línea
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"

Sustituye la URL del proxy por la tuya, y license.txt por el archivo que contiene tu Instance Key (consulta Instalación). Si tu proxy exige iniciar sesión, consulta Autenticación del proxy: la contraseña no va en la URL.

Los flags de proxy de ironflock appliance install:

Flag	Propósito
`--http-proxy <url>`	Proxy para el tráfico HTTP simple de Docker, el agente y el appliance. `""` lo elimina.
`--https-proxy <url>`	Proxy para el tráfico HTTPS (el que importa para la descarga de imágenes). `""` lo elimina.
`--no-proxy <list>`	Hosts adicionales, separados por comas, que deben omitir el proxy.
`--proxy-password-file <file>`	Un archivo o una tubería (`/dev/stdin`) cuya única línea es la contraseña del usuario de las URL de proxy.

sudo no transmite a ironflock las variables de proxy de tu shell, así que indica el proxy con los flags. Los demás flags del comando se describen en ironflock appliance install.

El tráfico local siempre omite el proxy

No necesitas gestionar NO_PROXY a mano. La instalación siempre mantiene localhost, 127.0.0.1 y la propia dirección del host del appliance fuera del proxy (todo lo que pases con --no-proxy se conserva y se fusiona). Esto garantiza que la app store local y el registro del appliance se alcancen directamente, sin enrutarse hacia fuera a través del proxy corporativo.

Autenticación del proxy

Si tu proxy exige iniciar sesión, asigna al appliance su propia cuenta de servicio en lugar de la cuenta de una persona. Así, su tráfico aparece en los logs del proxy bajo un nombre que controla tu equipo de red: pueden limitar a qué puede acceder, y deshabilitarla o rotar su contraseña sin tocar el inicio de sesión personal de nadie. Esta es la parte del proxy de Identidad de red de los hosts de IronFlock.

Admitida: autenticación Basic. Indica el usuario en la URL del proxy y da la contraseña con --proxy-password-file, un archivo que la contiene en una línea (o /dev/stdin). ironflock rechaza una URL de proxy que contiene una contraseña, porque cualquier usuario del host puede leer las líneas de comandos. El appliance guarda la contraseña en archivos que solo root puede leer, así que después puedes borrar el archivo:
```
sudo ironflock appliance install --license-file license.txt \
  --https-proxy "http://[email protected]:3128" \
  --proxy-password-file proxy-password.txt
```
Aún no admitida: autenticación integrada de Windows (Kerberos, NTLM). Si tu proxy no acepta nada más, pide a tu equipo de red que permita la cuenta de servicio con autenticación Basic, o que admita la dirección del appliance sin autenticación como host con nombre.

Qué contarle a tu equipo de red sobre el tráfico:

Solo va a los endpoints de la lista de Configuración del cortafuegos, por HTTPS en el puerto 443. El relay de correo en el puerto 2525 nunca usa el proxy.
La conexión de gestión remota con cbw.ironflock.com es un WebSocket de larga duración con tráfico de keep-alive cada pocos segundos. Si el proxy corta las conexiones de larga duración tras un tiempo fijo, el appliance se reconecta por sí solo en cuestión de segundos, pero los usuarios remotos pueden notar una breve interrupción cada vez — siempre que puedas, exime esta conexión de los límites de duración de las conexiones.

Cambiar o eliminar el proxy más adelante

El proxy queda registrado en el archivo de configuración central del appliance, /opt/ironflock/.env, y cada actualización lo conserva. Para cambiarlo en un appliance ya instalado, usa ironflock appliance configure. Aplica la configuración al demonio de Docker, a los servicios de la plataforma y al agente del dispositivo, y reinicia el appliance solo cuando algo cambió:


# Cambiar a otro proxy
sudo ironflock appliance configure --https-proxy "http://proxy2.your-company.com:3128"
 
# Cambiar los hosts que eluden el proxy
sudo ironflock appliance configure --no-proxy "buildserver.corp.example.com"

Cada ajuste es independiente: un ajuste que no indicas conserva lo que tiene el appliance, así que pasar solo --https-proxy mantiene intacta tu lista NO_PROXY existente.

Para eliminar el proxy — por ejemplo, tras mover el appliance a una red con acceso directo a internet — pasa un proxy vacío:


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

La configuración de proxy se elimina de nuevo del demonio de Docker y del agente del dispositivo, y el appliance vuelve a las conexiones directas. Tu lista NO_PROXY se conserva para una posible reactivación posterior.

Un proxy que exige iniciar sesión no se puede definir hoy con configure: ironflock appliance configure no acepta contraseña de proxy. Solo ironflock appliance install acepta --proxy-password-file. Ejecutado en un appliance instalado, appliance install lo lleva a las opciones indicadas y conserva sus secretos y ajustes (Volver a ejecutarlo), así que puede definir el proxy nuevo con su contraseña:


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

Indica en --version la versión que ejecuta el appliance (ironflock status la muestra); sin ella, la ejecución también actualiza el appliance a la versión más reciente de su canal. El appliance instalado conserva su Instance Key, así que la ejecución no necesita --license-file.

Dispositivos de borde

Todo lo anterior se aplica igualmente a los dispositivos de borde conectados con ironflock agent install. Acepta los mismos flags de proxy: pasa el proxy cuando lo ejecutes y enrutará sus descargas (gestor de paquetes, instalación de Docker, descarga del agente), el demonio de Docker y el agente del dispositivo a través del proxy por ti:


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

El script de instalación que descarga ironflock se ejecuta antes que él, así que dale el proxy también a ese paso. sudo no transmite por defecto las variables de proxy de tu shell, por lo que debes pasarlas explícitamente, y reenvía los flags de proxy a 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"

Si el dispositivo descarga las imágenes de apps desde una app store local de un appliance en lugar de la nube, añade el host de ese registro con --no-proxy para que esas descargas permanezcan en la red local.

Si el proxy requiere inicio de sesión, la contraseña no va en la URL del proxy en un dispositivo. ironflock rechaza un flag de proxy cuya URL contiene una contraseña, porque cualquier usuario del dispositivo puede leer las líneas de comandos. Indica el usuario en la URL y pon la contraseña en un archivo que la contenga en una sola línea:


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

El dispositivo guarda la contraseña en /etc/ironflock/proxy.env, que solo root puede leer, así que después puedes eliminar el archivo.

En los dispositivos Windows el agente se ejecuta como servicio de Windows. Pase el proxy al instalador del servicio — cubre la conexión con la plataforma y las autoactualizaciones del agente:


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

Qué hosts eluden el proxy

NO_PROXY se aplica al nombre de host que marca el cliente, nunca a la dirección a la que ese nombre se resuelve. Un appliance al que el dispositivo llega por su nombre — cualquier appliance en modo dominio, véase Interfaces de apps y HTTPS — debe nombrarse explícitamente; de lo contrario el agente envía su conexión al appliance local a través del proxy corporativo y, como la mayoría de los proxies se niegan a enrutar de vuelta hacia la red interna, el dispositivo nunca se conecta.

El instalador lo deduce del propio .flock del dispositivo. Junto a localhost y 127.0.0.1 añade el dominio del appliance — tanto en su forma simple como con punto inicial — y cualquier host de registro al que se acceda sin TLS. Los dispositivos en la nube no reciben nada más allá de las dos entradas de loopback, porque sus endpoints son públicos y sí necesitan el proxy.

Todo lo demás que requiera su instalación va en -no-proxy, el equivalente al flag --no-proxy de 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"

Cambiar la configuración más adelante

El resultado se escribe en %ProgramData%\IronFlock\DeviceAgent\proxy.env, y ese archivo es autoritativo a partir de entonces:


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

Edítelo y vuelva a ejecutar .\device-agent.exe service install para aplicar el cambio. Una instalación posterior nunca sobrescribe el archivo, y service uninstall conserva el directorio del agente, de modo que su configuración sobrevive al ciclo de desinstalación/instalación que exige reinstalar el servicio. Use -force-proxy para reemplazar deliberadamente el archivo con los valores de los flags.

En los dispositivos Windows instalados antes del agente 1.4.0, la carpeta sigue siendo %ProgramData%\IronFlock\Reagent hasta que el agente haya movido el dispositivo a la nueva estructura.

Elimine una entrada si esta instalación llega al appliance a través del proxy. Ambos escenarios son reales: un appliance en la misma LAN de planta se alcanza directamente, mientras que uno alojado centralmente puede ser accesible solo por el proxy corporativo. El instalador no puede distinguirlos, así que escribe los hosts de forma literal — quite los que no correspondan a su red.

Docker se configura por separado

Docker Desktop no lee ni proxy.env ni el entorno del servicio. Las imágenes las descarga el demonio de Docker, que tiene su propia configuración en Settings → Resources → Proxies, incluida su propia lista de exclusiones — y esa lista también necesita el host del appliance. Un proxy corregido del lado del agente no arregla docker pull.

Dispositivos Linux

ironflock agent install acepta --no-proxy directamente, así que el appliance puede nombrarse ya durante la instalación:


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

localhost, 127.0.0.1 y ::1 siempre eluden el proxy. También lo elude el servidor de actualizaciones indicado en el archivo .flock del dispositivo cuando no es un host de la nube de IronFlock, como ocurre con los dispositivos de un appliance.

La configuración se guarda en /etc/ironflock/proxy.env, que solo root puede leer. Docker y el agente del dispositivo la toman de ahí. Para ajustarla después, usa ironflock agent configure. Cada flag que indiques reemplaza su ajuste, y los demás se mantienen:


# Cambiar los hosts que eluden el proxy
sudo ironflock agent configure --no-proxy "appliance.corp.example.com,buildserver.corp.example"
 
# Cambiar a otro proxy
sudo ironflock agent configure --https-proxy "http://proxy2.your-company.com:3128"
 
# Quitar el proxy del dispositivo
sudo ironflock agent configure --remove-proxy

El comando muestra la configuración antes y después del cambio. Docker tiene que reiniciarse para aplicarla, lo que detiene un momento las apps del dispositivo, así que el comando pregunta antes. Una variable de proxy en un drop-in de systemd propio (systemctl edit) deja de tener efecto en cuanto el archivo de configuración define la misma variable; el comando te avisa de un drop-in así. Consulta ironflock agent configure para más detalles.

Los dispositivos configurados antes de ironflock guardan su proxy en un drop-in de systemd llamado http-proxy.conf, donde cualquier usuario del dispositivo puede leerlo, incluida una contraseña. La primera ejecución de ironflock agent configure traslada la configuración a /etc/ironflock/proxy.env.

En los dispositivos instalados antes de octubre de 2026, la unidad sigue llamándose reagent.service (con el directorio de drop-ins reagent.service.d) hasta que el agente haya movido el dispositivo a la nueva estructura.

Proxies que interceptan TLS (CA corporativa)

Muchos proxies corporativos inspeccionan el tráfico HTTPS volviéndolo a firmar con una autoridad de certificación (CA) de la empresa. Para estos, configurar el proxy es necesario pero no suficiente — el host del appliance también debe confiar en esa CA, o se rechazará cada conexión a la nube (descargas de imágenes, validación de licencia, el enlace de gestión).

Instala la CA una sola vez, en el almacén de confianza del sistema del host. El appliance monta ese almacén de confianza en todos sus contenedores, de modo que Docker y todos los servicios de IronFlock toman la CA — no hay nada que configurar por contenedor ni por servicio. Como los contenedores la leen al arrancar, reinicia el stack tras añadir o cambiar la CA (paso 3 más abajo).

1. Obtén la CA corporativa

Pide a tu equipo de red la CA raíz de “inspección SSL” / “interceptación TLS” del proxy — el mismo certificado ya desplegado en las máquinas corporativas gestionadas — como un archivo .crt. Esa es la fuente más limpia.

Instala la CA emisora, no el certificado de un único host. El error habitual es guardar el certificado refirmado por el proxy para un nombre de host (por ejemplo, solo instance-registry.ironflock.com). Eso hace que únicamente ese host funcione y deja fallando a todos los demás hosts de la nube. Necesitas la CA que firma esos certificados.

Si no puedes obtener el archivo directamente pero el proxy presenta su cadena completa, puedes extraer la CA desde la conexión — sustituye <PROXY_HOST>:<PROXY_PORT> por tu proxy:


# Captura la cadena, un PEM por certificado. c1 es la hoja por host (omítela);
# c2..cN son la cadena de CA corporativa en la que 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 — inspecciona lo que se obtuvo:
for f in /tmp/proxy-c*.pem; do echo "== $f =="; openssl x509 -in "$f" -noout -subject -issuer; done

2. Instálala y reconstruye el almacén de confianza

Si tu equipo de IT te dio el .crt directamente:


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

Si la extrajiste de la cadena anterior, confía en cada certificado excepto la hoja (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. Verifica

Cada host de la nube de IronFlock debe validarse ahora a través del proxy — un estado HTTP, no un error 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

Un código como 200, 401 o 404 para los cinco significa que la CA es correcta. Luego reinicia el appliance para que los servicios la tomen. Si la instalación se había detenido en el paso de inicio de sesión, vuelve a ejecutar en su lugar el mismo comando de instalación: continúa desde donde se detuvo.


sudo ironflock appliance restart

Acceso remoto a las interfaces de usuario de los dispositivos

IronFlock te permite abrir una interfaz de usuario que se ejecuta en un dispositivo o máquina de borde — un HMI de máquina, una página de PLC, una pantalla de configuración o dashboard en el propio dispositivo — directamente dentro de IronFlock, desde cualquier lugar. Este es un habilitador clave para el servicio y soporte remotos: un ingeniero puede alcanzar la interfaz de una máquina sin estar en las instalaciones ni en la red local. El acceso está siempre mediado y protegido por el sistema de privilegios de IronFlock, de modo que solo los usuarios autorizados alcanzan un dispositivo dado.

Este túnel de acceso remoto está construido sobre frp (Fast Reverse Proxy), una tecnología de código abierto madura y ampliamente utilizada. IronFlock la usa únicamente para proporcionar el acceso a la interfaz de dispositivos descrito arriba.

Por qué un proxy corporativo puede interponerse

frp tiene potentes capacidades de atravesado de red y, por esa razón, los productos de seguridad antivirus y proxy a menudo lo marcan genéricamente como riskware — aunque, como componente de código abierto con una larga trayectoria, es seguro y aquí se usa solo para la función de acceso remoto autorizada. Cuando eso ocurre, el proxy bloquea la descarga del componente de IronFlock que contiene frp.

Esto no rompe tu appliance: el túnel de acceso remoto es una función opcional, así que si ese componente se bloquea, la plataforma se instala y funciona con normalidad y simplemente opera sin acceso a la interfaz de dispositivos. En el dashboard, los controles de acceso remoto de un dispositivo indican entonces que el acceso remoto no está disponible en este appliance.

Qué necesita permitir el IT corporativo

Si tu organización quiere beneficiarse de las funciones de servicio remoto de IronFlock, el componente de IronFlock que contiene frp debe poder descargarse a través del proxy corporativo. Pide a tu equipo de red/seguridad dos cosas concretas:

Una excepción de análisis para las descargas de imágenes desde instance-registry.ironflock.com, para que el veredicto genérico de riskware no bloquee el componente del túnel. Es más acotado que excluir todo el tráfico de IronFlock de la inspección TLS — el resto del tráfico del appliance puede seguir inspeccionándose.
Registrar la detección como un falso positivo conocido. frp es un proxy inverso de código abierto ampliamente utilizado; IronFlock lo usa únicamente para la función de acceso remoto descrita arriba, protegida por control de acceso.

Se aplican los mismos endpoints de IronFlock ya enumerados para el appliance — consulta Configuración del cortafuegos; esto trata de no analizar/bloquear ese tráfico, además de simplemente enrutarlo.

Una vez que frp está permitido, la siguiente actualización vuelve a intentar la descarga, y la función se activa en cuanto funciona, sin ningún otro cambio. Para intentarlo de inmediato, vuelve a ejecutar la instalación con la versión que ejecuta el appliance (ironflock status la muestra); conserva los secretos y los ajustes del appliance:


sudo ironflock appliance install --version <version>

Funcionar sin acceso remoto

Si no necesitas acceso a la interfaz de dispositivos — o quieres una instalación limpia mientras se gestiona la excepción del proxy — puedes desactivar el túnel explícitamente. Todo lo demás se instala con normalidad:


# en el momento de la instalación
sudo ironflock appliance install --license-file license.txt --no-tunnel
 
# o en un appliance ya instalado
sudo ironflock appliance configure --no-tunnel

La elección se recuerda entre actualizaciones. Vuelve a activarlo más tarde (una vez que frp esté permitido) con --tunnel:


sudo ironflock appliance configure --tunnel

Resolución de problemas

La instalación se detiene en el inicio de sesión en instance-registry.ironflock.com con un error Client.Timeout. El demonio de Docker no puede alcanzar el registro. Vuelve a ejecutar ironflock appliance install y pasa tu proxy con --http-proxy / --https-proxy, como se muestra arriba.

El inicio de sesión sigue fallando tras configurar el proxy. Lo más probable es que tu proxy intercepte TLS. Instala la CA corporativa como se describe en Proxies que interceptan TLS, y vuelve a ejecutar el comando de instalación.

Comprueba que el demonio de Docker ve el proxy:


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

docker info muestra el proxy que usa Docker, con la contraseña enmascarada. Si docker login funciona por sí solo, la instalación del appliance superará el paso que falla.

Un único componente no se descarga mientras todo lo demás se instala correctamente. Normalmente se trata del componente de acceso remoto basado en frp que tu proxy o antivirus bloquea como riskware. La instalación se completa igualmente — solo el acceso a la interfaz de dispositivos queda no disponible. Para habilitarlo, pide a tu equipo de proxy que permita ese tráfico como se describe en Acceso remoto a las interfaces de usuario de los dispositivos, y luego ejecuta sudo ironflock appliance install --version <version> con la versión que ejecuta el appliance. Para instalar deliberadamente sin él, pasa --no-tunnel.

Actualizaciones

Una vez que un appliance está instalado detrás de un proxy, su configuración de proxy se recuerda en /opt/ironflock/.env y se vuelve a aplicar en cada actualización. Las actualizaciones desde la UI del appliance y con ironflock appliance update siguen funcionando a través del proxy sin ninguna acción adicional — consulta Mantenimiento en la guía del Appliance. Para apuntar el appliance a un proxy diferente — o quitarlo del proxy por completo — consulta Cambiar o eliminar el proxy más adelante.

Si el acceso remoto a las interfaces de dispositivos fue bloqueado en el momento de la instalación, cada actualización lo reintenta automáticamente — así, en cuanto tu proxy permita frp, la siguiente actualización activa la función sin pasos adicionales.