AdGuard Home

Self-Hosted

Network‑wide ad and tracker blocker

Active(100)

30.6kstars

1views

Updated 1 day ago

1 / 2

Overview

Discover what makes AdGuard Home powerful

AdGuard Home is a **network‑level DNS server** that filters out advertising, tracking, and malicious domains before they reach any device on the network. From a developer’s perspective it is essentially an HTTP‑style API + a high‑performance DNS resolver that supports **DNS over TLS, HTTPS, and QUIC**. The core logic is written in Go, enabling fast compilation, static binaries, and easy cross‑platform deployment. The application exposes a RESTful API for configuration, statistics, and real‑time rule management, making it suitable for integration into orchestration pipelines or custom dashboards.

Dynamic filtering

Advanced DNS features

Fine‑grained control

Metrics & analytics

Overview

AdGuard Home is a network‑level DNS server that filters out advertising, tracking, and malicious domains before they reach any device on the network. From a developer’s perspective it is essentially an HTTP‑style API + a high‑performance DNS resolver that supports DNS over TLS, HTTPS, and QUIC. The core logic is written in Go, enabling fast compilation, static binaries, and easy cross‑platform deployment. The application exposes a RESTful API for configuration, statistics, and real‑time rule management, making it suitable for integration into orchestration pipelines or custom dashboards.

Key Features

Dynamic filtering: Uses AdBlock‑style filter lists (e.g., EasyList, EasyPrivacy) and custom blocklists that can be updated at runtime via the API.
Advanced DNS features: Supports DNSSEC validation, DNS over TLS/HTTPS/QUIC, and local zone overrides for custom domain routing.
Fine‑grained control: Per‑client and per‑group policies, parental controls (Safe Search enforcement), and query logging with privacy‑preserving anonymization.
Metrics & analytics: Prometheus‑compatible metrics endpoint, JSON logs, and a built‑in UI that aggregates statistics on blocked queries, client activity, and filter performance.

Technical Stack

Layer	Technology
Runtime	Go 1.22+ (static binary, no external dependencies)
Networking	`net`/`golang.org/x/net/dns/dnsmessage`, custom TLS/QUIC handlers
Data storage	In‑memory structures for fast lookup; optional SQLite for persistent configuration and logging
API	JSON‑over‑HTTP (REST) with automatic OpenAPI spec generation; optional gRPC for low‑latency control
UI	Single‑page React app bundled with the binary; served over HTTPS with self‑signed certificates by default
Containerization	Official Docker image (`adguard/adguardhome`) based on Alpine, with minimal runtime footprint (~50 MB)

The Go codebase is heavily tested (≈80 % coverage, as shown by Codecov) and passes the Go Report Card checks, ensuring a stable foundation for custom extensions.

Core Capabilities

Rule Engine: Compiles filter rules into a highly optimized trie structure for O(1) lookup. Supports custom rule syntax (regex, domain suffixes, IP blocks).
API Endpoints:
- /control – CRUD operations for clients, groups, and filters.
- /api/v1/metrics – Prometheus metrics endpoint.
- /dns-query – DNS over HTTPS endpoint (JSON‑PIP).
Event Hooks: Webhook support for query events, allowing external services to react in real time (e.g., logging to a SIEM or triggering alerts).
Extensibility: Although the core is closed, developers can fork the repository or contribute via the public issue tracker. The filter engine exposes a Go API for custom rule processors.

Deployment & Infrastructure

AdGuard Home is designed to run on a single host but can be scaled horizontally with a load balancer in front of multiple instances. Because it is stateless (except for optional SQLite persistence), any changes to configuration can be propagated via the API or by mounting a shared volume. Containerized deployments are common in home automation stacks (e.g., Home Assistant, Synology Docker). For production use, recommend:

Running behind a reverse proxy that terminates TLS and provides IP whitelisting.
Enabling DNSSEC validation for upstream resolvers to protect against spoofing.
Using a dedicated network interface or VLAN for the DNS server to isolate traffic.

Integration & Extensibility

Custom Plugins: While the core does not support dynamic plugins, developers can extend functionality by embedding AdGuard Home as a library in their own Go applications. The filter engine and DNS resolver are exposed as packages.
API Automation: Terraform providers or Ansible modules can be built to manage AdGuard Home configuration declaratively.
Webhooks & Callbacks: Real‑time query data can be sent to external services (e.g., Grafana dashboards, Slack alerts) via HTTP POST.
Third‑Party Filters: Developers can host their own filter lists on GitHub or internal servers and point AdGuard Home to them via the API.

Developer Experience

The project follows a clean Git workflow, with comprehensive documentation on the wiki and a well‑structured API reference. The community is active on GitHub, Reddit, and Telegram, providing quick support for integration questions. The codebase is modular, making it straightforward to isolate components (e.g., the DNS server or the filter parser) for unit testing. The licensing model is AGPL‑3.0, which encourages open collaboration but requires derivative works to be released under the same license.

Use Cases

Home Automation – Deploy on a Raspberry Pi or router to block ads for all IoT devices without installing client software.
Enterprise Edge – Serve as a DNS firewall on the perimeter, integrating with corporate SIEMs via webhooks.
Custom Ad‑Blocking Service – Build a SaaS offering that provides users with a private DNS resolver, leveraging the API for on‑the‑fly filter updates.
Research & Education – Use the open source code as a teaching tool for DNS protocol internals and filter engine design.