UpDNS

A lightweight Go DynDNS‑proxy service that accepts authenticated update requests and forwards them to an upstream DDNS provider (e.g. Hetzner Cloud DNS). Fully pluggable so you can add new providers in future.

Features

• HTTP API for dynamic DNS updates
• Per‑host API key (“secret”) authentication
• Client‑to‑domain mapping in a single YAML/JSON/TOML config
• Support for exact hostnames and wildcard domains (all subdomains)
• Configurable upstream DDNS (default: Hetzner Cloud DNS)
• Extensible provider interface for other DNS services
• Optional TLS support
• Logging & metrics

Quick Start

1. Install

   go install git.cloonar.com/cloonar/updns@latest
   

2. Create a config file (config.yaml):

   server:
     bind_address: ":8080"
     tls:
       enabled: false
       cert_file: "/path/to/cert.pem"
       key_file: "/path/to/key.pem"
   
   upstream:
     provider: hetzner
     hetzner:
       api_token: "YOUR_HETZNER_API_TOKEN"
   
   clients:
     client1:
       secret: "s3cr3t123"
       # Allow updates only to exactly these hostnames:
       exact:
         - "home.example.com"
         - "sub.example.org"
       # Allow updates to this domain and all its subdomains:
       wildcard:
         - "example.net"
   
     client2:
       secret: "otherSecret"
       # Allow both an exact record and entire subdomain tree:
       exact:
         - "app.acme.io"
       wildcard:
         - "acme.io"
   

3. Run the proxy

   updns --config config.yaml
   

4. Update DNS

   curl -X POST https://<your-host>/update \
     -H "Content-Type: application/json" \
     -d '{
       "key": "client1",
       "secret": "s3cr3t123",
       "host": "api.example.net",
       "ip": "203.0.113.42"
     }'
   

   Since client1 has wildcard: ["example.net"], api.example.net is permitted.
   Success returns:

   { "status": "ok", "message": "Record updated" }
   

Configuration

• server.bind_address – host:port to bind (default :8080)
• server.tls.enabled – enable HTTPS
• upstream.provider – one of hetzner (future: cloudflare, aws, etc)
• upstream. – provider‑specific credentials
• clients – mapping client IDs to:
  • secret – HMAC/API key for authentication
  • exact – list of fully qualified hostnames the client may update
  • wildcard – list of base domains; any subdomain (including the base) is permitted

Note:

• An exact entry like home.example.com allows only that specific record.
• A wildcard entry like example.com allows updates to example.com, www.example.com, foo.bar.example.com, etc.

HTTP API

POST /update

Field	Type	Required	Description
key	string	yes	Client identifier
secret	string	yes	Client’s secret for authentication
host	string	yes	Hostname to update (must match exact or fall under a wildcard)
ip	string	no	IPv4 or IPv6; defaults to caller’s IP

Response

• 200 OK on success:

  { "status": "ok", "message": "Record updated" }
  

• 4xx/5xx on error:

  { "status": "error", "message": "Invalid secret or unauthorized host" }
  

Extending Providers

1. Implement the Provider interface:

   type Provider interface {
     UpdateRecord(ctx context.Context, domain, ip string) error
   }
   

2. Wire it up in cmd/updns/main.go’s provider factory.
3. Add config fields under upstream.<newprovider>.

Contributing

1. Fork & clone this repo
2. go mod tidy
3. Write code, tests & update docs
4. Submit a PR

License

MIT © 2025 Cloonar Technologies GmbH