MerVLAN v0.52.1 (dev 0.52.5) Simple and Powerful VLAN Management **BETA**

[r80xcore]

MerVLAN VLAN Manager – Simple and Powerful VLAN Management

MerVLAN is an addon for Asuswrt-Merlin that adds a graphical VLAN manager directly inside the asuswrt-merlin web UI.

It is designed for AP-mode deployments and lets you:

• Assign VLANs per SSID (Wi-Fi network)
• Assign VLANs per physical LAN port
• (Experimental) Configure trunk ports for daisy-chained APs
• Synchronize VLAN config to other Asuswrt-Merlin nodes over SSH

The addon installs under the normal Merlin web interface (LAN section) and handles the low-level bridge/VLAN wiring for you.

MerVLAN is not a router or managed switch! It tags and bridges traffic at the AP; you still need a VLAN-aware upstream switch/firewall for routing, DHCP, and policy.

---

Status / Beta Notes

• Status: Public beta – expect bugs and breaking changes.
• Mode: AP-mode only (main and nodes must be running as APs, not routers).
• If you hit issues, collect logs and share them (Discord/SNB/PM or open a issue ticket on Gitub):
  • CLI output: visible via the UI
  • VLAN manager: visible via "View Logs")

---

What MerVLAN Actually Does

High level:

• Adds a VLAN configuration UI into Asuswrt-Merlin..
• Auto-configure SSID ↔ interface mapping, bridges, and VLAN interfaces for your device.
• Keeps configuration persistent across reboots and repairs it if something breaks.

Under the hood (simplified):

• Detects hardware capabilities (SSIDs, LAN ports, guest slots, etc.) via `functions/hw_probe.sh` and stores them in `settings/settings.json`.
• Maps each SSID and LAN port to VLANs based on your UI selections and writes a canonical JSON config.
• Applies VLAN tagging/bridging via `functions/mervlan_manager.sh` and friends.
• Hooks into `services-start` and `service-event` using templates in `templates/mervlan_templates.sh` so VLANs re-apply automatically on boot and certain system events.
• Uses a health-check/cron-style script (`functions/heal_event.sh`) to detect if VLAN bridges go missing and re-apply them.

This gives you a repeatable, UI-driven way to deploy and maintain VLANs on Asuswrt-Merlin APs.

---

Key Features

UI-driven VLAN management

• Per-SSID VLAN tagging (up to the number of SSIDs supported by your device).
• Per-LAN-port VLAN tagging for access ports.
• Experimental trunk support for daisy-chaining AP units via Ethernet backhaul.
• Built-in “Clients Overview” panel to see which VLAN clients are active on each node.

Multi-AP / Multi-node aware

• Syncs configuration and scripts to other Asuswrt-Merlin APs/nodes over SSH using `functions/sync_nodes.sh`.
• Supports mixed models as long as they run Asuswrt-Merlin (or compatible) with addon support.
• Optional modes to run VLAN manager locally, on nodes only, or on both.

Self-healing behavior

• `functions/heal_event.sh` and service hooks monitor VLAN bridges.
• If VLAN bridges disappear (e.g., you changed LAN/Wi-Fi settings and Merlin wiped them), MerVLAN re-applies the expected configuration.
• Health check runs on a short interval (worst-case downtime roughly a few minutes); in testing, stable setups run for weeks without observed VLAN drops.

Safe integration with Merlin

• Uses templates in `templates/mervlan_templates.sh` instead of blindly overwriting `services-start`/`service-event`.
• Hooks are injected in a variant-aware way and can be removed cleanly by the uninstall script.

Logging and debugging

• Structured logs in `/tmp/mervlan_tmp/logs/`:
  • `vlan_manager.log` – core apply pipeline
  • `cli_output.log` – what the UI shows in the command output panel
  • Additional logs for node sync, hardware probe, etc.
• Logs are also exposed via the UI under `/www/user/mervlan/tmp/logs`.

Install/Update lifecycle

• First-install script lays out directories, installs hooks, and provisions the UI.
• Update script. Update the addon via GUI or CLI.
• A public copy of settings is kept under `/www/user/mervlan/settings/settings.json` for the SPA to read.

---

Requirements

• Asuswrt-Merlin firmware with addon support on every device that will tag VLANs.
• AP-mode only on all participating routers/APs.
• JFFS enabled for persistent storage.
• SSH enabled on the main AP and any standalone APs/nodes (AiMesh nodes share SSH keys).
• Ethernet backhaul only between nodes/APs:
  • Wi-Fi backhaul cannot preserve VLAN tags on Asus hardware/driver stacks.
  • Daisy-chaining APs over Ethernet is supported (experimental) and under active testing.
• VLAN-aware upstream device (mandatory):
  • Managed switch and VLAN-aware router/firewall (e.g., OPNsense, pfSense, Asus Pro, etc.).
  • MerVLAN does not provide routing, firewalling, or DHCP.

Multi-AP notes:

• All APs must connect to VLAN-aware switches.
• LAN port VLAN tagging is currently global– the same per-port mapping is applied to all synced APs.
  • Since MerVLAN v052.5 it is now possible to configure LAN ports individually per node.

SSH key behavior:

• On typical AiMesh setups, the main AP’s SSH key (installed via MerVLAN’s “SSH Key Install” flow) is shared with AiMesh nodes by the firmware.
• For standalone APs used as nodes (non-AiMesh), you must manually install the same public key on each unit, just as you did on the main AP, before MerVLAN can sync and execute remotely on them.

---

Limitations

• Maximum number of VLANs is effectively bounded by the number of SSID slots on your hardware (e.g., if the AP supports 5 SSIDs, you can’t have 12 actively used VLANs mapped to SSIDs).
• Mesh behavior is constrained by Asus firmware:
  • Some models support more guest SSIDs than they can actually mesh; non-mesh SSIDs will only broadcast from the main node.
  • Devices on VLANs use standard band steering; per-VLAN steering is not supported.
• Wi-Fi backhaul cannot carry VLAN tags; only Ethernet backhaul is supported for VLAN-aware nodes.
• MerVLAN does not: route traffic, run DHCP, or replace a firewall.

---

Install

Only install if you are comfortable with beta software (including factory reset) if something goes wrong.

SSH into the AP and run this command. The addon will be placed under LAN → MerVLAN in the GUI:

mkdir -p /jffs/addons/mervlan && /usr/sbin/curl -fsL --retry 3 "https://raw.githubusercontent.com/r80xcore/mervlan/refs/heads/main/install.sh" -o "/jffs/addons/mervlan/install.sh" && chmod 0755 /jffs/addons/mervlan/install.sh && /jffs/addons/mervlan/install.sh full

This will:

• Create `/jffs/addons/mervlan` and required subdirectories.
• Install the core scripts under `functions/` and configs under `settings/`.
• Install the web UI under `/www/user/mervlan`.
• Inject the required `services-start` / `service-event` hooks.

If the web UI ever looks out of sync or partially broken after manual file changes, you can use a quick uninstall + reinstall as a manual flush/refresh of the public UI and addon files:

/jffs/addons/mervlan/uninstall.sh && /jffs/addons/mervlan/install.sh

---

Uninstall

From `/jffs/addons/mervlan` on the AP:

Standard uninstall (leave addon data directories in place):

./uninstall.sh

Full uninstall (also removes addon directories and temp workspace):

./uninstall.sh full

This will remove `/jffs/addons/mervlan` and `/tmp/mervlan_tmp` and attempt to clean up the service hooks.

---

Update

You can update the addon while preserving your settings and SSH keys.

On the main AP, run:

/jffs/addons/mervlan/functions/update_mervlan.sh

The updater will:

• Download the latest snapshot from GitHub.
• Validate required files and directories.
• Stage the new version, copy over `settings/settings.json` and SSH keys, and swap atomically.
• Re-run the hardware probe and resync files to nodes (when SSH keys and nodes are configured).
• Refresh the public web copy and reinstall hooks.

Updating the addon directly from the GUI is planned.

---

Logs & Debugging

Primary log directory:

• `/tmp/mervlan_tmp/logs`

Common logs, available in GUI:

• `vlan_manager.log` – VLAN apply pipeline and health checks.
• `cli_output.log` – mirrored output of commands run from the UI.

---

Development / Testing Notes

• Developed on an ASUS XT8 mesh system in AP-mode.
• Intended to work with most newer Asuswrt-Merlin / Gnuton-supported routers and mesh AP systems.
• Daisy-chaining under testing; experimental trunk options are exposed in the UI.

For structured beta testing and discussion, see the Discord

• MerVLAN on Discord
• MerVLAN on Github

---

See `changelog.txt` for detailed version history and notes.

---

See `LICENSE` for full license details.

 

[RaccoonNL]

I am interested in following this project, unfortunately the discord invitation link is not valid anymore.
Can you tell me if your VLAN manager also works when the router is setup in ap-mode?

 

[r80xcore]

I am interested in following this project, unfortunately the discord invitation link is not valid anymore.
Can you tell me if your VLAN manager also works when the router is setup in ap-mode?

Hi!
I will update the link tonight when I'm home, sorry for that.

The vlan manager is specifically made for routers in AP mode as running vlan in router mode generally isn't recommended and can introduce double NAT (as you need another firewall/router routing the vlans.

So if you're running in Ap mode you're hopefully good to go.

I'm currently in the process in porting this program to a real Addon where it's accessible from within the merlin GUI. It probably ready in a week or so. Until then, feel free to try the beta that uses it's own gui and adress.

 

[RaccoonNL]

Thanks for getting back at me so promptly.

I was asking because I am exploring the posibility to run an OPNsense mini pc as router/firewall and want to re-use my two Asus routers as access points in combination with VLAN tagging over Wifi and multiple SSID's (Main, Guests, IoT).

I will follow this thread with much interest.
Thanks for investing your time in what promisses to be a great addon.

Keep up the good work.

 

[r80xcore]

Thanks for getting back at me so promptly.

I was asking because I am exploring the posibility to run an OPNsense mini pc as router/firewall and want to re-use my two Asus routers as access points in combination with VLAN tagging over Wifi and multiple SSID's (Main, Guests, IoT).

I will follow this thread with much interest.
Thanks for investing your time in what promisses to be a great addon.

Keep up the good work.

No problems!

I'm running OPNsense myself and using this addon to tag three different guest networks in mesh and vlan 187,188,189, and it works great. then the plan is to run the untagged as 186 in the switch so everything ends up tagged in opnsense.

 

[Tech9]

Mesh users: VLAN tagging is only supported when nodes are connected via Ethernet backhaul.

But... this is not technically Mesh anymore and whoever has Ethernet available may find AP Mode much better with more control per AP and better spectrum utilization with up to 2x higher aggregate throughput to wirelessly connected clients. So when Ethernet is available and there is VLAN capable APs (native or via custom script) this AiMesh option is actually a limitation and has to be avoided.

Thanks for sharing your work! It may save someone money by reusing available hardware.

 

[r80xcore]

But... this is not technically Mesh anymore and whoever has Ethernet available may find AP Mode much better with more control per AP and better spectrum utilization with up to 2x higher aggregate throughput to wirelessly connected clients. So when Ethernet is available and there is VLAN capable APs (native or via custom script) this AiMesh option is actually a limitation and has to be avoided.

Thanks for sharing your work! It may save someone money by reusing available hardware.

What I mean by that is that the WiFi in these devices does not support vlan trunking which means that the tagged VLAN packets is stripped if they travel from the mesh node using WiFi backhaul. So you need to connect the the mesh nodes via ethernet to a managed switch. Daisy chaining is planned but not something I will start with until everything is up and running.

When setting up mesh you do that via the gui as normal. This addon only tags traffic on the chosen SSID.

So TLDR.
Mesh is supported but only if device is connected via cable. Which honestly is the preffered way anyhow for an AP, especially when using VLAN.

My devices work on mesh VLAN at home.

 

[Tech9]

Mesh is supported but only if device is connected via cable.

Some terms mismatch. Mesh is wireless only in networking. Wired mesh is consumer products marketing invention.

 

[r80xcore]

Some terms mismatch. Mesh is wireless only in networking. Wired mesh is consumer products marketing invention.

Right, when I said device, I meant the other AiMesh nodes, not client devices like phones or laptops. I was probably a bit unclear there.

You’re correct that mesh in enterprise networking usually means a wireless interconnect between access points. But in ASUS AiMesh (and most consumer systems), the term mesh also includes setups that use Ethernet backhaul — it’s still the same AiMesh control layer, just with wired links instead of wireless ones. In other words, one SSID covered by several APs.

So yes, VLAN Manager fully supports AiMesh, but only when the nodes are connected via Ethernet backhaul. That ensures VLAN tags are preserved end-to-end while keeping the roaming benefits without breaking isolation. This setup must use Ethernet backhaul only so VLAN tags travel correctly. Mixed Ethernet + Wi-Fi backhaul can break VLAN isolation.

The key difference is that AiMesh can’t “control” or steer clients on a VLAN-tagged SSID. Those SSIDs still broadcast on all nodes, but AiMesh’s smart-connect and steering logic won’t apply to them. Clients just roam naturally between nodes.

 

[jksmurf]

But... this is not technically Mesh anymore

Can you please expand on why not? Asus WebGui makes no differentiation as to how nodes are connected. Is there a standardized Mesh definition?

 

[Tech9]

There is nothing to expand. Mesh is wirelessly connected re-transmitters. It was invented long before Wi-Fi. Consumer products marketing invented wired mesh. It's a key word. What ASUS (or others on the same market) have in their App or Web GUI is whatever they decided to call specific feature. There are many strictly marketing terms like Game Boost (QoS), Game Accelerator (QoS), OpenNAT (port forwarding), WTFast (some paid VPN service), as well as mimicking common abbreviations like SDN (as per ASUS - Self-Defined Network), Ai/AI (as per ASUS for some products - Always Incredible), etc. Part of the learning curve when moving to more business oriented products comes from technically incorrect terms used in consumer products.

 

[jksmurf]

There is nothing to expand.

OK thanks.

 

[r80xcore]

I am interested in following this project, unfortunately the discord invitation link is not valid anymore.
Can you tell me if your VLAN manager also works when the router is setup in ap-mode?

Sorry for the delay. I got caught up in work and forgot to send you the link. Here's a new link for you.

Join the r80xcores-Merlin-VLAN Discord Server!

Check out the r80xcores-Merlin-VLAN community on Discord - hang out with 5 other members and enjoy free voice and text chat.

discord.gg

The version available there is v0.44 with its own ui on another Web adress. I would suggest you wait until v0.45 is done. It will be installed as an addon and be a part of the official Gui under the "Tools". Has been a learning curve to get it right but it should be finished and ready for use by the weekend.

Full changelog will be available when released as there are a lot of changes under the hood. It's more sturdy, self-contained and most important following the addon api and guidelines as well as a new GUI following the system css.

See you on Discord!

 

[r80xcore]

Update v0.45

* Name change from Merlin VLAN Manager to MerVLAN.
* full transition to real addon instead of standalone lighttpd site.
* rewrite of most scripts.
* github repository
* hunted down a lot of bugs but as the transition was quite extensive bugs might be present. Please send logs and info if you run into any.

 

[r80xcore]

MerVLANn v0.46

Changelog:

# execute_nodes.sh v0.45 - v0.46
# Reworked to fix broken paths

# mervlan_boot.sh v0.45 -> v0.46
# Added SSH-propagated node actions (nodeenable, nodedisable, setupenable, setupdisable) so main commands fan out to satellites.
# Hardened template injection logic; corrected service-event-nodes.tpl handling so the main router service handler no longer receives the node variant.

# mervlan_manager.sh v0.45 -> v0.46
# Queue-aware, timed restarts: skip duplicate restart_wireless/switch/httpd via /tmp/rc_service/ps and enforce timeouts.
# Global mkdir lock: prevents overlapping runs from clobbering bridges/interfaces.
# VAP wait cap: wait_for_interface limited to ~63 s (exponential backoff).
# Clean bridge teardown: detach all member ports before brctl delbr.
# Safer delif: ignore empty bridge names and dedupe in remove_from_all_bridges.
# Fail-fast env: exit if CHANGES or LOCKDIR aren’t set.
# Full cmdlines: use ps w so token matching is reliable.
# Cleaned stray braces and adjusted client-refresh conditions in mervlan_manager.sh to Ensured only the main router runs collect_clients.sh

# service-event-handler.sh v0.45 -> v0.46
# Added debounce to deflect multi-clicks or multi-calls.
# Added missing executenodes_vlanmgr

# sync_nodes.sh v0.45 -> v0.46
# Hardened to create all runtime directories remotely before file sync.
# Added missing hw_settings.json, preventing the execution of some scripts.

# service-event-nodes.tpl
# Added TEMPLATE_2 mirroring the service-event-handler.sh on main. Used to prevent accidental writes to the main version.

# var_settings.sh v0.45 -> v0.46
# added several definitions that is used in the updated versions.

# index.html
Updated index.html buttons to send actions through the unified queue, added modal button wiring, and maintained per-action logging/locking.

# mervlan.asp
# Restored action_mode="apply" and built policy-controlled wrappers in mervlan.asp, including sandboxed skip-refresh handling and the shared MVM_trigger pathway.

A lot of other both small and medium bugs fixed in .html .asp and general definitions throughout the scripts.

 

[Seth Harman]

So I'd suggest we just continue in here and maybe you make a final post on the other thread that points at this thread.

One thing that occurred to me is part of the setup involves figuring out the IP addresses of the AiMesh nodes and manually inputting them. Eventually some kind of auto-discovery would be great, if possible, but the bigger question is what happens in the unlikely event the node IP address changes after install/configuration? Those addresses are assigned via DHCP when you add the node under AiMesh so I'm assuming there's still a possibility they could get reassigned by the system itself, of if you remove and then re-add it could change. If the IP changes after install/configuration does this all break?

 

[visortgw]

So I'd suggest we just continue in here and maybe you make a final post on the other thread that points at this thread.

One thing that occurred to me is part of the setup involves figuring out the IP addresses of the AiMesh nodes and manually inputting them. Eventually some kind of auto-discovery would be great, if possible, but the bigger question is what happens in the unlikely event the node IP address changes after install/configuration? Those addresses are assigned via DHCP when you add the node under AiMesh so I'm assuming there's still a possibility they could get reassigned by the system itself, of if you remove and then re-add it could change. If the IP changes after install/configuration does this all break?

Solution: Create DHCP reservation for AiMesh nodes.

 

[Seth Harman]

Ok, installed, everything worked this time including generating the SSH key. One question I have is I see Lan 1-5 in the interface but no reference to which piece of hardware this is applying to. If, for example, I set LAN 2 to VLAN ID 53 is that going to cause Lan 2 on each node to tag 53? And what if you have an AiMesh node that has a different number of LAN ports?

Here's another issue:

 

[Seth Harman]

Ok, log files are telling me it's because of the same thing @visortgw just said in the other thread, the SSH key hasn't been copied to the nodes. Is there a step I'm missing here where I was supposed to manually install that key somewhere on the nodes?

 

[jksmurf]

Solution: Create DHCP reservation for AiMesh nodes.

That’s exactly what I do in both my networks and works even when you delete and later re-add the same node. Easy to manage via SSH as IP is fixed. Even comes up with dinky little icons.

Although have you ever noticed they whilst they appear in the log, they don’t ever get assigned names in the system log, wireless log, if you use wireless backhaul…