ddflare is a DDNS (Dynamic DNS) library that allows DNS record updates via either the Cloudflare API or the DynDNS update prococol v3.
It comes with a CLI tool built on top of the library and released for different architectures.

Note

The DynDNS update prococol v3 is an HTTP API introduced back in the day by dyndns.org (now Dyn, part of Oracle) which is used by many of the available DDNS service providers available nowadays.

Tip

In order to update your DNS records with ddflare you need a DNS domain registered with Cloudflare or a registratrion to a Dynamic DNS service provider (e.g., No-IP, Dyn, ...).

ddflare allows to:

• update a target domain name (FQDN, recorded as a type A record) to point to the current public address or a custom IP
• retrieve and display the current public IP address
• resolve any domain name (acting as a simple DNS client)

Quickstart CLI

Get ddflare

ddflare CLI is released as statically compiled binaries for different OS/architetures that you can grab from the release page.

Get a x86_64 linux binary example:

wget https://github.com/fgiudici/ddflare/releases/download/v0.4.0/ddflare-linux-amd64
sudo install ddflare-linux-amd64 /usr/local/bin/ddflare

Container images are availble as well on the github repository. Run ddflare via docker with:

docker run -ti --rm ghcr.io/fgiudici/ddflare:0.4.0

Available commands

ddflare has two main commands:

• set - to update the type A record of the target FQDN to the current public ip (or a custom IP address)
• get - to retrieve the current public IP address (or resolve the FQDN passed as argument)

Run ddflare help to display all the available commands and options.

Update domain name via DDNS services

Note

You should register to a DDNS service first, configure the desired FQDN there and retrieve the username and password required to authenticate to the service.

To update a domain name (FQDN, type A record) to the current public IP address of the host run:

ddflare set -s <DDNS_URL> -t <AUTH_TOKEN> <FQDN>

where <DDNS_URL> is the http endpoint of the DDNS service, <FQDN> is the domain to be updated and <AUTH_TOKEN> is the API authentication token.

Example:

DDNS provider	No-IP
FQDN to update	myhost.ddns.net
user	68816xj
password	v4UMHzugodpE

ddflare set -s noip -t 68816xj:v4UMHzugodpE  myhost.ddns.net

Update domain name via Cloudflare

To update a domain name (FQDN, type A record) to the current public IP address of the host run:

ddflare set -t <CLOUDFLARE_TOKEN> <FQDN>

where <FQDN> is the domain to be updated and <CLOUDFLARE_TOKEN> is the Cloudflare API token.

Tip

You should get a Cloudflare API token with Zone.DNS Edit permission. You can create one following the Cloudflare docs.

Example:

FQDN to update	myhost.example.com
API token	gB1fOLbl2d5XynhfIOJvzX8Y4rZnU5RLPW1hg7cM

ddflare set -t gB1fOLbl2d5XynhfIOJvzX8Y4rZnU5RLPW1hg7cM  myhost.example.com

Note

ddflare can update existing type A DNS records but cannot create new ones yet, so the record should be created in advance.

To create a type A record see Cloudflare's Manage DNS Records docs.

Tip

When creating a type A DNS record pay attention to the value of the TTL field: it tracks the number of seconds DNS clients and DNS resolvers are allowed to cache the resolved IP address. You may want to keep the TTL low (the allowed minimum is 60 secs) if you plan to use the record to track the (dynamic) IP address of a host in a DDNS scenario.

Get the current public IP address

Retrieving the current public IP address is as easy as running:

ddflare get

ddflare queries the ipify.org service under the hood, which detects the public IP address used to reach the service.

Quickstart Library

The ddflare go library allows updates of DNS type A records with the actual Public IP address in 4 steps:

1. create a new DNSManager (NewDNSManager())
2. initialize the DNSManager with the authentication credentials (.Init())
3. retrieve the current public IP address (GetPublicIP())
4. update the DNS record via the DNSManager (.UpdateFQDN)

Example:

import "github.com/fgiudici/ddflare"

func main() {
  // fqdn to be updated
  fqdn := "www.myddns.host"
  // auth Token from the DDNS service if available or contatenation of user:password
  authToken := "user:password"

  // create a new DNSManager targeting the desired service (ddflare.Cloudflare,
  // ddflare.NoIP or ddflare.DDNS). For a DDNS provider using the DynDNS API v3
  // but not in the list, pick ddflare.DDNS and set a custom API endpoint with
  // dm.SetAPIEndpoint("$HTTP_ENDPOINT")
  dm, err := ddflare.NewDNSManager(ddflare.NoIP)
  if err != nil {
    log.Fatal(err)
  }

  // init the DNSManager with the API credentials
  if err = dm.Init(authToken); err != nil {
    log.Fatal(err)
  }

  // retrieve the current Public IP address
  pubIP, err := ddflare.GetPublicIP()
  if err != nil {
    log.Fatal(err)
  }
  // set the Public IP address just retrieved as the addres of `fqdn`
  if err = dm.UpdateFQDN(fqdn, pubIP); err != nil {
    log.Fatal("update failed")
  }

  log.Info("update successful")
}