Posted on by patrick

Raspberry Pi Hostname Collision Resolver

Situation

When deploying multiple Raspberry Pi devices from the same firmware image for Ansible automation, hostname conflicts create operational challenges. While RFC 6762 specifies that mDNS devices should automatically resolve naming collisions by incrementing the duplicate name with a -2/3/4/etc postfix, real-world implementations often fail. Pinging ansibledest.local often returns competing results when multiple pis are online. This leaves devices unreachable with duplicate hostnames like ansibledest.local. This makes Ansible playbooks unable to identify and manage devices reliably.

Task

I will develop an automated solution that:

  • Proactively resolves hostname conflicts before they impact operations
  • Runs automatically on first boot without manual intervention
  • Scales to simultaneous deployment of multiple devices
  • Provides comprehensive audit logging for network discovery
  • Integrates seamlessly with existing Ansible automation workflows

Action

I created a comprehensive hostname collision resolver system consisting of:

Core Components

  1. hostname-collision-resolver.sh – Main script that:
    • Waits for network interfaces (wlan0/eth0) to be ready
    • Adds random delay (10-40 seconds) to prevent simultaneous boot conflicts
    • Scans network using avahi-browse and ping for existing hostname variants
    • Uses gap-filling algorithm to find lowest available hostname number
    • Updates system hostname and configuration files
    • Logs detailed network state including IP/MAC addresses of discovered hosts
    • Reboots automatically if hostname changes are made
  2. hostname-collision-resolver.service – Systemd service for proper boot integration:
    • Runs after network services are online
    • Executes before Ansible automation services
    • Configured as one-time execution with comprehensive logging
  3. firstrun.sh – Bootstrap script for SD card deployment:
    • Installs required packages (avahi-utils, avahi-daemon)
    • Embeds and installs the hostname resolver
    • Enables services for automatic execution
    • Self-removes after completion

Deployment Strategy

  • Embedded the entire hostname resolver system into a single firstrun.sh script
  • Used Raspberry Pi Imager advanced options for base configuration
  • Copied firstrun.sh to boot partition with proper permissions (chmod +x, chown root:root)
  • Created master SD card image ready for mass duplication via drive cloner

Key Features Implemented

  • Network-aware startup: Waits for actual network connectivity, not just interface up
  • Collision prevention: Random delays handle simultaneous device deployments
  • Intelligent naming: Gap-filling algorithm finds lowest available hostname variant
  • Comprehensive logging: Permanent audit trail of network state and decisions
  • One-time execution: Flag file prevents repeated runs throughout device lifetime
  • Automatic integration: Ready for immediate Ansible automation post-boot

Result

Successfully created a production-ready solution ready for testing. Should deliver the following results:

Immediate Outcomes

  • Master image ready: SD card contains fully integrated hostname resolver system
  • Scalable deployment: Ready for drive cloner to create multiple identical cards
  • Zero-touch automation: Devices will automatically resolve hostname conflicts on first boot
  • Ansible-ready: Devices will be immediately discoverable for automation after hostname resolution

Technical Achievements

  • Robust conflict detection: Uses both mDNS discovery and ping verification
  • Intelligent numbering: Finds optimal hostname (e.g., picks device-2.local if device-1.local and device-4.local exist)
  • Comprehensive logging: Complete audit trail including network topology at boot time
  • Production hardening: Error handling, timeouts, and safety mechanisms throughout

Next Steps Enabled

  1. Use drive cloner to duplicate master SD card to multiple cards
  2. Deploy cards to Raspberry Pi devices simultaneously
  3. Power on devices – automatic hostname resolution occurs
  4. Run Ansible discovery to locate renamed devices
  5. Proceed with normal Ansible automation workflows

The solution transforms a manual, error-prone process into a fully automated system that scales from single devices to large deployments while maintaining complete operational visibility.

I did write a testplan.md file that’s more detailed with test steps.