From e179d1c3d7f592413019adf839992754a30d564d Mon Sep 17 00:00:00 2001
From: Max Resnick <max@ofmax.li>
Date: Mon, 3 Mar 2025 22:07:17 -0800
Subject: docs: update info on the tool

---
 README.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index b06b0c2..7741c08 100644
--- a/README.md
+++ b/README.md
@@ -64,3 +64,77 @@ go build
 ```bash
 go test -v
 ```
+# unbound-ads
+
+A tool to generate [Unbound DNS server](https://nlnetlabs.nl/projects/unbound/about/) configuration for domain blocking. It fetches domain lists from URLs and converts them into Unbound's local-zone configuration format for DNS-based ad and malware blocking.
+
+## Features
+
+- Fetches domain lists from multiple URLs
+- Supports various domain list formats (hosts file format, plain domain lists)
+- Deduplicates domains automatically
+- Generates Unbound-compatible configuration
+- Progress logging with slog
+- Docker support
+
+## Installation
+
+
+### Using Docker
+
+```bash
+docker pull public.ecr.aws/s0f9o2k5/unbound-ads:latest
+```
+
+## Usage
+
+### Binary
+
+```bash
+unbound-ads <url-list> <output-file>
+```
+
+Where:
+- `url-list` is a URL containing a list of domain list URLs (one per line)
+- `output-file` is the path where the Unbound configuration will be written
+
+Example:
+```bash
+unbound-ads https://v.firebog.net/hosts/lists.php?type=tick blocking.conf
+```
+
+### Docker
+
+```bash
+docker run --rm -v "$PWD:/data" ghcr.io/yourusername/unbound-ads \
+  https://v.firebog.net/hosts/lists.php?type=tick /data/blocking.conf
+```
+
+## Building from Source
+
+Requirements:
+- Go 1.21 or later
+- just command runner
+- Docker (optional)
+
+```bash
+# Build binary
+just build
+
+# Build Docker image
+just docker-build
+
+# Run tests
+just test
+```
+
+## Output Format
+
+The tool generates Unbound configuration in this format:
+
+```
+local-zone: "example.com" refuse
+local-zone: "ads.example.com" refuse
+```
+
+When added to your Unbound configuration, these entries will cause Unbound to return NXDOMAIN for queries to blocked domains.
-- 
cgit v1.2.3