dnsleaf

Workspace-driven Cloudflare DDNS for Linux, primarily Proxmox VE hosts. Requires Python 3.11+. Each entry publishes IPv4, IPv6, or both from a PVE LXC guest, a PVE VM guest agent, the local host, or explicit static addresses. A oneshot sync and a system-level systemd timer handle periodic updates. Cloudflare is the only supported provider.

1.4.0 is pending release. The public PyPI installation commands below apply after publication. For this pending version, install the reviewed wheel with the same uv tool install command.

Install the Python tool

Use uv for a persistent, isolated installation. For PVE system services, run these commands in a root shell with uv available:

uv tool install --python 3.11 dnsleaf
DNSLEAF="$(uv tool dir --bin)/dnsleaf"
"$DNSLEAF" --version
"$DNSLEAF" --help

For pre-release review, replace dnsleaf in the install command with the absolute path to dnsleaf-1.4.0-py3-none-any.whl. Installing the package creates a CLI; it does not install a timer or synchronize DNS. Keep this tool environment and its Python interpreter installed for the timer. The module entrypoint is python -m dnsleaf when that Python environment contains the package.

Unprivileged users can initialize and validate writable workspaces, and sync local/static entries when credentials and state are accessible. PVE guest discovery requires host privileges. apply and uninstall require root. From a non-root shell, use explicit sudo with the absolute installed entry, for example sudo /absolute/path/to/dnsleaf apply --workspace /etc/dnsleaf/example-zone. The tool never elevates itself.

Create and configure a workspace

In the same root shell:

"$DNSLEAF" init /etc/dnsleaf/example-zone
chmod 700 /etc/dnsleaf/example-zone
install -m 600 /dev/null /etc/dnsleaf/example-zone/secrets/cloudflare_api_token.txt

Put your Cloudflare API token in that file using your editor. Restrict it to the intended zone and grant the DNS permissions needed for record reads and edits; zone lookup by name also needs zone read access. Never put the token in YAML, commands, Git, or shared reports.

Edit /etc/dnsleaf/example-zone/workspace.yaml: set zone_name, optionally zone_id, and keep api_token_file pointing to the token file. Its relative path is based on the workspace directory. The generated YAML contains the packaged defaults; partial overrides are also supported. See configuration for schema 5 and all settings.

Add entries with the CLI, or edit entries.yaml (schema 3):

"$DNSLEAF" entry add lxc --workspace /etc/dnsleaf/example-zone \
  --id 101 --fqdn web.example.com --name web --family both
"$DNSLEAF" entry add vm --workspace /etc/dnsleaf/example-zone \
  --id 201 --fqdn vm.example.com --name vm --family ipv6
"$DNSLEAF" entry add local --workspace /etc/dnsleaf/example-zone \
  --fqdn host.example.com --name host --family both
"$DNSLEAF" entry add static --workspace /etc/dnsleaf/example-zone \
  --fqdn edge.example.com --name edge --family both \
  --ipv4 192.0.2.10 --ipv6 2001:db8::10

These names, guest IDs, and static documentation addresses are placeholders: use your own values. LXC discovery uses pct exec; VM discovery supports Linux and Windows through a working standard QEMU guest agent; local discovery uses ip. The default selection policy is unchanged. Windows Guests with multiple plausible IPv6 addresses can use --selection-policy require-dhcpv6 --evidence windows-powershell on entry add vm, entry update, or discover vm. The policy requires proven DHCPv6 eligibility; the evidence setting separately permits the fixed read-only PowerShell probe through qm guest exec. A working network-interface query alone is insufficient. Exact VM-ID source defaults may supply either field. Default selection never probes, even when evidence permission is inherited. See discovery for prerequisites and refusal behavior, and entry management.

Find an existing workspace

Existing dnsleaf deployments keep their directories; 1.4.0 requires replacement source configuration but no relocation or reinitialization. Select with --workspace / -w (including explicit .), then a non-empty DNSLEAF_WORKSPACE, or let dnsleaf search automatically. Automatic bases are the current directory, its ancestors nearest to farthest including /, then home if not already visited. Each base checks its immediate child directories in lexicographic order before the base itself. The first directory with readable regular workspace.yaml and entries.yaml files wins; there is no sibling ambiguity error.

Search is one level only. From a home containing ddns-config/ and dnsleaf-backups/backup-2026-09-17/, the nested backup is not inspected. A complete backup placed directly among searched siblings is a normal candidate; use --workspace to choose a particular one.

Partial candidates warn on stderr and search continues. A complete candidate with invalid YAML, schema, or relevant runtime references fails without fallback. Explicit paths and environment paths are authoritative. See configuration for diagnostics.

Validate, plan, and synchronize

"$DNSLEAF" validate --workspace /etc/dnsleaf/example-zone
"$DNSLEAF" plan --workspace /etc/dnsleaf/example-zone
"$DNSLEAF" sync-once --workspace /etc/dnsleaf/example-zone --apply

validate checks local configuration and token readability without API calls. plan and sync-once without --apply read Cloudflare state and discover addresses, but never change DNS. sync-once --apply performs one immediate sync. These commands may write workspace logs.

IPv4 and IPv6 are handled independently. Missing or ambiguous addresses are skipped without publishing guesses or deleting existing records. default_ttl: auto uses Cloudflare automatic TTL; default_proxied: null preserves existing proxy settings. Entry overrides may set true or false. Enabled entries must own distinct FQDN + record type targets (case and trailing dots are ignored). Each sync queries a dynamic source once, sharing its raw snapshot across node/service names and families. Address-discovery commands have a package-default 30-second timeout. Prune is off by default; explicit --prune-managed only removes stale records tracked by this workspace. Unmanaged zone records are preserved. See DNS sync.

Install the timer

"$DNSLEAF" apply --workspace /etc/dnsleaf/example-zone --no-run-sync
"$DNSLEAF" status --workspace /etc/dnsleaf/example-zone
systemctl status dnsleaf-example-zone.timer
journalctl -u dnsleaf-example-zone.service

apply validates and renders the workspace, installs system units, then enables and restarts the timer. --no-run-sync skips the command's immediate sync; the enabled timer will still run on its schedule. render only writes local generated artifacts. The service uses the absolute Python from the environment that ran apply, followed by -m dnsleaf, so its entry does not depend on an interactive shell's PATH or a development checkout. See systemd.

Workspace files are separated by purpose:

Upgrade and uninstall

1.4.0 intentionally removes the windows-dhcpv6 preset and accepts only the new source configuration schemas: workspace 5 and entries 3. This is a breaking configuration change. Prepare and validate both replacement source files with the reviewed package before deployment. An operator must pause the scheduler and coordinate package/config replacement, validate and inspect a dry-run, then resume it. Do not blindly upgrade only the package. See the 1.4.0 operator procedure.

Keep credentials, paths, managed-record/last-apply state, and installed unit names. No state reset, workspace purge or unit reinstall is needed when the interpreter/workspace paths remain the same. If those paths change independently, explicitly refresh the units using the intended interpreter.

Remove the local service installation before uninstalling the Python tool:

"$DNSLEAF" uninstall --workspace /etc/dnsleaf/example-zone
uv tool uninstall dnsleaf

Repeat local service removal for every installed workspace before removing the tool environment. Normal uninstall retains configuration, credentials, and state. To explicitly delete a workspace, use uninstall --purge while the tool is still installed. Neither form deletes remote DNS records. A stop/disable failure aborts cleanup and returns failure.

Development and release

make sync
make check
make build

See development, architecture, release preparation, 1.4.0 notes, and CHANGELOG. Author: eserie-fox. License: MIT.