HUB
Sign inSign up

kylemmkay/adguardhome-keepalived

By kylemmkay

•Updated about 1 month ago

A small Alpine-based keepalived image that gives two AdGuard Home nodes one shared, highly available

Image
0

129

kylemmkay/adguardhome-keepalived repository overview

⁠AdGuard Home - Keepalived

Source on Codeberg Docker Hub

A small Alpine-based keepalived image that gives two AdGuard Home nodes one shared, highly available DNS IP using VRRP.

The health check runs every 5 seconds. It queries the local AdGuard Home for keepalived-check.lan and passes only if the answer is 0.0.0.0. Two failures in a row release the virtual IP to the other node, and two successes take it back. The answer comes from a local rule, so an internet outage doesn't trigger a failover.

On both AdGuard instances:

  • Add the custom filtering rule ||keepalived-check.lan^. With the default blocking mode, AdGuard answers it with 0.0.0.0.
  • Optionally add keepalived-check.lan to the ignored domains for the query log and statistics, so the checks don't flood them.

⁠Configuration

At startup the container writes its keepalived config from these environment variables:

VariableRequiredDefaultDescription
UNICAST_SRC_IPyesThis node's IP
UNICAST_PEER_IPyesThe other node's IP
VIRTUAL_IPyesShared IP with prefix, e.g. 192.168.1.53/24
AUTH_PASSyesVRRP password, the same on both nodes (max 8 characters)
INTERFACEnoeth0Network interface
PRIORITYno100Higher value = preferred node
VIRTUAL_ROUTER_IDno53VRRP router ID, the same on both nodes
CHECK_IPnoUNICAST_SRC_IPAdGuard Home IP to health-check

To use your own config instead, mount it at /etc/keepalived/keepalived.conf. The environment variables are then ignored.

⁠Usage

Two example stacks show a full setup, with AdGuard Home, keepalived and adguardhome-sync:

Copy the matching file to each host as compose.yaml, replace the example IPs and interface, and put the secrets listed at the top of each file in a .env file next to it.

To run the check by hand: docker exec keepalived check_adguard.sh <adguard-ip> && echo OK

⁠Troubleshooting

  • Both nodes hold the VIP (intermittent DNS): the nodes can't hear each other. Stop keepalived on the secondary, then check that AUTH_PASS and VIRTUAL_ROUTER_ID match on both nodes, that the peers can ping each other, and that no host firewall drops VRRP traffic from the peer.
  • Clear a stuck VIP by hand: ip addr del 192.168.1.53/24 dev eth0
  • One failed check at startup is normal while AdGuard loads its blocklists.
⁠Synology NAS

My local setup

  • If you want to see per-device (ip) logging, you may need to set adguards container to use network_mode: host instead of port bindings. With bridged ports, DSM's Docker shows every client as the bridge gateway. With host networking, AdGuard listens on every address, including the VIP once keepalived moves it there.

    services:
      adguardhome:
        container_name: adguardhome
        image: adguard/adguardhome
        network_mode: host
        #...
    
  • The interface is usually ovs_eth0 when Open vSwitch is active, not eth0.

      keepalived:
        container_name: keepalived
        image: codeberg.org/kylemmkay/adguardhome-keepalived:latest
        #...
        environment:
          INTERFACE: ovs_eth0
    
  • If the DSM firewall is on, allow all traffic from the peer node.

  • keepalived may warn that it was built for a newer kernel than DSM's. VRRP still works.

⁠License

MIT

Tag summary

Content type

Image

Digest

sha256:5951b43e1…

Size

7.1 MB

Last updated

about 1 month ago

docker pull kylemmkay/adguardhome-keepalived