nebula-sync

Synchronize Pi-hole v6.x configuration to replicas.

This project is not a part of the official Pi-hole project, but uses the api provided by Pi-hole instances to perform the synchronization actions.

Features

Full sync: Use Pi-hole Teleporter for full synchronization.
Manual sync: Selective feature synchronization.
Cron schedule: Run on chron schedule.

Installation

Linux/OSX binary

Download binary from the latest release or build from source:

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

Run binary:

# run
nebula-sync run

# read envs from file
nebula-sync run --env-file .env

Docker Compose (recommended)

---
services:
  nebula-sync:
    image: ghcr.io/lovelaze/nebula-sync:latest
    container_name: nebula-sync
    environment:
    - PRIMARY=http://ph1.example.com|password
    - REPLICAS=http://ph2.example.com|password,http://ph3.example.com|password
    - FULL_SYNC=true
    - CRON=0 * * * *

Docker CLI

docker run --rm \
  --name nebula-sync \
  -e PRIMARY="http://ph1.example.com|password" \
  -e REPLICAS="http://ph2.example.com|password" \
  -e FULL_SYNC=true \
  ghcr.io/lovelaze/nebula-sync:latest

Examples

Env and docker-compose examples can be found here

Configuration

The following environment variables can be specified:

Required Environment Variables

Name	Default	Example	Description
`PRIMARY`	n/a	`http://ph1.example.com\|password`	Specifies the primary Pi-hole configuration
`REPLICAS`	n/a	`http://ph2.example.com\|password,http://ph3.example.com\|password`	Specifies the list of replica Pi-hole configurations
`FULL_SYNC`	n/a	`true`	Specifies whether to perform a full synchronization

Note: When FULL_SYNC=true, the system will perform a full Teleporter import/export from the primary Pi-hole to the replicas. This will synchronize all settings and configurations.

Optional Environment Variables

Name	Default	Example	Description
`CRON`	n/a	`0 * * * *`	Specifies the cron schedule for synchronization
`TZ`	n/a	`Europe/London`	Specifies the timezone for logs and cron

Note: The following optional settings apply only if FULL_SYNC=false. They allow for granular control of synchronization if a full sync is not wanted.

Name	Default	Description
`SYNC_CONFIG_DNS`	false	Synchronize DNS settings
`SYNC_CONFIG_DHCP`	false	Synchronize DHCP settings
`SYNC_CONFIG_NTP`	false	Synchronize NTP settings
`SYNC_CONFIG_RESOLVER`	false	Synchronize resolver settings
`SYNC_CONFIG_DATABASE`	false	Synchronize database settings
`SYNC_CONFIG_MISC`	false	Synchronize miscellaneous settings
`SYNC_CONFIG_DEBUG`	false	Synchronize debug settings
`SYNC_GRAVITY_DHCP_LEASES`	false	Synchronize DHCP leases
`SYNC_GRAVITY_GROUP`	false	Synchronize groups
`SYNC_GRAVITY_AD_LIST`	false	Synchronize ad lists
`SYNC_GRAVITY_AD_LIST_BY_GROUP`	false	Synchronize ad lists by group
`SYNC_GRAVITY_DOMAIN_LIST`	false	Synchronize domain lists
`SYNC_GRAVITY_DOMAIN_LIST_BY_GROUP`	false	Synchronize domain lists by group
`SYNC_GRAVITY_CLIENT`	false	Synchronize clients
`SYNC_GRAVITY_CLIENT_BY_GROUP`	false	Synchronize clients by group

Disclaimer

This project is an unofficial, community-maintained project and is not affiliated with the official Pi-hole project. It aims to add sync/replication features not available in the core Pi-hole product but operates independently of Pi-hole LLC. Although tested across various environments, using any software from the Internet involves inherent risks. See the license for more details.

Pi-hole and the Pi-hole logo are registered trademarks of Pi-hole LLC.