Upgrading

dnz --version
docker exec dnz dnz --version   # with Docker

Take a backup first

dnz backup run

sqlite3 /var/lib/dnz/dnz.db ".backup '/root/dnz-before-upgrade-$(date +%F).db'"

docker compose stop dnz
docker compose cp dnz:/data/dnz.db ./dnz-before-upgrade.db
docker compose cp dnz:/data/dnz.db-wal ./dnz-before-upgrade.db-wal 2>/dev/null || true

pg_dump -Fc dnz > dnz-before-upgrade-$(date +%F).dump
mysqldump --single-transaction dnz > dnz-before-upgrade-$(date +%F).sql

docker compose exec -T postgres pg_dump -U dnz -Fc dnz > dnz-before-upgrade-$(date +%F).dump

Upgrade

docker compose pull && docker compose up -d
docker compose logs -f dnz

curl -fsSL https://raw.githubusercontent.com/terrific-ci/dnz/main/install.sh | sh
sudo systemctl restart dnz
journalctl -u dnz -f

sudo install -m 755 dnz/dnz /usr/local/bin/dnz
sudo systemctl restart dnz

dnz --version
dnz healthcheck

A cluster

Going back

Breaking changes

v2.0.0

• The copy DNZ makes. Before dropping anything, DNZ copies a SQLite database (and the Redis backend’s local copy) to backups/before-cleanup-<time>.db in the folder of the database: /var/lib/dnz/backups/ with systemd, /data/backups/ in the Docker volume. With Postgres or MySQL, DNZ makes no copy: take a dump before upgrading.
• Going back. After this upgrade, going back to an older version needs that copy or your own backup (v1.27 could still go back to v1.26 without one); see Going back.
• Straight from v1.26 or older. Allowed: the proxy services are moved into upstreams first, as in v1.27.0 (below), then the old tables are dropped. DNZ makes one copy before both, backups/before-upstreams-<time>.db. Check the proxies on a copy of the database before upgrading, as v1.27.0 describes, with the new version’s image.
• Middlewares and firewalls are every proxy’s. Each proxy’s middlewares, firewalls and TCP middlewares are merged once into one list, Proxy → Middlewares. The same name with other settings on another proxy is renamed after that proxy (office-edge2): a Traefik’s own routers (Docker labels, files) naming dnz-office@http there must name dnz-office-edge2@http. DNZ copies a SQLite database (and the Redis backend’s local copy) to backups/before-v2-<time>.db first. See From per-proxy middlewares.
• Transports become an upstream’s connection settings. An upstream that proxies connected to differently is split (<upstream>-<proxy>), and Caddy proxies start applying an upstream’s connection settings. See From per-proxy transports.
• Sites in DNS becomes read-only proxies. Every Caddy and Traefik under Settings → Proxy → Sites in DNS becomes a read-only proxy with the same settings (API and password, addresses or CNAME, TTL, read interval, add only, paused, division) and the same records, which it keeps managing. It keeps its name, or becomes <name>-sites when a proxy already has that name. Records lose the caddy_id, origin_port and origin_https fields. dnz caddy is now dnz proxy sites, and the API moved from /api/divisions/{id}/caddies and /api/caddies/{id} to /api/proxy-sites and /api/proxies/{id}/sites. See Upgrading from v1.
• Metrics renamed. dnz_caddy_sync_success and dnz_caddy_sync_timestamp_seconds are now dnz_proxy_sites_sync_success and dnz_proxy_sites_sync_timestamp_seconds, labelled proxy and kind. The old names are still exported for one release: move dashboards and alerts to the new ones. See Prometheus.
• Check first. dnz proxy advanced-check --database <copy>, run with the new version’s image on a copy of the database, lists every merge, rename and split before you upgrade, and each Caddy and Traefik of Sites in DNS with the read-only proxy it becomes (see Checking a proxy setup).
• Proxy YAML. Exports are version: 2 and hold TCP and UDP routes and each upstream’s connection settings. Version-1 files still apply; one naming a middleware or upstream the upgrade renamed is refused with the new name. See Configuration as code.
• API. /api/proxies/{id}/services is gone (v1.27 answered 410 Gone). Use /api/proxy/upstreams instead. /api/proxies/{id}/middlewares answers 410 Gone too: use /api/proxy/middlewares.
• Certificate checks per server. An upstream’s accept any certificate switch moves onto each of its HTTPS servers (Skip TLS verification on the server’s badge, skip_tls_verify on each server in the API and proxy YAML), so nothing changes for visitors. Skipping it per server is DNZ Proxy only: on Traefik and Caddy, an upstream mixing servers that skip the check with servers that don’t has every server’s certificate checked, with a warning on the proxy page. See Certificate checks per server.
• CLI. dnz proxy middlewares add|edit, dnz notify add|set and dnz backup targets add|set take their settings with --settings instead of --config (it clashed with the config file flag -c/--config). dnz dhcp leases --search is -q for short, no longer -s. List commands that page print the API’s page with --json ({zones, total, page, per_page} and so on) instead of a bare array, and dnz proxy routes list --json prints rows with each proxy’s copy in entries: scripts reading the old shapes need updating.
• From v1.15 or older. The server loses the query log those versions kept in the main database: it is dropped during the upgrade, in one step, with nothing to wait for (v1.16 and later keep the query log in day files). See Upgrading to the day files.

docker compose cp dnz:/data/backups/ ./dnz-backups/
ls ./dnz-backups

v1.27.0

• DNZ copied a SQLite database to backups/before-upstreams-<time>.db next to it before the move. With Postgres or MySQL, take a dump before upgrading.
• The proxy page’s Advanced tab is gone. To see before upgrading which routes hold settings only the proxy’s YAML can change, check a copy of the database with the new version (read-only; the running server isn’t touched):
  mkdir -p ~/dnz-check
  docker cp dnz:/data/dnz.db ~/dnz-check/
  docker cp dnz:/data/dnz.db-wal ~/dnz-check/ 2>/dev/null || true
  docker run --rm --user "$(id -u):$(id -g)" -v ~/dnz-check:/check terrificci/dnz:1.27.0 \
    proxy advanced-check --database /check/dnz.db
  
  Without Docker:
  dnz proxy advanced-check --database ./dnz-backup.db
  
  --database also takes a postgres:// or mysql:// URL of a restored copy. See Checking a proxy setup.
• /api/proxies/{id}/services answers 410 Gone: use /api/proxy/upstreams.
• Going back to v1.26 still works.

v1.16.0