Customize Block Page

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?

Hey all!
first time playing with the pi-hole and i really dont have much scripting skills.
Long story short i wanted to make sure that when something is blocked that my wife when working home will know its because of my "toys".. this way i can quickly fix it.

i followed the above guide however it didnt work well so i looked up another guide which suggested using php instead of htm..

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

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

  1. On the pi-hole go to the /var/www/html/pihole folder
  2. type the following:
  1. Create an PHP file for your custom block page with the name “CustomBlockPage.php” 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.php

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

  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” in the “pihole-FTL.conf” file by adding a block mode line:
    *note: I changed mine ti BLOCKINGMODE=IP its up to you
    Blocking modes options:

sudo nano /etc/pihole/pihole-FTL.conf

  1. add this line:


Save and exit.

  1. Restart the pihole-FTL service:

sudo service pihole-FTL restart

Congratulations, your block page is now ready.

Thank you for sharing. The problem is that the 404 page will not work on google chrome, is there a way to fix it?

Look like I got bad request 400

Awsome solution; thanks for sharing -weird thing is that it doesnt seem to work for the Brave Browswer, i get:

This site can’t be reached is unreachable.


any ideas?

There's a small error in this line:


Instead it should be:

Then you shouldn't get a 400 - bad request.

A post was split to a new topic: Custom block page is not working with v5.0

For the website to be displayed correctly in Google Chrome, MS Edge, Opera, Vivaldi, Brave etc. browsers, you must change the extension from .htm to .html

I don't believe that is true. The webserver is the software that cares what the extension is.

It works for me in all browsers.

That's fine, the lighttpd configuration determines what file extensions it serves and what rendering engine is used to serve it.

Thanks to this post, I was able to setup my customized block page.
Any clue to get it working also for https?
I already own a nginx letsencrypt proxy with 80 and 443 ports open.
Defining the blocking page on it could be useful?


Blockpages don't work on HTTPS/TLS. You can't impersonate a TLS site (without creating a Man-In-The-MIddle attack on yourself.)

Doesn't work with the current strategy. Other products out there are able to do it, a different strategy to solve this problem must exists.

Sure, create your own Certificate Authority (and all the associated security hardening required for it) and push that CA to all the devices browsers or certificate stores and you can do it.

The only way to impersonate a TLS site is to set up an authority that has implicit trust to impersonate ANY domain they want.