Guide

Upgrades, backups, and moving in

Keep TelltaleDNS current, keep a copy of everything you set up, move it to a new machine, and bring your settings over from Pi-hole or Technitium.

• Your version and channel
• Update checks
• Upgrade
• Upgrade a cluster
• Back up
• Restore on a new machine
• Move in from Pi-hole or Technitium
• Troubleshooting

Your version and channel

Every build says exactly what it is, the same way on every architecture:

$ telltale --version
telltale 0.1.0-edge.64 (commit 3f46fd4, built 2026-10-05T12:00:00Z, channel edge, aarch64-unknown-linux-musl)

• Releases are 0.1.0. Builds of main (the edge channel) are 0.1.0-edge.<run>. A local build is dev with its commit.
• Where else it shows: the web UI's sidebar, Settings → System → Version and updates (with how the node was installed: native, container, or helm), GET /api/v1/system/info (build and update), the metric telltale_build_info{version,commit,channel,target}, and the Cluster page for every node.

Each install type picks its channel its own way:

The edge channel publishes several builds a day.

Update checks

Each node checks for a newer build of its channel by itself. Nothing is installed: TelltaleDNS never updates itself from the UI.

• When: a minute after the node starts, then every 24 hours (an hour after a failed check).
• How: the node reads its channel's releases.json, which is published with every release and signed with the release key. An index whose signature doesn't verify is ignored.
• The result is up_to_date, available, newer (a dev build), or unknown (not checked yet, or failing).
• Where it shows: an update pill next to the version in the sidebar, the Version and updates panel (with the step for your install), each node's version on the Cluster page, and telltale_update_available (1 when an update exists).

To look now, an admin clicks Check now under Settings → System → Version and updates (or POST /api/v1/system/update-check). Clicks less than a minute apart show the last result without fetching again.

Upgrade

The Version and updates panel shows the step for your install. Here are all three.

sudo telltale self-update --check                 # only look
sudo telltale self-update --restart               # upgrade and restart
sudo telltale self-update --channel edge --restart  # builds from main

docker compose pull && docker compose up -d

helm upgrade telltale oci://ghcr.io/paimonsoror/charts/telltale --version <version> \
  -n telltale -f my-values.yaml

Upgrade a cluster

1. Upgrade one node at a time, the replicas first. DNS keeps answering throughout if your clients have two DNS servers (each node is one).
2. Upgrade the primary last.
3. Check the Cluster page. Its versions check lists the mix of versions until the last node is upgraded.

• A half-upgraded cluster is fine. Versions one cluster protocol apart work together (N and N−1, either way round).
• A replica older than its primary keeps working, unless the primary starts using settings the older version doesn't know. Then the replica keeps serving its last version, and its sync status says to upgrade it.

More in Build a cluster and the cluster docs.

Back up

A backup is one file. Make one before a big change, and whenever you'd hate to set things up again.

• In the web UI: an admin clicks Settings → System → Download a backup.
• Through the API: GET /api/v1/backup.
• On the server, safe while TelltaleDNS runs:

telltale backup create -o pi.ttbk                 # settings, users, history
telltale backup create --include-qlog -o pi.ttbk  # also the query log (can be large)
telltale backup show pi.ttbk                      # check it and list what's in it

Downloads from the UI and API leave out the query log; use the command for that. Each download is recorded in the audit log as backup.create.

Restore on a new machine

1. Install TelltaleDNS on the new machine (see Get started), and copy the backup file to it.
2. Stop TelltaleDNS there. Restore refuses while TelltaleDNS runs on that data directory, because it can't take the directory's lock.
3. Restore:

   telltale backup restore pi.ttbk

   Every file is checked before anything is written, so a damaged or truncated backup changes nothing. Existing files are only replaced with --force (the installer writes a starter config, so a fresh install already has one).
4. Start TelltaleDNS and sign in again. Lists are downloaded and compiled again.
5. Point your router's DHCP DNS setting at the new machine.

• Where files go: data goes back to the directory it came from, or --data-dir; config files go back where they were, or --config-dir.
• A different data directory? The restored config still names the old one. Restore says so; set data_dir (or add a small file that does).
• Running it as root is fine: files are given the data directory's owner, so the telltale service user can read them.
• A cluster member starts on its own after a restore: run telltale cluster init, or join it again (Build a cluster).

Details: Backups and moving to a new machine.

Move in from Pi-hole or Technitium

Pi-hole and Technitium DNS Server are the projects that inspired TelltaleDNS, and the importers bring the setup you built there along with you. Each one writes a TelltaleDNS config file and checks that it loads before writing it. The short version is on Get started.

telltale import pihole PATH -o pihole.toml

TECHNITIUM_TOKEN=… telltale import technitium http://192.168.1.2:5380 -o technitium.toml

Zone files from any DNS server (Technitium's Zones → Export Zone, BIND, PowerDNS) become [[record]] entries for your config:

telltale import zone exported.zone > records.toml

The header lists anything with no local equivalent; SOA and NS aren't needed. Names under the zone that you don't import still resolve normally, so a split-horizon domain keeps working. Keep your old server running until TelltaleDNS answers the way you expect, then point your router at TelltaleDNS.

Troubleshooting