This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Basic Tutorial

Understand networking fundamentals through vivid metaphors

1: What is DNS
2: NullPrivate Fundamentals
3: Home Setup

📚 Reading Guide
To make networking knowledge easier to grasp, this tutorial uses plenty of everyday metaphors and analogies. Our goal is for everyone to master networking basics effortlessly, regardless of technical background. While these metaphors may not be perfectly rigorous, they will help you quickly build a foundational understanding of networking concepts.

Introduction to Networking Basics

In this tutorial, we’ll explain networking fundamentals through vivid metaphors and analogies. Our goal is for everyone to master these concepts effortlessly, regardless of technical background. While these metaphors may not be perfectly rigorous, they will help you quickly build a foundational understanding of networking concepts.

Unlike precise technical terms, this section uses plain language so non-technical readers can understand the basics of networking.

We’ll employ many fitting—or sometimes unfitting—metaphors and analogies, aiming to let readers grasp networking concepts quickly.

1 - What is DNS

DNS (Domain Name System) is one of the fundamental infrastructures of the Internet. This article introduces the basic concepts and working principles of DNS.

In essence, DNS service is like a Xinhua Dictionary; by consulting the dictionary, we can find the IP address corresponding to a domain name.

DNS Introduction

DNS (Domain Name System) is one of the fundamental infrastructures of the Internet. Like a Xinhua Dictionary, it is responsible for translating human-readable domain names into IP addresses that computers can understand.

DNS Resolution Principle

How DNS Works

When you enter a URL in your browser:

The browser first checks the local cache.
If not found, it initiates a query to a DNS server.
The DNS server returns the corresponding IP address.
The browser uses that IP address to access the target website.

Key Concepts

Domain Name: A human-readable address for a website, e.g., www.nullprivate.com
URL (Uniform Resource Locator): The complete web address, including protocol, domain name, and path, e.g., https://www.nullprivate.com
IP Address: A numerical identifier for network devices, e.g., 1.1.1.1
DNS Server: A computer that provides domain name resolution services
Web Hosting: Storing website files on a server so they can be accessed over the Internet

2 - NullPrivate Fundamentals

By intercepting at the DNS layer, NullPrivate effectively blocks ads, trackers, and malicious sites.

How It Works

NullPrivate safeguards your network security and privacy by intercepting requests at the DNS layer. It acts like an intelligent gatekeeper, screening every domain request:

✅ Safe sites: allowed through
❌ Ad domains: blocked
❌ Trackers: blocked
❌ Malicious sites: blocked

Interception Flow Diagram

NullPrivate Basic Interception Principle

Key Features

DNS-Level Blocking: Intercepts before the request is even made, more efficient
No Browser Plugins Needed: Network-layer protection works for every device
Minimal Resource Usage: Only handles DNS queries, negligible impact on device performance
Covers All Devices: One-time configuration protects every connected device

3 - Home Setup

A step-by-step guide to building the NullPrivate network ad-blocking service at home

Setting Up NullPrivate at Home

NullPrivate is an enhanced fork of AdGuard Home, purpose-built for superior network-level ad blocking and privacy protection. This tutorial walks you through installing and configuring NullPrivate on your home network.

Project Overview

NullPrivate is an open-source fork of AdGuard Home that offers both SaaS hosting and a rich set of extra features, all aimed at delivering a better DNS resolution and network-filtering experience.

Key Features

Original Features

Network-wide ad blocking: Block ads and trackers across the entire network
Custom filtering rules: Add personalized blocklists and allowlists
Encrypted DNS support: DNS-over-HTTPS, DNS-over-TLS, and DNSCrypt
Built-in DHCP server: Ready-to-use DHCP functionality
Per-client settings: Tailor settings for each individual device
Parental controls: Block adult content and enforce Safe Search
Cross-platform: Runs on Linux, macOS, Windows, and more
Privacy-first: No usage analytics or telemetry

NullPrivate Add-ons

DNS routing rule lists: Route DNS queries using rule lists in a config file
App-level blocking rules: Target specific application sources
Dynamic DNS (DDNS): Automatic hostname resolution updates
Advanced rate limiting: Efficient traffic management and control
Enhanced deployment: Load balancing, automatic certificate renewal, optimized connectivity

Installation Methods

Method 1: Download the Binary

Visit the Releases page and grab the binary for your OS.
Create a working directory:
```
mkdir -p ./data
```

Launch NullPrivate:

./NullPrivate -c ./AdGuardHome.yaml -w ./data --web-addr 0.0.0.0:34020 --local-frontend --no-check-update --verbose

Method 2: Use Docker

Docker is the easiest and most portable way to deploy:

docker run --rm --name NullPrivate \
  -p 34020:80 \
  -v ./data/container/work:/opt/adguardhome/work \
  -v ./data/container/conf:/opt/adguardhome/conf \
  nullprivate/nullprivate:latest

Supported Platforms

✅ Windows
✅ macOS
✅ Linux
✅ Docker
✅ Other Unix-like systems

Configuration Guide

Initial Setup

After launch, open the web UI to finish configuration:

Default admin URL: http://localhost:34020
Create an admin account on first run
Optionally import an existing AdGuard Home config

Configuration Files

The main file is AdGuardHome.yaml, which contains:

DNS server settings
Filtering rules
Client definitions
Security options

Command-Line Flags

Flag	Purpose
`-c`	Path to the configuration file
`-w`	Working directory
`--web-addr`	Address and port for the web UI
`--local-frontend`	Use the embedded web interface
`--no-check-update`	Disable automatic update checks
`--verbose`	Enable detailed logging

Usage Tips

Network setup: Point your router’s DNS to the NullPrivate IP
Rule updates: Refresh blocklists periodically for best coverage
Performance monitoring: Check DNS query stats in the web UI
Security hardening: Enable HTTPS and use a strong password
Backups: Regularly back up the config file and data directory

Troubleshooting

Common Issues

Port conflict: Make sure port 34020 is free
Permission errors: Ensure correct file permissions on Linux
Startup failure: Verify the config path and working directory exist

Getting Help

Read the official docs
Open an issue on GitHub Issues

Wrap-up

You should now have a working NullPrivate instance at home, giving you a cleaner, more private internet experience. NullPrivate’s rich feature set and flexible configuration options make it easy to tailor the service to your exact needs.