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

> Discover how atomcam_tools uses hostname and mDNS avahi resolution for seamless local network access. Connect easily via <hostname>.local without DNS setup.

- Repository: [Mitsuru Nakada/atomcam_tools](https://github.com/mnakada/atomcam_tools)
- Tags: internals
- Published: 2026-03-07

---

**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.

```sh

# 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`](https://github.com/mnakada/atomcam_tools/blob/main/webcmd.sh) script handles the atomic update and service propagation.

The script at [`overlay_rootfs/scripts/webcmd.sh`](https://github.com/mnakada/atomcam_tools/blob/main/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`

```sh

# 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`](https://github.com/mnakada/atomcam_tools/blob/main/network_samples/network_init_linklocal.sh) demonstrates this configuration:

```sh

# 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:

```sh

# 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`](https://github.com/mnakada/atomcam_tools/blob/main/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`](https://github.com/mnakada/atomcam_tools/blob/main/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.