UniFi Gateway emulator

[amd989]

Hey all,

Like many of you I run UniFi APs and switches but use my own router (OPNSense in my case). The one thing that always bugged me was the missing gateway in the UniFi controller. No topology, no WAN stats, just a hole where a "UniFi Gateway" should be.

Thanks to the brilliant efforts of others before me, the inform protocol got reversed-engineered. Some work started to get a working emulator but nothing concrete materialized over the last ten years. Sadly, lots of abandoned projects.

A reddit post recently reminded me of this topic and after looking back and seeing nothing, I decided to take a stab at it.

I've been working on a small daemon that emulates a UGW3. It speaks the actual inform protocol (TNBU binary, AES encryption, the whole thing) so the controller genuinely thinks there's a USG on the network. You get interface stats, traffic counters, connected clients, DHCP leases, CPU/mem, latency, all showing up in the dashboard like a real gateway.

It currently runs on:

• Linux (Debian, Ubuntu, RHEL, etc.) - apt/dnf repos available
• FreeBSD / OPNSense / pfSense - pkg repo available
• OpenWRT - opkg repo available
• Docker - if you just want to throw it on whatever box
• There are also standalone binaries (x86_64, ARM64, ARMv7) if you don't want to mess with Python.

Setup is basically: install, point it at your controller's inform URL, adopt it like any other device, and run. The config file just maps your real interfaces (like eth0, br-lan, whatever) to the emulated USG ports.

It supports dnsmasq, ISC dhcpd, and KEA lease formats out of the box. Platform-specific stuff (ARP tables, routing, neighbors) is handled automatically based on your OS.

It is still a work in progress. I'm working on deeper API integrations for OPNSense and OpenWRT so it can pull richer data (per-device traffic from Netflow, manufacturer info from ARP, etc.) and eventually push config back from the controller to the router (DHCP reservations, port forwards, DNS overrides).

Repo: https://github.com/amd989/unifi-gateway

Would love for people to try it out and let me know what breaks. Issues and PRs welcome.


Disclaimer: I've used AI code assisting tools to get well ahead I would have done on my own, so if that doesn't rock your boat, just skip this one.

[nero355]

Why do you want the USG in your UniFi Controller while all USG models are declared EOL officially and should be avoided since about 1 year ago ?!

I have replaced mine with OPNsense and I don't really miss it to be honest :)



_{But then again pfSense/OPNsense or the USG or simply use my xDSL Modem/Router from DrayTek with GlassFiber too was something I considered a long time ago anyway so you could say I am a bit biased...}

[amd989]

Why do you want the USG in your UniFi Controller while all USG models are declared EOL officially and should be avoided since about 1 year ago ?!

The point of this app is to emulate a USG device backed by OPNSense, there is no real USG whether its EOL or not is not the point.

In other words, it is just a shim/facade. UniFi thinks OPNSense it's a USG, that's all. Now you can see OPNSense stats inside UniFi Controller. Something you couldn't before.

But you bring a valid point. I guess you could technically emulate the latest device, in the inform protocol, it is just a string identifier. I would just need to find out what that string is and maybe we could unlock more features within UniFi's controller.

I hope this clarifies it.

[meyergru]

Normally, I would suggest this thread for immediate deletion to the forum moderators, because in the last few weeks, there have been several attempts by first-time-posters to advertise tools with "flashy" names hosted on Github that do one thing or another - always coded with the help of Claude, BTW.

In almost all of those cases, the tools were from first-time-releasers on Github, too, so it became all too obvious what their real purpose was - or at least: could have been.

That being said, I know your are a real person (and also a fellow "arctic pole vault contributor") and I do not think this follows the same pattern, but (and this is a big BUT):

You should be aware that the alert level rises when anybody from outside augments OpnSense with external code that must be installed with high privileges and could - even if it currently poses no risk (not that I even bothered checking) - take over control of a security appliance like OpnSense.

I, for instance, would not point curl at any abitrary internet URL, fetch a script and let it execute on my OpnSense - even if I like the idea and could use it.

My suggestion for you would be to create an OpnSense plugin and try to create a PR for OpnSense. In that case, any further iteration could be controlled by trusted parties and more people would likely use your tool.

If Deciso finds your tool is not eligible for that approach, you should at least think about the following:

Both the Unifi inform API and the Deciso API to get the needed info from are open to use remotely. That access can be controlled to allow read-only access without a risk of OpnSense being modified by bad actors. Thus, you could as well create a docker container that runs independently and does not have to be integrated as executable code into OpnSense, thereby causing no risk at all.

[Monviech (Cedrik)]

We only accept plugin contributions which glue around an existing freebsd port packages.

It's better to offer something like this in an own repository.

I don't mind this being here to be honest, a user who uses the shell as root should know what they are doing (hopefully). I know not all do know the implications, I also like to run simple install scripts on linux after all. I hope for the best xD

We're never safe from supply chain attacks as the current npm thingy shows once more (and did multiple times in the past but nobody is learning :O)

[meyergru]

As I said, the same purpose can be had without any installation on OpnSense at all. So there is one big risk and it can be avoided.

P.S.: NPM and LZ (see: https://www.youtube.com/watch?v=aoag03mSuXQ) are at least controlled by some well-known contributors (even if they did not notice the attacks, but I doubt AI would have caught this, either).

I think there is a difference between well though-out attacks that went over months like with LZ and the thing we are witnessing now, which is offering some AI-generated tools that first seem to do something useful, but can be exploited later on, because they are not audited at all. There are discussions about the same thing in Proxmox, too:

https://forum.proxmox.com/threads/onboard-sata-controller-durchreichen-wo-finde-ich-ihn.181699/post-845202

[nero355]

there is no real USG whether its EOL or not is not the point.

There is a point if it's unsupported as of version x.y.z of the UniFi Controller and might not show any statistics at all because of that even tho it's not the actual device !! ;)

I would suggest emulating something recent like the https://eu.store.ui.com/eu/en/category/cloud-gateways-compact/products/ucg-ultra since it's very likely that it's going to be supported for a long time in the future.

[amd989]

Thanks for the thoughtful responses!

I apologize for coming in hot with "yet another AI generated tool" I suspected it would be rubbing a little in the wrong direction. Hence the disclaimer.
I understand, it bothers me too when I see it.

I, for instance, would not point curl at any abitrary internet URL, fetch a script and let it execute on my OpnSense - even if I like the idea and could use it.

You bring valid security concerns, I offered an easy setup script, but I should have also presented the manual way as well, maybe first. I'm trying to host my own pkg/apk/yum/opk/deb repo inside of GitHub pages so installing the GPG key is a requisite and that script takes care of it. Maybe does not warrant an easy script but yeah.

My suggestion for you would be to create an OpnSense plugin and try to create a PR for OpnSense. In that case, any further iteration could be controlled by trusted parties and more people would likely use your tool.

This was ultimately my goal, but as Monviech suggested, it appeared that a python script would not fly as a candidate. My best approach was to convert it into an executable and publish it using the go-to package managers first. Then maybe look for a plugin, but seems like it's for naught.

Thus, you could as well create a docker container that runs independently and does not have to be integrated as executable code into OpnSense, thereby causing no risk at all.

I am also offering a docker container for this, but as I understand FreeBSD doesn't support docker, so I think at some point I would like to entertain the idea of providing an OCI-compliant image for Podman which appears to be supported there (more on that later)

The main reason to be running inside of FreeBSD (for now hopefully) was to be able to access some of the utilities to get stats, like CPU/memory, ARP tables, DHCP registrations, interfaces, etc. But my goal is to move into the API side of things as soon as I can as I understand provides even more data I could leverage. This, after all, is an alpha version and I'm trying to also target pfSense/OpenWRT for those that like to use them (until I can figure out their APIs as well). And maybe after all this, hosting it in a docker container would be the first choice, no root access, can run outside of the router, and I don't have to host my own FreeBSD GitHub runner anymore :D.

I don't mind this being here to be honest, a user who uses the shell as root should know what they are doing (hopefully). I know not all do know the implications, I also like to run simple install scripts on linux after all. I hope for the best xD

We're never safe from supply chain attacks as the current npm thingy shows once more (and did multiple times in the past but nobody is learning :O)

I hope that I don't have to depend on more libraries to get this going. So far, the only dependencies are python3-psutil and python3-pycryptodome. I will keep this in mind to reduce my attack surface.

There is a point if it's unsupported as of version x.y.z of the UniFi Controller and might not show any statistics at all because of that even tho it's not the actual device !! ;)

I would suggest emulating something recent like the https://eu.store.ui.com/eu/en/category/cloud-gateways-compact/products/ucg-ultra since it's very likely that it's going to be supported for a long time in the future.

You are right! Now there seems to be a new UniFi OS something or other, that most likely will kill the USGs. The problem is that I don't have one of those new UCGs and getting one well, I would not have any need for this emulator anymore, or OPNSense for that matter :(

So maybe, after all this, I was 10 years too late... 

[patient0]

Now there seems to be a new UniFi OS something or other, that most likely will kill the USGs

UniFi OS is just a way to self host a UniFi Controller. Before, you did install the UniFi Network app on a Linux machine. With the UniFi OS they deliver the full stack that can be installed on a Linux (Mac/Windows) machine. I do use an UXG-Fiber[1] (like the cloud UCG-Fiber but without the controller built-in) and the UniFi OS as the controller.

If you can emulate the UXG-Fiber then you'll be fine for a few years, they won't go anywhere. Or the higher-end Gateway Enterprise.

And if you can tell me what to sniff for, I can run a tcpdump.

[1] https://store.ui.com/us/en/products/uxg-fiber