DDNS

DDNS JSON Configuration File Reference

This document provides detailed information about the JSON configuration file format and parameters for the DDNS tool. JSON configuration files have priority between command line arguments and environment variables.

Basic Usage

By default, DDNS looks for a config.json file in the current directory. You can also use the -c parameter to specify a configuration file path:

Note: When using configuration files in Docker, you need to mount the configuration file to the container’s /ddns/ directory through volume mapping. For details, please refer to the Docker documentation.

# Generate configuration file
ddns --new-config
# Specify parameters and configuration file
ddns --dns dnspod --ipv4 ddns.newfuture.cc --new-config config.json

# Use specified configuration file
ddns -c /path/to/config.json
# Or use Python source code
python -m ddns -c /path/to/config.json

# Use multiple configuration files
ddns -c cloudflare.json -c dnspod.json
# Or via environment variables
export DDNS_CONFIG="cloudflare.json,dnspod.json"
ddns

JSON Schema

DDNS configuration files follow JSON Schema standards. It’s recommended to add the $schema field to your configuration file for editor auto-completion and validation features:

Since v4.1, configuration files support single-line comments.

{
  "$schema": "https://ddns.newfuture.cc/schema/v4.1.json"
}

Schema

Configuration Parameters Table

Key Name Type Required Default Value Parameter Description Notes
dns string No None DNS Provider Available values: 51dns, alidns, aliesa, callback, cloudflare, debug, dnscom, dnspod_com, dnspod, edgeone, he, huaweidns, namesilo, noip, tencentcloud
id string Yes None API Access ID Configure according to provider documentation (e.g., AccessKeyID)
token string Yes None API Authorization Token Configure according to provider documentation (e.g., AccessSecret)
endpoint string No None API Endpoint URL For custom or private deployment API addresses, uses default endpoint when empty
ipv4 array No [] IPv4 Domain List  
ipv6 array No [] IPv6 Domain List  
index4 string|int|array No ["default"] IPv4 Retrieval Method See details below
index6 string|int|array No ["default"] IPv6 Retrieval Method See details below
ttl number No null DNS TTL Time In seconds, uses DNS default policy when not set
line string No null DNS Resolution Line ISP line selection, supported values depend on DNS provider
proxy string|array No None HTTP Proxy Try multiple proxies sequentially until success, supports DIRECT(direct), SYSTEM(system proxy)
ssl string|boolean No "auto" SSL Verification Method true (force verification), false (disable verification), "auto" (auto downgrade) or custom CA certificate file path
cache string|bool No true Enable Record Caching Enable to avoid frequent updates, default location is ddns.{hash}.cache in temp directory, or specify custom path
log object No null Log Configuration Log configuration object, supports level, file, format, datefmt parameters

dns

The dns parameter specifies the DNS provider identifier. For supported values, please refer to the Provider List:

When in debug mode and no dns parameter is configured, the debug provider is used.

id and token

The id and token parameters are used for API authentication. Their specific meaning and format depend on the selected DNS provider.

endpoint

The endpoint parameter is used to specify a custom API endpoint. Most providers have default endpoints, so modification is not needed unless there are special requirements.

Special cases include:

ipv4-ipv6

The ipv4 and ipv6 parameters specify the DNS record names to be updated, which can be domain or subdomain lists. You can use array format to specify multiple records.

Supported formats:

index4-index6

The index4 and index6 parameters are used to specify the method for obtaining IP addresses. The following values can be used:

Supported types:

Configuration examples:

{
    "index4": ["public", "url:http://ipv4.icanhazip.com"], // Prefer public IP, fallback to specified URL
    "index6": ["shell:ip route", "regex:2003:.*"], // Use shell command, fallback to regex matching IPv6 addresses
    "index4": [0, "public"], // Use first network interface IP, fallback to public IP
    "index6": "public", // Use public IPv6 address
    "index4": false // Disable IPv4 record updates
}

ttl

The ttl parameter specifies the Time To Live (TTL) for DNS records in seconds. The default value is null, which means using the DNS provider’s default TTL policy. The specific value range and default value depend on the selected DNS provider.

line

The line parameter is used to specify DNS resolution lines. Supported values depend on the selected DNS provider.

proxy

The proxy parameter is used to set HTTP proxy, which can be a single proxy address or an array of multiple proxy addresses. The following formats are supported:

Proxy types:

Configuration examples:

{
    "proxy": "http://127.0.0.1:1080",                    // Single proxy address
    "proxy": "SYSTEM",                                   // Use system proxy settings
    "proxy": "DIRECT",                                   // Force direct connection
    "proxy": ["http://127.0.0.1:1080", "DIRECT"],       // Try proxy first, fallback to direct
    "proxy": ["SYSTEM", "http://backup:8080", "DIRECT"], // System proxy → backup proxy → direct
    "proxy": null                                        // Use system default proxy settings
}

Note: If proxy is configured, the proxy only applies to provider requests; IP retrieval APIs will not use the proxy parameter.

ssl

The ssl parameter is used to configure SSL verification method. The following values are supported:

Note: If ssl is configured, all API requests, including provider and IP retrieval APIs, will use this configuration.

cache

The cache parameter is used to configure DNS record caching method. The following values are supported:

log

The log parameter is used to configure logging. It’s an object that supports the following fields:

Key Name Type Required Default Value Description
level string No INFO Log level
file string No None Log file path
format string No Auto-adjusted Log format string
datefmt string No %Y-%m-%dT%H:%M:%S Date time format

Configuration Examples

Single-Provider Format

{
  "$schema": "https://ddns.newfuture.cc/schema/v4.0.json",
  "id": "12345",
  "token": "mytokenkey",
  "dns": "cloudflare",
  "ipv4": ["ddns.newfuture.cc"],
  "ipv6": ["ddns.newfuture.cc", "ipv6.ddns.newfuture.cc"],
  "index4": ["public", "regex:192\\.168\\.1\\..*"],
  "index6": "public",
  "ttl": 300,
  "proxy": ["http://127.0.0.1:1080", "DIRECT"],
  "ssl": "auto",
  "cache": "/var/cache/ddns.cache",
  "log": {
    "level": "DEBUG",
    "file": "/var/log/ddns.log",
    "datefmt": "%Y-%m-%d %H:%M:%S"
  }
}

Multi-Provider Format

Starting from v4.1.0, you can define multiple DNS providers in a single configuration file using the new providers array format:

{
  "$schema": "https://ddns.newfuture.cc/schema/v4.1.json",
  "ssl": "auto",
  "cache": true,
  "log": {"level": "INFO", "file": "/var/log/ddns.log"},
  "providers": [
    {
      "provider": "cloudflare",
      "id": "user1@example.com",
      "token": "cloudflare-token",
      "ipv4": ["test1.example.com"],
      "ttl": 300
    },
    {
      "provider": "dnspod",
      "id": "user2@example.com",
      "token": "dnspod-token",
      "ipv4": ["test2.example.com"],
      "ttl": 600
    }
  ]
}

v4.1 Format Features

Conflict Check

Configuration Priority and Field Override Relationships

The configuration priority order in the DDNS tool is: Command Line Arguments > JSON Configuration File > Environment Variables.

Configuration Override Example

Assuming the following configuration:

  1. Environment Variable: DDNS_TTL=600
  2. JSON Configuration File: "ttl": 300
  3. Command Line Argument: --ttl 900

The final effective value is from the command line argument: ttl=900

If no command line argument is provided, the JSON configuration value is used: ttl=300

Special Cases

Notes

  1. Configuration files use UTF-8 encoding without BOM
  2. All key names in JSON are case-sensitive
  3. For strings that need to use backslashes (such as regular expressions) in configuration files, double escaping is required
  4. The debug parameter is ineffective when set in configuration files, only supports command line parameter --debug
  5. A template configuration file will be automatically generated in the current directory on first run
  6. It’s recommended to use editors that support JSON Schema (such as VSCode) to edit configuration files for auto-completion and validation features
This site is open source. Improve this page.