DDNS Environment Variables Configuration

Overview

DDNS supports configuration through environment variables with the following priority order: Command Line Arguments > Configuration File > Environment Variables

All environment variables use the DDNS_ prefix followed by the parameter name (recommended uppercase).

export DDNS_xxx="xxx" command applies to the current host docker run -e DDNS_xxx="xxx" command applies to the container

Complete Environment Variables List

Environment Variable	Accepted Values	Description	Example
`DDNS_CONFIG`	File path, supports comma or semicolon-separated multiple paths	Specify config file path, supports multiple files	`DDNS_CONFIG="config.json"` or `DDNS_CONFIG="cloudflare.json,dnspod.json"`
`DDNS_DNS`	`51dns`, `alidns`, `aliesa`, `callback`, `cloudflare`, `debug`, `dnscom`, `dnspod_com`, `dnspod`, `edgeone`, `he`, `huaweidns`, `noip`, `tencentcloud`	DNS Provider	`DDNS_DNS=cloudflare`
`DDNS_ID`	Depends on the provider	API account or ID	`DDNS_ID="[email protected]"`
`DDNS_TOKEN`	Depends on the provider	API token or secret	`DDNS_TOKEN="abcdef123456"`
`DDNS_ENDPOINT`	URL (starting with http or https)	Custom API endpoint	`DDNS_ENDPOINT=https://api.dns.cn`
`DDNS_IPV4`	Domains as array or comma-separated string	List of IPv4 domains	`DDNS_IPV4='["t.com","4.t.com"]'`
`DDNS_IPV6`	Domains as array or comma-separated string	List of IPv6 domains	`DDNS_IPV6=t.com,6.t.com`
`DDNS_INDEX4`	Number, `default`, `public`, `url:`, `regex:`, `cmd:`, `shell:`, or an array of them	IPv4 address detection methods	`DDNS_INDEX4="[0,'regex:192.168.*']"`
`DDNS_INDEX6`	Number, `default`, `public`, `url:`, `regex:`, `cmd:`, `shell:`, or an array of them	IPv6 address detection methods	`DDNS_INDEX6=public`
`DDNS_TTL`	Integer (seconds), varies by provider	DNS record TTL	`DDNS_TTL=600`
`DDNS_LINE`	ISP line such as: 电信, 联通, 移动, or provider-specific values	DNS resolution line	`DDNS_LINE=电信`
`DDNS_PROXY`	IP:port or `DIRECT`, multiple values separated by semicolons	HTTP proxy settings	`DDNS_PROXY="127.0.0.1:1080;DIRECT"`
`DDNS_CACHE`	`true`, `false`, or file path	Enable or specify cache file	`DDNS_CACHE="/tmp/cache"`
`DDNS_SSL`	`true`, `false`, `auto`, or file path	SSL verification mode or certificate path	`DDNS_SSL=false` `DDNS_SSL=/path/ca.crt`
`DDNS_LOG_LEVEL`	`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`	Logging level	`DDNS_LOG_LEVEL="DEBUG"`
`DDNS_LOG_FILE`	File path	Output log file (default: stdout)	`DDNS_LOG_FILE="/tmp/ddns.log"`
`DDNS_LOG_FORMAT`	Python logging format string	Log format template	`DDNS_LOG_FORMAT="%(message)s"`
`DDNS_LOG_DATEFMT`	Date-time format string	Log timestamp format	`DDNS_LOG_DATEFMT="%m-%d %H:%M"`

Basic Configuration Parameters

Configuration File Path

DDNS_CONFIG

Type: String
Required: No
Default: Search in default paths (config.json, ~/.ddns/config.json, etc.)
Format: Single file path or multiple file paths (separated by commas or semicolons)
Description: Specify configuration file path, supports multiple configuration files

Examples:

# Single configuration file
export DDNS_CONFIG="config.json"
export DDNS_CONFIG="/path/to/ddns.json"
  
# Multiple configuration files 
export DDNS_CONFIG="/etc/ddns/cloudflare.json,./dnspod.json"

Authentication Information

DDNS_ID

Type: String
Required: Yes (optional for some DNS providers)
Description: API access ID or user identifier

Examples:

# Cloudflare (email address)
export DDNS_ID="[email protected]"
  
# DNSPod (numeric ID)
export DDNS_ID="12345"
  
# Alibaba Cloud (Access Key ID)
export DDNS_ID="LTAI4xxxxxxxxxxxxx"
  
# HE.net (can be empty)
export DDNS_ID=""

DDNS_TOKEN

Type: String
Required: Yes
Description: API authorization token or key

Examples:

# General API token
export DDNS_TOKEN="abcdef1234567890"
  
# Cloudflare API token
export DDNS_TOKEN="1234567890abcdef_example_token"
  
# Alibaba Cloud Secret Key
export DDNS_TOKEN="secretkey1234567890"

DNS Provider

DDNS_DNS

Type: String
Required: No
Default: dnspod
Available Values: 51dns, alidns, aliesa, callback, cloudflare, debug, dnscom, dnspod, dnspod_com, edgeone, he, huaweidns, noip, tencentcloud
Description: DNS service provider

Examples:

export DDNS_DNS="cloudflare"
export DDNS_DNS="alidns"
export DDNS_DNS="dnspod"

DDNS_ENDPOINT

Type: String
Required: No
Default: None (uses default API endpoint for each DNS provider)
Description: API endpoint URL for custom or private deployments

Examples:

# Custom Cloudflare endpoint
export DDNS_ENDPOINT="https://api.private-cloudflare.com"
  
# Private DNSPod deployment
export DDNS_ENDPOINT="https://internal-dns-api.company.com"
  
# Local testing endpoint
export DDNS_ENDPOINT="http://localhost:8080/api"

Custom Callback Configuration

When using DDNS_DNS="callback", configure custom callbacks with these environment variables:

DDNS_ID: Callback URL address with variable substitution support
DDNS_TOKEN: POST request parameters (JSON string), empty for GET requests

For detailed configuration, see: Callback Provider Configuration Documentation

Examples:

# GET method callback
export DDNS_DNS="callback"
export DDNS_ID="https://api.example.com/ddns?domain=__DOMAIN__&ip=__IP__"
export DDNS_TOKEN=""

# POST method callback (JSON string)
export DDNS_DNS="callback"
export DDNS_ID="https://api.example.com/ddns"
export DDNS_TOKEN='{"api_key": "your_key", "domain": "__DOMAIN__", "ip": "__IP__"}'

Supported Variable Substitutions:

__DOMAIN__: Full domain name
__IP__: IP address (IPv4 or IPv6)
__RECORDTYPE__: DNS record type
__TTL__: Time to live (seconds)
__LINE__: Resolution line
__TIMESTAMP__: Current timestamp

Domain Configuration

IPv4 Domain List

DDNS_IPV4

Type: Array (supports JSON/Python format)
Required: No
Default: []
Description: List of domains requiring IPv4 record updates

Examples:

# JSON array format (recommended)
export DDNS_IPV4='["example.com", "www.example.com", "api.example.com"]'
  
# Python list format
export DDNS_IPV4="['example.com', 'www.example.com']"
  
# Comma-separated string
export DDNS_IPV4="example.com,www.example.com"
  
# Single domain
export DDNS_IPV4="example.com"

IPv6 Domain List

DDNS_IPV6

Type: Array (supports JSON/Python format)
Required: No
Default: []
Description: List of domains requiring IPv6 record updates

Examples:

# JSON array format
export DDNS_IPV6='["example.com", "ipv6.example.com"]'
  
# Comma-separated string
export DDNS_IPV6="example.com,ipv6.example.com"
  
# Single domain
export DDNS_IPV6="ipv6.example.com"

IP Detection Methods

IPv4 Detection Method

DDNS_INDEX4

Type: String or Array
Required: No
Default: ["default"] (uses system's default external IP)
Description: IPv4 address detection methods. Supports comma , or semicolon ; separated string format
Special Note: When value contains regex:, cmd:, or shell: prefix, separator splitting is not supported; the entire string is treated as a single configuration item

Examples:

# Use public IP detection
export DDNS_INDEX4="public"
  
# Multiple methods with fallback
export DDNS_INDEX4='["public", "default"]'
  
# Network interface index
export DDNS_INDEX4="0"  # First network interface
export DDNS_INDEX4="1"  # Second network interface
  
# Custom URL
export DDNS_INDEX4="url:https://api.ipify.org"
  
# Regex pattern (no splitting)
export DDNS_INDEX4="regex:192\\.168\\..*"
  
# Command execution (no splitting)
export DDNS_INDEX4="cmd:hostname -I | awk '{print \$1}'"
  
# Shell command (no splitting)
export DDNS_INDEX4="shell:ip route get 8.8.8.8 | awk '{print \$7}'"

IPv6 Detection Method

DDNS_INDEX6

Type: String or Array
Required: No
Default: ["default"] (uses system's default external IPv6)
Description: IPv6 address detection methods

Examples:

# Use public IPv6 detection
export DDNS_INDEX6="public"
  
# Network interface index
export DDNS_INDEX6="0"
  
# Custom IPv6 detection URL
export DDNS_INDEX6="url:https://api6.ipify.org"
  
# Multiple methods
export DDNS_INDEX6='["public", "default"]'

DNS Configuration

TTL Setting

DDNS_TTL

Type: Integer
Required: No
Default: None (uses DNS provider's default)
Description: DNS record TTL (Time To Live) in seconds

Examples:

# 5 minutes
export DDNS_TTL="300"
  
# 10 minutes (commonly used)
export DDNS_TTL="600"
  
# 1 hour
export DDNS_TTL="3600"

Resolution Line

DDNS_LINE

Type: String
Required: No
Default: None (uses default line)
Description: DNS resolution line, ISP line selection

Examples:

# Default line
export DDNS_LINE="default"
  
# China Telecom
export DDNS_LINE="telecom"
  
# China Unicom
export DDNS_LINE="unicom"
  
# China Mobile
export DDNS_LINE="mobile"
  
# Overseas
export DDNS_LINE="overseas"

Network Configuration

Proxy Settings

DDNS_PROXY

Type: Array or String
Required: No
Default: None (no proxy)
Description: HTTP proxy settings, tries multiple proxies until success

Examples:

# Single proxy
export DDNS_PROXY="127.0.0.1:1080"
  
# Multiple proxies with fallback
export DDNS_PROXY="127.0.0.1:1080;127.0.0.1:8080;DIRECT"
  
# JSON array format
export DDNS_PROXY='["127.0.0.1:1080", "DIRECT"]'
  
# SOCKS proxy
export DDNS_PROXY="socks5://127.0.0.1:1080"
  
# HTTP proxy with authentication
export DDNS_PROXY="http://user:[email protected]:8080"

Cache Configuration

DDNS_CACHE

Type: Boolean or String
Required: No
Default: true
Description: Cache settings to avoid frequent updates

Examples:

# Enable cache (default location)
export DDNS_CACHE="true"
  
# Disable cache
export DDNS_CACHE="false"
  
# Custom cache file path
export DDNS_CACHE="/var/cache/ddns/cache.json"
  
# Use temporary directory
export DDNS_CACHE="/tmp/ddns.cache"

Logging Configuration

Log Level

DDNS_LOG_LEVEL

Type: String
Required: No
Default: INFO
Available Values: DEBUG, INFO, WARNING, ERROR, CRITICAL
Description: Log level

Examples:

# Debug mode (most verbose)
export DDNS_LOG_LEVEL="DEBUG"
  
# Normal operation
export DDNS_LOG_LEVEL="INFO"
  
# Warnings only
export DDNS_LOG_LEVEL="WARNING"
  
# Errors only
export DDNS_LOG_LEVEL="ERROR"

Log File

DDNS_LOG_FILE

Type: String
Required: No
Default: None (outputs to console)
Description: Log file path

Examples:

# System log directory
export DDNS_LOG_FILE="/var/log/ddns.log"
  
# User home directory
export DDNS_LOG_FILE="$HOME/ddns.log"
  
# Temporary directory
export DDNS_LOG_FILE="/tmp/ddns.log"

Log Format

DDNS_LOG_FORMAT

Type: String
Required: No
Default: %(asctime)s %(levelname)s [%(module)s]: %(message)s
Description: Log format string

Examples:

# Simple format
export DDNS_LOG_FORMAT="%(asctime)s: %(message)s"
  
# Detailed format
export DDNS_LOG_FORMAT="%(asctime)s [%(levelname)s] %(name)s: %(message)s"
  
# JSON format
export DDNS_LOG_FORMAT='{"time": "%(asctime)s", "level": "%(levelname)s", "message": "%(message)s"}'

DDNS_LOG_DATEFMT

Type: String
Required: No
Default: %Y-%m-%dT%H:%M:%S
Description: Date time format string

Examples:

# ISO format (default)
export DDNS_LOG_DATEFMT="%Y-%m-%dT%H:%M:%S"
  
# Standard format
export DDNS_LOG_DATEFMT="%Y-%m-%d %H:%M:%S"
  
# Short format
export DDNS_LOG_DATEFMT="%m/%d %H:%M:%S"

Complete Configuration Examples

Basic Configuration

# Basic Cloudflare configuration
export DDNS_DNS="cloudflare"
export DDNS_ID="[email protected]"
export DDNS_TOKEN="your_cloudflare_token"
export DDNS_IPV4="example.com"

Advanced Configuration

# Advanced configuration with multiple domains and custom settings
export DDNS_DNS="cloudflare"
export DDNS_TOKEN="your_api_token"
export DDNS_IPV4='["example.com", "www.example.com", "api.example.com"]'
export DDNS_IPV6='["ipv6.example.com"]'
export DDNS_INDEX4="public"
export DDNS_INDEX6="public"
export DDNS_TTL="600"
export DDNS_PROXY="127.0.0.1:1080;DIRECT"
export DDNS_CACHE="/var/cache/ddns.json"
export DDNS_LOG_LEVEL="DEBUG"
export DDNS_LOG_FILE="/var/log/ddns.log"

Provider-Specific Examples

DNSPod Configuration

export DDNS_DNS="dnspod"
export DDNS_ID="12345"
export DDNS_TOKEN="your_dnspod_token"
export DDNS_IPV4="example.com"
export DDNS_LINE="默认"

Alibaba Cloud DNS Configuration

export DDNS_DNS="alidns"
export DDNS_ID="LTAI4xxxxxxxxxxxxx"
export DDNS_TOKEN="your_secret_key"
export DDNS_IPV4="example.com"
export DDNS_LINE="default"

Custom Callback Configuration

export DDNS_DNS="callback"
export DDNS_ID="https://api.example.com/webhook?domain=__DOMAIN__&ip=__IP__"
export DDNS_TOKEN=""
export DDNS_IPV4="example.com"

Standard Environment Variables Support

DDNS also supports some standard environment variables commonly used in system environments:

Standard Variable	DDNS Equivalent	Description
`HTTP_PROXY`	`DDNS_PROXY`	HTTP proxy server
`HTTPS_PROXY`	`DDNS_PROXY`	HTTPS proxy server
`NO_PROXY`	-	Bypass proxy for these hosts
`PYTHONHTTPSVERIFY`	`DDNS_SSL`	Python HTTPS verification

Note: DDNS-specific variables take priority over standard environment variables.

Configuration Validation

When using environment variables, DDNS will validate the configuration and provide error messages for invalid values:

DNS Provider: Must be one of the supported providers
Domains: Must be valid domain names
TTL: Must be a positive integer
Log Level: Must be a valid log level
File Paths: Must be accessible file paths

env.en.md 17 KB History Raw

DDNS Environment Variables Configuration

Overview

Complete Environment Variables List

Basic Configuration Parameters

Configuration File Path

DDNS_CONFIG

Authentication Information

DDNS_ID

DDNS_TOKEN

DNS Provider

DDNS_DNS

DDNS_ENDPOINT

Custom Callback Configuration

Domain Configuration

IPv4 Domain List

DDNS_IPV4

IPv6 Domain List

DDNS_IPV6

IP Detection Methods

IPv4 Detection Method

DDNS_INDEX4

IPv6 Detection Method

DDNS_INDEX6

DNS Configuration

TTL Setting

DDNS_TTL

Resolution Line

DDNS_LINE

Network Configuration

Proxy Settings

DDNS_PROXY

Cache Configuration

DDNS_CACHE

Logging Configuration

Log Level

DDNS_LOG_LEVEL

Log File

DDNS_LOG_FILE

Log Format

DDNS_LOG_FORMAT

DDNS_LOG_DATEFMT

Complete Configuration Examples

Basic Configuration

Advanced Configuration

Provider-Specific Examples

DNSPod Configuration

Alibaba Cloud DNS Configuration

Custom Callback Configuration

Standard Environment Variables Support

Configuration Validation

See Also

env.en.md 17 KB

History Raw