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 not considered ready for production use. See v1.0 tracking*
Installing the cddns CLI will provide the means to test your configuration locally and run interactive builders on your local machine.
Cargo is the recommended way to install CDDNS as a CLI (What is Cargo?).
- cargo install cddns
cddns is the non-complicated DDNS tool for Cloudflare, only needing a Cloudflare API token to see and edit your DNS records. cddns can be deployed as a service or installed locally as a CLI, which is helpful in testing and building DNS inventory files.
To operate, cddns needs an inventory file, which can be built on CLI (recommended) or written manually. For configuration, cddns takes the typical layered configuration approach. There are 3 layers. The config file is the base, which is then superseded by environment variables, which are finally superseded by CLI arguments and options.
Appending --help or -h to any command or subcommand will provide additional information.
First, test your Cloudflare API token (How do I create 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"
You can also set the CDDNSVERIFYTOKEN environment variable to manually specify your token. 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 | trace (everything, unfiltered) |
| 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 | inventory.yaml | 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) |
To operate, cddns needs an inventory file in YAML format containing the DNS records you want to watch.
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]
If you prefer, you can visit inventory.yaml for an annotated example.
By default, we check the current directory for an inventory.yaml file.
You can set the CDDNSINVENTORYPATH environment variable to manually specify the location of this file. Click here for more environment variables.
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 (Configuration help). cddns takes the typical layered configuration approach. There are 3 layers. The config file is the base, which is then superseded by environment variables, which are finally superseded by CLI arguments and options.
To show your configuration:
-c or --config will show the config at the given path
bash
cddns config show
To build a configuration file:
bash
cddns config build
By default, cddns checks your local configuration folder for saved configuration.
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.
To build an inventory:
bash
cddns inventory build
To show your inventory:
-p or --path will show the inventory at the given path
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 5 seconds.
Supported architectures: amd64, arm64, riscv64, ppc64le, s390x, i386, armv7, armv6
Running cddns on Docker is an easy 3 step process.
Tip: The CLI is useful for testing and building inventory files locally, which can then be used for your service.
Test your Cloudflare API token: (Help)
bash
docker run \
-e CDDNS_VERIFY_TOKEN='<YOUR_CLOUDFLARE_TOKEN>' \
simbleau/cddns:latest verify
Test your inventory (Help).
bash
docker run \
-e CDDNS_VERIFY_TOKEN='<YOUR_CLOUDFLARE_TOKEN>' \
-v $(pwd)/inventory.yaml:/inventory.yaml \
simbleau/cddns:latest inventory show
Deploy
All environment variables can be used for additional configuration.
bash
docker run \
-e CDDNS_VERIFY_TOKEN='<YOUR_CLOUDFLARE_TOKEN>' \
-v $(pwd)/inventory.yaml:/inventory.yaml \
simbleau/cddns:latest
Tip: The CLI is useful for testing and building inventory files locally, which can then be used for your service.
Test your Cloudflare API token in Docker: (Help)
bash
docker run \
-e CDDNS_VERIFY_TOKEN='<YOUR_CLOUDFLARE_TOKEN>' \
simbleau/cddns:latest verify
Test your inventory in Docker (Help).
bash
docker run \
-e CDDNS_VERIFY_TOKEN='<YOUR_CLOUDFLARE_TOKEN>' \
-v $(pwd)/inventory.yaml:/inventory.yaml \
simbleau/cddns:latest inventory show
Create 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='
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:
Test your Cloudflare API token: (Help)
bash
cddns verify --token '<YOUR_CLOUDFLARE_TOKEN>'
Test your inventory (Help).
bash
cddns inventory --path '/to/your/inventory.yaml' show
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.yaml'
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: "inventory.yaml" readOnly: true env: - 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 commit --force"
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.