cddns is a modern, green, hackable DDNS CLI and cloud-native service for Cloudflare built in Rust, featuring interactive builders and layered configuration options.
Cargo is the recommended way to install CDDNS as a CLI (What is Cargo?).
- cargo install cddns
cddns uses a Cloudflare API token to see and edit your DNS records. In both usage as a CLI and a service, an inventory file is used to know which DNS records to watch. 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 to any command or subcommand will provide additional information.
First test a Cloudflare 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 CDDNS_TOKEN environment variable to manually specify your token. Click here for more environment variables.
For CLI usage and testing, you may 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, we offer 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 |
| ----------------------------------------------- | --------------------------------------------------- | ---------------------------------- | ------------------------------------------ |
| CDDNSCONFIG | The path to your configuration file | Varies by OS | /etc/cddns/CDDNS.toml |
| CDDNSTOKEN or CDDNSVERIFYTOKEN | The default Cloudflare API Token to use | None | GAWnixPCAADXRAjoKSxiKsIhe7pJqMmAzkhZc33w |
| CDDNSINVENTORY or CDDNSINVENTORYPATH | The path to your inventory file | inventory.yaml | MyInventory.yml |
| CDDNSLISTINCLUDEZONES | Regex filters for zones to include in CLI usage | .* (Match all) | imbleau.com,imbleau.dev |
| CDDNSLISTINCLUDERECORDS | Regex filters for records to include in CLI usage | .* (Match all) | .*\.imbleau.com |
| CDDNSLISTIGNOREZONES | Regex filters for zones to ignore in CLI usage | None | imbleau.com |
| CDDNSLISTIGNORERECORDS | Regex filters for records to ignore in CLI usage | None | shop\..+\.com |
| CDDNSCOMMITFORCE | Force commit (Do not prompt) for inventory commit | false | true |
| CDDNSWATCH_INTERVAL | The milliseconds between checking DNS records | 5000 (5s) | 60000 (60s) |
cddns uses YAML files to save which DNS records to watch.
To see DNS records managed by your API token, we offer a list command.
cddns list [records/zones]
To quickly get setup, we offer an interactive inventory file builder.
cddns inventory build
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 CDDNS_INVENTORY environment variable to manually specify the location of this file. Click here for more environment variables.
Help: cddns verify --help
The verify command will attempt to authenticate using your Cloudflare API token.
If you do not provide --token ..., the token will be obtained from your configuration file or the CDDNS_TOKEN environment variable.
Example:
bash
cddns verify --token 'YOUR_CLOUDFLARE_TOKEN'
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:
Example:
bash
cddns config show
To build a configuration file:
Example:
bash
cddns config build
By default, cddns checks your local configuration folder for saved configuration (More).
Help: cddns list --help
The list command will print Cloudflare resources.
To show your zones AND records:
Example:
bash
cddns list
To show only zones:
Example:
bash
cddns list zones
To show only records:
Example:
bash
cddns list records
Help: cddns inventory --help
The inventory command has several subcommands to manage, build, or show your inventory.
To build an inventory:
Example:
bash
cddns inventory build
To show or validate an inventory:
Example:
bash
cddns inventory [--path 'inventory.yaml'] show
To check an inventory, without making any changes:
Example:
bash
cddns inventory check
To fix erroneous records discovered via check:
Example:
bash
cddns inventory commit [--force]
To continuously fix erroneous records:
Example:
bash
cddns inventory watch [--interval 5000]
cddns will work as a service daemon to keep DNS records up to date. The default check interval is every 5 seconds.
Once you have tested your token and built an inventory file with the CLI, you can deploy via Docker.
1. Ensure your token is valid with the CLI (Help).
bash
cddns verify --token 'YOUR_CLOUDFLARE_TOKEN'
2. Ensure your inventory is valid with the CLI (Help).
bash
cddns inventory --path '/to/your/inventory.yaml' show
3. Deploy with Docker
bash
docker service create -d \
--replicas=1 \
--name cddns-service \
--mount type=bind,source=/to/your/inventory.yaml,target=inventory.yaml \
-e CDDNS_TOKEN='<YOUR_CLOUDFLARE_TOKEN>' \
simbleau/cddns:latest
We will eventually support standard installation techniques such as Helm. You may try a custom setup or you may follow our imperative steps:
bash
cddns verify --token 'YOUR_CLOUDFLARE_TOKEN'
bash
cddns inventory --path '/to/your/inventory.yaml' show
kubectl create secret generic cddns-api-token \
--from-literal=token='YOUR_CLOUDFLARE_API_TOKEN'
kubectl create configmap cddns-inventory \
--from-file '/to/your/inventory.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: CDDNS_TOKEN
valueFrom: # Cloudflare API token
secretKeyRef:
name: cddns-api-token
key: token
6. Apply deployment
kubectl apply -f deployment.yaml
```
bash
cddns verify
bash
cddns inventory show
bash
sudo crontab -e
*/10 * * * * "cfddns inventory commit --force"
Dynamic DNS 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.