network-performance-analyzer/docs/dns-testing-guide.md

Automated analysis tool for network performance test datasets containing DNS testing results and iperf3 performance measurements

# DNS Testing Functionality Guide

## Overview

The DNS testing component of the Network Performance Data Gatherer provides comprehensive DNS resolution performance analysis with specialized validation for Carrier-Grade NAT (CGN) environments. The system automatically discovers domains from zone files, tests resolution performance across multiple DNS servers, and validates results against specific IP range requirements.

## DNS Testing Architecture

### Core Components

1. **Zone File Parser**: Extracts domains and record types from DNS zone files
2. **CGN Validator**: Validates resolved IPs against 100.64.0.0/10 CIDR block
3. **Performance Tester**: Measures DNS resolution times using dig command
4. **Concurrent Executor**: Parallel testing for improved efficiency
5. **Results Aggregator**: Collects and formats test results

### Test Flow

```
Zone File → Domain Discovery → DNS Resolution → CGN Validation → Performance Recording
```

## Zone File Parsing

### Supported Record Types

The parser handles standard BIND zone file format with support for:

#### A Records
```
domain.example.com.    1    IN    A    100.64.1.10
```

#### CNAME Records
```
alias.example.com.     1    IN    CNAME    target.example.com.
```

#### Parsing Rules
- Ignores comments (lines starting with `;`)
- Handles trailing dots in domain names
- Extracts domain, record type, and target information
- Supports both absolute and relative domain names

### Zone File Format Requirements

**Standard BIND Format**:
```
;; Comment lines start with semicolons
domain.example.com.    TTL    IN    A       100.64.1.10
subdomain.example.com. 1      IN    A       100.64.1.20
alias.example.com.     1      IN    CNAME   target.example.com.
```

**Key Requirements**:
- Whitespace-separated fields
- Record type in field 4 (A, CNAME, etc.)
- Target/value in field 5
- Proper domain name formatting

### Example Zone File Structure

```
;;
;; Domain: example.com
;; Purpose: Network performance testing
;;

;; A Records for direct IP resolution
web.example.com.       1    IN    A    100.64.1.10
api.example.com.       1    IN    A    100.64.1.20
db.example.com.        1    IN    A    100.64.1.30

;; CNAME Records for alias testing
www.example.com.       1    IN    CNAME web.example.com.
admin.example.com.     1    IN    CNAME api.example.com.
```

## CGN IP Validation

### Carrier-Grade NAT (CGN) Overview

**RFC 6598 Specification**: 100.64.0.0/10 CIDR block reserved for CGN deployments

**IP Range**: 100.64.0.0 to 100.127.255.255
- **Network**: 100.64.0.0/10
- **Subnet Mask**: 255.192.0.0
- **Total Addresses**: 4,194,304 addresses

### Validation Process

1. **DNS Resolution**: Query domain using dig command
2. **IP Extraction**: Parse resolved IP addresses from dig output
3. **CIDR Validation**: Check if IPs fall within 100.64.0.0/10 range
4. **Result Classification**: Mark as SUCCESS or FAILED_CGN_VALIDATION

### Validation Logic

```python
def _is_cgn_ip(self, ip_address: str) -> bool:
    """Checks if an IP address is within the 100.64.0.0/10 CIDR block."""
    try:
        return ipaddress.ip_address(ip_address) in self.cgn_cidr
    except ipaddress.AddressValueError:
        return False
```

### CGN Validation Examples

**Valid CGN IPs**:
- 100.64.0.1 ✅
- 100.100.50.100 ✅
- 100.127.255.254 ✅

**Invalid CGN IPs**:
- 192.168.1.1 ❌ (Private RFC 1918)
- 8.8.8.8 ❌ (Public Internet)
- 100.63.255.255 ❌ (Below CGN range)
- 100.128.0.1 ❌ (Above CGN range)

## DNS Performance Testing

### Test Methodology

#### DNS Servers Tested
1. **System DNS**: Default system resolver (None parameter)
2. **Google DNS**: 8.8.8.8
3. **Cloudflare DNS**: 1.1.1.1
4. **Custom DNS**: User-specified servers

#### dig Command Parameters
```bash
dig +time=5 +tries=3 +short [@dns_server] domain.com
```

**Parameters Explained**:
- `+time=5`: 5-second timeout per query attempt
- `+tries=3`: Maximum 3 retry attempts
- `+short`: Concise output format (IPs only)
- `@dns_server`: Specific DNS server (optional)

### Performance Metrics

#### Response Time Measurement
- **Start Time**: Recorded before dig execution
- **End Time**: Recorded after dig completion
- **Response Time**: (End - Start) × 1000 milliseconds
- **Query Time**: Currently uses response time as proxy

#### Success Criteria
1. **DNS Resolution**: dig command returns successfully
2. **IP Extraction**: Valid IP addresses extracted from output
3. **CGN Validation**: At least one IP within 100.64.0.0/10 range

### Concurrent Testing

#### Thread Pool Execution
- **Max Workers**: 5 concurrent threads
- **Domain Distribution**: Each domain tested against all DNS servers
- **Result Aggregation**: Immediate result processing and display

#### Benefits of Concurrent Testing
- **Reduced Test Time**: Parallel execution significantly faster
- **Resource Efficiency**: Optimal use of network and CPU resources
- **Scalability**: Handles large domain lists effectively

## DNS Test Results Structure

### Result Data Model

```python
{
    'domain': 'example.domain.com',
    'dns_server': '8.8.8.8',
    'success': True,
    'response_time_ms': 23.4,
    'query_time_ms': 23.4,
    'status': 'SUCCESS',
    'resolved_ips': ['100.64.1.10'],
    'error': ''
}
```

### Status Classifications

#### SUCCESS
- DNS resolution successful
- Valid IPs extracted
- At least one IP within CGN range

#### FAILED_VALIDATION
- DNS resolution successful
- Valid IPs extracted
- No IPs within CGN range

#### FAILED_CGN_VALIDATION
- DNS resolution successful
- Resolved IPs not in CGN range

#### TIMEOUT
- dig command exceeded timeout
- Network or DNS server issues

#### ERROR
- Unexpected errors during testing
- System or configuration issues

### Error Handling

#### Common Error Scenarios

**Domain Not in Zone File**:
```
Error: Domain 'unknown.com' not found in the provided zone file.
Status: FAILED_VALIDATION
```

**DNS Resolution Failure**:
```
Error: dig command failed
Status: FAILED_VALIDATION
```

**CGN Validation Failure**:
```
Error: Resolved IP(s) not within 100.64.0.0/10 CGN range.
Status: FAILED_CGN_VALIDATION
```

**Timeout Scenarios**:
```
Error: Timeout
Status: TIMEOUT
Response Time: 10000ms (timeout value)
```

## DNS Performance Analysis

### Statistical Metrics

#### Per DNS Server Analysis
- **Average Response Time**: Mean of all successful queries
- **Median Response Time**: Middle value of response times
- **Min/Max Response Time**: Fastest and slowest queries
- **Standard Deviation**: Response time variability
- **Success Rate**: Percentage of successful queries

#### Domain Performance Ranking
- **Slowest Domains**: Domains with highest response times
- **Fastest Domains**: Domains with lowest response times
- **Failure Analysis**: Domains with consistent failures

### Performance Comparison

#### DNS Server Comparison
```
DNS Server Performance Summary:
- System DNS: Avg 15.2ms, Success 95%
- Google DNS (8.8.8.8): Avg 12.8ms, Success 98%
- Cloudflare DNS (1.1.1.1): Avg 11.5ms, Success 97%
```

#### Domain Analysis
```
Slowest Domains (CGN Validated):
1. complex.domain.com: 45.2ms (IPs: 100.64.1.50)
2. remote.domain.com: 38.7ms (IPs: 100.64.1.60)
3. legacy.domain.com: 32.1ms (IPs: 100.64.1.70)
```

## Troubleshooting DNS Testing

### Common Issues and Solutions

#### Zone File Not Found
**Error**: `Warning: Zone file 'thepi.es.txt' not found`

**Solutions**:
- Verify zone file path and filename
- Check file permissions (readable)
- Use absolute path if relative path fails
- Ensure zone file is in correct format

#### dig Command Not Found
**Error**: `dig: command not found`

**Solutions**:
- **Ubuntu/Debian**: `sudo apt-get install dnsutils`
- **CentOS/RHEL**: `sudo yum install bind-utils`
- **macOS**: `brew install bind`
- Verify dig is in system PATH

#### DNS Resolution Failures
**Error**: `dig command failed`

**Solutions**:
- Test manual dig command: `dig @8.8.8.8 domain.com`
- Check network connectivity to DNS servers
- Verify domain names are correct
- Try alternative DNS servers

#### CGN Validation Failures
**Error**: `Resolved IP(s) not within 100.64.0.0/10 CGN range`

**Solutions**:
- Verify zone file contains correct CGN IP addresses
- Check DNS server configuration
- Confirm domain resolution returns expected IPs
- Validate zone file IP ranges

#### Performance Issues
**Symptoms**: Slow DNS testing, timeouts

**Solutions**:
- Reduce concurrent thread count (modify max_workers)
- Increase dig timeout values
- Test with fewer domains initially
- Check network latency to DNS servers

### Debugging Commands

#### Manual DNS Testing
```bash
# Test specific domain with specific DNS server
dig +time=5 +tries=3 @8.8.8.8 domain.com

# Test with verbose output
dig +time=5 +tries=3 +trace @8.8.8.8 domain.com

# Test system DNS
dig domain.com
```

#### Zone File Validation
```bash
# Check zone file syntax
named-checkzone example.com zone_file.txt

# Validate specific records
grep "IN A" zone_file.txt | head -5
```

#### Network Connectivity
```bash
# Test DNS server connectivity
ping -c 3 8.8.8.8

# Test DNS port connectivity
nc -u -v 8.8.8.8 53
```

## Best Practices

### Zone File Management
1. **Consistent Format**: Use standard BIND zone file format
2. **CGN IP Ranges**: Ensure all A records use 100.64.0.0/10 addresses
3. **Regular Updates**: Keep zone files current with network changes
4. **Validation**: Test zone files before use in production testing

### DNS Server Selection
1. **Diverse Providers**: Test multiple DNS providers for comparison
2. **Geographic Considerations**: Include geographically diverse servers
3. **Performance Baseline**: Establish baseline performance for each server
4. **Reliability Testing**: Monitor DNS server availability and consistency

### Performance Optimization
1. **Concurrent Limits**: Adjust thread count based on system capabilities
2. **Timeout Tuning**: Balance between thoroughness and speed
3. **Domain Filtering**: Focus on critical domains for faster testing
4. **Result Caching**: Consider caching for repeated tests

### Integration Considerations
1. **Data Format Consistency**: Maintain consistent result formats for analysis
2. **Error Handling**: Implement robust error handling and recovery
3. **Logging**: Comprehensive logging for troubleshooting
4. **Monitoring**: Track DNS testing performance and reliability

This comprehensive DNS testing system provides detailed insights into DNS resolution performance while ensuring compliance with CGN network requirements, enabling thorough analysis of network infrastructure DNS capabilities.