How can I enable HTTPS (SSL/TLS) for my Pi-hole Web Interface?
Many users run their Pi-hole on Virtual Private Servers and such, meaning that they would need to access the Web Interface via insecure HTTP. Now, you are able to configure Pi-hole so you can securely access your Web Interface, and not cause issues with blocked HTTPS content.
What has changed to allow this?
With the release of v3.2, we have made changes to our default lighttpd config to not automatically enable the SSL engine if /etc/lighttpd/conf-enabled/letsencrypt.conf was detected, as your certificate of pihole.example.com will not match advertiser.com.
Blindly enabling HTTPS for your Pi-hole Web Interface via Let's Encrypt or a Self-Signed certificate causes issues such as:
- Browsing slowdowns on any site visited, as blocked content needed to time out (or load infinitely)
- Web Browser errors, such as mismatched certificates
- Operating system popups on macOS/iOS devices on every site containing blocked content
As you can imagine, that is not a very good end-user experience!
With the instructions below, you will be able to selectively enable HTTPS for your Fully Qualified Domain Name (FQDN), and have it not conflict with blocked HTTPS enabled domains.
How to get started
- Ensure you have a standard fully qualified domain name (e.g:
domain.com,pihole.example.com, etc) that allows you to access your Pi-hole - Deploy an SSL certificate for your FQDN
- Configure
lighttpdto only enable the SSL engine for your FQDN
Assisting users with the first two steps is outside the scope of this article, so you will need to find tutorials that suits your level of skill. Having said that, we'd suggest checking out Certbot by the EFF, which allows you to deploy a free SSL certificate issued by Let's Encrypt. The Certbot site provides you with instructions as to how to install the package, and to generate your first certificate. You will also need to ensure you set up the auto renewal tool, so that your certificate does not expire after 90 days!
How to configure Pi-hole to use an SSL certificate
The lighttpd daemon will need a custom configuration to enable the SSL engine. Fortunately, you can configure all this from /etc/lighttpd/external.conf as this will not get overwritten when running a Pi-hole update.
To start, you will need to create a file called combined.pem as this is the ssl.pemfile that lighttpd expects to see. Run the following command:
sudo cat /etc/letsencrypt/live/pihole.example.com/privkey.pem \
/etc/letsencrypt/live/pihole.example.com/cert.pem | \
sudo tee /etc/letsencrypt/live/pihole.example.com/combined.pem
Next, ensure the lighttpd user www-data can read the required certificates:
sudo chown www-data -R /etc/letsencrypt/live
Now, place the following into /etc/lighttpd/external.conf (again, making sure to subsitute pihole.example.com for your FQDN):
#Loading openssl
server.modules += ( "mod_openssl" )
setenv.add-environment = ("fqdn" => "true")
$SERVER["socket"] == ":443" {
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/combined.pem"
ssl.openssl.ssl-conf-cmd = ("MinProtocol" => "TLSv1.3", "Options" => "-ServerPreference")
}
# Redirect HTTP to HTTPS
$HTTP["scheme"] == "http" {
$HTTP["host"] =~ ".*" {
url.redirect = (".*" => "https://%0$0")
}
}
Finally, be sure to run sudo service lighttpd restart after this change has been made.
Postscript
You can now take advantage of a HTTPS-secured Web Interface! If you wish, you can also host content on your Pi-hole by using /var/www/html/landing.php as your /var/www/html/index.php equivalent.
2018-07-16 Edit:
Removed ssl.use-compression = “disable” as per @person51's post.
2022-12-09 Edit:
With a docker image newer or equal to 2022.04.01 the settings before didn't work anymore because lighttpd software has been updated, so no more old and insecure protocols will be accepted.
References:
- With latest docker-image (2022.04.01) Web-GUI (https) doesn't work anymore: ./run: line 32: Segmentation fault lighttpd -D -f /etc/lighttpd/lighttpd.conf · Issue #1046 · pi-hole/docker-pi-hole · GitHub
- https://wiki.lighttpd.net/
- lighttpd TLS config reference can additionally be found at Mozilla SSL Configuration Generator
