From 341ac893ff62441c2d8e7b0315bfbd94ce796d4f Mon Sep 17 00:00:00 2001 From: Sukru Senli Date: Fri, 26 Dec 2025 13:20:24 +0000 Subject: [PATCH] netmode: add advanced mode with bridge VLAN/QinQ and multi-service support --- netmode/README.md | 109 -- netmode/docs/ADVANCED_MODE_GUIDE.md | 901 ++++++++++ netmode/docs/ADVANCED_MODE_IMPLEMENTATION.md | 567 ++++++ netmode/docs/ADVANCED_MODE_QUICK_REFERENCE.md | 313 ++++ netmode/docs/BRIDGE_VLAN_FILTERING.md | 333 ++++ netmode/docs/BRVLAN_MIXED_MODE_EXAMPLES.md | 318 ++++ netmode/docs/CONFIGURATION_SCENARIOS.md | 739 ++++++++ netmode/docs/DEVELOPER_GUIDE.md | 1220 +++++++++++++ netmode/docs/IMPLEMENTATION_GUIDE.md | 1038 +++++++++++ netmode/docs/README.md | 422 +++++ netmode/docs/USER_GUIDE.md | 887 +++++++++ netmode/docs/VALIDATION_AND_ERROR_HANDLING.md | 294 +++ netmode/files/etc/init.d/netmode | 124 +- .../etc/netmodes/advanced/scripts/10-advanced | 577 ++++++ .../etc/netmodes/bridged/scripts/10-bridged | 118 -- .../routed-dhcp/scripts/10-routed-dhcp | 28 +- .../routed-pppoe/scripts/10-routed-pppoe | 28 +- .../routed-static/scripts/10-routed-static | 28 +- .../files/etc/netmodes/supported_modes.json | 34 + netmode/files/lib/netmode/advanced_helper.sh | 1584 +++++++++++++++++ .../files/lib/netmode/post/10-dhcp_options.sh | 64 + .../files/lib/netmode/post/15-static_lan.sh | 53 + .../lib/netmode/post/99-datamodel_init.sh | 57 + .../files/lib/netmode/post/datamodel_init.sh | 21 - .../lib/netmode/pre/10-restore_defaults.sh | 72 + 25 files changed, 9574 insertions(+), 355 deletions(-) delete mode 100644 netmode/README.md create mode 100644 netmode/docs/ADVANCED_MODE_GUIDE.md create mode 100644 netmode/docs/ADVANCED_MODE_IMPLEMENTATION.md create mode 100644 netmode/docs/ADVANCED_MODE_QUICK_REFERENCE.md create mode 100644 netmode/docs/BRIDGE_VLAN_FILTERING.md create mode 100644 netmode/docs/BRVLAN_MIXED_MODE_EXAMPLES.md create mode 100644 netmode/docs/CONFIGURATION_SCENARIOS.md create mode 100644 netmode/docs/DEVELOPER_GUIDE.md create mode 100644 netmode/docs/IMPLEMENTATION_GUIDE.md create mode 100644 netmode/docs/README.md create mode 100644 netmode/docs/USER_GUIDE.md create mode 100644 netmode/docs/VALIDATION_AND_ERROR_HANDLING.md create mode 100755 netmode/files/etc/netmodes/advanced/scripts/10-advanced delete mode 100644 netmode/files/etc/netmodes/bridged/scripts/10-bridged create mode 100644 netmode/files/lib/netmode/advanced_helper.sh create mode 100755 netmode/files/lib/netmode/post/10-dhcp_options.sh create mode 100644 netmode/files/lib/netmode/post/15-static_lan.sh create mode 100644 netmode/files/lib/netmode/post/99-datamodel_init.sh delete mode 100644 netmode/files/lib/netmode/post/datamodel_init.sh create mode 100644 netmode/files/lib/netmode/pre/10-restore_defaults.sh diff --git a/netmode/README.md b/netmode/README.md deleted file mode 100644 index a96c26c38..000000000 --- a/netmode/README.md +++ /dev/null @@ -1,109 +0,0 @@ -# Creating Custom Netmodes in IOWRT - -This guide provides developers with detailed instructions on how to create and manage custom network modes (netmodes) in IOWRT. The `netmode` script allows for flexible network configuration, and developers can define their own modes by structuring the necessary files and scripts within the `/etc/netmodes/` directory. - -## Table of Contents -1. [Overview of Netmodes](#overview-of-netmodes) -2. [Directory Structure](#directory-structure) -3. [Creating a Custom Netmode](#creating-a-custom-netmode) - - [Step 1: Pre-Execution Scripts](#step-1-pre-execution-scripts) - - [Step 2: UCI Configuration Files](#step-2-uci-configuration-files) - - [Step 3: Custom Execution Scripts](#step-3-custom-execution-scripts) - - [Step 4: Post-Execution Scripts](#step-4-post-execution-scripts) -4. [Enabling and Switching Netmodes](#enabling-and-switching-netmodes) - -## Overview of Netmodes - -Netmodes in IOWRT provide a way to switch between different network configurations based on the needs of the environment. Developers can create custom netmodes by organizing scripts and configuration files in specific directories under `/etc/netmodes/`. - -## Directory Structure - -A custom netmode is defined within the `/etc/netmodes/` directory, which should contain the following subdirectories: - -- **/lib/netmode/pre/**: Generic scripts executed before the netmode-specific configurations are applied. -- **/etc/netmodes//uci/**: Contains UCI configuration files that will be copied to `/etc/config/` during the application of the netmode. -- **/etc/netmodes//scripts/**: Custom scripts specific to the netmode that are executed after the UCI configurations are applied. -- **/lib/netmode/post/**: Generic scripts executed after the netmode-specific configurations are completed. - -## Creating a Custom Netmode - -To create a new netmode, follow these steps: - -### Step 1: Pre-Execution Scripts - -Scripts located in `/lib/netmode/pre/` are executed before any mode-specific actions. These are typically used for preparing the system or cleaning up configurations from the previous netmode. - -- **Create Pre-Execution Scripts**: - - Place your generic pre-execution scripts in `/lib/netmode/pre/`. - - Example script (`/lib/netmode/pre/cleanup.sh`): - ```bash - #!/bin/sh - echo "Cleaning up old network configurations..." - # Add commands here - ``` - -### Step 2: UCI Configuration Files - -The UCI configuration files stored in `/etc/netmodes//uci/` will be copied to `/etc/config/`, effectively applying the desired network configuration. - -- **Place UCI Config Files**: - - Create UCI configuration files under `/etc/netmodes//uci/`. - - Example (`/etc/netmodes/bridge/uci/network`): -````bash -config device 'br_lan' - option name 'br-lan' - option type 'bridge' - option multicast_to_unicast '0' - option bridge_empty '1' - list ports 'eth1' - list ports 'eth3' - list ports 'eth4' - -config interface 'lan' - option proto 'dhcp' - option device 'br-lan' - option force_link '1' - option reqopts '43 125' -```` - -### Step 3: Custom Execution Scripts - -After the UCI files are applied, any scripts in `/etc/netmodes//scripts/` are executed. These can be used to perform additional configuration tasks that are specific to the netmode. - -- **Create Custom Scripts**: - - Add scripts to `/etc/netmodes//scripts/`. - - Example (`/etc/netmodes/bridge/scripts/setup_bridge.sh`): - ```bash - #!/bin/sh - echo "Setting up bridge mode..." - # Additional configuration commands here - ``` - -### Step 4: Post-Execution Scripts - -Finally, the generic scripts in `/lib/netmode/post/` are executed. These scripts typically finalize the setup or perform any necessary cleanups. - -- **Create Post-Execution Scripts**: - - Place scripts in `/lib/netmode/post/`. - - Example script (`/lib/netmode/post/restart_services.sh`): - ```bash - #!/bin/sh - echo "Restarting network services..." - # Add commands here - ``` - -## Enabling and Switching Netmodes - -The netmode mechanism can be enabled or disabled via the UCI configuration, and you can switch between netmodes using UCI commands. - -- **Enable Netmode**: - ```bash - uci set netmode.global.enabled=1 - uci commit netmode - ``` - -- **Switch Netmode**: - ```bash - uci set netmode.global.mode='' - uci commit netmode - ``` diff --git a/netmode/docs/ADVANCED_MODE_GUIDE.md b/netmode/docs/ADVANCED_MODE_GUIDE.md new file mode 100644 index 000000000..1bc4abcfa --- /dev/null +++ b/netmode/docs/ADVANCED_MODE_GUIDE.md @@ -0,0 +1,901 @@ +# 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) +- **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_names` | Comma-separated interface names | `wan,iptv,mgmt` | +| `interface_types` | Comma-separated interface types | `bridge:transparent,brvlan:wan-tagged:1499,route:vlan:100,direct:200` | +| `ports` | Comma-separated port assignments | `ALL,LAN1-LAN2-WAN,WAN` | +| `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=none by default). + +| Type | Syntax | Description | +|------|--------|-------------| +| **Direct VLAN** | `direct:VID` | Standalone VLAN interface, proto=none | + +### Device Reference Types + +Device reference types allow multiple interfaces to share the same underlying device. + +| Type | Syntax | Description | +|------|--------|-------------| +| **Device Reference** | `device-ref:INTERFACE` | References the device from another 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 +interface_names='wan,wan6' +interface_types='bridge:tagged:2501,device-ref:wan-dhcpv6' +ports='WAN,WAN' +``` + +**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. + +### 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` | +| `-disabled`, `-d` | Create but mark as disabled | `route:vlan:200-disabled` or `route:vlan:200-d` | + + +#### Notes + +- 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, inet and mgmt modifier can only be used with route interfaces, and they can be clubbed with disabled modifier, but disable should be in the last. + +#### 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_names='lan,wan' +interface_types='bridge:transparent-static,bridge:tagged:2501' +ports='ALL_LAN,WAN' +``` + +For non-LAN interfaces with `-static`, only `proto=static` is set without additional configuration. + +**Note**: Direct interfaces default to `proto=none`, so `-n` is implicit. + +### 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='wan' # interface_names +uci set netmode.@supported_args[13].value='bridge:transparent' # interface_types +uci set netmode.@supported_args[14].value='ALL' # ports +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='lan,wan' +uci set netmode.@supported_args[13].value='bridge:transparent,route:transparent' +uci set netmode.@supported_args[14].value='ALL_LAN,WAN' +uci commit netmode +service netmode restart +``` + +**Result**: Creates `br-lan` bridge with all LAN ports only, WAN routed separately + +--- + +### 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='mgmt' +uci set netmode.@supported_args[13].value='bridge:tagged:100' +uci set netmode.@supported_args[14].value='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='inet,iptv,mgmt' +uci set netmode.@supported_args[13].value='bridge:tagged:100-n,bridge:tagged:200-n,bridge:tagged:300' +uci set netmode.@supported_args[14].value='LAN1-LAN2-WAN,LAN3-LAN4-WAN,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='customer_a,customer_b' +uci set netmode.@supported_args[13].value='bridge:qinq:10:100-n,bridge:qinq:20:100-n' +uci set netmode.@supported_args[14].value='LAN1-LAN2-WAN,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='mgmt_wan,wan,iptv_wan,lan' +uci set netmode.@supported_args[13].value='route:macvlan:BaseMACAddressP2-mgmt,route:macvlan:BaseMACAddressP3-inet,route:macvlan:BaseMACAddressP4-iptv,bridge:transparent-static' +uci set netmode.@supported_args[14].value='WAN,WAN,WAN,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='mgmt_wan,wan,iptv_wan,lan' +uci set netmode.@supported_args[13].value='route:vlan:300-mgmt,route:vlan:100-inet,route:vlan:200-iptv,bridge:transparent-static' +uci set netmode.@supported_args[14].value='WAN,WAN,WAN,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='wan,iptv' +uci set netmode.@supported_args[13].value='route:transparent,route:macvlan:BaseMACAddressP1' +uci set netmode.@supported_args[14].value='WAN,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,route:macvlan:AA:BB:CC:DD:EE:FF' +``` + +--- + +### 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='wan,iptv' +uci set netmode.@supported_args[13].value='route:vlan:100,route:vlan:200:AA:BB:CC:DD:EE:FF' +uci set netmode.@supported_args[14].value='WAN,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='wan' +uci set netmode.@supported_args[13].value='direct:2501' +uci set netmode.@supported_args[14].value='WAN' +uci commit netmode +service netmode restart +``` + +**Result**: Creates WAN.2501 interface, proto=none (no 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='wan,iptv' +uci set netmode.@supported_args[13].value='route:vlan:100,bridge:tagged:200-n' +uci set netmode.@supported_args[14].value='WAN,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='wan,iptv,voip' +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' +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='wan,iptv,voip' +uci set netmode.@supported_args[13].value='route:transparent,route:macvlan:AA:BB:CC:DD:EE:01,route:macvlan:AA:BB:CC:DD:EE:02' +uci set netmode.@supported_args[14].value='WAN,WAN,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='guest,corporate,mgmt' +uci set netmode.@supported_args[13].value='bridge:tagged:100-n,bridge:tagged:200-n,bridge:tagged:300' +uci set netmode.@supported_args[14].value='LAN1-WAN,LAN2-LAN3-WAN,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='cust_a,cust_b,cust_c' +uci set netmode.@supported_args[13].value='bridge:qinq:10:100-n,bridge:qinq:20:100-n,bridge:qinq:30:100-n' +uci set netmode.@supported_args[14].value='LAN1-LAN2-WAN,LAN3-LAN4-WAN,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='wan,iptv' +uci set netmode.@supported_args[13].value='route:vlan:100,bridge:tagged:200-n' +uci set netmode.@supported_args[14].value='WAN,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-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". + +### 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_names` +2. **SupportedArguments.2** = `interface_types` +3. **SupportedArguments.3** = `ports` + +### Example 1: Transparent Bridge via TR-069 + +```xml + + + + Device.X_IOWRT_EU_NetMode.Mode + advanced + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.1.Value + wan + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.2.Value + bridge:transparent + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.3.Value + ALL + + + +``` + +### Example 2: Routed Multi-Service via TR-069 + +```xml + + + + Device.X_IOWRT_EU_NetMode.Mode + advanced + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.1.Value + wan,iptv,mgmt + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.2.Value + route:vlan:100,route:vlan:200,route:vlan:300 + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.3.Value + WAN,WAN,WAN + + + +``` + +### Example 3: QinQ Bridge via TR-069 + +```xml + + + + Device.X_IOWRT_EU_NetMode.Mode + advanced + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.1.Value + customer_a,customer_b + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.2.Value + bridge:qinq:10:100-n,bridge:qinq:20:100-n + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.3.Value + LAN1-LAN2-WAN,LAN3-LAN4-WAN + + + +``` + +--- + +## 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 _macvlan | grep ether + +# Test DHCP +udhcpc -i _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 diff --git a/netmode/docs/ADVANCED_MODE_IMPLEMENTATION.md b/netmode/docs/ADVANCED_MODE_IMPLEMENTATION.md new file mode 100644 index 000000000..16b940fff --- /dev/null +++ b/netmode/docs/ADVANCED_MODE_IMPLEMENTATION.md @@ -0,0 +1,567 @@ +# Advanced Mode - Implementation Summary + +## Overview + +The **advanced** mode is a unified network configuration mode that consolidates and extends the functionality of the previous `bridged` and `routed-multi-service` modes into a single, flexible interface. + +## Design Rationale + +### Problems with Old Approach + +1. **Mode Fragmentation**: Separate modes for bridged and routed scenarios +2. **Limited Flexibility**: Couldn't mix bridges and routed interfaces +3. **Confusing Naming**: "bridged" mode actually supported standalone interfaces too +4. **Parameter Proliferation**: routed-multi-service had 6+ parameters for just 3 services +5. **No Scalability**: Adding new services required new parameters + +### New Unified Approach + +The advanced mode uses a **declarative, array-based configuration**: + +``` +interface_names: wan, iptv, mgmt +interface_types: route:vlan:100, bridge:tagged:200, direct:300 +ports: WAN, LAN1-LAN2-WAN, WAN +``` + +**Benefits**: +- ✅ Single mode for all scenarios +- ✅ Scalable (add N interfaces without new parameters) +- ✅ Flexible (mix bridge/route/standalone) +- ✅ Intuitive syntax +- ✅ Self-documenting configuration + +## Architecture + +### File Structure + +``` +netmode/ +├── files/ +│ ├── etc/netmodes/advanced/ +│ │ └── scripts/ +│ │ └── 10-advanced # Main mode script +│ ├── lib/netmode/ +│ │ └── advanced_helper.sh # Helper library +│ └── etc/netmodes/supported_modes.json +└── docs/ + ├── ADVANCED_MODE_GUIDE.md # Complete guide + └── ADVANCED_MODE_QUICK_REFERENCE.md +``` + +### Components + +#### 1. advanced_helper.sh + +**Purpose**: Core library for interface creation + +**Key Functions**: +- `parse_interface_type()` - Parse interface type specifications +- `create_bridge()` - Create bridge interfaces with VLAN/QinQ +- `create_routed_interface()` - Create routed interfaces with VLAN/MACVLAN +- `create_standalone_interface()` - Create direct VLAN interfaces +- `parse_port_list()` - Resolve port macros to device names +- `resolve_device_name()` - Resolve LAN1/WAN to actual device names +- `cleanup_interfaces()` - Clean up all interfaces before applying new config + +#### 2. 10-advanced Script + +**Purpose**: Main mode script + +**Flow**: +1. Parse environment variables (NETMODE_*) +2. Split comma-separated values +3. Loop through each interface +4. Parse interface type +5. Call appropriate creation function (bridge/route/direct) +6. Configure multicast, DHCP, firewall +7. Update service dependencies + +#### 3. supported_modes.json + +**Purpose**: Mode definition for UCI import + +**Configuration**: +```json +{ + "name": "advanced", + "description": "Advanced Mode - Unified configuration...", + "supported_args": [ + { + "name": "interface_names", + "description": "Interface names (comma-separated...)", + "type": "string" + }, + ... + ] +} +``` + +## Interface Type Syntax + +### Design Philosophy + +**Format**: `MODE:SUBTYPE[:PARAMS][:MODIFIERS]` + +Examples: +- `bridge:transparent` - Mode=bridge, Subtype=transparent +- `bridge:tagged:100` - Mode=bridge, Subtype=tagged, Param=VID +- `route:vlan:100:AA:BB:CC:DD:EE:FF` - Mode=route, Subtype=vlan, Params=VID+MAC +- `direct:2501-n` - Mode=direct, Param=VID, Modifier=proto_none + +### Parsing Logic + +The `parse_interface_type()` function: + +1. **Extract modifiers** (-n, -d) +2. **Parse mode prefix** (bridge:/route:/direct:) +3. **Parse subtype** (transparent/tagged/vlan/macvlan) +4. **Parse parameters** (VID, SVID, MAC address) +5. **Export to environment variables** for caller + +## UCI Device Resolution + +### Problem + +Port macros (LAN1, LAN2, WAN) are logical names that need to be mapped to actual hardware interfaces. + +### Solution + +```bash +resolve_device_name() { + local device_id="$1" + local resolved_name="" + + # Try UCI device section + resolved_name="$(uci -q get network.${device_id}.name)" + + # Fallback to input + if [ -z "$resolved_name" ]; then + resolved_name="$device_id" + fi + + echo "$resolved_name" +} +``` + +**Example**: +``` +LAN1 → uci get network.LAN1.name → eth1 +WAN → uci get network.WAN.name → ae_wan +``` + +### Port List Resolution + +The `parse_port_list()` function: + +1. **Check for "ALL"** → Resolve all LAN1-8 + WAN +2. **Parse dash-separated** → LAN1-LAN2-WAN → resolve each +3. **Return space-separated** → "eth1 eth2 ae_wan" + +## VLAN Device Creation + +### 802.1Q (C-tag) + +```bash +create_vlan_device "eth0" "100" "8021q" +``` + +Creates: +``` +config device 'eth0__100' + option type '8021q' + option enabled '1' + option vid '100' + option ifname 'eth0' + option name 'eth0.100' +``` + +### 802.1ad (S-tag) + +```bash +create_vlan_device "eth0" "300" "8021ad" +``` + +Creates: +``` +config device 'eth0__300' + option type '8021ad' + option enabled '1' + option vid '300' + option ifname 'eth0' + option name 'eth0.300' +``` + +### QinQ (Double Tagging) + +For `bridge:qinq:100:300`: + +```bash +# Create S-tag first +svlan=$(create_vlan_device "eth0" "300" "8021ad") # eth0.300 + +# Create C-tag on top of S-tag +cvlan=$(create_vlan_device "$svlan" "100" "8021q") # eth0.300.100 +``` + +Result: `eth0.300.100` (S-tag 300, C-tag 100) + +## MACVLAN Device Creation + +For `route:macvlan:AA:BB:CC:DD:EE:FF`: + +```bash +create_macvlan_device "ae_wan" "AA:BB:CC:DD:EE:FF" "iptv" +``` + +Creates: +``` +config device 'iptv_macvlan' + option type 'macvlan' + option enabled '1' + option ifname 'ae_wan' + option name 'iptv_macvlan' + option macaddr 'AA:BB:CC:DD:EE:FF' + option mode 'passthru' +``` + +## Bridge Creation + +### Transparent Bridge + +For `bridge:transparent` with `ports='ALL'`: + +```bash +create_bridge "wan" "bridge:transparent" "ALL" +``` + +Creates: +``` +config interface 'wan' + option proto 'dhcp' + option device 'br-wan' + +config device 'br_wan' + option name 'br-wan' + option type 'bridge' + option bridge_empty '1' + list ports 'eth1' + list ports 'eth2' + list ports 'ae_wan' +``` + +### VLAN-Tagged Bridge + +For `bridge:tagged:100` with `ports='ALL'`: + +Creates VLAN devices on all ports first, then adds to bridge: +``` +config device 'br_mgmt' + option name 'br-mgmt' + option type 'bridge' + list ports 'eth1.100' + list ports 'eth2.100' + list ports 'ae_wan.100' +``` + +## Routed Interface Creation + +For `route:vlan:100`: + +```bash +create_routed_interface "wan" "vlan" "100" "" "dhcp" "ae_wan" "0" +``` + +Creates: +``` +config device 'ae_wan__100' + option type '8021q' + option vid '100' + option ifname 'ae_wan' + option name 'ae_wan.100' + +config interface 'wan' + option proto 'dhcp' + option device 'ae_wan.100' +``` + +## Firewall Logic + +The advanced mode has **intelligent firewall handling**: + +```bash +configure_firewall() { + local has_routed=0 + + # Check if ANY interface is routed + for if_type in $interface_types; do + if echo "$if_type" | grep -q "^route:"; then + has_routed=1 + break + fi + done + + if [ "$has_routed" = "1" ]; then + uci set firewall.globals.enabled="1" # Enable for routed + else + uci set firewall.globals.enabled="0" # Disable for bridge-only + fi +} +``` + +**Logic**: +- If **any** interface is routed → Enable firewall +- If **all** interfaces are bridges → Disable firewall + +## Environment Variable Flow + +### Input (UCI → Environment) + +```bash +# In netmode init script +export NETMODE_interface_names="wan,iptv,mgmt" +export NETMODE_interface_types="route:vlan:100,route:vlan:200,route:vlan:300" +export NETMODE_ports="WAN,WAN,WAN" +``` + +### Parsing (Script) + +```bash +# In 10-advanced script +local interface_names="${NETMODE_interface_names:-wan}" +local interface_types="${NETMODE_interface_types:-bridge:transparent}" +local ports="${NETMODE_ports:-ALL}" + +# Split by comma +IFS=',' +for name in $interface_names; do + names_arr="$names_arr $name" +done +``` + +### Output (UCI Network Config) + +``` +config interface 'wan' + option proto 'dhcp' + option device 'ae_wan.100' + +config interface 'iptv' + option proto 'dhcp' + option device 'ae_wan.200' +... +``` + +## Cleanup Strategy + +Before applying new configuration, all existing interfaces are cleaned up: + +```bash +cleanup_interfaces() { + # Delete VLAN devices (8021q and 8021ad) + for vlandev_sec in $(uci show network | grep -E "\.type='(8021q|8021ad)'" ...); do + uci delete "$vlandev_sec" + done + + # Delete MACVLAN devices + for macvlandev_sec in $(uci show network | grep "\.type='macvlan'" ...); do + uci delete "$macvlandev_sec" + done + + # Delete bridge devices + for brdev_sec in $(uci show network | grep "\.type='bridge'" ...); do + uci delete "$brdev_sec" + done + + # Delete standard interfaces + uci delete network.lan + uci delete network.wan + uci delete network.wan6 +} +``` + +This ensures a clean slate for the new configuration. + +## Migration Path + +### From bridged Mode + +**Before**: +```bash +mode='bridged' +interface_names='wan,lan100' +interface_types='transparent,tagged:100' +ports='ALL,LAN1-LAN2' +``` + +**After**: +```bash +mode='advanced' +interface_names='wan,lan100' +interface_types='bridge:transparent,bridge:tagged:100' +ports='ALL,LAN1-LAN2' +``` + +**Change**: Add `bridge:` prefix to types. + +### From routed-multi-service Mode + +**Before**: +```bash +mode='routed-multi-service' +inet_vlanid='100' +iptv_vlanid='200' +mgmt_vlanid='300' +``` + +**After**: +```bash +mode='advanced' +interface_names='wan,iptv,mgmt' +interface_types='route:vlan:100,route:vlan:200,route:vlan:300' +ports='WAN,WAN,WAN' +``` + +**Change**: Explicit interface names and unified syntax. + +## Testing Approach + +### Unit Testing + +Test individual helper functions: + +```bash +# Test device resolution +resolve_device_name "LAN1" # Should return eth1 + +# Test port parsing +parse_port_list "LAN1-LAN2-WAN" # Should return "eth1 eth2 ae_wan" + +# Test type parsing +parse_interface_type "bridge:qinq:100:300-n" +# Should set: mode=bridge, vlan_type=qinq, cvid=100, svid=300, proto=none +``` + +### Integration Testing + +Test complete scenarios: + +```bash +# Test transparent bridge +uci set netmode.global.mode='advanced' +uci set netmode.@supported_args[0].value='wan' +uci set netmode.@supported_args[1].value='bridge:transparent' +uci set netmode.@supported_args[2].value='ALL' +uci commit netmode +service netmode restart + +# Verify +brctl show | grep br-wan +``` + +### Validation + +```bash +# Check UCI output +uci show network + +# Check actual interfaces +ip addr show +brctl show +ip -d link show type vlan + +# Check logs +logread | grep netmode-advanced +``` + +## Performance Considerations + +### Comma Splitting Optimization + +The script uses efficient IFS-based splitting: + +```bash +local OLD_IFS="$IFS" +IFS=',' +for name in $interface_names; do + names_arr="$names_arr $name" +done +IFS="$OLD_IFS" +``` + +This is faster than using `cut` or `awk` in loops. + +### UCI Batching + +All UCI commands are batched, with a single `uci commit` at the end: + +```bash +# Multiple uci set commands +uci set ... +uci set ... +uci set ... + +# Single commit +uci commit network +``` + +### Logging + +Logging is selective - info level for major steps, debug for details: + +```bash +_log "Creating interface $idx/$total_interfaces" # Info +logger -s -p user.debug -t "$_log_prefix" "Adding port: $port" # Debug +``` + +## Security Considerations + +### Input Validation + +- VLANs IDs: 1-4094 +- MAC addresses: Validated format +- Port names: Resolved through UCI (trusted source) + +### Privilege Separation + +- Script runs as root (required for network config) +- No user input directly executed +- Environment variables sanitized through UCI + +## Future Enhancements + +Possible future additions: + +1. **Static IP support**: `route:vlan:100:static:192.168.1.1` +2. **Port roles**: `ports='LAN1(tagged),LAN2(untagged)'` +3. **Bridge STP**: `bridge:transparent:stp` +4. **IPv6 specific**: `route:vlan:100:ipv6` +5. **Validation**: Pre-flight checks for VLAN conflicts + +## Backward Compatibility + +**Status**: ⚠️ Breaking change by design + +The old `bridged` and `routed-multi-service` modes are **replaced** by advanced mode. This is acceptable because: + +1. This is the **first deployment** of advanced features +2. No existing production deployments use old syntax +3. Cleaner architecture without legacy baggage +4. Documentation focuses on new syntax only + +## Summary + +The advanced mode represents a significant architectural improvement: + +- ✅ **Unified**: One mode for all scenarios +- ✅ **Scalable**: Array-based configuration +- ✅ **Flexible**: Mix bridges, routed, standalone +- ✅ **Intuitive**: Self-documenting syntax +- ✅ **Powerful**: VLAN, QinQ, MACVLAN support +- ✅ **Clean**: No backward compatibility burden + +--- + +**Implementation Version**: 1.0 +**Date**: 2024-12-12 +**Status**: Production Ready diff --git a/netmode/docs/ADVANCED_MODE_QUICK_REFERENCE.md b/netmode/docs/ADVANCED_MODE_QUICK_REFERENCE.md new file mode 100644 index 000000000..1c567d6e4 --- /dev/null +++ b/netmode/docs/ADVANCED_MODE_QUICK_REFERENCE.md @@ -0,0 +1,313 @@ +# Advanced Mode - Quick Reference + +## Interface Type Syntax + +### Bridge Types (Traditional VLAN Devices) +``` +bridge:transparent # No VLANs +bridge:tagged:VID # All ports tagged +bridge:wan-tagged:VID # Only WAN tagged +bridge:transparent-qinq:SVID # LAN untagged, WAN S-tag +bridge:transparent-qinq:C:S # LAN untagged, WAN C+S tags +bridge:tagged-qinq:C:S # LAN C-tag, WAN C+S tags +bridge:qinq:C:S # All ports C+S tags +``` + +### Bridge VLAN Filtering (Modern - Recommended) +``` +brvlan:tagged:VID # All ports tagged (bridge-vlan) +brvlan:wan-tagged:VID # WAN tagged, LAN untagged (bridge-vlan) +brvlan:mixed:VID # Custom tagging (bridge-vlan) +``` + +### Routed Types +``` +route:transparent # No VLAN, default MAC +route:vlan:VID # VLAN routing +route:macvlan:MAC # MACVLAN device (supports BaseMACAddress macros) +route:vlan:VID:MAC # VLAN + custom MAC +``` + +### Standalone Types +``` +direct:VID # Standalone VLAN (proto=none) +``` + +### Device Reference Types +``` +device-ref:INTERFACE # Reference device from another interface + # Allows multiple interfaces to share the same device + # Example: wan6 sharing wan's device +``` + +### Modifiers +``` +-pppoe # proto=pppoe (PPPoE authentication) +-dhcpv6 # proto=dhcpv6 (DHCPv6 client) +-dhcp # proto=dhcp (DHCP client - explicit, default if no suffix) +-static # proto=static (static IP configuration) +-none, -n # proto=none (no IP configuration) +-disabled, -d # disabled=1 (interface disabled) +``` + +**Default Protocol**: If no protocol modifier is specified, the interface defaults to `-dhcp`. + +**Note**: When using `-static` with interface name `lan`, the system automatically configures: +- IP: 192.168.1.1/24 +- IPv6 prefix delegation: /60 +- DHCP server: 192.168.1.100-250, 1h lease +- DHCPv6 and RA server enabled + +### MAC Address Macros +``` +BaseMACAddress # Base MAC from fw_printenv -n ethaddr +BaseMACAddressP1 # Base MAC + 1 +BaseMACAddressP2 # Base MAC + 2 +BaseMACAddressPN # Base MAC + N +AA:BB:CC:DD:EE:FF # Explicit MAC address +``` + +--- + +## Common Configurations + +### 1. Transparent Bridge +```bash +uci set netmode.global.mode='advanced' +uci set netmode.@supported_args[0].value='wan' +uci set netmode.@supported_args[1].value='bridge:transparent' +uci set netmode.@supported_args[2].value='ALL' +uci commit netmode && service netmode restart +``` + +### 2. Router Mode (LAN + WAN) +```bash +# LAN bridge with static IP + DHCP server, WAN bridge with DHCP client +uci set netmode.global.mode='advanced' +uci set netmode.@supported_args[0].value='lan,wan' +uci set netmode.@supported_args[1].value='bridge:transparent-static,bridge:tagged:2501' +uci set netmode.@supported_args[2].value='ALL_LAN,WAN' +uci commit netmode && service netmode restart +``` + +### 3. VLAN-Tagged Bridge +```bash +uci set netmode.global.mode='advanced' +uci set netmode.@supported_args[0].value='mgmt' +uci set netmode.@supported_args[1].value='bridge:tagged:100' +uci set netmode.@supported_args[2].value='ALL' +uci commit netmode && service netmode restart +``` + +### 4. Multiple Service Bridges +```bash +uci set netmode.global.mode='advanced' +uci set netmode.@supported_args[0].value='inet,iptv,mgmt' +uci set netmode.@supported_args[1].value='bridge:tagged:100-n,bridge:tagged:200-n,bridge:tagged:300' +uci set netmode.@supported_args[2].value='LAN1-LAN2-WAN,LAN3-LAN4-WAN,WAN' +uci commit netmode && service netmode restart +``` + +### 5. QinQ Configuration +```bash +uci set netmode.global.mode='advanced' +uci set netmode.@supported_args[0].value='customer_a,customer_b' +uci set netmode.@supported_args[1].value='bridge:qinq:10:100-n,bridge:qinq:20:100-n' +uci set netmode.@supported_args[2].value='LAN1-LAN2-WAN,LAN3-LAN4-WAN' +uci commit netmode && service netmode restart +``` + +### 6. Routed Multi-Service (VLAN) +```bash +uci set netmode.global.mode='advanced' +uci set netmode.@supported_args[0].value='wan,iptv,mgmt' +uci set netmode.@supported_args[1].value='route:vlan:100,route:vlan:200,route:vlan:300' +uci set netmode.@supported_args[2].value='WAN,WAN,WAN' +uci commit netmode && service netmode restart +``` + +### 7. Routed Multi-Service with Custom MAC Addresses +```bash +uci set netmode.global.mode='advanced' +uci set netmode.@supported_args[0].value='wan,iptv' +uci set netmode.@supported_args[1].value='route:transparent,route:transparent' +uci set netmode.@supported_args[2].value='WAN,WAN' +uci set netmode.@supported_args[3].value='BaseMACAddress,BaseMACAddressP1' +uci commit netmode && service netmode restart +``` + +### 8. IPv4 + IPv6 on Same Device (Device Reference) +```bash +# wan uses DHCP, wan6 uses DHCPv6 on the same bridge device +uci set netmode.global.mode='advanced' +uci set netmode.@supported_args[0].value='wan,wan6' +uci set netmode.@supported_args[1].value='bridge:tagged:2501,device-ref:wan-dhcpv6' +uci set netmode.@supported_args[2].value='WAN,WAN' +uci commit netmode && service netmode restart +``` + +### 9. Direct VLAN Interface +```bash +uci set netmode.global.mode='advanced' +uci set netmode.@supported_args[0].value='wan' +uci set netmode.@supported_args[1].value='direct:2501' +uci set netmode.@supported_args[2].value='WAN' +uci commit netmode && service netmode restart +``` + +### 10. Hybrid (Routed + Bridged) +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='wan,iptv' +uci set netmode.mode_4_supprted_args_2.value='route:vlan:100,bridge:tagged:200-n' +uci set netmode.mode_4_supprted_args_3.value='WAN,LAN1-LAN2-LAN3-WAN' +uci commit netmode && service netmode restart +``` + +### 11. Bridge VLAN Filtering (WAN Tagged) +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='internet' +uci set netmode.mode_4_supprted_args_2.value='brvlan:wan-tagged:1499' +uci set netmode.mode_4_supprted_args_3.value='LAN1-LAN2-WAN' +uci commit netmode && service netmode restart +``` + +### 12. Multiple Services with Bridge VLAN Filtering +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='internet,tv' +uci set netmode.mode_4_supprted_args_2.value='brvlan:wan-tagged:1499,brvlan:wan-tagged:1510-n' +uci set netmode.mode_4_supprted_args_3.value='LAN1-LAN2-WAN,LAN3-LAN4-WAN' +uci commit netmode && service netmode restart +``` + +--- + +## Port List Syntax + +| Syntax | Description | +|--------|-------------| +| `ALL` | All LAN + WAN + EXT ports (from UCI/board.json) | +| `ALL_LAN` | All LAN ports only (no WAN, no EXT) | +| `LAN` | Single LAN port (for devices with one LAN port) | +| `WAN` | WAN port only | +| `EXT` | EXT port only | +| `LAN-WAN` | Single LAN port and WAN | +| `LAN1-LAN2-WAN` | LAN1, LAN2, and WAN | +| `LAN1-LAN3-EXT` | LAN1, LAN3, and EXT | +| `WAN-EXT` | WAN and EXT ports | + +**Note**: `LAN` is used for devices with a single LAN port, while `LAN1-8` are used for devices with multiple numbered LAN ports. The system automatically detects which is present in UCI. + +--- + +## Verification Commands + +```bash +# Check current mode +cat /etc/netmodes/.last_mode + +# View configuration +uci show netmode + +# View network interfaces +ip addr show + +# View bridges +brctl show + +# View VLAN devices +ip -d link show type vlan + +# View MACVLAN devices +ip -d link show type macvlan + +# View logs +logread | grep netmode-advanced + +# Test DHCP +udhcpc -i wan -n + +# Capture VLAN traffic +tcpdump -i eth4 -e -n vlan +``` + +--- + +## Troubleshooting + +### Force mode reapply +```bash +rm /etc/netmodes/.last_mode +service netmode restart +``` + +### Check for errors +```bash +logread | grep -E "(error|ERROR|failed|FAILED)" +``` + +### Verify UCI syntax +```bash +uci show netmode +uci show network +``` + +### Reset to DHCP mode +```bash +uci set netmode.global.mode='routed-dhcp' +uci commit netmode +service netmode restart +``` + +--- + +## TR-181 Argument Mapping + +``` +Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.1.Value = interface_names +Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.2.Value = interface_types +Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.3.Value = ports +Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.4.Value = macaddrs +``` + +--- + +## Examples by Use Case + +### ISP Triple-Play (VLAN-based with MAC Addresses) +```bash +# Internet VLAN 100, IPTV VLAN 200, VoIP VLAN 300 with different MACs +uci set netmode.global.mode='advanced' +uci set netmode.@supported_args[0].value='wan,iptv,voip' +uci set netmode.@supported_args[1].value='route:vlan:100,route:vlan:200,route:vlan:300' +uci set netmode.@supported_args[2].value='WAN,WAN,WAN' +uci set netmode.@supported_args[3].value='BaseMACAddress,BaseMACAddressP1,BaseMACAddressP2' +uci commit netmode && service netmode restart +``` + +### Enterprise Guest + Corporate Networks +```bash +# Guest VLAN 100, Corporate VLAN 200, Management VLAN 300 +uci set netmode.global.mode='advanced' +uci set netmode.@supported_args[0].value='guest,corporate,mgmt' +uci set netmode.@supported_args[1].value='bridge:tagged:100-n,bridge:tagged:200-n,bridge:tagged:300' +uci set netmode.@supported_args[2].value='LAN1-WAN,LAN2-LAN3-WAN,WAN' +uci commit netmode && service netmode restart +``` + +### Wholesale QinQ Provider +```bash +# Multiple customers with different C-tags, same S-tag +uci set netmode.global.mode='advanced' +uci set netmode.@supported_args[0].value='cust_a,cust_b,cust_c' +uci set netmode.@supported_args[1].value='bridge:qinq:10:100-n,bridge:qinq:20:100-n,bridge:qinq:30:100-n' +uci set netmode.@supported_args[2].value='LAN1-LAN2-WAN,LAN3-LAN4-WAN,LAN5-LAN6-WAN' +uci commit netmode && service netmode restart +``` + +--- + +**Version**: 1.0 +**Last Updated**: 2024-12-12 diff --git a/netmode/docs/BRIDGE_VLAN_FILTERING.md b/netmode/docs/BRIDGE_VLAN_FILTERING.md new file mode 100644 index 000000000..aa6acc3ae --- /dev/null +++ b/netmode/docs/BRIDGE_VLAN_FILTERING.md @@ -0,0 +1,333 @@ +# Bridge VLAN Filtering Mode + +## Overview + +The advanced netmode now supports **bridge VLAN filtering**, a modern approach to VLAN configuration that uses the kernel's bridge VLAN filtering feature instead of creating separate VLAN devices. + +### Benefits + +- **Better Performance**: No need to create multiple VLAN devices +- **Cleaner Configuration**: Single bridge with VLAN filtering instead of multiple VLAN interfaces +- **Hardware Offloading**: Better support for hardware VLAN acceleration +- **Simplified Management**: All VLANs configured in one place + +## Syntax + +Use the `brvlan:` prefix instead of `bridge:` to enable bridge VLAN filtering: + +| Traditional Mode | Bridge VLAN Filtering Mode | +|------------------|---------------------------| +| `bridge:tagged:100` | `brvlan:tagged:100` | +| `bridge:wan-tagged:100` | `brvlan:wan-tagged:100` | +| N/A | `brvlan:mixed:100` | + +## Interface Types + +### `brvlan:tagged:VID` + +All ports are tagged with the specified VLAN ID. + +**Example**: +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='internet' +uci set netmode.mode_4_supprted_args_2.value='brvlan:tagged:1499' +uci set netmode.mode_4_supprted_args_3.value='ALL' +uci commit netmode && service netmode restart +``` + +**Resulting Configuration**: +``` +config interface 'internet' + option device 'br-internet.1499' + option proto 'dhcp' + +config device br_internet + option name 'br-internet' + option type 'bridge' + option vlan_filtering '1' + list ports 'ae_wan' + list ports 'eth0' + list ports 'eth1' + +config bridge-vlan brvlan_1499_internet + option device 'br-internet' + option vlan '1499' + list ports 'ae_wan:t' + list ports 'eth0:t' + list ports 'eth1:t' +``` + +--- + +### `brvlan:wan-tagged:VID` + +WAN port is tagged, LAN ports are untagged. + +**Example**: +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='iptv' +uci set netmode.mode_4_supprted_args_2.value='brvlan:wan-tagged:1510-n' +uci set netmode.mode_4_supprted_args_3.value='LAN1-LAN2-WAN' +uci commit netmode && service netmode restart +``` + +**Resulting Configuration**: +``` +config interface 'iptv' + option device 'br-iptv.1510' + option proto 'none' + +config device br_iptv + option name 'br-iptv' + option type 'bridge' + option vlan_filtering '1' + list ports 'ae_wan' + list ports 'eth0' + list ports 'eth1' + +config bridge-vlan brvlan_1510_iptv + option device 'br-iptv' + option vlan '1510' + list ports 'ae_wan:t' + list ports 'eth0:u' + list ports 'eth1:u' +``` + +--- + +### `brvlan:mixed:VID` or `brvlan:mixed:VID:TAGGED_PORTS` + +Custom tagged/untagged configuration with flexible port-specific tagging. + +**Syntax**: +- `brvlan:mixed:VID` - Default behavior: WAN tagged, LAN untagged +- `brvlan:mixed:VID:TAGGED_PORTS` - Specify which ports are tagged (e.g., `LAN1-WAN`) + +**Example 1: Default (WAN Tagged)**: +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='service' +uci set netmode.mode_4_supprted_args_2.value='brvlan:mixed:100' +uci set netmode.mode_4_supprted_args_3.value='LAN1-LAN2-WAN' +uci commit netmode && service netmode restart +``` + +**Result**: WAN tagged, LAN1 and LAN2 untagged + +**Example 2: Custom Tagging (LAN1 and WAN Tagged)**: +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='corporate' +uci set netmode.mode_4_supprted_args_2.value='brvlan:mixed:200:LAN1-WAN' +uci set netmode.mode_4_supprted_args_3.value='LAN1-LAN2-LAN3-WAN' +uci commit netmode && service netmode restart +``` + +**Resulting Configuration**: +``` +config bridge-vlan brvlan_200_corporate + option device 'br-corporate' + option vlan '200' + list ports 'eth0:t' # LAN1 tagged + list ports 'eth1:u' # LAN2 untagged + list ports 'eth2:u' # LAN3 untagged + list ports 'ae_wan:t' # WAN tagged +``` + +**See [BRVLAN_MIXED_MODE_EXAMPLES.md](BRVLAN_MIXED_MODE_EXAMPLES.md) for comprehensive examples.** + +--- + +## Comparison: Traditional vs Bridge VLAN Filtering + +### Traditional VLAN Device Approach (`bridge:tagged:100`) + +Creates separate VLAN devices for each port: + +``` +config device eth0_100 + option type '8021q' + option vid '100' + option ifname 'eth0' + option name 'eth0.100' + +config device wan_100 + option type '8021q' + option vid '100' + option ifname 'ae_wan' + option name 'ae_wan.100' + +config device br_internet + option type 'bridge' + list ports 'eth0.100' + list ports 'ae_wan.100' +``` + +### Bridge VLAN Filtering Approach (`brvlan:tagged:100`) + +Single bridge with VLAN filtering: + +``` +config device br_internet + option type 'bridge' + option vlan_filtering '1' + list ports 'eth0' + list ports 'ae_wan' + +config bridge-vlan brvlan_100_internet + option device 'br-internet' + option vlan '100' + list ports 'eth0:t' + list ports 'ae_wan:t' +``` + +--- + +## Use Cases + +### ISP Internet Service (VLAN 1499, WAN Tagged) + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='internet' +uci set netmode.mode_4_supprted_args_2.value='brvlan:wan-tagged:1499' +uci set netmode.mode_4_supprted_args_3.value='LAN1-LAN2-WAN' +uci commit netmode && service netmode restart +``` + +### IPTV Service (VLAN 1510, WAN Tagged, No DHCP) + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='tv' +uci set netmode.mode_4_supprted_args_2.value='brvlan:wan-tagged:1510-n' +uci set netmode.mode_4_supprted_args_3.value='LAN3-LAN4-WAN' +uci commit netmode && service netmode restart +``` + +### Multiple Services (Internet + IPTV) + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='internet,tv' +uci set netmode.mode_4_supprted_args_2.value='brvlan:wan-tagged:1499,brvlan:wan-tagged:1510-n' +uci set netmode.mode_4_supprted_args_3.value='LAN1-LAN2-WAN,LAN3-LAN4-WAN' +uci commit netmode && service netmode restart +``` + +### Corporate Network (All Ports Tagged) + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='corporate' +uci set netmode.mode_4_supprted_args_2.value='brvlan:tagged:100' +uci set netmode.mode_4_supprted_args_3.value='ALL' +uci commit netmode && service netmode restart +``` + +--- + +## Modifiers + +Bridge VLAN filtering modes support the same modifiers as traditional bridge modes: + +| Modifier | Effect | Example | +|----------|--------|---------| +| `-n` | Set proto=none (no DHCP client) | `brvlan:tagged:100-n` | +| `-d` | Create but mark as disabled | `brvlan:wan-tagged:200-d` | + +--- + +## Verification + +### Check Bridge VLAN Configuration + +```bash +# View bridge device +uci show network | grep "vlan_filtering" + +# View bridge-vlan sections +uci show network | grep "bridge-vlan" + +# View interface status +ip addr show + +# View bridge VLAN table +bridge vlan show +``` + +### Example Output + +```bash +root@router:~# bridge vlan show +port vlan-id +ae_wan 1499 Tagged +eth0 1499 Untagged +eth1 1499 Untagged +br-internet 1499 +``` + +--- + +## Limitations + +1. **No QinQ Support**: Bridge VLAN filtering does not currently support 802.1ad (QinQ) double tagging +2. **Single VLAN per Interface**: Each bridge-vlan section defines one VLAN +3. **Kernel Support Required**: Requires kernel with bridge VLAN filtering support + +--- + +## Migration from Traditional Bridge + +### Before (Traditional VLAN Devices) + +```bash +uci set netmode.mode_4_supprted_args_2.value='bridge:wan-tagged:100' +``` + +### After (Bridge VLAN Filtering) + +```bash +uci set netmode.mode_4_supprted_args_2.value='brvlan:wan-tagged:100' +``` + +Simply change the prefix from `bridge:` to `brvlan:`. + +--- + +## Troubleshooting + +### Check if VLAN Filtering is Enabled + +```bash +cat /sys/class/net/br-internet/bridge/vlan_filtering +# Should output: 1 +``` + +### View Bridge VLAN Table + +```bash +bridge vlan show dev br-internet +``` + +### Check Kernel Support + +```bash +# Check if bridge module supports vlan_filtering +cat /sys/module/bridge/parameters/vlan_filtering +``` + +### Enable Debug Logging + +```bash +# Monitor netmode logs +logread -f | grep netmode-advanced +``` + +--- + +**Version**: 1.0 +**Last Updated**: 2025-12-12 +**Feature Status**: Production Ready diff --git a/netmode/docs/BRVLAN_MIXED_MODE_EXAMPLES.md b/netmode/docs/BRVLAN_MIXED_MODE_EXAMPLES.md new file mode 100644 index 000000000..d1e0f7878 --- /dev/null +++ b/netmode/docs/BRVLAN_MIXED_MODE_EXAMPLES.md @@ -0,0 +1,318 @@ +# Bridge VLAN Filtering - Mixed Mode Examples + +## Overview + +The `brvlan:mixed` mode provides flexible control over which ports are tagged vs untagged in a bridge VLAN configuration. This is useful for complex scenarios where different ports need different VLAN tagging behavior. + +## Syntax + +### Basic Mixed Mode (Default Behavior) +``` +brvlan:mixed:VID +``` +**Behavior**: WAN tagged, LAN ports untagged (same as `brvlan:wan-tagged:VID`) + +### Custom Mixed Mode (Specify Tagged Ports) +``` +brvlan:mixed:VID:TAGGED_PORTS +``` +**Behavior**: Ports listed in `TAGGED_PORTS` are tagged, all others are untagged + +**TAGGED_PORTS Format**: Same as port list specification (`LAN1-LAN2-WAN`, `WAN`, etc.) + +--- + +## Examples + +### Example 1: Basic Mixed Mode (WAN Tagged by Default) + +**Scenario**: Internet service where WAN needs VLAN 100, LAN ports untagged + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='internet' +uci set netmode.mode_4_supprted_args_2.value='brvlan:mixed:100' +uci set netmode.mode_4_supprted_args_3.value='LAN1-LAN2-WAN' +uci commit netmode && service netmode restart +``` + +**Result**: +``` +config interface 'internet' + option device 'br-internet.100' + option proto 'dhcp' + +config device br_internet + option name 'br-internet' + option type 'bridge' + option vlan_filtering '1' + list ports 'eth0' # LAN1 + list ports 'eth1' # LAN2 + list ports 'ae_wan' # WAN + +config bridge-vlan brvlan_100_internet + option device 'br-internet' + option vlan '100' + list ports 'eth0:u' # LAN1 untagged + list ports 'eth1:u' # LAN2 untagged + list ports 'ae_wan:t' # WAN tagged +``` + +--- + +### Example 2: Only Specific LAN Ports Tagged + +**Scenario**: Enterprise network where LAN1 and WAN are tagged, LAN2 and LAN3 are untagged + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='corporate' +uci set netmode.mode_4_supprted_args_2.value='brvlan:mixed:200:LAN1-WAN' +uci set netmode.mode_4_supprted_args_3.value='LAN1-LAN2-LAN3-WAN' +uci commit netmode && service netmode restart +``` + +**Result**: +``` +config interface 'corporate' + option device 'br-corporate.200' + option proto 'dhcp' + +config device br_corporate + option name 'br-corporate' + option type 'bridge' + option vlan_filtering '1' + list ports 'eth0' # LAN1 + list ports 'eth1' # LAN2 + list ports 'eth2' # LAN3 + list ports 'ae_wan' # WAN + +config bridge-vlan brvlan_200_corporate + option device 'br-corporate' + option vlan '200' + list ports 'eth0:t' # LAN1 tagged (specified) + list ports 'eth1:u' # LAN2 untagged + list ports 'eth2:u' # LAN3 untagged + list ports 'ae_wan:t' # WAN tagged (specified) +``` + +--- + +### Example 3: All LAN Ports Tagged, WAN Untagged + +**Scenario**: Reverse scenario where LAN ports carry VLAN tags but WAN doesn't + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='service' +uci set netmode.mode_4_supprted_args_2.value='brvlan:mixed:300:LAN1-LAN2-LAN3' +uci set netmode.mode_4_supprted_args_3.value='LAN1-LAN2-LAN3-WAN' +uci commit netmode && service netmode restart +``` + +**Result**: +``` +config bridge-vlan brvlan_300_service + option device 'br-service' + option vlan '300' + list ports 'eth0:t' # LAN1 tagged + list ports 'eth1:t' # LAN2 tagged + list ports 'eth2:t' # LAN3 tagged + list ports 'ae_wan:u' # WAN untagged +``` + +--- + +### Example 4: Only WAN Tagged (Explicit) + +**Scenario**: Same as `wan-tagged` but using mixed mode explicitly + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='iptv' +uci set netmode.mode_4_supprted_args_2.value='brvlan:mixed:1510:WAN-n' +uci set netmode.mode_4_supprted_args_3.value='LAN3-LAN4-WAN' +uci commit netmode && service netmode restart +``` + +**Result**: +``` +config interface 'iptv' + option device 'br-iptv.1510' + option proto 'none' + +config bridge-vlan brvlan_1510_iptv + option device 'br-iptv' + option vlan '1510' + list ports 'eth2:u' # LAN3 untagged + list ports 'eth3:u' # LAN4 untagged + list ports 'ae_wan:t' # WAN tagged +``` + +--- + +### Example 5: Multi-Service with Different Tagging + +**Scenario**: Internet with LAN1+WAN tagged, IPTV with only WAN tagged + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='internet,tv' +uci set netmode.mode_4_supprted_args_2.value='brvlan:mixed:1499:LAN1-WAN,brvlan:mixed:1510:WAN-n' +uci set netmode.mode_4_supprted_args_3.value='LAN1-LAN2-WAN,LAN3-LAN4-WAN' +uci commit netmode && service netmode restart +``` + +**Result**: + +**Internet Service (VLAN 1499)**: +``` +config bridge-vlan brvlan_1499_internet + option device 'br-internet' + option vlan '1499' + list ports 'eth0:t' # LAN1 tagged + list ports 'eth1:u' # LAN2 untagged + list ports 'ae_wan:t' # WAN tagged +``` + +**TV Service (VLAN 1510)**: +``` +config bridge-vlan brvlan_1510_tv + option device 'br-tv' + option vlan '1510' + list ports 'eth2:u' # LAN3 untagged + list ports 'eth3:u' # LAN4 untagged + list ports 'ae_wan:t' # WAN tagged +``` + +--- + +### Example 6: Trunk Port Configuration + +**Scenario**: LAN1 as trunk port (tagged), others as access ports (untagged) + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='vlan100' +uci set netmode.mode_4_supprted_args_2.value='brvlan:mixed:100:LAN1' +uci set netmode.mode_4_supprted_args_3.value='LAN1-LAN2-LAN3-LAN4' +uci commit netmode && service netmode restart +``` + +**Result**: +``` +config bridge-vlan brvlan_100_vlan100 + option device 'br-vlan100' + option vlan '100' + list ports 'eth0:t' # LAN1 tagged (trunk port) + list ports 'eth1:u' # LAN2 untagged (access port) + list ports 'eth2:u' # LAN3 untagged (access port) + list ports 'eth3:u' # LAN4 untagged (access port) +``` + +--- + +## Comparison: Mixed Mode vs Other Modes + +| Mode | Syntax | Tagged Ports | Untagged Ports | +|------|--------|--------------|----------------| +| **tagged** | `brvlan:tagged:100` | ALL | None | +| **wan-tagged** | `brvlan:wan-tagged:100` | WAN only | All LAN | +| **mixed (default)** | `brvlan:mixed:100` | WAN only | All LAN | +| **mixed (custom)** | `brvlan:mixed:100:LAN1-WAN` | LAN1, WAN | All others | + +--- + +## Use Cases + +### Use Case 1: DMZ Configuration +- **LAN1**: Tagged (DMZ network with VLAN tag) +- **LAN2-4**: Untagged (local network) +- **WAN**: Tagged (ISP requirement) + +```bash +brvlan:mixed:100:LAN1-WAN +``` + +### Use Case 2: Guest Network +- **LAN1-2**: Tagged (guest WiFi APs that handle VLANs) +- **LAN3-4**: Untagged (local devices) +- **WAN**: Untagged (local ISP connection) + +```bash +brvlan:mixed:50:LAN1-LAN2 +``` + +### Use Case 3: Managed Switch Uplink +- **LAN1**: Tagged (uplink to managed switch) +- **LAN2-4**: Untagged (end user devices) +- **WAN**: Tagged (ISP VLAN) + +```bash +brvlan:mixed:200:LAN1-WAN +``` + +--- + +## Port Specification Reference + +When specifying tagged ports in mixed mode: + +| Specification | Resolves To | Example | +|---------------|-------------|---------| +| `WAN` | WAN device | `ae_wan` | +| `LAN1` | LAN1 device from UCI | `eth0` | +| `LAN1-LAN2` | LAN1 and LAN2 | `eth0`, `eth1` | +| `LAN1-WAN` | LAN1 and WAN | `eth0`, `ae_wan` | +| `ALL` | Not supported in tagged ports spec | Use `brvlan:tagged` instead | + +--- + +## Troubleshooting + +### Verify Port Tagging + +```bash +# View bridge VLAN table +bridge vlan show + +# Expected output shows :t (tagged) or :u (untagged) +port vlan-id +eth0 100 Tagged +eth1 100 Untagged +ae_wan 100 Tagged +``` + +### Check Configuration + +```bash +# View bridge-vlan sections +uci show network | grep bridge-vlan -A5 + +# Look for ports list with :t or :u suffixes +``` + +### Common Mistakes + +1. **Wrong Syntax**: Must use colon between VID and port spec + - ❌ `brvlan:mixed:100-LAN1-WAN` + - ✅ `brvlan:mixed:100:LAN1-WAN` + +2. **Using ALL**: Don't use ALL in tagged ports + - ❌ `brvlan:mixed:100:ALL` + - ✅ Use `brvlan:tagged:100` instead + +3. **Duplicate Ports**: Port appears in both bridge port list and tagged spec + - Ensure the port list in arg 3 includes all ports you reference in arg 2 + +--- + +## Advanced: Multiple VLANs on Same Bridge + +While this guide focuses on single VLAN per bridge, you can create multiple bridge-vlan sections manually after netmode configuration for trunk scenarios. However, this is beyond the scope of netmode automation. + +--- + +**Document Version**: 1.0 +**Last Updated**: 2025-12-12 +**Feature**: Bridge VLAN Filtering Mixed Mode diff --git a/netmode/docs/CONFIGURATION_SCENARIOS.md b/netmode/docs/CONFIGURATION_SCENARIOS.md new file mode 100644 index 000000000..72fffebd6 --- /dev/null +++ b/netmode/docs/CONFIGURATION_SCENARIOS.md @@ -0,0 +1,739 @@ +# Advanced Mode - Configuration Scenarios + +Complete examples for common use cases with both UCI and TR-181 configuration methods. + +--- + +## Scenario 1: Simple Home Router (Transparent Bridge) + +**Use Case**: All ports bridged together for simple home network + +**Network Topology**: +``` +All LAN ports + WAN → br-wan (no VLANs) +``` + +### UCI Configuration + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='wan' +uci set netmode.mode_4_supprted_args_2.value='bridge:transparent' +uci set netmode.mode_4_supprted_args_3.value='ALL' +uci commit netmode && service netmode restart +``` + +### TR-181 Configuration + +```xml + + + + Device.X_IOWRT_EU_NetMode.Mode + advanced + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.1.Value + wan + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.2.Value + bridge:transparent + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.3.Value + ALL + + + +``` + +**Result**: +- Single bridge interface `br-wan` +- All ports untagged +- DHCP client enabled + +--- + +## Scenario 2: Traditional LAN Bridge with Routed WAN + +**Use Case**: Classic router setup with LAN bridge and separate routed WAN + +**Network Topology**: +``` +All LAN ports → br-lan (bridge) +WAN port → wan (routed interface) +``` + +### UCI Configuration + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='lan,wan' +uci set netmode.mode_4_supprted_args_2.value='bridge:transparent,route:transparent' +uci set netmode.mode_4_supprted_args_3.value='ALL_LAN,WAN' +uci commit netmode && service netmode restart +``` + +### TR-181 Configuration + +```xml + + + + Device.X_IOWRT_EU_NetMode.Mode + advanced + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.1.Value + lan,wan + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.2.Value + bridge:transparent,route:transparent + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.3.Value + ALL_LAN,WAN + + + +``` + +**Result**: +- Bridge interface `br-lan` with all LAN ports only +- Routed interface `wan` on WAN port +- Traditional router topology + +--- + +## Scenario 3: ISP Internet Service (Single VLAN) + +**Use Case**: ISP requires VLAN 100 on WAN port for internet access + +**Network Topology**: +``` +WAN.100 (tagged) + LAN1-4 (untagged) → br-internet.100 +``` + +### UCI Configuration (Bridge VLAN Filtering - Recommended) + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='internet' +uci set netmode.mode_4_supprted_args_2.value='brvlan:wan-tagged:100' +uci set netmode.mode_4_supprted_args_3.value='ALL' +uci commit netmode && service netmode restart +``` + +### UCI Configuration (Traditional VLAN Devices) + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='internet' +uci set netmode.mode_4_supprted_args_2.value='bridge:wan-tagged:100' +uci set netmode.mode_4_supprted_args_3.value='ALL' +uci commit netmode && service netmode restart +``` + +### TR-181 Configuration + +```xml + + + + Device.X_IOWRT_EU_NetMode.Mode + advanced + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.1.Value + internet + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.2.Value + brvlan:wan-tagged:100 + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.3.Value + ALL + + + +``` + +**Result**: +- WAN port tagged with VLAN 100 +- LAN ports untagged +- DHCP client enabled + +--- + +## Scenario 4: ISP Dual Service (Internet + IPTV) + +**Use Case**: ISP provides Internet on VLAN 1499 and IPTV on VLAN 1510 + +**Network Topology**: +``` +Internet: WAN.1499 (tagged) + LAN1-2 (untagged) → br-internet.1499 +IPTV: WAN.1510 (tagged) + LAN3-4 (untagged) → br-tv.1510 +``` + +### UCI Configuration + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='internet,tv' +uci set netmode.mode_4_supprted_args_2.value='brvlan:wan-tagged:1499,brvlan:wan-tagged:1510-n' +uci set netmode.mode_4_supprted_args_3.value='LAN1-LAN2-WAN,LAN3-LAN4-WAN' +uci commit netmode && service netmode restart +``` + +### TR-181 Configuration + +```xml + + + + Device.X_IOWRT_EU_NetMode.Mode + advanced + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.1.Value + internet,tv + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.2.Value + brvlan:wan-tagged:1499,brvlan:wan-tagged:1510-n + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.3.Value + LAN1-LAN2-WAN,LAN3-LAN4-WAN + + + +``` + +**Result**: +- Internet bridge on VLAN 1499 with LAN1-2 +- IPTV bridge on VLAN 1510 with LAN3-4 (proto=none, no DHCP) +- Both services use WAN port with respective VLANs + +--- + +## Scenario 5: ISP Triple-Play (Internet + IPTV + VoIP) + +**Use Case**: Full triple-play service with Internet, IPTV, and VoIP + +**Network Topology**: +``` +Internet: WAN.100 (tagged) + LAN1-2 (untagged) → br-internet.100 +IPTV: WAN.200 (tagged) + LAN3 (untagged) → br-tv.200 +VoIP: WAN.300 (tagged) + LAN4 (untagged) → br-voip.300 +``` + +### UCI Configuration + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='internet,tv,voip' +uci set netmode.mode_4_supprted_args_2.value='brvlan:wan-tagged:100,brvlan:wan-tagged:200-n,brvlan:wan-tagged:300-n' +uci set netmode.mode_4_supprted_args_3.value='LAN1-LAN2-WAN,LAN3-WAN,LAN4-WAN' +uci commit netmode && service netmode restart +``` + +### TR-181 Configuration + +```xml + + + + Device.X_IOWRT_EU_NetMode.Mode + advanced + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.1.Value + internet,tv,voip + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.2.Value + brvlan:wan-tagged:100,brvlan:wan-tagged:200-n,brvlan:wan-tagged:300-n + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.3.Value + LAN1-LAN2-WAN,LAN3-WAN,LAN4-WAN + + + +``` + +**Result**: +- Internet on VLAN 100 with DHCP (LAN1-2) +- IPTV on VLAN 200 without DHCP (LAN3) +- VoIP on VLAN 300 without DHCP (LAN4) + +--- + +## Scenario 6: Routed Multi-Service (Internet + IPTV + Management) + +**Use Case**: Multiple routed services on different VLANs with NAT/firewall + +**Network Topology**: +``` +WAN.100 → wan (routed, DHCP, firewall) +WAN.200 → iptv (routed, DHCP, firewall) +WAN.300 → mgmt (routed, DHCP, firewall) +``` + +### UCI Configuration + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='wan,iptv,mgmt' +uci set netmode.mode_4_supprted_args_2.value='route:vlan:100,route:vlan:200,route:vlan:300' +uci set netmode.mode_4_supprted_args_3.value='WAN,WAN,WAN' +uci commit netmode && service netmode restart +``` + +### TR-181 Configuration + +```xml + + + + Device.X_IOWRT_EU_NetMode.Mode + advanced + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.1.Value + wan,iptv,mgmt + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.2.Value + route:vlan:100,route:vlan:200,route:vlan:300 + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.3.Value + WAN,WAN,WAN + + + +``` + +**Result**: +- Three separate routed interfaces +- Each with own firewall zone +- All with DHCP clients enabled + +--- + +## Scenario 7: Hybrid Setup (Routed Internet + Bridged IPTV) + +**Use Case**: Internet needs routing/NAT, but IPTV needs transparent bridge to STBs + +**Network Topology**: +``` +WAN.100 → wan (routed, firewall) +WAN.200 + LAN1-3 → br-iptv.200 (bridged, transparent) +``` + +### UCI Configuration + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='wan,iptv' +uci set netmode.mode_4_supprted_args_2.value='route:vlan:100,brvlan:wan-tagged:200-n' +uci set netmode.mode_4_supprted_args_3.value='WAN,LAN1-LAN2-LAN3-WAN' +uci commit netmode && service netmode restart +``` + +### TR-181 Configuration + +```xml + + + + Device.X_IOWRT_EU_NetMode.Mode + advanced + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.1.Value + wan,iptv + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.2.Value + route:vlan:100,brvlan:wan-tagged:200-n + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.3.Value + WAN,LAN1-LAN2-LAN3-WAN + + + +``` + +**Result**: +- WAN interface routed with firewall +- IPTV bridged transparently to LAN ports +- Firewall enabled (because of routed interface) + +--- + +## Scenario 8: Corporate Network with Trunk Port + +**Use Case**: LAN1 is trunk port to managed switch, other ports are access ports + +**Network Topology**: +``` +VLAN 200: LAN1 (tagged) + WAN (tagged) + LAN2-3 (untagged) → br-corporate.200 +``` + +### UCI Configuration + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='corporate' +uci set netmode.mode_4_supprted_args_2.value='brvlan:mixed:200:LAN1-WAN' +uci set netmode.mode_4_supprted_args_3.value='LAN1-LAN2-LAN3-WAN' +uci commit netmode && service netmode restart +``` + +### TR-181 Configuration + +```xml + + + + Device.X_IOWRT_EU_NetMode.Mode + advanced + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.1.Value + corporate + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.2.Value + brvlan:mixed:200:LAN1-WAN + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.3.Value + LAN1-LAN2-LAN3-WAN + + + +``` + +**Result**: +- LAN1 and WAN tagged (trunk ports) +- LAN2-3 untagged (access ports) +- All on VLAN 200 + +--- + +## Scenario 9: Enterprise Multi-VLAN (Separate Networks) + +**Use Case**: Separate networks for guest, corporate, and management + +**Network Topology**: +``` +Guest: WAN.100 (tagged) + LAN1 (untagged) → br-guest.100 +Corporate: WAN.200 (tagged) + LAN2-3 (untagged) → br-corporate.200 +Management: WAN.300 (tagged) + LAN4 (untagged) → br-mgmt.300 +``` + +### UCI Configuration + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='guest,corporate,mgmt' +uci set netmode.mode_4_supprted_args_2.value='brvlan:wan-tagged:100-n,brvlan:wan-tagged:200-n,brvlan:wan-tagged:300' +uci set netmode.mode_4_supprted_args_3.value='LAN1-WAN,LAN2-LAN3-WAN,LAN4-WAN' +uci commit netmode && service netmode restart +``` + +### TR-181 Configuration + +```xml + + + + Device.X_IOWRT_EU_NetMode.Mode + advanced + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.1.Value + guest,corporate,mgmt + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.2.Value + brvlan:wan-tagged:100-n,brvlan:wan-tagged:200-n,brvlan:wan-tagged:300 + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.3.Value + LAN1-WAN,LAN2-LAN3-WAN,LAN4-WAN + + + +``` + +**Result**: +- Guest network on VLAN 100 (no DHCP) +- Corporate network on VLAN 200 (no DHCP) +- Management network on VLAN 300 (DHCP enabled) + +--- + +## Scenario 10: Wholesale QinQ Provider + +**Use Case**: Service provider supporting multiple customers with QinQ (802.1ad) + +**Network Topology**: +``` +Customer A: All ports double-tagged (S-tag 100, C-tag 10) +Customer B: All ports double-tagged (S-tag 100, C-tag 20) +``` + +### UCI Configuration + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='customer_a,customer_b' +uci set netmode.mode_4_supprted_args_2.value='bridge:qinq:10:100-n,bridge:qinq:20:100-n' +uci set netmode.mode_4_supprted_args_3.value='LAN1-LAN2-WAN,LAN3-LAN4-WAN' +uci commit netmode && service netmode restart +``` + +### TR-181 Configuration + +```xml + + + + Device.X_IOWRT_EU_NetMode.Mode + advanced + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.1.Value + customer_a,customer_b + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.2.Value + bridge:qinq:10:100-n,bridge:qinq:20:100-n + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.3.Value + LAN1-LAN2-WAN,LAN3-LAN4-WAN + + + +``` + +**Result**: +- Customer A bridge with C-tag 10, S-tag 100 +- Customer B bridge with C-tag 20, S-tag 100 +- Both without DHCP (proto=none) + +**Note**: QinQ requires traditional `bridge:` mode, not available with `brvlan:` mode. + +--- + +## Scenario 11: MACVLAN Multi-Service (Different MAC Addresses) + +**Use Case**: ISP requires different MAC addresses for Internet and IPTV services + +**Network Topology**: +``` +WAN (default MAC) → wan (routed) +WAN (custom MAC) → iptv (routed) +``` + +### UCI Configuration + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='wan,iptv' +uci set netmode.mode_4_supprted_args_2.value='route:transparent,route:macvlan:AA:BB:CC:DD:EE:FF' +uci set netmode.mode_4_supprted_args_3.value='WAN,WAN' +uci commit netmode && service netmode restart +``` + +### TR-181 Configuration + +```xml + + + + Device.X_IOWRT_EU_NetMode.Mode + advanced + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.1.Value + wan,iptv + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.2.Value + route:transparent,route:macvlan:AA:BB:CC:DD:EE:FF + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.3.Value + WAN,WAN + + + +``` + +**Result**: +- WAN interface with default MAC +- IPTV interface with custom MAC (AA:BB:CC:DD:EE:FF) +- Both routed with firewall + +--- + +## Scenario 12: Standalone VLAN Interface + +**Use Case**: WAN as standalone VLAN interface (no bridge, no routing, for custom protocols) + +**Network Topology**: +``` +WAN.2501 → wan (standalone, proto=none) +``` + +### UCI Configuration + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='wan' +uci set netmode.mode_4_supprted_args_2.value='direct:2501' +uci set netmode.mode_4_supprted_args_3.value='WAN' +uci commit netmode && service netmode restart +``` + +### TR-181 Configuration + +```xml + + + + Device.X_IOWRT_EU_NetMode.Mode + advanced + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.1.Value + wan + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.2.Value + direct:2501 + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.3.Value + WAN + + + +``` + +**Result**: +- WAN.2501 VLAN device created +- No bridge, no routing layer +- proto=none (manual configuration needed) + +--- + +## Scenario 13: All Ports Tagged (Managed Network) + +**Use Case**: All ports need VLAN tags for managed switch environment + +**Network Topology**: +``` +VLAN 100: All ports tagged → br-mgmt.100 +``` + +### UCI Configuration + +```bash +uci set netmode.global.mode='advanced' +uci set netmode.mode_4_supprted_args_1.value='mgmt' +uci set netmode.mode_4_supprted_args_2.value='brvlan:tagged:100' +uci set netmode.mode_4_supprted_args_3.value='ALL' +uci commit netmode && service netmode restart +``` + +### TR-181 Configuration + +```xml + + + + Device.X_IOWRT_EU_NetMode.Mode + advanced + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.1.Value + mgmt + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.2.Value + brvlan:tagged:100 + + + Device.X_IOWRT_EU_NetMode.SupportedModes.4.SupportedArguments.3.Value + ALL + + + +``` + +**Result**: +- All ports (LAN + WAN) tagged with VLAN 100 +- Single bridge with VLAN filtering +- DHCP client enabled + +--- + +## Quick Reference: Configuration Cheat Sheet + +### Interface Types + +| Type | Syntax | When to Use | +|------|--------|-------------| +| Transparent Bridge | `bridge:transparent` | Simple home network, no VLANs | +| Bridge VLAN Filtering (Tagged) | `brvlan:tagged:VID` | All ports need VLAN tags, modern approach | +| Bridge VLAN Filtering (WAN Tagged) | `brvlan:wan-tagged:VID` | ISP VLAN on WAN, LAN untagged (recommended) | +| Bridge VLAN Filtering (Mixed) | `brvlan:mixed:VID:PORTS` | Custom trunk/access port setup | +| Traditional Tagged Bridge | `bridge:tagged:VID` | Legacy systems, all ports tagged | +| Traditional WAN Tagged | `bridge:wan-tagged:VID` | Legacy ISP VLAN setup | +| QinQ Bridge | `bridge:qinq:CVID:SVID` | Wholesale provider, double tagging | +| Routed VLAN | `route:vlan:VID` | Need routing/NAT per service | +| Routed MACVLAN | `route:macvlan:MAC` | Different MAC per service | +| Direct VLAN | `direct:VID` | Standalone VLAN for custom protocols | + +### Modifiers + +| Modifier | Effect | Example | +|----------|--------|---------| +| `-n` | Disable DHCP client (proto=none) | `brvlan:wan-tagged:100-n` | +| `-d` | Disable interface | `route:vlan:200-d` | + +### Port Specifications + +| Syntax | Meaning | +|--------|---------| +| `ALL` | All LAN + WAN ports | +| `WAN` | WAN port only | +| `LAN1-LAN2-WAN` | LAN1, LAN2, and WAN | +| `LAN1-LAN3` | LAN1 and LAN3 only | + +### MAC Address Macros + +| Macro | Description | Example Result | +|-------|-------------|----------------| +| `BaseMACAddress` | Base MAC from `fw_printenv -n ethaddr` | `94:3F:0C:D5:76:00` | +| `BaseMACAddressP1` | Base MAC + 1 | `94:3F:0C:D5:76:01` | +| `BaseMACAddressP2` | Base MAC + 2 | `94:3F:0C:D5:76:02` | +| `BaseMACAddressPN` | Base MAC + N | `BaseMACAddressP5` → `94:3F:0C:D5:76:05` | +| Explicit MAC | Direct assignment | `AA:BB:CC:DD:EE:FF` | + +--- + +**Document Version**: 1.0 +**Last Updated**: 2025-12-12 diff --git a/netmode/docs/DEVELOPER_GUIDE.md b/netmode/docs/DEVELOPER_GUIDE.md new file mode 100644 index 000000000..333d88d98 --- /dev/null +++ b/netmode/docs/DEVELOPER_GUIDE.md @@ -0,0 +1,1220 @@ +# Netmode Developer Guide + +## Table of Contents +1. [Development Environment Setup](#development-environment-setup) +2. [Package Build System](#package-build-system) +3. [Code Organization](#code-organization) +4. [API Reference](#api-reference) +5. [Mode Script Development](#mode-script-development) +6. [UCI Integration](#uci-integration) +7. [Data Model Development](#data-model-development) +8. [Debugging Techniques](#debugging-techniques) +9. [Testing Framework](#testing-framework) +10. [Release Process](#release-process) + +--- + +## Development Environment Setup + +### Prerequisites + +```bash +# OpenWrt build environment +sudo apt-get install build-essential libncurses5-dev gawk git \ + subversion libssl-dev gettext unzip zlib1g-dev file python3 + +# Clone iopsys repository +git clone https://dev.iopsys.eu/iopsys/iopsyswrt.git +cd iopsyswrt + +# Update feeds +./scripts/feeds update -a +./scripts/feeds install -a +``` + +### Building netmode Package + +```bash +# Configure build +make menuconfig +# Navigate to: Utilities -> netmode + +# Build package only +make package/feeds/iopsys/netmode/compile V=s + +# Build with debug symbols +make package/feeds/iopsys/netmode/compile V=s CONFIG_DEBUG=y +``` + +### Installing to Device + +```bash +# Copy to device +scp bin/packages/*/iopsys/netmode_*.ipk root@192.168.1.1:/tmp/ + +# Install on device +ssh root@192.168.1.1 +opkg install /tmp/netmode_*.ipk +``` + +### Development Workflow + +```bash +# Make changes to files in feeds/iopsys/netmode/files/ + +# Clean and rebuild +make package/feeds/iopsys/netmode/clean +make package/feeds/iopsys/netmode/compile V=s + +# Test on device +scp bin/packages/*/iopsys/netmode_*.ipk root@192.168.1.1:/tmp/ +ssh root@192.168.1.1 "opkg remove netmode; opkg install /tmp/netmode_*.ipk" +``` + +--- + +## Package Build System + +### Makefile Analysis + +```makefile +PKG_NAME:=netmode +PKG_VERSION:=1.1.11 +PKG_RELEASE:=1 +``` + +**Version Scheme**: `MAJOR.MINOR.PATCH` +- **MAJOR**: Breaking changes +- **MINOR**: New features, backward compatible +- **PATCH**: Bug fixes + +### Build Configuration + +```makefile +define Package/$(PKG_NAME)/config + config NETMODE_VENDOR_PREFIX + depends on PACKAGE_netmode + string "Vendor Extension used for netmode datamodel" + default "" +endef +``` + +**Usage in code**: +```json +"object": "{BBF_VENDOR_PREFIX}NetMode" +``` + +Replaced by `BBFDM_REGISTER_SERVICES` during build. + +### Installation Targets + +```makefile +define Package/netmode/install + $(INSTALL_DIR) $(1)/etc + $(INSTALL_DIR) $(1)/lib + $(CP) ./files/etc/* $(1)/etc/ + $(CP) ./files/lib/* $(1)/lib/ + $(BBFDM_REGISTER_SERVICES) -v ${VENDOR_PREFIX} ./bbfdm_service.json $(1) $(PKG_NAME) + $(BBFDM_INSTALL_MS_DM) -v ${VENDOR_PREFIX} ./files/datamodel.json $(1) $(PKG_NAME) +endef +``` + +**File Permissions**: +- Scripts in `/etc/init.d/`: `0755` (executable) +- UCI configs: `0644` (readable) +- Mode scripts: Must be made executable in postinst + +--- + +## Code Organization + +### Module Responsibilities + +| Module | File | Responsibility | +|--------|------|----------------| +| **Init System** | `/etc/init.d/netmode` | Service lifecycle, mode switching orchestration | +| **Mode Scripts** | `/etc/netmodes//scripts/*` | Mode-specific UCI configuration | +| **Pre-hooks** | `/lib/netmode/pre/*` | Pre-switch preparation | +| **Post-hooks** | `/lib/netmode/post/*` | Post-switch cleanup, reboot | +| **UCI Defaults** | `/etc/uci-defaults/*` | First-boot configuration | +| **Data Model** | `/files/datamodel.json` | BBF TR-181 mappings | +| **Service Def** | `bbfdm_service.json` | BBF service registration | + +### Init Script Architecture + +``` +/etc/init.d/netmode +├── start_service() # Main entry point +│ ├── configure_env_vars() # Setup NETMODE_* vars +│ ├── libnetmode_exec("pre") +│ ├── Copy UCI files +│ ├── libnetmode_exec() # Generic scripts +│ ├── Execute mode scripts +│ ├── libnetmode_exec("post") +│ └── cleanup_env_vars() +├── service_triggers() # Procd reload trigger +└── Helper functions: + ├── _log() + ├── _get_modes_sec_name() + ├── _set_env_args() + └── cleanup_arg_values() +``` + +--- + +## API Reference + +### Init Script Functions + +#### `start_service()` + +Main service entry point called by procd. + +**Execution Conditions**: +- `/etc/config/netmode` exists +- `netmode.global.enabled = 1` +- `netmode.global.mode` is set +- Current mode differs from `.last_mode` + +**Side Effects**: +- Modifies UCI configuration +- Exports environment variables +- Writes `.last_mode` file +- May trigger system reboot (via post-hook) + +#### `configure_env_vars(mode)` + +Exports mode arguments as environment variables. + +**Parameters**: +- `mode`: Mode name (e.g., "routed-pppoe") + +**Behavior**: +1. Find UCI section matching mode name +2. Iterate `supported_args` with matching `dm_parent` +3. Export `NETMODE_=` if value is non-empty +4. Exit if required arguments are missing + +**Example**: +```bash +configure_env_vars "routed-pppoe" +# Exports: +# NETMODE_username="user@isp.com" +# NETMODE_password="secret123" +``` + +#### `cleanup_env_vars(mode)` + +Unsets NETMODE_* environment variables and clears UCI values. + +**Parameters**: +- `mode`: Current mode name + +**Behavior**: +1. Unset all `NETMODE_*` environment variables +2. Clear `value` field in UCI for all arguments of current mode +3. Commit UCI changes + +**Security Note**: Prevents leaking credentials to subsequent processes. + +#### `libnetmode_exec(when)` + +Executes hook scripts from `/lib/netmode//`. + +**Parameters**: +- `when`: Hook type ("pre", "post", or empty for default) + +**Execution**: +- Scripts executed in lexicographical order +- Runs in subshell via `sh