--- title: "How to Set Up DNS Failover with PowerDNS LUA Records" description: "Configure health-checked DNS failover on Ubuntu 24.04 with PowerDNS LUA records, so your domain answers with a backup server IP when the primary goes down." category: "Migration and Disaster Recovery" language: en source: https://cubepath.com/docs/migration-and-disaster-recovery/dns-failover-configuration updated: 2026-09-25 --- # How to Set Up DNS Failover with PowerDNS LUA Records DNS failover makes your domain answer with a backup server's IP address when the primary server stops responding. Instead of a cron script that rewrites zone files, you can let the authoritative DNS server run the health checks itself. PowerDNS Authoritative Server supports LUA records, whose answers are computed at query time: the `ifurlup()` function checks a URL on each candidate address and returns only the healthy ones. In this tutorial you will install PowerDNS on Ubuntu 24.04, serve a zone with a health-checked failover record and test that it switches when the primary fails. ## How DNS failover works (and its limits) With the configuration in this guide, PowerDNS checks `https://www.your_domain/healthz` on the primary and backup servers every few seconds. While the primary is healthy, queries for `www.your_domain` return only the primary IP. When the primary fails its checks, the same query returns the backup IP. Keep these limits in mind: - Resolvers cache answers for the record's TTL. With a 30-second TTL, most clients move to the backup within a minute, but some resolvers and applications cache longer than the TTL. - DNS failover redirects new connections only. Open connections to the failed server are lost. - The backup must be able to serve the site: files, database and TLS certificates must already be there. - Your nameservers must be highly available themselves. Run at least two, in different locations. If you need sub-second failover within one location, a floating IP or a load balancer is a better fit; DNS failover shines for failover between sites. ## Prerequisites To follow this guide you need: - Two web servers serving the same site: a primary (`primary_ip`) and a backup (`backup_ip`). Both must respond on `https://www.your_domain/healthz` with HTTP 200 and the body `ok`, using a valid certificate for `www.your_domain`. - Two servers running Ubuntu 24.04 LTS for the nameservers, each with a non-root sudo user and a public IP (`ns1_ip` and `ns2_ip`). Small CubePath VPS instances in different locations work well. This guide shows the setup on `ns1`; repeat it identically on `ns2`. - A registered domain (`your_domain`) whose registrar lets you set custom nameservers and glue records. - TCP and UDP port 53 open to the internet on both nameservers. ## Step 1 - Creating the health check endpoint The health check should confirm that the application really works, not just that Nginx is running. A good endpoint checks the database connection and returns `ok`. For a quick start, a static endpoint in Nginx is enough. On both web servers, add this block to the site's `server` block: ```nginx location = /healthz { access_log off; default_type text/plain; return 200 "ok"; } ``` Reload Nginx and test from any machine: ```bash curl -s --resolve www.your_domain:443:primary_ip https://www.your_domain/healthz curl -s --resolve www.your_domain:443:backup_ip https://www.your_domain/healthz ``` ```output okok ``` Both servers must answer. If the backup fails here, failover would send traffic to a broken server. ## Step 2 - Installing PowerDNS Ubuntu 24.04 ships PowerDNS Authoritative Server 4.8 with the BIND zone file backend as a separate package. Install both on `ns1`: ```bash sudo apt update sudo apt install pdns-server pdns-backend-bind ``` The package starts the service right away. Ubuntu's `systemd-resolved` already listens on `127.0.0.53:53`, so PowerDNS must bind only to the public IP. You will set that in the next step. ## Step 3 - Configuring PowerDNS Keep a copy of the packaged configuration: ```bash sudo cp /etc/powerdns/pdns.conf /etc/powerdns/pdns.conf.orig ``` Open the main configuration file: ```bash sudo nano /etc/powerdns/pdns.conf ``` Replace its contents with the following. Replace `ns1_ip` with the server's public IPv4 address: ```ini # Serve zones from BIND-style zone files launch=bind bind-config=/etc/powerdns/named.conf # Listen only on the public address (systemd-resolved uses 127.0.0.53) local-address=ns1_ip local-port=53 # Enable LUA records and their health checks enable-lua-records=yes lua-health-checks-interval=5 ``` Because this file no longer contains an `include-dir` line, the drop-in files under `/etc/powerdns/pdns.d/` are not loaded, and this file is the complete configuration. Create the file that lists the zones: ```bash sudo nano /etc/powerdns/named.conf ``` ```text zone "your_domain" { type master; file "/etc/powerdns/zones/your_domain.zone"; }; ``` ## Step 4 - Writing the zone with a failover record Create the zone directory: ```bash sudo install -d -m 0755 /etc/powerdns/zones ``` Open the zone file: ```bash sudo nano /etc/powerdns/zones/your_domain.zone ``` Add the following zone. The `www` record is a LUA record that returns an `A` answer: ```text $ORIGIN your_domain. $TTL 3600 @ IN SOA ns1.your_domain. hostmaster.your_domain. ( 2026092501 ; serial 3600 ; refresh 600 ; retry 1209600 ; expire 300 ) ; negative caching TTL @ IN NS ns1.your_domain. @ IN NS ns2.your_domain. ns1 IN A ns1_ip ns2 IN A ns2_ip www 30 IN LUA A "ifurlup('https://www.your_domain/healthz', {{'primary_ip'}, {'backup_ip'}}, {stringmatch='ok'})" ``` How the `www` record works: - `ifurlup()` requests the URL on each address, sending the host name from the URL, and considers an address up when the request succeeds within the timeout. - `{stringmatch='ok'}` also requires the body to contain `ok`, so an error page served with status 200 counts as down. - The addresses are given as a list of groups: `{{'primary_ip'}, {'backup_ip'}}`. PowerDNS answers with the healthy addresses of the first group, and only moves to the next group when every address in the first one is down. That is active/passive failover. A single flat list such as `{'primary_ip', 'backup_ip'}` would instead return one of the healthy addresses at random (active/active). - The TTL of 30 seconds keeps resolver caches short. To fail over the apex domain too, add the same LUA record with `@` as the name. LUA records work at the apex, where a CNAME is not allowed. Validate the zone: ```bash sudo pdnsutil check-zone your_domain ``` ```output Checked 6 records of 'your_domain', 0 errors, 0 warnings. ``` Restart PowerDNS and check that it is running: ```bash sudo systemctl restart pdns sudo systemctl status pdns --no-pager ``` ```output ● pdns.service - PowerDNS Authoritative Server Loaded: loaded (/usr/lib/systemd/system/pdns.service; enabled; preset: enabled) Active: active (running) since Thu 2026-09-25 11:04:12 UTC; 3s ago ``` If the service fails, read the log with `sudo journalctl -u pdns -n 50`. Open port 53 for TCP and UDP: ```bash sudo ufw allow 53 ``` ## Step 5 - Querying the failover record Query the server directly: ```bash dig @ns1_ip www.your_domain A +noall +answer ``` ```output www.your_domain. 30 IN A primary_ip ``` Right after startup, PowerDNS may answer before the first health check has completed. Wait a few seconds and query again; from then on the answer reflects the check results. Repeat Steps 2 to 5 on `ns2` with its own IP in `local-address`. Keep the zone file identical on both servers: copy it with `scp` or manage it with a configuration management tool, and increase the serial every time you change it. > Note: Use two PowerDNS servers that each evaluate the LUA records, rather than a classic primary/secondary pair with zone transfers. A secondary that is not PowerDNS with LUA records enabled cannot evaluate the `LUA` record type. ## Step 6 - Delegating the domain At your registrar, set the nameservers of `your_domain` to `ns1.your_domain` and `ns2.your_domain`, and create glue records pointing `ns1.your_domain` to `ns1_ip` and `ns2.your_domain` to `ns2_ip`. Glue records are required because the nameservers live inside the domain they serve. Delegation can take up to a day to propagate because the parent zone has long TTLs. Check it with a trace: ```bash dig +trace www.your_domain A ``` The last section of the output should come from `ns1.your_domain` or `ns2.your_domain` and contain the primary IP. ## Step 7 - Testing the failover Simulate an outage on the primary web server by stopping Nginx: ```bash sudo systemctl stop nginx ``` Within a few check intervals (the interval is 5 seconds), the answer changes. Query both nameservers: ```bash dig @ns1_ip www.your_domain A +short dig @ns2_ip www.your_domain A +short ``` ```output backup_ip backup_ip ``` Start Nginx on the primary again: ```bash sudo systemctl start nginx ``` A few seconds later, both nameservers return `primary_ip` again. Note that failback is automatic: as soon as the primary passes its checks it receives traffic again. If the backup has accepted writes that the primary does not have, handle data synchronization before bringing the primary back. To see the failover from a client's point of view, query a public resolver in a loop, pausing between queries: ```bash for i in $(seq 1 10); do dig @1.1.1.1 www.your_domain A +short; sleep 10; done ``` ## Troubleshooting **PowerDNS fails with "Unable to bind UDP socket to '0.0.0.0:53': Address already in use".** `local-address` is missing or wrong. Set it to the server's public IP so it does not collide with `systemd-resolved`. **The record always returns the backup.** The check to the primary fails. Run `curl -sv --resolve www.your_domain:443:primary_ip https://www.your_domain/healthz` from the nameserver: firewall rules, an invalid certificate or a body that does not contain `ok` all mark the address as down. **`pdnsutil check-zone` reports an error on the LUA record.** Check that `enable-lua-records=yes` is set and that the record content is wrapped in double quotes, with single quotes inside the Lua code. **Clients keep reaching the failed server.** Some resolvers enforce a minimum TTL, and browsers and applications keep their own DNS caches. This is a limit of DNS failover, not of the configuration. ## Conclusion You now have two PowerDNS nameservers that health-check your web servers and answer with the backup IP when the primary fails, then fail back automatically when it recovers. The same `ifurlup()` pattern works for AAAA records, and `ifportup()` checks a TCP port for services that do not speak HTTP. As next steps, alert on failovers by monitoring the answer of your nameservers, and make sure the backup server's data is kept current with replication or regular syncs so a failover never serves stale content.