zedmanny/dhcpd-dns-wg

•Updated 4 months ago

Image

1.8K

zedmanny/dhcpd-dns-wg repository overview

⁠dhcpd-dns-wg

A DHCP + DNS + WireGuard appliance with a web UI. Multi-interface ISC dhcpd (one DHCP scope per VLAN), a dnsmasq DNS server (recursive + local/forward zones), and an outbound WireGuard tunnel — optionally routing all DNS through the tunnel. Runs anywhere containers do (Linux host, VM, EVE-OS).

Image: zedmanny/dhcpd-dns-wg:latest (multi-arch: amd64 + arm64)

⁠What it does

DHCP to one or more VLANs — one scope per interface.
DNS — recursive resolution via upstreams + your own authoritative/forward zones.
WireGuard — connect an outbound tunnel from cloud-init or the UI; optionally send all DNS resolution through it.
Web UI on port 8080 — configure everything; live DHCP / DNS / WireGuard topology.

Ports: DHCP 67/udp, DNS 53, WireGuard 51820/udp, web UI 8080/tcp. State persists in /data.

⁠Web UI

Tab	Purpose
Global / Subnets	DHCP scopes (broadcast auto-fills from netmask)
Reservations	static host → MAC → IP
Leases	active DHCP leases
Topology	container → interfaces → VLAN clouds → leased devices
DNS	recursive upstreams + zones (authoritative / conditional forward)
DNS Topology	this box as DNS server → clouds → upstream DNS servers
WireGuard	tunnel config + connect/disconnect + live status
WG Topology	this box → tunnel (up/down) → peer endpoint
dhcpd.conf	rendered DHCP config

⁠Interfaces & routing

The container distinguishes its uplink from the networks it serves:

WAN / uplink (optional but recommended with WireGuard) — owns the container's default route and is the WireGuard underlay (path to the tunnel endpoint):
Var Notes
WAN_IFACE uplink NIC (e.g. eth0)
WAN_DHCP true → get an address + default route via DHCP
WAN_IP / WAN_GW static alternative to DHCP
DHCP-serving NICs (NET1_*, NET2_*, … 1–8) — one VLAN/scope per NIC: NET{i}_IFACE, NET{i}_IP (with prefix), NET{i}_RANGE_START/END, NET{i}_GATEWAY, NET{i}_DNS, NET{i}_NTP, NET{i}_DOMAIN.

Var	Notes
`WAN_IFACE`	uplink NIC (e.g. `eth0`)
`WAN_DHCP`	`true` → get an address + default route via DHCP
`WAN_IP` / `WAN_GW`	static alternative to DHCP

NET{i}_GATEWAY is the gateway handed to that VLAN's DHCP clients — it does not route the container itself when a WAN is configured. The WAN owns the default route, so tunnel/DNS egress is deterministic (not a random served-VLAN gateway). Without a WAN, the last NET{i}_GATEWAY becomes the default route.

Single interface (legacy): STATIC_IP, STATIC_GW, STATIC_IFACE. Global DHCP options: DHCP_FORCE_SEED, DHCP_LEASE_DEFAULT/MAX.

⁠DNS configuration

Default (recursive) zone — upstreams in DNS_RECURSIVE (CSV, default 1.1.1.1,8.8.8.8) or the DNS tab.
Authoritative / forward zones — created in the UI, persisted in /data/dns.json.

⁠WireGuard configuration

Connect on boot via cloud-init WG_* env, or from the WireGuard tab.

Var	Notes
`WG_ENABLED`	`true` to connect on boot
`WG_PRIVATE_KEY`	this end's private key (base64)
`WG_ADDRESS`	this end's tunnel address, CIDR (e.g. `10.7.0.2/32`)
`WG_PEER_PUBLIC_KEY`	server/peer public key
`WG_ENDPOINT`	`host:port`
`WG_ALLOWED_IPS`	CSV, default `0.0.0.0/0`
`WG_KEEPALIVE`	persistent keepalive seconds (default 25)
`WG_PRESHARED_KEY`	optional
`WG_ROUTE_DNS`	`true` (default) → route the DNS upstreams through the tunnel

Route all DNS through the tunnel: with WG_ROUTE_DNS=true, the DNS recursive upstreams are added to AllowedIPs and routed via wg0, so all DNS resolution is tunneled. Config persists in /data/wireguard.json.

Requirements: the container needs NET_ADMIN and a kernel with the wireguard module (standard on modern kernels / EVE). Without it, wg0 creation fails with a clear error and the rest (DHCP/DNS) keeps working.

⁠Web UI auth

USER_NAME + USER_PASS (SHA-256 hex hash), or WEBUI_USER/WEBUI_PASSWORD (plaintext). Hash: printf '%s' 'pw' | openssl dgst -sha256 | awk '{print $NF}'.

⁠Example — two VLANs + tunnel (Docker)

docker run -d --name dhcpd-dns-wg --network host \
  --cap-add NET_ADMIN --cap-add NET_RAW -v dhcpd-dns-wg-data:/data \
  -e NET1_IFACE=eth0 -e NET1_IP=192.168.254.100/24 \
  -e NET1_RANGE_START=192.168.254.150 -e NET1_RANGE_END=192.168.254.200 \
  -e NET1_GATEWAY=192.168.254.1 -e NET1_DNS=192.168.254.100 \
  -e DNS_RECURSIVE=1.1.1.1,1.0.0.1 \
  -e WG_ENABLED=true -e WG_PRIVATE_KEY=... -e WG_ADDRESS=10.7.0.2/32 \
  -e WG_PEER_PUBLIC_KEY=... -e WG_ENDPOINT=vpn.example.com:51820 \
  -e WG_ALLOWED_IPS=0.0.0.0/0 -e WG_ROUTE_DNS=true \
  zedmanny/dhcpd-dns-wg:latest

⁠API

Method	Path	Purpose
GET/PUT	`/api/config`	DHCP config
PUT	`/api/reservations`	reservations
GET	`/api/leases` · `/api/topology`	leases · DHCP topology
GET/PUT	`/api/dns`	DNS config
GET	`/api/dns/topology`	DNS topology
GET/PUT	`/api/wireguard`	WireGuard config (PUT connects/disconnects per `enabled`)
GET	`/api/wireguard/status`	tunnel status (`wg show`)
POST	`/api/wireguard/up` · `/api/wireguard/down`	connect · disconnect
GET	`/api/docs`	OpenAPI / Swagger UI

Tag summary

Recent tags

Content type

Image

Digest

sha256:96b0d8fb5…

Size

77.5 MB

Last updated

4 months ago

docker pull zedmanny/dhcpd-dns-wg