DDNS

Automatically update DNS records to the current IP address, supporting IPv4 and IPv6, local (private) IP and public IP. Proxy mode supported, with automatic DNS record creation.

---

Features

• Compatibility and Cross-Platform:

  • Docker (@NN708)
  • Binary files

• Configuration Methods:

  • Command Line Arguments
  • JSON Configuration File
  • Environment Variables
  • Provider Configuration Guide

• Domain Support:

  • Multiple domain support
  • Multi-level domain resolution
  • Automatic DNS record creation

• IP Types:

  • Private IPv4 / IPv6
  • Public IPv4 / IPv6 (supports custom API)
  • Custom commands (shell)
  • Regex selection support (@rufengsuixing)

• Network Proxy:

  • HTTP proxy support
  • Automatic multi-proxy switching

• DNS Provider Support:

  • DNSPOD China (Configuration Guide)
  • Alibaba Cloud DNS (Configuration Guide) ⚡
  • Alibaba Cloud ESA (Configuration Guide) ⚡
  • DNS.COM (Configuration Guide) (@loftor-git)
  • DNSPOD International (Configuration Guide)
  • CloudFlare (Configuration Guide) (@tongyifan)
  • HE.net (Configuration Guide) (@NN708) (Does not support auto-record creation)
  • Huawei Cloud (Configuration Guide) (@cybmp3) ⚡
  • NameSilo (Configuration Guide)
  • Tencent Cloud DNS (Configuration Guide) ⚡
  • Tencent Cloud EdgeOne (Configuration Guide) ⚡
  • No-IP (Configuration Guide)
  • Custom Callback API (Configuration Guide)

  ⚡ Providers marked with lightning use advanced HMAC-SHA256 signature authentication for enterprise-level security

• Other Features:

  • Configurable scheduled tasks
  • TTL configuration support
  • DNS line (ISP) configuration support (for domestic providers)
  • Local file caching (reduces API requests)
  • Custom callback API trigger on IP change (mutually exclusive with DDNS functionality)

Usage

① Installation

Choose one of the following methods: binary version, pip version, source code execution, or Docker.

Docker version is recommended for best compatibility, small size, and optimized performance.

• Docker (Requires Docker Installation)

  For detailed instructions and advanced usage, see Docker Usage Documentation

  Supports command line, configuration file, and environment variable parameters

  • Command line CLI

    docker run newfuture/ddns -h
    

  • Using configuration file (Docker working directory /ddns/, default config location /ddns/config.json):

    docker run -d -v /host/config/:/ddns/ --network host newfuture/ddns
    

  • Using environment variables:

    docker run -d \
      -e DDNS_DNS=dnspod \
      -e DDNS_ID=12345 \
      -e DDNS_TOKEN=mytokenkey \
      -e DDNS_IPV4=ddns.newfuture.cc \
      --network host \
      newfuture/ddns
    

• pip Installation (Requires pip or easy_install)

  1. Install ddns: pip install ddns or easy_install ddns
  2. Run: ddns -h or python -m ddns

• Binary Version (Single file, no Python required)

  Go to releases to download the corresponding version

• Source Code Execution (No dependencies, requires Python environment)

  1. Clone or download this repository and extract
  2. Run python run.py or python -m ddns

② Quick Configuration

1. Apply for API token, fill in the corresponding id and token fields:

   • DNSPOD (China): Create token | Detailed Configuration
   • Alibaba Cloud DNS: Apply for accesskey | Detailed Configuration
   • Alibaba Cloud ESA: Apply for accesskey | Detailed Configuration
   • DNS.COM: API Key/Secret | Detailed Configuration
   • DNSPOD (International): Get token | Detailed Configuration
   • CloudFlare: API Key (Besides email + API KEY, you can also use Token, requires list Zone permission) | Detailed Configuration
   • HE.net: DDNS Documentation (Only fill the set password in the token field, id field can be left empty) | Detailed Configuration
   • Huawei Cloud DNS: APIKEY Application (Click Access Keys on the left, then click Create Access Key) | Detailed Configuration
   • NameSilo: API Key (Get API Key from API Manager) | Detailed Configuration
   • Tencent Cloud DNS: Detailed Configuration
   • No-IP: Username and Password (Use No-IP account username and password) | Detailed Configuration
   • Custom Callback: For parameter configuration, please refer to the custom callback configuration instructions below

2. Modify the configuration file, ipv4 and ipv6 fields for domains to be updated, refer to configuration instructions for details

Detailed Configuration

All fields can be configured through three methods, with priority: Command Line Parameters > JSON Configuration File > Environment Variables

1. Command Line Parameters ddns --key=value (use ddns -h for details), highest priority
2. JSON Configuration File (null values are considered valid and will override environment variable settings; if no corresponding key exists, environment variables will be used)
3. Environment Variables with DDNS_ prefix plus key in uppercase or lowercase, dots converted to underscores (${ddns_id} or ${DDNS_ID}, ${DDNS_LOG_LEVEL})

Configuration Priority and Field Override Relationship

If the same configuration item is set in multiple places, the following priority rules apply:

• Command Line Parameters: Highest priority, overrides all other settings
• JSON Configuration File: Between command line and environment variables, overrides environment variable settings
• Environment Variables: Lowest priority, used when not set by other methods

Advanced Usage:

• JSON configuration file can contain only partial fields, missing fields will use environment variables
• Environment variables support both uppercase and lowercase formats
• Support for nested configuration through dot notation converted to underscores

Scheduled Tasks

Set up scheduled tasks to run automatically

This tool itself does not include loop and scheduled execution functions (to reduce code complexity). You can use system scheduled tasks to run regularly.

Windows

• [Recommended] Run as system identity, right-click "Run as administrator" on task.bat (or run in administrator command line)
• Run scheduled task as current user, double-click or run task.bat (a black window will flash during execution)

Linux

• Using init.d and crontab:

  sudo ./task.sh
  

• Using systemd:

  Install:
  sudo ./systemd.sh install
  Uninstall:
  sudo ./systemd.sh uninstall
  

  Files installed by this script comply with Filesystem Hierarchy Standard (FHS): Executable files are located in /usr/share/DDNS Configuration files are located in /etc/DDNS

Docker

Docker images, without additional parameters, have a scheduled task enabled by default that runs every 5 minutes

FAQ

Windows Server [SSL: CERTIFICATE_VERIFY_FAILED]

Windows Server default security policy will prohibit any untrusted SSL certificates. You can manually add the corresponding certificates #56

Use the system's built-in IE browser to visit the corresponding API once:

• alidns: https://alidns.aliyuncs.com
• aliesa: https://esa.cn-hangzhou.aliyuncs.com
• cloudflare: https://api.cloudflare.com
• dns.com: https://www.dns.com
• dnspod.cn: https://dnsapi.cn
• dnspod international: https://api.dnspod.com
• Huawei DNS: https://dns.myhuaweicloud.com

Troubleshooting and Feedback

1. First confirm whether it's a system/network environment issue
2. Search for similar issues in issues
3. If neither of the above can solve the problem or you're sure it's a bug, create a new issue here
   • Enable --debug
   • Include these contents: running version and method, system environment, error logs, configuration file with id/token removed
   • For source code execution, specify the Python environment used

---

Contributors

License

Star History