- Python 95.6%
- Dockerfile 4.4%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
All checks were successful
Build container image / Build zonesync image (push) Successful in 17s
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. |
||
| .forgejo/workflows | ||
| zonesync | ||
| .gitignore | ||
| CHANGELOG.md | ||
| Dockerfile | ||
| LICENSE | ||
| pyproject.toml | ||
| README.md | ||
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
SERIALAUTOUPDATEmarker - 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:
paramikodnspython
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
zonesyncpackage - 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:
zonesyncis the Docker image namezone-syncis 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-hostHostname or IP address of the hidden master.
SSH users and keys
-
SSH_USERNAME/--ssh-usernameSSH user used to runknotc. -
SFTP_USERNAME/--sftp-usernameSFTP user used to transfer zone files. -
SSH_PRIVATE_KEY/--ssh-private-keyPath to SSH private key file. -
SSH_PRIVATE_KEY_B64/--ssh-private-key-b64Base64-encoded private key content (for example a PEM file encoded withbase64). Mutually exclusive withSSH_PRIVATE_KEY/--ssh-private-key.
Optional host key pinning
-
SSH_PUBLIC_HOST_KEY/--ssh-public-host-keyPath to a file containing the server’s host key inknown_hostsformat. -
SSH_PUBLIC_HOST_KEY_B64/--ssh-public-host-key-b64Base64-encodedknown_hostsentry for the hidden master’s host key. Mutually exclusive withSSH_PUBLIC_HOST_KEY/--ssh-public-host-key.
Other settings
-
LOCAL_ZONES_DIRECTORY/--local-zones-directoryDirectory containing local zone files. Default: current working directory. -
REMOTE_ZONES_ROOT/--remote-zones-rootRemote directory containing zone files. Default:zones. -
DRY_RUN/--dry-runBoolean (true/false,1/0, etc.). Do not write anything to the hidden master. -
VERBOSE/--verboseEnable verbose/diagnostic logging. -
--no-colorDisable 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)
- Fetch remote zones via SFTP into a temporary workspace
- Normalize zones (reset auto-managed serial lines)
- Diff normalized local vs remote zones
- Increment serials for changed zones using UNIX timestamp
- Validate using
named-checkzone+ DNS SOA lookup - Upload & reload changed zones via SFTP +
knotc zone-reload - Cleanup zones removed locally
License
MIT
Notes
- The hidden master must allow:
- SFTP access as
SFTP_USERNAME - Restricted SSH access as
SSH_USERNAMEto runknotc
- SFTP access as
- 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
zonesyncpackage itself; all other Python modules come from system packages.