iopsys-feed/netmode/docs/README.md

# 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

```bash
# Install via opkg
opkg update
opkg install netmode

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

### Basic Usage

```bash
# 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**:
```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
```

See **[ADVANCED_MODE_GUIDE.md](ADVANCED_MODE_GUIDE.md)** for complete documentation.

## Documentation

Comprehensive documentation is available in the following guides:

### For Users
- **[ADVANCED_MODE_GUIDE.md](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.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](ADVANCED_MODE_QUICK_REFERENCE.md)** - Quick reference for advanced mode
- **[CONFIGURATION_SCENARIOS.md](CONFIGURATION_SCENARIOS.md)** - Real-world configuration examples with UCI and TR-181
- **[VALIDATION_AND_ERROR_HANDLING.md](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.md)** - User guide for basic modes (DHCP, PPPoE, Static)
  - Getting started
  - Mode descriptions
  - Common use cases
  - FAQ

### For Developers
- **[DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md)** - Developer documentation
  - Development environment setup
  - Code organization
  - API reference
  - Testing framework
  - Contributing guidelines

### For Implementers
- **[IMPLEMENTATION_GUIDE.md](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

```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_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:
```xml
<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

```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)