mirror of
https://github.com/pi-hole/docs.git
synced 2024-12-06 19:27:12 +01:00
Merge branch 'master' into upstream-dns-providers
This commit is contained in:
Mark Drobnak
GitHub
+14
-2
@@ -4,6 +4,13 @@ We update the database file periodically and on exit of *FTL*DNS (triggered e.g.
|
||||
|
||||
The location of the database can be configures by the config parameter [`DBFILE`](configfile.md#dbfile). It defaults to `/etc/pihole/pihole-FTL.db`. If the given file does not exist, *FTL*DNS will create a new (empty) database file.
|
||||
|
||||
Another way of controlling the size of the long-term database is setting a maximum age for log queries to keep using the config parameter [`MAXDBDAYS`](configfile.md#maxdbdays). It defaults to 365 days, i.e. queries that are older than one year get periodically removed to limit the growth of the long-term database file.
|
||||
|
||||
The config parameter [`DBIMPORT`](configfile.md#dbimport) controls whether `FTL` loads information from the database on startup. It need to do this to populate the internal datastructure with the most recent history. However, as importing from the database on disk can delay FTL on very large deploys, it can be disabled using this option.
|
||||
|
||||
---
|
||||
### Split database
|
||||
|
||||
You can split your long-term database by periodically rotating the database file (do this only when `pihole-FTL` is *not* running). The individual database contents can easily be merged when required.
|
||||
This could be implemented by running a monthly `cron` job such as:
|
||||
```
|
||||
@@ -13,9 +20,14 @@ sudo service pihole-FTL start
|
||||
```
|
||||
Note that DNS resolution will not be available as long as `pihole-FTL` is stopped.
|
||||
|
||||
Another way of controlling the size of the long-term database is setting a maximum age for log queries to keep using the config parameter [`MAXDBDAYS`](configfile.md#maxdbdays). It defaults to 365 days, i.e. queries that are older than one year get periodically removed to limit the growth of the long-term database file.
|
||||
### Backup database
|
||||
|
||||
The database can be backed up while FTL is running when using the SQLite3 Online backup method, e.g.,
|
||||
```
|
||||
sqlite3 /etc/pihole/pihole-FTL.db ".backup /home/pi/pihole-FTL.db.backup"
|
||||
```
|
||||
will create `/home/pi/pihole-FTL.db.backup` which is a copy of your long-term database.
|
||||
|
||||
The config parameter [`DBIMPORT`](configfile.md#dbimport) controls whether `FTL` loads information from the database on startup. It need to do this to populate the internal datastructure with the most recent history. However, as importing from the database on disk can delay FTL on very large deploys, it can be disabled using this option.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,62 @@
|
||||
|
||||
If you'd like to use Caddy as your main web server with Pi-hole, you'll need to make a few changes.
|
||||
|
||||
## Modifying lighttpd configuration
|
||||
First, change the listen port in this file:
|
||||
`/etc/lighttpd/lighttpd.conf:`
|
||||
|
||||
```
|
||||
server.port = 1080
|
||||
```
|
||||
|
||||
In this case I chose 1080 somewhat at random. Use whatever feels right to you.
|
||||
|
||||
Next, restart the lighttpd server with either of these commands:
|
||||
- `sudo systemctl restart lighttpd`
|
||||
- `sudo service lighttpd restart.`
|
||||
|
||||
## Setting up your Caddyfile
|
||||
Now we need to set up a "virtual host" in our Caddyfile (default `/etc/caddy/Caddyfile`). There are many more options you can add, but at bare minimum you need to make a "default" host by binding `0.0.0.0:80` which will accept requests for any host.
|
||||
```YAML
|
||||
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 case I've chosen to also add blackhole and pi.hole as valid names to open the admin page with.
|
||||
|
||||
Finally, restart your Caddy server:
|
||||
- `sudo service caddy restart`
|
||||
|
||||
## Verifying your set up
|
||||
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` in your Caddyfile, open up a browser to `http://myawesomesite.com` 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:
|
||||
```BASH
|
||||
$ 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."
|
||||
```
|
||||
@@ -0,0 +1,88 @@
|
||||
### Notes & Warnings
|
||||
- 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;
|
||||
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 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 html directory to nginx user
|
||||
`chown -R www-data:www-data /var/www/html`
|
||||
|
||||
9. Make sure html directory is writable
|
||||
`chmod -R 755 /var/www/html`
|
||||
|
||||
10. Start php7.0-fpm daemon
|
||||
`service php7.0-fpm start`
|
||||
|
||||
11. 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
|
||||
```
|
||||
|
||||
@@ -0,0 +1,85 @@
|
||||
### What to Whitelist or Blacklist
|
||||
|
||||
[This extension for Google Chrome](https://chrome.google.com/webstore/detail/whitelist-assistant-by-dn/fdmpekabnlekabjlimjkfmdjajnddgpc) can help you in finding out which domains you need to whitelist.
|
||||
|
||||
|
||||
### How to Whitelist or Blacklist
|
||||
|
||||
There are scripts to aid users in adding or removing domains to the whitelist or blacklist.
|
||||
|
||||
The scripts will first parse `whitelist.txt` or `blacklist.txt` for any changes, and if any additions or deletions are detected, it will reload `dnsmasq` so that they are effective immediately.
|
||||
|
||||
Each script accepts the following parameters:
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th><code>[domain]</code></th>
|
||||
<td>Fully qualified domain name you wish to add or remove. You can pass any number of domains.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th><code>-d</code></th>
|
||||
<td>Removal mode. Domains will be removed from the list, rather than added</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th><code>-nr</code></th>
|
||||
<td>Update blacklist without refreshing dnsmasq</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th><code>-f</code></th>
|
||||
<td>Force delete cached blocklist content</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th><code>-q</code></th>
|
||||
<td>Quiet mode. Console output is minimal. Useful for calling from another script (see <code>gravity.sh</code>)</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
Domains passed are parsed by the script to ensure they are valid domains. If a domain is invalid it will be ignored.
|
||||
|
||||
|
||||
##### Example `pihole -w` usages
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th><code>pihole -w domain1 [domain2...]</code></th>
|
||||
<td>Attempt to add one or more domains to the whitelist and reload dnsmasq.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th><code>pihole -w -nr domain1 [domain2...]</code></th>
|
||||
<td>Attempt to add one or more domains to the whitelist, but do not reload dnsmasq.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th><code>pihole -w -f domain1 [domain2...]</code></th>
|
||||
<td>Attempt to add one or more domains to the whitelist and force dnsmasq to reload</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
To remove domains from the whitelist:
|
||||
Add `-d` as an additional argument (e.g `pihole -w -d domain1 [domain2...]`)
|
||||
|
||||
|
||||
##### Example `pihole -b` usages
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th><code>pihole -b domain1 [domain2...]</code></th>
|
||||
<td>Attempt to add one or more domains to the blacklist and reload dnsmasq.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th><code>pihole -b -nr domain1 [domain2...]</code></th>
|
||||
<td>Attempt to add one or more domains to the blacklist, but do not reload dnsmasq.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th><code>pihole -b -f domain1 [domain2...]</code></th>
|
||||
<td>Attempt to add one or more domains to the blacklist and force dnsmasq to reload</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
To remove domains from the blacklist:
|
||||
Add `-d` as an additional argument (e.g `pihole -b -d domain1 [domain2...]`)
|
||||
+4
-1
@@ -1,4 +1,4 @@
|
||||
site_name: "Pi-hole documentation for v4.0+"
|
||||
site_name: "Pi-hole documentation"
|
||||
site_url: https://docs.pi-hole.net
|
||||
repo_url: "https://github.com/pi-hole/pi-hole/"
|
||||
edit_uri: ""
|
||||
@@ -64,6 +64,9 @@ pages:
|
||||
- 'Pi-hole as All-Around DNS Solution': guides/unbound.md
|
||||
- 'Configuring DNS-Over-HTTPS on Pi-hole': guides/dns-over-https.md
|
||||
- 'Upstream DNS Providers': guides/upstream-dns-providers.md
|
||||
- 'Editing Whitelist and Blacklist': guides/whitelist-blacklist.md
|
||||
- 'Configuring NGINX for Pi-hole': guides/nginx-configuration.md
|
||||
- 'Configuring Caddy for Pi-hole': guides/caddy-configuration.md
|
||||
- 'Pi-hole and OpenVPN Server':
|
||||
- 'Overview': 'guides/vpn/overview.md'
|
||||
- 'Installation': 'guides/vpn/installation.md'
|
||||
|
||||
Reference in New Issue
Block a user