Networking Ddns

Dynamic DNS (DDNS) — Direct-to-Home Networking

How home.alienzj.org stays pointed at a dynamic residential IP using Cloudflare DDNS, and why you might (or might not) want to bypass the VPS.

Concepts

IP Types

This home network has dynamic public IPs — a pool of real public addresses rotated by the ISP. Single NAT layer (the router at 192.168.31.1). Not CGNAT.

How ISPs Assign IPs

ISP edge router
  ├── Pool: 203.0.113.0/24, 198.51.100.0/24, ...
  │     ├── id3-eniac  gets 203.0.113.1 (today)
  │     └── lab-matrix gets 198.51.100.1  (today)
  │     └── (tomorrow: both may rotate to different IPs)
  └── Router (192.168.31.1) — single NAT, not CGNAT

Two Paths to Home

Path A: Via VPS (current default)

Internet → vps-pacman (static IP, nginx) → Tailscale → lab-matrix (100.88.42.65)
                                              ↑ encrypted overlay

Path B: Direct-to-Home (DDNS)

Internet → home.alienzj.org (dynamic IP, Cloudflare DDNS) → router → host
              ↑ updated every 5min by cloudflare-ddns service

Path C: Hybrid (best of both)

home.alienzj.org  → DDNS → home IP (direct, low latency)
*.alienzj.org     → VPS   → Tailscale → lab-matrix (existing infra)

Direct-to-home for latency-sensitive services; VPS for everything else.

Module: modules/services/net/ddns.nix

Options

modules.services.net.ddns = {
  enable = true;                    # toggle the DDNS updater
  domain = "home.alienzj.org";      # DNS record to update
  ip4Provider = "cloudflare.trace"; # IP detection method
  ip6Provider = "none";             # IPv6 disabled (no home IPv6)
  updateCron = "@every 5m";         # update frequency
  proxied = false;                  # Cloudflare proxy (orange cloud)
};

How it works

1. cloudflare-ddns service starts at boot (after network-online.target)
2. Reads CLOUDFLARE_API_TOKEN from agenix secret (/run/agenix/cloudflare-api-token)
3. Detects public IP via cloudflare.trace (Cloudflare’s /cdn-cgi/trace endpoint)
4. Updates the home.alienzj.org A record via Cloudflare API
5. Repeats every 5 minutes (configurable via UPDATE_CRON)

Per-host enablement

DDNS should only be enabled on the host that owns home.alienzj.org:

# hosts/id3-eniac/modules/modules.nix
modules.services.net.ddns.enable = true;

Prerequisites

1. Cloudflare API token with Zone.DNS.Edit permission (already exists for ACME)
2. DNS record home.alienzj.org must exist in Cloudflare (even as a dummy)
3. Port forwarding on the router if serving traffic:
   • TCP 443 → host IP (nginx/https)
   • TCP 80 → host IP (ACME HTTP-01, optional)

IP Detection Methods

cloudflare-ddns supports multiple detection providers, configured via ip4Provider:

Default is cloudflare.trace — simple, reliable, and Cloudflare already handles your DNS API calls.

Port Forwarding

For direct-to-home HTTP/HTTPS, configure the router to forward:

WAN:443 → 192.168.31.11:443   (id3-eniac nginx)
WAN:80  → 192.168.31.11:80    (ACME HTTP-01, if not using DNS-01)

Without port forwarding, home.alienzj.org resolves correctly but connections are refused at the router. The DNS update still works — it just doesn’t serve traffic.

Security Considerations

Cloudflare Proxy vs DNS-only

Proxied mode adds a Cloudflare hop but hides your home IP from casual observers. DNS-only gives lower latency since clients connect directly.

Latency Comparison

VPS path:   Client → VPS (10ms) → Tailscale (5ms) → homelab = ~15ms extra
DDNS path:  Client → home IP (0ms extra)                    = direct

For local access (same city/ISP), the difference is negligible. For international clients, DDNS can save 10-30ms by skipping the VPS hop.

Related Modules

Related Docs

• Networking & VPN — Tailscale, Headscale, MagicDNS
• Networking & Proxy — Sing-box, SSH tunnels
• Web Services — Nginx, ACME
• SSH Architecture — SSH config layers, agent