Customize Block Page

Please allow us to customize the block page and not stop our pi-hole from updating. I’d love to be able to add a Leslie South Park themed block page for my users at home to get a chuckle out of it whenever an AD is blocked.

Hi there!
Block page contents are stored in /var/www/html/pihole, and whatever modification you done to those files will remain as it is after updating Pi-Hole.

Wally3k in a thread mentioned that modifying these files will cease the updates from updating? Is this not true then?

I have modified my Pi-Hole block page, since then there were 3 Pi-Hole updates nothing modified yet. It’s currently running on Ubuntu server 16.04

Also, since you’re now using AdminLTE, would it be simple enough to create a slight templating type system where people could create their own custom block pages?


A la, we pick from variables that are system set in settings, or we set our own, statically. Also perhaps the community could help with themes.

1 Like

This will be implemented in v3.2

1 Like

We are at v4 and it still isn’t available. I followed instructions to create a custom block page from here:“”, but it only works for error 404 (if you try to access the pi hole by ip address) it does not work for “Error Code: INET_E_RESOURCE_NOT_FOUND”

Block pages can only work for 404 and IP blocking mode. The page is pretty much going to go away as it does not work for https, Null blocking or NXDOMAIN blocking and the performance gain of Null/NX is so much that is makes the use of blocking pages a performance penalty.

Actually I got it working. The instructions were incorrect. BLOCKINGMODE=IP-NODATA-AAAA works. It works because the redirect created in that block mode goes to the IP address of the PI Hole which returns a 404 error and loads the custom page. The NULL does not because it returns an address of I also copied image files to the custom block page location so that the images can be supplied locally. Image files referenced in the HTML must contain the folder address of “pihole/[imagename]”. It works for all addresses including https. Although occasionally pi hole lags and the browser times out so the page dos not load (usually because the computer I’m using for the Pi Hole has gone into power save and doesn’t wake up the HDD on time).

I’m using an old laptop - Dell Inspiron 2650 - for the Pi Hole.

The only trouble I’m having now is that the touchpad stopped working right after I started using a mouse. I’ve tried to fix it, but no success… Oh well, something for another thread.

Here are the refined instructions for my particular block page setup…

How to set up a custom block page in Pi-Hole:

  1. Create a folder in your documents folder called “CustomBlockPage”.

  2. Copy the following files from the Pi-Hole web site into the folder: (Logo) (Background)
  1. Open a terminal window with LXTerminal.

  2. Copy the image files to the Pi-Hole block page folder:

sudo cp /home/[Your user name]/Documents/CustomBlockPage/*.* /var/www/html/pihole
  1. Create an HTML file for your custom block page with the name “CustomBlockPage.htm” and paste the HTML code in the file:
    (NOTE: Do not use LeafPad to make the file because it does not correctly format text for our purposes.)
sudo nano /var/www/html/pihole/CustomBlockPage.htm
<BODY BGCOLOR=000000 BACKGROUND="pihole/pihole-llc.png" TEXT=FFFFFF>
      <IMG SRC="pihole/Vortex-R.png" WIDTH=100><BR>
      <FONT Size=+2>
         This Page has Been Blocked<BR>
         *OR* Does not exist<BR>
      Notice: Some pages have been blocked due to content or bandwidth restrictions.
      If you believe that this page has been blocked in error,<BR>please contact the front desk.

Save and close.

  1. Set your file’s permissions:
sudo chmod +x /var/www/html/pihole/CustomBlockPage.htm
  1. Open the “lighttpd.conf” file to change the error handler for 404 file not found errors so that the custom block page opens instead of the default:
sudo nano /etc/lighttpd/lighttpd.conf
  1. Comment out the line “server.error-handler-404=“pihole/index.php”” with “#”, then add a new line with the custom block page file:

Save and exit.

  1. Restart the lighttpd service:
sudo service lighttpd restart
  1. Change the blocking mode to “IP-NODATA-AAAA” in the “pihole-FTL.conf” file by adding a block mode line:
sudo nano /etc/pihole/pihole-FTL.conf

add this line:


Save and exit.

(Note: “IP-NODATA-AAAA” returns the IP address of the Pi-Hole as the page location. When Pi-Hole tries to load the page, it returns a 404 error and re-directs to the custom block page. Null returns an IP of which will not help directing to the block page. “IP” and the other options also do not return a useful IP address for our purposes.)

  1. Restart the pihole-FTL service:
`sudo service pihole-FTL restart`

Congratulations, your block page is now ready.

Please Note: You may have to flush the DNS caches and browser cashes on the computers in your network for all the changes to take effect.

1 Like

So I have followed your instructions. Now rather than the normal page I get an “ERR_SSL_PROTOCOL_ERROR” on the pages i try to visit and not a block page.

I take it you are probably using Chrome. I don’t use Chrome. Here is a troubleshooting article for Chrome related to the error:

A post was split to a new topic: Error with custom web page

Saving images in pihole folder is save for any future Pihole update? If not, what is the best approach to saving the images too?

Cool Thanks. Here is mine. I tried it 3 times and all after loading a block domain in url bar would download the file and not show the 404 page. It turns out that I only need to add the ‘ip’ to this line instead.


If you are using a bg image, most likely the image will not fill the entire screen on mobile and will tile to fill in the rest. Add these 2 lines to your css block if you are using a .css file.

background-size: cover;
background-repeat: no-repeat;

I followed all of your instructions and I got an 400 Bad Request as shown in an image instead of your custom block page
Please Help!!!
I am running pi-hole on debian

I did all the steps above and I still get the default block screen. Any ideas?

so this works fine in IE. However, if I launch a blocked site in Chrome it prompts a download dialog box with a file name “download”.

Anyone else have this issue?