How Hostname and mDNS/avahi Resolution Work for Local Network Access in atomcam_tools

The atomcam_tools firmware persists the device hostname to /media/mmc/hostname, binds it to /etc/hostname at boot via the S40hostname init script, and broadcasts it via Avahi mDNS by restarting avahi-daemon whenever the name changes, enabling access via <hostname>.local without DNS configuration.

The atomcam_tools repository provides extended firmware for ATOM-Cam based devices including ATOMCam, ATOMCam2, AtomSwing, and WyzeCam V3. Understanding how hostname and mDNS/avahi resolution function is essential for reliable local network access without relying on a DHCP server's DNS records. This implementation uses a mutable hostname file combined with Avahi (mDNS) and NetBIOS to advertise the device identity on the LAN.

Boot-Time Hostname Initialization with S40hostname

At system startup, the S40hostname init script establishes the device's network identity by binding persistent storage to the system's hostname configuration.

The script performs three critical operations:

1. Creates default hostname: If /media/mmc/hostname does not exist, it initializes the file with atomcam.
2. Bind mounts: Uses mount -o bind /media/mmc/hostname /etc/hostname to make the SD card file appear as the system's hostname file.
3. Kernel update: Executes hostname -F /media/mmc/hostname to load the name into the running kernel.

# overlay_rootfs/etc/init.d/S40hostname

case "$1" in
  start)
    [ ! -f /media/mmc/hostname ] && echo "atomcam" > /media/mmc/hostname
    mount -o bind /media/mmc/hostname /etc/hostname
    hostname -F /media/mmc/hostname
    ;;
  stop)
    umount /etc/hostname
    ;;
esac

This bind mount technique ensures that any changes to /etc/hostname are immediately written to the SD card, providing persistence across reboots without requiring flash writes to the root filesystem.

Runtime Hostname Changes via WebCMD

When users modify the hostname through the web interface, the webcmd.sh script handles the atomic update and service propagation.

The script at overlay_rootfs/scripts/webcmd.sh processes the hostname command by:

• Writing the new name (stripping any domain suffix using ${params%%.*}) to /media/mmc/hostname
• Updating the kernel immediately with hostname <newname>
• Restarting avahi-daemon via /usr/sbin/avahi-daemon -k && /usr/sbin/avahi-daemon -D
• Restarting NetBIOS via killall -9 nmbd && nmbd -D

# overlay_rootfs/scripts/webcmd.sh (hostname section)

if [ "$cmd" = "hostname" ] && [ "$params" != "" ]; then
  echo ${params%%.*} > /media/mmc/hostname
  hostname ${params%%.*}
  if [ "`pidof avahi-daemon`" != "" ]; then
    /usr/sbin/avahi-daemon -k
    /usr/sbin/avahi-daemon -D
  fi
  if [ "`pidof nmbd`" != "" ]; then
    killall -9 nmbd
    nmbd -D
  fi
  echo "$cmd $params OK" >> /var/run/webres
fi

This immediate service restart ensures that the previous mDNS advertisement is withdrawn and the new <hostname>.local address becomes resolvable within seconds, without requiring a full system reboot.

mDNS Advertisement and Link-Local Networking

Avahi implements the mDNS (multicast DNS) protocol on UDP port 5353, advertising the device's hostname as <hostname>.local to the multicast address 224.0.0.251.

For environments without a DHCP server, the avahi-autoipd daemon establishes link-local connectivity. The script network_samples/network_init_linklocal.sh demonstrates this configuration:

# network_samples/network_init_linklocal.sh

ifconfig usb0 up
/usr/sbin/avahi-autoipd -D --no-drop-root usb0

This command:

• Assigns a link-local IPv4 address in the 169.254.x.x range
• Creates the virtual interface alias usb0:avahi
• Enables Avahi to bind to the correct network interface for mDNS packet transmission

When operating in this mode, the device remains discoverable via mDNS even without router connectivity, making it ideal for direct USB Ethernet or isolated network configurations.

Accessing the Device from Client Systems

Clients with mDNS support—including macOS, Linux with Avahi or systemd-resolved, and Windows 10 or later—can resolve the device using the <hostname>.local domain suffix.

To verify connectivity from a client machine:

# macOS or Linux

ping atomcam.local

# Windows PowerShell

Test-Connection atomcam.local

If the device obtains a DHCP-assigned address (e.g., 192.168.1.42) while also maintaining link-local connectivity, both addresses respond to the same .local hostname, providing redundant access paths.

Summary

• Persistent storage: The hostname is stored in /media/mmc/hostname on the SD card, surviving firmware updates and reboots.
• Boot binding: The S40hostname init script bind-mounts this file to /etc/hostname and applies it to the kernel at startup.
• Dynamic updates: The webcmd.sh script handles runtime changes by updating the file, kernel, and restarting avahi-daemon and nmbd to broadcast the new name immediately.
• Zero-configuration networking: Avahi advertises the hostname via mDNS on UDP port 5353, while avahi-autoipd provides 169.254.x.x link-local addressing for direct connections.
• Universal access: Modern operating systems resolve <hostname>.local without requiring manual DNS entries or knowledge of the device's IP address.

Frequently Asked Questions

How do I change the hostname on my ATOM-Cam device?

You can change the hostname by writing the desired name to /media/mmc/hostname, running hostname <newname> to update the kernel, and restarting the Avahi daemon with /usr/sbin/avahi-daemon -k && /usr/sbin/avahi-daemon -D. Alternatively, use the web interface's WebCMD feature which executes these steps automatically via webcmd.sh.

What is the .local domain and why does it work without DNS?

The .local domain is reserved for link-local naming via mDNS (multicast DNS). When you query hostname.local, your operating system sends a multicast packet to 224.0.0.251:5353 on the local network. The Avahi daemon running on the ATOM-Cam responds with its current IP address, eliminating the need for a centralized DNS server or router configuration.

Does Windows support accessing the camera via mDNS?

Yes. Windows 10 and later versions include native mDNS support through Link-Local Multicast Name Resolution (LLMNR) and the Windows DNS client. You can ping or browse to atomcam.local directly from PowerShell or Command Prompt without installing additional software.

Why does the hostname revert after a reboot if I edit /etc/hostname directly?

Direct edits to /etc/hostname are non-persistent because S40hostname bind-mounts /media/mmc/hostname over /etc/hostname during startup. Always modify /media/mmc/hostname or use the web interface to ensure changes survive reboots.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}