iopsys-feed/netmode/docs/USER_GUIDE.md

Netmode User Guide

Table of Contents

1. Introduction
2. Getting Started
3. Available Network Modes
4. Configuration Methods
5. Common Use Cases
6. Troubleshooting
7. FAQ
8. 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

# 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

# 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

# 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:

# 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:

# 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:

# 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:

# Simple transparent bridge
uci set netmode.global.mode='bridged'
uci commit netmode
service netmode restart

Advanced Configuration Examples:

# 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:

# 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:

GetParameterValues
  Device.X_IOWRT_EU_NetMode.Mode

Set PPPoE mode:

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:

# 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

# 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

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

# 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

# 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

# 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:

# 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:

   # Restart network
   /etc/init.d/network restart
   
   # Release and renew DHCP
   udhcpc -i wan -n
   

2. For PPPoE mode:

   # 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:

   # 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:

   # 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:

# Check if netmode is enabled
uci get netmode.global.enabled

# Check logs
logread | grep netmode

# Check if mode exists
ls /etc/netmodes/*/scripts/

Solutions:

# 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:

# Check PPPoE logs
logread | grep ppp

# Common errors:
# - "authentication failed"
# - "LCP timeout"
# - "CHAP authentication failed"

Solutions:

# 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):

   # Set MTU for PPPoE
   uci set netmode.@supported_args[5].value='1492'
   uci commit netmode
   service netmode restart
   

2. Check for DNS issues:

   # 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:

   # 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:

# 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:

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:

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:

# 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

# 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

# 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