Configuring NGINX for Pi-hole

Notes & Warnings

  • This is an unsupported configuration created by the community
  • If you're using php5, change all instances of php7.0-fpm to php5-fpm and change /run/php/php7.0-fpm.sock to /var/run/php5-fpm.sock

Basic requirements

  1. Stop default lighttpd

    service lighttpd stop
  2. Install necessary packages

    apt-get -y install nginx php7.0-fpm php7.0-zip apache2-utils
  3. Disable lighttpd at startup

    systemctl disable lighttpd
  4. Enable php7.0-fpm at startup

    systemctl enable php7.0-fpm
  5. Enable nginx at startup

    systemctl enable nginx
  6. Edit /etc/nginx/sites-available/default to:

    server {
        listen 80 default_server;
        listen [::]:80 default_server;
        root /var/www/html;
        server_name _;
        autoindex off;
        index pihole/index.php index.php index.html index.htm;
        location / {
            expires max;
            try_files $uri $uri/ =404;
        location ~ \.php$ {
            include fastcgi_params;
            fastcgi_param SCRIPT_FILENAME $document_root/$fastcgi_script_name;
            fastcgi_pass unix:/run/php/php7.0-fpm.sock;
            fastcgi_param FQDN true;
            auth_basic "Restricted"; # For Basic Auth
            auth_basic_user_file /etc/nginx/.htpasswd; # For Basic Auth
        location /*.js {
            index pihole/index.js;
            auth_basic "Restricted"; # For Basic Auth
            auth_basic_user_file /etc/nginx/.htpasswd; # For Basic Auth
        location /admin {
            root /var/www/html;
            index index.php index.html index.htm;
            auth_basic "Restricted"; # For Basic Auth
            auth_basic_user_file /etc/nginx/.htpasswd; # For Basic Auth
        location ~ /\.ht {
            deny all;
  7. Create a username for authentication for the admin - we don't want other people in our network change our black and whitelist ;)

    htpasswd -c /etc/nginx/.htpasswd exampleuser
  8. Change ownership of the html directory to nginx user

    chown -R www-data:www-data /var/www/html
  9. Make sure the html directory is writable

    chmod -R 755 /var/www/html
  10. Start php7.0-fpm daemon

    service php7.0-fpm start
  11. Start nginx web server

    service nginx start

Optional configuration

  • If you want to use your custom domain to access admin page (e.g.: http://mydomain.internal/admin/settings.php instead of http://pi.hole/admin/settings.php), make sure mydomain.internal is assigned to server_name in /etc/nginx/sites-available/default. E.g.: server_name mydomain.internal;

  • If you want to use block page for any blocked domain subpage (aka Nginx 404), add this to Pi-hole server block in your Nginx configuration file:

    error_page 404 /pihole/index.php;
  • When using nginx to serve Pi-hole, Let's Encrypt can be used to directly configure nginx. Make sure to use your hostname instead of _ in server_name _; line above.

    add-apt-repository ppa:certbot/certbot
    apt-get install certbot python-certbot-nginx
    certbot --nginx -m "$email" -d "$domain" -n --agree-tos --no-eff-email

Last update: February 10, 2020