Skip to content
A temporary unblock solution and blockpage for your Pi-Hole system
Branch: master
Clone or download
Latest commit b1e21ff Jun 24, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Nevermind Jun 24, 2019
blockpage It should work Jun 1, 2019
docs Added pages to the wiki Jun 24, 2019
locale Create locale-it.php Jun 23, 2019
setup Update setup.php Jun 24, 2019
LICENSE Nevermind Jun 24, 2019 One-step install is here Jun 22, 2019
config.php Change version to 1.3.5 to prepare for release Jun 21, 2019
index.php Improved update and setup functionality May 28, 2019


Maintainability version GitHub pull-requests GitHub pull-requests

PiPass is an extention to the Pi-Hole project which adds easy temporary unblocking functionality and a visually appealing blockpage. The whole project currently is written in PHP, so it will integrate very easily with your existing Pi-Hole system. The blockpage is very easy to use, presenting three distinct options, an automated, temporary unblock button among them.

PiPass blockpage


Obviously, this is an open-source project. You may find problems in the code, in which I would strongly encourage you to create an issue, or if you're willing to solve it yourself, fork the repository and create a pull request. If you want a feature added, feel free to create an issue.

A list of known caveats is at the bottom of this document. If you'd like to contribute but don't know how, check there for some ideas.


  • Pi-Hole server
    • Includes webserver and PHP already installed & configured (confirmed working on PHP version 7.3)
  • SSH or direct terminal access
  • SSL certificate for your Pi-Hole (self signed is ok)
  • PHP-CURL to check for new versions (sudo apt update && sudo apt install php7.0-curl) Root (sudo) access to Pi-Hole
  • Git (if this isn't installed yet, use sudo apt-get install wget git-core)
  • Knowledge of location of webroot (normaly this can be found under /var/www/html/)
  • Webroot folder without any index files (e.g. no index.php/index.html/etc.)
  • Knowledge of which user PHP is running as
  • Optional, will improve functionality: Domain or subdomain linked to your Pi-Hole


Installation on a vanilla Pi-Hole is completely automated. Execute bash <(wget -qO- to install.

If you have a more complex installation (e.g. using NGiNX as a webserver), follow these steps below.

  1. Make your webserver redirect all 404 errors to the webroot. If you use lighttpd, this function is automated.

For NGiNX, this is

        location / {
                try_files $uri $uri/ =404;
                error_page 404 =200 http://$host;
  1. bash <(wget -qO- - You may be prompted for elevated permissions using sudo.

  2. Optional: fill out the config.php configuration file.


Having problems? Let me know.

Pull requests are welcome!

Known Caveats

  • Requires webroot index
  • Does not work on websites with HSTS header cached :(

Future Ideas

  • Ability to trigger permanent whitelist after password entry
  • Admin console for PiPass (currently in the works)
  • apt repository/package and Docker image
You can’t perform that action at this time.