DDNS Updater

A lightweight dynamic DNS updater for Cloudflare written in Go. Automatically detects your public IP changes and updates specified DNS A records.

Features

• Automatic public IP detection with fallback services
• Multiple subdomain support
• Cloudflare API v4 integration
• Configurable check intervals
• Retry logic with exponential backoff
• Structured JSON logging
• Graceful shutdown handling
• Cross-platform (Linux, macOS)

Building and running

1. Generate config

go run main.go -init-config > config.yaml
# edit config.yaml with your Cloudflare token, zone_id, zone_name, and subdomains

Key fields:

cloudflare:
  api_token: "your-token"
  zone_id: "your-zone-id"
  zone_name: "example.com"
  subdomains:
    - name: "lc"
      proxied: false
logging:
  file: "/config/logs/ddns-updater.log"

2. Local binary (Linux/macOS)

make build
./bin/ddns-updater -config config.yaml

---

Production: Linux (systemd)

1. Install:

sudo make install
sudo mkdir -p /etc/ddns-updater
sudo cp config.yaml /etc/ddns-updater/config.yaml
sudo chmod 600 /etc/ddns-updater/config.yaml

2. Create /etc/systemd/system/ddns-updater.service:

[Unit]
Description=DDNS Updater
After=network-online.target

[Service]
ExecStart=/usr/local/bin/ddns-updater -config /etc/ddns-updater/config.yaml
Restart=always
RestartSec=10
User=root

[Install]
WantedBy=multi-user.target

3. Enable:

sudo systemctl daemon-reload
sudo systemctl enable --now ddns-updater
sudo systemctl status ddns-updater

---

Production: macOS (launchd)

1. Install:

sudo make install
sudo mkdir -p /usr/local/etc /usr/local/var/log
sudo cp config.yaml /usr/local/etc/ddns-updater.yaml
sudo chmod 600 /usr/local/etc/ddns-updater.yaml

2. Create ~/Library/LaunchAgents/com.ddns-updater.plist pointing at:

<array>
  <string>/usr/local/bin/ddns-updater</string>
  <string>-config</string>
  <string>/usr/local/etc/ddns-updater.yaml</string>
</array>

3. Load:

launchctl load ~/Library/LaunchAgents/com.ddns-updater.plist
launchctl start com.ddns-updater

---

Docker usage

1. Prepare appdata on host (e.g. Unraid)

mkdir -p /mnt/user/appdata/ddns-updater/logs
cp config.yaml /mnt/user/appdata/ddns-updater/config.yaml
chmod -R 775 /mnt/user/appdata/ddns-updater

Ensure logging.file in /mnt/user/appdata/ddns-updater/config.yaml is:

logging:
  file: "/config/logs/ddns-updater.log"

2. Dockerfile (multi-stage)

Already in repo, using /config/config.yaml inside the container and writing logs to /config/logs.

3. Run with docker

docker run -d \
  --name ddns-updater \
  --restart unless-stopped \
  -v /mnt/user/appdata/ddns-updater:/config \
  kccleoc/ddns-updater:latest

4. Docker Compose (Unraid 7 friendly)

services:
  ddns-updater:
    image: kccleoc/ddns-updater:latest
    container_name: ddns-updater
    restart: unless-stopped
    user: "0:0"
    volumes:
      - /mnt/user/appdata/ddns-updater:/config

Bring it up from the Compose UI (or CLI):

docker compose up -d

Makefile (Docker image build)

Usage examples:

make build-dockerimg IMAGE=kccleoc/ddns-updater:latest
make push-dockerimg IMAGE=kccleoc/ddns-updater:latest