DDNS

DDNS Docker

Image Information

Image Versions

DDNS image versions (Docker Tags):

docker pull newfuture/ddns:latest
docker pull newfuture/ddns:next

You can also specify a specific version, for example:

docker pull newfuture/ddns:v4.0.0

Image Sources

Images are published to the following registries:

Supports docker pull ghcr.io/newfuture/ddns

Running with docker run

DDNS Docker image supports three configuration methods: command line, environment variables, and config file.

Notes (for docker run):

Using Command Line Parameters (CLI)

You can refer to the CLI parameter documentation for a detailed parameter list. In this case, docker run -v /local/config/:/ddns/ --name=ddns --network=host newfuture/ddns is equivalent to the ddns command line and will not execute scheduled tasks.

This method is suitable for one-time runs or debugging scenarios. Parameters are identical to DDNS command line parameters.

# View ddns command line parameters, equivalent to ddns -h
docker run --rm newfuture/ddns -h
# Add ddns --debug parameter to enable debug mode (or --log.level=debug)
docker run --rm --network=host newfuture/ddns --debug --dns=dnspod --id=12345 --token=mytokenkey --ipv4=www.example.com --ipv4=ipv4.example.com --index4 public
# Debug inside container
docker run -it newfuture/ddns sh

Using Configuration File (JSON)

The working directory inside the Docker container is /ddns/, and the default config file is mapped to /ddns/config.json inside the container.

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

Where /host/config/ is your local directory containing config.json. For details on config.json content, refer to JSON Configuration File Documentation.

Using Environment Variables (ENV)

Environment variables are similar to command line parameters, with a DDNS prefix, recommended in uppercase. Array types need to use JSON format or be wrapped in single quotes.

You can also use the --env-file parameter to load environment variable files.

docker run -d \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV4='["example.com","www.example.com"]' \
  -e DDNS_INDEX4='["public",0]' \
  --network host \
  --name ddns \
  newfuture/ddns

To learn about all supported environment variables, please refer to Environment Variable Configuration Documentation.

Network Modes

Host Network Mode

Using --network host allows the container to directly use the host’s network, so DDNS can correctly obtain the host’s IP address.

For Public or URL modes, host network is usually not required.

docker run -d \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV4=example.com \
  --network host \
  newfuture/ddns

Bridge Network Mode (Default)

If you don’t want to use host network mode, you can also use the default bridge mode, but note that the container will have its own IP. You need to use public mode to get the public IP:

docker run -d \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV4=example.com \
  -e DDNS_INDEX4=public \
  newfuture/ddns

Advanced Configuration

Multi-Domain Configuration

Environment variable method for configuring multiple domains:

docker run -d \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV4='["example.com", "www.example.com", "sub.example.com"]' \
  --network host \
  newfuture/ddns

Command line parameter method for configuring multiple domains:

docker run --rm --network host newfuture/ddns \
  --dns dnspod \
  --id 12345 \
  --token mytokenkey \
  --ipv4 ipv4.example.com \
  --ipv4 www.example.com

Enable IPv6 Support

To use IPv6 in Docker containers, you need to ensure the Docker daemon is configured with IPv6 support:

  1. Edit /etc/docker/daemon.json:
{
    "ipv6": true,
    "fixed-cidr-v6": "fd00::/80"
}
  1. Restart Docker service:
sudo systemctl restart docker
  1. Enable IPv6 when starting the container:
docker run -d \
  --network host \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV6=example.com \
  newfuture/ddns

Docker Compose Examples

Create a docker-compose.yml file:

Basic Environment Variable Configuration

version: "3"
services:
    ddns:
        image: newfuture/ddns:latest
        restart: always
        network_mode: host
        environment:
            - DDNS_DNS=dnspod
            - DDNS_ID=12345
            - DDNS_TOKEN=mytokenkey
            - DDNS_IPV4=example.com,www.example.com
            - DDNS_INDEX4=['public','url:https://api.ipify.org']
            - DDNS_LOG_LEVEL=WARNING

Using Configuration File

version: "3"
services:
    ddns:
        image: newfuture/ddns:latest
        restart: always
        network_mode: host
        volumes:
            - ./config:/ddns

Run Docker Compose:

docker-compose up -d

Using Custom Images

If you need to add other tools or customize the environment in the container, you can create your own Dockerfile based on the official image:

FROM newfuture/ddns:latest

# Install additional tools
RUN apk add --no-cache curl

# Add custom scripts
COPY custom-script.sh /bin/
RUN chmod +x /bin/custom-script.sh

# Override default entrypoint (optional)
# ENTRYPOINT ["/bin/custom-script.sh"]

Troubleshooting & FAQ

Container Can’t Get Correct IP Address

Problem: DDNS cannot correctly obtain host IP

Solution:

  1. Use --network host network mode
  2. Or set -e DDNS_INDEX4=public to force using public API to get IP

No Scheduled Updates Received

Problem: Container runs but doesn’t automatically update DNS

Solution:

  1. Check container logs docker logs ddns
  2. Confirm container is not paused docker ps -a
  3. Try manual update execution docker exec ddns /bin/ddns

Exits Immediately After First Run

Problem: Container exits immediately after startup

Solution:

  1. Add -it parameter to run interactively and see the issue docker run -it --rm newfuture/ddns
  2. Check if environment variables or config files are set correctly

Network Connection Issues

Problem: Container cannot connect to DNS provider API

Solution:

  1. Check network connectivity docker exec ddns ping api.dnspod.cn
  2. Configure HTTP proxy -e DDNS_PROXY=http://proxy:port

More Resources

Configuration Examples for Different DNS Providers

CloudFlare

docker run -d \
  -e DDNS_DNS=cloudflare \
  -e DDNS_ID=user@example.com \
  -e DDNS_TOKEN=your_cloudflare_api_token \
  -e DDNS_IPV4='["example.com"]' \
  --name ddns-cloudflare \
  newfuture/ddns

Alibaba Cloud DNS

docker run -d \
  -e DDNS_DNS=alidns \
  -e DDNS_ID=your_access_key_id \
  -e DDNS_TOKEN=your_access_key_secret \
  -e DDNS_IPV4='["example.com"]' \
  --name ddns-alidns \
  newfuture/ddns

Huawei Cloud DNS

docker run -d \
  -e DDNS_DNS=huaweidns \
  -e DDNS_ID=your_access_key \
  -e DDNS_TOKEN=your_secret_key \
  -e DDNS_IPV4='["example.com"]' \
  --name ddns-huawei \
  newfuture/ddns

Tencent Cloud DNS

docker run -d \
  -e DDNS_DNS=tencentcloud \
  -e DDNS_ID=your_secret_id \
  -e DDNS_TOKEN=your_secret_key \
  -e DDNS_IPV4='["example.com"]' \
  --name ddns-tencent \
  newfuture/ddns

Custom Callback

# GET method callback
docker run -d \
  -e DDNS_DNS=callback \
  -e DDNS_ID="https://api.example.com/ddns?domain=__DOMAIN__&ip=__IP__" \
  -e DDNS_TOKEN="" \
  -e DDNS_IPV4='["example.com"]' \
  --name ddns-callback-get \
  newfuture/ddns

# POST method callback
docker run -d \
  -e DDNS_DNS=callback \
  -e DDNS_ID="https://api.example.com/ddns" \
  -e DDNS_TOKEN='{"api_key": "your_key", "domain": "__DOMAIN__", "ip": "__IP__"}' \
  -e DDNS_IPV4='["example.com"]' \
  --name ddns-callback-post \
  newfuture/ddns

Using Custom API Endpoints

docker run -d \
  -e DDNS_DNS=cloudflare \
  -e DDNS_ENDPOINT=https://api.private-cloudflare.com \
  -e DDNS_ID=user@example.com \
  -e DDNS_TOKEN=your_token \
  -e DDNS_IPV4='["example.com"]' \
  --name ddns-custom-endpoint \
  newfuture/ddns
This site is open source. Improve this page.