CDDNS : Cloudflare Dynamic DNS

cddns is a non-complicated, uncompromisingly green DDNS CLI and cloud-native service for Cloudflare built in Rust. Featuring layered configuration and interactive file builders.

⚠️ WARNING: This project is operational, but not yet considered production ready. See v1.0 tracking

Table of Contents

• CDDNS : Cloudflare Dynamic DNS
• Table of Contents
• 1 Installation
  • 1.1 Supported Platforms
  • 1.2 Requirements
  • 1.3 Local Installation
    • Option A: Cargo (Recommended)
    • Option B: Binary
  • 1.4 Docker
• 2 Quickstart
• 3 Usage
  • 3.1 Overview
    • 3.1.1 API Tokens
    • 3.1.2 Inventory
    • 3.1.3 Configuration (Optional)
    • 3.1.4 Environment Variables
  • 3.2 Subcommands
    • 3.2.1 Verify
    • 3.2.2 Config
      • 3.2.2.1 Show
      • 3.2.2.2 Build
    • 3.2.3 List
      • 3.2.3.1 Zones
      • 3.2.3.2 Records
    • 3.2.4 Inventory
      • 3.2.4.1 Build
      • 3.2.4.2 Show
      • 3.2.4.3 Check
      • 3.2.4.4 Update
      • 3.2.4.5 Prune
      • 3.2.4.6 Watch
  • 3.3 Service Deployment
    • 3.3.1 Docker
    • 3.3.2 Docker Compose
    • 3.3.3 Kubernetes
    • 3.3.4 Crontab
• 4 Purpose
• 5 License

1 Installation

1.1 Supported Platforms

• Command Line Utility
  • Native (Windows / MacOS / Unix)
• Service
  • Docker
  • Docker Compose
  • Kubernetes
  • Crontab

1.2 Requirements

• Cloudflare Account (Help)
• Cloudflare API Token with Edit DNS permissions (Help)

1.3 Local Installation

Installing the cddns CLI is a convenient way to test your configuration and build the necessary files for service deployment.

Option A: Cargo (Recommended)

Cargo is the recommended way to install CDDNS as a CLI (What is Cargo?).

• cargo +nightly install cddns

Option B: Binary

• Download a compatible binary release from releases

1.4 Docker

Any command in this document can be run or tested in a container with Docker.

docker run simbleau/cddns <SUBCOMMAND>

2 Quickstart

Docker users: Replace "cddns" with "docker run simbleau/cddns"

First, test your Cloudflare API token (Help) with the following command:

cddns --token <YOUR_CLOUDFLARE_TOKEN> verify

Next, generate an inventory file (Help) and save it:

Note: You can add --stdout to redirect the inventory file to the terminal

cddns \
  --token <YOUR_CLOUDFLARE_TOKEN> \
  inventory build

Check your inventory:

cddns \
  --token <YOUR_CLOUDFLARE_TOKEN> \
  inventory --path '/path/to/inventory.yml' \
  check

If the following works, continue to your OS-specific service instructions:

• Docker
• Docker Compose
• Kubernetes
• Crontab

3 Usage

3.1 Overview

cddns is a non-complicated DDNS tool for Cloudflare, only needing a Cloudflare API token and inventory file. cddns can be run in a container or installed locally as a CLI.

To operate, cddns needs an inventory file containing your DNS records (What is a DNS record?), which can be generated or written manually. For configuration, cddns takes the typical layered configuration approach: The config file is the base, which is superseded by environment variables, which are superseded by CLI arguments.

3.1.1 API Tokens

cddns will need a valid Cloudflare API token to function (How do I create an API token?).

You can test an API token with the following command:

cddns verify --token <YOUR_CLOUDFLARE_TOKEN>.

On success, you may see "This API Token is valid and active"

To avoid using --token in every command, you can save a configuration file or set the CDDNS_VERIFY_TOKEN environment variable to manually specify your token. Click here for more environment variables.

3.1.2 Inventory

cddns also needs an inventory file in YAML format containing the DNS records you want to watch.

By default, we check your local configuration directory for your inventory file.

• On Linux, this would be $XDG_CONFIG_HOME/cddns/inventory.yml or $HOME/.config/cddns/inventory.yml
• On MacOS, this would be $HOME/Library/Application Support/cddns/inventory.yml
• On Windows, this would be %AppData%\cddns\inventory.yml

To quickly get setup, the CLI offers an interactive inventory file builder.

cddns inventory build

• Zones are domains, subdomains, and identities managed by Cloudflare.
• Records are A (IPv4) or AAAA (IPv6) DNS records managed by Cloudflare.

To see DNS records managed by your API token, the CLI also offers a list command.

cddns list [records/zones]

You can visit inventory.yml for an annotated example.

You can set the CDDNS_INVENTORY_PATH environment variable to manually specify the location of this file. Click here for more environment variables.

3.1.3 Configuration (Optional)

You may optionally use a TOML file to save configuration, such as your API key. You should restrict the permissions on this file if storing your API token.

By default, we check your local configuration directory for your configuration file.

• On Linux, this would be $XDG_CONFIG_HOME/cddns/config.toml or $HOME/.config/cddns/config.toml
• On MacOS, this would be $HOME/Library/Application Support/cddns/config.toml
• On Windows, this would be %AppData%\cddns\config.toml

To quickly get setup, the CLI offers an interactive configuration file builder.

cddns config build

You can also visit config.toml for an annotated example.

You can set the CDDNS_CONFIG environment variable to manually specify the location of this file. Click here for more environment variables.

3.1.4 Environment Variables

Every value which can be stored in a configuration file can be superseded or provided as an environment variable.

3.2 Subcommands

Appending --help or -h to any command or subcommand will provide additional information.

The CLI is useful for testing and building files for your service deployment. Below is a reference of all commands in the CLI.

Reminder: you may add -h or --help to any subcommand to receive helpful usage information.

3.2.1 Verify

Help: cddns verify --help

The verify command will validate your Cloudflare API token.

cddns verify [--token '<YOUR_CLOUDFLARE_TOKEN>']

If you do not provide --token ..., the token will be obtained from your configuration file or the CDDNS_VERIFY_TOKEN environment variable.

3.2.2 Config

Help: cddns config --help

The config command will help you build or manage your configuration (Help). cddns takes the typical layered configuration approach; there are 3 layers. The config file is the base, which is superseded by environment variables, which are superseded by CLI arguments.

By default, cddns checks your local configuration folder for saved configuration.

3.2.2.1 Show

To show your current configuration:

-c or --config will show the inventory at the given path

cddns config show

3.2.2.2 Build

To build a configuration file:

cddns config build

3.2.3 List

Help: cddns list --help

The list command will print Cloudflare resources visible with your API token.

• Zones are domains, subdomains, and identities managed by Cloudflare.
• Records are A (IPv4) or AAAA (IPv6) DNS records managed by Cloudflare.

To list your zones AND records:

-include-zones <pattern1,pattern2,..> will include only zones matching one of the given regex patterns -ignore-zones <pattern1,pattern2,..> will ignore zones matching one of the given regex patterns -include-records <pattern1,pattern2,..> will include only records matching one of the given regex patterns -ignore-records <pattern1,pattern2,..> will ignore records matching one of the given regex patterns

cddns list

3.2.3.1 Zones

To list only zones:

-z or --zone will only show the zone matching the given name or id.

cddns list zones

3.2.3.2 Records

To list only records:

-z or --zone will only show the records matching the given zone's name or id. -r or --record will only show the records matching the given name or id.

cddns list records

3.2.4 Inventory

Help: cddns inventory --help

The inventory command has several subcommands to build and control inventory.

-p or --path will show the inventory at the given path

3.2.4.1 Build

To build an inventory:

--stdout will output the inventory to stdout
--clean will output without post-processing

cddns inventory build

3.2.4.2 Show

To show your inventory:

--clean will output without post-processing

cddns inventory show

3.2.4.3 Check

To check your DNS records, without making any changes:

cddns inventory check

3.2.4.4 Update

To update all outdated DNS records found in inventory check:

--force-update true will attempt to skip prompts

cddns inventory update

3.2.4.5 Prune

To prune all invalid DNS records found in inventory check:

--force-prune true will attempt to skip prompts

cddns inventory prune

3.2.4.6 Watch

To continuously update erroneous records:

-w or --watch-interval will change the milliseconds between DNS refresh

cddns inventory watch

3.3 Service Deployment

cddns will work as a service daemon to keep DNS records up to date. The default check interval is every 30 seconds.

3.3.1 Docker

Currently supported architectures: amd64, arm64

Running cddns on Docker is an easy 3 step process.

1. Test your Cloudflare API token: (Help)

export CDDNS_VERIFY_TOKEN='...'

docker run  \
  -e CDDNS_VERIFY_TOKEN \
  simbleau/cddns:latest verify

1. Test your inventory (Help).

export CDDNS_INVENTORY_PATH='/to/your/inventory.yml'

docker run \
  -e CDDNS_VERIFY_TOKEN \
  -e CDDNS_INVENTORY_PATH='/inventory.yml' \
  -v $CDDNS_INVENTORY_PATH:'/inventory.yml' \
  simbleau/cddns:latest inventory check

1. Deploy

All environment variables can be used for additional configuration.

docker run \
  -e CDDNS_VERIFY_TOKEN \
  -e CDDNS_INVENTORY_PATH='/inventory.yml' \
  -v $CDDNS_INVENTORY_PATH:/inventory.yml \
  simbleau/cddns:latest

3.3.2 Docker Compose

1. Validate your configuration with the Docker instructions (above)

2. Deploy Compose file[?]

All environment variables can be used for additional configuration.

# docker-compose.yaml
version: '3.3'
services:
    cddns:
        environment:
            - CDDNS_VERIFY_TOKEN
            - CDDNS_INVENTORY_PATH='/inventory.yml'
        volumes:
            - /host/path/to/inventory.yml:/inventory.yml
        image: 'simbleau/cddns:latest'

docker compose up

3.3.3 Kubernetes

We will eventually support standard installation techniques such as Helm. You may try a custom setup or you may follow our imperative steps with the help of the cddns CLI:

1. Create a Secret[?] for your API token:

kubectl create secret generic cddns-api-token \
  --from-literal=token='YOUR_CLOUDFLARE_API_TOKEN'

2. Create a ConfigMap[?] for your inventory:

kubectl create configmap cddns-inventory \
  --from-file '/to/your/inventory.yml'

3. Create a Deployment[?]:

All environment variables can be used for additional configuration.

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: cddns-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: cddns
  template:
    metadata:
      labels:
        app: cddns
    spec:
      volumes: # Expose inventory as volume
        - name: "inventory"
          configMap:
            name: "cddns-inventory"
      containers:
      - name: cddns
        image: simbleau/cddns:latest
        volumeMounts:
        - name: inventory # Mount inventory file
            mountPath: /opt/bin/cddns/
            readOnly: true
        env:
        - name: CDDNS_INVENTORY_PATH
          value: /opt/bin/cddns/inventory.yml
        - name: CDDNS_VERIFY_TOKEN
            valueFrom: # Cloudflare API token
              secretKeyRef:
                  name: cddns-api-token
                  key: token

1. Deploy:

kubectl apply -f deployment.yaml

3.3.4 Crontab

1. Test your Cloudflare API token: (Help)

cddns verify

1. Test your inventory (Help).

cddns inventory show

1. Launch crontab editor

sudo crontab -e

1. Add crontab entry (e.g. every 10 minutes)

*/10 * * * * "cfddns inventory --force-update true update"

4 Purpose

cddns allows experts and home users to keep services available without a static IP address. CDDNS will support low-end hardware and is uncompromisingly green, helping you minimize costs and maximize hardware.

5 License

This project is dual-licensed under both Apache 2.0 and MIT licenses.