maza-ad-blocking/README.md

366 lines
7.2 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-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
2024-05-05 15:04:06 +02:00
By 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.
2022-03-16 10:28:17 +01:00
```
2024-05-05 15:04:06 +02:00
URL_DNS_LIST_CUSTOM="https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts"
2022-03-16 10:28:17 +01:00
```
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-08-08 08:42:55 +02:00
## ☕ Buy me a coffee
2024-03-29 07:59:23 +01:00
2024-08-08 08:42:55 +02:00
Help me continue to improve.
2024-03-29 07:59:23 +01:00
2024-08-08 08:42:55 +02:00
```shell
ssh customer@andros.dev -p 5555
```
2024-03-29 08:01:58 +01:00
2024-08-08 08:42:55 +02:00
## 💬 Get Help or talk with the community
[Jabber/XMPP](xmpp:maza-ad-blocking@groups.im.andros.dev/?join)
2024-03-29 07:59:23 +01:00
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>