mirror of
https://dev.iopsys.eu/feed/iopsys.git
synced 2026-01-28 01:47:19 +01:00
40240a7152
the idea is to make them similar to route interface, to avoid confusion * they can be also be mgmt/inet/iptv * they will have default proto set to dhcp * syntax is now direct:vlan:100 or direct:transparent
294 lines
7.3 KiB
Markdown
294 lines
7.3 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
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:
|
|
```bash
|
|
uci set netmode.mode_4_supprted_args_2.value='bridge:transparent,brvlan:wan-tagged:100'
|
|
```
|
|
|
|
#### 2. Invalid VLAN ID
|
|
|
|
**Problem**:
|
|
```bash
|
|
uci set netmode.mode_4_supprted_args_2.value='bridge:tagged:5000' # > 4094
|
|
```
|
|
|
|
**Solution**: Use valid VLAN ID (1-4094):
|
|
```bash
|
|
uci set netmode.mode_4_supprted_args_2.value='bridge:tagged:100'
|
|
```
|
|
|
|
#### 3. Invalid MAC Address Format
|
|
|
|
**Problem**:
|
|
```bash
|
|
uci set netmode.mode_4_supprted_args_4.value='AA-BB-CC-DD-EE-FF' # Wrong separator
|
|
```
|
|
|
|
**Solution**: Use colon separator:
|
|
```bash
|
|
uci set netmode.mode_4_supprted_args_4.value='AA:BB:CC:DD:EE:FF'
|
|
```
|
|
|
|
#### 4. Invalid Interface Name
|
|
|
|
**Problem**:
|
|
```bash
|
|
uci set netmode.mode_4_supprted_args_1.value='wan-interface' # Dash not allowed
|
|
```
|
|
|
|
**Solution**: Use underscore instead:
|
|
```bash
|
|
uci set netmode.mode_4_supprted_args_1.value='wan_interface'
|
|
```
|
|
|
|
#### 5. Invalid Port Specification
|
|
|
|
**Problem**:
|
|
```bash
|
|
uci set netmode.mode_4_supprted_args_3.value='LAN1,LAN2' # Wrong separator
|
|
```
|
|
|
|
**Solution**: Use dash separator:
|
|
```bash
|
|
uci set netmode.mode_4_supprted_args_3.value='LAN1-LAN2'
|
|
```
|
|
|
|
## Testing Validation
|
|
|
|
### Test Invalid VLAN ID
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|