What files does Pi-hole use?

FAQs
1

Note: FAQ updated in September 2022 to reflect files locations for Pi-Hole V5.12.

/etc/.pihole/

This directory is a clone of the pi-hole repo. During installation, the repository is cloned here so the files Pi-hole needs can be copied to your system.

/etc/cron.d/

  • pihole: the cron file that runs scheduled tasks such as rotating and flushing the log files or downloading the latest updates from the blocklist sources

/etc/dnsmasq.d/

  • 01-pihole.conf: the config specific to Pi-hole that controls how dnsmasq functions
  • 02-pihole-dhcp.conf: the config file used when Pi-hole's DHCP server is active
  • 04-pihole-static-dhcp.conf : file of static DHCP leases

/etc/lighttpd/

  • lighttpd.conf: this is used to configure the Web server to respond to black holed domains and return a 404 of a blank Webpage. It also contains X-Headers and a few other settings.
  • external.conf: this is a user-created file that can be used to modify the Web server. These changes will persist through updates, unlike if you were to manually edit lighttpd.conf

/etc/pihole/

This is where most of Pi-hole's config files exist. It contains:

  • adlists.list: a custom user-defined list of blocklist URL's (public blocklists maintained by Pi-Hole users)
  • blacklist.txt: a user-defined list of additional domains to block locally - legacy file (pre v5.x)
  • dhcp.leases: store Pi-hole's DHCP leases information
  • dns-servers.conf : The list of DNS servers that ship with Pi-Hole
  • gravity.db : database file with all of the domains that are being blocked - perhaps Pi-hole's most important database
  • install.log: a log file generated during installation
  • list.**.domain: these are the raw block lists that are downloaded.
  • local.list: this contains local list entries such as pi.hole so you can access the Web interface via name instead of IP.
  • logrotate: this is the config file that controls how logrotate handles flushing the log file
  • macvendor.db: a database of MAC addresses that relate the MAC address to a vendor (this file is updated when Pi-Hole is updated)
  • pihole-FTL.conf: this is the config file that specifies local pihole-FTL options
  • pihole-FTL.db: this is the long term Pi-Hole database, containing a record of queries and a network table of clients.
  • regex.list : file of regex filters that are compiled with each pihole-FTL start or restart - legacy file (pre v5.x)
  • setupVars.conf: this file contains variables needed to effectively setup and configure Pi-hole
  • versions: this file has information about the release version in GitHub and local versions
  • whitelist.txt: a user-defined list of domains to be whitelisted locally. Adding domains to this list makes them "gravity proof." - legacy file (pre v5.x)

/opt/pihole/

  • individual scripts that are called by pihole
  • COL_TABLE: used for showing colors in the output of scripts

/usr/local/bin/

/run/

  • pihole-FTL.pid: the process ID used by FTL
  • pihole-FTL.port the port number used by FTL (defaults to 4711)

/var/log/pihole/

  • FTL.log: This is the log file that contains information handled by our FTL engine. This file is rotated every night at midnight.
  • pihole.log: This is the log file that contains all of the DNS queries Pi-hole handles as well as the queries that were blocked. See this post to learn how to interpret this file. This file is rotated every night at midnight.
  • pihole_debug.log: This is the log file generated by pihole -d. This is stored locally, but you also have the option to upload it to our secure server

/var/log/lighttpd/

  • access-pihole.log: this log contains entries from blocked domains (and the web interface). It is useful for visualizing Pi-hole.
  • error-pihole.log: this log file contains errors lighttpd may run into

/var/www/html/admin/

  • This folder contains all the files needed for the admin interface and is simply a clone of the repo.

/var/www/html/pihole/

  • This folder contains the blank HTML page that is delivered in place of advertisements.
  • It also contains the blockpage if you try to directly visit a domain that is blocked
4 Likes
3

2 posts were split to a new topic: Multiple Pi-holes and pi.hole

4

A post was split to a new topic: What is /etc/.pihole/.git

7

This is a very useful list. It would be good if it identified the files/directories that must be preserved across reinstalls so these can be put in place prior to running the unattended installer. This would be useful when recreating containers or if rebuilding a physical machine.

8

I think it's worth noting, that when using Docker for pi-hole, amount of "exposed" to us (using bind command) is even smaller.

dnsmasq.d with two files:

01-pihole.conf 06-rfc6761.conf

and

ll pihole/ | grep -v list
total 1.4G
-rw-r--r-- 1 root             root               16 Mar 12 18:44 GitHubVersions
-rw-r--r-- 1 systemd-coredump systemd-coredump    0 Mar 12 07:50 dhcp.leases
-rw-r--r-- 1 root             root              651 Mar 12 07:50 dns-servers.conf
-rw-rw-r-- 1 systemd-coredump systemd-coredump  76M Mar 13 13:33 gravity.db
-rw-rw-r-- 1 systemd-coredump systemd-coredump  76M Mar 13 04:21 gravity_old.db
-rw-r--r-- 1 root             root               20 Mar 13 14:20 localbranches
-rw-r--r-- 1 root             root               38 Mar 13 14:20 localversions
drwxr-xr-x 2 root             root             4.0K Dec  4 22:16 migration_backup
-rw-r--r-- 1 systemd-coredump systemd-coredump   20 Mar 12 07:50 pihole-FTL.conf
-rw-rw-r-- 1 systemd-coredump systemd-coredump 1.2G Mar 13 14:24 pihole-FTL.db
-rw-r--r-- 1 root             root              271 Mar 12 07:50 setupVars.conf

Everything else is just gravity related lists of domains.

This is very important (at least for me :slight_smile: ) because it makes backup and restore very easy to do. It's crucial to me i keep my history for long-term. With this setup i tar single folder and viola.