vps/docs/unifi-openwrt-vlan10-implementation-examples.md

# UniFi AP + OpenWrt VLAN-backed Wi-Fi: implementation evidence

**Research date:** 2026-08-08  
**Scope:** research only. This file does not assert that the local physical
path currently carries VLAN 10, and no controller, AP, ERX, or OpenWrt setting
was changed while preparing it.

## Conclusion

Yes. This is a normal, supported deployment pattern: UniFi APs and Network
Application manage the SSID-to-VLAN mapping, while a non-UniFi gateway such as
OpenWrt owns the tagged VLAN interface, its subnet, DHCP, routing, and
firewall/policy routing. The existing untagged LAN DHCP server remains in
place; it serves only the native LAN, while OpenWrt serves the tagged VLAN.

Ubiquiti's current third-party-gateway recipe specifically says to configure
the subnet, VLAN ID, and DHCP **on the third-party gateway first**, then create
a UniFi virtual network with **Router = Third-party Gateway** and the same VLAN
ID. [Ubiquiti: Creating Virtual Networks (VLANs)](https://help.ui.com/hc/en-us/articles/9761080275607-Creating-Virtual-Networks-VLANs)

That supported pattern requires an end-to-end tagged path. It is not feasible
on the current local topology: `gfw` is a VM connected only to untagged LAN 66
and there is no verified physical or virtual switch trunk carrying VLAN 10 from
the U6 Lite to that VM. Creating `eth0.10` inside the VM cannot supply the
missing L2 transport.

## The reusable topology

```text
main SSID ── untagged/native LAN66 ── ERX DHCP ── 192.168.66.0/24
                         │
U6 Lite ── AP uplink trunk (native LAN66 + tagged VLAN 10) ── gfw/OpenWrt
   └── ubnt-upg SSID ── VLAN 10 ── gfw.10: 192.168.10.1/24 + DHCP + OpenClash
```

This is not two DHCP servers answering one broadcast domain. They serve two
separate L2 broadcast domains. An AP bridges a station's DHCP request into the
VLAN selected for its SSID; it does not allocate the address itself. Ubiquiti
states that SSID clients become members of the selected VLAN and that every
port between AP and gateway must allow that VLAN. [Ubiquiti: Creating UniFi
WiFi SSIDs](https://help.ui.com/hc/en-us/articles/26136823938583-Creating-UniFi-WiFi-SSIDs)

OpenWrt's own VLAN documentation shows the same mixed-link model: an untagged
LAN plus tagged VLAN interfaces on a common link, and explicitly notes that a
separate DHCP server can serve each segment. [OpenWrt: VLAN / switch
configuration](https://openwrt.org/docs/guide-user/network/vlan/switch_configuration)

## Evidence of existing deployments

### Protocol and product documentation (authoritative)

* Ubiquiti's third-party-gateway workflow is an exact product-supported recipe
  for the UniFi half: gateway first, then matching VLAN in UniFi. It does not
  require a UniFi gateway or switch. [Creating Virtual Networks
  (VLANs)](https://help.ui.com/hc/en-us/articles/9761080275607-Creating-Virtual-Networks-VLANs)
* Ubiquiti specifies the exact Wi-Fi half: choose the network in the SSID's
  **Network** dropdown, select the APs that should broadcast it, and permit the
  VLAN on all intervening ports. [Creating UniFi WiFi
  SSIDs](https://help.ui.com/hc/en-us/articles/26136823938583-Creating-UniFi-WiFi-SSIDs)
* Ubiquiti's troubleshooting topology specifically calls an SSID VLAN made
  native on the AP port, or absent as a tagged VLAN upstream, a broken setup;
  it directs operators to trace every AP-to-gateway port. [Virtual Network
  (VLAN) Troubleshooting](https://help.ui.com/hc/en-us/articles/9592924981911-Virtual-Network-VLAN-Troubleshooting)
* OpenWrt documents Linux 802.1Q interfaces and bridge VLAN membership. Its
  example calls out a trunk carrying untagged traffic and tagged VLANs, which
  is the link gfw needs. [OpenWrt: VLAN / switch
  configuration](https://openwrt.org/docs/guide-user/network/vlan/switch_configuration)

### User-reported working deployments (official Ubiquiti Community; anecdotal)

These are not Ubiquiti support guarantees, but they demonstrate that the exact
vendor split is in real use:

* A user reports a UniFi site whose upstream router/DHCP server is **OpenWrt**;
  they create a Third-Party Gateway network, assign its VLAN tag, then bind it
  to the Wi-Fi SSID. The report says it works without a UniFi gateway or switch.
  [UniFi Network Application 7.4.156 discussion](https://community.ui.com/releases/UniFi-Network-Application-7-4-156/15ac6260-9cd1-4ac3-a91c-4880c1c87882?page=36)
* A second user reports two SSID VLANs over an **OpenWrt Linksys WRT32X 802.1Q
  trunk**, with no USG or UniFi switch; the controller network is selected in
  the SSID's Network dropdown. [Assigning VLANs to SSIDs on Controller
  6](https://community.ui.com/questions/Assigning-VLANs-to-SSIDs-on-Controller-6/3e656047-685f-470e-954c-703077e89aaa)
* A Ubiquiti Community post describes an existing multi-VLAN UniFi deployment
  with an OpenWrt NanoPi R6S gateway and all UniFi networks configured as
  Third-party Gateway. [OpenWrt third-party-gateway
  deployment](https://community.ui.com/questions/Replacing-an-existing-third-party-router-firewall-with-a-UXG-Lite-on-an-existing-UniFi-network/5de2504a-fac2-437a-b893-495a6be2f3c0)

## Exact mapping for this network

| Layer | Required configuration |
|---|---|
| `gfw` / OpenWrt | Only after a tagged path reaches the VM: create/retain VLAN-10 interface, address `192.168.10.1/24`, run the **only** DHCP server for that segment, and apply the intended OpenClash/policy routing. |
| U6-to-gfw path | Native/untagged LAN66 for U6 management; tagged VLAN 10 allowed at every switch/link. Do not replace the native LAN with VLAN 10. |
| UniFi network | One VLAN 10 virtual network with **Router: Third-party Gateway**. This is controller metadata that makes the AP tag the selected SSID; it is not a DHCP service. |
| `ubnt-upg` Wi-Fi | Select that VLAN 10 network. Do not enable UniFi Hotspot/guest portal unless deliberately required. |
| Existing Wi-Fi | Leave `ubnt-windy`, `ubnt-windy-2`, and `ubnt-haas` network/VLAN choices untouched; they remain on their existing LANs and DHCP servers. |

The acceptance test is therefore unambiguous: after reconnecting, a device on
`ubnt-upg` must receive `192.168.10.x` from the VLAN 10 gateway, while a device
on existing Wi-Fi continues to receive its established LAN address. A
`192.168.66.x` lease on the dedicated SSID means VLAN 10 was not selected or
did not pass the L2 path; it is not evidence that the U6 should run DHCP.

## Protecting the existing Wi-Fi during a retry

The current UniFi UI supports **All**, **Specific**, and **Groups** independently
for each SSID's Broadcasting APs selection. [UniFi WiFi SSID and AP Settings
Overview](https://help.ui.com/hc/en-us/articles/32065480092951-UniFi-WiFi-SSID-and-AP-Settings-Overview)

Given the earlier incident where changing a virtual/AP group removed
`ubnt-windy` from the U6 Lite, the low-risk control is to leave every existing
SSID's Broadcasting APs selection unchanged and set **only `ubnt-upg`** to
**Specific → U6 Lite**. Do not reuse or move the default SSID into a temporary
group. This does not eliminate the short re-provision/reassociation caused by
an AP config push, but it prevents the configuration-level loss of the default
SSID that was observed.

Before enabling the dedicated SSID, inspect the saved settings and AP's
effective configuration, then test with one client. Only the dedicated SSID
should be affected by a failure; LAN66 DHCP and the existing SSIDs require no
change.