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.

Github Release PyPI Docker Image Version Build Status Publish

Features

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.

② Quick Configuration

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

  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 
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

Custom Callback Configuration

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:

Advanced Usage:

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

Linux

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:

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

MIT

Star History

Star History Chart

This site is open source. Improve this page.