diff --git a/docs/guides/webserver/caddy.md b/docs/guides/webserver/caddy.md deleted file mode 100644 index 94bbeb3..0000000 --- a/docs/guides/webserver/caddy.md +++ /dev/null @@ -1,128 +0,0 @@ -**This is an unsupported configuration created by the community** - -If you'd like to use [Caddy](https://caddyserver.com/) as your main web server with Pi-hole, you'll need to make a few changes. - -!!! note - This guide only deals with setting up caddy as a reverse-proxy and not as a replacement for lighttpd (Although caddy is capable of doing so, but it is beyond the scope of this guide). - -## Modifying lighttpd configuration - -First, change the listen port in this file: `/etc/lighttpd/lighttpd.conf:` - -```lighttpd -server.port = 1080 -``` - -In this case, port 1080 was chosen at random. You can use a custom port. - -BUT ANY CHANGES MADE TO THIS FILE WILL BE LOST ON THE NEXT PI-HOLE UPDATE. - -So if you want a permanent method of changing the lighttpd port and your lighttpd version >= 1.4.46, you can overwrite the port in: `/etc/lighttpd/external.conf` (note the different syntax!): - -```lighttpd -server.port := 1080 -``` - -Next, restart the lighttpd server with either of these commands: - -```bash -sudo systemctl restart lighttpd -``` - -or - -```bash -sudo service lighttpd restart -``` - -## Installing Caddy - -Follow the instructions on the [Caddy download](https://caddyserver.com/docs/download) documentation page. - -## Setting up your Caddyfile - -Now set up a "virtual host" in your Caddyfile (default `/etc/caddy/Caddyfile`). There are many options you can add, but at a minimum, you need to make a "default" host by binding `:80`. This will accept requests for any interface on port `80`. - -### Caddyfile (for Caddy v2) - -``` -http://pi.hole { - reverse_proxy localhost:1080 -} -``` - -- If you'd like to enable HTTPS on your site, make sure your server is reachable via your domain name (ex: myawesomesite.com) and is pointing to the right IP address. -- Additionally you need to open ports :80 and :443 (Apart from the one's required specifically for pi-hole) for your server before setting up HTTPS. - -The following configuration will automatically fetch and setup HTTPS for your domain using Lets-Encrypt - -``` -myawesomesite.com { - reverse_proxy localhost:1080 -} -``` - -Additionally you can make pihole reachable via a subdomain and optionally can you enable Zstandard and Gzip compression as follows: - -``` -pihole.myawesomesite.com { - reverse_proxy localhost:1080 - encode zstd gzip -} -``` - -Finally, run `sudo systemctl caddy reload` to reload Caddy with the new configuration. - -### Caddyfile (for Caddy v1) - -Caddy v1 is no longer actively supported, but the following is a config example if you're running an old installation. - -``` -blackhole:80, pi.hole:80, 0.0.0.0:80 { - root /var/www/html/pihole - log /var/log/caddy/blackhole.log - - rewrite { - ext js - to index.js - } - - proxy / localhost:1080 { - transparent - } -} -``` - -In this example, `blackhole` and `pi.hole` are added as valid names with which to open the admin page. - -## Verifying your setup - -First, make sure that any other sites you're serving from caddy are still functioning. For example, if you have a block for `myawesomesite.com:80` or similar in your Caddyfile, open up a browser to `http://myawesomesite.com` (or `https://` if you have enabled it) and verify it still loads. - -Next, verify you can load the admin page. Open up `http://pi.hole/admin` (or use the IP address of your server) and verify that you can access the admin page. - -Finally, verify that requests for ads are being black holed: - -```console -$ curl -H "Host: badhost" pi.hole/ - - - - - - - -``` - -Replace the URL `pi.hole` with the IP address or alternate DNS name you're using if necessary. - -Lastly, ensure that requests for JavaScript files from advertisement domains are being served properly: - -```bash -curl -H "Host: badhost" pi.hole/malicious.js -var x = "Pi-hole: A black hole for Internet advertisements." -``` - -For more information visit Caddy's documentation [website](https://caddyserver.com/docs/). - -For usage questions or support, visit the [Caddy Community forums](https://caddy.community/). diff --git a/docs/guides/webserver/nginx.md b/docs/guides/webserver/nginx.md deleted file mode 100644 index 0678992..0000000 --- a/docs/guides/webserver/nginx.md +++ /dev/null @@ -1,132 +0,0 @@ -### Notes & Warnings - -- **This is an unsupported configuration created by the community** -- **Replace `7.3` with the PHP version you installed, e.g. if you're using Raspbian Stretch (Debian 9) replace `7.3` with `7.0`.** -- The `php7.3-sqlite3` package must be installed otherwise Networking and Querying will throw an error that it can't access the database. - -### Basic requirements - -1. Stop default lighttpd - - ```bash - service lighttpd stop - ``` - -2. Install necessary packages - - ```bash - apt-get -y install nginx php7.3-fpm php7.3-cgi php7.3-xml php7.3-sqlite3 php7.3-intl apache2-utils - ``` - -3. Disable lighttpd at startup - - ```bash - systemctl disable lighttpd - ``` - -4. Enable php7.3-fpm at startup - - ```bash - systemctl enable php7.3-fpm - ``` - -5. Enable nginx at startup - - ```bash - systemctl enable nginx - ``` - -6. Edit `/etc/nginx/sites-available/default` to: - - ```nginx - 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.3-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 - - ```bash - htpasswd -c /etc/nginx/.htpasswd exampleuser - ``` - -8. Change ownership of the html directory to nginx user - - ```bash - chown -R www-data:www-data /var/www/html - ``` - -9. Make sure the html directory is writable - - ```bash - chmod -R 755 /var/www/html - ``` - -10. Grant the admin panel access to the gravity database - - ```bash - usermod -aG pihole www-data - ``` - -11. Start php7.3-fpm daemon - - ```bash - service php7.3-fpm start - ``` - -12. Start nginx web server - - ```bash - 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;` - -- 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. - - ```bash - 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 - ``` diff --git a/docs/guides/webserver/traefik-nodocker.md b/docs/guides/webserver/traefik-nodocker.md deleted file mode 100644 index 8ec1cf3..0000000 --- a/docs/guides/webserver/traefik-nodocker.md +++ /dev/null @@ -1,77 +0,0 @@ -### Notes & Warnings - -- **This is an unsupported configuration created by the community** -- This describes how to use traefik on a (possibly remote) machine to serve pi-hole via https and a different domain, not how to do this in docker (via docker-compose). - -### Basic requirements - -1. Have a traefik server running anywhere where it can access port 80 of the pihole server. Technically it can run in a docker container though. For LetsEncrypt to work traefik must be reachable on port 80 and 443 from the internet and have the domain.tld pointed at its external address. - -2. The following traefik config (traefik.toml) - - ```toml - debug = false - checkNewVersion = true - logLevel = "INFO" - defaultEntryPoints = ["https","http"] - - [entryPoints] - [entryPoints.http] - address = ":80" - [entryPoints.http.redirect] - entryPoint = "https" - [entryPoints.https] - address = ":443" - [entryPoints.https.tls] - # Optional Security Settings - [retry] - - [docker] - endpoint = "unix:///var/run/docker.sock" - domain = "domain.tld" - watch = true - exposedbydefault = false - - [acme] - email = "emailForLetsEncryptACME" - storage = "acme.json" - storageFile = "/etc/traefik/acme/acme.json" - entryPoint = "https" - OnHostRule = true - [acme.tlsChallenge] - [[acme.domains]] - main = "pihole.domain.tld" - - [file] - watch = true - - [backends] - [backends.pihole] - [backends.pihole.servers.server1] - url = "http://IP-Of-Pihole:80" - - [frontends] - [frontends.pihole] - backend = "pihole" - passHostHeader = true - [frontends.pihole.headers] - STSSeconds = 31536000 - [frontends.pihole.routes.route1] - rule = "Host:pihole.domain.tld" - ``` - -3. Edit your /etc/lighttpd/external.conf to - - ```lighttpd - $SERVER["socket"] == ":80" { - # Ensure the Pi-hole Block Page knows that this is not a blocked domain - setenv.add-environment = ("fqdn" => "true") - - - $HTTP["host"] =~ "^pi\.hole" { - url.redirect = ("^/(.*)" => "https://pihole.domain.tld/$1") - } - } - ``` - -4. Restart pi-hole's lighttpd and traefik, then you should be able to access your pihole via `https://pihole.domain.tld/` diff --git a/docs/guides/webserver/traefik-v2-docker.md b/docs/guides/webserver/traefik-v2-docker.md deleted file mode 100644 index e5e7a50..0000000 --- a/docs/guides/webserver/traefik-v2-docker.md +++ /dev/null @@ -1,69 +0,0 @@ -### Notes & Warnings - -- **This is an unsupported configuration created by the community** -- This describes how to use [Traefik](https://doc.traefik.io/traefik/) v2 in a Docker container (via docker-compose.yml) to serve the Pi-hole web admin interface via https and includes a permenent http -> https redirect. -- This does not describe how to proxy DNS or DHCP requests to Pi-hole, which is not recommended. -- For ACME challenges, the Traefik container may need to be able to resolve the desired Pi-hole hostname without relying on Pi-hole to do so. Provide this via the `extra_hosts` parameter in your Traefik container's config in docker-compose.yml if needed. -- For LetsEncrypt to work Traefik must be reachable on port 80 and 443 from the Internet and have `domain.tld` pointed at its external address. - -### Basic requirements - -1. Have a Traefik v2 Docker container running where it can access port 80 of the Pi-hole server. - -1. The following Traefik static config (passed as `command` arguments to the Traefik container in docker-compose.yml): - - ``` - - "--providers.docker=true" - - "--providers.docker.network=traefik-net" # replace with your configured Docker network name - - "--entrypoints.web.address=:80" - - "--entrypoints.web.http.redirections.entrypoint.to=websecure" - - "--entrypoints.websecure.address=:443" - - "--certificatesresolvers.letsencrypt.acme.httpchallenge=true" - - "--certificatesresolvers.letsencrypt.acme.email=your-email@example.com" - - "--certificatesresolvers.letsencrypt.acme.storage=acme.json" - - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web" - ``` - -1. The next step has 2 scenarios: - - - If Pi-hole is running in a container on the same Docker host as Traefik, put the following `labels` in your Pi-hole container's config in docker-compose.yml: - - ``` - - "traefik.http.routers.pihole.rule=Host(`pihole.domain.tld`)" - - "traefik.http.routers.pihole.entrypoints=websecure" - - "traefik.http.routers.pihole.tls=true" - - "traefik.http.routers.pihole.tls.certresolver=letsencrypt" - - "traefik.http.routers.pihole.tls.domains[0].main=pihole.domain.tld" - - "traefik.http.routers.pihole.tls.domains[0].sans=pihole.domain.tld" - - "traefik.http.services.pihole.loadbalancer.server.port=80" - ``` - - - If Pi-hole is running on a different host, you need to provide the Pi-hole (dynamic) config via a `traefik.yml` file to Traefik. This is best done by bind mounting the local directory containing this file to the `/etc/traefik` directory within the container: - - ``` - # Traefik container config: - volumes: - - './traefik/fileproviders:/etc/traefik' - ``` - - ``` - # traefik.yml dynamic config for Pi-hole: - http: - routers: - pihole: - rule: Host(`pihole.domain.tld`) - entrypoints: websecure - tls: - certresolver: letsencrypt - domains: - - main: pihole.domain.tld - sans: - - pihole.domain.tld - services: - pihole: - loadbalancer: - servers: - - url: "http://pihole.domain.tld/" - ``` - -1. Restart the Traefik and Pi-hole containers, then you should be able to access your pihole via `https://pihole.domain.tld/` diff --git a/mkdocs.yml b/mkdocs.yml index d654a95..7559d64 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -208,11 +208,6 @@ nav: - 'Performance and other issues': guides/misc/tor/performance-issues.md - 'Using DNSSEC': guides/misc/tor/dnssec.md - 'Allowlist and Denylist editing': guides/misc/allowlist-denylist.md - - 'Web server': - #- 'NGINX': guides/webserver/nginx.md - #- 'Caddy': guides/webserver/caddy.md - #- 'Traefik v1 (not in Docker)': guides/webserver/traefik-nodocker.md - - 'Traefik v2 (with Docker)': guides/webserver/traefik-v2-docker.md - 'Router setup': - 'ASUS router': routers/asus.md - 'Fritz!Box (EN)': routers/fritzbox.md