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

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