No description
  • Python 95.6%
  • Dockerfile 4.4%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
André Keller a294823490
All checks were successful
Build container image / Build zonesync image (push) Successful in 17s
Use zonefile names in log messages
Display zonefile names instead of temporary workspace paths in
normalization, validation, and synchronization messages.

Preserve full paths in debug transfer logs and external tool output
where they remain useful for troubleshooting.
2026-11-13 20:32:43 +01:00
.forgejo/workflows Add forgejo workflow 2026-11-13 19:12:14 +01:00
zonesync Use zonefile names in log messages 2026-11-13 20:32:43 +01:00
.gitignore Initial release 2025-11-16 01:11:20 +01:00
CHANGELOG.md 1.0.0 release 2025-11-16 01:30:19 +01:00
Dockerfile Add forgejo workflow 2026-11-13 19:12:14 +01:00
LICENSE Initialize repository 2025-11-16 01:01:01 +01:00
pyproject.toml Initial release 2025-11-16 01:11:20 +01:00
README.md Initial release 2025-11-16 01:11:20 +01:00

Zone Synchronization Tool

This repository provides a Python-based zone file synchronizer for a hidden-master DNS setup (Knot DNS). It fetches the current zones from the hidden master, normalizes them, compares them against local copies, updates serials, validates the result and pushes changed zones back to the hidden master.

The tool is implemented as a Python package called zonesync and exposes a CLI command called zone-sync.


Features

  • Hidden-master zone synchronization for Knot DNS
  • Serial auto-management using a SERIALAUTOUPDATE marker
  • Syntax validation via named-checkzone
  • RFC 1982 serial arithmetic
  • DNS-based serial checks
  • Optional SSH host key pinning
  • Dry-run mode
  • Docker image for consistent execution

Requirements

Python

  • Python 3.12+

Python dependencies

Automatically installed via pip:

  • paramiko
  • dnspython

System packages

The tool requires named-checkzone.

Debian/Ubuntu

python3
python3-pip
python3-paramiko
python3-dns
bind9utils      # provides named-checkzone
ca-certificates

Alpine Linux (Docker image)

The Docker image is based on Alpine Linux and uses system Python packages rather than pip-installed ones. The image contains:

python3
py3-paramiko
py3-dnspython
bind-tools      # provides named-checkzone
ca-certificates
bash
iputils-ping
openssh-client-default

A minimal Python virtual environment is created at build time, but it only contains the zonesync package itself. All dependencies (paramiko, dnspython, etc.) are provided by Alpine’s system packages, not by pip.


Installation

From source

git clone git@code.peer42.net:tools/zonesync.git
cd zonesync
python3 -m pip install .

This installs:

  • The zonesync package
  • The CLI command zone-sync

Docker

Build the image (tag name is arbitrary, here we use zonesync):

docker build -t zonesync .

Run the synchronizer (the container entrypoint is the zone-sync CLI):

docker run --rm \
  -v "$PWD/zones:/zones" \
  -e HIDDEN_MASTER_HOST=ns-hidden-master.example.com \
  -e SSH_USERNAME=zone_ssh \
  -e SFTP_USERNAME=zone_sftp \
  -e SSH_PRIVATE_KEY_B64="$(base64 -w0 id_ed25519_zone_sync)" \
  zonesync \
  --dry-run

In this example:

  • zonesync is the Docker image name
  • zone-sync is the CLI command executed inside the container (as the container entrypoint)

Configuration

All configuration options can be provided via environment variables and/or CLI arguments, CLI arguments take precedence.


Required settings

Hidden master

  • HIDDEN_MASTER_HOST / --hidden-master-host Hostname or IP address of the hidden master.

SSH users and keys

  • SSH_USERNAME / --ssh-username SSH user used to run knotc.

  • SFTP_USERNAME / --sftp-username SFTP user used to transfer zone files.

  • SSH_PRIVATE_KEY / --ssh-private-key Path to SSH private key file.

  • SSH_PRIVATE_KEY_B64 / --ssh-private-key-b64 Base64-encoded private key content (for example a PEM file encoded with base64). Mutually exclusive with SSH_PRIVATE_KEY / --ssh-private-key.

Optional host key pinning

  • SSH_PUBLIC_HOST_KEY / --ssh-public-host-key Path to a file containing the server’s host key in known_hosts format.

  • SSH_PUBLIC_HOST_KEY_B64 / --ssh-public-host-key-b64 Base64-encoded known_hosts entry for the hidden master’s host key. Mutually exclusive with SSH_PUBLIC_HOST_KEY / --ssh-public-host-key.


Other settings

  • LOCAL_ZONES_DIRECTORY / --local-zones-directory Directory containing local zone files. Default: current working directory.

  • REMOTE_ZONES_ROOT / --remote-zones-root Remote directory containing zone files. Default: zones.

  • DRY_RUN / --dry-run Boolean (true/false, 1/0, etc.). Do not write anything to the hidden master.

  • VERBOSE / --verbose Enable verbose/diagnostic logging.

  • --no-color Disable ANSI colors (CLI only).


Usage

Local

zone-sync --dry-run --verbose

or:

python -m zonesync --dry-run --verbose

Available CLI options:

--hidden-master-host         (or HIDDEN_MASTER_HOST)
--ssh-username               (or SSH_USERNAME)
--sftp-username              (or SFTP_USERNAME)
--ssh-private-key            (or SSH_PRIVATE_KEY)
--ssh-private-key-b64        (or SSH_PRIVATE_KEY_B64)
--ssh-public-host-key        (or SSH_PUBLIC_HOST_KEY)
--ssh-public-host-key-b64    (or SSH_PUBLIC_HOST_KEY_B64)
--local-zones-directory      (or LOCAL_ZONES_DIRECTORY)
--remote-zones-root          (or REMOTE_ZONES_ROOT)
--dry-run                    (or DRY_RUN)
--verbose                    (or VERBOSE)
--no-color

Docker

Dry-run example:

docker run --rm \
  -v "$PWD/zones:/zones" \
  -e HIDDEN_MASTER_HOST=ns.example.com \
  -e SSH_USERNAME=zone_ssh \
  -e SFTP_USERNAME=zone_sftp \
  -e SSH_PRIVATE_KEY_B64="$(base64 -w0 id_ed25519_zone_sync)" \
  zonesync \
  --dry-run

Without --dry-run:

docker run --rm \
  -v "$PWD/zones:/zones" \
  -e HIDDEN_MASTER_HOST=ns.example.com \
  -e SSH_USERNAME=zone_ssh \
  -e SFTP_USERNAME=zone_sftp \
  -e SSH_PRIVATE_KEY_B64="$(base64 -w0 id_ed25519_zone_sync)" \
  zonesync

How it works (overview)

  1. Fetch remote zones via SFTP into a temporary workspace
  2. Normalize zones (reset auto-managed serial lines)
  3. Diff normalized local vs remote zones
  4. Increment serials for changed zones using UNIX timestamp
  5. Validate using named-checkzone + DNS SOA lookup
  6. Upload & reload changed zones via SFTP + knotc zone-reload
  7. Cleanup zones removed locally

License

MIT


Notes

  • The hidden master must allow:
    • SFTP access as SFTP_USERNAME
    • Restricted SSH access as SSH_USERNAME to run knotc
  • Dry-run mode is recommended when testing changes.
  • The Docker image relies on Alpine Linux for Python dependencies. The virtual environment included in the image only contains the zonesync package itself; all other Python modules come from system packages.