iopsys-feed/netmode/docs/VALIDATION_AND_ERROR_HANDLING.md

Advanced Mode - Validation and Error Handling

Overview

The advanced mode includes comprehensive input validation and error handling to ensure configuration correctness and provide helpful error messages when issues occur.

Validation Functions

1. VLAN ID Validation

Function: validate_vlan_id()

Validates:

• VLAN ID is a number
• VLAN ID is in valid range (1-4094)

Example Error:

ERROR: VLAN ID in type 'bridge:tagged:5000' out of range (must be 1-4094): 5000

2. MAC Address Validation

Function: validate_mac_address()

Validates:

• MAC address format (XX:XX:XX:XX:XX:XX)
• MAC address macros (BaseMACAddress, BaseMACAddressPNN)
• Hexadecimal characters only

Example Errors:

ERROR: Invalid MAC address format: 'ZZ:BB:CC:DD:EE:FF' (expected XX:XX:XX:XX:XX:XX)
ERROR: Invalid MAC macro format: 'BaseMACAddressP' (expected BaseMACAddressPNN)

3. Interface Name Validation

Function: validate_interface_name()

Validates:

• Interface name is not empty
• Only alphanumeric characters and underscore allowed
• Reserved names not used (loopback, lo, globals)

Example Errors:

ERROR: Interface name 'wan-interface' invalid (only alphanumeric and underscore allowed)
ERROR: Interface name 'loopback' is reserved

4. Port Specification Validation

Function: validate_port_spec()

Validates:

• Port specification is not empty
• Valid port identifiers (LAN1-8, WAN, or interface names)
• Format is correct (dash-separated)

Example Error:

ERROR: Invalid port identifier in 'LAN1-LAN9-WAN': 'LAN9'

5. Interface Type Validation

Function: validate_interface_type()

Validates:

• Interface type syntax is correct
• VLAN IDs in types are valid
• MAC addresses in types are valid
• Type is recognized

Example Errors:

ERROR: Unknown interface type: 'bridge:unknown:100'
Valid types: bridge:transparent, bridge:tagged:VID, brvlan:wan-tagged:VID, route:vlan:VID, route:macvlan:MAC, direct:vlan:VID, direct:transparent

ERROR: VLAN ID in type 'route:vlan:9999' out of range (must be 1-4094): 9999

Configuration Validation

Parameter Count Matching

The system validates that all configuration parameters have matching element counts:

# This is VALID (3 interfaces, 3 types, 3 port lists)
interface_names='wan,iptv,voip'
interface_types='route:vlan:100,route:vlan:200,route:vlan:300'
ports='WAN,WAN,WAN'

# This is INVALID (3 interfaces but only 2 types)
interface_names='wan,iptv,voip'
interface_types='route:vlan:100,route:vlan:200'  # ERROR!
ports='WAN,WAN,WAN'

Error Message:

ERROR: Number of interface names (3) does not match number of interface types (2)
interface_names: wan,iptv,voip
interface_types: route:vlan:100,route:vlan:200

MAC Address Count Warning

If MAC addresses are provided but don't match interface count, a warning is issued:

WARNING: Number of MAC addresses (2) does not match number of interfaces (3)
Some interfaces will use default MAC addresses

Error Handling

MAC Address Operations

Base MAC Not Found

WARNING: Base MAC address not found or invalid, using default

MAC Increment Overflow

WARNING: MAC address overflow after increment, wrapping around

Invalid Increment Value

ERROR: MAC increment must be a number: 'ABC'

Port Resolution

WAN Port Not Found

ERROR: WAN port not found in board.json or UCI

Validation Failure Behavior

When validation fails:

1. Error is logged to syslog with severity user.err
2. Configuration is aborted - no changes are applied
3. Exit code 1 is returned
4. Helpful error message indicates what went wrong

Debugging Validation Issues

View Validation Logs

# Check recent netmode logs
logread | grep netmode-advanced

# Filter for errors only
logread | grep -E "netmode-advanced.*ERROR"

# Watch logs in real-time
logread -f | grep netmode-advanced

Common Validation Errors

1. Mismatched Parameter Counts

Problem:

uci set netmode.mode_4_supprted_args_1.value='wan,iptv'
uci set netmode.mode_4_supprted_args_2.value='bridge:transparent'  # Only 1!
uci set netmode.mode_4_supprted_args_3.value='ALL,LAN1-LAN2-WAN'

Solution: Ensure all parameters have same number of comma-separated values:

uci set netmode.mode_4_supprted_args_2.value='bridge:transparent,brvlan:wan-tagged:100'

2. Invalid VLAN ID

Problem:

uci set netmode.mode_4_supprted_args_2.value='bridge:tagged:5000'  # > 4094

Solution: Use valid VLAN ID (1-4094):

uci set netmode.mode_4_supprted_args_2.value='bridge:tagged:100'

3. Invalid MAC Address Format

Problem:

uci set netmode.mode_4_supprted_args_4.value='AA-BB-CC-DD-EE-FF'  # Wrong separator

Solution: Use colon separator:

uci set netmode.mode_4_supprted_args_4.value='AA:BB:CC:DD:EE:FF'

4. Invalid Interface Name

Problem:

uci set netmode.mode_4_supprted_args_1.value='wan-interface'  # Dash not allowed

Solution: Use underscore instead:

uci set netmode.mode_4_supprted_args_1.value='wan_interface'

5. Invalid Port Specification

Problem:

uci set netmode.mode_4_supprted_args_3.value='LAN1,LAN2'  # Wrong separator

Solution: Use dash separator:

uci set netmode.mode_4_supprted_args_3.value='LAN1-LAN2'

Testing Validation

Test Invalid VLAN ID

uci set netmode.mode_4_supprted_args_1.value='test'
uci set netmode.mode_4_supprted_args_2.value='bridge:tagged:9999'
uci set netmode.mode_4_supprted_args_3.value='ALL'
uci commit netmode && service netmode restart

# Check logs
logread | tail -20 | grep netmode-advanced
# Should show: ERROR: VLAN ID in type 'bridge:tagged:9999' out of range (must be 1-4094): 9999

Test Mismatched Counts

uci set netmode.mode_4_supprted_args_1.value='wan,iptv,voip'
uci set netmode.mode_4_supprted_args_2.value='route:vlan:100,route:vlan:200'  # Only 2!
uci set netmode.mode_4_supprted_args_3.value='WAN,WAN,WAN'
uci commit netmode && service netmode restart

# Check logs
logread | tail -20 | grep netmode-advanced
# Should show: ERROR: Number of interface names (3) does not match number of interface types (2)

Test Invalid MAC Address

uci set netmode.mode_4_supprted_args_4.value='INVALID-MAC'
uci commit netmode && service netmode restart

# Check logs
logread | tail -20 | grep netmode-advanced
# Should show: ERROR: Invalid MAC address format: 'INVALID-MAC' (expected XX:XX:XX:XX:XX:XX)

Best Practices

1. Always check logs after configuration changes
2. Test configurations in a development environment first
3. Use validation to catch errors early
4. Read error messages - they indicate exactly what's wrong
5. Keep backup of working configuration

Exit Codes

Exit Code	Meaning
0	Success - configuration applied
1	Failure - validation error or configuration error

Integration with Management Systems

When using TR-181 or other management systems:

1. Check exit code of netmode service
2. Parse error logs to provide user feedback
3. Validate before applying using the same validation rules
4. Provide helpful error messages to end users

---

Document Version: 1.0 Last Updated: 2025-12-13