maza-ad-blocking/README.md

373 lines
7.4 KiB
Markdown
Raw Normal View History

2023-08-22 12:42:10 +02:00
# Maza ad blocking
## 🥇 Top 1 in Hacker News
2020-03-30 08:47:49 +02:00
Comments: https://news.ycombinator.com/item?id=22717650
2021-04-26 23:25:27 +02:00
<img alt="banner" src="media/banner.png" width="100%">
2020-01-03 17:21:55 +01:00
2021-04-26 23:25:27 +02:00
## A command to squash all ads in all browsers
2021-04-26 23:27:38 +02:00
```shell
2021-04-26 23:28:19 +02:00
sudo maza start
2021-04-26 23:27:38 +02:00
```
2021-04-26 23:26:05 +02:00
Like Pi-hole but local and using your operating system.
2020-01-03 18:03:22 +01:00
2023-01-16 08:53:24 +01:00
Simple, native and efficient **local ad blocker**. Bash script compatible with **MacOS**, **Linux**, **BSD** and **Windows Subsystem for Linux (WSL)**.
2020-10-20 20:03:10 +02:00
2023-02-28 09:07:48 +01:00
- Just **bash** 🤖.
- It affects **any browser** or software installed 😱.
- You **don't have to install any browser extensions or applications** 🚫, you just use the tools of your operating system.
- You update the list of DNS to be blocked with a **single command** 😎.
- Pure **Opensource** ❤️.
2020-01-03 18:31:45 +01:00
2021-04-26 23:23:29 +02:00
<img alt="demo" src="media/demov2.jpg">
2020-10-20 19:55:48 +02:00
2023-08-21 18:40:45 +02:00
## Index
- [Commands](#-commands)
2023-08-21 18:41:54 +02:00
- [Install or update](#%EF%B8%8F-install-or-update)
2023-08-21 18:40:45 +02:00
- [Auto update of domains to be blocked](#-auto-update-of-domains-to-be-blocked)
- [Uninstall](#-uninstall)
- [Not blocking certain domains](#-not-blocking-certain-domains)
- [Add custom domains to block](#-add-custom-domains-to-block)
- [Alternative DNS list](#-alternative-dns-list)
- [DNSMASQ (or support sub-domains: wildcards)](#dnsmasq)
- [Create your own Pi-Hole](#-create-your-own-pi-hole-server-with-maza)
2020-10-20 20:11:35 +02:00
## Help me continue to improve
2020-10-20 20:03:10 +02:00
2020-10-20 20:07:53 +02:00
<p align="center">
2024-03-29 07:59:23 +01:00
<a href="https://liberapay.com/androsfenollosa/donate"><img alt="Donate using Liberapay" src="https://liberapay.com/assets/widgets/donate.svg"></a>
2020-10-20 20:07:53 +02:00
</p>
2020-10-20 20:03:10 +02:00
2020-08-23 19:28:05 +02:00
## 📟 Commands
2020-01-03 17:29:15 +01:00
2023-03-13 18:41:15 +01:00
### 📡 Update database
2020-01-03 17:29:15 +01:00
``` bash
2023-03-13 18:41:15 +01:00
maza update
2020-01-03 17:29:15 +01:00
```
2020-01-03 17:37:07 +01:00
### 🔨 Start
2020-01-03 17:29:15 +01:00
``` bash
2023-03-13 18:41:15 +01:00
sudo maza start
2020-01-03 17:29:15 +01:00
```
2020-01-03 17:37:07 +01:00
### 🛠 Stop
2020-01-03 17:29:15 +01:00
``` bash
2023-03-13 18:41:15 +01:00
sudo maza stop
2020-01-03 17:29:15 +01:00
```
2020-01-03 17:37:07 +01:00
### ⚖️ Status
2020-01-03 17:29:15 +01:00
``` bash
2023-03-13 18:41:15 +01:00
maza status
2020-01-03 17:29:15 +01:00
```
2023-08-21 10:47:17 +02:00
## ⚙️ Install or Update
2020-01-03 17:29:15 +01:00
2023-03-13 18:41:15 +01:00
### 😥 Requirements
2020-01-03 17:29:15 +01:00
2020-03-22 09:42:54 +01:00
- **bash** 4.0 or higher
- **curl**
2020-04-04 10:09:50 +02:00
- Only macOS users, **gsed**: `brew install gnu-sed`
2020-01-03 17:29:15 +01:00
Then you do this.
``` bash
2023-08-21 10:47:17 +02:00
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
2020-01-03 17:29:15 +01:00
```
2020-03-29 13:33:51 +02:00
Optional but recommended, make a backup of your hosts file.
``` bash
sudo cp /etc/hosts /etc/hosts.backup
```
2020-08-23 19:15:30 +02:00
## 🤖 Auto update of domains to be blocked
Open your `cron`.
``` bash
crontab -e
```
Add the following line at the end.
```
2020-08-23 19:22:04 +02:00
@daily maza update
2020-08-23 19:15:30 +02:00
```
2024-02-11 10:31:44 +01:00
Some users have reported problems creating daemons on MacOS. Fixed with `TERM=dumb`.
2024-01-22 08:40:23 +01:00
```
TERM=dumb
@daily maza update
```
2020-03-21 20:42:02 +01:00
## 🔪 Uninstall
2020-03-21 20:29:29 +01:00
``` bash
2023-05-29 10:09:37 +02:00
sudo rm /usr/local/bin/maza && sudo rm -r ~/.config/maza
2020-03-21 20:29:29 +01:00
```
2023-03-13 18:41:15 +01:00
## 🚫 Not blocking certain domains
2023-08-21 11:34:53 +02:00
Edit `~/.config/maza/ignore` and add the domains you want to ignore.
2023-03-13 18:41:15 +01:00
Example:
``` txt
ads-twitter.com
ads.twitter.com
```
2023-08-21 10:56:59 +02:00
By default, the following domains are ignored to avoid problems with the operating system.
``` txt
localhost
localhost.localdomain
local
broadcasthost
ip6-localhost
ip6-loopback
ip6-localnet
ip6-mcastprefix
ip6-allnodes
ip6-allrouters
ip6-allhosts
0.0.0.0
```
2023-03-13 18:41:15 +01:00
Finally update Maza to apply the changes.
``` bash
maza update
```
2023-08-21 18:40:45 +02:00
## 🎯 Add custom domains to block
If you want to include your own domains to be blocked, you can add them to `~/.config/maza/custom-domains`. They must each be on one line, ignoring end slash or protocol (`http` or `https`).
For example:
``` txt
beauty-tea.com
www.expaqua.cloud
ad.about.com
```
Then update the database to regenerate the list to include your domains.
```
maza update
```
2022-03-16 10:28:17 +01:00
## 🔒 Alternative DNS list
2023-03-13 18:41:15 +01:00
By default the Yoyo DNS list (Peter Lowe) is used. If you want to use another list, like Steven Black's for example, you must modify the variable in line 7.
2022-03-16 10:28:17 +01:00
2023-08-21 11:17:19 +02:00
Replace this line:
2022-03-16 10:28:17 +01:00
```
URL_DNS_LIST="https://pgl.yoyo.org/adservers/serverlist.php?showintro=0&mimetype=plaintext"
```
2023-08-21 11:17:19 +02:00
with this:
2022-03-16 10:28:17 +01:00
```
URL_DNS_LIST="https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts"
```
2020-01-04 08:53:35 +01:00
## DNSMASQ
2020-08-23 19:07:44 +02:00
Unfortunately 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.
2020-01-04 08:53:35 +01:00
2021-04-26 22:11:53 +02:00
[MacOS](#MacOS)
2021-04-26 22:12:56 +02:00
[Linux](#user-content-linux-debianubuntu)
2021-04-26 22:11:53 +02:00
2020-08-23 19:07:44 +02:00
### MacOS
2021-04-26 22:11:53 +02:00
#### 0 Update Maza
```bash
maza update
```
2020-08-23 19:07:44 +02:00
#### 1 Install
2020-01-04 08:53:35 +01:00
```bash
brew install dnsmasq
```
2020-08-23 19:07:44 +02:00
#### 2 Configure
2020-01-04 08:53:35 +01:00
Edit the file.
```
/usr/local/etc/dnsmasq.conf
```
2020-08-23 19:07:44 +02:00
Add the following line at the end.
2020-01-04 08:53:35 +01:00
```
2023-05-29 10:09:37 +02:00
conf-file=(your user path)/.config/maza/dnsmasq.conf
2020-01-04 08:53:35 +01:00
```
2020-08-23 19:07:44 +02:00
Example
```
2023-05-29 10:09:37 +02:00
conf-file=/Users/myuser/.config/maza/dnsmasq.conf
2020-08-23 19:07:44 +02:00
```
2020-01-04 08:53:35 +01:00
Start DNSMASQ.
```bash
sudo brew services stop dnsmasq
sudo brew services start dnsmasq
```
2020-08-23 19:07:44 +02:00
#### 3 Tell your OS to use your DNS server
2020-01-04 08:53:35 +01:00
2020-04-04 10:09:50 +02:00
Delete 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.
2020-01-04 08:53:35 +01:00
```bash
127.0.0.1
208.67.222.222
208.67.220.220
```
2020-04-04 10:09:50 +02:00
<img alt="network macos" src="media/network-osx.jpg" width="500">
2020-03-30 09:00:31 +02:00
2020-01-04 08:53:35 +01:00
Refresh your DNS cache
```bash
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
```
2020-08-23 19:07:44 +02:00
#### 4 Restart/Start Maza
```bash
sudo maza stop
sudo maza start
```
2021-04-26 22:11:53 +02:00
### Linux (Debian/Ubuntu)
#### 0 Update Maza
```bash
maza update
```
2020-08-23 19:07:44 +02:00
#### 1 Install
```bash
sudo apt update
sudo apt install dnsmasq
```
#### 2 Configure
Edit file in path.
```
/etc/dnsmasq.conf
```
Add the following line at the end.
```
2023-05-29 10:09:37 +02:00
conf-file=(your user path)/.config/maza/dnsmasq.conf
2020-08-23 19:07:44 +02:00
```
Example
```
2023-05-29 10:09:37 +02:00
conf-file=/home/myuser/.config/maza/dnsmasq.conf
2020-08-23 19:07:44 +02:00
```
Start DNSMASQ.
```bash
sudo systemctl stop dnsmasq
sudo systemctl start dnsmasq
sudo systemctl enable dnsmasq
```
#### 3 Tell your OS to use your DNS server
2021-04-26 22:11:53 +02:00
##### 3.1 Gnome Shell
2020-08-23 19:07:44 +02:00
2024-02-11 10:31:44 +01:00
In Gnome Shell, open `Settings->Network`. Click in your connection.
2021-04-26 22:11:53 +02:00
<img alt="network gnome" src="media/network-gnome.png" width="500">
2020-08-23 19:07:44 +02:00
Add your local server (dnsmasq), and the other 2 belong to OpenDNS, which you can use any other.
```bash
127.0.0.1,208.67.222.222,208.67.220.220
```
2021-04-26 22:11:53 +02:00
<img alt="gnome dns" src="media/dns-gnome.png" width="500">
##### 3.2 KDE Plasma
2024-02-11 10:31:44 +01:00
In KDE Plasma, open `Settings->Network->Connectios`. Click in your connection and tab `ip4`.
2021-04-26 22:11:53 +02:00
2021-04-26 22:17:06 +02:00
- `Method`: Automatic (Only addresses).
Add your local server (dnsmasq), and the other 2 belong to OpenDNS, which you can use any other.
- `DNS Servers`: `127.0.0.1,208.67.222.222,208.67.220.220`.
2021-04-26 22:11:53 +02:00
2021-04-26 22:17:06 +02:00
<img alt="kde dns" src="media/dns-kde.png" width="100%">
2020-08-23 19:07:44 +02:00
#### 4 Restart/Start Maza
```bash
sudo maza stop
sudo maza start
```
2020-03-22 09:41:05 +01:00
### Bonus: dnsmasq is in charge of solving all DNS
2020-01-05 08:45:25 +01:00
2020-05-09 16:38:13 +02:00
Add in configure file: `/usr/local/etc/dnsmasq.conf`
2020-01-05 08:45:25 +01:00
```
no-resolv
server=208.67.222.222
server=208.67.220.220
```
2020-08-23 19:07:44 +02:00
### Bonus: dnsmasq have `localhost` domains
2020-01-05 08:45:25 +01:00
2020-08-23 19:07:44 +02:00
If you want all your `.localhost` domains, for example, point to localhost add in configure file: `/usr/local/etc/dnsmasq.conf` or `/etc/dnsmasq.conf`.
2020-01-05 08:45:25 +01:00
```
address=/.localhost/127.0.0.1
```
2024-03-29 07:59:23 +01:00
## 💬 Get Help or talk to the community
[Jabber/XMPP](xmpp://maza-ad-blocking@conference.im.andros.dev/?join)
2022-10-04 16:46:44 +02:00
## 🍓 CREATE YOUR OWN PI-HOLE SERVER WITH MAZA
2022-03-16 20:42:45 +01:00
You 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/).
2020-01-03 17:37:07 +01:00
## ⚠️ CAUTION
2020-01-03 17:21:55 +01:00
2023-01-16 08:56:03 +01:00
Remember 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.
2020-04-10 14:01:51 +02:00
## 🧑‍🎨 Credits
2023-01-16 08:56:03 +01:00
<a target="_blank" href="https://andros.dev/">Andros Fenollosa</a>