= zone-sync(8)

== NAME
zone-sync - Keeps DNS zone files in sync with a primary

== SYNOPSIS
[verse]
`zone-sync --primary HOSTNAME [OPTIONS...] ZONE [ZONE...]`

== DESCRIPTION
`zone-sync` fetches DNS zones from a primary by zone transfer and stores
them as zone files, so that they can be used by anything that reads zone
files, for example to load Response Policy Zones (RPZ) into a resolver.

Every zone is being stored in a file of its own in the zone directory,
which is named after the zone (e.g. 'example.org.zone'). The name of
the file is always in lowercase and has no trailing dot, no matter how
the zone has been written on the command line.

If there is a zone file already, `zone-sync` asks the primary for the
changes since the serial of that zone (IXFR). If the zone is up to date,
the primary only responds with its SOA record and nothing is being
transferred. If the primary cannot send the changes, it sends the entire
zone. If there is no zone file, or if the zone file cannot be loaded,
the entire zone is being transferred (AXFR).

The zone file is being replaced atomically after a successful transfer,
so that anything that is reading it never sees a partially written zone.

`zone-sync` exits once all zones have been processed. It is meant to be
run periodically, e.g. by a systemd timer or by cron.

== OPTIONS

--primary HOSTNAME::
	The hostname or IP address of the primary to fetch the zones from.
	This option is mandatory.
	+
	If the hostname resolves to more than one address, all of them are
	being tried in order until a transfer succeeds.

--port PORT::
	The port of the primary. The default is 53, or 853 with '--secure'.

--secure::
	Transfers the zones over TLS (XFR-over-TLS). The certificate of the
	primary is being verified against the system's certificate store and
	must be valid for the hostname that has been passed with '--primary'.

--path PATH::
	The directory where the zone files are being stored.
	The default is '/var/lib/zone-sync'.

--parallel N::
	The number of zones that are being processed at the same time.
	The default is 1, and 0 means no limit.

--debug::
	Logs a lot more about what is happening.

--quiet::
	Only logs errors.

--help::
	Shows a short help text and exits.

--version::
	Shows the version and exits.

== FILES

'/var/lib/zone-sync/ZONE.zone'::
	The zone file of each zone.

'/var/lib/zone-sync/ZONE.zone.jnl'::
	The journal of an incremental transfer. It only exists while the
	transfer is running, or if the zone file could not be written.

== EXIT STATUS
`zone-sync` exits with 0 if all zones have been transferred successfully
or have been up to date, and with 1 if anything has failed. A failure of
one zone does not stop the other zones from being processed.

== EXAMPLES

Fetch two zones over TLS and store them in the default directory:

	zone-sync --primary primary.example.org --secure \
		malware.rpz.example.org phishing.rpz.example.org

Fetch a zone from a primary that is listening on a different port:

	zone-sync --primary 192.0.2.1 --port 5353 --path /tmp/zones example.org

== BUGS
Please report all bugs to the IPFire Bugzilla at
https://bugzilla.ipfire.org/enter_bug.cgi?product=zone-sync.

== AUTHORS
Michael Tremer
