No description
  • Python 85.5%
  • Nix 14.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Benjamin Hanzelmann d4eb0b3e4a
All checks were successful
test / Flake checks (push) Successful in 15s
Choose the prefix with the longest preferred lifetime
2026-10-31 17:35:45 +01:00
.forgejo/workflows Push CI builds to the Attic cache 2026-10-11 17:26:06 +02:00
hetzner_dyndns Choose the prefix with the longest preferred lifetime 2026-10-31 17:35:45 +01:00
tests Choose the prefix with the longest preferred lifetime 2026-10-31 17:35:45 +01:00
.envrc initial version 2024-01-02 10:34:54 +01:00
.gitignore Set up flake to build hddns 2024-12-28 00:39:44 +01:00
default.nix Choose the prefix with the longest preferred lifetime 2026-10-31 17:35:45 +01:00
flake.lock Use hcloud library for DNS updates 2026-05-01 17:52:47 +02:00
flake.nix Run tests in nix flake check and on Forgejo Actions 2026-10-11 17:14:48 +02:00
module.nix Release 0.6.0 2026-10-31 17:33:06 +01:00
Pipfile Update Pipfile to Python 3.13 and current dependencies 2026-10-11 17:06:57 +02:00
Pipfile.lock Update Pipfile to Python 3.13 and current dependencies 2026-10-11 17:06:57 +02:00
pyproject.toml Release 0.6.0 2026-10-31 17:33:06 +01:00
README.md Choose the prefix with the longest preferred lifetime 2026-10-31 17:35:45 +01:00
renovate.json Add renovate.json 2026-10-11 15:45:49 +00:00
requirements.txt Use hcloud library for DNS updates 2026-05-01 17:52:47 +02:00

hetzner-dyndns

Point a Hetzner DNS A record at this machine's current public IPv4 address, and optionally AAAA records of several names at this machine's IPv6 prefix plus a fixed interface ID each.

Config

The config file is taken from, in order:

  1. --config PATH
  2. the HDDNS_CONFIG environment variable
  3. ~/.config/local-tooling/config.ini, /usr/local/etc/hetzner-dyndns.ini or /etc/hetzner-dyndns.ini

An explicitly given file (1 or 2) that is missing or has no [hetzner-dyndns] section is an error; there is no fallback to the default locations.

Example:

[hetzner-dyndns]
token=<hetzner cloud api token>
zone_name=example.com
record_name=home
; optional
ipinfo_token=
; optional, both or none
aaaa_interface=eth0
aaaa_records=host-a=::10,host-b=::20

The IPv4 address comes from ipinfo, asked over IPv4 only. With aaaa_interface and aaaa_records, every listed name in zone_name gets an AAAA record: the /64 of the first global address on aaaa_interface (from ip -j -6 addr; no ULA, temporary or deprecated address, and of several the one with the longest preferred lifetime, which is the newest prefix during a change) plus the name's interface ID, e.g. 2001:db8:0:1::10 for host-a=::10. Other machines in the same /64 can be listed, so one machine keeps the records of a whole LAN. Without a usable global address, the A record is still updated, the AAAA records are left alone and hddns exits with 1.

Run once

nix run .#hetzner-dyndns

Without Nix: pip install . && hddns.

NixOS

The flake provides a module that runs hddns from a systemd timer:

{
  inputs.hetzner-dyndns.url = "git+https://git.nabcos.de/nabcos/hetzner-dyndns";

  outputs = { nixpkgs, hetzner-dyndns, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      modules = [
        hetzner-dyndns.nixosModules.default
        {
          services.hetzner-dyndns = {
            enable = true;
            configFile = "/run/secrets/hetzner-dyndns.ini";
          };
        }
      ];
    };
  };
}

Options:

  • configFile (required): path to the config file. The service reads it via systemd LoadCredential, so it can stay readable by root only. Give it as a string so it is not copied into the Nix store.
  • interval: systemd OnCalendar expression, default *:0/5.
  • quiet: pass --quiet, default true.
  • package: the package to run.

The service runs with DynamicUser and keeps its state in /var/lib/hetzner-dyndns.

Options

  • -q, --quiet: only log errors.
  • -c, --config PATH: config file to use (see above).
  • -f, --force: ignore the state file and always check Hetzner.

State

After Hetzner confirms the records, hddns stores the IP in last_ip.json together with the zone, the record name and the AAAA values. On the next run, if the IP from ipinfo, the AAAA values and the configured zone and record are unchanged, Hetzner is not contacted at all. Use --force if the records were changed elsewhere.

The state file lives in $STATE_DIRECTORY (set by systemd's StateDirectory=), otherwise in $XDG_STATE_HOME/hetzner-dyndns/ or ~/.local/state/hetzner-dyndns/. A missing or broken state file only means Hetzner gets checked again.