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 snippets/fastcgi-php.conf;
                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;
  1. Create 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

  2. Change ownership of html directory to nginx user
    chown -R www-data:www-data /var/www/html

  3. Make sure html directory is writable
    chmod -R 755 /var/www/html

  4. Start php7.0-fpm daemon
    service php7.0-fpm start

  5. Start nginx webserver
    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