pi-hole/docs
1
0
Fork 0
mirror of https://github.com/pi-hole/docs.git synced 2024-12-06 19:27:12 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Remove webserver community guides - they're outdated and it is probably time for a refresh in any case - these can come later
editorconfig-checker / editorconfig-checker (push) Has been cancelled
Details
Check for merge conflicts / main (push) Has been cancelled
Details

Browse Source 
Signed-off-by: Adam Warner <me@adamwarner.co.uk>
This commit is contained in:
Adam Warner
2024-10-21 19:12:18 +00:00
parent 08b9ddd3fe
commit 49c32e2cf9
5 changed files with 0 additions and 411 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/guides/webserver/caddy.md
-128
View File
@@ -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/
<html>
<head>
<script>window.close();</script>
</head>
<body>
</body>
</html>
```
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/).
docs/guides/webserver/nginx.md
-132
View File
@@ -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
```
docs/guides/webserver/traefik-nodocker.md
-77
View File
@@ -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/`
docs/guides/webserver/traefik-v2-docker.md
-69
View File
@@ -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/`
mkdocs.yml
-5
View File
@@ -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