How to make a full backup of Pi-hole

We're going to tell you how to make a backup complete Pi-hole helps you avoid losing your settings. While Teleporter is the native mechanism for this, it has limitations when it comes to creating a complete backup. In this post, we'll tell you how. What does Teleporter's support include, and what other options do you have? so that nothing is left out.

How to make a full backup of Pi-hole

Pi-hole has become a fundamental piece of network infrastructure for thousands of enthusiasts homelab and IT professionals. Once you configure it with your custom blocklists, client groups, local DNS entries, and DHCP settings, It's scary to lose everythingSo the question isn't whether you should make a full backup of Pi-hole, but when and how.

There is a widespread belief that the Teleporter function integrated into Pi-hole is sufficient to support the entire installation. But the reality is more nuanced: Teleporter captures most of the configuration, but leaves out critical elements such as the long-term query history. So let's start by looking at the procedure for creating a backup with Teleporter and what other options you have to ensure the backup is truly complete.

Teleporter: the starting point (but not the end)

Let's review the procedure for creating a full backup of Pi-hole using Teleporter. This is Pi-hole's official tool for exporting and importing configurations, and it's accessed from the web interface. Settings – Teleporter. With it, the system generates a file .tar.gz which contains the block lists, custom domain rules, group settings, defined clients, and main system settings.

To start the export process, simply click on Export, Download the file and save it in a safe place. Importing works in reverse, allowing you to select which components to restore granularly. However, Teleporter has limitations documented that are worth mentioning.

The most notable of all is that It does not include the query database (pihole-FTL.dbThis can contain months or years of DNS activity history. Why is it so important? Because this history allows you to analyze trends, identify traffic patterns, and detect problematic devices on the network. Losing it in a backup would be a disaster, so relying solely on this tool is risky.

How to manually perform a full backup of Pi-hole

To make a backup complete From Pi-hole, you have to access your file system and back up specific directoriesThe essential elements are found in /etc/pihole/ And, depending on the configuration, you might also need to back up /etc/dnsmasq.d/ y /etc/lighttpd/.

Within the directory /etc/pihole/ you find critical files such as the following:

• gravity.dbThis contains all blocklists, allowed and denied domains, groups, and client settings. It's the heart of your filtering configuration.
• pihole-FTL.dbThe long-term query history. This file can grow considerably, up to several gigabytes in active installations.
• pihole.toml (in Pi-hole v6) or setupVars.conf (in previous versions): the main system settings.
• Archives .list y .conf in the dnsmasq directory: Custom configurations that you have manually added.

From the terminal, you can run a command to make a backup Complete Pi-hole backup of all these files. For example, on Linux you just need to run the following command with superuser privileges to create a compressed file: sudo tar -czvf pihole-backup-manual.tar.gz /etc/pihole/ /etc/dnsmasq.d/.

Automation: Pi-hole's full backup that does itself

However, the best backup is the one that requires no manual intervention. Relying on a backup system often results in outdated backups, especially during emergencies. Therefore, the best practice is automate the generation and external storage of copies using a Bash script and a scheduled task in cron.

Do you need help with the latter? Don't worry: there are several scripts available on GitHub that automate the Pi-hole backup process. What they do is combine the native Teleporter option with direct file copiesA typical automation script performs the following operations:

1. Execute pihole-FTL --teleporter to generate the configuration file.
2. Copy that file to a backup directory (possibly on a NAS mounted by NFS or CIFS).
3. Optionally, also copy the file pihole-FTL.db to preserve the history.
4. Delete older copies to manage storage space.

Also remember that configuring these scripts involves adjust variables as BACKUP_DIR (the destination route) and MAX_BACKUPS (how many copies to keep). A reasonable value for MAX_BACKUPS It's between 7 and 10, which gives you at least a week's worth of backup history.

Once the script is written, you need to program it to run automaticallyThe best way to do this is by adding an entry to cron run the script daily or weekly, depending on how often you change your settings.

Let's say you want to perform a full backup of Pi-hole. every week (for example, Sundays at 3:00 AM). First, edit the crontab of the system with sudo crontab -eThen, add the following line to the end of the file: 0 3 * * 0 /usr/local/bin/backup_pihole.sh > /dev/null 2>&1.

Restoring the backup

A complete Pi-hole backup will only be as good as its ability to be restored The restoration process varies depending on the method you used. For example, if you used Teleporter, you just need to access the Pi-hole web interface and go to Settings – Teleporter – Browse and upload the file .tar.gz restoration.

And for direct copies of the directory, you have to stop Pi-hole. replace the contents of the directory /etc/pihole/ with your backup and, finally, restart the service. The procedure is actually quite simple and rarely fails, but the result is invaluable: the preservation of all your Pi-hole configuration.

You already know: for a backup complete from Pi-hole It is advisable to combine Teleporter for portable configuration with manual copies. from the directory /etc/pihole/ To preserve the complete history, it's best to automate the process and store the backups in a secure location from which they can be easily restored.