pihole-restore

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.

Compile Time Dependencies

1. glibc - At most v2.28 (since the oldest pihole setup I could get my hands on had this version)

Ubuntu

The following dev headers will be needed to compile the binary.

1. libsqlite3-dev

Runtime Dependencies

1. 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.)

Usage

$ 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.

1. blacklist - Blacklist (exact)
2. blacklistregex - Blacklist (regex)
3. whitelist - Whitelist (exact)
4. whitelistregex - Whitelist (regex)
5. adlist - Adlists
6. auditlog - Audit log
7. group - Group
8. client - Client
9. staticdhcp - Static DHCP Leases
10. localdns - Local DNS Records
11. localcname - 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 as pihole 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

TODO

1. test more use cases
2. automated testing to cover most code
3. edge cases on deduplication
4. support for older glibc runtimes
5. possibility on a fully independent binary (musl C?)

Development

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.

License

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.