Your Cable Modem Picked 2 AM to Have a Bad Day
You know the pattern. The backup job kicks off at 2 AM, the cable modem hiccups for four minutes because your ISP decided that was a fine time for maintenance, and you wake up to a failed job and a Slack alert nobody read. Or it happens during the day: someone starts a 90GB game download and your video call turns into a slideshow, because one WAN link is carrying every single packet in the house.
A single internet connection is a single point of failure, and homelabs love pretending that doesn’t matter until it does. The fix is two WAN links (cable plus LTE, fiber plus DSL, whatever you can get into the building) and an OPNsense box that knows how to use both. That’s two separate problems, though, and treating them as one is how people give up halfway through:
- Failover and load balancing. If a link dies, traffic needs to move to the other one without you touching anything. If both links are healthy, you might want to spread load across them instead of leaving one idle.
- Policy-based routing. Not everything should share the same fate. Your VoIP box probably wants the low-latency line always, the kid’s Xbox can go out whatever link has more headroom, and the rest of the house can just use whatever’s up.
OPNsense solves both with the same building block: gateway groups. This walkthrough builds a working two-WAN setup on OPNsense 26.7 (“Xenial Xenops”), the current stable release as of this writing, and the menu paths below match that version. If you’re running an older release the concepts hold, but double check the menu names before you go clicking.
If you’re still deciding between OPNsense and pfSense for this box, that’s a different article. This one assumes you’ve already made the call and just need the WAN links to behave.
What You Need Before You Touch a Single Setting
Both WAN interfaces need to already be configured and getting an address, whether that’s DHCP from your ISP’s modem, a static IP, or a cellular WAN via USB modem or LTE/5G gateway in bridge mode. If Interfaces > [WAN2] shows a valid IP and OPNsense auto-created a gateway for it, you’re ready. If it doesn’t, fix that first. Multi-WAN doesn’t help you if the second WAN doesn’t actually work.
Step 1: Give Each Gateway Something to Watch
OPNsense decides whether a gateway is alive by pinging a monitor IP with dpinger, its gateway monitoring daemon. Each gateway needs its own monitor IP, and it needs to be a real one, because “gateway down” decisions drive everything downstream.
Go to System ‣ Gateways ‣ Configuration, click the pencil next to your primary WAN gateway, and check:
Disable Gateway Monitoring: uncheckedMonitor IP: 8.8.8.8Mark Gateway as Down: uncheckedThen repeat for the second gateway with a different monitor IP, for example 8.8.4.4. Using the same monitor IP on both gateways is a classic gotcha: if that one IP goes unreachable for reasons that have nothing to do with either of your links, OPNsense marks both gateways down at once and you’ve achieved zero WANs instead of two.
Each gateway’s edit page also has an advanced section worth knowing about, even if you leave it alone on day one:
- Latency thresholds (low/high, in milliseconds)
- Packet Loss thresholds (low/high, in percent)
- Probe Interval (how often
dpingersends a probe, in seconds) - Down (seconds of failed probes before the alarm fires)
- Avg Delay Replies Qty and Avg Packet Loss Probes Qty (how many samples get averaged)
- Lost Probe Delay (delay, in probe samples, before loss counts)
- Weight (used later for unequal load balancing)
If one of your links is LTE or 5G, loosen the latency and packet loss thresholds on that gateway specifically. Cellular backhaul routinely runs higher and jitterier latency than a wired line, and if you leave conservative wired-link thresholds in place, dpinger will flap that gateway up and down all day and your failover group will thrash along with it. There’s no universal number to hand you here: watch the gateway’s real-world latency in System ‣ Gateways ‣ Configuration for a day, then set thresholds above what you actually see in normal operation.
Step 2: Build the Gateway Group (This Is the Failover Part)
Gateway groups are where OPNsense decides which gateway (or gateways) get traffic, and in what order. Go to System ‣ Gateways ‣ Group and add a new group:
Group Name: WANGWGROUPGateway Priority: WAN_GW / Tier 1 WAN2_GW / Tier 2Trigger Level: Packet LossDescription: Failover GroupTier 1 is preferred. Tier 2 only gets traffic when every gateway in Tier 1 trips the trigger you picked. The trigger level options are:
- Member Down: fires at 100% packet loss to the monitor IP. The blunt option.
- Packet Loss: fires when loss crosses the threshold you set on that gateway.
- High Latency: fires when latency crosses the threshold you set on that gateway.
- Packet Loss or High Latency: fires on either condition. This is the one most homelabs actually want, because a half-dead link that’s up but garbage is worse than one that’s cleanly down.
Separately, each gateway has a numeric Priority from 1 (most important) to 255 (least important), plus an Upstream Gateway flag that marks it as a default-gateway candidate. For a simple two-WAN failover, set your main ISP’s priority lower (more preferred) than the metered one, for example 10 for the primary and 20 for the backup. Gateway groups handle the traffic-steering logic; priority and upstream handle which gateway OPNsense treats as the system default outside of policy routing.
One more setting worth understanding before you rely on this: each gateway has its own Failover States checkbox, found in that gateway’s advanced settings under System ‣ Gateways ‣ Configuration, not in the gateway group. Checking it kills all firewall states on that gateway the moment a failover happens, forcing every connection to re-establish on the new gateway immediately. If your backup link is a metered LTE plan, you want this on: a lingering state that keeps happily forwarding traffic to a dead primary gateway does you no good, and a state that fails back slowly onto a per-gigabyte LTE plan can get expensive fast.
Step 3: Point DNS at the Right Door
Multi-WAN setups get weird with DNS if you don’t handle it explicitly. Go to System ‣ Settings ‣ General and bind each configured DNS server to a specific gateway instead of leaving them unbound:
DNS Servers8.8.8.8 -> WAN_GW8.8.4.4 -> WAN2_GWWithout this, OPNsense can try to resolve a query out a WAN that just failed, and your “the internet is down” troubleshooting session turns into “actually DNS is down, which looks identical from a browser.”
Step 4: Turn the Gateway Group Loose With a Firewall Rule
This is the part that actually makes failover (or load balancing) happen for real traffic, and it’s the same mechanism you’ll reuse for policy routing later. Gateway groups don’t do anything until a firewall rule tells traffic to use one.
Go to Firewall ‣ Rules, open your interface (LAN, for most homelabs), and edit the default allow rule. Under Gateway, change the selection from the default system routing to WANGWGROUP. Save and apply.
That single dropdown is policy-based routing. It overrides OPNsense’s normal routing table for any traffic that matches this rule, and sends it out whichever gateway (or gateway group) you picked instead. Powerful, and also exactly the kind of powerful that bites you if you don’t account for what else matches “any.”
Step 5: Stop the Firewall From Routing Itself Into a Ditch
Step 4 has a catch: the default LAN rule usually matches “any” destination, which includes traffic headed to the firewall itself and to other internal networks, like a VPN tunnel or a second VLAN. Policy routing doesn’t know the difference between “this packet is going to Netflix” and “this packet is going to the firewall’s own DNS resolver.” It just applies the rule.
Fix it by adding a rule above the policy-routed one that carves out traffic to the firewall itself, with no gateway set so it uses normal system routing:
Action: PassInterface: LANTCP/IP Version: IPv4Protocol: TCP/UDPSource: anyDestination: Single host or NetworkDestination address: 192.168.1.1/32Destination port: DNS (53)Gateway: (default / none)Category: DNSSame idea applies to anything else that shouldn’t go out a WAN: site-to-site VPN subnets, other internal VLANs, management traffic. Build an alias for your internal RFC1918 ranges, add a plain pass rule for that alias above the gateway-group rule with no gateway set, and internal traffic stops taking scenic detours through your ISP.
Load Balancing Instead of Just Failing Over
If both WAN links are healthy and you’d rather spread load than have one sit idle, the change is one field: go back to System ‣ Gateways ‣ Group and put both gateways in the same Tier. Same configuration, different tier assignment, completely different behavior: OPNsense now balances connections across both instead of preferring one.
Two settings matter once you do this, both under Firewall ‣ Settings ‣ Advanced:
- Shared forwarding must be disabled whenever two gateways share a tier. This is a hard requirement in the docs, not a suggestion: skip it and load balancing across same-tier gateways doesn’t work correctly.
- Sticky Connections, if you turn it on, keeps each client pinned to the same gateway for the duration of a session instead of splitting new connections to the same site across both links. Some sites get cranky when your source IP changes mid-session (payment processors, some streaming logins), and sticky connections fixes that without giving up load balancing for everything else.
If your two links aren’t the same speed, and they usually aren’t, set a Weight on each gateway under the advanced section of its configuration page. A 10Mbps line paired with a 20Mbps line at weight 1 and weight 2 respectively sends the second gateway twice the connections of the first. Equal weight on unequal lines just means your faster line finishes early and your slower one becomes the new bottleneck, which defeats the point.
Combining Both: Balance Two, Fail Over to a Third
OPNsense gives you five tiers total, and each tier can hold more than one gateway. That means you can balance across your two good links in Tier 1 and drop a third, worse link (LTE, a neighbor’s guest network, whatever emergency backup you’ve got) into Tier 2 as pure failover. Set it up exactly like the sections above: two gateways at Tier 1 for balancing, one gateway at Tier 2 that only wakes up when both Tier 1 links trip the trigger. It’s not complicated once you’ve built the failover group and the balance group separately; combining them is just tier math.
Now Send Specific Traffic Out a Specific WAN
This is the second half of the combo, and it’s the same mechanism as Step 4, just aimed at fewer hosts. You don’t have to send your whole LAN through the gateway group. You can point one VLAN, one host, or one alias at a single named gateway (skipping the group’s failover logic entirely) or at the group (keeping failover for that traffic specifically).
Say you’ve got a VoIP ATA at 192.168.30.50 that should always prefer your primary fiber line and never wander onto LTE, even during a brief failover blip elsewhere. Build a rule above your general LAN rule:
Action: PassInterface: LANSource: 192.168.30.50/32Destination: anyGateway: WAN_GWBecause firewall rules process top to bottom and stop at the first match (when the rule is set to quick, which is the default), this rule catches the VoIP box’s traffic before it ever reaches your general gateway-group rule further down. Everything else on the LAN still hits the group rule and gets the failover/balancing behavior you configured. Want the kid’s game console to load-balance across both consumer links instead of hogging one? Same pattern, alias for the console’s IP or its own VLAN, gateway set to your balancing group, rule placed above the catch-all.
This is why gateway groups and firewall rules are separate concepts in OPNsense instead of one wizard: the group defines the pool of possible paths and how they behave under failure, and the rule decides which traffic is allowed to use that pool. Mix and match as many rules as you have use cases, from top (most specific) to bottom (the general catch-all).
Verify It Before You Trust It at 2 AM
Don’t configure this and walk away hoping. Test it while you’re awake and paying attention.
For failover, physically unplug (or disable) your primary WAN interface and watch the gateway monitor trip in the OPNsense dashboard. Keep an SSH or RDP session open to something external during the test: if Failover States is working, that session drops and has to reconnect on the backup gateway. Plug the primary back in and confirm the reverse happens on failback. If something doesn’t fail over cleanly, check gateway priorities, confirm default gateway switching is behaving as expected, and check Firewall ‣ Diagnostics ‣ States to see which gateway your states are actually attached to.
For policy routing, confirm from a client machine that traffic is actually leaving the WAN link you think it is:
curl ifconfig.meRun that from the policy-routed host and compare the returned IP against each WAN’s actual public address. If your VoIP box’s rule is working, that command returns your primary WAN’s IP even while the rest of the LAN is balancing across both links. A traceroute to an external host from the same machine is a decent second check: the first hop should be the gateway you expect, not the other one.
Common Questions
Does OPNsense multi-WAN combine bandwidth for a single download?
No. Gateway group load balancing spreads separate connections across links; it doesn’t split one download’s packets across two WANs at once. A single large file transfer rides one gateway for its whole session, capped at that link’s speed. To use both links’ combined bandwidth, you need multiple simultaneous connections, which is normal for browsing but not for one big file.
Do I need a business-class internet plan for OPNsense multi-WAN failover?
No. Multi-WAN works with consumer cable, DSL, fiber, or an LTE/5G modem in bridge mode, as long as each link hands OPNsense a real routable IP on its own interface. Business plans mainly buy you static IPs and better SLAs, not a requirement for the feature itself. Plenty of homelabs run this on two residential connections.
Does CGNAT break OPNsense multi-WAN or policy routing?
Failover and policy routing both still work under CGNAT, because OPNsense only needs an address on its WAN interface to route through, not a public one. What breaks is inbound access: port forwards and self-hosted services reachable from outside won’t work on a CGNAT link no matter how your gateway groups are configured, since the carrier owns the public IP.
Can I use gateway groups and policy routing on IPv6 too?
Yes, gateway groups and policy-based routing rules both support IPv6 as a separate address family from IPv4 in the same rule set. Configure IPv6 monitor IPs and gateways the same way as IPv4, then set the TCP/IP Version field on your firewall rules to match. Mixed dual-stack failover needs both IPv4 and IPv6 gateways monitored and grouped independently; one doesn’t cover the other.
Will disabling shared forwarding break single-WAN setups?
No, shared forwarding only matters once you put two or more gateways in the same tier for load balancing. A single WAN, or a pure failover setup where every gateway sits in its own tier, is unaffected either way. Only touch that setting when you’ve specifically configured same-tier balancing and traffic isn’t splitting the way you expect.
