iopsys-feed/netmode/docs

Netmode - Network Mode Switching for OpenWrt/iopsys

Version: 1.1.11 License: GPL-2.0-only Maintainer: iopsys

Overview

Netmode is a network configuration management package for OpenWrt/iopsys-based routers that enables seamless switching between different WAN connection types. It provides a unified interface for managing network modes including DHCP, PPPoE, Static IP, and Bridge configurations.

Key Features

• Simple Mode Switching: Change WAN connection type with a single command
• Multiple Mode Support: DHCP, PPPoE, Static IP, and Bridged mode
• Automatic Configuration: Handles network, firewall, DHCP, and multicast settings
• TR-069/USP Integration: Remote management via BBF data model
• Extensible Architecture: Easy to add custom network modes
• Safe Transitions: Proper cleanup and validation during mode switches

Quick Start

Installation

# Install via opkg
opkg update
opkg install netmode

# Or build from source
make package/feeds/iopsys/netmode/compile

Basic Usage

# Check current mode
cat /etc/netmodes/.last_mode

# Switch to DHCP mode
uci set netmode.global.mode='routed-dhcp'
uci commit netmode
service netmode restart

# Switch to PPPoE mode
uci set netmode.global.mode='routed-pppoe'
uci set netmode.@supported_args[2].value='username@isp.com'
uci set netmode.@supported_args[3].value='password'
uci commit netmode
service netmode restart

Supported Modes

Mode	Description	Use Case
routed-dhcp	Router with DHCP WAN	Cable/Fiber internet with automatic IP
routed-pppoe	Router with PPPoE WAN	DSL internet with authentication
routed-static	Router with Static IP WAN	Business connections with fixed IP
advanced ⭐	Unified Advanced Mode	Bridges, routed interfaces, VLAN, QinQ, MACVLAN - all in one

Advanced Mode (v1.1.11+) - Recommended

The advanced mode is a unified, powerful configuration mode that replaces both bridged and routed-multi-service modes. It supports:

✅ Bridge interfaces with VLAN/QinQ support (traditional VLAN devices) ✅ Bridge VLAN filtering (modern kernel bridge VLAN filtering - recommended) ✅ Routed interfaces with VLAN/MACVLAN support ✅ Standalone VLAN interfaces (direct, no bridge) ✅ Mixed scenarios (combine bridges and routed interfaces) ✅ Flexible configuration with single, intuitive syntax ✅ MAC address assignment with macros (BaseMACAddress, BaseMACAddressPNN) ✅ Comprehensive validation with helpful error messages

Quick Example - Triple-Play Service:

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

See ADVANCED_MODE_GUIDE.md for complete documentation.

Documentation

Comprehensive documentation is available in the following guides:

For Users

• ADVANCED_MODE_GUIDE.md ⭐ - Complete advanced mode guide (RECOMMENDED)
  • All interface types (bridge, routed, standalone)
  • VLAN, QinQ, MACVLAN configurations
  • Bridge VLAN filtering (modern approach)
  • Real-world use case scenarios
  • TR-069/USP examples
  • Troubleshooting
• BRIDGE_VLAN_FILTERING.md 🆕 - Bridge VLAN filtering guide
  • Modern bridge VLAN filtering feature
  • Syntax and configuration examples
  • Performance benefits
  • Migration from traditional VLAN devices
• ADVANCED_MODE_QUICK_REFERENCE.md - Quick reference for advanced mode
• CONFIGURATION_SCENARIOS.md - Real-world configuration examples with UCI and TR-181
• VALIDATION_AND_ERROR_HANDLING.md 🆕 - Validation and error handling guide
  • Input validation rules
  • Error messages and troubleshooting
  • Common validation errors
  • Testing validation
• USER_GUIDE.md - User guide for basic modes (DHCP, PPPoE, Static)
  • Getting started
  • Mode descriptions
  • Common use cases
  • FAQ

For Developers

• DEVELOPER_GUIDE.md - Developer documentation
  • Development environment setup
  • Code organization
  • API reference
  • Testing framework
  • Contributing guidelines

For Implementers

• IMPLEMENTATION_GUIDE.md - Implementation details
  • Architecture overview
  • Creating custom modes
  • Environment variables
  • Hook system
  • Data model integration

Architecture

┌─────────────────────────────────────────┐
│         Netmode System                   │
├─────────────────────────────────────────┤
│  UCI Config → Init Service → Mode Scripts│
│       ↓             ↓              ↓     │
│  Environment    Pre-hooks      UCI Copy │
│   Variables       ↓              ↓       │
│       ↓       Mode Scripts   Post-hooks │
│       └──────────┴────────────┘         │
│              Network Reconfiguration     │
└─────────────────────────────────────────┘

Components

• Init Service (/etc/init.d/netmode): Orchestrates mode switching
• Mode Scripts (/etc/netmodes/<mode>/scripts/): Mode-specific configuration
• UCI Config (/etc/config/netmode): Mode definitions and parameters
• Data Model (datamodel.json): BBF TR-181 integration
• Hooks (/lib/netmode/{pre,post}/): Pre/post mode switch scripts

Configuration Examples

DHCP with VLAN

uci set netmode.global.mode='routed-dhcp'
uci set netmode.@supported_args[0].value='100'  # VLAN ID
uci commit netmode
service netmode restart

PPPoE with Custom DNS

uci set netmode.global.mode='routed-pppoe'
uci set netmode.@supported_args[2].value='user@isp.com'
uci set netmode.@supported_args[3].value='password123'
uci set netmode.@supported_args[6].value='8.8.8.8,8.8.4.4'
uci commit netmode
service netmode restart

Static IP Business Connection

uci set netmode.global.mode='routed-static'
uci set netmode.@supported_args[6].value='203.0.113.10'
uci set netmode.@supported_args[7].value='255.255.255.0'
uci set netmode.@supported_args[8].value='203.0.113.1'
uci commit netmode
service netmode restart

Creating Custom Modes

Custom network modes can be added by following these steps:

1. Create mode directory structure:

   mkdir -p /etc/netmodes/my-mode/scripts
   

2. Define mode in supported_modes.json:

   {
     "name": "my-mode",
     "description": "My Custom Mode",
     "supported_args": [...]
   }
   

3. Create mode script:

   cat > /etc/netmodes/my-mode/scripts/10-my-mode << 'EOF'
   #!/bin/sh
   # Configuration logic here
   EOF
   chmod +x /etc/netmodes/my-mode/scripts/10-my-mode
   

4. Import to UCI and test:

   sh /etc/uci-defaults/40_netmode_populated_supported_modes
   uci set netmode.global.mode='my-mode'
   service netmode restart
   

See IMPLEMENTATION_GUIDE.md for detailed instructions.

TR-069/USP Integration

Netmode exposes a BBF TR-181 data model for remote management:

Data Model Path: Device.X_IOWRT_EU_NetMode.

Device.X_IOWRT_EU_NetMode.
├── Enable (boolean, r/w)
├── Mode (string, r/w)
├── SupportedModesNumberOfEntries (unsignedInt, r)
└── SupportedModes.{i}.
    ├── Name (string, r)
    ├── Description (string, r)
    └── SupportedArguments.{i}.
        ├── Name (string, r)
        ├── Type (string, r)
        ├── Required (boolean, r)
        └── Value (string, r/w)

Example TR-069 operation:

<SetParameterValues>
  <ParameterList>
    <ParameterValueStruct>
      <Name>Device.X_IOWRT_EU_NetMode.Mode</Name>
      <Value>routed-dhcp</Value>
    </ParameterValueStruct>
  </ParameterList>
</SetParameterValues>

System Requirements

• Platform: OpenWrt/iopsys
• Dependencies:
  • dm-service (BBF data model service)
  • uci
  • procd
  • libubox (jshn)
• Recommended:
  • logread for monitoring
  • firewall, odhcpd, mcast for full functionality

File Structure

netmode/
├── Makefile                          # Package build definition
├── README.md                         # This file
├── IMPLEMENTATION_GUIDE.md           # Implementation guide
├── DEVELOPER_GUIDE.md                # Developer documentation
├── USER_GUIDE.md                     # User documentation
├── bbfdm_service.json                # BBF service registration
└── files/
    ├── etc/
    │   ├── config/netmode            # UCI configuration
    │   ├── init.d/netmode            # Init script (START=11)
    │   ├── uci-defaults/             # First-boot scripts
    │   └── netmodes/
    │       ├── supported_modes.json  # Mode definitions
    │       ├── routed-dhcp/scripts/
    │       ├── routed-pppoe/scripts/
    │       ├── routed-static/scripts/
    │       └── bridged/scripts/
    └── lib/
        ├── netmode/
        │   ├── pre/                  # Pre-switch hooks
        │   └── post/                 # Post-switch hooks
        └── upgrade/keep.d/netmode    # Sysupgrade preservation

Troubleshooting

Mode Not Switching

# Check if enabled
uci get netmode.global.enabled

# Check logs
logread | grep netmode

# Force mode change
rm /etc/netmodes/.last_mode
service netmode restart

No Internet After Switch

# Verify mode applied
cat /etc/netmodes/.last_mode

# Check WAN status
ifconfig wan
ip route

# Restart network
/etc/init.d/network restart

PPPoE Authentication Failed

# Check credentials
uci show network.wan | grep -E "username|password"

# Check logs
logread | grep ppp

# Verify VLAN if required
uci get network.wan.device

See USER_GUIDE.md for comprehensive troubleshooting.

Development

Building

# Clone repository
cd feeds/iopsys/netmode

# Build package
make package/feeds/iopsys/netmode/compile V=s

# Install on device
scp bin/packages/*/iopsys/netmode_*.ipk root@192.168.1.1:/tmp/
ssh root@192.168.1.1 "opkg install /tmp/netmode_*.ipk"

Testing

# Run mode switch test
./test-mode-switch.sh routed-dhcp

# Monitor logs
logread -f | grep netmode

# Verify configuration
uci show network
cat /etc/netmodes/.last_mode

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly on target hardware
5. Update documentation
6. Submit a pull request

See DEVELOPER_GUIDE.md for detailed guidelines.

License

This project is licensed under the GNU General Public License v2.0 only.

See /LICENSE for more information.

Support

• Documentation: See guides in this repository
• Issues: Contact iopsys development team
• Community: OpenWrt and iopsys forums

Changelog

Version 1.1.11

• Current stable release
• Support for DHCP, PPPoE, Static IP, and Bridge modes
• BBF TR-181 data model integration
• Comprehensive documentation

Acknowledgments

• OpenWrt project for the underlying platform
• iopsys for development and maintenance
• Contributors and testers

Related Projects

• OpenWrt - Linux operating system for embedded devices
• iopsys - Broadband device management
• BBF - Broadband Forum standards

---

For detailed information, please refer to the specific guides:

• Users: USER_GUIDE.md
• Developers: DEVELOPER_GUIDE.md
• Implementers: IMPLEMENTATION_GUIDE.md