Deploying Maza Ad Blocking

Introduction

Maza is a lightweight, local ad blocker that works by modifying your system’s hosts file to block advertising, tracking, and malware domains at the network level. Unlike browser-based ad blockers that only work within specific browsers, Maza provides system-wide protection that blocks unwanted content across all applications.

Built as a simple bash script, Maza aggregates multiple trusted hosts file sources to create a comprehensive blocklist. The tool is designed to be simple, transparent, and respect user privacy by keeping all blocking local to your machine without requiring external DNS services.

Key highlights of Maza:

• System-Wide Blocking: Blocks ads and trackers across all applications, not just browsers
• Multiple Sources: Aggregates blocklists from StevenBlack, energized, and other trusted sources
• Simple CLI: Easy-to-use command-line interface for starting, stopping, and updating blocklists
• No External Dependencies: Works entirely locally without sending DNS queries to third-party services
• Transparent Operation: Uses standard hosts file blocking that you can inspect and modify
• Lightweight: Minimal resource usage with no background processes required
• Privacy-Focused: No data collection or external communication after initial blocklist download
• Cross-Platform: Works on Linux and macOS systems

This guide walks through deploying a Maza-based DNS blocking service on Klutch.sh using Docker, providing network-wide ad blocking for your infrastructure.

Why Deploy Maza on Klutch.sh

Deploying Maza on Klutch.sh provides several advantages for network-wide ad blocking:

Centralized Blocking: Host a DNS-based ad blocking service that can protect multiple devices on your network without installing software on each device.

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds your ad blocking service without complex configuration.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access to any management interface.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates to your blocklist configuration trigger automatic redeployments.

Persistent Storage: Attach persistent volumes for blocklist caching and configuration, ensuring your setup survives container restarts.

Scalable Resources: Allocate CPU and memory based on your network size and expected DNS query volume.

Always-On Availability: Your ad blocking service remains accessible 24/7 without managing your own hardware.

Prerequisites

Before deploying Maza on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and containerization concepts
• Understanding of DNS and hosts file blocking

Preparing Your Repository

To deploy a Maza-based blocking service on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

maza-deploy/
├── Dockerfile
├── blocklist-updater.sh
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM alpine:latest

# Install required packages
RUN apk add --no-cache \
    bash \
    curl \
    dnsmasq \
    ca-certificates \
    tzdata

# Create directories
RUN mkdir -p /etc/maza /var/log/dnsmasq

# Copy blocklist updater script
COPY blocklist-updater.sh /usr/local/bin/blocklist-updater.sh
RUN chmod +x /usr/local/bin/blocklist-updater.sh

# Configure dnsmasq
RUN echo "addn-hosts=/etc/maza/hosts" >> /etc/dnsmasq.conf && \
    echo "log-queries" >> /etc/dnsmasq.conf && \
    echo "log-facility=/var/log/dnsmasq/queries.log" >> /etc/dnsmasq.conf

# Expose DNS port
EXPOSE 53/udp
EXPOSE 53/tcp

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
  CMD nslookup localhost 127.0.0.1 || exit 1

# Start script
CMD ["/bin/bash", "-c", "/usr/local/bin/blocklist-updater.sh && dnsmasq -d"]

Creating the Blocklist Updater Script

Create a blocklist-updater.sh script:

#!/bin/bash

# Maza-style hosts file aggregator
HOSTS_FILE="/etc/maza/hosts"
SOURCES=(
    "https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts"
    "https://adaway.org/hosts.txt"
    "https://v.firebog.net/hosts/AdguardDNS.txt"
)

echo "Updating blocklists..."
> "$HOSTS_FILE"

for source in "${SOURCES[@]}"; do
    echo "Fetching: $source"
    curl -s "$source" | grep -E "^0\.0\.0\.0|^127\.0\.0\.1" >> "$HOSTS_FILE" 2>/dev/null || true
done

# Remove duplicates and comments
sort -u "$HOSTS_FILE" -o "$HOSTS_FILE"

echo "Blocklist updated with $(wc -l < "$HOSTS_FILE") entries"

Environment Variables Reference

Variable	Required	Default	Description
TZ	No	UTC	Timezone for logging
UPDATE_INTERVAL	No	86400	Blocklist update interval in seconds

Deploying on Klutch.sh

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile blocklist-updater.sh .dockerignore
git commit -m "Initial Maza ad blocking configuration"
git remote add origin https://github.com/yourusername/maza-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “maza-adblock” or “dns-blocking”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Maza Dockerfile.

Configure Network Settings

For DNS-based blocking:

• Configure your deployment for UDP/TCP traffic on port 53
• Note: DNS traffic requires specific port configuration

Set Environment Variables

Add the following environment variables:

Variable	Value
TZ	Your timezone (e.g., America/New_York)

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/etc/maza	100 MB	Blocklist hosts file
/var/log/dnsmasq	500 MB	DNS query logs

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container and start your ad blocking service.

Configure DNS Clients

Point your devices or network router to use your Klutch.sh deployment as the DNS server.

Blocklist Configuration

Adding Custom Blocklists

Modify your blocklist-updater.sh to include additional sources:

SOURCES=(
    "https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts"
    "https://adaway.org/hosts.txt"
    "https://v.firebog.net/hosts/AdguardDNS.txt"
    "https://someonewhocares.org/hosts/hosts"
    "https://raw.githubusercontent.com/crazy-max/WindowsSpyBlocker/master/data/hosts/spy.txt"
)

Whitelisting Domains

Create a whitelist to exclude specific domains:

# In blocklist-updater.sh, after updating:
while read domain; do
    sed -i "/$domain/d" "$HOSTS_FILE"
done < /etc/maza/whitelist.txt

Monitoring and Logging

Viewing DNS Queries

Access DNS query logs in /var/log/dnsmasq/queries.log to see which domains are being blocked.

Blocked Domain Statistics

Analyze your logs to see which ad domains are most frequently blocked:

grep "is 0.0.0.0" /var/log/dnsmasq/queries.log | awk '{print $6}' | sort | uniq -c | sort -rn | head -20

Troubleshooting

DNS Queries Not Being Blocked

• Verify the blocklist file was created successfully
• Check that dnsmasq is reading the hosts file
• Ensure client devices are using your DNS server

Blocklist Not Updating

• Check network connectivity to blocklist sources
• Verify the update script has execute permissions
• Review logs for curl errors

Legitimate Sites Being Blocked

• Add the domain to your whitelist
• Check which source list is blocking the domain
• Update your blocklist configuration

Additional Resources

• Maza GitHub Repository
• StevenBlack Hosts
• The Big Blocklist Collection
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Maza-style ad blocking on Klutch.sh gives you a centralized, network-wide solution for blocking ads, trackers, and malware domains. By using hosts file blocking through a DNS server, you can protect all devices on your network without installing software on each device.

The combination of aggregated blocklists from trusted sources and Klutch.sh’s reliable infrastructure provides effective, always-on protection for your network while respecting privacy by keeping all blocking local to your deployment.