NearlyFreeSpeech.NET Dynamic DNS

This script will update the A DNS record (and optionally, the AAAA records) for a domain/subdomain at NearlyFreeSpeech.NET with the public IP address for the machine the script runs on. Run this script on a server in which the public IP address is dynamic and changes so your domain is always up to date.

How It Works

There are two steps to this script. First, it retrieves the configured IP address for the domain/subdomain, the current public IP address of the server, and then compares the two. If the public IP address is different, it updates the A (and, if configured, the AAAA) record(s) of the domain/subdomain with the new IP address.

Requirements

• python-dotenv
• requests

Both can be downloaded from pip using pip install -r requirements.txt

Configuring

Configurations are set by providing the script with environment variables or command line arguments.

Configs

Env Variable	Command Line Argument	Required	Description
USERNAME		Y	Your NFSN username
API_KEY		Y	API key for using NFSN's APIs. This can be obtained via the Member Interface > "Profile" tab > "Actions" > "Manage API Key"
DOMAIN		Y	Domain that the subdomain belongs to
SUBDOMAIN		N	Subdomain to update with the script. Leave blank for the bare domain name
ENABLE_DDNS		N	Enable dynamic DNS updates. Defaults to true for backwards compatibility. Set to false to disable DDNS and run only certificate management.
ENABLE_CERTS		N	Enable Let's Encrypt certificate issuing and renewal via ACME DNS-01 challenge. Defaults to false. Set to true to enable certificate management.
DDNS_CRON		N	Cron schedule for DDNS updates. Defaults to */30 * * * * (every 30 minutes). Only used if ENABLE_DDNS=true. Can also be set at build time via --build-arg.
CERT_CRON		N	Cron schedule for certificate renewal checks. Defaults to 0 3 * * * (daily at 3 AM). Only used if ENABLE_CERTS=true. Can also be set at build time via --build-arg.
LE_CONFIG_HOME		N	Directory acme.sh uses for its renewal state. Defaults to /root/.acme.sh, which is not persisted across container recreates. Set to a mounted path such as /acme-state when ENABLE_CERTS=true.
IP_PROVIDER		N	Use a different IP providing service than the default: http://ipinfo.io/ip This might be useful if the default provider is unavailable or is blocked. The alternate provider MUST be served over http (please open an issue if this is ever a problem) and MUST return ONLY the IP in the response body
IPV6_PROVIDER		N	Use a different IP providing service than the default: http://v6.ipinfo.io/ip This might be useful if the default provider is unavailable or is blocked. The alternate provider MUST be served over http (please open an issue if this is ever a problem) and MUST return ONLY the IP in the response body
ENABLE_IPV4	--no-ipv4	N	Update the A (IPv4) record. Defaults to true. Set to false (or pass --no-ipv4) together with IPv6 for an IPv6-only run.
ENABLE_IPV6	--ipv6 or -6	N	Also check and update the AAAA (IPv6) record on the specified domain, in addition to the A record. Defaults to false.
IP_USE_DIG	--useDig or -d	N	Use the system's dig command and Google's DNS server to determine the IP address instead of an IP providing service over HTTP

Boolean environment variables accept true, 1, yes and on to enable, and false, 0, no, off or an empty value to disable.

Running

Manually

It is as easy as running: python3 ./nfsn-ddns.py (after installing the dependencies listed above)

To include all of the environmental variables inline when running, you can do something like this:

$ export USERNAME=username API_KEY=api_key DOMAIN=domain.com SUBDOMAIN=subdomain && python3 ./nfsn-ddns.py

or with optional command line arguments like this:

$ export USERNAME=username API_KEY=api_key DOMAIN=domain.com SUBDOMAIN=subdomain && python3 ./nfsn-ddns.py --useDig

or you can put your variables in a .env file:

# NFSN credentials
USERNAME=your_username
API_KEY=your_api_key
DOMAIN=example.com
SUBDOMAIN=subdomain

# Feature flags
ENABLE_DDNS=true        # Enable dynamic DNS (default: true)
ENABLE_CERTS=false      # Enable Let's Encrypt certs (default: false)

# Optional: Customize schedules
#DDNS_CRON=*/30 * * * *  # Every 30 minutes (default)
#CERT_CRON=0 3 * * *     # Daily at 3 AM (default)

# Optional: also update the AAAA record
#ENABLE_IPV6=true

# Optional: set false with ENABLE_IPV6=true for an IPv6-only run
#ENABLE_IPV4=true

# Optional: Customize IP providers
#IP_PROVIDER=http://ipinfo.io/ip
#IPV6_PROVIDER=http://v6.ipinfo.io/ip

With Cron

To run the script on a schedule, it can be set up as a cron job (e.g. every 30 minutes):

*/30 * * * * export USERNAME=username API_KEY=api_key DOMAIN=domain.com SUBDOMAIN=subdomain && /path/to/venv/bin/python3 /path/to/nfsn-ddns.py >> ~/nfsn-ddns.log 2>&1

Note: Use the full path to your virtualenv's python3 so cron can find the installed dependencies. The >> ~/nfsn-ddns.log 2>&1 part redirects output to a log file in your home directory.

With Docker

1. Set the configuration values in the script the way you want them (or create a file containing the environment variables)

2. Build the image with docker build -t nfs-dynamic-dns .

3. Run the image (production) with docker run -d --name nfsn-dynamic-dns nfs-dynamic-dns (add the --env-file <file> argument before the last nfsn-dynamic-dns if you want to use your environment variable file)

   Ex: docker run -d --name nfsn-dynamic-dns --env-file .env nfs-dynamic-dns

With Docker Compose

You can use the following config to run this with docker compose.

services:
  nfs-dynamic-dns:
    image: ghcr.io/mhum/nfs-dynamic-dns:latest
    container_name: nfs-dynamic-dns
    network_mode: host
    environment:
     - USERNAME=username
     - API_KEY=api_key
     - DOMAIN=domain.com
     - SUBDOMAIN=subdomain
    restart: unless-stopped

Development

To run the container locally (and let it run its cronjobs), use this command: docker run -it --rm --init nfs-dynamic-dns

to run the container locally and be put into a shell where you can run python3 ./nfsn-ddns.py yourself use this: docker run -it --rm --init nfs-dynamic-dns sh

If your setup uses environment variables, you will also need to add the --env-file argument (or specify variables individually with the -e docker flag). The --env-file option is for docker run and the env file format can be found here.

Docker

When using the Docker file, DDNS updates are scheduled to run every 30 minutes by default. This is configurable when building the container using build args.

Customizing Cron Schedules

You can customize the schedules using build args:

With docker:

# For DDNS updates (backwards compatible)
$ docker build --build-arg CRON_SCHEDULE="*/5 * * * *" -t nfs-dynamic-dns .

# Or use the new arg names
$ docker build --build-arg DDNS_CRON="*/5 * * * *" --build-arg CERT_CRON="0 2 * * *" -t nfs-dynamic-dns .

With docker compose:

services:
  nfs-dynamic-dns:
    image: nfs-dynamic-dns
    build:
      context: ./nfs-dynamic-dns
      args:
        - DDNS_CRON=*/5 * * * *
        - CERT_CRON=0 2 * * *
    container_name: nfs-dynamic-dns
...

Note: The CRON_SCHEDULE build arg is still supported for backwards compatibility and maps to DDNS_CRON.

ACME Certificate Management

This application can automatically issue and renew Let's Encrypt certificates using DNS-01 challenges via the NFSN DNS API.

Requirements for Certificate Management

• Set ENABLE_CERTS=true environment variable
• Ensure DOMAIN environment variable is set (certificates will be issued for $DOMAIN and *.$DOMAIN)
• Mount a volume to /certs to persist certificates outside the container
• Set LE_CONFIG_HOME=/acme-state and mount a volume there to persist acme.sh's renewal state

Note: mounting /certs alone is not enough. acme.sh keeps its account key and per-certificate config under /root/.acme.sh, which is lost whenever the container is recreated. The certificate files survive, but acme.sh no longer has any record of the certificate and the renewal cron silently stops renewing it — the certificate then expires with nothing logged as an error. Don't mount a volume over /root/.acme.sh itself; that path is also the acme.sh install directory, and mounting over it hides the acme.sh script and the dns_nfsn plugin.

Certificate Paths

Certificates are stored in /certs:

• Certificate (full chain): /certs/$DOMAIN.crt
• Private key: /certs/$DOMAIN.key

Renewal state is stored in /acme-state. It contains your ACME account key, so keep it out of version control.

Docker Example with Certificates

docker run -d \
  --name nfsn-dynamic-dns \
  --env-file .env \
  -e LE_CONFIG_HOME=/acme-state \
  -v /path/to/certs:/certs \
  -v /path/to/acme-state:/acme-state \
  nfs-dynamic-dns

Make sure your .env file includes:

ENABLE_CERTS=true

Docker Compose Example with Certificates

version: "3"

services:
  nfs-dynamic-dns:
    image: nfs-dynamic-dns
    build: ./nfs-dynamic-dns
    container_name: nfs-dynamic-dns
    network_mode: host
    environment:
      - USERNAME=username
      - API_KEY=api_key
      - DOMAIN=domain.com
      - SUBDOMAIN=subdomain
      - ENABLE_DDNS=true
      - ENABLE_CERTS=true
      - LE_CONFIG_HOME=/acme-state
    volumes:
      - ./certs:/certs
      - ./logs:/logs
      - ./acme-state:/acme-state
    restart: unless-stopped

Running Only Certificate Management (No DDNS)

To run only certificate issuing/renewal without DDNS:

docker run -d \
  --name nfsn-certs \
  -e USERNAME=username \
  -e API_KEY=api_key \
  -e DOMAIN=domain.com \
  -e ENABLE_DDNS=false \
  -e ENABLE_CERTS=true \
  -e LE_CONFIG_HOME=/acme-state \
  -v /path/to/certs:/certs \
  -v /path/to/acme-state:/acme-state \
  nfs-dynamic-dns

Manual Certificate Operations

To manually issue a certificate inside the container:

docker exec nfsn-dynamic-dns /root/.acme.sh/acme.sh --issue \
  -d domain.com -d "*.domain.com" \
  --dns dns_nfsn \
  --server letsencrypt \
  --fullchain-file /certs/domain.com.crt \
  --key-file /certs/domain.com.key \
  --home /root/.acme.sh

acme.sh defaults to ZeroSSL, so --server letsencrypt is needed to match what the entrypoint uses.

To force renewal:

docker exec nfsn-dynamic-dns /root/.acme.sh/acme.sh --renew \
  -d domain.com \
  --force \
  --ecc \
  --home /root/.acme.sh

Certificates are issued as ECDSA, so --ecc is needed when renewing by name.

Customizing Certificate Renewal Schedule

Both DDNS and certificate renewal schedules can be customized via environment variables:

environment:
  - DDNS_CRON=*/15 * * * *      # Check DDNS every 15 minutes
  - CERT_CRON=0 2 * * *         # Check renewal daily at 2 AM

Development

Install the test dependencies and run the suite:

pip install -r requirements-dev.txt
pytest

The tests run entirely offline — no NFSN credentials or network access needed.

Troubleshooting

The script communicates with NearlyFreeSpeech.NET via its RESTful API. Specifics about the API can be found here.