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
Installing the cddns CLI is a convenient way to test your configuration and build the necessary files for service deployment.
Cargo is the recommended way to install CDDNS as a CLI (What is Cargo?).
- cargo +nightly install cddns
Any command in this document can be run or tested in a container with Docker.
bash
docker run simbleau/cddns <SUBCOMMAND>
Docker users: Replace "cddns" with "docker run simbleau/cddns"
First, test your Cloudflare API token (Help) with the following command:
bash
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
bash
cddns \
--token <YOUR_CLOUDFLARE_TOKEN> \
inventory build
Check your inventory:
bash
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
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.
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 CDDNSVERIFYTOKEN environment variable to manually specify your token. Click here for more environment variables.
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
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 CDDNSINVENTORYPATH environment variable to manually specify the location of this file. Click here for more environment variables.
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.
Every value which can be stored in a configuration file can be superseded or provided as an environment variable.
| Variable Name | Description | Default | Example |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- | ------------------------ |
| RUSTLOG | Log filtering directives | info,cddns=trace | debug |
| CDDNSCONFIG | The path to your configuration file | Varies by OS | /etc/cddns/config.toml |
| CDDNSVERIFYTOKEN | The default Cloudflare API Token to use | None | GAWnixPCAADXRAjoK... |
| CDDNSLISTINCLUDEZONES | Regex filters for zones to include in CLI usage | .* (Match all) | imbleau.com,.*\.dev |
| CDDNSLISTIGNOREZONES | Regex filters for zones to ignore in CLI usage | None | imbleau.com |
| CDDNSLISTINCLUDERECORDS | Regex filters for records to include in CLI usage | .* (Match all) | .*\.imbleau.com |
| CDDNSLISTIGNORERECORDS | Regex filters for records to ignore in CLI usage | None | shop\..+\.com |
| CDDNSINVENTORYPATH | The path to your inventory file | Varies by OS | MyInventory.yml |
| CDDNSINVENTORYFORCEUPDATE | Skip all prompts (force) for inventory update | false | true |
| CDDNSINVENTORYFORCEPRUNE | Skip all prompts (force) for inventory prune | false | true |
| CDDNSINVENTORYWATCH_INTERVAL | The milliseconds between checking DNS records | 30000 (30s) | 60000 (60s) |
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.
Help: cddns verify --help
The verify command will validate your Cloudflare API token.
bash
cddns verify [--token '<YOUR_CLOUDFLARE_TOKEN>']
If you do not provide --token ..., the token will be obtained from your configuration file or the CDDNSVERIFYTOKEN environment variable.
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.
To show your current configuration:
-c or --config will show the inventory at the given path
bash
cddns config show
To build a configuration file:
bash
cddns config build
Help: cddns list --help
The list command will print Cloudflare resources visible with your API token.
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
bash
cddns list
To list only zones:
-z or --zone will only show the zone matching the given name or id.
bash
cddns list zones
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.
bash
cddns list records
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
To build an inventory:
--stdout will output the inventory to stdout\
--clean will output without post-processing
bash
cddns inventory build
To show your inventory:
--clean will output without post-processing
bash
cddns inventory show
To check your DNS records, without making any changes:
bash
cddns inventory check
To update all outdated DNS records found in inventory check:
--force-update true will attempt to skip prompts
bash
cddns inventory update
To prune all invalid DNS records found in inventory check:
--force-prune true will attempt to skip prompts
bash
cddns inventory prune
To continuously update erroneous records:
-w or --watch-interval will change the milliseconds between DNS refresh
bash
cddns inventory watch
cddns will work as a service daemon to keep DNS records up to date. The default check interval is every 30 seconds.
Currently supported architectures: amd64, arm64
Running cddns on Docker is an easy 3 step process.
Test your Cloudflare API token: (Help)
bash
export CDDNS_VERIFY_TOKEN='...'
bash
docker run \
-e CDDNS_VERIFY_TOKEN \
simbleau/cddns:latest verify
Test your inventory (Help).
bash
export CDDNS_INVENTORY_PATH='/to/your/inventory.yml'
bash
docker run \
-e CDDNS_VERIFY_TOKEN \
-e CDDNS_INVENTORY_PATH='/inventory.yml' \
-v $CDDNS_INVENTORY_PATH:'/inventory.yml' \
simbleau/cddns:latest inventory check
Deploy
All environment variables can be used for additional configuration.
bash
docker run \
-e CDDNS_VERIFY_TOKEN \
-e CDDNS_INVENTORY_PATH='/inventory.yml' \
-v $CDDNS_INVENTORY_PATH:/inventory.yml \
simbleau/cddns:latest
Validate your configuration with the Docker instructions (above)
Deploy Compose file[[?](https://docs.docker.com/compose/compose-file/)]
All environment variables can be used for additional configuration. ```yaml
version: '3.3'
services:
cddns:
environment:
- CDDNSVERIFYTOKEN
- CDDNSINVENTORYPATH='/inventory.yml'
volumes:
- /host/path/to/inventory.yml:/inventory.yml
image: 'simbleau/cddns:latest'
bash
docker compose up
```
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:
Create a Secret[?] for your API token:
kubectl create secret generic cddns-api-token \
--from-literal=token='YOUR_CLOUDFLARE_API_TOKEN'
Create a ConfigMap[?] for your inventory:
kubectl create configmap cddns-inventory \
--from-file '/to/your/inventory.yml'
Create a Deployment[?]:
All environment variables can be used for additional configuration. ```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: CDDNSINVENTORYPATH value: /opt/bin/cddns/inventory.yml - name: CDDNSVERIFYTOKEN valueFrom: # Cloudflare API token secretKeyRef: name: cddns-api-token key: token ```
Deploy:
kubectl apply -f deployment.yaml
Test your Cloudflare API token: (Help)
bash
cddns verify
Test your inventory (Help).
bash
cddns inventory show
Launch crontab editor
bash
sudo crontab -e
Add crontab entry (e.g. every 10 minutes)
*/10 * * * * "cfddns inventory --force-update true update"
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.
This project is dual-licensed under both Apache 2.0 and MIT licenses.