netmode doc

netmode/README.md

@@ -1,109 +1,380 @@
-# Creating Custom Netmodes in IOWRT
+# Netmode - Network Mode Switching for OpenWrt/iopsys
 
-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.
+**Version**: 1.1.11
+**License**: GPL-2.0-only
+**Maintainer**: iopsys
 
-## 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
 
-## Overview of Netmodes
+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.
 
-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/<NETMODE_NAME>`.
+### Key Features
 
-## Directory Structure
+- **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
 
-A custom netmode is defined within the `/etc/netmodes/<NETMODE_NAME>` directory, which should contain the following subdirectories:
+## Quick Start
 
-- **/lib/netmode/pre/**: Generic scripts executed before the netmode-specific configurations are applied.
-- **/etc/netmodes/<NETMODE_NAME>/uci/**: Contains UCI configuration files that will be copied to `/etc/config/` during the application of the netmode.
-- **/etc/netmodes/<NETMODE_NAME>/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.
+### Installation
 
-## Creating a Custom Netmode
+```bash
+# Install via opkg
+opkg update
+opkg install netmode
 
-To create a new netmode, follow these steps:
+# Or build from source
+make package/feeds/iopsys/netmode/compile
+```
 
-### Step 1: Pre-Execution Scripts
+### Basic Usage
 
-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.
+```bash
+# Check current mode
+cat /etc/netmodes/.last_mode
 
-- **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
-    ```
+# Switch to DHCP mode
+uci set netmode.global.mode='routed-dhcp'
+uci commit netmode
+service netmode restart
 
-### Step 2: UCI Configuration Files
+# 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
+```
 
-The UCI configuration files stored in `/etc/netmodes/<NETMODE_NAME>/uci/` will be copied to `/etc/config/`, effectively applying the desired network configuration.
+## Supported Modes
 
-- **Place UCI Config Files**:
-  - Create UCI configuration files under `/etc/netmodes/<NETMODE_NAME>/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'
+| 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 |
+| **bridged** | L2 Bridge Mode | Transparent bridge, no routing |
 
-config interface 'lan'
-        option proto 'dhcp'
-        option device 'br-lan'
-        option force_link '1'
-        option reqopts '43 125'
-````
+## Documentation
 
-### Step 3: Custom Execution Scripts
+Comprehensive documentation is available in the following guides:
 
-After the UCI files are applied, any scripts in `/etc/netmodes/<NETMODE_NAME>/scripts/` are executed. These can be used to perform additional configuration tasks that are specific to the netmode.
+### For Users
+- **[USER_GUIDE.md](USER_GUIDE.md)** - Complete user guide with configuration examples
+  - Getting started
+  - Mode descriptions
+  - Common use cases
+  - Troubleshooting
+  - FAQ
 
-- **Create Custom Scripts**:
-  - Add scripts to `/etc/netmodes/<NETMODE_NAME>/scripts/`.
-  - Example (`/etc/netmodes/bridge/scripts/setup_bridge.sh`):
-    ```bash
-    #!/bin/sh
-    echo "Setting up bridge mode..."
-    # Additional configuration commands here
-    ```
+### For Developers
+- **[DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md)** - Developer documentation
+  - Development environment setup
+  - Code organization
+  - API reference
+  - Testing framework
+  - Contributing guidelines
 
-### Step 4: Post-Execution Scripts
+### For Implementers
+- **[IMPLEMENTATION_GUIDE.md](IMPLEMENTATION_GUIDE.md)** - Implementation details
+  - Architecture overview
+  - Creating custom modes
+  - Environment variables
+  - Hook system
+  - Data model integration
 
-Finally, the generic scripts in `/lib/netmode/post/` are executed. These scripts typically finalize the setup or perform any necessary cleanups.
+## Architecture
 
-- **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
-    ```
+```
+┌─────────────────────────────────────────┐
+│         Netmode System                   │
+├─────────────────────────────────────────┤
+│  UCI Config → Init Service → Mode Scripts│
+│       ↓             ↓              ↓     │
+│  Environment    Pre-hooks      UCI Copy │
+│   Variables       ↓              ↓       │
+│       ↓       Mode Scripts   Post-hooks │
+│       └──────────┴────────────┘         │
+│              Network Reconfiguration     │
+└─────────────────────────────────────────┘
+```
 
-## Enabling and Switching Netmodes
+### Components
 
-The netmode mechanism can be enabled or disabled via the UCI configuration, and you can switch between netmodes using UCI commands.
+- **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
 
-- **Enable Netmode**:
-  ```bash
-  uci set netmode.global.enabled=1
-  uci commit netmode
-    ```
-    
-- **Switch Netmode**:
-  ```bash
-  uci set netmode.global.mode='<NETMODE_NAME>'
-  uci commit netmode
-    ```
+## Configuration Examples
+
+### DHCP with VLAN
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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**:
+   ```bash
+   mkdir -p /etc/netmodes/my-mode/scripts
+   ```
+
+2. **Define mode in supported_modes.json**:
+   ```json
+   {
+     "name": "my-mode",
+     "description": "My Custom Mode",
+     "supported_args": [...]
+   }
+   ```
+
+3. **Create mode script**:
+   ```bash
+   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**:
+   ```bash
+   sh /etc/uci-defaults/40_netmode_populated_supported_modes
+   uci set netmode.global.mode='my-mode'
+   service netmode restart
+   ```
+
+See [IMPLEMENTATION_GUIDE.md](IMPLEMENTATION_GUIDE.md#creating-a-new-network-mode) for detailed instructions.
+
+## TR-069/USP Integration
+
+Netmode exposes a BBF TR-181 data model for remote management:
+
+**Data Model Path**: `Device.X_IOPSYS_EU_NetMode.`
+
+```
+Device.X_IOPSYS_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:
+```xml
+<SetParameterValues>
+  <ParameterList>
+    <ParameterValueStruct>
+      <Name>Device.X_IOPSYS_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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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](USER_GUIDE.md#troubleshooting) for comprehensive troubleshooting.
+
+## Development
+
+### Building
+
+```bash
+# 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
+
+```bash
+# 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](DEVELOPER_GUIDE.md#contributing-guidelines) 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](https://openwrt.org/) - Linux operating system for embedded devices
+- [iopsys](https://www.iopsys.eu/) - Broadband device management
+- [BBF](https://www.broadband-forum.org/) - Broadband Forum standards
+
+---
+
+**For detailed information, please refer to the specific guides:**
+- Users: [USER_GUIDE.md](USER_GUIDE.md)
+- Developers: [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md)
+- Implementers: [IMPLEMENTATION_GUIDE.md](IMPLEMENTATION_GUIDE.md)

netmode/USER_GUIDE.md

@@ -0,0 +1,857 @@
+# Netmode User Guide
+
+## Table of Contents
+1. [Introduction](#introduction)
+2. [Getting Started](#getting-started)
+3. [Available Network Modes](#available-network-modes)
+4. [Configuration Methods](#configuration-methods)
+5. [Common Use Cases](#common-use-cases)
+6. [Troubleshooting](#troubleshooting)
+7. [FAQ](#faq)
+8. [Glossary](#glossary)
+
+---
+
+## Introduction
+
+### What is Netmode?
+
+Netmode is a network configuration management system for iopsys-based routers that allows you to easily switch between different WAN (Wide Area Network) connection types without manual configuration.
+
+### Why Use Netmode?
+
+- **Simplicity**: Switch network modes with a single command
+- **Flexibility**: Support for multiple WAN connection types
+- **Consistency**: Ensures proper configuration of all related network services
+- **Remote Management**: Can be controlled via TR-069/USP protocols
+- **Safety**: Automatically handles complex network reconfigurations
+
+### Supported Connection Types
+
+- **DHCP**: Automatic IP configuration (most common for cable/fiber connections)
+- **PPPoE**: Username/password authentication (common for DSL connections)
+- **Static IP**: Manual IP configuration (business connections)
+- **Bridged Mode**: Bridge/modem mode (disable routing)
+
+---
+
+## Getting Started
+
+### Checking if Netmode is Installed
+
+```bash
+# Check if netmode package is installed
+opkg list-installed | grep netmode
+
+# Check netmode service status
+service netmode status
+```
+
+Expected output:
+```
+netmode - 1.1.11-1 - Network Modes and Utils
+```
+
+### Checking Current Mode
+
+```bash
+# View current configuration
+uci show netmode.global
+
+# Check active mode
+cat /etc/netmodes/.last_mode
+```
+
+Example output:
+```
+netmode.global=netmode
+netmode.global.enabled='1'
+netmode.global.mode='routed-dhcp'
+```
+
+### Viewing Available Modes
+
+```bash
+# List all supported modes
+uci show netmode | grep "supported_modes.*name"
+```
+
+Example output:
+```
+netmode.@supported_modes[0].name='routed-dhcp'
+netmode.@supported_modes[1].name='routed-pppoe'
+netmode.@supported_modes[2].name='routed-static'
+netmode.@supported_modes[3].name='bridged'
+```
+
+---
+
+## Available Network Modes
+
+### 1. Routed DHCP Mode
+
+**Mode Name**: `routed-dhcp`
+
+**When to Use**:
+- Cable internet connection
+- Fiber internet connection
+- Any ISP that automatically provides IP configuration
+
+**Features**:
+- Automatic IP address assignment
+- Built-in router (NAT)
+- Firewall enabled
+- DHCP server for local devices
+- IPv4 and IPv6 support
+
+**Configuration Parameters**:
+- `vlanid` (optional): VLAN ID if required by ISP
+- `dns_servers` (optional): Custom DNS servers (comma-separated)
+
+**Example Configuration**:
+```bash
+# Basic DHCP mode
+uci set netmode.global.mode='routed-dhcp'
+uci commit netmode
+service netmode restart
+
+# DHCP with VLAN ID 100
+uci set netmode.global.mode='routed-dhcp'
+# Find VLAN argument and set value
+uci set netmode.@supported_args[0].value='100'
+uci commit netmode
+service netmode restart
+```
+
+---
+
+### 2. Routed PPPoE Mode
+
+**Mode Name**: `routed-pppoe`
+
+**When to Use**:
+- DSL internet connection
+- ISP requires username and password authentication
+- Connection uses PPPoE protocol
+
+**Features**:
+- Username/password authentication
+- Built-in router (NAT)
+- Firewall enabled
+- DHCP server for local devices
+- Automatic MTU optimization
+
+**Required Parameters**:
+- `username`: PPPoE username (provided by ISP)
+- `password`: PPPoE password (provided by ISP)
+
+**Optional Parameters**:
+- `vlanid`: VLAN ID if required by ISP
+- `mtu`: Maximum transmission unit (default: 1492 for PPPoE)
+- `dns_servers`: Custom DNS servers (comma-separated)
+
+**Example Configuration**:
+```bash
+# Set mode
+uci set netmode.global.mode='routed-pppoe'
+
+# Set username (find correct argument index)
+uci set netmode.@supported_args[2].value='myuser@isp.com'
+
+# Set password
+uci set netmode.@supported_args[3].value='mypassword'
+
+# Optional: Set VLAN
+uci set netmode.@supported_args[4].value='100'
+
+# Optional: Set MTU
+uci set netmode.@supported_args[5].value='1492'
+
+# Apply configuration
+uci commit netmode
+service netmode restart
+```
+
+**Important Notes**:
+- Device will reboot after configuration
+- Keep ISP credentials safe
+- Most DSL connections use VLAN ID 7 or 100 (check with ISP)
+- MTU typically 1492 for PPPoE (auto-configured)
+
+---
+
+### 3. Routed Static IP Mode
+
+**Mode Name**: `routed-static`
+
+**When to Use**:
+- Business internet connection with static IP
+- ISP provided specific IP address, subnet mask, and gateway
+- Fixed IP address required for services (web server, VPN, etc.)
+
+**Features**:
+- Manual IP configuration
+- Built-in router (NAT)
+- Firewall enabled
+- DHCP server for local devices
+- Fixed WAN IP address
+
+**Required Parameters**:
+- `ipaddr`: Static IP address (e.g., 93.21.0.104)
+- `netmask`: Subnet mask (e.g., 255.255.255.0)
+- `gateway`: Default gateway IP (e.g., 93.21.0.1)
+
+**Optional Parameters**:
+- `vlanid`: VLAN ID if required
+- `dns_servers`: DNS servers (comma-separated, e.g., 8.8.8.8,8.8.4.4)
+
+**Example Configuration**:
+```bash
+# Set mode
+uci set netmode.global.mode='routed-static'
+
+# Set IP address
+uci set netmode.@supported_args[6].value='93.21.0.104'
+
+# Set subnet mask
+uci set netmode.@supported_args[7].value='255.255.255.0'
+
+# Set gateway
+uci set netmode.@supported_args[8].value='93.21.0.1'
+
+# Optional: Set DNS servers
+uci set netmode.@supported_args[9].value='8.8.8.8,8.8.4.4'
+
+# Apply configuration
+uci commit netmode
+service netmode restart
+```
+
+**Important Notes**:
+- Use exact IP settings provided by ISP
+- Incorrect settings will result in no internet connectivity
+- DNS servers are optional but recommended
+- Device will reboot after configuration
+
+---
+
+### 4. Bridged Mode
+
+**Mode Name**: `bridged`
+
+**When to Use**:
+- Using router as a bridge/modem only
+- Another router handles routing and DHCP
+- ISP requires bridge mode
+- Cascading routers (not recommended, prefer this mode on upstream device)
+
+**Features**:
+- All LAN and WAN ports bridged together
+- No routing (NAT disabled)
+- Firewall disabled
+- DHCP server disabled
+- Device acts as transparent bridge
+
+**Configuration Parameters**:
+- No parameters required
+
+**Example Configuration**:
+```bash
+# Set mode
+uci set netmode.global.mode='bridged'
+uci commit netmode
+service netmode restart
+```
+
+**Important Notes**:
+- Device will obtain IP from upstream router/ISP
+- Web interface may be inaccessible until device gets IP
+- To access device: connect directly and check DHCP leases on upstream router
+- Device will reboot after configuration
+- Use this mode carefully - you may lose access to the device
+
+**Reverting from Bridge Mode**:
+If you lose access, connect via serial console or perform factory reset.
+
+---
+
+## Configuration Methods
+
+### Method 1: UCI Command Line (SSH/Console)
+
+**Step-by-step procedure**:
+
+```bash
+# 1. Connect to device
+ssh root@192.168.1.1
+
+# 2. View current configuration
+uci show netmode
+
+# 3. Set desired mode
+uci set netmode.global.mode='routed-dhcp'
+
+# 4. Set any required parameters (example for PPPoE)
+uci set netmode.@supported_args[2].value='username@isp.com'
+uci set netmode.@supported_args[3].value='password123'
+
+# 5. Save configuration
+uci commit netmode
+
+# 6. Apply changes
+service netmode restart
+
+# 7. Monitor logs (optional)
+logread -f | grep netmode
+```
+
+### Method 2: TR-069/CWMP (Remote Management)
+
+If your device is managed by an ACS (Auto Configuration Server):
+
+**Get current mode**:
+```xml
+GetParameterValues
+  Device.X_IOPSYS_EU_NetMode.Mode
+```
+
+**Set PPPoE mode**:
+```xml
+SetParameterValues
+  Device.X_IOPSYS_EU_NetMode.Mode = "routed-pppoe"
+  Device.X_IOPSYS_EU_NetMode.SupportedModes.2.SupportedArguments.1.Value = "username@isp.com"
+  Device.X_IOPSYS_EU_NetMode.SupportedModes.2.SupportedArguments.2.Value = "password123"
+```
+
+**Trigger mode change**:
+```bash
+# On device (via TR-069 script)
+service netmode restart
+```
+
+### Method 3: Web Interface (if available)
+
+Some firmware may provide a web interface for netmode configuration.
+
+Typical location: **Network → WAN → Connection Type**
+
+---
+
+## Common Use Cases
+
+### Use Case 1: Switching from DHCP to PPPoE
+
+**Scenario**: ISP changed from cable to DSL connection
+
+```bash
+# 1. Connect to router
+ssh root@192.168.1.1
+
+# 2. Find username and password argument indices
+uci show netmode | grep -A3 "name='username'"
+# Note the index numbers
+
+# 3. Set mode and credentials
+uci set netmode.global.mode='routed-pppoe'
+uci set netmode.@supported_args[2].value='newuser@dsl-isp.com'
+uci set netmode.@supported_args[3].value='newpassword'
+
+# 4. If ISP requires VLAN (e.g., VLAN 7)
+uci set netmode.@supported_args[4].value='7'
+
+# 5. Apply
+uci commit netmode
+service netmode restart
+
+# Device will reboot
+```
+
+### Use Case 2: Adding Custom DNS Servers
+
+**Scenario**: Want to use Google DNS or Cloudflare DNS
+
+```bash
+# For DHCP mode
+uci set netmode.global.mode='routed-dhcp'
+
+# Find dns_servers argument index
+uci show netmode | grep -B2 "name='dns_servers'"
+
+# Set custom DNS (Google DNS example)
+uci set netmode.@supported_args[1].value='8.8.8.8,8.8.4.4'
+
+# Or Cloudflare DNS
+uci set netmode.@supported_args[1].value='1.1.1.1,1.0.0.1'
+
+# Apply
+uci commit netmode
+service netmode restart
+```
+
+### Use Case 3: Configuring VLAN for ISP
+
+**Scenario**: ISP requires VLAN tagging (common for fiber)
+
+```bash
+# Identify your mode (example: DHCP)
+uci set netmode.global.mode='routed-dhcp'
+
+# Find VLAN argument
+uci show netmode | grep -B2 "name='vlanid'"
+
+# Set VLAN ID (ISP will provide this, commonly 100, 7, or other)
+uci set netmode.@supported_args[0].value='100'
+
+# Apply
+uci commit netmode
+service netmode restart
+```
+
+### Use Case 4: Setting Up Bridge Mode for Secondary Router
+
+**Scenario**: Using dedicated router behind ISP modem
+
+```bash
+# Configure device as bridge
+uci set netmode.global.mode='bridged'
+uci commit netmode
+service netmode restart
+
+# After reboot, device will be in bridge mode
+# Connect to it via the IP it receives from upstream
+```
+
+### Use Case 5: Business Static IP Setup
+
+**Scenario**: ISP provided static IP configuration
+
+**ISP Information**:
+- IP Address: 203.0.113.10
+- Subnet Mask: 255.255.255.248
+- Gateway: 203.0.113.9
+- DNS: 203.0.113.1, 203.0.113.2
+
+```bash
+# Set mode
+uci set netmode.global.mode='routed-static'
+
+# Configure IP settings (find argument indices first)
+uci show netmode | grep -B2 "name='ipaddr'"
+uci show netmode | grep -B2 "name='netmask'"
+uci show netmode | grep -B2 "name='gateway'"
+
+# Set values
+uci set netmode.@supported_args[6].value='203.0.113.10'
+uci set netmode.@supported_args[7].value='255.255.255.248'
+uci set netmode.@supported_args[8].value='203.0.113.9'
+uci set netmode.@supported_args[9].value='203.0.113.1,203.0.113.2'
+
+# Apply
+uci commit netmode
+service netmode restart
+```
+
+---
+
+## Troubleshooting
+
+### Problem: No Internet After Mode Switch
+
+**Symptoms**:
+- Cannot access websites
+- No WAN IP address
+- Local network works but no internet
+
+**Diagnosis**:
+```bash
+# Check WAN interface status
+ifconfig wan
+
+# Check if WAN has IP
+ip addr show wan
+
+# Check routing table
+ip route
+
+# Check DNS resolution
+nslookup google.com
+
+# Check mode applied correctly
+cat /etc/netmodes/.last_mode
+uci show netmode.global.mode
+```
+
+**Solutions**:
+
+1. **For DHCP mode**:
+   ```bash
+   # Restart network
+   /etc/init.d/network restart
+
+   # Release and renew DHCP
+   udhcpc -i wan -n
+   ```
+
+2. **For PPPoE mode**:
+   ```bash
+   # Check credentials
+   uci show network.wan.username
+   uci show network.wan.password
+
+   # Check PPPoE connection
+   logread | grep pppd
+
+   # Restart PPPoE
+   ifdown wan
+   ifup wan
+   ```
+
+3. **For Static IP mode**:
+   ```bash
+   # Verify settings
+   uci show network.wan
+
+   # Check if gateway is reachable
+   ping -c 3 $(uci get network.wan.gateway)
+   ```
+
+### Problem: Cannot Access Router After Mode Change
+
+**Symptoms**:
+- Cannot reach router web interface
+- Cannot SSH to router
+- Router appears offline
+
+**Solutions**:
+
+1. **Check router IP address**:
+   - Routed modes: Router should be at `192.168.1.1`
+   - Bridged mode: Router gets IP from upstream device
+
+2. **For bridged mode**:
+   ```bash
+   # Connect to upstream router
+   # Check DHCP leases for your device MAC address
+   # Or connect via serial console
+   ```
+
+3. **Factory reset** (last resort):
+   - Hold reset button for 10 seconds
+   - Device will reset to default configuration
+
+### Problem: Mode Not Switching
+
+**Symptoms**:
+- `.last_mode` not updated
+- Old configuration still active
+- No changes after restart
+
+**Diagnosis**:
+```bash
+# Check if netmode is enabled
+uci get netmode.global.enabled
+
+# Check logs
+logread | grep netmode
+
+# Check if mode exists
+ls /etc/netmodes/*/scripts/
+```
+
+**Solutions**:
+```bash
+# Enable netmode if disabled
+uci set netmode.global.enabled='1'
+uci commit netmode
+
+# Force mode change by removing last_mode
+rm /etc/netmodes/.last_mode
+service netmode restart
+```
+
+### Problem: PPPoE Authentication Failure
+
+**Symptoms**:
+- WAN interface shows "connecting" but never connects
+- Logs show authentication errors
+
+**Diagnosis**:
+```bash
+# Check PPPoE logs
+logread | grep ppp
+
+# Common errors:
+# - "authentication failed"
+# - "LCP timeout"
+# - "CHAP authentication failed"
+```
+
+**Solutions**:
+```bash
+# Verify credentials (double-check with ISP)
+uci show network.wan.username
+uci show network.wan.password
+
+# Some ISPs require VLAN tagging
+uci set netmode.@supported_args[4].value='7'  # or ISP-specific VLAN
+uci commit netmode
+service netmode restart
+
+# Check if service name is required (rare)
+uci set network.wan.service='ISP-SERVICE-NAME'
+uci commit network
+```
+
+### Problem: Slow Internet After Mode Switch
+
+**Symptoms**:
+- Internet works but very slow
+- High latency
+
+**Solutions**:
+
+1. **Check MTU settings** (especially for PPPoE):
+   ```bash
+   # Set MTU for PPPoE
+   uci set netmode.@supported_args[5].value='1492'
+   uci commit netmode
+   service netmode restart
+   ```
+
+2. **Check for DNS issues**:
+   ```bash
+   # Test DNS resolution speed
+   time nslookup google.com
+
+   # Use faster DNS
+   uci set netmode.@supported_args[X].value='1.1.1.1,1.0.0.1'
+   uci commit netmode
+   service netmode restart
+   ```
+
+3. **Check WAN speed**:
+   ```bash
+   # Install iperf3 and test
+   opkg update
+   opkg install iperf3
+   ```
+
+---
+
+## FAQ
+
+### General Questions
+
+**Q: Will I lose my configuration when switching modes?**
+
+A: Netmode preserves most router settings (WiFi, firewall rules, etc.), but WAN-specific settings are reconfigured. Local network settings remain unchanged.
+
+**Q: How long does a mode switch take?**
+
+A: The mode switch itself takes a few seconds, but the device will reboot, which takes 1-2 minutes total.
+
+**Q: Can I switch modes remotely?**
+
+A: Yes, via SSH or TR-069/USP if configured. However, be careful with bridge mode as you may lose connectivity.
+
+**Q: Do I need to reboot manually?**
+
+A: No, the system automatically reboots after applying a new mode.
+
+**Q: Can I schedule a mode switch?**
+
+A: Yes, using cron:
+```bash
+# Switch to bridged mode at 2 AM
+echo "0 2 * * * uci set netmode.global.mode='bridged' && uci commit && service netmode restart" | crontab -
+```
+
+### Mode-Specific Questions
+
+**Q: Which mode should I use?**
+
+A: Depends on your ISP:
+- Cable/Fiber without login: **routed-dhcp**
+- DSL with username/password: **routed-pppoe**
+- Static IP business connection: **routed-static**
+- Using as bridge only: **bridged**
+
+**Q: Can I use PPPoE with VLAN?**
+
+A: Yes, set both the mode and VLAN ID:
+```bash
+uci set netmode.global.mode='routed-pppoe'
+uci set netmode.@supported_args[4].value='100'
+```
+
+**Q: What's the difference between routed and bridged mode?**
+
+A:
+- **Routed modes**: Router performs NAT, runs firewall, provides DHCP to local network
+- **Bridged mode**: Router acts as transparent bridge, no NAT, no firewall, no DHCP
+
+**Q: Can I customize the LAN IP in routed modes?**
+
+A: Yes, but not through netmode. After mode switch, manually configure:
+```bash
+uci set network.lan.ipaddr='192.168.2.1'
+uci commit network
+/etc/init.d/network restart
+```
+
+### Technical Questions
+
+**Q: Where are my credentials stored?**
+
+A: In `/etc/config/netmode` (UCI configuration). They are cleared from memory after mode application for security.
+
+**Q: Can I create custom modes?**
+
+A: Yes, advanced users can create custom modes. See the IMPLEMENTATION_GUIDE.md and DEVELOPER_GUIDE.md.
+
+**Q: Does netmode support IPv6?**
+
+A: Yes, routed-dhcp and routed-pppoe modes support IPv6 (DHCPv6).
+
+**Q: What happens to firewall rules?**
+
+A: Firewall is enabled for routed modes and disabled for bridged mode. Custom rules are preserved.
+
+**Q: Can I use multiple WAN connections?**
+
+A: Netmode manages the primary WAN. For multi-WAN setups, configure secondary WANs manually after netmode configuration.
+
+---
+
+## Glossary
+
+**Bridge Mode**: Operating mode where the router acts as a transparent network bridge without routing or NAT.
+
+**DHCP (Dynamic Host Configuration Protocol)**: Automatic IP address assignment protocol.
+
+**DMZ (Demilitarized Zone)**: Network segment that sits between internal network and external network.
+
+**DNS (Domain Name System)**: Service that translates domain names to IP addresses.
+
+**Gateway**: Router IP address that connects local network to the internet.
+
+**ISP (Internet Service Provider)**: Company providing internet access.
+
+**LAN (Local Area Network)**: Internal network (devices in your home/office).
+
+**MTU (Maximum Transmission Unit)**: Largest packet size that can be transmitted. PPPoE typically uses 1492.
+
+**NAT (Network Address Translation)**: Technology allowing multiple devices to share one public IP address.
+
+**PPPoE (Point-to-Point Protocol over Ethernet)**: Authentication protocol commonly used for DSL connections.
+
+**Static IP**: Fixed IP address that doesn't change (opposite of DHCP).
+
+**Subnet Mask**: Defines the network portion of an IP address (e.g., 255.255.255.0).
+
+**TR-069/CWMP**: Remote management protocol for network devices.
+
+**UCI (Unified Configuration Interface)**: OpenWrt configuration system.
+
+**USP (User Services Platform)**: Next-generation device management protocol.
+
+**VLAN (Virtual LAN)**: Network segmentation using VLAN tags (802.1Q).
+
+**WAN (Wide Area Network)**: External network connection (internet).
+
+---
+
+## Getting Help
+
+### Log Collection
+
+When reporting issues, collect these logs:
+
+```bash
+# System logs
+logread > /tmp/system.log
+
+# Network configuration
+uci export network > /tmp/network.conf
+uci export netmode > /tmp/netmode.conf
+
+# Interface status
+ifconfig > /tmp/interfaces.txt
+ip route > /tmp/routes.txt
+
+# Copy to external system
+scp /tmp/*.{log,conf,txt} user@external-host:/path/
+```
+
+### Support Resources
+
+- **Documentation**: Check IMPLEMENTATION_GUIDE.md and DEVELOPER_GUIDE.md
+- **Community Forums**: OpenWrt and iopsys community forums
+- **Issue Tracker**: Report bugs to iopsys development team
+- **ISP Support**: Contact ISP for connection-specific parameters (VLAN, credentials, etc.)
+
+### Before Contacting Support
+
+Please have ready:
+1. Current mode: `cat /etc/netmodes/.last_mode`
+2. Netmode version: `opkg info netmode | grep Version`
+3. Error logs: `logread | grep netmode`
+4. Network configuration: `uci export netmode`
+5. What you're trying to achieve
+6. What you've already tried
+
+---
+
+## Quick Reference Card
+
+### Common Commands
+
+```bash
+# View current mode
+cat /etc/netmodes/.last_mode
+
+# List available modes
+uci show netmode | grep "supported_modes.*name"
+
+# Switch to DHCP
+uci set netmode.global.mode='routed-dhcp'
+uci commit netmode && service netmode restart
+
+# Switch to PPPoE
+uci set netmode.global.mode='routed-pppoe'
+uci set netmode.@supported_args[2].value='username'
+uci set netmode.@supported_args[3].value='password'
+uci commit netmode && service netmode restart
+
+# Switch to Bridge
+uci set netmode.global.mode='bridged'
+uci commit netmode && service netmode restart
+
+# View logs
+logread | grep netmode
+
+# Reset to last mode
+rm /etc/netmodes/.last_mode
+service netmode restart
+```
+
+### Emergency Recovery
+
+```bash
+# If locked out after bridge mode
+# Connect via serial console and run:
+uci set netmode.global.mode='routed-dhcp'
+uci commit netmode
+service netmode restart
+
+# Factory reset (hold reset button 10 seconds)
+# Or via console:
+firstboot -y && reboot
+```
+
+---
+
+**Document Version**: 1.0
+**Package Version**: 1.1.11
+**Last Updated**: 2024
+**License**: GPL-2.0-only