A small and fast DDNS updater for Cloudflare.
π Quiet mode enabled
π Cloudflare DDNS
π₯· Priviledges after dropping:
πΈ Effective UID: 1000
πΈ Effective GID: 1000
πΈ Supplementary GIDs: (empty)
π£ Added a new A record of "β¦β¦" (ID: β¦β¦)
π£ Added a new AAAA record of "β¦β¦" (ID: β¦β¦)
- Ultra-small Docker images (about 2.5 MB) for all common architectures.
- Ability to update multiple domains across different zones.
- Ability to enable or disable IPv4 and IPv6 individually.
- Support of internationalized domain names.
- Support of wildcard domain names (e.g.,
*.example.org
). - Ability to remove stale records or choose to remove records on exit/stop.
- Ability to obtain IP addresses from Cloudflare, ipify, or local network interfaces.
- Support of timezone and Cron expressions.
- Full configurability via environment variables.
- Ability to pass API tokens via a file instead of an environment variable.
- Local caching to reduce Cloudflare API usage.
- Integration with Healthchecks.io.
By default, public IP addresses are obtained using the Cloudflare debugging page. This minimizes the impact on privacy because we are already using the Cloudflare API to update DNS records. Moreover, if Cloudflare servers are not reachable, chances are you could not update DNS records anyways. You can also configure the tool to use ipify, which claims not to log any visitor information.
π· The superuser privilege is immediately dropped after the updater starts.
The updater honors PGID
and PUID
and will drop Linux capabilities (divided superuser privileges).
π The source code depends on six external libraries (outside the Go project).
- cap:
Manipulation of Linux capabilities. - cloudflare-go:
The official Go binding of Cloudflare API v4. It provides robust handling of pagination, rate limiting, and other tricky details. - cron:
Parsing of Cron expressions. - go-cache:
Essentiallymap[string]interface{}
with expiration times. - mock (for testing only):
A comprehensive, semi-official framework for mocking. - testify (for testing only):
A comprehensive tool set for testing Go programs.
π Directly run the provided Docker images.
docker run \
--network host \
-e CF_API_TOKEN=YOUR-CLOUDFLARE-API-TOKEN \
-e DOMAINS=www.example.org \
-e PROXIED=true \
favonia/cloudflare-ddns
𧬠Directly run the updater from its source.
You need the Go tool to run the updater from its source.
CF_API_TOKEN=YOUR-CLOUDFLARE-API-TOKEN \
DOMAINS=www.example.org \
PROXIED=true \
go run ./cmd/*.go
Incorporate the following fragment into the compose file (typically docker-compose.yml
or docker-compose.yaml
).
version: "3"
services:
cloudflare-ddns:
image: favonia/cloudflare-ddns:latest
network_mode: host
restart: always
security_opt:
- no-new-privileges:true
environment:
- PGID=1000
- PUID=1000
- CF_API_TOKEN
- DOMAINS
- PROXIED=true
π‘ Use network_mode: host
to enable IPv6 (or read more).
The easiest way to enable IPv6 is to use network_mode: host
so that the tool can access the host IPv6 network directly. If you wish to keep the tool isolated from the host network, check out the official documentation on IPv6 and this GitHub issue about IPv6. If your host OS is Linux, hereβs the tl;dr:
- Use
network_mode: bridge
instead ofnetwork_mode: host
. - Edit or create
/etc/docker/daemon.json
with the following content:{ "ipv6": true, "fixed-cidr-v6": "fd00::/8", "experimental": true, "ip6tables": true }
- Restart the Docker daemon (if you are using systemd):
systemctl restart docker.service
π Use restart: always
to automatically restart the updater on system reboot.
Dockerβs default restart policies should prevent excessive logging when there are configuration errors.
π‘οΈ Use no-new-privileges:true
, PUID
, and PGID
to protect yourself.
Change 1000
to the user or group IDs you wish to use to run the updater. The setting no-new-privileges:true
provides additional protection, especially when you run the container as a non-superuser. The updater itself will read PUID
and PGID
and attempt to drop all those privileges as much as possible.
π Use PROXIED=true
to hide your IP addresses.
The setting PROXIED=true
instructs Cloudflare to cache webpages on your machine and hide your actual IP addresses. If you wish to bypass that and expose your actual IP addresses, simply remove PROXIED=true
. (The default value of PROXIED
is false
.)
Add these lines to your environment file (typically .env
):
CF_API_TOKEN=YOUR-CLOUDFLARE-API-TOKEN
DOMAINS=example.org,www.example.org,example.io
π CF_API_TOKEN
is your Cloudflare API token.
The value of CF_API_TOKEN
should be an API token (not an API key), which can be obtained from the API Tokens page. Use the Edit zone DNS template to create and copy a token into the environment file.
π DOMAINS
contains the domains to update.
The value of DOMAINS
should be a list of fully qualified domain names separated by commas. For example, DOMAINS=example.org,www.example.org,example.io
instructs the tool to manage the domains example.org
, www.example.org
, and example.io
. These domains do not have to be in the same zone---the tool will identify their zones automatically.
docker-compose pull cloudflare-ddns
docker-compose up --detach --build cloudflare-ddns
Kubernetes offers great flexibility in assembling different objects together. The following shows a minimum setup.
Save the following configuration as cloudflare-ddns.yaml
.
apiVersion: apps/v1
kind: Deployment
metadata:
name: cloudflare-ddns
labels:
app: cloudflare-ddns
spec:
replicas: 1
strategy:
type: Recreate
selector:
matchLabels:
app: cloudflare-ddns
template:
metadata:
name: cloudflare-ddns
labels:
app: cloudflare-ddns
spec:
restartPolicy: Always
containers:
- name: cloudflare-ddns
image: favonia/cloudflare-ddns:latest
securityContext:
allowPrivilegeEscalation: false
runAsUser: 1000
runAsGroup: 1000
env:
- name: "IP6_PROVIDER"
value: "none"
- name: "PROXIED"
value: "true"
- name: "CF_API_TOKEN"
value: YOUR-CLOUDFLARE-API-TOKEN
- name: "DOMAINS"
value: "example.org,www.example.org,example.io"
π Use restartPolicy: Always
to automatically restart the updater on system reboot.
Kubernetesβs default restart policies should prevent excessive logging when there are configuration errors.
π‘οΈ Use runAsUser
, runAsGroup
, and allowPrivilegeEscalation: false
to protect yourself.
Kubernetes comes with built-in support to drop superuser privileges. The updater itself will also attempt to drop all of them.
π‘ Use IP6_PROVIDER: "none"
to disable IPv6 management.
The support of IPv6 in Kubernetes has been improving, but a working setup still takes effort. Since Kubernetes 1.21+, the IPv4/IPv6 dual stack is enabled by default, but a setup which allows IPv6 egress traffic (e.g., to reach Cloudflare servers to detect public IPv6 addresses) still requires deep understanding of Kubernetes and is beyond this simple guide. The popular tool minicube, which implements a simple local Kubernetes cluster, unfortunately does not support IPv6 yet. Until there is an easy way to enable IPv6 in Kubernetes, the template here will have IPv6 disabled.
If you manage to enable IPv6, congratulations. Feel free to remove IP6_PROVIDER: "none"
to detect and update both A
and AAAA
records. There is almost no danger in enabling IPv6 even when the IPv6 setup is not working. In the worst case, the updater will remove all AAAA
records associated with the domains in DOMAINS
and IP6_DOMAINS
because those records will appear to be βstale.β The deleted records will be recreated once the updater correctly detects the IPv6 addresses.
π Use PROXIED: "true"
to hide your IP addresses.
The setting PROXIED: "true"
instructs Cloudflare to cache webpages on your machine and hide your actual IP addresses. If you wish to bypass that and expose your actual IP addresses, simply remove PROXIED: "true"
. (The default value of PROXIED
is false
.)
π CF_API_TOKEN
is your Cloudflare API token.
The value of CF_API_TOKEN
should be an API token (not an API key), which can be obtained from the API Tokens page. Use the Edit zone DNS template to create and copy a token into the environment file.
π DOMAINS
contains the domains to update.
The value of DOMAINS
should be a list of fully qualified domain names separated by commas. For example, DOMAINS=example.org,www.example.org,example.io
instructs this tool to manage the domains example.org
, www.example.org
, and example.io
. These domains do not have to be in the same zone---this tool will identify their zones automatically.
kubectl create -f cloudflare-ddns.yaml
π Cloudflare accounts and API tokens
Name | Valid Values | Meaning | Required? | Default Value |
---|---|---|---|---|
CF_ACCOUNT_ID |
Cloudflare Account IDs | The account ID used to distinguish multiple zone IDs with the same name | No | "" (unset) |
CF_API_TOKEN_FILE |
Paths to files containing Cloudflare API tokens | A file that contains the token to access the Cloudflare API | Exactly one of CF_API_TOKEN and CF_API_TOKEN_FILE should be set |
N/A |
CF_API_TOKEN |
Cloudflare API tokens | The token to access the Cloudflare API | Exactly one of CF_API_TOKEN and CF_API_TOKEN_FILE should be set |
N/A |
In most cases, CF_ACCOUNT_ID
is not needed.
π Domains and IP providers
Name | Valid Values | Meaning | Required? | Default Value |
---|---|---|---|---|
DOMAINS |
Comma-separated fully qualified domain names or wildcard domain names | The domains this tool should manage for both A and AAAA records |
(See below) | N/A |
IP4_DOMAINS |
Comma-separated fully qualified domain names or wildcard domain names | The domains this tool should manage for A records |
(See below) | N/A |
IP6_DOMAINS |
Comma-separated fully qualified domain names or wildcard domain names | The domains this tool should manage for AAAA records |
(See below) | N/A |
IP4_PROVIDER |
cloudflare.doh , cloudflare.trace , ipify , local , and none |
How to detect IPv4 addresses. (See below) | No | cloudflare.trace |
IP6_PROVIDER |
cloudflare.doh , cloudflare.trace , ipify , local , and none |
How to detect IPv6 addresses. (See below) | No | cloudflare.trace |
π At least one of
DOMAINS
andIP4/6_DOMAINS
must be non-empty.At least one domain should be listed in
DOMAINS
,IP4_DOMAINS
, orIP6_DOMAINS
. Otherwise, if all of them are empty, then this updater has nothing to do. It is fine to list the same domain in bothIP4_DOMAINS
andIP6_DOMAINS
, which is equivalent to listing it inDOMAINS
. Internationalized domain names are supported using the non-transitional processing that is fully compatible with IDNA2008.
π Available providers for
IP4_PROVIDER
andIP6_PROVIDER
cloudflare.doh
Get the public IP address by queryingwhoami.cloudflare.
against Cloudflare via DNS-over-HTTPS and update DNS records accordingly.cloudflare.trace
Get the public IP address by parsing the Cloudflare debugging page and update DNS records accordingly.ipify
Get the public IP address via ipifyβs public API and update DNS records accordingly.local
Get the address via local network interfaces and update DNS records accordingly. When multiple local network interfaces or in general multiple IP addresses are present, the tool will use the address that would have been used for outbound UDP connections to Cloudflare servers.β οΈ You need access to the host network (such asnetwork_mode: host
in Docker Compose orhostNetwork: true
in Kubernetes) for this policy, for otherwise the tool will detect the addresses inside the bridge network in Docker or the default namespaces in Kubernetes instead of those in the host network.none
Stop the DNS updating completely. Existing DNS records will not be removed.The option
IP4_PROVIDER
is governing IPv4 addresses andA
-type records, while the optionIP6_PROVIDER
is governing IPv6 addresses andAAAA
-type records. The two options act independently of each other.
β³ Schedules, timeouts, and parameters of new DNS records
Name | Valid Values | Meaning | Required? | Default Value |
---|---|---|---|---|
CACHE_EXPIRATION |
Positive time durations with a unit, such as 1h and 10m . See time.ParseDuration |
The expiration of cached Cloudflare API responses | No | 6h0m0s (6 hours) |
DELETE_ON_STOP |
Boolean values, such as true , false , 0 and 1 . See strconv.ParseBool |
Whether managed DNS records should be deleted on exit | No | false |
DETECTION_TIMEOUT |
Positive time durations with a unit, such as 1h and 10m . See time.ParseDuration |
The timeout of each attempt to detect IP addresses | No | 5s (5 seconds) |
PROXIED |
Boolean values, such as true , false , 0 and 1 . See strconv.ParseBool |
Whether new DNS records should be proxied by Cloudflare | No | false |
TTL |
Time-to-live (TTL) values in seconds | The TTL values used to create new DNS records | No | 1 (This means βautomaticβ to Cloudflare) |
TZ |
Recognized timezones, such as UTC |
The timezone used for logging and parsing UPDATE_CRON |
No | UTC |
UPDATE_CRON |
Cron expressions. See the documentation of cron | The schedule to re-check IP addresses and update DNS records (if necessary) | No | @every 5m (every 5 minutes) |
UPDATE_ON_START |
Boolean values, such as true , false , 0 and 1 . See strconv.ParseBool |
Whether to check IP addresses on start regardless of UPDATE_CRON |
No | true |
UPDATE_TIMEOUT |
Positive time durations with a unit, such as 1h and 10m . See time.ParseDuration |
The timeout of each attempt to update DNS records, per domain, per record type | No | 30s (30 seconds) |
Note that the update schedule does not take the time to update records into consideration. For example, if the schedule is βfor every 5 minutesβ, and if the updating itself takes 2 minutes, then the actual interval between adjacent updates is 3 minutes, not 5 minutes.
π‘οΈ Dropping superuser privileges
Name | Valid Values | Meaning | Required? | Default Value |
---|---|---|---|---|
PGID |
Non-zero POSIX group ID | The group ID this tool should assume | No | Effective group ID; if it is zero, then the real group ID; if it is still zero, then 1000 |
PUID |
Non-zero POSIX user ID | The user ID this tool should assume | No | Effective user ID; if it is zero, then the real user ID; if it is still zero, then 1000 |
The updater will also try to drop supplementary group IDs.
ποΈ Monitoring the tool
Name | Valid Values | Meaning | Required? | Default Value |
---|---|---|---|---|
QUIET |
Boolean values, such as true , false , 0 and 1 . See strconv.ParseBool |
Whether the updater should reduce the logging to the standard output | No | false |
HEALTHCHECKS |
Healthchecks.io ping URLs, such as https://hc-ping.com/<uuid> or https://hc-ping.com/<project-ping-key>/<name-slug> |
If set, the tool will ping Healthchecks.io when it successfully updates IP addresses | No | N/A |
If you are using Docker Compose, run docker-compose up --detach
after changing the settings.
If you are using Kubernetes, run kubectl replace -f cloudflare-ddns.yaml
after changing the settings.
I am migrating from oznu/cloudflare-ddns.
Old Parameter | New Paramater | |
---|---|---|
API_KEY=key |
βοΈ | Use CF_API_TOKEN=key |
API_KEY_FILE=file |
βοΈ | Use CF_API_TOKEN_FILE=file |
ZONE=example.org and SUBDOMAIN=sub |
βοΈ | Use DOMAINS=sub.example.org directly |
PROXIED=true |
βοΈ | Same |
RRTYPE=A |
βοΈ | Both IPv4 and IPv6 are enabled by default; use IP6_PROVIDER=none to disable IPv6 |
RRTYPE=AAAA |
βοΈ | Both IPv4 and IPv6 are enabled by default; use IP4_PROVIDER=none to disable IPv4 |
DELETE_ON_STOP=true |
βοΈ | Same |
INTERFACE=iface |
βοΈ | Not required for local providers; we can handle multiple network interfaces |
CUSTOM_LOOKUP_CMD=cmd |
β | There is not even a shell in the minimum Docker image. |
DNS_SERVER=server |
β | Only the Cloudflare server is supported. |
Questions, suggestions, feature requests, and contributions are all welcome! Feel free to open a GitHub issue.