DDNS

English

简体中文

English

简体中文

Appearance

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 ReleasePyPIDocker Image VersionBuild StatusPublish

Features ​

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.

  • For detailed instructions and advanced usage, see Docker Usage Documentation

    Supports command line, configuration file, and environment variable parameters

    • Command line CLI

      sh
      docker run newfuture/ddns -h

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

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

    • Using environment variables:

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

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

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

keytyperequireddefaultdescriptiontips
idstring√N/AAPI Access IDCloudflare uses email (leave empty when using Token)
HE.net can be left empty
Huawei Cloud uses Access Key ID (AK)
tokenstring√N/AAPI Auth TokenSome platforms call it secret key, remove when sharing feedback
dnsstringNo"dnspod"DNS ProviderAlibaba 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
ipv4arrayNo[]IPv4 Domain ListWhen [], IPv4 address will not be retrieved and updated
ipv6arrayNo[]IPv6 Domain ListWhen [], IPv6 address will not be retrieved and updated
index4string|int|arrayNo"default"IPv4 Get MethodCan set network interface, private, public, regex etc.
index6string|int|arrayNo"default"IPv6 Get MethodCan set network interface, private, public, regex etc.
ttlnumberNonullDNS Resolution TTLUses DNS default policy when not set
proxystring|arrayNoN/AHTTP Proxy Format: http://host:portMultiple proxies tried sequentially until success, DIRECT for direct connection
sslstring|booleanNo"auto"SSL Certificate Verificationtrue (force verify), false (disable verify), "auto" (auto downgrade) or custom CA certificate file path
debugboolNofalseEnable DebugDebug mode, only effective with command line parameter --debug
cachestring|boolNotrueCache RecordsKeep enabled normally to avoid frequent updates, default location is ddns.cache in temp directory, can also specify a specific path
logobjectNonullLog 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 NameConstant ContentDescription
__DOMAIN__DDNS Domain
__IP__Obtained corresponding type IP address
__RECORDTYPE__DDNS Record Type
__TTL__DDNS TTL
__TIMESTAMP__Request timestampWith decimal

Configuration Example ​

json
{
  "$schema": "https://ddns.newfuture.cc/schema/v4.1.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 ​

bash
# 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 ​

bash
# 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:

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

Released under the MIT License

Copyright © 2016 ~ 2026 NewFuture