avahi-hosts

A collection of Bash scripts to generate a living hosts file using data from the Avahi Browser. This solution is designed to feed any hosts-based DNS service (such as Pi-hole's custom.list or dnsmasq addn-hosts) with current LAN hostnames, especially when you cannot rely on a built-in DHCP service. Many hosts-based engines cannot accept Dynamic DNS Updates (RFC 2136), and this script keeps the chosen hosts file synchronized with Avahi discoveries.

---

Table of Contents

1. About
2. Features
3. Prerequisites
4. Installation
5. Usage 5.1 dnsmasq hosts file notes
6. Configuration
7. Automating Execution
8. Examples
9. Contributing
10. License
11. Acknowledgments

---

1. About

The avahi-hosts project provides a solution for dynamically generating a static hosts file using Avahi's mDNS/Bonjour service discovery in a scheduled way. You can point the generated list at any hosts-based DNS resolver—Pi-hole, dnsmasq, or another capable daemon—so it always serves accurate hostnames for devices on your LAN, even if the resolver cannot accept Dynamic DNS Updates.

Avahi is used to detect active hosts and automatically updates their names to the file you specify with -f (a Pi-hole custom.list, a dnsmasq /etc/<lanname>.list, and so on), so your resolver keeps working even as devices join or leave the network.

---

2. Features

• Automated Host Discovery: Uses avahi-browse to discover devices on the local network.
• Static Hosts File Generation: Creates or updates a hosts file compatible with Pi-hole.
• Customizable Purge Time: Configurable duration to remove inactive hosts from the database.
• Flexible Hostname Suffix: Allows setting a custom domain suffix for hostnames.
• Debug Mode: Provides detailed logs for troubleshooting.
• Persistency: Maintains a database of known hosts with timestamps.

---

3. Prerequisites

• Operating System: Linux (tested on Ubuntu 24.04)
• Dependencies:
  • avahi-utils: Provides the avahi-browse command.
  • bash: The script uses Bash shell features.
• Permissions: The script must be run with root privileges since it updates system files.

---

4. Installation

1. Clone the Repository

   git clone https://github.com/your_username/avahi-hosts.git
   cd avahi-hosts

2. Copy the Script

   Place the avahi-hosts.sh script into a directory in your PATH, such as /usr/local/bin/:

   sudo cp avahi-hosts.sh /usr/local/sbin/
   sudo chmod +x /usr/local/sbin/avahi-hosts.sh

3. Install Dependencies

   Ensure avahi-utils is installed on your system:

   sudo apt update
   sudo apt install avahi-utils

4. Create Data Directory

   The script uses /etc/avahi-hosts/data to store its database file. It also creates this directory automatically, but if not:

   sudo mkdir -p /etc/avahi-hosts

   Ensure it has the correct permissions:

   sudo chmod 755 /etc/avahi-hosts

---

5. Usage

Run the script with elevated privileges and point it at the hosts file used by your resolver:

sudo avahi-hosts.sh -f /etc/pihole/custom.list

You can also feed any other hosts-based DNS service by changing the -f argument, for example -f /etc/<yourlanname>.list when dnsmasq is configured to read /etc/<lanname>.list.

Options

• -f output_hosts_file: Specify the output hosts file path (default: /path/to/pihole/custom.list).
• -s hostname_suffix: Specify the hostname suffix for the local network (default: .lan).
• -d: Enable debug mode for detailed output.
• -h: Display help message.

Example

sudo avahi-hosts.sh -d -f /etc/pihole/custom.list -s .local

This command runs the script in debug mode, outputs the hosts to /etc/pihole/custom.list, and uses .local as the hostname suffix.

---

Supporting dnsmasq or other addn-hosts consumers

When your DNS stack is managed with dnsmasq (or a similar resolver that reads a hosts file), point the script at the list dnsmasq consumes:

sudo avahi-hosts.sh -d -f /etc/<yourlanname>.list -s .<yourlanname>

Then ensure dnsmasq.conf references that list and your local domain, this works even with VPN adapters like tailscale, but make sure you understand the security implications:

• addn-hosts=/etc/<yourlanname>.list
• local=/<yourlanname>/
• except-interface=lo
• bind-dynamic
• Optional: server=1.1.1.1 (or your preferred upstream) so dnsmasq forwards beyond your LAN.

Keep /etc/<yourlanname>.list auto-generated by this script—avoid manual edits—and configure /etc/resolv.conf so clients (and the Pi itself) query the local dnsmasq instance first, with fallbacks to upstream resolvers. When the script rebuilds the list, dnsmasq will automatically use the fresh records without any extra steps.

If you also use systemd timers for automation, point the service at the same file (for example /etc/<yourlanname>.list) so the helper service shown below rebuilds dnsmasq's host list on schedule.

6. Configuration

Purge Time

The default purge time is 2880 minutes (2 days). To change this, edit the avahi_hosts.db file located in /etc/avahi-hosts/data/ and modify the line starting with # x= to your desired purge time in minutes.

sudo nano /var/lib/avahi-hosts/avahi_hosts.db

Change:

# x=2880

To:

# x=desired_purge_time_in_minutes

Hostname Suffix

If your network uses a different domain suffix, use the -s option to specify it when running the script.

---

7. Automating Execution

To run the script automatically every 12 hours, you can use either systemd timers. Here, we'll explain how to use systemd timers.

Using systemd Timers

1. Create systemd Service and Timer Files

   sudo cp systemd/avahi-hosts.* /etc/systemd/system/
   sudo nano /etc/systemd/system/avahi-hosts.service

   Content:

   [Unit]
   Description=Avahi Hosts Script for PiHole
   
   [Service]
   Type=oneshot
   ExecStart=/usr/local/bin/avahi-hosts.sh -f /etc/pihole/custom.list
   

2. Create a systemd Timer File

   sudo nano /etc/systemd/system/avahi-hosts.timer

   Content:

   [Unit]
   Description=Run Avahi Hosts Update every 12 hours
   
   [Timer]
   OnBootSec=15min
   OnUnitActiveSec=12h
   Persistent=true
   
   [Install]
   WantedBy=timers.target
   

3. Reload systemd and Enable the Timer

   sudo systemctl daemon-reload
   sudo systemctl enable avahi-hosts.timer
   sudo systemctl start avahi-hosts.timer

4. Verify the Timer

   systemctl list-timers avahi-hosts.timer

   This command will show when the timer last ran and when it is scheduled to run next.

Viewing Debug Output

To troubleshoot, run the script in debug mode:

sudo avahi-hosts.sh -d -f /etc/pihole/custom.list

This will output detailed information about the discovery process, host selection, and any issues encountered.

---

9. Contributing

Contributions are welcome! For significant changes, please open an issue first to discuss what you'd like to change.

Coding Standards

• ShellCheck: Please ensure your Bash code passes ShellCheck linting.
• Comments: Include comments explaining complex sections of code.
• Style: Follow consistent indentation and coding style throughout the script.

---

10. License

This project is licensed under the MIT License. See the LICENSE file for details.

---

11. Acknowledgments

• Avahi: A system which facilitates service discovery on a local network.
• Community Contributors: Thank you to everyone who has contributed to this project.

---

If there's anything you'd like me to add or adjust in this README document, please let me know!