Project Icon

cloudflare-ddns

Cloudflare DDNS更新器,高效管理动态DNS记录

Cloudflare DDNS更新器是一款高效的动态DNS管理工具。它能自动检测公网IP并更新DNS记录,支持多种域名类型,包括国际化域名和通配符域名。该工具兼容IPv4和IPv6,集成了Cloudflare特有功能,如代理和DNS记录注释。此外,它还注重隐私保护,提供多种通知方式,满足不同用户的动态DNS管理需求。

🌟 Cloudflare DDNS

Github Source Go Reference Codecov Docker Image Size OpenSSF Best Practices OpenSSF Scorecard

A feature-rich and robust Cloudflare DDNS updater with a small footprint. The program will detect your machine's public IP addresses and update DNS records using the Cloudflare API.

📜 Highlights

⚡ Efficiency

  • 🤏 The Docker image takes less than 5 MB after compression.
  • 🔁 The Go runtime re-uses existing HTTP connections.
  • 🗃️ Cloudflare API responses are cached to reduce the API usage.

💯 Complete Support of Domain Names

  • 😌 You can simply list domains (e.g., www.a.org, hello.io) without knowing their DNS zones.
  • 🌍 Internationalized domain names (e.g., 🐱.example.org and 日本。co。jp) are fully supported.
  • 🃏 Wildcard domains (e.g., *.example.org) are also supported.
  • 🕹️ You can toggle IPv4 (A records) and IPv6 (AAAA records) for each domain.

🌥️ Enjoy Cloudflare-specific Features

🕵️ Privacy

By default, public IP addresses are obtained via 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 cannot update DNS records anyways.

👁️ Notification

  • 🩺 The updater can work with Healthchecks or Uptime Kuma so that you receive notifications when it fails to update IP addresses.
  • 📣 The updater can also actively send you notifications via any service supported by the shoutrrr library, including emails, major notification services, major messaging platforms, and generic webhooks.

🛡️ Security

  • 🛡️ The updater uses only HTTPS or DNS over HTTPS to detect IP addresses. This makes it harder for someone else to trick the updater into updating your DNS records with wrong IP addresses. See the Security Model for more information.

  • ✍️ You can verify the Docker images were built from this repository using the cosign tool (click to expand)
    cosign verify favonia/cloudflare-ddns:latest \
      --certificate-identity-regexp https://github.com/favonia/cloudflare-ddns/ \
      --certificate-oidc-issuer https://token.actions.githubusercontent.com
    

    Note: this only proves that a Docker image is from this repository. It cannot prevent malicious code if someone hacks into GitHub or this repository.

  • 📚 The updater uses only established open-source Go libraries (click to expand)
    • cloudflare-go:
      The official Go binding of Cloudflare API v4.
    • cron:
      Parsing of Cron expressions.
    • go-retryablehttp:
      HTTP clients with automatic retries and exponential backoff.
    • go-querystring:
      A library to construct URL query parameters.
    • shoutrrr:
      A notification library for sending general updates.
    • ttlcache:
      In-memory cache to hold Cloudflare API responses.
    • mock (for testing only):
      A comprehensive, semi-official framework for mocking.
    • testify (for testing only):
      A comprehensive tool set for testing Go programs.

⛷️ Quick Start

(Click to expand the following items.)

🐋 Directly run the Docker image.
docker run \
  --network host \
  -e CF_API_TOKEN=YOUR-CLOUDFLARE-API-TOKEN \
  -e DOMAINS=example.org,www.example.org,example.io \
  -e PROXIED=true \
  favonia/cloudflare-ddns:latest
🧬 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=example.org,www.example.org,example.io \
  PROXIED=true \
  go run github.com/favonia/cloudflare-ddns/cmd/ddns@latest

🐋 Deployment with Docker Compose

📦 Step 1: Updating the Compose File

Incorporate the following fragment into the compose file (typically docker-compose.yml or docker-compose.yaml). The template may look a bit scary, but only because it includes various optional flags for extra security protection.

services:
  cloudflare-ddns:
    image: favonia/cloudflare-ddns:latest
    # Choose the appropriate tag based on your need:
    # - "latest" for the latest stable version (which could become 2.x.y
    #   in the future and break things)
    # - "1" for the latest stable version whose major version is 1
    # - "1.x.y" to pin the specific version 1.x.y
    network_mode: host
    # This bypasses network isolation and makes IPv6 easier (optional; see below)
    restart: always
    # Restart the updater after reboot
    user: "1000:1000"
    # Run the updater with specific user and group IDs (in that order).
    # You can change the two numbers based on your need.
    read_only: true
    # Make the container filesystem read-only (optional but recommended)
    cap_drop: [all]
    # Drop all Linux capabilities (optional but recommended)
    security_opt: [no-new-privileges:true]
    # Another protection to restrict superuser privileges (optional but recommended)
    environment:
      - CF_API_TOKEN=YOUR-CLOUDFLARE-API-TOKEN
        # Your Cloudflare API token
      - DOMAINS=example.org,www.example.org,example.io
        # Your domains (separated by commas)
      - PROXIED=true
        # Tell Cloudflare to cache webpages and hide your IP (optional)

(Click to expand the following important tips.)

🔑 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. (The less secure API key authentication is deliberately not supported.)

  • To update only DNS records, use the Edit zone DNS template to create a token.
  • To update only WAF lists, choose Create Custom Token and add the Accounts - Account Filter Lists - Write permission to create a token.
  • To update DNS records and WAF lists, use the Edit zone DNS template and add the Accounts - Account Filter Lists - Write permission to create a token.

You can also grant new permissions to existing tokens at any time!

📍 DOMAINS is the list of domains to update

The value of DOMAINS should be a list of fully qualified domain names (FQDNs) separated by commas. For example, DOMAINS=example.org,www.example.org,example.io instructs the updater to manage the domains example.org, www.example.org, and example.io. These domains do not have to be in the same zone---the updater will identify their zones automatically.

🚨 Remove PROXIED=true if you are not running a web server

The setting PROXIED=true instructs Cloudflare to cache webpages and hide your IP addresses. If you wish to bypass that and expose your actual IP addresses, remove PROXIED=true. If your traffic is not HTTP(S), then Cloudflare cannot proxy it and you should probably turn off the proxying by removing PROXIED=true. The default value of PROXIED is false.

📴 Add IP6_PROVIDER=none if you want to disable IPv6 completely

The updater, by default, will attempt to update DNS records for both IPv4 and IPv6, and there is no harm in leaving the automatic detection on even if your network does not work for one of them. However, if you want to disable IPv6 entirely (perhaps to avoid all the detection errors), add the setting IP6_PROVIDER=none.

📡 Expand this if you want IPv6 without bypassing network isolation (without network_mode: host)

The easiest way to enable IPv6 is to use network_mode: host so that the updater can access the host IPv6 network directly. This has the downside of bypassing the network isolation. If you wish to keep the updater isolated from the host network, remove network_mode: host and follow the steps in the official Docker documentation to enable IPv6. Use newer versions of Docker that come with (much) better IPv6 support.

🛡️ Change user: "1000:1000" to the user and group IDs you want to use

Change 1000:1000 to USER:GROUP for the USER and GROUP IDs you wish to use to run the updater. The settings cap_drop, read_only, and no-new-privileges in the template provide additional protection, especially when you run the container as a non-superuser.

🚀 Step 2: Building the Container

docker-compose pull cloudflare-ddns
docker-compose up --detach --build cloudflare-ddns

❓ Frequently Asked Questions

(Click to expand the following items.)

😠 I simulated an IP address change by editing the DNS records, but the updater never picked it up!

Please rest assured that the updater is working as expected. It will update the DNS records immediately for a real IP change. Here is a detailed explanation. There are two causes of an IP mismatch:

  1. A change of your actual IP address (a real change), or
  2. A change of the IP address in the DNS records (a simulated change).

The updater assumes no one will actively change the DNS records. In other words, it assumes simulated changes will not happen. It thus caches the DNS records and cannot detect your simulated changes. However, when your actual IP address changes, the updater will immediately update the DNS records. Also, the updater will eventually check the DNS records and detect simulated changes after CACHE_EXPIRATION (six hours by default) has passed.

If you really wish to test the updater with simulated IP changes in the DNS records, you can set CACHE_EXPIRATION=1ns (all cache expiring in one nanosecond), effectively disabling the caching. However, it is recommended to keep the default value (six hours) to reduce your network traffic.

😠 Why did the updater detect a public IP address different from the WAN IP address on my router?

Is your “public” IP address on your router between 100.64.0.0 and 100.127.255.255? If so, you are within your ISP’s CGNAT (Carrier-grade NAT). In practice, there is no way for DDNS to work with CGNAT, because your ISP does not give you a real public IP address, nor does it allow you to forward IP packages to your router using cool protocols such as Port Control Protocol. You have to give up DDNS or switch to another ISP. You may consider other services such as Cloudflare Tunnel that can work around CGNAT.

🎛️ Further Customization

⚙️ All Settings

(Click to expand the following items.)

🔑 The Cloudflare API token
NameValid ValuesMeaningRequired?Default Value
CF_API_TOKENCloudflare API tokensThe token to access the Cloudflare APIExactly one of CF_API_TOKEN and CF_API_TOKEN_FILE should be setN/A
CF_API_TOKEN_FILEPaths to files containing Cloudflare API tokensA file that contains the token to access the Cloudflare APIExactly one of CF_API_TOKEN and CF_API_TOKEN_FILE should be setN/A
📍 DNS domains to update
NameValid ValuesMeaningRequired?Default Value
DOMAINSComma-separated fully qualified domain names or wildcard domain namesThe domains the updater should manage for both A and AAAA records(See below)(empty list)
IP4_DOMAINSComma-separated fully qualified domain names or wildcard domain namesThe domains the updater should manage for A records(See below)(empty list)
IP6_DOMAINSComma-separated fully qualified domain names or wildcard domain namesThe domains the updater should manage for AAAA records(See below)(empty list)
📍 At least one of DOMAINS, IP4/6_DOMAINS, and WAF_LISTS must be non-empty.

At least something should be listed in DOMAINS, IP4_DOMAINS, IP6_DOMAINS, or WAF_LISTS (for WAF lists, see below). Otherwise, if all of them are empty, then the updater has nothing to do. It is fine to list the same domain in both IP4_DOMAINS and IP6_DOMAINS, which is equivalent to listing it in DOMAINS. Internationalized domain names are supported using the non-transitional processing fully compatible with IDNA2008. See this useful FAQ on internationalized domain names.

🃏 What are wildcard domains?

Wildcard domains (*.example.org) represent all subdomains that would not exist otherwise. Therefore, if you have another subdomain entry sub.example.org, the wildcard domain is independent of it, because it only represents the other subdomains which do not have their own entries. Also, you can only have one layer of *---*.*.example.org would not work.

🔍 IP address providers
NameValid ValuesMeaningRequired?Default Value
IP4_PROVIDERcloudflare.doh, cloudflare.trace, local, url:URL, or noneHow to detect IPv4 addresses, or none to disable IPv4 (see below)Nocloudflare.trace
IP6_PROVIDERcloudflare.doh, cloudflare.trace, local, url:URL, or noneHow
项目侧边栏1项目侧边栏2
推荐项目
Project Cover

豆包MarsCode

豆包 MarsCode 是一款革命性的编程助手,通过AI技术提供代码补全、单测生成、代码解释和智能问答等功能,支持100+编程语言,与主流编辑器无缝集成,显著提升开发效率和代码质量。

Project Cover

AI写歌

Suno AI是一个革命性的AI音乐创作平台,能在短短30秒内帮助用户创作出一首完整的歌曲。无论是寻找创作灵感还是需要快速制作音乐,Suno AI都是音乐爱好者和专业人士的理想选择。

Project Cover

有言AI

有言平台提供一站式AIGC视频创作解决方案,通过智能技术简化视频制作流程。无论是企业宣传还是个人分享,有言都能帮助用户快速、轻松地制作出专业级别的视频内容。

Project Cover

Kimi

Kimi AI助手提供多语言对话支持,能够阅读和理解用户上传的文件内容,解析网页信息,并结合搜索结果为用户提供详尽的答案。无论是日常咨询还是专业问题,Kimi都能以友好、专业的方式提供帮助。

Project Cover

阿里绘蛙

绘蛙是阿里巴巴集团推出的革命性AI电商营销平台。利用尖端人工智能技术,为商家提供一键生成商品图和营销文案的服务,显著提升内容创作效率和营销效果。适用于淘宝、天猫等电商平台,让商品第一时间被种草。

Project Cover

吐司

探索Tensor.Art平台的独特AI模型,免费访问各种图像生成与AI训练工具,从Stable Diffusion等基础模型开始,轻松实现创新图像生成。体验前沿的AI技术,推动个人和企业的创新发展。

Project Cover

SubCat字幕猫

SubCat字幕猫APP是一款创新的视频播放器,它将改变您观看视频的方式!SubCat结合了先进的人工智能技术,为您提供即时视频字幕翻译,无论是本地视频还是网络流媒体,让您轻松享受各种语言的内容。

Project Cover

美间AI

美间AI创意设计平台,利用前沿AI技术,为设计师和营销人员提供一站式设计解决方案。从智能海报到3D效果图,再到文案生成,美间让创意设计更简单、更高效。

Project Cover

AIWritePaper论文写作

AIWritePaper论文写作是一站式AI论文写作辅助工具,简化了选题、文献检索至论文撰写的整个过程。通过简单设定,平台可快速生成高质量论文大纲和全文,配合图表、参考文献等一应俱全,同时提供开题报告和答辩PPT等增值服务,保障数据安全,有效提升写作效率和论文质量。

投诉举报邮箱: service@vectorlightyear.com
@2024 懂AI·鲁ICP备2024100362号-6·鲁公网安备37021002001498号