Not every device fleet lives on a network with open internet access. Hospitals isolate medical devices behind air gaps to meet regulatory requirements. Mining operations run equipment in underground networks with a single controlled uplink. Ships at sea, factory floors with legacy security policies—all share a common constraint: the devices that need software updates cannot reach the cloud directly.
The conventional OTA architecture assumes devices initiate outbound connections to a management server. When network topology forbids this, organizations often fall back to manual update processes: USB drives, technician visits, scheduled maintenance windows. These workarounds introduce delay, human error, and audit complexity—exactly the problems OTA was meant to solve.
Mender Gateway exists for these environments. It is a Mender-aware HTTPS forwarder that bridges segregated device networks with hosted Mender — terminating Mender Client connections locally, relaying them upstream, and caching artifacts at the boundary so the same update doesn’t traverse the upstream link twice. The gateway is a Mender Enterprise feature; details are in the Mender Gateway documentation. This guide covers how Mender Gateway works, its standard deployment patterns, and what to do when your infrastructure doesn’t match the textbook scenarios.
This piece assumes one specific constraint: the network boundary permits a single controlled upstream link from a gateway host to the Mender Server. If that link is also forbidden — fully air-gapped environments where no system inside the boundary may reach the outside — the Trusted Intermediary pattern covers operator-mediated bridging with portable media or data diodes.
The segregated network problem
A segregated network is any network architecture where devices cannot establish direct outbound connections to the internet. The segregation may be physical (air gap), logical (firewall rules), or operational (policy-driven isolation). Common examples:
| Environment | Segregation Driver | Typical Constraints |
|---|---|---|
| Healthcare | HIPAA, medical device regulations | Medical devices on isolated VLANs, strict change control |
| Industrial/Mining | Operational safety, remote locations | Underground networks, satellite uplinks, bandwidth limits |
| Maritime | Connectivity cost, availability | Satellite bandwidth measured in kbps, intermittent links |
| Defense/Government | Classification requirements | Air-gapped networks with formalized data transfer procedures |
In each case, the devices requiring updates—infusion pumps, excavator control units, monitoring systems—sit on networks that cannot reach hosted.mender.io directly. Yet these are often the devices where reliable, auditable software updates matter most.
How Mender Gateway bridges the gap
Mender Gateway terminates Mender Client connections from isolated devices and relays them upstream to hosted Mender (or an on-premise Mender server), with local caching of artifacts. It is purpose-built for the Mender protocol — it is not a generic HTTP proxy and is not configured to forward arbitrary traffic. The gateway sits at the network boundary: one interface on the segregated network, one interface with upstream connectivity. In network architecture terms, the gateway machine is an exposed host — the single, deliberately permitted bridge between the segregated network and the outside, with all other paths blocked by firewall, VLAN, or physical separation.
Devices on the segregated network connect to the gateway as if it were the Mender server. The gateway runs on an exposed host at the network boundary and holds the only upstream link. The same topology applies whether the gateway is delivered as a Docker container or as a native systemd service.
From the device’s perspective, the gateway is the Mender server. Devices are configured to connect to the gateway’s address (e.g., https://gateway.local) rather than directly to hosted Mender. The gateway authenticates with hosted Mender on behalf of the devices, retrieves artifacts, and serves them locally.
Key capabilities
Artifact caching: When multiple devices need the same update, the gateway downloads the artifact once and serves it to all local devices. For bandwidth-constrained environments (satellite links, metered connections), this can reduce upstream data transfer by orders of magnitude.
Phase 1 — the first device to request an artifact triggers an upstream fetch; the gateway caches the result. Phase 2 — a second device requesting the same artifact is served from the local cache, with no upstream traffic. The asymmetry between the two phases is what turns into bandwidth savings as fleet size grows.
mTLS device authorization: The gateway can use mutual TLS to authenticate devices based on certificates. Devices with trusted certificates are automatically authorized without requiring individual enrollment through the Mender UI. This simplifies fleet provisioning in environments where devices may not have interactive setup.
Protocol termination: The gateway handles TLS termination for the segregated network. Devices can connect over HTTPS to the gateway using a locally-trusted certificate, while the gateway maintains its own secure connection upstream. This allows certificate management to be scoped to the local environment.
Standard deployment patterns
Mender Gateway is distributed primarily as a Docker container image. The expected topology is a single exposed host on the segregated network’s boundary — a mini-PC, a NUC-class industrial edge box, a dedicated server, or any machine with one interface inside the segregated network and one with upstream connectivity. The cloud is, by definition, out of scope: the gateway has to be reachable from the devices, which means it has to live where they live.
Container deployment: Docker on an exposed host
The recommended deployment is a single docker run (or docker-compose) on a Linux exposed host, pulling registry.mender.io/mendersoftware/mender-gateway. Configuration is via environment variables and mounted certificates. Image versions are pinned and updated via standard container image flows. Capacity scales with host hardware — CPU and disk for the artifact cache — not with orchestration complexity.
This works for fleets of a handful of devices and for fleets in the thousands. Most segregated-network deployments should start here.
When to use: An exposed host that runs Docker exists or can be provisioned. This is the default answer.
Native systemd service on Linux
For Linux exposed hosts where a container runtime is undesirable — a hardened single-purpose appliance, a Yocto-based device that already runs the Mender Client, an environment with strict change-control on what binaries the host runs — Mender Gateway can be installed as a native systemd service. The functionality is identical; the trade-off is purely about the runtime environment on the host.
When to use: Linux exposed hosts where Docker is undesirable, or where the gateway is co-located with other Mender-managed software updated via the Mender Client itself.
The infrastructure reality check
These two patterns cover most scenarios. But not every site has a Linux exposed host available:
- No spare Linux hardware, but there’s a Windows server already designated as the boundary host
- Legacy infrastructure that can’t easily accommodate new Linux systems
- Operational constraints that mandate using existing approved platforms
The question becomes: what do you do when the exposed host you have isn’t Linux?
When the exposed host runs Windows: Hybrid deployment
Because the gateway is a container, it runs anywhere a compatible container runtime runs. That property is what makes the recommended container deployment work on whatever Linux exposed host the site already has — and it is also what makes Windows viable when no Linux host is available.
Docker Desktop on Windows can run Linux containers through WSL2 (Windows Subsystem for Linux). The Mender Gateway container, being a Linux container, runs inside this environment with full functionality. From the container’s perspective, it’s running on Linux. From the organization’s perspective, it’s running on their existing Windows server infrastructure — the same exposed-host role that a Linux box would otherwise fill.
The hybrid deployment model
A hybrid deployment places Mender Gateway in a container on an on-premise exposed host — typically a Windows server — where it relays Mender traffic between the segregated network and the upstream Mender Server. This combines characteristics of both standard patterns:
- Same gateway, same
docker runflow as the recommended Linux container path - Same exposed-host topology — the gateway sits at the segregated network’s boundary
- The only difference: the host OS is Windows rather than Linux
The gateway container runs inside Docker Desktop on a Windows host. From the container’s perspective it is on Linux; from the organization’s perspective it is on existing Windows infrastructure. Devices on the segregated network reach the container through the Windows host’s port forwarding.
Technical implementation
The deployment uses standard Docker commands. On Windows, after installing Docker Desktop with WSL2 backend:
1. Authenticate with Mender’s container registry:
docker login registry.mender.io
2. Pull the gateway image:
docker pull registry.mender.io/mendersoftware/mender-gateway:2.0.0
3. Prepare certificates:
The gateway needs a TLS certificate that devices will trust. For segregated networks, this is typically a self-signed certificate or one issued by an internal CA. The certificate and private key must be accessible to the container.
4. Run the gateway container:
docker run \
-p 443:443 \
-e HTTPS_ENABLED="true" \
-e HTTPS_LISTEN=":443" \
-e HTTPS_SERVER_CERTIFICATE="/etc/mender/certs/server.crt" \
-e HTTPS_SERVER_KEY="/etc/mender/certs/server.key" \
-e UPSTREAM_SERVER_URL="https://hosted.mender.io" \
-v /path/to/certs/cert.crt:/etc/mender/certs/server.crt \
-v /path/to/certs/private.key:/etc/mender/certs/server.key \
registry.mender.io/mendersoftware/mender-gateway:2.0.0 --log-level debug
The volume mounts (-v) map host filesystem paths to paths inside the Linux container. From a WSL2 terminal on Windows, use Linux-style paths (or the /mnt/c/... mount point for Windows drives). The gateway binds to port 443 and forwards Mender Client traffic upstream to hosted Mender.
5. Configure devices to use the gateway:
Devices on the segregated network need:
- DNS or
/etc/hostsentry resolving the gateway hostname to the Windows server’s IP on the segregated network - The gateway’s TLS certificate (or CA certificate) in their trust store
- Mender client configuration pointing to the gateway URL instead of hosted Mender
Reaching the container from the segregated network (WSL2 networking)
Docker Desktop on Windows runs the gateway container inside a WSL2 virtual machine, and that adds a layer between the published port and the host’s segregated-network interface. Two WSL2 networking modes apply, with different consequences for LAN reachability.
Default (NAT) mode — the legacy default. A -p 443:443 publish makes the container reachable on the Windows host’s localhost, but not from devices on the LAN. Reaching it from the segregated network requires both a Windows Firewall inbound rule on TCP/443 and a netsh interface portproxy rule forwarding the host’s LAN-facing address to the WSL2 VM’s IP:
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=443 connectaddress=$(wsl hostname -I) connectport=443
The WSL2 VM’s IP changes at every Windows reboot, so the portproxy rule has to be refreshed at startup — typically via a scheduled task.
Mirrored networking mode (Windows 11 22H2 and later, WSL 2.0.4+). WSL2 shares the Windows host’s physical network interfaces, and a published container port lands directly on the host’s segregated-network IP — no portproxy needed. Enable it under [wsl2] in %UserProfile%\.wslconfig:
[wsl2]
networkingMode=mirrored
Then wsl --shutdown and let WSL restart. Inbound traffic also requires a Hyper-V firewall rule, which is distinct from the standard Windows Firewall:
New-NetFirewallHyperVRule -Name "MenderGateway443" -Direction Inbound -VMCreatorId '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' -Protocol TCP -LocalPorts 443
Note: the GUID {40E0AC32-46A5-438A-A0B2-2B479E8F2E90} is Microsoft’s fixed well-known identifier for WSL. Using it here means “apply this rule to traffic going to/from WSL VMs”, which is what you want, since Docker Desktop’s gateway container lives inside the WSL2 VM.
Mirrored mode is the cleaner setup, but is still maturing; port-binding conflicts between WSL2’s mirrored stack and Docker Desktop’s vpnkit have been reported in some Docker Desktop and WSL version combinations. For a production deployment, validate the chosen mode against the exact Windows, Docker Desktop, and WSL versions on the target host before committing.
Network and TLS configuration
The segregated network devices must be able to resolve the gateway’s hostname and trust its certificate.
DNS/hosts configuration on devices (example):
192.168.8.103 gateway.docker.mender.io
TLS trust: Devices must trust the gateway’s certificate. Options include:
- Self-signed certificate: Generate a certificate for the gateway, distribute the certificate (or CA) to devices during provisioning
- Internal CA: Issue a certificate from your organization’s internal CA, which devices already trust
- HTTP (unencrypted): For physically secured segregated networks where encryption overhead is unwarranted, the gateway can run without TLS—though this should be a deliberate security decision, not a shortcut
The choice depends on the threat model of the segregated network. An air-gapped network inside a physically secure facility has different requirements than a logically segregated VLAN in a shared data center.
Professional services: The appropriate boundary
Hybrid deployments — Windows + Docker Desktop, the WSL2 networking work above, custom certificate authorities — sit outside Mender’s continuously-tested configuration matrix. Windows version, Docker Desktop release, WSL networking mode, site firewalls, and certificate infrastructure all vary too widely to generalize. These deployments are delivered as professional-services engagements: Mender’s engineering team designs and implements the architecture for your environment, documents it for your ops team, and remains the entry point for support on the configuration they built. Issues should be reproduced on a standard Linux deployment where possible, or routed through the team that delivered your hybrid setup.
Choosing the right deployment pattern
| Factor | Docker on Linux | Native systemd | Hybrid (Windows) |
|---|---|---|---|
| Exposed host | Linux PC, server, edge box | Linux device, often Yocto-based | Windows server |
| Runtime | Docker / docker-compose | systemd | Docker Desktop + WSL2 |
| Fleet size | Handful to thousands | Small to medium | Varies |
| Maintenance | Standard container ops | Updated alongside the host | Custom procedures |
| Support model | Standard | Standard | Professional services |
| Artifact caching | Yes | Yes | Yes |
The decision tree:
- Is the exposed host a Linux machine that runs Docker? → Docker on Linux. This is the default and covers the large majority of segregated-network deployments.
- Is the exposed host a Linux machine where a container runtime is undesirable? → Native systemd service.
- Is the only available exposed host a Windows server? → Hybrid (Docker Desktop + WSL2), via professional services.
Combining Gateway with broader update strategy
Mender Gateway handles the transport problem—getting updates from hosted Mender to isolated devices. It doesn’t change what you can deploy.
Devices behind a gateway still benefit from:
- A/B rootfs updates with automatic rollback
- Application updates to the data partition using update modules
- Container updates via Docker or docker-compose modules
- Provides/depends for dependency management across components
A composable update strategy that separates OS, application, and container update domains works identically behind a gateway. The gateway is transparent to the update modules — they see the gateway as the Mender server.
Artifact caching becomes particularly valuable for large updates (rootfs images, container images) in bandwidth-constrained environments. A 500MB rootfs image downloaded once to the gateway, then distributed to 20 local devices, uses 500MB of upstream bandwidth instead of 10GB.
Conclusion
Segregated networks exist for legitimate reasons—regulatory compliance, security policy, operational constraints. The devices on these networks still need software updates, and “send a technician with a USB drive” doesn’t scale.
Mender Gateway solves the transport problem by terminating Mender Client connections from isolated devices, relaying them upstream to hosted Mender, and caching artifacts at the boundary. The expected deployment is straightforward: a Docker container on an exposed host at the segregated network’s boundary. A native systemd service is the alternative when a container runtime is unwanted.
For sites where the only available exposed host runs Windows, the same gateway container runs on Docker Desktop with WSL2. That variant is professional-services territory: custom engineering for your specific environment, with maintenance procedures you control.
If your infrastructure doesn’t fit the mold, that’s not a barrier. It’s a conversation.
Next steps
- Mender Gateway documentation — Configuration, deployment, and operational guidance for the gateway. (Mender Enterprise feature.)
- Trusted Intermediary Pattern: Managing Updates When Devices Can’t Reach the Server — The complementary pattern for fully air-gapped networks where no upstream link is permitted at all.
- Mutual TLS authentication — Reference for the certificate-based device authorization the gateway terminates.
- Need help with a custom deployment? Contact the Mender professional services team to discuss your specific requirements.