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 (supports single-file multi-provider, multiple config files, and remote URL)
  • Environment Variables
  • Provider Configuration Guide

• Domain Support:

  • Multiple domain support
  • Multi-level domain resolution
  • Automatic DNS record creation
  • Multiple configuration files and multi-provider concurrent execution

• 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: Docker, binary version, pip version, or source code execution.

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

• Docker (Recommended)

  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
    

• Binary Version (Single file, no Python required)

  Go to releases to download the corresponding version

  Or use the one‑click installation script to automatically download and install the binary for your platform:

  curl -#fSL https://ddns.newfuture.cc/install.sh | sh
  

  Note: Installing to system directories (e.g., /usr/local/bin) may require root or sudo; if permissions are insufficient, run as sudo sh.

  For detailed instructions, see Installation Documentation

• 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

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

  1. Clone or download this repository and extract
  2. Run 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})

📖 Environment Variables Documentation: See Environment Variables Configuration for detailed usage and examples of all environment variables

config.json Configuration File

• A template configuration file will be automatically generated on first run
• Use -c to specify a configuration file (defaults to config.json in the current directory)
• Recommended to use editors that support JsonSchema like VSCode for editing configuration files
• See JSON Configuration File Documentation for complete configuration options and examples

ddns -c path/to/config.json
# Or run with Python
python -m ddns -c /path/to/config.json
# Remote configuration file
ddns -c https://ddns.newfuture.cc/tests/config/debug.json

Configuration Parameters Table

key	type	required	default	description	tips
id	string	√	N/A	API Access ID	Cloudflare uses email (leave empty when using Token) HE.net can be left empty Huawei Cloud uses Access Key ID (AK)
token	string	√	N/A	API Auth Token	Some platforms call it secret key, remove when sharing feedback
dns	string	No	"dnspod"	DNS Provider	Alibaba DNS: alidns, Alibaba ESA: aliesa, Cloudflare: cloudflare, DNS.COM: dnscom, DNSPOD China: dnspod, DNSPOD International: dnspod_com, HE.net: he, Huawei Cloud: huaweidns, NameSilo: namesilo, Tencent Cloud: tencentcloud, Tencent EdgeOne: edgeone, No-IP: noip, Custom Callback: callback. Some providers have detailed configuration docs
ipv4	array	No	[]	IPv4 Domain List	When [], IPv4 address will not be retrieved and updated
ipv6	array	No	[]	IPv6 Domain List	When [], IPv6 address will not be retrieved and updated
index4	string|int|array	No	"default"	IPv4 Get Method	Can set network interface, private, public, regex etc.
index6	string|int|array	No	"default"	IPv6 Get Method	Can set network interface, private, public, regex etc.
ttl	number	No	null	DNS Resolution TTL	Uses DNS default policy when not set
proxy	string|array	No	N/A	HTTP Proxy Format: http://host:port	Multiple proxies tried sequentially until success, DIRECT for direct connection
ssl	string|boolean	No	"auto"	SSL Certificate Verification	true (force verify), false (disable verify), "auto" (auto downgrade) or custom CA certificate file path
debug	bool	No	false	Enable Debug	Debug mode, only effective with command line parameter --debug
cache	string|bool	No	true	Cache Records	Keep enabled normally to avoid frequent updates, default location is ddns.cache in temp directory, can also specify a specific path
log	object	No	null	Log Config (Optional)	Log configuration object, supports level, file, format, datefmt parameters

index4 and index6 Parameter Description

• Numbers (0, 1, 2, 3, etc.): The i-th network interface IP
• String "default" (or no this field): System default IP for external access
• String "public": Use public IP (query via public API, simplified URL mode)
• String "url:xxx": Open URL xxx (e.g., "url:http://ip.sb"), extract IP address from returned data
• String "regex:xxx" Regular expression (e.g., "regex:192.*"): Extract the first IP address matching from ifconfig/ipconfig, note JSON escaping (\ should be written as \\)
  • "192.*" matches all IPs starting with 192 (note: regex: cannot be omitted)
  • To match 10.00.xxxx, write as "regex:10\\.00\\..*" ("\\" JSON escapes to \)
• String "cmd:xxxx": Execute command xxxx and use stdout output as target IP
• String "shell:xxx": Use system shell to run xxx, and use stdout result as target IP
• false: Force disable IPv4 or IPv6 DNS resolution updates
• List: Execute index rules in the list sequentially, using the first successful result as target IP
  • For example, ["public", "regex:172\\..*"] will first query public API, then look for local IPs starting with 172 if no IP is obtained

Custom Callback Configuration

• id field: Fill in callback URL starting with HTTP or HTTPS, HTTPS recommended, supports variable replacement
• token field: POST request parameters (JSON object or JSON string), use GET request if this field is empty or missing. When JSON parameter values contain constants from the table below, they will be automatically replaced with actual content

For detailed configuration guide, see: Callback Provider Configuration

Constant Name	Constant Content	Description
__DOMAIN__	DDNS Domain
__IP__	Obtained corresponding type IP address
__RECORDTYPE__	DDNS Record Type
__TTL__	DDNS TTL
__TIMESTAMP__	Request timestamp	With decimal

Configuration Example

{
  "$schema": "https://ddns.newfuture.cc/schema/v4.0.json",
  "id": "12345",
  "token": "mytokenkey",
  "dns": "dnspod or dnspod_com or alidns or aliesa or dnscom or cloudflare or he or huaweidns or namesilo or tencentcloud or noip or callback",
  "ipv4": ["ddns.newfuture.cc", "ipv4.ddns.newfuture.cc"],
  "ipv6": ["ddns.newfuture.cc", "ipv6.ddns.newfuture.cc"],
  "index4": 0,
  "index6": "public",
  "ttl": 600,
  "proxy": ["http://127.0.0.1:1080", "DIRECT"],
  "log": {
    "level": "DEBUG",
    "file": "dns.log",
    "datefmt": "%Y-%m-%dT%H:%M:%S"
  }
}

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

Use built-in task command to set up scheduled tasks (checks IP every 5 minutes by default for automatic updates)

DDNS provides a built-in task subcommand for managing scheduled tasks with cross-platform automated deployment:

Basic Usage

# Install scheduled task (default 5-minute interval)
ddns task --install --dns dnspod --id your_id --token your_token --ipv4 your.domain.com

# Check task status
ddns task --status

# Uninstall scheduled task
ddns task --uninstall

Supported Systems

• Windows: Uses Task Scheduler
• Linux: Automatically selects systemd or crontab
• macOS: Uses launchd

Advanced Management

# Install with custom interval (minutes)
ddns task --install 10 -c /etc/ddns/config.json

# Enable/disable tasks
ddns task --enable
ddns task --disable

New Feature Advantages:

• ✅ Cross-platform automatic system detection
• ✅ Automatically overwrites existing tasks without manual uninstallation
• ✅ Supports all DDNS configuration parameters
• ✅ Unified command-line interface

For detailed configuration guide, see: CLI Parameters Documentation

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