# Maza: a local Bash ad blocker with optional dnsmasq support

> Maza blocks advertising and tracking domains on macOS, Linux, BSD and WSL by managing local DNS and hosts-file data from Bash. It suits users who want system-wide filtering without a browser extension, but its dnsmasq setup adds local service configuration.

**tanrax/maza-ad-blocking** — Simple, native and efficient local ad blocker. Only Bash.

- Repository: https://github.com/tanrax/maza-ad-blocking
- Website: https://maza-ad-blocking.andros.dev/
- Stars: 1,875 · Forks: 72
- Language: Shell
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/tanrax-maza-ad-blocking

## Why Maza targets system-wide DNS instead of a browser extension

Maza addresses the problem of advertising domains appearing across browsers and other software installed on a machine. Its documented scope is local rather than network-wide: the project describes itself as a local ad blocker based on the operating system, and says that it affects any browser or software without requiring browser extensions or separate applications.

That distinction matters for the intended user. A browser extension can filter requests made by one browser, while Maza is aimed at users who want filtering to apply to multiple applications at the DNS or hosts-file level. It is also suitable for a single workstation, a home lab or a small personal setup where adding a full network service would be unnecessary.

The basic command is short because the tool is implemented as a Bash script. Installation places the `maza` executable in `/usr/local/bin`, while its configuration is kept under `/root/.config/maza` when commands are run with `sudo`. This arrangement makes the operating system the application layer, but it also means the user is responsible for backups, configuration edits and removal of system-managed files.

## Inside Maza's database, hosts file and dnsmasq paths

Maza has two filtering paths described by the README. The simpler path uses the hosts file and a downloadable DNS block list. The default list is the Yoyo Peter Lowe list, which the documentation describes as containing 3.7k blocked domains. Running `sudo maza update` refreshes the database and applies configured filtering. A test request such as `curl googleadservices.com` should fail to connect when the domain is blocked; an HTML response, including a 404 response, indicates that the request was not blocked.

Maza also supports custom domains. Entries in `/root/.config/maza/custom-domains` are included when the database is regenerated, with one domain per line and no protocol or trailing slash. Exclusions belong in `/root/.config/maza/ignore`, followed by another update. The default exclusions include loopback names such as `localhost` and several IPv6 local hostnames, which prevents the generated blocking rules from interfering with local operating-system resolution.

The hosts file has a documented limitation: it does not support wildcard subdomains. For filtering that depends on subdomain matching, Maza supports dnsmasq format. In this mode, dnsmasq becomes the local DNS server, `/usr/local/etc/dnsmasq.conf` or `/etc/dnsmasq.conf` includes the generated Maza configuration, and the operating system is pointed at `127.0.0.1` plus fallback DNS addresses. This is a different architecture from editing only the hosts file. It handles wildcard requirements more directly, but it adds a service, a configuration file and operating-system DNS settings.

## Installing Maza and running the first blocking command

The documented requirements are Bash 4.0 or higher and `curl`. macOS users also need `gsed`, installed through Homebrew according to the README. The installation command downloads the script from the repository and places it in `/usr/local/bin`. The optional backup is prudent because Maza changes the system hosts file.

On macOS, install the required replacement first:

```bash
brew install gnu-sed
```

Then create a hosts-file backup and install Maza with the documented commands:

```bash
sudo cp /etc/hosts /etc/hosts.backup
curl -o maza https://raw.githubusercontent.com/tanrax/maza-ad-blocking/master/maza && sudo rm -rf /usr/local/bin/maza && chmod +x maza && sudo mv maza /usr/local/bin
```

The first real use is to start the blocker and inspect a known blocked domain:

```bash
sudo maza start
curl googleadservices.com
```

The expected result is a connection error for `googleadservices.com`. A response containing HTML means that the domain was not blocked, although the README notes that the response might be a 404. The `sudo maza status`, `sudo maza stop` and `sudo maza update` commands cover state inspection, stopping and database refreshes. The README does not document a non-privileged mode for these commands, so the `sudo` examples should be treated as part of the documented interface.

## Updating lists and scheduling daily database refreshes

Maza separates blocking from maintenance. The `sudo maza update` command downloads or regenerates the configured list, while `sudo maza start` activates the current configuration. That separation is useful when a list changes because the user can refresh data before restarting or applying it, although the README does not state every detail of the internal file transaction.

For automatic refreshes, the documented cron entry is:

```bash
sudo crontab -e
```

The README then instructs users to add this line:

```cron
@daily maza update
```

macOS requires additional cron environment settings because cron runs with a minimal environment. The documented block is:

```cron
PATH=/bin:/usr/bin:/usr/local/bin:/opt/homebrew/bin
TERM=dumb
@daily maza update
```

This includes the Bash and `env` locations, `/usr/local/bin` for Maza, and `/opt/homebrew/bin` for `gsed` on Apple Silicon. Intel Mac users are told to adjust that path as needed. The project therefore reduces update work to a scheduled command, but the schedule does not remove the need to check logs, list availability or the effect of blocked domains. No GitHub releases are listed, and the README does not document a rollback command or a compatibility policy for database changes.

## Choosing dnsmasq for wildcard subdomain filtering

Maza is a poor fit for a request that depends on wildcard subdomains if the hosts-file path is used, because the README explicitly says that hosts files do not support that behavior. The dnsmasq path is the documented alternative. On macOS, install dnsmasq, include Maza's generated configuration, restart the Homebrew service, configure the system DNS addresses, flush the macOS DNS cache and restart Maza:

```bash
brew install dnsmasq
sudo brew services stop dnsmasq
sudo brew services start dnsmasq
```

The configuration file named in the README is `/usr/local/etc/dnsmasq.conf`. It should contain a line in this form, with the user path adjusted to the actual account:

```text
conf-file=/Users/myuser/.config/maza/dnsmasq.conf
```

The documented DNS values for macOS are `127.0.0.1`, `208.67.222.222` and `208.67.220.220`. The local address handles dnsmasq, while the two OpenDNS addresses provide the fallback arrangement described by the README.

On Debian or Ubuntu, the documented installation and service commands are:

```bash
sudo apt update
sudo apt install dnsmasq
sudo systemctl stop dnsmasq
sudo systemctl start dnsmasq
sudo systemctl enable dnsmasq
```

The relevant file is `/etc/dnsmasq.conf`, with an example such as `conf-file=/home/myuser/.config/maza/dnsmasq.conf`. GNOME and KDE require the user to set `127.0.0.1,208.67.222.222,208.67.220.220` or the equivalent DNS values in the desktop network settings. This adds meaningful administrative work compared with the hosts-file mode, so dnsmasq should be selected for wildcard filtering rather than simply because it is available.

## Maza versus Pi-hole and network-wide DNS management

The README describes Maza as “Like Pi-hole but local and using your operating system.” The practical difference is scope and implementation. Pi-hole is presented in the documentation as the inspiration for creating a server with Maza, while Maza's basic operation is a Bash command that updates a local hosts file or integrates with dnsmasq on one machine.

A local design means Maza does not need to become the DNS server for every device on a network. It can affect software installed on the host without browser-specific configuration. That is a direct fit for a personal computer or a controlled workstation. The trade-off is centralized control. The README does not document a dashboard, multi-user administration model, network-wide deployment process or per-client policy management for Maza.

The dnsmasq instructions change the operational picture, but they do not make Maza a full network appliance. The user still installs and configures dnsmasq, points the local operating system at it, schedules list updates and manages custom and ignored domains manually. Maza is more relevant when the goal is a lightweight local script and system-level blocking with direct control over files.

## Custom rules, licensing and the maintenance cost of local administration

Maza gives the user two direct customization points: exclusions in `/root/.config/maza/ignore` and additional blocked domains in `/root/.config/maza/custom-domains`. An exclusion file can contain entries such as `ads-twitter.com` or `ads.twitter.com`; a custom file can contain `beauty-tea.com`, `www.expaqua.cloud` or `ad.about.com`. The README requires one entry per line and says to omit protocols and trailing slashes. Changes take effect after `sudo maza update`.

The default Yoyo list can be replaced by editing line 8 of the script. The documented example is:

```bash
URL_DNS_LIST_CUSTOM="https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts"
```

This creates an upgrade and operations cost. The project is licensed under Apache-2.0, so the repository carries a permissive open-source license, but the README does not provide legal interpretation or guidance for redistribution and modification. Operational cost comes from updating lists, reviewing false positives, maintaining cron entries and, if used, keeping dnsmasq and the operating system's DNS configuration consistent.

The repository is not archived, and its last push was on 2026-08-14. There are no GitHub releases listed. There are no GitHub releases listed. The README also does not document rollback, so restoring `/etc/hosts.backup` is the only backup step explicitly described.

## Conclusion

Adopt Maza if you want a small, local command-line blocker and are comfortable administering `/etc/hosts`, cron or dnsmasq. Do not choose it if you need a centrally managed network filter or a supported graphical control plane. Before installing, verify that your operating system, shell, `curl`, and optional `gsed` or dnsmasq requirements match the documented setup, and inspect the resulting hosts and DNS configuration before applying changes.

## FAQ

### What operating systems does Maza support?

Maza is documented as compatible with macOS, Linux, BSD and Windows Subsystem for Linux. The README requires Bash 4.0 or higher and `curl`, with `gsed` additionally required for macOS users.

### How do I install Maza on my computer?

The README provides a `curl` command that downloads the `maza` script and moves it into `/usr/local/bin`. It also recommends backing up `/etc/hosts` before installation.

### Can Maza block ads in browsers and other applications?

Yes. The README says Maza affects any browser or software installed on the system, rather than requiring a browser extension or application.

### When should I use dnsmasq with Maza?

The README says dnsmasq is needed when filtering depends on wildcard subdomains, because the hosts file does not support subdomains. Maza can generate a dnsmasq configuration that is included by the local dnsmasq server.

### How do I stop or check Maza?

Use `sudo maza stop` to stop Maza and `sudo maza status` to inspect its status. The README also documents `sudo maza start` and `sudo maza update`.

## Sources

- [Issues](https://github.com/tanrax/maza-ad-blocking/issues)
- [License: Apache-2.0](https://github.com/tanrax/maza-ad-blocking/blob/master/LICENSE)
- [Project website](https://maza-ad-blocking.andros.dev/)
- [README](https://github.com/tanrax/maza-ad-blocking/blob/master/README.md)
- [tanrax/maza-ad-blocking on GitHub](https://github.com/tanrax/maza-ad-blocking)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tanrax-maza-ad-blocking