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