lovelaze

nebula-sync: Replicate Pi-hole Configuration Across Instances

Nebula Sync copies Pi-hole v6 configuration from a primary instance to replicas, using full Teleporter sync or selective settings and data sync. It suits self-hosters who want consistent configurations across multiple Pi-hole servers.

View on GitHub Compare
Stars
1.6k
Forks
47
Stars, last 30 days
+24

Our take

Health score

36/100

How it is scored
Activity
31
Community
45
Issues
46
Pull requests
20

+24 stars in the last 30 days

Project history

Daily GitHub snapshots since Oct 7, 2026. History covers stars and forks; health signals are not tracked historically.

Selected snapshot

Stars

1,670

Forks

49

Change since Nov 17, 2026: +1 stars·0 forks

Overview

Nebula Sync is a Go tool for synchronizing configuration from a primary Pi-hole v6 instance to one or more replicas. It addresses the work of keeping multiple Pi-hole servers aligned, using Pi-hole's API rather than being part of the official Pi-hole project.

It supports full synchronization through Pi-hole Teleporter and selective synchronization for chosen settings and Gravity data. You can run it on a cron schedule, making it useful for maintaining replicas without manually repeating configuration changes.

Key Features

  • Synchronizes a primary Pi-hole v6 instance with configured replicas.
  • Supports full synchronization through Pi-hole Teleporter.
  • Allows selective synchronization of configuration sections and Gravity data.
  • Supports include and exclude filters for configuration keys during selective sync.
  • Can run synchronization on a cron schedule.
  • Optionally runs Gravity after synchronization.
  • Can send success and failure notifications through configurable webhooks.
  • Runs as a binary or in a Docker container.

Use Cases

  • A home-network administrator can keep secondary Pi-hole servers aligned with a primary server.
  • A self-hoster can maintain replicas for availability without manually copying settings after each change.
  • An operator who wants only selected DNS, DHCP, or Gravity data copied can use selective sync and filters.
  • A Docker-based deployment can schedule recurring syncs and send webhook alerts when a run succeeds or fails.

Getting Started

Install the binary with Go:

go install github.com/lovelaze/nebula-sync@latest

Configure the primary and replica instances, then run nebula-sync run. The README documents environment variables, Docker setup, and sync options.

Considerations

  • The project targets Pi-hole v6.x and depends on the Pi-hole API. It is not an official Pi-hole project.
  • Full sync transfers all settings and configurations. Selective options and config filters apply only when FULL_SYNC=false.
  • Replica credentials and API permissions must be configured correctly. The README notes that app-password authentication may require enabling webserver.api.app_sudo on replicas.
  • The Docker image runs as user 1001 by default, so Docker secret file permissions may need adjustment.
  • The repository reports 49 open issues. Check the issues page for current project concerns.

Found this useful?

Share it with someone who would like nebula-sync.