iopsys-feed/netmode/docs/USER_GUIDE.md

# 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)
- Advanced VLAN configurations (multiple bridges, QinQ)

**Features**:
- Supports multiple bridge configurations
- VLAN tagging and QinQ support
- Can create standalone VLAN interfaces (no bridge)
- No routing (NAT disabled)
- Firewall disabled
- DHCP server disabled
- Device acts as transparent bridge

**Configuration Parameters**:
- `interface_names` (optional): Comma-separated interface names (default: wan)
- `interface_types` (optional): Comma-separated types (transparent, tagged:VID, direct:vlan:VID, qinq:C:S, etc.)
- `ports` (optional): Comma-separated port lists (default: ALL)

**Basic Configuration**:
```bash
# Simple transparent bridge
uci set netmode.global.mode='bridged'
uci commit netmode
service netmode restart
```

**Advanced Configuration Examples**:
```bash
# Multiple VLANs as separate bridges
uci set netmode.global.mode='bridged'
uci set netmode.@supported_args[0].value='lan100,lan200'      # interface_names
uci set netmode.@supported_args[1].value='tagged:100,tagged:200'  # interface_types
uci set netmode.@supported_args[2].value='LAN1-LAN2,LAN3-LAN4'    # ports
uci commit netmode
service netmode restart

# Standalone VLAN interface (no bridge)
uci set netmode.global.mode='bridged'
uci set netmode.@supported_args[0].value='wan'
uci set netmode.@supported_args[1].value='direct:vlan:2501'  # Direct VLAN interface
uci set netmode.@supported_args[2].value='WAN'
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
- For advanced VLAN scenarios, see ADVANCED_BRIDGE_GUIDE.md

**Parameter Naming Note**:
As of version 1.1.11, parameters were renamed for clarity:
- `bridge_names` → `interface_names` (old name still works)
- `bridge_types` → `interface_types` (old name still works)

**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_IOWRT_EU_NetMode.Mode
```

**Set PPPoE mode**:
```xml
SetParameterValues
  Device.X_IOWRT_EU_NetMode.Mode = "routed-pppoe"
  Device.X_IOWRT_EU_NetMode.SupportedModes.2.SupportedArguments.1.Value = "username@isp.com"
  Device.X_IOWRT_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