Why The Omada APs Needed a Relay, and How We Removed It

This article explains the Omada controller problem in very simple language.

If you know nothing about networks, that is fine. Think of this as a story about two little Wi-Fi boxes trying to find their boss.

The Simple Story

Imagine:

• the APs are little workers
• the Omada controller is the boss
• the network is the neighborhood
• an IP address is a house number

The workers need to know which house the boss lives in.

For a while, they thought the boss lived at:

192.168.2.108

Then the boss moved to a new house:

192.168.6.116

But the workers did not learn the new address.

So they kept walking to the old house and knocking on the old door.

That is why they dropped off the controller.

What The Relay Was

A relay is like putting a helper at the old house.

The helper stands at 192.168.2.108 and says:

“The boss does not live here anymore. I will carry your messages to the new house.”

So the APs could still talk to the controller, even though they were going to the wrong place first.

This kept things working for a while, but it was not the clean final setup.

Why That Was Not The Best Fix

The relay was a band-aid.

It meant:

• the APs were still using the old address
• the old machine still mattered
• if the relay stopped, the APs got confused again

That is not a real move. That is just mail forwarding.

The Two Real Problems

There were actually two separate problems.

Problem 1: The APs still wanted the old controller address

The APs were still trying to reach:

192.168.2.108

So even though the new controller was healthy on Ubuntu, the APs were not talking to it directly.

Problem 2: The controller was telling devices the wrong address

Inside Omada, the controller was advertising this address:

172.17.0.3

That is not a normal house on your real network.

That is Docker’s private inside-the-container address.

It is like the boss telling everyone:

“Come visit me in my secret room inside a cardboard box in the garage.”

The APs cannot use that address properly from the real network.

So even if they found the controller once, the controller could still hand back the wrong return address.

What Docker Bridge Networking Means Here

Docker puts containers on a little pretend network of their own.

Inside that pretend network, the controller had:

172.17.0.3

But on the real network, the Ubuntu server had:

192.168.6.116

Your APs live on the real network, not inside Docker’s private pretend network.

So the controller must tell them the real address:

192.168.6.116

not the container address.

What DHCP Option 138 Means

DHCP is the part of the network that tells devices useful things when they join.

Usually it says things like:

• here is your IP address
• here is your gateway
• here is your DNS server

It can also say:

• here is where your Omada controller lives

That special message is DHCP option 138.

So when an AP wakes up and asks, “Where is my boss?”, DHCP option 138 can answer:

192.168.6.116

That helps the AP find the controller without needing the relay.

What We Changed

We changed two important things.

1. We fixed the controller’s advertised address

We changed Omada so it now reports:

192.168.6.116

instead of:

172.17.0.3

That means the controller now gives out a real reachable address.

2. We added DHCP option 138 on the AP subnet

On pfSense, for the 192.168.2.x AP network, we added DHCP option 138 pointing to:

192.168.6.116

That means when the APs renew DHCP or reboot, they can learn the new controller address directly.

What The Clean End State Looks Like

The clean setup is:

• controller runs on Ubuntu
• controller tells devices to use 192.168.6.116
• DHCP also tells APs to use 192.168.6.116
• no relay is needed
• the old Windows host at 192.168.2.108 can stop pretending to be the controller

That is the proper fix.

Why The APs Might Not Reappear Instantly

Even after the fix, the APs may not reconnect immediately.

That is because they may still be holding old information in memory.

They often need one of these:

• a DHCP renew
• a reboot
• a short wait while they retry discovery

So the final step is usually to bounce the APs once and let them come back up.

Tiny Summary

The APs were not broken.

They were just confused.

They had the wrong boss address, and the boss was also giving out the wrong return address.

The relay helped for a while by forwarding messages from the old address to the new one.

The proper fix was:

1. make the controller advertise the real Ubuntu LAN IP
2. teach the APs the real controller IP through DHCP option 138
3. stop depending on the old relay

That is how you move from “it works with a helper” to “it works properly by itself.”