Maza Ad Blocking

Maza ad blocking is a lightweight, self‑hosted DNS filtering tool that operates entirely within the host operating system. Instead of relying on a browser extension or an external service, it modifies the local hosts file (or uses dnsmasq for more advanced scenarios) to resolve known ad domains to the loopback address. This approach guarantees that any network request—whether made by a browser, mobile app, or system service—is intercepted before it reaches the internet. The tool is written in plain Bash and requires only bash 4.x, curl, and optionally GNU‑sed on macOS. Its minimal footprint makes it ideal for developers who want a reproducible, scriptable ad‑blocking solution that can be deployed across multiple platforms (Linux, macOS, BSD, WSL).

Technical Stack & Architecture

• Language: Bash (POSIX‑compatible, with optional GNU extensions on macOS).
• Runtime: Native shell; no runtime dependencies beyond the standard Unix toolset.
• Data Store: Plain text files (/root/.config/maza/domains.txt, ignore) that are periodically fetched via curl from an online blocklist.
• DNS Resolution: Two modes are supported:
  1. Hosts‑file mode – appends entries to /etc/hosts.
  2. dnsmasq mode – launches a lightweight local DNS server that forwards all non‑blocked queries upstream, enabling wildcard support and subdomain filtering.
• Deployment: The binary is a single executable script installed under /usr/local/bin. It can be run as a systemd service, launch daemon (macOS), or manually via sudo maza start/stop. The package also provides a cron‑based updater (@daily maza update) for automatic list refreshes.

Core Capabilities & APIs

• Domain List Management: maza update pulls the latest blocklist from a configured URL, parses it, and writes to the hosts or dnsmasq configuration.
• Whitelist / Ignore Support: Users can edit /root/.config/maza/ignore to exempt specific domains from blocking.
• Custom Domains: Developers can append custom entries to the blocklist file, allowing project‑specific filtering.
• Status & Diagnostics: maza status reports whether the service is running, and curl tests confirm that blocked domains resolve to 127.0.0.1 or fail to connect.
• Extensibility: While the core is a Bash script, developers can hook into its update cycle by replacing the blocklist URL or injecting additional hosts entries via a wrapper script. The dnsmasq mode can be extended with custom DNS records or upstream resolvers.

Deployment & Infrastructure

• Self‑Hosting Requirements: A machine with a POSIX shell, network access for downloading blocklists, and write permission to /etc/hosts or a dedicated directory for dnsmasq.
• Scalability: The hosts‑file approach scales to thousands of entries without performance degradation, as the OS performs a simple lookup. dnsmasq can handle higher query volumes and provides caching for improved throughput.
• Containerization: A Docker image can be built around the script, exposing /etc/hosts or a dnsmasq socket. This makes it straightforward to run Maza inside CI pipelines, home‑lab containers, or cloud VMs.
• High Availability: For environments requiring failover, a secondary instance can be spun up with identical blocklists; traffic can be routed via system routing rules or a load balancer that forwards DNS queries to the active Maza service.

Integration & Extensibility

• Plugin System: While not a formal plugin architecture, developers can write auxiliary scripts that generate blocklist fragments or modify the ignore file, then trigger maza update.
• Webhooks & Automation: By exposing the update command as a REST endpoint (e.g., via a lightweight HTTP server), external systems can trigger list refreshes or report blocking statistics.
• Custom DNS Resolvers: In dnsmasq mode, upstream resolvers can be configured (e.g., Cloudflare, Google DNS), enabling a hybrid approach that blocks ads locally but relies on fast external resolution for legitimate traffic.
• Wildcard Support: dnsmasq mode allows *.ads.example.com entries, giving developers granular control over subdomain filtering.

Developer Experience

• Configuration Simplicity: All settings are text files; no complex YAML or JSON.
• Documentation Quality: The README provides clear command references and troubleshooting tips, but the lack of a formal API documentation means developers must inspect the Bash source for advanced use cases.
• Community & Support: The project has a modest but active GitHub presence, with issues covering macOS launchd quirks and WSL networking. Community contributions are accepted via pull requests, and the project’s “Top 1 on Hacker News” badge indicates strong community interest.
• Licensing: The tool is fully open‑source under the MIT license, allowing unrestricted modification and redistribution—critical for enterprise or security‑focused deployments.

Use Cases

1. Developer Workstations – Quickly block intrusive ad networks while testing web applications locally, ensuring that analytics or tracking scripts do not interfere with debugging.
2. CI/CD Pipelines – Run Maza in a Docker container to provide deterministic DNS responses during automated tests, preventing flaky network calls caused by ad redirects.
3. Home Labs & IoT – Deploy