mdns-traffic-generator 1.0.0

A Python tool for generating mDNS traffic for network testing

MDNS Traffic Generator

A Python tool for generating mDNS (Multicast DNS) traffic for network testing. This tool allows you to register, announce, and discover mDNS services across a network, making it ideal for testing network configurations, firewalls, and mDNS-aware applications.

Features

• Service Registration: Register custom mDNS services with configurable properties
• Traffic Generation: Generate continuous mDNS announcements for stress testing
• Service Discovery: Discover and browse mDNS services on the network
• INI-Based Configuration: Persistent configuration stored in an INI file
• CLI Configuration Management: All config changes through CLI commands
• Cross-Platform: Works on Windows, macOS, and Linux
• PyPI Ready: Installable via pip

Installation

From PyPI (when published)

pip install mdns-traffic-generator

From Source

# Clone the repository
git clone https://github.com/example/mdns-traffic-generator.git
cd mdns-traffic-generator

# Install in development mode
pip install -e ".[dev]"

Windows Installation

On Windows, the tool works out of the box but may require additional configuration:

1. Check Platform Requirements

After installation, run the platform check command:

mdns-generator check

This will show your platform status, IP addresses, and any warnings.

2. Configure Windows Firewall

mDNS uses UDP port 5353. You may need to allow this through Windows Firewall.

Option A: Using PowerShell (Run as Administrator)

# Allow inbound mDNS traffic
New-NetFirewallRule -DisplayName "mDNS-In" -Direction Inbound -Protocol UDP -LocalPort 5353 -Action Allow

# Allow outbound mDNS traffic  
New-NetFirewallRule -DisplayName "mDNS-Out" -Direction Outbound -Protocol UDP -LocalPort 5353 -Action Allow

Option B: Using the GUI

1. Open "Windows Defender Firewall with Advanced Security"
2. Click "Inbound Rules" > "New Rule"
3. Select "Port" > "UDP" > Specific port: 5353
4. Allow the connection
5. Repeat for "Outbound Rules"

To see detailed firewall instructions:

mdns-generator check --firewall

3. Optional: Install Bonjour (Windows 7/8)

On older Windows versions, you may need Apple's Bonjour service for mDNS support:

• Download Bonjour Print Services for Windows
• Or install iTunes (includes Bonjour)

Windows 10/11 have built-in mDNS support and typically don't need Bonjour.

4. Run as Administrator (If Needed)

Some operations may require elevated privileges:

# Right-click Command Prompt or PowerShell
# Select "Run as Administrator"
mdns-generator generate --name test-service --duration 60

Quick Start

Generate mDNS Traffic

# Generate traffic with default settings for 60 seconds
mdns-generator generate

# Generate with custom service name and duration
mdns-generator generate --name my-test-service --duration 120

# Generate multiple services
mdns-generator generate --name load-test --count 10 --duration 300

Discover Services

# Discover HTTP services
mdns-generator discover

# Discover all common service types
mdns-generator discover --all --duration 10

# Continuous discovery with live updates
mdns-generator discover --continuous

# Output as JSON
mdns-generator discover --json

Register a Single Service

# Register a service and keep it active
mdns-generator register --name my-webapp --port 8080 --type _http._tcp.local.

# With custom properties
mdns-generator register --name my-api --port 3000 -P version=2.0 -P env=testing

Configuration

Configuration is stored in an INI file and can only be modified through CLI commands. This ensures consistent and validated configuration.

Configuration File Location

• Windows: %APPDATA%\mdns-generator\config.ini
• macOS/Linux: ~/.config/mdns-generator/config.ini

View Current Configuration

# Show all configuration values
mdns-generator config show

# Show config file path only
mdns-generator config show --path

Set Configuration Values

# Set service name
mdns-generator config set service.name my-service

# Set service port
mdns-generator config set service.port 9000

# Set broadcast interval
mdns-generator config set traffic.broadcast_interval 10

# Set logging level
mdns-generator config set logging.level DEBUG

Available Configuration Keys

Key	Description	Default
service.name	Service instance name	test-service
service.type	mDNS service type	_http._tcp.local.
service.port	Service port (1-65535)	8080
network.interface	Network interface to bind	0.0.0.0
network.ttl	mDNS record TTL in seconds	4500
traffic.broadcast_interval	Announcement interval (seconds)	5.0
traffic.service_count	Number of services (1-100)	1
logging.level	Log level	INFO
logging.file	Log file path (optional)	(not set)

Initialize or Reset Configuration

# Initialize config file with defaults
mdns-generator config init

# Reset configuration to defaults
mdns-generator config reset

# Force overwrite existing config
mdns-generator config init --force

Edit Configuration Manually

# Open config file in default editor
mdns-generator config edit

CLI Reference

Global Options

mdns-generator --version          # Show version
mdns-generator --help             # Show help
mdns-generator --log-level DEBUG  # Override log level for this session

Commands

generate - Generate mDNS Traffic

mdns-generator generate [OPTIONS]

Options:
  -n, --name TEXT        Service name (overrides config)
  -t, --type TEXT        Service type (overrides config)
  -p, --port INTEGER     Service port (overrides config)
  -c, --count INTEGER    Number of services to register (overrides config)
  -d, --duration FLOAT   Duration in seconds, 0 for indefinite (default: 60)
  -i, --interval FLOAT   Broadcast interval in seconds (overrides config)
  -P, --property TEXT    Service property as key=value (repeatable)

discover - Discover mDNS Services

mdns-generator discover [OPTIONS]

Options:
  -t, --type TEXT        Service type to discover (repeatable)
  -d, --duration FLOAT   Discovery duration in seconds (default: 5)
  -a, --all              Discover all common service types
  -j, --json             Output results as JSON
  -c, --continuous       Continuously discover and display services

register - Register a Single Service

mdns-generator register [OPTIONS]

Options:
  -n, --name TEXT        Service name (required)
  -t, --type TEXT        Service type (default: _http._tcp.local.)
  -p, --port INTEGER     Service port (required)
  -P, --property TEXT    Service property as key=value (repeatable)

config - Manage Configuration

mdns-generator config show [--path]           # Show configuration
mdns-generator config set <key> <value>       # Set a configuration value
mdns-generator config reset [--yes]           # Reset to defaults
mdns-generator config init [--force]          # Initialize config file
mdns-generator config edit                    # Open in editor

list-types - List Common Service Types

mdns-generator list-types

check - Check Platform Requirements

mdns-generator check [OPTIONS]

Options:
  -f, --firewall    Show firewall configuration instructions

Example output:

Platform Check
----------------------------------------
Platform: Windows
Python: 3.11.0
Hostname: DESKTOP-ABC123.local.
IP Addresses: 192.168.1.100
----------------------------------------
Status: Ready
All mDNS requirements met!

Programmatic Usage

from mdns_generator import MDNSGenerator, ServiceConfig, ServiceDiscovery

# Generate traffic
with MDNSGenerator() as generator:
    config = ServiceConfig(
        name="my-service",
        service_type="_http._tcp.local.",
        port=8080,
        properties={"version": "1.0"}
    )
    generator.register_service(config)
    generator.start_broadcasting(interval=5.0)
    
    # Keep running...
    import time
    time.sleep(60)

# Discover services
with ServiceDiscovery() as discovery:
    services = discovery.discover_services(
        service_types=["_http._tcp.local."],
        duration=5.0
    )
    for service in services:
        print(f"Found: {service.name} at {service.addresses}:{service.port}")

Common Service Types

Service Type	Description
_http._tcp.local.	HTTP web servers
_https._tcp.local.	HTTPS web servers
_ssh._tcp.local.	SSH servers
_ftp._tcp.local.	FTP servers
_smb._tcp.local.	SMB file shares
_printer._tcp.local.	Network printers
_ipp._tcp.local.	IPP printers
_airplay._tcp.local.	Apple AirPlay
_googlecast._tcp.local.	Google Cast devices
_homekit._tcp.local.	HomeKit devices

Development

Setup Development Environment

# Clone and install with dev dependencies
git clone https://github.com/example/mdns-traffic-generator.git
cd mdns-traffic-generator
pip install -e ".[dev]"

Run Tests

# Run all tests with coverage
pytest

# Run specific test file
pytest tests/test_generator.py

# Run with verbose output
pytest -v

Code Quality

# Run linter
pylint src/mdns_generator

# Format code
black src tests
isort src tests

# Type checking
mypy src/mdns_generator

Build Package

# Build distribution packages
pip install build
python -m build

# The packages will be in dist/
# - mdns_traffic_generator-1.0.0.tar.gz
# - mdns_traffic_generator-1.0.0-py3-none-any.whl

Publish to PyPI

# Install twine
pip install twine

# Upload to TestPyPI first
twine upload --repository testpypi dist/*

# Upload to PyPI
twine upload dist/*

Troubleshooting

Windows: Access Denied

Run Command Prompt or PowerShell as Administrator, or check firewall settings.

No Services Discovered

1. Ensure mDNS traffic is allowed through the firewall (UDP port 5353)
2. Check that the network supports multicast
3. Some corporate networks block mDNS traffic

Service Registration Fails

1. Verify the port is not already in use
2. Check that you have permission to bind to the network interface
3. Try running with elevated privileges

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.