Orbital Sync
Orbital Sync synchronizes multiple Pi-hole instances for high availability (HA) using the built-in "teleporter". In other words, it performs a "backup" in the Pi-hole admin interface of your primary Pi-hole instance, and then "restores" that backup to any number of "secondary" Pi-holes also via their admin interface. As a result, it supports the synchronization of anything currently supported by Pi-hole's "teleporter". See "Configuration" for the defaults.
Alternatives
I love Gravity Sync and have used it for some time, but I personally find it to be difficult to set up in some contexts (Docker, Unraid, Synology, etc.). Orbital Sync's approach is designed to rely less on the servers running Pi-hole by instead acting on their admin interface just like you would.
Why would I want multiple Pi-holes?
Ever had the server running your Pi-hole go down? Or have you ever needed to perform maintenance on that server? This can obviously be extremely disruptive to anyone using your network. By running multiple Pi-hole instances (replicas) and giving your network clients secondary/tertiary/etc DNS servers, any outage involving one of your Pi-hole instances doesn't bring down your whole network.
Getting Started
Set up your secondary Pi-hole instance(s) just like you did your primary. Once that's done, choose one of the following:
Docker
The following is an example Docker Compose file for running this project. See the configuration section for more environment variables.
version: '3'
services:
orbital-sync:
image: mattwebbio/orbital-sync:1
environment:
PRIMARY_HOST_BASE_URL: 'https://pihole1.example.com'
PRIMARY_HOST_PASSWORD: 'your_password1'
SECONDARY_HOST_1_BASE_URL: 'https://pihole2.example.com'
SECONDARY_HOST_1_PASSWORD: 'your_password2'
SECONDARY_HOST_2_BASE_URL: 'http://192.168.1.3'
SECONDARY_HOST_2_PASSWORD: 'your_password3'
INTERVAL_MINUTES: 30
The Orbital Sync Docker image is published to both DockerHub and the GitHub Package Repository:
mattwebbio/orbital-sync
ghcr.io/mattwebbio/orbital-sync
Node
As with Docker, running with Node requires you export any required environment variables before running Orbital Sync. See the configuration section for more information.
npm install -g orbital-sync
orbital-sync
Requirements
The admin web interfaces of all Pi-holes must be accessible by the container/server running this service. In other words, they have to be on the same network.
It is recommended you run this service with Docker.
Configuration
Sync Configuration
| Environment Variable | Required | Default | Examples | Description |
|---|---|---|---|---|
PRIMARY_HOST_BASE_URL |
Yes | N/A | http://192.168.1.2 or https://pihole.example.com |
The base URL of your Pi-hole, including the scheme (HTTP or HTTPS) and port but not including a following slash. |
PRIMARY_HOST_PASSWORD |
Yes | N/A | mypassword |
The password used to log in to the admin interface. |
SECONDARY_HOST_(#)_BASE_URL |
Yes | N/A | http://192.168.1.3 or https://pihole2.example.com |
The base URL of your secondary Pi-hole, including the scheme (HTTP or HTTPS) and port but not including a following slash. Replace (#) with a number, starting at 1, to add multiple secondary Pi-holes. |
SECONDARY_HOST_(#)_PASSWORD |
Yes | N/A | mypassword2 |
The password used to log in to the admin interface. |
INTERVAL_MINUTES |
No | 30 | Any non-zero positive integer, for example 5, 30, or 1440 |
How long to wait between synchronizations. Defaults to five minutes. Remember that the DNS server on your secondary servers restarts everytime a sync is performed. |
SYNC_WHITELIST |
No | true |
true/false |
Copies the whitelist |
SYNC_REGEX_WHITELIST |
No | true |
true/false |
Copies the regex whitelist |
SYNC_BLACKLIST |
No | true |
true/false |
Copies the blacklist |
SYNC_REGEXLIST |
No | true |
true/false |
Copies the regex blacklist |
SYNC_ADLIST |
No | true |
true/false |
Copies the adlist |
SYNC_CLIENT |
No | true |
true/false |
Copies clients |
SYNC_GROUP |
No | true |
true/false |
Copies groups |
SYNC_AUDITLOG |
No | false |
true/false |
Copies the audit log |
SYNC_STATICDHCPLEASES |
No | false |
true/false |
Copies static dhcp leases |
SYNC_LOCALDNSRECORDS |
No | true |
true/false |
Copies local DNS records |
SYNC_LOCALCNAMERECORDS |
No | true |
true/false |
Copies local CNAME records |
SYNC_FLUSHTABLES |
No | true |
true/false |
Clears existing data on the secondary (copy target) Pi-hole |
RUN_ONCE |
No | false |
true/false |
By default, orbital-sync runs indefinitely until stopped. Setting RUN_ONCE to true forces it to exit immediately after the first sync. |
Secondary hosts must be sequential (SECONDARY_HOST_1_BASE_URL, SECONDARY_HOST_2_BASE_URL, SECONDARY_HOST_3_BASE_URL, and so on) and start at number 1. Any gaps (for example, 3 to 5 skipping 4) will result in hosts after the gap being skipped in the sync process.
Notifications
| Environment Variable | Required | Default | Examples | Description |
|---|---|---|---|---|
NOTIFY_ON_SUCCESS |
No | false |
true/false |
Send a notification if a sync completes successfully. |
NOTIFY_ON_FAILURE |
No | true |
true/false |
Send notifications if a sync fails for any reason. |
NOTIFY_VIA_SMTP |
No | false |
true/false |
Send notifications via email. |
HONEYBADGER_API_KEY |
No | N/A | hbp_xxxxxxxxxxxxxxxxxx |
Get notifications to honeybadger.io when the process crashes for any reason by creating a new project and putting your API key here. |
VERBOSE |
No | false |
true/false |
Increases the verbosity of log output. Useful for debugging. |
TZ |
No | N/A | America/Los_Angeles |
The timezone for the timestamps displayed in log output. |
SMTP
| Environment Variable | Required | Default | Examples | Description |
|---|---|---|---|---|
SMTP_HOST |
Yes | N/A | smtp.example.com |
The SMTP server host. |
SMTP_PORT |
No | 587 |
25/587/465 |
The SMTP server port. |
SMTP_TLS |
No | false |
true/false |
Should usually be set to true if using port 465. Otherwise, leave as is. |
SMTP_USER |
No | N/A | [email protected] |
The SMTP account username. |
SMTP_PASSWORD |
No | N/A | yourpasswordhere |
The SMTP account password. |
SMTP_FROM |
No | N/A | [email protected] |
The email address to send notifications from. |
SMTP_TO |
Yes | N/A | [email protected] |
The email address to send notifications to. Can be a comma-seperated list. |
Disclaimer
This project is not associated with the official Pi-hole project and is a community maintained piece of software. See the license.
Pi-hole is a registered trademark of Pi-hole LLC.
41 Jan 7, 2023
13 Jan 7, 2023
3 Oct 8, 2022
5 Oct 18, 2022
70 Aug 13, 2023
0 Aug 4, 2022
11 Jun 23, 2022
3 Nov 1, 2022
9 Dec 14, 2022
29 Dec 29, 2022
1 Oct 10, 2022
16 Dec 29, 2022
6 Mar 29, 2022
20 Dec 30, 2022
585 Dec 31, 2022
74 Dec 31, 2022
493 Mar 5, 2022
7 Aug 18, 2022
10 Dec 7, 2022