Skip to content

Migrating from 0.3 to 0.4

dnspatch is v0.x: the configuration format and the plugin API may change between minor versions. This page lists what breaks in 0.4 and how to adapt.

Four things need attention: the Go module path, the import paths of the built-in plugins, a container with a read-only filesystem, and the name of the example configuration. A configuration file that worked on 0.3 works on 0.4 unchanged, and the Retriever and Provider interfaces are the same. Everything else in 0.4 is additive.

Go module path

The repository moved to the dnspatch organisation, and the module path with it: github.com/KrimsN/dnspatch is now github.com/dnspatch/dnspatch. Versions up to 0.3.2 stay under the old path, so the change is only visible when you move to 0.4. It affects Go code that imports plugin/ (a plugin in its own module, a program that embeds dnspatch) and anyone who installs with go install.

Before:

import "github.com/KrimsN/dnspatch/plugin"

After:

import "github.com/dnspatch/dnspatch/plugin"

In a module that depends on dnspatch, replace the path everywhere and let Go fetch the new one:

grep -rl 'github.com/KrimsN/dnspatch' --include='*.go' . | xargs sed -i 's#github.com/KrimsN/dnspatch#github.com/dnspatch/dnspatch#g'
go mod edit -droprequire github.com/KrimsN/dnspatch
go get github.com/dnspatch/dnspatch@v0.4.0
go mod tidy

To install the daemon from source:

go install github.com/dnspatch/dnspatch/cmd/dnspatch@v0.4.0

The container image keeps its name on Docker Hub, krimsn/dnspatch, and is mirrored to ghcr.io/dnspatch/dnspatch under the same tags. Nothing changes for anyone who only pulls the image or downloads a release archive.

Import paths of the built-in plugins

The built-in plugins moved from a flat plugins/<name> to plugins/<kind>/<name>, where the kind is providers, retrievers or notifiers. This only matters to Go code that imports a built-in plugin directly, such as the main of a custom build.

Before:

import _ "github.com/KrimsN/dnspatch/plugins/cloudflare"

After:

import _ "github.com/dnspatch/dnspatch/plugins/providers/cloudflare"

Build tags and the type names in the configuration are unchanged. A plugin that lives outside the repository needs no other change: the plugin package re-exports the whole public API, and a plugin imports nothing but it.

Docker: a read-only filesystem needs /tmp

The image now runs dnspatch healthcheck as its HEALTHCHECK. The daemon writes a status file per instance on every completed cycle, by default under $TMPDIR/dnspatch-health. If you run the container with read_only: true, those writes fail, the check reports the daemon as stuck, and the container is marked unhealthy even though the DNS updates keep working. Orchestrators that restart an unhealthy container will restart it.

Give the daemon a writable place, as the compose.yml of the repository does:

services:
  dnspatch:
    read_only: true
    tmpfs:
      - /tmp

To keep the files somewhere else, point DNSPATCH_HEALTH_DIR at a writable path. See Monitoring.

The example configuration is renamed

config.toml.example is now dnspatch.toml.example. A running installation is not affected; update a script or an instruction that copies the file:

cp dnspatch.toml.example dnspatch.toml

The full build: needed only for the new features

Two features exist only in the full build: ping_url on an instance and the [notify.<name>] notifiers. They are new in 0.4, so no configuration written for 0.3 uses them. The lightweight build, which is what latest and the plain tags give, rejects a configuration that does:

instance "home": ping_url is set, but this build does not support monitoring hooks; use a build with the ping tag (the -full image or binary)

To use them, switch to the -full image tag (0.4.0-full), the dnspatch-full_* archive, or build with -tags "ping,notify_all". The full build is new in 0.4: releases 0.1 to 0.3 had a single build, the lightweight one. See Installation.

What is new and needs no action

  • dnspatch healthcheck and a per-instance status file, in every build.
  • ping_url on an instance, called on every completed cycle (Healthchecks.io, Uptime Kuma): full build.
  • Notifiers, a third kind of plugin next to retrievers and providers. An instance publishes a JSON event when it flips between success and failure. They are defined as [notify.<name>] and an instance picks them with notify = [...]: no key means every definition, [] means none. Backends: Redis Pub/Sub and RabbitMQ, in the full build. See Monitoring.
  • Build tags for a smaller binary: dnspatch_none leaves every retriever and provider out, retrievers_all and providers_all bring a kind back, and each plugin has a tag named after its type. A build that lacks a plugin the configuration names says which tag to add. See Building from source.
  • The packages app and httpx are public, so a plugin in a module of your own can be built into a custom dnspatch binary without a fork. See Plugins outside the repository.
  • For plugin authors: plugin.RegisterNotifier and the Notifier interface. Retriever and Provider are as in 0.3.
  • The documentation moved from the README to this site.