{"id":13395238,"url":"https://github.com/tanrax/maza-ad-blocking","last_synced_at":"2025-05-14T12:09:47.190Z","repository":{"id":45248702,"uuid":"231528631","full_name":"tanrax/maza-ad-blocking","owner":"tanrax","description":"Simple, native and efficient local ad blocker. Only Bash.","archived":false,"fork":false,"pushed_at":"2024-12-23T13:00:22.000Z","size":2982,"stargazers_count":1822,"open_issues_count":1,"forks_count":69,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-04-11T04:58:25.273Z","etag":null,"topics":["ads","bash","blocker-proxy","dnsmasq","linux","macos","maza","pi-hole"],"latest_commit_sha":null,"homepage":"https://maza-ad-blocking.andros.dev/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tanrax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"liberapay":"androsfenollosa"}},"created_at":"2020-01-03T06:41:48.000Z","updated_at":"2025-03-30T13:43:47.000Z","dependencies_parsed_at":"2024-03-12T08:47:33.425Z","dependency_job_id":"8f79c9fe-51ac-4e77-a7ac-849490334ba9","html_url":"https://github.com/tanrax/maza-ad-blocking","commit_stats":{"total_commits":147,"total_committers":7,"mean_commits":21.0,"dds":0.3537414965986394,"last_synced_commit":"e32584b97804916c5d68ee223b7603ecfe41a79c"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tanrax%2Fmaza-ad-blocking","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tanrax%2Fmaza-ad-blocking/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tanrax%2Fmaza-ad-blocking/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tanrax%2Fmaza-ad-blocking/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tanrax","download_url":"https://codeload.github.com/tanrax/maza-ad-blocking/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248345273,"owners_count":21088244,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ads","bash","blocker-proxy","dnsmasq","linux","macos","maza","pi-hole"],"created_at":"2024-07-30T17:01:47.210Z","updated_at":"2025-04-11T04:58:38.676Z","avatar_url":"https://github.com/tanrax.png","language":"Shell","funding_links":["https://liberapay.com/androsfenollosa"],"categories":["Shell","Git Blocklist Repos","Apps","macos","System Utilities"],"sub_categories":["Host Blocking","Security","Directory Navigation"],"readme":"# Maza ad blocking\n\n## 🥇 Top 1 in Hacker News\n\nComments: https://news.ycombinator.com/item?id=22717650\n\n\u003cimg alt=\"banner\" src=\"media/banner.png\" width=\"100%\"\u003e\n\n## A command to squash all ads in all browsers\n\n```shell\nsudo maza start\n```\n\nLike Pi-hole but local and using your operating system.\n\nSimple, native and efficient **local ad blocker**. Bash script compatible with **MacOS**, **Linux**, **BSD** and **Windows Subsystem for Linux (WSL)**.\n\n- Just **bash** 🤖.\n- It affects **any browser** or software installed 😱.\n- You **don't have to install any browser extensions or applications** 🚫, you just use the tools of your operating system.\n- You update the list of DNS to be blocked with a **single command** 😎.\n- Pure **Opensource** ❤️.\n\n\u003cimg alt=\"demo\" src=\"media/demov2.jpg\"\u003e\n\n## Index\n\n- [Commands](#-commands)\n- [Install or update](#%EF%B8%8F-install-or-update)\n- [Check if you block ads](#-check-if-you-block-ads)\n- [Auto update of domains to be blocked](#-auto-update-of-domains-to-be-blocked)\n- [Uninstall](#-uninstall)\n- [Not blocking certain domains](#-not-blocking-certain-domains)\n- [Add custom domains to block](#-add-custom-domains-to-block)\n- [Alternative DNS list](#-alternative-dns-list)\n- [DNSMASQ (or support sub-domains: wildcards)](#dnsmasq)\n  - [Create your own Pi-Hole](#-create-your-own-pi-hole-server-with-maza)\n- [Projects inspired by Maza](#user-content-️-projects-inspired-by-maza)\n- [Donations](#-buy-me-a-coffee)\n- [Community or questions](#-get-help-or-talk-with-the-community)\n\n## 📟 Commands\n\n### 📡 Update database\n\n``` bash\nsudo maza update\n```\n\n### 🔨 Start\n\n``` bash\nsudo maza start\n```\n\n### 🛠 Stop\n\n``` bash\nsudo maza stop\n```\n\n### ⚖️ Status\n\n``` bash\nsudo maza status\n```\n\n## ⚙️ Install or Update\n\n### 😥 Requirements\n\n- **bash** 4.0 or higher\n- **curl**\n- Only macOS users, **gsed**: `brew install gnu-sed`\n\nThen you do this.\n\n``` bash\ncurl -o maza https://raw.githubusercontent.com/tanrax/maza-ad-blocking/master/maza \u0026\u0026 sudo rm -rf /usr/local/bin/maza \u0026\u0026 chmod +x maza \u0026\u0026 sudo mv maza /usr/local/bin\n```\n\nOptional but recommended, make a backup of your hosts file.\n\n``` bash\nsudo cp /etc/hosts /etc/hosts.backup\n```\n\n## 🧪 Check if you block ads\n\nYou can run a test to see if the domains are blocked.\n\nFor example, you can run the following command.\n\n``` bash\ncurl googleadservices.com\n```\n\nIf you get an error like this, it means that the domain is blocked.\n\n``` shell\ncurl: (7) Failed to connect to googleadservices.com port 80 after 2 ms: Could not connect to server\n```\n\nBut if you get a response with HTML, it means that the domain is not blocked (maybe a 404 error).\n\n\n## 🤖 Auto update of domains to be blocked\n\nOpen your `cron`.\n\n``` bash\ncrontab -e\n```\n\nAdd the following line at the end.\n\n```\n@daily maza update\n```\n\nSome users have reported problems creating daemons on MacOS. Fixed with `TERM=dumb`.\n\n```\nTERM=dumb\n@daily maza update\n```\n\n## 🔪 Uninstall\n\n``` bash\nsudo rm /usr/local/bin/maza \u0026\u0026 sudo rm -r /root/.config/maza\n```\n\n## 🚫 Not blocking certain domains\n\nEdit `/root/.config/maza/ignore` and add the domains you want to ignore.\n\nExample:\n\n``` txt\nads-twitter.com\nads.twitter.com\n```\n\nBy default, the following domains are ignored to avoid problems with the operating system.\n\n``` txt\nlocalhost\nlocalhost.localdomain\nlocal\nbroadcasthost\nip6-localhost\nip6-loopback\nip6-localnet\nip6-mcastprefix\nip6-allnodes\nip6-allrouters\nip6-allhosts\n0.0.0.0\n```\n\nFinally update Maza to apply the changes.\n\n``` bash\nsudo maza update\n```\n\n## 🎯 Add custom domains to block\n\nIf you want to include your own domains to be blocked, you can add them to `/root/.config/maza/custom-domains`. They must each be on one line, ignoring end slash or protocol (`http` or `https`).\n\nFor example:\n\n``` txt\nbeauty-tea.com\nwww.expaqua.cloud\nad.about.com\n```\n\nThen update the database to regenerate the list to include your domains.\n\n```\nsudo maza update\n```\n\n## 🔒 Alternative DNS list\n\nBy default the Yoyo (Peter Lowe) DNS list is used (3.7k blocked domains). If you want to use another list, such as Steven Black's for example (with 135k blocked domains), you must add the URL of your list on line 8.\n\n```\nURL_DNS_LIST_CUSTOM=\"https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts\"\n```\n\n## DNSMASQ\n\nUnfortunately the hosts file does **not support sub-domains (wildcards)**, which is necessary to correctly filter all DNS. You will **need to install locally a server** for that purpose, Maza supports the **Dnsmasq** format.\n\n[MacOS](#MacOS)\n\n[Linux](#user-content-linux-debianubuntu)\n\n### MacOS\n\n#### 0 Update Maza\n\n```bash\nsudo maza update\n```\n\n#### 1 Install\n\n```bash\nbrew install dnsmasq\n```\n\n#### 2 Configure\n\nEdit the file.\n\n```\n/usr/local/etc/dnsmasq.conf\n```\n\nAdd the following line at the end.\n\n```\nconf-file=(your user path)/.config/maza/dnsmasq.conf\n```\n\nExample\n\n```\nconf-file=/Users/myuser/.config/maza/dnsmasq.conf\n```\n\nStart DNSMASQ.\n\n```bash\nsudo brew services stop dnsmasq\nsudo brew services start dnsmasq\n```\n\n#### 3 Tell your OS to use your DNS server\n\nDelete the list of macOS DNS servers and add the 3 addresses. The first one will be your local server, and the other 2 belong to OpenDNS, which you can use any other.\n\n```bash\n127.0.0.1\n208.67.222.222\n208.67.220.220\n```\n\n\u003cimg alt=\"network macos\" src=\"media/network-osx.jpg\" width=\"500\"\u003e\n\nRefresh your DNS cache\n\n```bash\nsudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder\n```\n\n#### 4 Restart/Start Maza\n\n```bash\nsudo maza stop\nsudo maza start\n```\n\n### Linux (Debian/Ubuntu)\n\n#### 0 Update Maza\n\n```bash\nsudo maza update\n```\n\n#### 1 Install\n\n```bash\nsudo apt update\nsudo apt install dnsmasq\n```\n\n#### 2 Configure\n\nEdit file in path.\n\n```\n/etc/dnsmasq.conf\n```\n\nAdd the following line at the end.\n\n```\nconf-file=(your user path)/.config/maza/dnsmasq.conf\n```\n\nExample\n\n```\nconf-file=/home/myuser/.config/maza/dnsmasq.conf\n```\n\nStart DNSMASQ.\n\n```bash\nsudo systemctl stop dnsmasq\nsudo systemctl start dnsmasq\nsudo systemctl enable dnsmasq\n```\n\n#### 3 Tell your OS to use your DNS server\n\n##### 3.1 Gnome Shell\n\nIn Gnome Shell, open `Settings-\u003eNetwork`. Click in your connection.\n\n\u003cimg alt=\"network gnome\" src=\"media/network-gnome.png\" width=\"500\"\u003e\n\nAdd your local server (dnsmasq), and the other 2 belong to OpenDNS, which you can use any other.\n\n```bash\n127.0.0.1,208.67.222.222,208.67.220.220\n```\n\n\u003cimg alt=\"gnome dns\" src=\"media/dns-gnome.png\" width=\"500\"\u003e\n\n##### 3.2 KDE Plasma\n\nIn KDE Plasma, open `Settings-\u003eNetwork-\u003eConnectios`. Click in your connection and tab `ip4`.\n\n- `Method`: Automatic (Only addresses).\n\nAdd your local server (dnsmasq), and the other 2 belong to OpenDNS, which you can use any other.\n\n- `DNS Servers`: `127.0.0.1,208.67.222.222,208.67.220.220`.\n\n\u003cimg alt=\"kde dns\" src=\"media/dns-kde.png\" width=\"100%\"\u003e\n\n#### 4 Restart/Start Maza\n\n```bash\nsudo maza stop\nsudo maza start\n```\n\n### Bonus: dnsmasq is in charge of solving all DNS\n\nAdd in configure file: `/usr/local/etc/dnsmasq.conf`\n\n```\nno-resolv\nserver=208.67.222.222\nserver=208.67.220.220\n```\n\n### Bonus: dnsmasq have `localhost` domains\n\nIf you want all your `.localhost` domains, for example, point to localhost add in configure file: `/usr/local/etc/dnsmasq.conf` or `/etc/dnsmasq.conf`.\n\n```\naddress=/.localhost/127.0.0.1\n```\n\n## ☕ Buy me a coffee\n\nHelp me continue to improve.\n\n```shell\nssh customer@andros.dev -p 5555\n```\n\n## 💬 Get Help or talk with the community\n\n- [IRC: #maza-ad-blocking on irc.libera.chat](ircs://irc.libera.chat:6697/maza-ad-blocking)\n- [Fediverse/Mastodon](https://activity.andros.dev/@andros)\n\n## 🍓 CREATE YOUR OWN PI-HOLE SERVER WITH MAZA\n\nYou can easily create your own DNS server on a Raspberry Pi, VPS or wherever you want, to connect your devices in just 10 commands thanks to Maza. Follow the [tutorial](https://programadorwebvalencia.com/create-your-own-pi-hole-with-10-commands/).\n\n## 🎖️ Projects inspired by Maza\n\n- [adless](https://github.com/WIttyJudge/adless)\n\n## ⚠️ CAUTION\n\nRemember to make a backup copy of `/etc/hosts` in case of unforeseen circumstances, neither the project nor its author will be responsible for any possible repercussions derived from not carrying out this action.\n\n## 🧑‍🎨 Credits\n\n\u003ca target=\"_blank\" href=\"https://andros.dev/\"\u003eAndros Fenollosa\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftanrax%2Fmaza-ad-blocking","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftanrax%2Fmaza-ad-blocking","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftanrax%2Fmaza-ad-blocking/lists"}