aeron/digitalocean-ddns-updater repository overview

⁠DigitalOcean DDNS Updater

A tiny DDNS updater (service) for DigitalOcean, primarily intended to be used as a container image.

It’s made to be compatible with Tomato firmware. Yet it probably will work with OpenWRT and DD-WRT as well.

As a security measure, the updater uses a simple token as a first authentication factor and a strict incoming request rate limiter to mitigate a brute-force attack risk.

⁠Usage

This image is available as aeron/digitalocean-ddns-updater⁠ from Docker Hub and ghcr.io/Aeron/digitalocean-ddns-updater⁠ from GitHub Container Registry. You can use them both interchangeably.

docker pull aeron/digitalocean-ddns-updater
# …or…
docker pull ghcr.io/aeron/digitalocean-ddns-updater

⁠Container Running

Simply run a container along with the DIGITALOCEAN_API_TOKEN environment variable supplied:

docker run -d --restart unless-stopped --name ddns \
    -p 80:8080/tcp \
    -e DIGITALOCEAN_API_TOKEN=$DIGITALOCEAN_API_TOKEN \
    aeron/digitalocean-ddns-updater:latest

Or, without publishing ports, in case of a reverse-proxy is handling things.

Optionally, other enviroment variables⁠ can be provided.

⁠Application Options

The following options can be used to run the application:

Arguments can be supplied as a container’s CMD directive.

The default RPS limit value is 0.01, and the default burst limit is 1. It means the updater will accept one request per 100 seconds. Also, the delay will be increased for another 100 seconds on each failed attempt.

Because the token parameter is optional, the updater can generate SHA512 checksum hash from the provided DigitalOcean API token. Considering that a DO API token is private, it should be safe. A security token will be displayed in a container logs on start.

⁠Router Configuration

To make it work properly, the following URL query parameters are required:

• domain — a domain name that will be updated with a supplied IP address;
• ip — an IP address that will bu supplued as a new value for a provided domain;
• token — a security token, which must be the same as the updater has.

In case of Tomato, a custom URL must look alike:

https://domain.com/ddns?domain=a.domain.com&ip=@IP&token=sup3r-l0ng-and-s3cure-t0k3n

The token must be an URL-safe string and long enough. Using plain HTTP is not even considered here.