pihole_restore
is a CLI tool to restore a Pihole Backup archive file. It can
be used in a setup where multiple Pihole servers are configured that needs
syncing from a given master configuration point. This CLI is intended to be run
on the same runtime as the target Pihole server itself. It cannot run in a
detached runtime, since it depends on being able to access the pihole
CLI.
The motivation to write this tool was the absence of a restore
command in the
pihole
CLI shipped with Pi-hole.
glibc
- At most v2.28 (since the oldest pihole setup I could get my hands on had this version)
The following dev headers will be needed to compile the binary.
libsqlite3-dev
glibc
- At least v2.28 (if your runtime is older than this, please open an issue. I haven't explored far back enough to see if the older docker images have runtimes older than this.)
$ pihole_restore -h
Usage: pihole_restore [OPTIONS] --file <FILE>
Options:
-f, --file <FILE> teleporter archive file to restore from
-d, --database <DATABASE> gravity db file location [default: /etc/pihole/gravity.db]
-c, --clear clean existing tables and files
--filters <FILTERS> filter which config to restore, specify in comma separated keywords [default: all]
-h, --help Print help
-V, --version Print version
In a typical scenario, the following command will restore from the archive to
the /etc/pihole/gravity.db
and the other locations inside Pihole
installation.
pihole_restore -f pihole-backup.tar.gz
If the current configuration needs to be cleared before restoring from the
archive, -c
(--clear
) flag can be used. Doing so will clear out the tables
and the configuration files.
By default, the following configuration is restored.
blacklist
- Blacklist (exact)blacklistregex
- Blacklist (regex)whitelist
- Whitelist (exact)whitelistregex
- Whitelist (regex)adlist
- Adlistsauditlog
- Audit loggroup
- Groupclient
- Clientstaticdhcp
- Static DHCP Leaseslocaldns
- Local DNS Recordslocalcname
- Local CNAME Records
If only a subset of this configuration needs to be applied, use the --filter
argument. For an example, to restore only the Local DNS records run,
pihole_restore -f <archive_file.tar.gz> --filter localdns
use
sudo
in Raspbian since Pihole runs aspihole
nologin
user
Multiple filters can be specified as a comma separated string.
# restore blacklist (exact), adlists, groups, and clients
pihole_restore -f <archive_file.tar.gz> --filter blacklist,adlist,group,client
- test more use cases
- automated testing to cover most code
- edge cases on deduplication
- support for older glibc runtimes
- possibility on a fully independent binary (musl C?)
Use the makefile
target test
to spin up a pihole Docker container. It
compiles the binary on a Debian Buster container (to link to glibc 2.28), and
copies the result to the Pihole container. Create a backup of a Pihole setup
and copy it to the test
directory as test/pi-hole_backup.tar.gz
.
This source code and the binary is licensed under Apache v2 license. It is not distributed with the official Pihole distribution, and it is not endorsed by official Pi-hole community at this moment.