olm/dns/platform/REFACTORING_SUMMARY.md

DNS Platform Module Refactoring Summary

Changes Made

Successfully refactored the DNS platform directory from a NetBird-derived codebase into a standalone, simplified DNS override module.

Files Created

Core Interface & Types:

• types.go - DNSConfigurator interface and shared types (DNSConfig, DNSState)

Platform Implementations:

• darwin.go - macOS DNS configurator using scutil (replaces host_darwin.go)
• windows.go - Windows DNS configurator using registry (replaces host_windows.go)
• file.go - Linux/Unix file-based configurator (replaces file_unix.go + file_parser_unix.go + file_repair_unix.go)
• networkmanager.go - NetworkManager D-Bus configurator (replaces network_manager_unix.go)
• systemd.go - systemd-resolved D-Bus configurator (replaces systemd_linux.go)
• resolvconf.go - resolvconf utility configurator (replaces resolvconf_unix.go)

Detection & Helpers:

• detect_unix.go - Automatic detection for Linux/FreeBSD
• detect_darwin.go - Automatic detection for macOS
• detect_windows.go - Automatic detection for Windows

Documentation:

• README.md - Comprehensive module documentation
• examples/example_usage.go - Usage examples for all platforms

Files Removed

Old NetBird-specific files:

• dbus_unix.go - D-Bus utilities (functionality moved into platform-specific files)
• file_parser_unix.go - resolv.conf parser (simplified and integrated into file.go)
• file_repair_unix.go - File watching/repair (removed - out of scope)
• file_unix.go - Old file configurator (replaced by file.go)
• host_darwin.go - Old macOS configurator (replaced by darwin.go)
• host_unix.go - Old Unix manager factory (replaced by detect_unix.go)
• host_windows.go - Old Windows configurator (replaced by windows.go)
• network_manager_unix.go - Old NetworkManager (replaced by networkmanager.go)
• resolvconf_unix.go - Old resolvconf (replaced by resolvconf.go)
• systemd_linux.go - Old systemd-resolved (replaced by systemd.go)
• unclean_shutdown_*.go - Unclean shutdown detection (removed - out of scope)

Key Architectural Changes

1. Removed Build Tags for Platform Selection

   • Old: Used //go:build tags at top of files to compile different code per platform
   • New: Named structs differently per platform (e.g., DarwinDNSConfigurator, WindowsDNSConfigurator)
   • Build tags kept only where necessary for cross-platform library imports

2. Simplified Interface

   • Removed complex domain routing, search domains, and port customization
   • Focused on core functionality: Set DNS, Get DNS, Restore DNS
   • Removed state manager dependencies

3. Removed External Dependencies

   • Removed: statemanager, NetBird-specific types, logging libraries
   • Kept only: D-Bus (for Linux), x/sys (for Windows registry and Unix syscalls)
   • Uses standard library where possible

4. Standalone Operation

   • No longer depends on NetBird types (HostDNSConfig, etc.)
   • Uses standard library types (net/netip.Addr)
   • Self-contained backup/restore logic

5. Improved Code Organization

   • Each platform has its own clearly-named file
   • Detection logic separated into detect_*.go files
   • Shared types in types.go
   • Examples in dedicated examples/ directory

Feature Comparison

Removed (out of scope for basic DNS override):

• Search domain management
• Match-only domains
• DNS port customization (except where natively supported)
• File watching and auto-repair
• Unclean shutdown detection
• State persistence
• Integration with external state managers

Retained (core DNS functionality):

• Setting DNS servers
• Getting current DNS servers
• Restoring original DNS servers
• Automatic platform detection
• DNS cache flushing
• Backup and restore of original configuration

Platform-Specific Notes

macOS (Darwin):

• Simplified to focus on DNS server override using scutil
• Removed complex domain routing and local DNS setup
• Removed GPO and state management
• Kept DNS cache flushing

Windows:

• Simplified registry manipulation to just NameServer key
• Removed NRPT (Name Resolution Policy Table) support
• Removed DNS registration and WINS management
• Kept DNS cache flushing

Linux - File-based:

• Direct /etc/resolv.conf manipulation with backup
• Removed file watching and auto-repair
• Removed complex search domain merging logic
• Simple nameserver-only configuration

Linux - systemd-resolved:

• D-Bus API for per-link DNS configuration
• Simplified to just DNS server setting
• Uses Revert method for restoration

Linux - NetworkManager:

• D-Bus API for connection settings modification
• Simplified to IPv4 DNS only
• Removed search/match domain complexity

Linux - resolvconf:

• Uses resolvconf utility (openresolv or Debian resolvconf)
• Interface-specific configuration
• Simple nameserver configuration

Usage Pattern

// Automatic detection
configurator, err := platform.DetectBestConfigurator("eth0")

// Set DNS
original, err := configurator.SetDNS([]netip.Addr{
    netip.MustParseAddr("8.8.8.8"),
})

// Restore
defer configurator.RestoreDNS()

Maintenance Notes

• Each platform implementation is independent
• No shared state between configurators
• Backups are file-based or in-memory only
• No external database or state management required
• Configurators can be tested independently

Migration Guide

If you were using the old code:

1. Replace HostDNSConfig with simple []netip.Addr for DNS servers
2. Replace newHostManager() with platform.DetectBestConfigurator()
3. Replace applyDNSConfig() with SetDNS()
4. Replace restoreHostDNS() with RestoreDNS()
5. Remove state manager dependencies
6. Remove search domain configuration (can be added back if needed)

Dependencies

Required:

• github.com/godbus/dbus/v5 - For Linux D-Bus configurators
• golang.org/x/sys - For Windows registry and Unix syscalls
• Standard library

Testing Recommendations

Each configurator should be tested on its target platform:

• macOS: Test darwin.go with scutil
• Windows: Test windows.go with actual interface GUID
• Linux: Test all variants (file, systemd, networkmanager, resolvconf)
• Verify backup/restore functionality
• Test with invalid input (empty servers, bad interface names)