Nebula Sync Setup Guide - ajgillis04/GillisDockerDepot GitHub Wiki

Nebula Sync Setup Guide

Introduction

Nebula-Sync copies settings from a primary Pi-hole to one or more replicas, so a second Pi-hole can take over DNS when the first is down. It works with Pi-hole v6, and replaces Orbital Sync, which was built for v5 (see Orbital Sync Setup Guide).

Typical layout:

  • Primary: the Pi-hole where you make all changes (blocklists, local DNS, DHCP reservations). It may also run DHCP.
  • Replica: a second Pi-hole, for example on a Raspberry Pi, that answers DNS only.

Hand out both as DNS servers in DHCP so clients fall back automatically, for example with the dnsmasq line dhcp-option=6,192.168.1.5,192.168.1.6. See Pi-hole Setup Guide.

Step 1: Compose

On the replica's server (compose/server3/nebula-sync.yaml):

services:
  nebula-sync:
    container_name: nebula-sync.${HOST_NAME}
    image: ghcr.io/lovelaze/nebula-sync:v0.11.3
    user: "1000:1000"
    environment:
      TZ: ${TZ}
      PRIMARY_FILE: /run/secrets/nebula_sync_primary     # http://192.168.1.5|<password>
      REPLICAS_FILE: /run/secrets/nebula_sync_replicas   # http://192.168.1.6|<password>
      FULL_SYNC: "false"
      RUN_GRAVITY: "true"
      CRON: "15 4 * * *"
      SYNC_GRAVITY_GROUP: "true"
      SYNC_GRAVITY_AD_LIST: "true"
      SYNC_GRAVITY_AD_LIST_BY_GROUP: "true"
      SYNC_GRAVITY_DOMAIN_LIST: "true"
      SYNC_GRAVITY_DOMAIN_LIST_BY_GROUP: "true"
      SYNC_GRAVITY_CLIENT: "true"
      SYNC_GRAVITY_CLIENT_BY_GROUP: "true"
      SYNC_CONFIG_DNS: "true"
      SYNC_CONFIG_DNS_EXCLUDE: "upstreams,dnssec,revServers"
      SYNC_CONFIG_DHCP: "true"
      SYNC_CONFIG_DHCP_INCLUDE: "hosts"
    secrets:
      - nebula_sync_primary
      - nebula_sync_replicas
    restart: unless-stopped
    labels:
      - "com.centurylinklabs.watchtower.enable=false"

The two secret files hold URL|password and live in secrets/ (git-ignored).

Why Not a Full Sync

FULL_SYNC: "true" copies everything, including "DHCP on", which would give your network two DHCP servers. The selective settings above copy only:

  • blocklists, allow/deny lists, groups and clients (then rebuild gravity);
  • DNS settings such as local DNS records and CNAMEs, except settings you set on the replica with FTLCONF_ environment variables, which are read-only there (here: upstreams, DNSSEC, reverse servers);
  • DHCP reservations only (dhcp.hosts), never DHCP on/off or the address range.

Anything changed only on the replica is overwritten at the next sync, so always edit the primary.

Step 2: Replica Settings

On the replica, turn on webserver.api.app_sudo so the sync user can write settings: Pi-hole Settings → All settings → Webserver and API, or the FTLCONF_webserver_api_app_sudo: "true" environment variable.

Schedule

Each run with RUN_GRAVITY rebuilds the replica's gravity database, which downloads every blocklist again, so daily is plenty. Schedule the primary's own gravity update shortly before it (for example 04:00, sync at 04:15).

Checking It

docker logs nebula-sync.<host>

Look for Sync completed. Afterwards, both Pi-holes should report the same gravity domain count.

Troubleshooting

  • 401 / login failed: the password in a secret file is wrong. Nebula-Sync stops at the first failed login, so a 401 on the primary means the replica wasn't even tried. Stop the container while you fix it; otherwise it retries in a fast loop, each retry a new login attempt.
  • A setting won't sync: if it's set by an FTLCONF_ variable on the replica, it can't be changed by the API; exclude it or set it in compose instead.
⚠️ **GitHub.com Fallback** ⚠️