---
name: bnna-infra-mikrotik-vlan
version: 1.0.0
description: Add a VLAN to MikroTik switch trunk ports for the bnna cluster. Use when a new Proxmox SDN VLAN is not reachable despite the bridge being UP, or when setting up a new VLAN (e.g. global services vsvc174). Covers switch WebFig config, REST API, and diagnosis of L2 trunking failures.
---

# MikroTik Switch VLAN Trunking (BNNA)

When a new Proxmox SDN VLAN is created, it must also be added to the MikroTik
switch trunk ports. Without this, L2 frames are dropped at the switch even
though Proxmox shows the bridge and veth as UP.

## When to use this skill

- New SDN VLAN created but CT is unreachable from the router
- Proxmox `ip link show` confirms bridge is UP and veth is attached
- OPNsense ping to CT shows 100% packet loss
- TLS router returns SSL_ERROR_SYSCALL for `tls-<ip>` domains on the new VLAN

## Switch URLs and VLAN assignments

See `LOCAL.md` for deployment-specific switch URLs.
See `NETWORK.md` in the private infra repo (`m.bnna.net`) for full network
topology, switch IPs, and VLAN assignment table.

## Adding a VLAN via WebFig

1. Navigate to Bridge → VLANs
2. Find the entry for an existing working VLAN on the same path (e.g. 170)
3. Note which bridge port it's on
4. Add the new VLAN tag to the same entry's tagged VLAN list
5. Repeat on every switch in the path

MUST: Add the VLAN to ALL switches in the path between the Proxmox node and
the router. Missing any one causes L2 failures.

## Adding a VLAN via REST API

MikroTik RouterOS 7.1+ REST API (see `docs/mikrotik-routeros-api.md`):

```sh
# List bridge VLANs to find the entry ID
curl -sk -u admin:pass https://<switch>/rest/interface/bridge/vlan

# Add new tag to existing entry (append to vlan-ids)
curl -sk -u admin:pass -X PATCH \
  -H "Content-Type: application/json" \
  "https://<switch>/rest/interface/bridge/vlan/*<id>" \
  -d '{"vlan-ids": "170,174"}'
```

## Verification

From the OPNsense router diagnostic tools (or CLI), ping the CT's IP on the
new VLAN:

- 100% packet loss → VLAN not trunked on one or both switches
- Replies → L2 is working, proceed to OPNsense firewall rules

## VLAN categories

| Category | Example tags | Switch behavior |
|----------|-------------|----------------|
| Tenant VLANs | 1101–1149 | Already trunked (full range allowed on bridge) |
| Infrastructure VLANs | 160, 170, 174 | Must be added manually per switch when first created |

## Related

- `docs/new-vlan-checklist.md` — full checklist: SDN, switch, OPNsense, TLS router
- `docs/mikrotik-routeros-api.md` — RouterOS REST API reference
- `bnna-infra-postgres-setup` — uses vsvc174 for shared Postgres