Behind a Corporate Proxy

Many factory and enterprise networks only reach the internet through a corporate HTTP proxy (for example a Squid proxy on port 3128). The IronFlock Appliance installs and runs cleanly in this setup — you provide your proxy on the install command, and the installer configures everything else for you.

This page assumes the appliance host has no proxy environment variables set — you supply the proxy explicitly. It explains what the installer handles automatically and the one extra step needed for proxies that intercept TLS.

This is the proxy companion to the Firewall Configuration section of the Appliance guide. The same IronFlock endpoints must be reachable — the difference is that here they are reached through your proxy.

Why a Proxy Needs Attention

The IronFlock platform images are pulled by the Docker daemon — a background service with its own network configuration, separate from your shell. Even on a host that can otherwise reach the internet through the proxy, the daemon doesn’t know about it unless it is told explicitly. Left unconfigured, it tries to connect directly, the network blocks it, and the install stops at the login step with a timeout:


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

What the Installer Handles for You

When you provide a proxy on the install command, the installer configures the Docker daemon for you — it writes a proxy drop-in at /etc/systemd/system/docker.service.d/http-proxy.conf and restarts Docker once so it can reach the IronFlock registry. This step is:

Hands-off — you supply the proxy once (see below); the installer writes the config and restarts Docker for you, no manual daemon setup.
Idempotent — on later updates it only restarts Docker if the proxy actually changed, so your running apps aren’t disturbed.
Skipped entirely when no proxy is given — direct-internet installs are unaffected.

The installer also routes the appliance’s own connection to the cloud through the proxy — license validation and the remote-management uplink that lets you reach your instance from ironflock.com. It records your proxy in the appliance’s central configuration file, /opt/ironflock/.env, and the platform uses it automatically — that file remains the authoritative source on every later update (see Changing or Removing the Proxy Later). No separate setup is needed for the appliance to come online.

Running the Installer Behind a Proxy

The proxy is needed in two places: curl needs it to download the installer, and the installer needs it to configure Docker. Provide it to both in one command — set the proxy URL once, pass it to curl with --proxy, and to the installer with --http-proxy / --https-proxy:


# Your corporate proxy — edit this line
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"

Replace the proxy URL and <your-instance-key> with your own values. If your proxy requires authentication, include the credentials in the URL: http://user:[email protected]:3128 — see Proxy Authentication for which account to use.

Installer proxy flags:

Flag	Purpose
`--http-proxy <url>`	Proxy for plain HTTP traffic from the Docker daemon.
`--https-proxy <url>`	Proxy for HTTPS traffic (the one that matters for image pulls).
`--no-proxy <list>`	Extra comma-separated hosts that should bypass the proxy.

The same values can be supplied as IRONFLOCK_HTTP_PROXY, IRONFLOCK_HTTPS_PROXY, and IRONFLOCK_NO_PROXY environment variables.

If the host does already export HTTP_PROXY / HTTPS_PROXY, you can instead run sudo -E bash (without the flags) and the installer will auto-detect them — but on a fresh appliance these are usually unset, so passing them explicitly as above is the reliable path. Shell environment variables only seed the first install: once the appliance is installed, its recorded configuration wins (see Changing or Removing the Proxy Later).

Local traffic always bypasses the proxy

You don’t need to manage NO_PROXY by hand. The installer always keeps localhost, 127.0.0.1, and the appliance’s own host address off the proxy (anything you pass with --no-proxy is kept and merged). This ensures the appliance’s local app store and registry are reached directly, never routed out through the corporate proxy.

Proxy Authentication

If your proxy requires a login, give the appliance its own service account rather than a person’s account. Its traffic then appears in your proxy logs under a name your network team controls: they can limit what it may reach, and disable or rotate it without touching anyone’s personal login. This is the proxy side of Network Identity for IronFlock Hosts.

Supported: Basic authentication. Put the account in the proxy URL — http://user:[email protected]:3128 — on the install command, or in /opt/ironflock/.env followed by sudo ironflock-update. URL-encode special characters in the password (for example @ → %40).
Not supported yet: Windows-integrated authentication (Kerberos, NTLM). If your proxy accepts nothing else, ask your network team to allow the service account with Basic authentication, or to admit the appliance’s address without authentication as a named host.

What to tell your network team about the traffic:

It goes only to the endpoints in the Firewall Configuration list, over HTTPS on port 443. The email relay on port 2525 never uses the proxy.
The remote-management connection to cbw.ironflock.com is a long-lived WebSocket with keep-alive traffic every few seconds. If the proxy cuts long-lived connections after a fixed time, the appliance reconnects on its own within seconds, but remote users may notice a short interruption each time — exempt this connection from connection-lifetime limits where you can.

Changing or Removing the Proxy Later

The proxy is recorded in the appliance’s central configuration file, /opt/ironflock/.env. That file is the authoritative source: whatever it holds is what every update applies. So reconfiguring the proxy on an installed appliance takes two steps:

Edit the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY entries in /opt/ironflock/.env.
Run sudo ironflock-update.

The update re-applies the settings everywhere in one pass — the Docker daemon, the platform services, the device agent, and the remote-access tunnel — restarting only what actually changed.

Alternatively, pass the new values as flags — they override the file and are saved back into it:


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

Each setting is independent: passing only --https-proxy keeps your existing NO_PROXY list untouched (the missing HTTP scheme is mirrored automatically).

To remove the proxy — for example after moving the appliance to a network with direct internet access — blank the entries in /opt/ironflock/.env (HTTP_PROXY=, HTTPS_PROXY=), or pass explicitly empty flags, then update:


sudo ironflock-update --http-proxy "" --https-proxy ""

The proxy configuration is removed from the Docker daemon and the device agent again, and the appliance returns to direct connections. Your NO_PROXY list is kept for a later re-enable.

Edge Devices

Everything above applies equally to edge devices set up with the device setup tool (ironflock-init). It takes the same proxy flags and configures itself the same way — pass the proxy when you run it, and it routes its downloads (package manager, Docker installation, agent download) and the Docker daemon through the proxy for you:


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

The bootstrap script that downloads the setup tool runs before it, so give that step the proxy too — export it in the shell first so its download succeeds:


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

If the device pulls app images from a local appliance app store rather than the cloud, add that registry’s host with --no-proxy so those pulls stay on the local network.

On Windows devices the agent runs as a Windows service. Pass the proxy to the service installer — it covers the platform connection and the agent’s self-updates:


reagent.exe service install -config path\to\config.flock -proxy "http://proxy.example.com:3128"

Which hosts bypass the proxy

NO_PROXY matches on the host name a client dials, never on the address that name resolves to. An appliance the device reaches by name — any appliance in domain mode, see App UIs & HTTPS — must therefore be named explicitly, or the agent sends its connection to the local appliance out through the corporate proxy. Most proxies refuse to route back into the internal network, so the device never comes online.

The installer works this out from the device’s own .flock. Alongside localhost and 127.0.0.1 it adds the appliance domain — in both the bare and the leading-dot spelling — and any plain-HTTP registry host the device is configured for. Cloud devices get nothing beyond the two loopback entries, because their endpoints are public and do need the proxy.

Anything else your site needs goes in -no-proxy, the counterpart to ironflock-init’s flag:


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"

Changing the settings later

The result is written to %ProgramData%\IronFlock\Reagent\proxy.env, and that file is authoritative from then on:


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

Edit it and re-run reagent.exe service install to apply the change. A later install never overwrites the file, and service uninstall keeps the agent directory — so your settings survive the uninstall/install cycle that reinstalling the service requires. Pass -force-proxy to deliberately replace the file from the flags instead.

Delete an entry if this site reaches the appliance through the proxy. Both deployments are real: an appliance on the same plant LAN is reached directly, while a centrally hosted one may only be reachable via the corporate proxy. The installer cannot tell them apart, so it writes the hosts out literally — remove the ones that do not apply to your network.

Docker is configured separately

Docker Desktop reads neither proxy.env nor the service environment. Image pulls are made by the Docker daemon, which has its own settings under Settings → Resources → Proxies, including its own bypass list — and that list needs the appliance host as well. A proxy corrected on the agent side does not fix docker pull.

Linux devices

ironflock-init takes --no-proxy directly, so the appliance can be named at setup time:


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

It writes a systemd drop-in at /etc/systemd/system/reagent.service.d/http-proxy.conf. Do not edit that file to adjust the settings afterwards — the setup tool rewrites it. Use systemctl edit reagent instead, which creates an override.conf that systemd applies after the installer’s drop-in and that IronFlock never touches:


sudo systemctl edit reagent


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


sudo systemctl restart reagent

TLS-Intercepting Proxies (Corporate CA)

Many corporate proxies inspect HTTPS traffic by re-signing it with a company certificate authority (CA). For these, configuring the proxy is necessary but not sufficient — the appliance host must also trust that CA, or every cloud connection (image pulls, license validation, the management uplink) is rejected.

This is about the appliance trusting your CA — not about serving HTTPS to browsers. Here you make the appliance’s outbound connections to the cloud succeed through a TLS-intercepting proxy. Serving app web UIs to browsers on your network is the opposite direction — see App UIs & HTTPS.

Install the CA once, in the host’s system trust store. The appliance mounts that trust store into all of its containers, so Docker and every IronFlock service pick up the CA — there is nothing to configure per container or per service. Because the containers read it at startup, restart the stack after adding or changing the CA (step 3 below).

1. Obtain the corporate CA

Ask your network team for the proxy’s “SSL inspection” / “TLS interception” root CA — the same certificate already deployed to managed corporate machines — as a .crt file. That’s the cleanest source.

Install the issuing CA, not a single host’s certificate. The common mistake is to save the proxy’s re-signed certificate for one hostname (e.g. only instance-registry.ironflock.com). That makes only that host work and leaves every other cloud host failing. You need the CA that signs those certificates.

If you can’t get the file directly but the proxy presents its full chain, you can extract the CA from the wire — replace <PROXY_HOST>:<PROXY_PORT> with your proxy:


# Capture the chain, one PEM per cert. c1 is the per-host leaf (skip it);
# c2..cN are the corporate CA chain to trust.
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}'
 
# Optional — inspect what came back:
for f in /tmp/proxy-c*.pem; do echo "== $f =="; openssl x509 -in "$f" -noout -subject -issuer; done

2. Install it and rebuild the trust store

If your IT team gave you the .crt directly:


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

If you extracted it from the chain above, trust every cert except the 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. Verify

Every IronFlock cloud host must now validate through the proxy — an HTTP status, not a TLS error:


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

A code like 200, 401 or 404 for all five means the CA is correct. Then restart the stack so the services pick it up (or re-run the installer):


sudo systemctl restart ironflock.service

Remote Access to Device User Interfaces

IronFlock lets you open a user interface that runs on an edge device or machine — a machine HMI, a PLC page, an on-device configuration or dashboard screen — directly inside IronFlock, from anywhere. This is a key enabler for remote service and support: an engineer can reach a machine’s interface without being on-site or on the local network. Access is always mediated and guarded by the IronFlock privilege system, so only authorised users reach a given device.

This remote-access tunnel is built on frp (Fast Reverse Proxy), a mature, widely used open-source technology. IronFlock uses it solely to provide the device-interface access described above.

Why a corporate proxy can get in the way

frp has powerful network-traversal capabilities, and for that reason antivirus and proxy security products often flag it generically as riskware — even though, as an open-source component with a long track record, it is safe and is used here only for the sanctioned remote-access feature. When that happens, the proxy blocks the download of the IronFlock component that contains frp.

This does not break your appliance: the remote-access tunnel is an optional feature, so if that component is blocked the platform installs and runs normally and simply operates without device-interface access. In the dashboard, a device’s remote-access controls then indicate that remote access is not available on this appliance.

What corporate IT needs to allow

If your organisation wants to benefit from IronFlock’s remote-service features, the IronFlock component containing frp must be allowed to download through the corporate proxy. Ask your network/security team for two specific things:

A scanning exception for image downloads from instance-registry.ironflock.com, so the generic riskware verdict doesn’t block the tunnel component. This is narrower than excluding all IronFlock traffic from TLS inspection — the rest of the appliance’s traffic can stay inspected.
Recording the detection as a known false positive. frp is a widely used open-source reverse proxy; IronFlock uses it only for the access-controlled remote-access feature described above.

The same IronFlock endpoints already listed for the appliance apply — see Firewall Configuration; this is about not scanning/blocking that traffic, on top of merely routing it.

Once frp is allowed through, just re-run the update — the feature turns on automatically as soon as the download succeeds, with no other change:


sudo ironflock-update

Running without remote access

If you don’t need device-interface access — or want a clean install while the proxy exception is arranged — you can disable the tunnel explicitly. Everything else installs as normal:


# at install time, appended to the install command
... | sudo bash -s -- <your-instance-key> --no-tunnel
 
# or on an already-installed appliance
sudo ironflock-update --no-tunnel

The choice is remembered across updates. Re-enable it later (once frp is allowed) with --tunnel:


sudo ironflock-update --tunnel

Troubleshooting

The install stops at “Logging in to instance-registry.ironflock.com” with a Client.Timeout error. The Docker daemon can’t reach the registry. Re-run the installer and pass your proxy with --http-proxy / --https-proxy, as shown above.

Login still fails after configuring the proxy. Your proxy most likely intercepts TLS. Install the corporate CA as described in TLS-Intercepting Proxies, then re-run.

Check that the Docker daemon sees the proxy:


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

If docker login succeeds on its own, the appliance install will get past the failing step.

A single component fails to download while everything else installs fine. This is usually the frp-based remote-access component being blocked by your proxy or antivirus as riskware. The install still completes — only device-interface access is unavailable. To enable it, have your proxy team allow that traffic as described in Remote Access to Device User Interfaces, then re-run ironflock-update. To install deliberately without it, pass --no-tunnel.

Updates

Once an appliance is installed behind a proxy, its proxy settings are remembered in /opt/ironflock/.env and re-applied on every update. Both manual updates and automatic background updates continue to work through the proxy with no extra action — see Maintenance in the Appliance guide. To point the appliance at a different proxy — or take it off the proxy entirely — see Changing or Removing the Proxy Later.

If remote access to device interfaces was blocked at install time, every update automatically retries it — so once your proxy allows frp, the next update turns the feature on with no extra steps.