Repository navigation
Nebula Sync Setup Guide
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.
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).
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.
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.
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).
docker logs nebula-sync.<host>Look for Sync completed. Afterwards, both Pi-holes should report the same gravity domain count.
- 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.