iopsys-feed/netmode/docs/ADVANCED_MODE_GUIDE.md

# Advanced Mode - Complete Configuration Guide

## Table of Contents
1. [Overview](#overview)
2. [Interface Types](#interface-types)
3. [Configuration Examples](#configuration-examples)
4. [Use Case Scenarios](#use-case-scenarios)
5. [TR-069/USP Configuration](#tr-069usp-configuration)
6. [Troubleshooting](#troubleshooting)

---

## Overview

The **advanced** mode is a unified, flexible network configuration mode for OpenWrt/iopsys routers. It provides a single, powerful interface for configuring:

- **Bridge interfaces** with VLAN/QinQ support (traditional VLAN devices)
- **Bridge VLAN filtering** (modern kernel bridge features - recommended)
- **Routed interfaces** with VLAN/MACVLAN support
- **Standalone interfaces** (direct VLAN without bridge, similar to Routed, but does not support macvlan, or inet or iptv modifiers (those require routing), but it can be set to mgmt).
- **Mixed scenarios** (combine bridges and routed interfaces)

### Key Features

- ✅ Unified configuration syntax
- ✅ Multiple interface types in one configuration
- ✅ VLAN (802.1Q) and QinQ (802.1ad) support
- ✅ Modern bridge VLAN filtering for better performance
- ✅ MACVLAN support for multi-service routing
- ✅ Per-interface port assignment
- ✅ Flexible protocol configuration (DHCP, none, static)
- ✅ UCI device name resolution (LAN1 → eth1)
- ✅ Automatic reconfiguration on parameter changes

### Configuration Parameters

| Parameter | Description | Example |
|-----------|-------------|---------|
| `interface_configs` | Comma-separated interface configs | `bridge:transparent;ALL_LAN,route:transparent;WAN;mtu-1400` |
| `macaddrs` | Comma-separated MAC addresses (optional) | `BaseMACAddress,BaseMACAddressP1,AA:BB:CC:DD:EE:FF` |

### How It Works

When you change any configuration parameter and restart netmode:
1. The system detects the configuration change automatically
2. Old network configuration is cleaned up (interfaces, bridges, VLANs)
3. System configuration is preserved (loopback, physical devices)
4. New configuration is applied based on your parameters
5. No manual intervention needed!

---

## Interface Types

### Bridge Types (Traditional VLAN Devices)

Bridge types create L2 bridge interfaces using traditional VLAN devices (eth0.100, etc.).

| Type | Syntax | Description |
|------|--------|-------------|
| **Transparent** | `bridge:transparent` | No VLAN tagging on any port |
| **Tagged** | `bridge:tagged:VID` | All ports tagged with same VLAN ID |
| **WAN-Tagged** | `bridge:wan-tagged:VID` | Only WAN port tagged, LAN ports untagged |
| **Transparent QinQ** | `bridge:transparent-qinq:SVID` | LAN untagged, WAN single S-tag (802.1ad) |
| **Transparent QinQ (Double)** | `bridge:transparent-qinq:CVID:SVID` | LAN untagged, WAN double-tagged (C+S) |
| **Tagged QinQ** | `bridge:tagged-qinq:CVID:SVID` | LAN C-tagged, WAN double-tagged (C+S) |
| **QinQ (All ports)** | `bridge:qinq:CVID:SVID` | All ports double-tagged |

### Bridge VLAN Filtering Types (Modern Approach)

Bridge VLAN filtering uses kernel bridge VLAN filtering instead of creating VLAN devices. **Recommended for new deployments.**

| Type | Syntax | Description |
|------|--------|-------------|
| **Tagged** | `brvlan:tagged:VID` | All ports tagged with VLAN ID (uses bridge-vlan) |
| **WAN-Tagged** | `brvlan:wan-tagged:VID` | WAN tagged, LAN untagged (uses bridge-vlan) |
| **Mixed** | `brvlan:mixed:VID` | Custom tagged/untagged configuration |

**See [BRIDGE_VLAN_FILTERING.md](BRIDGE_VLAN_FILTERING.md) for detailed documentation.**

### Routed Types

Routed types create L3 routed interfaces (with NAT/firewall).

| Type | Syntax | Description |
|------|--------|-------------|
| **VLAN Routing** | `route:vlan:VID` | Routed interface on VLAN |
| **MACVLAN Routing** | `route:macvlan:MAC` | MACVLAN device with custom MAC (supports macros) |
| **VLAN + MAC Routing** | `route:vlan:VID:MAC` | Routed interface on VLAN with custom MAC |
| **Transparent Routing** | `route:transparent` | Routed interface on base device (no VLAN) |

### Standalone Types

Standalone types create VLAN interfaces without bridges or routing (proto=dhcp by default).

| Type | Syntax | Description |
|------|--------|-------------|
| **Direct VLAN** | `direct:vlan:VID` | Standalone VLAN interface, proto=dhcp |

### Device Reference Types

Device reference types allow multiple interfaces to share the same underlying device.

| Type | Syntax | Description |
|------|--------|-------------|
| **Device Reference** | `device-ref:INTERFACE_NUMBER` | References the device from Nth interface |

**Use Case**: Create separate IPv4 and IPv6 interfaces (wan and wan6) that share the same bridge or VLAN device.

**Example**:
```bash
# wan creates bridge on VLAN 2501 with DHCP
# wan6 shares the same br-wan device with DHCPv6
uci set netmode.@supported_args[12].value='bridge:tagged:2501;ALL,device-ref:1-dhcpv6;ALL'
```

#### Note

Currently we are using *"netmode.@supported_args[12]"* in the examples, but we can also use *netmode.mode_4_supprted_args_1*. Also, if any other changes occur, the uci index or mode index might change, what matters is that *advanced* mode's correct argument is being set (the one corresponding to *interface_configs*).

```
uci show netmode.@supported_args[12]

netmode.mode_4_supprted_args_1=supported_args
netmode.mode_4_supprted_args_1.name='interface_configs'
netmode.mode_4_supprted_args_1.description='Interface type;Ports (comma-separated). Categories for type -- Bridge: bridge:transparent, bridge:tagged:VID, bridge:wan-tagged:VID, bridge:qinq:C:S. Routed: route:vlan:VID, route:macvlan:MAC, route:vlan:VID:MAC. Standalone: direct:VID. Modifiers: -n (proto none), -d (disabled). Categories for ports: ALL, ALL_LAN, LAN1-LAN2-WAN, WAN.'
netmode.mode_4_supprted_args_1.required='0'
netmode.mode_4_supprted_args_1.type='string'
netmode.mode_4_supprted_args_1.dm_parent='mode_4'
```

**Result**:
- `wan`: Creates `br-wan` bridge device on VLAN 2501, proto=dhcp
- `wan6`: Uses same `br-wan` device, proto=dhcpv6

**Note**: The referenced interface must be defined before the device-ref interface in the interface_names list.

#### MTU

- MTU can be provided for each interface as "mtu-1400" for example, as one of the arguments of a semi-colon separated list. The first 2 arguments must still be interface type and port list respectively.
- It is optional, if not provided, no MTU will be set.
- Valid range for MTU is [65-9000].
- If proto is pppoe, then mtu will be increased by 8 before setting to accomodate the protocol overhead.

**Valid examples:**

*no mtu specified*
```
uci set netmode.@supported_args[12].value='bridge:transparent-static;ALL_LAN,bridge:tagged:200;WAN'
```

*mtu set to 1400 on transparent bridge*
```
netmode.mode_4_supprted_args_1.value='bridge:transparent;ALL;mtu-1400'
```

*mtu set for one of the interfaces*
```
# 1234 will be simply ignored and mtu of 1300 will be set for the first interface:
# Note, since this is a transparent bridge, MTU will be set for all LAN ports and the WAN port.
# So this MTU is going to affect the second interface also.
uci set netmode.@supported_args[12].value='bridge:transparent-n;ALL;1234;mtu-1300,direct:vlan:10-dhcp-mgmt;WAN'
```

*mtu with bridge-vlan*
```
uci set netmode.@supported_args[12].value='brvlan:mixed:200:LAN1-WAN;LAN1-LAN2-LAN3-WAN;mtu-1450'
```

**Notes:**

- If the underlying device for an interface is a vlan, then MTU will be set for that vlan device.
- If the underlying device for an interface is a base interface (example: eth1), then mtu will be set for eth1 and so on.
- MTU will be ignored for device-ref interfaces.
- For bridge interfaces, mtu will be set for all the ports. If the ports are eth1.100 and ae_wan.100, then mtu will be set for these vlan devices. If ports are eth1 and ae_wan, then mtu will be set for eth1 and ae_wan sections.
- For bridge-vlan interfaces, since there is a shared bridge with all the base ports (eth1, eth2 etc), the last provided mtu for a bridge-vlan will be used for eth1, eth2 etc


### Modifiers

Modifiers can be appended to any interface type:

| Modifier | Effect | Example |
|----------|--------|---------|
| `-pppoe` | Set proto=pppoe (PPPoE authentication) | `route:vlan:101-pppoe` |
| `-dhcpv6` | Set proto=dhcpv6 (DHCPv6 client) | `bridge:tagged:2501-dhcpv6` |
| `-dhcp` | Set proto=dhcp (DHCP client - explicit) | `bridge:transparent-dhcp` |
| `-static` | Set proto=static (static IP) | `bridge:transparent-static` |
| `-none`, `-n` | Set proto=none (no IP configuration) | `bridge:tagged:100-none` or `bridge:tagged:100-n` |
| `-iptv` | Signify that this is an iptv interface (affects firewall and mcast) | `route:vlan:200-iptv` |
| `-inet` | Signify that this is an internet interface (affects firewall) | `route:vlan:200-inet` |
| `-mgmt` | Signify that this is a management interface (affects firewall) | `route:vlan:200-mgmt` |
| `-lan` | Signify that this is a lan (downstream) interface (affects firewall) | `route:vlan:200-mgmt-lan` |
| `-disabled`, `-d` | Create but mark as disabled | `route:vlan:200-disabled` or `route:vlan:200-d` |


#### Notes

- For each interface individually, if more than one modifier is present, ordering among the modifiers should be as follows: none (or n), static, dhcp, dhcpv6, pppoe, lan, mgmt, inet, iptv, disabled(d). Example: `uci set netmode.@supported_args[13].value='bridge:transparent-n,direct:vlan:100-dhcp-mgmt'` 
- Some modifiers are mutually exclusive, for example mgmt and inet.
- The `-none` and `-n` modifiers are equivalent, as are `-disabled` and `-d`.
- If no protocol modifier is specified, interfaces default to `proto=dhcp`.
- Protocols and disabled can be clubbed together, and disabled should be in the last, for example: `transparent-qinq:2-n-d` will set proto as none and disable the interface, similarly other protocols can be used.
- iptv and inet modifier can only be used with route interfaces, mgmt can be used with route or direct interfaces, and they can be clubbed with disabled modifier, but disable should be in the last.
- There can be multiple interfaces with -lan modifier, and they will be added to firewall's lan zone.
- Interfaces with -mgmt modifier will go to separate mgmt zone in firewall UCI and traffic from lan will not be forwarded to it.
- Interfaces with -iptv and -inet modifier will go to wan zone in firewall UCI and traffic from lan will be forwarded to them.

### Interface Naming rules

- Interfaces will be called iface1, iface2 etc unless the following conditions are met (checked in the order listed).
- The first interface that has -lan modifier will be called lan.
- The first interface with dhcpv6 modifier will be called wan6.
- The first bridge interface with all ports (LAN + WAN) will be called wan.
- The first interface with inet modifier will be called wan.
- The first interface (bridge or not) with wan port or all ports will be called wan.
- The first bridge interface with ALL_LAN ports will be called lan.

#### Static IP Auto-Configuration

When using the `-static` modifier with an interface named `lan`, the system automatically configures:

**Network Configuration**:
- IP Address: 192.168.1.1
- Netmask: 255.255.255.0
- IPv6 Prefix: /60

**DHCP Server Configuration**:
- Start: 192.168.1.100
- Limit: 150 addresses (100-250)
- Lease time: 1 hour
- DHCPv4: server
- DHCPv6: server
- Router Advertisement: server
- SLAAC: enabled
- RA flags: managed-config, other-config

**Example**:
```bash
interface_configs='bridge:transparent-static;ALL_LAN,bridge:tagged:2501;WAN'
```

For non-LAN interfaces with `-static`, only `proto=static` is set without additional configuration.

**Note**: Direct interfaces default to `proto=dhcp`.

### MAC Address Assignment

You can assign custom MAC addresses to interfaces using the `macaddrs` parameter. This is useful when ISPs require specific MAC addresses per service or for multi-service configurations.

**Supported Formats:**

| Format | Description | Example |
|--------|-------------|---------|
| **Explicit MAC** | Direct MAC address assignment | `AA:BB:CC:DD:EE:FF` |
| **BaseMACAddress** | Use base MAC from `fw_printenv -n ethaddr` | `BaseMACAddress` |
| **BaseMACAddressP1** | Base MAC + 1 | `BaseMACAddressP1` |
| **BaseMACAddressPN** | Base MAC + N (any number) | `BaseMACAddressP5` |

**Example:**
```bash
# If base MAC is 94:3F:0C:D5:76:00
uci set netmode.@supported_args[3].value='BaseMACAddress,BaseMACAddressP1,AA:BB:CC:DD:EE:FF'
# Results in:
# Interface 1: 94:3F:0C:D5:76:00
# Interface 2: 94:3F:0C:D5:76:01
# Interface 3: AA:BB:CC:DD:EE:FF
```

**Note**: MAC addresses are assigned to interfaces in order. If you have 3 interfaces but only specify 2 MAC addresses, the 3rd interface will use the system default.

---

## Configuration Examples

### Example 1: Simple Transparent Bridge

**Scenario**: All ports bridged together, no VLANs

```bash
uci set netmode.global.mode='advanced'
uci set netmode.@supported_args[12].value='bridge:transparent;ALL'     # interface_types
uci commit netmode
service netmode restart
```

**Result**: Creates `br-wan` bridge with all LAN+WAN ports, proto=dhcp

---

### Example 2: LAN-Only Bridge with Routed WAN

**Scenario**: Bridge all LAN ports together, WAN as separate routed interface

```bash
uci set netmode.global.mode='advanced'
uci set netmode.@supported_args[12].value='bridge:transparent-static;ALL_LAN,route:transparent;WAN'
uci commit netmode
service netmode restart
```

**Result**: 
- Creates `br-lan` bridge with all LAN ports only, WAN routed separately.
- Since the first interface is a bridge with ALL_LAN, it will be named as lan.
- When netmode sees a static interface called lan, it sets up IP 192.168.1.1/24 and DHCP server on it.

---

### Example 3: VLAN-Tagged Bridge (Managed Network)

**Scenario**: All ports tagged with VLAN 100

```bash
uci set netmode.global.mode='advanced'
uci set netmode.@supported_args[12].value='bridge:tagged:100;ALL'
uci commit netmode
service netmode restart
```

**Result**: Creates `br-mgmt` with all ports tagged as `.100`

---

### Example 4: Multiple Service Bridges (VLAN Segregation)

**Scenario**: Separate bridges for Internet (VLAN 100), IPTV (VLAN 200), Management (VLAN 300)

```bash
uci set netmode.global.mode='advanced'
uci set netmode.@supported_args[12].value='bridge:tagged:100-n;LAN1-LAN2-WAN,bridge:tagged:200-n;LAN3-LAN4-WAN,bridge:tagged:300;WAN'
uci commit netmode
service netmode restart
```

**Result**:
- `br-inet`: LAN1.100 + LAN2.100 + WAN.100, proto=none
- `br-iptv`: LAN3.200 + LAN4.200 + WAN.200, proto=none
- `br-mgmt`: WAN.300, proto=dhcp

---

### Example 5: QinQ Configuration (Wholesale Provider)

**Scenario**: Customer A on C-tag 10 S-tag 100, Customer B on C-tag 20 S-tag 100

```bash
uci set netmode.global.mode='advanced'
uci set netmode.@supported_args[12].value='bridge:qinq:10:100-n;LAN1-LAN2-WAN,bridge:qinq:20:100-n;LAN3-LAN4-WAN'
uci commit netmode
service netmode restart
```

**Result**:
- `br-customer_a`: All ports double-tagged (100.10)
- `br-customer_b`: All ports double-tagged (100.20)

---

### Example 6: Routed Multi-Service with Custom MAC Addresses

**Scenario**: ISP requires different MAC addresses for Internet and IPTV services

```bash
uci set netmode.global.mode='advanced'
uci set netmode.@supported_args[12].value='route:macvlan:BaseMACAddressP2-mgmt;WAN,route:macvlan:BaseMACAddressP3-inet;WAN,route:macvlan:BaseMACAddressP4-iptv;WAN,bridge:transparent-static;ALL_LAN'
uci commit netmode
service netmode restart
```

**Result**:
- `mgmt_wan`: Routed interface on WAN with base MAC + 2(58:00:32:C0:0E:42)
- `wan`: Routed interface on WAN with base MAC + 3 (58:00:32:C0:0E:43)
- `iptv_wan`: Routed interface on WAN with base MAC + 4 (58:00:32:C0:0E:44)
- `lan`: bridged interface on ALL LAN ports with base MAC (58:00:32:C0:0E:40)

---

### Example 7: Routed Multi-Service (VLAN-based)

**Scenario**: Internet on VLAN 100, IPTV on VLAN 200, Management on VLAN 300, all routed

```bash
uci set netmode.global.mode='advanced'
uci set netmode.@supported_args[12].value='route:vlan:300-mgmt;WAN,route:vlan:100-inet;WAN,route:vlan:200-iptv;WAN,bridge:transparent-static;ALL_LAN'
uci commit netmode
service netmode restart
```

**Result**:
- `wan`: Routed on WAN.100, proto=dhcp
- `iptv`: Routed on WAN.200, proto=dhcp
- `mgmt`: Routed on WAN.300, proto=dhcp

---

### Example 8: Routed Multi-Service (MACVLAN with Macros)

**Scenario**: Internet and IPTV using MACVLAN devices with MAC address macros

```bash
uci set netmode.global.mode='advanced'
uci set netmode.@supported_args[12].value='route:transparent;WAN,route:macvlan:BaseMACAddressP1;WAN'
uci commit netmode
service netmode restart
```

**Result**:
- `wan`: Routed on WAN with default MAC (94:3F:0C:D5:76:00)
- `iptv`: MACVLAN device on WAN with base MAC + 1 (94:3F:0C:D5:76:01)

**Alternative with explicit MAC:**
```bash
uci set netmode.@supported_args[13].value='route:transparent;WAN,route:macvlan:AA:BB:CC:DD:EE:FF;WAN'
```

---

### Example 9: Routed Multi-Service (VLAN + MACVLAN)

**Scenario**: Internet on VLAN 100, IPTV on VLAN 200 with custom MAC

```bash
uci set netmode.global.mode='advanced'
uci set netmode.@supported_args[12].value='route:vlan:100;WAN,route:vlan:200:AA:BB:CC:DD:EE:FF;WAN'
uci commit netmode
service netmode restart
```

**Result**:
- `wan`: Routed on WAN.100 (default MAC), proto=dhcp
- `iptv`: Routed on WAN.200 with custom MAC, proto=dhcp

---

### Example 10: Standalone VLAN Interface (Direct)

**Scenario**: WAN as standalone VLAN 2501 interface (no bridge, no routing)

```bash
uci set netmode.global.mode='advanced'
uci set netmode.@supported_args[12].value='direct:vlan:2501;WAN'
uci commit netmode
service netmode restart
```

**Result**: Creates WAN.2501 interface, proto=DHCP

---

### Example 11: Mixed Bridge and Routed Interfaces

**Scenario**: IPTV bridged on VLAN 200, Internet routed on VLAN 100

```bash
uci set netmode.global.mode='advanced'
uci set netmode.@supported_args[12].value='route:vlan:100;WAN,bridge:tagged:200-n;LAN1-LAN2-WAN'
uci commit netmode
service netmode restart
```

**Result**:
- `wan`: Routed on WAN.100, proto=dhcp (firewall enabled)
- `br-iptv`: Bridge on LAN1.200 + LAN2.200 + WAN.200, proto=none

---

## Use Case Scenarios

### Scenario 1: ISP Triple-Play Service (Routed)

**Requirement**: Internet on VLAN 100, IPTV on VLAN 200, VoIP on VLAN 300, all routed

**Configuration**:
```bash
uci set netmode.global.mode='advanced'
uci set netmode.@supported_args[12].value='route:vlan:100;WAN,route:vlan:200;WAN,route:vlan:300;WAN'
uci commit netmode
service netmode restart
```

**Network Topology**:
```
WAN (ae_wan)
  ├── wan (VLAN 100) - Internet - Routed
  ├── iptv (VLAN 200) - IPTV - Routed
  └── voip (VLAN 300) - VoIP - Routed
```

---

### Scenario 2: ISP Triple-Play with MACVLAN

**Requirement**: Internet normal MAC, IPTV with custom MAC, VoIP with custom MAC

**Configuration**:
```bash
uci set netmode.global.mode='advanced'
uci set netmode.@supported_args[12].value='route:transparent;WAN,route:macvlan:AA:BB:CC:DD:EE:01;WAN,route:macvlan:AA:BB:CC:DD:EE:02;WAN'
uci commit netmode
service netmode restart
```

---

### Scenario 3: Enterprise VLAN Segregation (Bridged)

**Requirement**: Guest WiFi on VLAN 100, Corporate on VLAN 200, Management on VLAN 300, all bridged

**Configuration**:
```bash
uci set netmode.global.mode='advanced'
uci set netmode.@supported_args[12].value='bridge:tagged:100-n;LAN1-WAN,bridge:tagged:200-n;LAN2-LAN3-WAN,bridge:tagged:300;WAN'
uci commit netmode
service netmode restart
```

**Network Topology**:
```
LAN1.100 ──┬── WAN.100 ──[ br-guest ] (proto=none)
LAN2.200 ──┬── WAN.200 ──[ br-corporate ] (proto=none)
LAN3.200 ──┘
WAN.300 ────[ br-mgmt ] (proto=dhcp)
```

---

### Scenario 4: Wholesale QinQ Provider

**Requirement**: Multiple customers on single fiber, S-tag 100, different C-tags

**Configuration**:
```bash
uci set netmode.global.mode='advanced'
uci set netmode.@supported_args[12].value='bridge:qinq:10:100-n;LAN1-LAN2-WAN,bridge:qinq:20:100-n;LAN3-LAN4-WAN,bridge:qinq:30:100-n;LAN5-LAN6-WAN'
uci commit netmode
service netmode restart
```

---

### Scenario 5: Hybrid Bridge + Routed

**Requirement**: Internet routed, IPTV bridged to STBs

**Configuration**:
```bash
uci set netmode.global.mode='advanced'
uci set netmode.@supported_args[12].value='route:vlan:100;WAN,bridge:tagged:200-n;LAN1-LAN2-LAN3-WAN'
uci commit netmode
service netmode restart
```

**Network Topology**:
```
WAN.100 ─── [ wan - routed ] (NAT, firewall enabled)

LAN1.200 ──┐
LAN2.200 ──┼─ WAN.200 ──[ br-iptv ] (transparent bridge, proto=none)
LAN3.200 ──┘
```

---

## Port List Specifications

### Port List Syntax

- **`ALL`**: All LAN ports + WAN port + EXT port (resolved from UCI or board.json)
- **`ALL_LAN`**: All LAN ports only (no WAN, no EXT) - useful for LAN-only bridges
- **`LAN`**: Single LAN port (for devices with one LAN port)
- **`WAN`**: Only WAN port
- **`EXT`**: Only EXT port
- **`LAN-WAN`**: Single LAN port and WAN
- **`LAN1-LAN2-WAN`**: LAN1, LAN2, and WAN
- **`LAN1-LAN2:u-WAN`**: LAN1, LAN2, and WAN, but LAN2 will be untagged, if this is a tagged bridge.
- **`LAN1-LAN2-WAN:tpid:34984`**: LAN1, LAN2, and WAN, but if vlan device section is created on WAN, it will have tpid configured.
- **`LAN1-LAN3-EXT`**: LAN1, LAN3, and EXT
- **`WAN-EXT`**: WAN and EXT ports

**Note**: For devices with a single LAN port, use `LAN`. For devices with multiple LAN ports, use `LAN1-8`. The `ALL` and `ALL_LAN` macros automatically detect which configuration is present.

#### Individual untagged port

- Suppose we have a bridge:tagged type interface, so all the ports are going to be tagged in this case. To mark any of the ports untagged individually, ":u" modifier can be used with the port, for example, to make LAN3 untagged (transparent) here: "LAN2-LAN3:u-LAN4-WAN".
- ":u" and ":tpid" modifier cannot be used together for the same port in the same interface.

#### TPID

- TPID cannot be specified for ALL, ALL_LAN port specification.

- Example 1: `'direct:vlan:100-dhcp;WAN:tpid:34984,bridge:tagged:200-n;LAN1-LAN2:u-WAN:tpid:34984'`
- Example 2: `'bridge:wan-tagged:2-n;LAN4-WAN:tpid:34984,bridge:tagged:1006-dhcp;WAN'`
- Example 3: `'route:vlan:300-mgmt;WAN:tpid:33024,route:vlan:100-inet;WAN:tpid:33024,route:vlan:200-iptv;WAN,bridge:transparent-static;ALL_LAN'`
- TPID can be specified as shown above, and it will be set for the vlan device section. If only one vlan device section will be created, then tpid will be set in that section (for example: `bridge:transparent-qinq:2-n-d;LAN4-WAN` will have only one 8021ad device section in uci, and non-qinq interface types are other examples).
- For other qinq scenarios where there will be one 8021ad and one 8021q section, tpid will be set in the 8021ad section.
- TPID will be ignored for non-vlan interfaces, and bridge-vlan.

### Device Name Resolution

Port macros (LAN, LAN1-LAN8, WAN, EXT) are automatically resolved to actual device names:
- `LAN` → `uci get network.LAN.name` → e.g., `eth1` (single LAN port devices)
- `LAN1` → `uci get network.LAN1.name` → e.g., `eth1` (multi-port devices)
- `WAN` → `uci get network.WAN.name` → e.g., `ae_wan`
- `EXT` → `uci get network.EXT.name` → e.g., `eth5`

If UCI device section doesn't exist, the system falls back to board.json.

---

## TR-069/USP Configuration

### TR-181 Data Model Mapping

The advanced mode uses three arguments in TR-181:

1. **SupportedArguments.1** = `interface_configs`

### Example 1: Transparent Bridge via TR-069

```xml
<SetParameterValues>
  <ParameterList>
    <ParameterValueStruct>
      <Name>Device.X_IOWRT_EU_NetMode.Mode</Name>
      <Value>advanced</Value>
    </ParameterValueStruct>
    <ParameterValueStruct>
      <Name>Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.1.Value</Name>
      <Value>bridge:transparent;ALL</Value>
    </ParameterValueStruct>
  </ParameterList>
</SetParameterValues>
```

### Example 2: Routed Multi-Service via TR-069

```xml
<SetParameterValues>
  <ParameterList>
    <ParameterValueStruct>
      <Name>Device.X_IOWRT_EU_NetMode.Mode</Name>
      <Value>advanced</Value>
    </ParameterValueStruct>
    <ParameterValueStruct>
      <Name>Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.1.Value</Name>
      <Value>route:vlan:100;WAN,route:vlan:200;WAN,route:vlan:300;WAN</Value>
    </ParameterValueStruct>
  </ParameterList>
</SetParameterValues>
```

### Example 3: QinQ Bridge via TR-069

```xml
<SetParameterValues>
  <ParameterList>
    <ParameterValueStruct>
      <Name>Device.X_IOWRT_EU_NetMode.Mode</Name>
      <Value>advanced</Value>
    </ParameterValueStruct>
    <ParameterValueStruct>
      <Name>Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.1.Value</Name>
      <Value>bridge:qinq:10:100-n;LAN1-LAN2-WAN,bridge:qinq:20:100-n;LAN1-LAN2-WAN</Value>
    </ParameterValueStruct>
  </ParameterList>
</SetParameterValues>
```

---

## Troubleshooting

### Issue: VLANs Not Working

**Diagnosis**:
```bash
# Check VLAN devices created
uci show network | grep 8021q

# Check interface status
ip link show
ip addr show

# Verify VLAN traffic
tcpdump -i eth4 -e -n vlan
```

**Solution**:
```bash
# Ensure kernel module loaded
modprobe 8021q
lsmod | grep 8021

# Check switch configuration (if applicable)
swconfig dev switch0 show
```

---

### Issue: QinQ Not Working

**Diagnosis**:
```bash
# Check for 8021ad devices
uci show network | grep 8021ad

# Verify kernel support
modprobe 8021q
lsmod | grep 8021
```

**Solution**:
```bash
# Install QinQ support
opkg install kmod-8021q

# Verify S-tag ethertype (0x88a8)
tcpdump -i eth4 -e -n -xx vlan
```

---

### Issue: MACVLAN Interface Not Getting IP

**Diagnosis**:
```bash
# Check MACVLAN device
ip link show | grep macvlan

# Check MAC address
ip link show <interface>_macvlan | grep ether

# Test DHCP
udhcpc -i <interface>_macvlan -n
```

**Solution**:
```bash
# Verify passthru mode
uci show network | grep -A5 macvlan

# Ensure MAC is unique
# Some ISPs require specific MAC format
```

---

### Issue: Mixed Bridge/Route Not Working

**Diagnosis**:
```bash
# Check firewall status
uci show firewall.globals.enabled

# Verify interfaces
ip addr show

# Check routing table
ip route show
```

**Solution**:
Firewall is always enabled. For debugging:
```bash
# Temporarily disable firewall
uci set firewall.globals.enabled='0'
uci commit firewall
/etc/init.d/firewall restart
```

---

### Issue: Port Not Added to Bridge

**Diagnosis**:
```bash
# Check UCI device resolution
uci get network.LAN1.name

# Check bridge ports
brctl show

# Check UCI bridge configuration
uci show network | grep -A10 "type='bridge'"
```

**Solution**:
```bash
# Verify device sections exist
uci show network | grep "device="

# Check board.json for defaults
cat /etc/board.json | grep -A20 network
```

---

## Verification Commands

### Check Configuration

```bash
# View current mode
cat /etc/netmodes/.last_mode

# View netmode configuration
uci show netmode

# View network configuration
uci show network

# View environment variables (during mode switch)
logread | grep "Interface names:"
```

### Check Interface Status

```bash
# All interfaces
ip addr show

# Bridges
brctl show
bridge link show

# VLAN devices
ip -d link show type vlan

# MACVLAN devices
ip -d link show type macvlan
```

### Check Connectivity

```bash
# DHCP on interface
udhcpc -i wan -n

# Ping gateway
ping -c 3 $(ip route | grep default | awk '{print $3}')

# DNS resolution
nslookup google.com

# VLAN traffic capture
tcpdump -i eth4 -e -n vlan
```

### Check Logs

```bash
# Netmode logs
logread | grep netmode-advanced

# Network logs
logread | grep network

# Live monitoring
logread -f | grep -E "(netmode|network)"
```

---

## Migration from Old Modes

### From `bridged` Mode

**Old Configuration**:
```bash
uci set netmode.global.mode='bridged'
uci set netmode.@supported_args[0].value='wan'
uci set netmode.@supported_args[1].value='transparent'
uci set netmode.@supported_args[2].value='ALL'
```

**New Configuration**:
```bash
uci set netmode.global.mode='advanced'
uci set netmode.@supported_args[12].value='wan'
uci set netmode.@supported_args[13].value='bridge:transparent'
uci set netmode.@supported_args[14].value='ALL'
```

**Change**: Add `bridge:` prefix to interface type.

---

### From `routed-multi-service` Mode

**Old Configuration**:
```bash
uci set netmode.global.mode='routed-multi-service'
uci set netmode.@supported_args[0].value='100'  # inet_vlanid
uci set netmode.@supported_args[2].value='200'  # iptv_vlanid
uci set netmode.@supported_args[4].value='300'  # mgmt_vlanid
```

**New Configuration**:
```bash
uci set netmode.global.mode='advanced'
uci set netmode.@supported_args[12].value='wan,iptv,mgmt'
uci set netmode.@supported_args[13].value='route:vlan:100,route:vlan:200,route:vlan:300'
uci set netmode.@supported_args[14].value='WAN,WAN,WAN'
```

**Change**: Explicit interface names and unified syntax.

---

## Best Practices

1. **VLAN Planning**: Document all VLAN IDs before deployment
2. **Port Assignment**: Create clear mapping of ports to services
3. **Testing**: Test on lab environment before production
4. **Monitoring**: Use `tcpdump` to verify VLAN tags
5. **Firewall**: Be aware that routed interfaces enable firewall
6. **Naming**: Use descriptive interface names (iptv, mgmt, voip)
7. **Documentation**: Keep ISP-specific requirements documented
8. **Backup**: Always backup configuration before major changes

---

**Document Version**: 1.0
**Package Version**: 1.1.11+
**Last Updated**: 2024-12-12
**Mode Status**: Production Ready