{"id":13580021,"url":"https://github.com/simbleau/cddns","last_synced_at":"2025-04-06T00:30:38.381Z","repository":{"id":63145287,"uuid":"555590139","full_name":"simbleau/cddns","owner":"simbleau","description":"A modern, hackable, green DDNS service and cli for Cloudflare.","archived":true,"fork":false,"pushed_at":"2023-06-12T02:00:24.000Z","size":545,"stargazers_count":16,"open_issues_count":13,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-05T07:00:02.184Z","etag":null,"topics":["cli","cloudflare","ddns","devops","dns","docker","kubernetes","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simbleau.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-10-21T22:19:24.000Z","updated_at":"2024-09-25T08:36:07.000Z","dependencies_parsed_at":"2024-01-16T20:29:36.770Z","dependency_job_id":"60c7e6c7-3ef8-4321-99a5-0d6d30dc46e0","html_url":"https://github.com/simbleau/cddns","commit_stats":{"total_commits":280,"total_committers":5,"mean_commits":56.0,"dds":"0.16785714285714282","last_synced_commit":"efcedfac1051c18747415e49ab163c50955cb496"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simbleau%2Fcddns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simbleau%2Fcddns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simbleau%2Fcddns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simbleau%2Fcddns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simbleau","download_url":"https://codeload.github.com/simbleau/cddns/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247376088,"owners_count":20929181,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cloudflare","ddns","devops","dns","docker","kubernetes","rust"],"created_at":"2024-08-01T15:01:46.161Z","updated_at":"2025-04-06T00:30:38.026Z","avatar_url":"https://github.com/simbleau.png","language":"Rust","readme":"# CDDNS : Cloudflare Dynamic DNS\n**cddns** is a non-complicated, uncompromisingly green DDNS CLI and cloud-native service for [Cloudflare](https://cloudflare.com) built in Rust. Featuring layered configuration and interactive file builders.\n\n**⚠️ WARNING: This project is operational, but not yet considered production ready. [See v1.0 tracking](https://github.com/simbleau/cddns/issues/50)**\n\n---\n[![Crates.io](https://img.shields.io/crates/v/cddns)](https://crates.io/crates/cddns)\n[![dependency status](https://deps.rs/repo/github/simbleau/cddns/status.svg)](https://deps.rs/repo/github/simbleau/cddns)\n[![CI](https://github.com/simbleau/cddns/actions/workflows/ci.yaml/badge.svg)](https://github.com/simbleau/cddns/actions/workflows/ci.yaml)\n\n# Table of Contents\n- [CDDNS : Cloudflare Dynamic DNS](#cddns--cloudflare-dynamic-dns)\n- [Table of Contents](#table-of-contents)\n- [1 Installation](#1-installation)\n  - [1.1 Supported Platforms](#11-supported-platforms)\n  - [1.2 Requirements](#12-requirements)\n  - [1.3 Local Installation](#13-local-installation)\n    - [Option A: Cargo (Recommended)](#option-a-cargo-recommended)\n    - [Option B: Binary](#option-b-binary)\n  - [1.4 Docker](#14-docker)\n- [2 Quickstart](#2-quickstart)\n- [3 Usage](#3-usage)\n  - [3.1 Overview](#31-overview)\n    - [3.1.1 API Tokens](#311-api-tokens)\n    - [3.1.2 Inventory](#312-inventory)\n    - [3.1.3 Configuration (Optional)](#313-configuration-optional)\n    - [3.1.4 Environment Variables](#314-environment-variables)\n  - [3.2 Subcommands](#32-subcommands)\n    - [3.2.1 Verify](#321-verify)\n    - [3.2.2 Config](#322-config)\n      - [3.2.2.1 Show](#3221-show)\n      - [3.2.2.2 Build](#3222-build)\n    - [3.2.3 List](#323-list)\n      - [3.2.3.1 Zones](#3231-zones)\n      - [3.2.3.2 Records](#3232-records)\n    - [3.2.4 Inventory](#324-inventory)\n      - [3.2.4.1 Build](#3241-build)\n      - [3.2.4.2 Show](#3242-show)\n      - [3.2.4.3 Check](#3243-check)\n      - [3.2.4.4 Update](#3244-update)\n      - [3.2.4.5 Prune](#3245-prune)\n      - [3.2.4.6 Watch](#3246-watch)\n  - [3.3 Service Deployment](#33-service-deployment)\n    - [3.3.1 Docker](#331-docker)\n    - [3.3.2 Docker Compose](#332-docker-compose)\n    - [3.3.3 Kubernetes](#333-kubernetes)\n    - [3.3.4 Crontab](#334-crontab)\n- [4 Purpose](#4-purpose)\n- [5 License](#5-license)\n\n# 1 Installation\n\n## 1.1 Supported Platforms\n- Command Line Utility\n  - Native (Windows / MacOS / Unix)\n- Service\n  - Docker\n  - Docker Compose\n  - Kubernetes\n  - Crontab\n\n## 1.2 Requirements\n- Cloudflare Account ([Help](https://developers.cloudflare.com/fundamentals/account-and-billing/account-setup/create-account/))\n- Cloudflare API Token with **Edit DNS** permissions ([Help](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/))\n\n## 1.3 Local Installation\nInstalling the cddns CLI is a convenient way to test your configuration and build the necessary files for service deployment.\n\n### Option A: Cargo (Recommended)\nCargo is the recommended way to install CDDNS as a CLI ([What is Cargo?](https://doc.rust-lang.org/cargo/)).\n- `cargo +nightly install cddns`\n### Option B: Binary\n- Download a compatible binary release from [releases](https://github.com/simbleau/cloudflare-ddns/releases)\n\n## 1.4 Docker\nAny command in this document can be run or tested in a container with [Docker](https://docker.io).\n\n```bash\ndocker run simbleau/cddns \u003cSUBCOMMAND\u003e\n```\n\n# 2 Quickstart\nFirst, test your Cloudflare API token ([Help](#311-api-tokens)) with the following command:\n```bash\ncddns --token \u003cYOUR_CLOUDFLARE_TOKEN\u003e verify\n```\n\nNext, generate an inventory file ([Help](#312-inventory)):\n```bash\ncddns \\\n  --token \u003cYOUR_CLOUDFLARE_TOKEN\u003e \\\n  inventory build\n```\n\nCheck your inventory:\n```bash\ncddns \\\n  --token \u003cYOUR_CLOUDFLARE_TOKEN\u003e \\\n  inventory --path '/path/to/inventory.yml' \\\n  check\n```\n\nIf the following works, continue to your OS-specific service instructions:\n- [Docker](#331-docker)\n- [Docker Compose](#332-docker-compose)\n- [Kubernetes](#333-kubernetes)\n- [Crontab](#334-crontab)\n\n# 3 Usage\n## 3.1 Overview\n**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.\n\nTo operate, cddns needs an inventory file containing your DNS records ([What is a DNS record?](https://www.cloudflare.com/learning/dns/dns-records/)), 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.\n\n### 3.1.1 API Tokens\ncddns will need a valid Cloudflare API token to function ([How do I create an API token?](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/)).\n\nYou can test an API token with the following command:\n\u003e `cddns verify --token \u003cYOUR_CLOUDFLARE_TOKEN\u003e`.\n\nOn success, you may see \"`This API Token is valid and active`\"\n\nTo avoid using `--token` in every command, you can save a [configuration file](#313-configuration-optional) or set the **CDDNS_VERIFY_TOKEN** environment variable to manually specify your token. [Click here](#314-environment-variables) for more environment variables.\n\n### 3.1.2 Inventory\ncddns also needs an inventory file in [YAML format](https://yaml.org/) containing the DNS records you want to watch.\n\nBy default, we check your local configuration directory for your inventory file.\n- On Linux, this would be `$XDG_CONFIG_HOME/cddns/inventory.yml` or `$HOME/.config/cddns/inventory.yml`\n- On MacOS, this would be `$HOME/Library/Application Support/cddns/inventory.yml`\n- On Windows, this would be `%AppData%\\cddns\\inventory.yml`\n\nTo quickly get setup, the CLI offers an interactive inventory file builder.\n\u003e `cddns inventory build`\n\n- **Zones** are domains, subdomains, and identities managed by Cloudflare.\n- **Records** are A (IPv4) or AAAA (IPv6) DNS records managed by Cloudflare.\n\nTo see DNS records managed by your API token, the CLI also offers a list command.\n\u003e `cddns list [records/zones]`\n\nYou can visit [`inventory.yml`](inventory.yml) for an annotated example.\n\nYou can set the **CDDNS_INVENTORY_PATH** environment variable to manually specify the location of this file. [Click here](#314-environment-variables) for more environment variables.\n\n### 3.1.3 Configuration (Optional)\nYou may optionally use a [TOML file](https://toml.io/en/) to save configuration, such as your API key. **You should restrict the permissions on this file if storing your API token.**\n\nBy default, we check your local configuration directory for your configuration file.\n- On Linux, this would be `$XDG_CONFIG_HOME/cddns/config.toml` or `$HOME/.config/cddns/config.toml`\n- On MacOS, this would be `$HOME/Library/Application Support/cddns/config.toml`\n- On Windows, this would be `%AppData%\\cddns\\config.toml`\n\nTo quickly get setup, the CLI offers an interactive configuration file builder.\n\u003e `cddns config build`\n\nYou can also visit [`config.toml`](config.toml) for an annotated example.\n\nYou can set the **CDDNS_CONFIG** environment variable to manually specify the location of this file. [Click here](#314-environment-variables) for more environment variables.\n\n### 3.1.4 Environment Variables\nEvery value which can be stored in a [configuration file](#313-configuration-optional) can be superseded or provided as an environment variable.\n\n| Variable Name                      | Description                                                                                                                                                                                                                          | Default                                     | Example                  |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- | ------------------------ |\n| **RUST_LOG**                       | [Log filtering directives](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directiveshttps://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives) | `info,cddns=trace`                          | `debug`                  |\n| **CDDNS_CONFIG**                   | The path to your configuration file                                                                                                                                                                                                  | [Varies by OS](#313-configuration-optional) | `/etc/cddns/config.toml` |\n| **CDDNS_VERIFY_TOKEN**             | The default Cloudflare API Token to use                                                                                                                                                                                              | None                                        | `GAWnixPCAADXRAjoK...`   |\n| **CDDNS_LIST_INCLUDE_ZONES**       | Regex filters for zones to include in CLI usage                                                                                                                                                                                      | `.*` (Match all)                            | `imbleau.com,.*\\.dev`    |\n| **CDDNS_LIST_IGNORE_ZONES**        | Regex filters for zones to ignore in CLI usage                                                                                                                                                                                       | None                                        | `imbleau.com`            |\n| **CDDNS_LIST_INCLUDE_RECORDS**     | Regex filters for records to include in CLI usage                                                                                                                                                                                    | `.*` (Match all)                            | `.*\\.imbleau.com`        |\n| **CDDNS_LIST_IGNORE_RECORDS**      | Regex filters for records to ignore in CLI usage                                                                                                                                                                                     | None                                        | `shop\\..+\\.com`          |\n| **CDDNS_INVENTORY_PATH**           | The path to your inventory file                                                                                                                                                                                                      | [Varies by OS](#312-inventory)              | `MyInventory.yml`        |\n| **CDDNS_INVENTORY_FORCE_UPDATE**   | Skip all prompts (force) for `inventory update`                                                                                                                                                                                      | `false`                                     | `true`                   |\n| **CDDNS_INVENTORY_FORCE_PRUNE**    | Skip all prompts (force) for `inventory prune`                                                                                                                                                                                       | `false`                                     | `true`                   |\n| **CDDNS_INVENTORY_WATCH_INTERVAL** | The milliseconds between checking DNS records                                                                                                                                                                                        | `30000` (30s)                               | `60000` (60s)            |\n\n\n## 3.2 Subcommands\n**Appending `--help` or `-h` to any command or subcommand will provide additional information.**\n\nThe CLI is useful for testing and building files for your service deployment. Below is a reference of all commands in the CLI.\n\n*Reminder: you may add `-h` or `--help` to any subcommand to receive helpful usage information.*\n\n### 3.2.1 Verify\n**Help: `cddns verify --help`**\n\nThe `verify` command will validate your Cloudflare API token.\n```bash\ncddns verify [--token '\u003cYOUR_CLOUDFLARE_TOKEN\u003e']\n```\n\nIf you do not provide `--token ...`, the token will be obtained from your [configuration file](#313-configuration-optional) or the [**CDDNS_VERIFY_TOKEN**](#314-environment-variables) environment variable.\n\n### 3.2.2 Config\n**Help: `cddns config --help`**\n\nThe `config` command will help you build or manage your configuration ([Help](#313-configuration-optional)). 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.\n\nBy default, cddns checks your [local configuration folder](#313-configuration-optional) for saved configuration.\n\n#### 3.2.2.1 Show\nTo show your current configuration:\n\n*`-c` or `--config` will show the inventory at the given path*\n```bash\ncddns config show\n```\n\n#### 3.2.2.2 Build\nTo build a configuration file:\n\n```bash\ncddns config build\n```\n\n### 3.2.3 List\n**Help: `cddns list --help`**\n\nThe `list` command will print Cloudflare resources visible with your API token.\n\n- **Zones** are domains, subdomains, and identities managed by Cloudflare.\n- **Records** are A (IPv4) or AAAA (IPv6) DNS records managed by Cloudflare.\n\nTo list your zones AND records:\n\n*`-include-zones \u003cpattern1,pattern2,..\u003e` will include only zones matching one of the given regex patterns*\n*`-ignore-zones \u003cpattern1,pattern2,..\u003e` will ignore zones matching one of the given regex patterns*\n*`-include-records \u003cpattern1,pattern2,..\u003e` will include only records matching one of the given regex patterns*\n*`-ignore-records \u003cpattern1,pattern2,..\u003e` will ignore records matching one of the given regex patterns*\n```bash\ncddns list\n```\n\n#### 3.2.3.1 Zones\nTo list only zones:\n\n*`-z` or `--zone` will only show the zone matching the given name or id.*\n```bash\ncddns list zones\n```\n\n#### 3.2.3.2 Records\nTo list only records:\n\n*`-z` or `--zone` will only show the records matching the given zone's name or id.*\n*`-r` or `--record` will only show the records matching the given name or id.*\n```bash\ncddns list records\n```\n\n### 3.2.4 Inventory\n**Help: `cddns inventory --help`**\n\nThe `inventory` command has several subcommands to build and control inventory.\n\n*`-p` or `--path` will show the inventory at the given path*\n\n#### 3.2.4.1 Build\nTo build an inventory:\n\n*`--stdout` will output the inventory to stdout*\\\n*`--clean` will output without post-processing*\n```bash\ncddns inventory build\n```\n\n#### 3.2.4.2 Show\nTo show your inventory:\n\n*`--clean` will output without post-processing*\n```bash\ncddns inventory show\n```\n\n#### 3.2.4.3 Check\nTo check your DNS records, without making any changes:\n```bash\ncddns inventory check\n```\n\n#### 3.2.4.4 Update\nTo update all outdated DNS records found in `inventory check`:\n\n*`--force-update true` will attempt to skip prompts*\n```bash\ncddns inventory update\n```\n\n#### 3.2.4.5 Prune\nTo prune all invalid DNS records found in `inventory check`:\n\n*`--force-prune true` will attempt to skip prompts*\n```bash\ncddns inventory prune\n```\n\n#### 3.2.4.6 Watch\nTo continuously update erroneous records:\n\n*`-w` or `--watch-interval` will change the **milliseconds** between DNS refresh*\n```bash\ncddns inventory watch\n```\n\n## 3.3 Service Deployment\ncddns will work as a service daemon to keep DNS records up to date. The default check interval is every 30 seconds.\n\n### 3.3.1 Docker\nCurrently supported architectures: `amd64`, `arm64`\n\nRunning cddns on Docker is an easy 3 step process.\n\n1. Test your Cloudflare API token: ([Help](#311-api-tokens))\n```bash\nexport CDDNS_VERIFY_TOKEN='...'\n```\n```bash\ndocker run  \\\n  -e CDDNS_VERIFY_TOKEN \\\n  simbleau/cddns:latest verify\n```\n\n1. Test your inventory ([Help](#312-inventory)).\n```bash\nexport CDDNS_INVENTORY_PATH='/to/your/inventory.yml'\n```\n```bash\ndocker run \\\n  -e CDDNS_VERIFY_TOKEN \\\n  -e CDDNS_INVENTORY_PATH='/inventory.yml' \\\n  -v $CDDNS_INVENTORY_PATH:'/inventory.yml' \\\n  simbleau/cddns:latest inventory check\n```\n\n1. Deploy\n\n*All [environment variables](#314-environment-variables) can be used for additional configuration.*\n```bash\ndocker run \\\n  -e CDDNS_VERIFY_TOKEN \\\n  -e CDDNS_INVENTORY_PATH='/inventory.yml' \\\n  -v $CDDNS_INVENTORY_PATH:/inventory.yml \\\n  simbleau/cddns:latest\n```\n\n### 3.3.2 Docker Compose\n1. Validate your configuration with the [Docker instructions](#331-docker) (above)\n\n2. Deploy Compose file[[?](https://docs.docker.com/compose/compose-file/)]\n\n*All [environment variables](#314-environment-variables) can be used for additional configuration.*\n```yaml\n# docker-compose.yaml\nversion: '3.3'\nservices:\n    cddns:\n        environment:\n            - CDDNS_VERIFY_TOKEN\n            - CDDNS_INVENTORY_PATH='/inventory.yml'\n        volumes:\n            - /host/path/to/inventory.yml:/inventory.yml\n        image: 'simbleau/cddns:latest'\n```\n```bash\ndocker compose up\n```\n\n### 3.3.3 Kubernetes\nWe 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:\n\n1. Create a Secret[[?](https://kubernetes.io/docs/concepts/configuration/secret/)] for your API token:\n```\nkubectl create secret generic cddns-api-token \\\n  --from-literal=token='YOUR_CLOUDFLARE_API_TOKEN'\n```\n\n2. Create a ConfigMap[[?](https://kubernetes.io/docs/concepts/configuration/configmap/)] for your inventory:\n```\nkubectl create configmap cddns-inventory \\\n  --from-file '/to/your/inventory.yml'\n```\n\n3. Create a Deployment[[?](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)]:\n\n*All [environment variables](#314-environment-variables) can be used for additional configuration.*\n```yaml\n# deployment.yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: cddns-deployment\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      app: cddns\n  template:\n    metadata:\n      labels:\n        app: cddns\n    spec:\n      volumes: # Expose inventory as volume\n        - name: \"inventory\"\n          configMap:\n            name: \"cddns-inventory\"\n      containers:\n      - name: cddns\n        image: simbleau/cddns:latest\n        volumeMounts:\n        - name: inventory # Mount inventory file\n            mountPath: /opt/bin/cddns/\n            readOnly: true\n        env:\n        - name: CDDNS_INVENTORY_PATH\n          value: /opt/bin/cddns/inventory.yml\n        - name: CDDNS_VERIFY_TOKEN\n            valueFrom: # Cloudflare API token\n              secretKeyRef:\n                  name: cddns-api-token\n                  key: token\n```\n\n1. Deploy:\n```\nkubectl apply -f deployment.yaml\n```\n### 3.3.4 Crontab\n1. Test your Cloudflare API token: ([Help](#311-getting-started))\n```bash\ncddns verify\n```\n\n1. Test your inventory ([Help](#312-inventory)).\n```bash\ncddns inventory show\n```\n\n1. Launch crontab editor\n```bash\nsudo crontab -e\n```\n\n1. Add crontab entry (e.g. every 10 minutes)\n```\n*/10 * * * * \"cfddns inventory --force-update true update\"\n```\n\n---\n\n# 4 Purpose\ncddns 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.\n\n# 5 License\nThis project is dual-licensed under both [Apache 2.0](LICENSE-APACHE) and [MIT](LICENSE-MIT) licenses.","funding_links":[],"categories":["Rust"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimbleau%2Fcddns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimbleau%2Fcddns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimbleau%2Fcddns/lists"}