fix: update PKGBUILD URL to mohamad/doh-forwarder repo
This commit is contained in:
145
README.md
145
README.md
@@ -2,14 +2,18 @@
|
||||
|
||||
A lightweight DNS-over-HTTPS (DoH) forwarder written in Rust.
|
||||
|
||||
Accepts DNS queries over HTTPS ([RFC 8484](https://www.rfc-editor.org/rfc/rfc8484)) and forwards them to upstream DoH resolvers (Cloudflare, Google, Quad9, or custom).
|
||||
Accepts DNS queries over traditional DNS (UDP/TCP) and HTTP DoH ([RFC 8484](https://www.rfc-editor.org/rfc/rfc8484)), then forwards them upstream via DoH (HTTPS POST) to configurable resolvers.
|
||||
|
||||
## Why?
|
||||
|
||||
See [docs/story.md](docs/story.md) for the full context — why this exists, what already works, and where this project is headed.
|
||||
|
||||
## Features
|
||||
|
||||
- **Dual-protocol listener** — traditional DNS (UDP/TCP) + HTTP DoH endpoints
|
||||
- **RFC 8484 compliant** — GET (`?dns=base64url`) and POST (`application/dns-message`)
|
||||
- **Multiple upstreams** — configure several DoH resolvers
|
||||
- **Selection strategies** — round-robin or failover
|
||||
- **In-memory cache** — TTL-aware with LRU eviction (configurable)
|
||||
- **Selection strategies** — round-robin or failover with automatic retry
|
||||
- **Environment overrides** — override config via env vars
|
||||
- **Graceful shutdown** — handles SIGINT and SIGTERM
|
||||
- **Health endpoint** — `GET /health`
|
||||
@@ -20,7 +24,7 @@ Accepts DNS queries over HTTPS ([RFC 8484](https://www.rfc-editor.org/rfc/rfc848
|
||||
# Build
|
||||
cargo build --release
|
||||
|
||||
# Run with default config
|
||||
# Run with default config (DoH on :8800, DNS on :53530)
|
||||
./target/release/doh-forwarder
|
||||
|
||||
# Run with a custom config
|
||||
@@ -29,94 +33,111 @@ cargo build --release
|
||||
|
||||
## Configuration
|
||||
|
||||
Create a TOML config file (see [config/default.toml](config/default.toml)):
|
||||
See [config/default.toml](config/default.toml):
|
||||
|
||||
```toml
|
||||
[server]
|
||||
listen = "0.0.0.0:3000"
|
||||
listen = "0.0.0.0:8800"
|
||||
|
||||
[dns]
|
||||
listen = "0.0.0.0:53530"
|
||||
|
||||
[upstream]
|
||||
resolvers = [
|
||||
{ name = "cloudflare", url = "https://cloudflare-dns.com/dns-query" },
|
||||
{ name = "google", url = "https://dns.google/dns-query" },
|
||||
{ name = "quad9", url = "https://dns.quad9.net/dns-query" },
|
||||
]
|
||||
strategy = "round-robin" # or "failover"
|
||||
|
||||
[cache]
|
||||
enabled = true
|
||||
max_entries = 10000
|
||||
max_ttl_secs = 3600
|
||||
```
|
||||
|
||||
### Environment Variable Overrides
|
||||
|
||||
| Variable | Description | Example |
|
||||
|---|---|---|
|
||||
| `DOH_LISTEN` | Override server listen address | `0.0.0.0:8080` |
|
||||
| `DOH_LISTEN` | Override DoH server listen address | `0.0.0.0:8080` |
|
||||
| `DOH_UPSTREAM_STRATEGY` | Override upstream strategy | `failover` |
|
||||
| `DOH_UPSTREAM_RESOLVERS` | Comma-separated `name=url` pairs | `google=https://dns.google/dns-query,cf=https://cloudflare-dns.com/dns-query` |
|
||||
| `RUST_LOG` | Log level filter | `debug`, `doh_forwarder=trace` |
|
||||
|
||||
## API
|
||||
## Usage
|
||||
|
||||
### POST `/dns-query`
|
||||
|
||||
Send a raw DNS wire-format query in the request body.
|
||||
### Point your system DNS at the forwarder
|
||||
|
||||
```bash
|
||||
# Using a pre-built DNS query (hex-encoded)
|
||||
curl -X POST http://localhost:3000/dns-query \
|
||||
# /etc/resolv.conf
|
||||
nameserver 127.0.0.1
|
||||
# Then run the forwarder with [dns] listen = "127.0.0.1:53"
|
||||
```
|
||||
|
||||
Or use `resolvectl` with systemd-resolved:
|
||||
|
||||
```bash
|
||||
resolvectl dns eth0 127.0.0.1
|
||||
resolvectl dns-over-tls no # we handle encryption upstream
|
||||
```
|
||||
|
||||
### DoH API
|
||||
|
||||
**POST `/dns-query`** — raw DNS wire-format in body:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8800/dns-query \
|
||||
-H "Content-Type: application/dns-message" \
|
||||
-H "Accept: application/dns-message" \
|
||||
--data-binary @query.bin
|
||||
```
|
||||
|
||||
### GET `/dns-query`
|
||||
|
||||
Send a base64url-encoded DNS query as a query parameter.
|
||||
**GET `/dns-query`** — base64url-encoded query parameter:
|
||||
|
||||
```bash
|
||||
# Encode a DNS query and send via GET
|
||||
QUERY=$(python3 -c "
|
||||
import base64, struct
|
||||
# Minimal A record query for example.com
|
||||
q = b'\\x12\\x34' # ID
|
||||
q += b'\\x01\\x00' # flags
|
||||
q += b'\\x00\\x01' # 1 question
|
||||
q += b'\\x00\\x00' # 0 answers
|
||||
q += b'\\x00\\x00' # 0 authority
|
||||
q += b'\\x00\\x00' # 0 additional
|
||||
q += b'\\x07example\\x03com\\x00' # name
|
||||
q += b'\\x00\\x01' # type A
|
||||
q += b'\\x00\\x01' # class IN
|
||||
print(base64.urlsafe_b64encode(q).rstrip(b'=').decode())
|
||||
")
|
||||
curl "http://localhost:3000/dns-query?dns=$QUERY"
|
||||
curl "http://localhost:8800/dns-query?dns=<base64url-encoded-query>"
|
||||
```
|
||||
|
||||
### GET `/health`
|
||||
|
||||
Returns `ok` if the server is running.
|
||||
**GET `/health`** — returns `ok`:
|
||||
|
||||
```bash
|
||||
curl http://localhost:3000/health
|
||||
# ok
|
||||
curl http://localhost:8800/health
|
||||
```
|
||||
|
||||
## Upstream Strategies
|
||||
### Upstream Strategies
|
||||
|
||||
| Strategy | Behavior |
|
||||
|---|---|
|
||||
| `round-robin` | Distributes queries across resolvers in order |
|
||||
| `round-robin` | Distributes queries across resolvers in rotation |
|
||||
| `failover` | Tries resolvers in order; moves to the next on failure |
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
doh-forwarder/
|
||||
├── Cargo.toml
|
||||
├── config/
|
||||
│ └── default.toml # Default configuration
|
||||
├── docs/
|
||||
│ ├── plan.md # Project plan & milestones
|
||||
│ └── story.md # Why this project exists
|
||||
├── src/
|
||||
│ ├── main.rs # Entrypoint, server setup, graceful shutdown
|
||||
│ ├── lib.rs # Public API re-exports
|
||||
│ ├── config.rs # TOML config + env overrides
|
||||
│ ├── routes.rs # HTTP route handlers (/dns-query, /health)
|
||||
│ ├── dns/
|
||||
│ │ ├── mod.rs
|
||||
│ │ ├── query.rs # DNS query parsing
|
||||
│ │ ├── response.rs # DNS response building (SERVFAIL)
|
||||
│ │ └── listener.rs # UDP/TCP DNS listener
|
||||
│ └── upstream/
|
||||
│ ├── mod.rs
|
||||
│ └── doh_client.rs # DoH forwarding client (retry, strategies)
|
||||
├── tests/
|
||||
│ └── integration.rs # HTTP integration tests
|
||||
└── DEVELOP.md # Development rules & milestone tracking
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
# Prerequisites
|
||||
rustup show # Rust 1.80+
|
||||
See [DEVELOP.md](DEVELOP.md) for development rules, coding standards, and milestone tracking.
|
||||
|
||||
```bash
|
||||
# Run with auto-reload
|
||||
cargo install cargo-watch
|
||||
cargo watch -x run
|
||||
@@ -129,32 +150,6 @@ cargo clippy -- -D warnings
|
||||
cargo fmt --check
|
||||
```
|
||||
|
||||
See [DEVELOP.md](DEVELOP.md) for full development rules and milestone tracking.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
doh-forwarder/
|
||||
├── Cargo.toml
|
||||
├── config/
|
||||
│ └── default.toml # Default configuration
|
||||
├── src/
|
||||
│ ├── main.rs # Entrypoint, server setup
|
||||
│ ├── lib.rs # Public API re-exports
|
||||
│ ├── config.rs # TOML config + env overrides
|
||||
│ ├── cache.rs # DNS response cache (TTL + LRU)
|
||||
│ ├── dns/
|
||||
│ │ ├── mod.rs
|
||||
│ │ ├── query.rs # DNS query parsing
|
||||
│ │ └── response.rs # DNS response building
|
||||
│ ├── upstream/
|
||||
│ │ ├── mod.rs
|
||||
│ │ └── doh_client.rs # DoH forwarding client
|
||||
│ └── routes.rs # HTTP route handlers
|
||||
└── tests/
|
||||
└── integration.rs # Integration tests
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
||||
Reference in New Issue
Block a user