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

Merge pull request #197 from XhmikosR/lint-md

Browse Source 
Many Markdown tweaks
This commit is contained in:
DL6ER
2019-12-20 08:34:43 +01:00
committed by GitHub
parent aa8e82dbbe 825db6caa4
commit fcddd4b993
49 changed files with 978 additions and 582 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+39 -31
View File
@@ -11,54 +11,62 @@ The Pi-hole[®](https://pi-hole.net/trademark-rules-and-brand-guidelines/) is a
This repo is the source for the official [Pi-hole documentation](https://docs.pi-hole.net/).
### How to contribute.
To add a new link on the navigation panel you need to edit the `mkdocs.yml` file in the root of the repo. There is a guide for building the navbar [on the mkdocs wiki](https://www.mkdocs.org/user-guide/configuration/#nav)
To add a new document or guide.
- Navigate to the directory where it will be hosted.
EG. guides are in `docs/guides`
EG. guides are in `docs/guides`
- Create the file using a URL friendly filename.
EG. `docs/guides/url-friendly.md`
EG. `docs/guides/url-friendly.md`
- Edit your document using Markdown, there are loads of resources available for the correct syntax.
### Testing your changes.
Whilst working on this repo, it is advised that you review your own changes locally before committing them. The `mkdocs serve` command can be used to live preview your changes (as you type) on your local machine.
Please make sure you fork the repo and change the clone URL in the example below for your fork:
- Linux Mint / Ubuntu instructions (tested on Linux Mint 18):
- Preparations (only required once):
```bash
git clone https://github.com/YOUR-USERNAME/docs
cd docs
sudo pip install mkdocs
sudo pip install mkdocs-material markdown-include
```
- Running the docs server:
```bash
mkdocs serve --dev-addr 0.0.0.0:8000
```
- Preparations (only required once):
```bash
git clone https://github.com/YOUR-USERNAME/docs
cd docs
sudo pip install mkdocs
sudo pip install mkdocs-material markdown-include
```
- Running the docs server:
```bash
mkdocs serve --dev-addr 0.0.0.0:8000
```
- Fedora Linux instructions (tested on Fedora Linux 28):
- Preparations (only required once):
```bash
git clone https://github.com/YOUR-USERNAME/docs
cd docs
pip install mkdocs --user
pip install mkdocs-material markdown-include --user
```
- Running the docs server:
```bash
mkdocs serve --dev-addr 0.0.0.0:8000
```
- Preparations (only required once):
```bash
git clone https://github.com/YOUR-USERNAME/docs
cd docs
pip install mkdocs --user
pip install mkdocs-material markdown-include --user
```
- Running the docs server:
```bash
mkdocs serve --dev-addr 0.0.0.0:8000
```
- Docker instructions:
- One-shot run:
```bash
docker run -v `pwd`:/opt/app/ -w /opt/app/ -p 8000:8000 -it python:2-alpine \
sh -c "pip install --user mkdocs mkdocs-material markdown-include && \
/root/.local/bin/mkdocs serve --dev-addr 0.0.0.0:8000"
```
- One-shot run:
```bash
docker run -v `pwd`:/opt/app/ -w /opt/app/ -p 8000:8000 -it python:2-alpine \
sh -c "pip install --user mkdocs mkdocs-material markdown-include && \
/root/.local/bin/mkdocs serve --dev-addr 0.0.0.0:8000"
```
After these commands, the current branch is accessible through your favorite browser at http://localhost:8000
docs/core/pihole-command.md
+35 -9
View File
@@ -1,4 +1,6 @@
---
title: The pihole command - Pi-hole documentation
---
Pi-hole makes use of many commands, and here we will break down those required to administer the program via the Command Line Interface.
@@ -33,6 +35,7 @@ Pi-hole makes use of many commands, and here we will break down those required t
[Checkout](#checkout) | `pihole checkout`
### Core Script
| | |
-------------- | --------------
Help Command | `pihole --help`
@@ -42,6 +45,7 @@ Example Usage | `pihole -b advertiser.example.com`
The core script of Pi-hole provides the ability to tie many DNS related functions into a simple and user friendly management system, so that one may easily block unwanted content such as advertisements. For both the Command Line Interface (CLI) and Web Interface, we achieve this through the `pihole` command (this helps minimise code duplication, and allows users to read exactly what's happening using `bash` scripting). This "wrapper" elevates the current user (whether it be your own user account, or `www-data`) using `sudo`, but restricts the elevation to solely what can be called through the wrapper.
### Whitelisting, Blacklisting and Regex
| | |
-------------- | --------------
Help Command | `pihole -w --help`, `pihole -b --help`, `pihole -regex --help`, `pihole -wild --help`
@@ -57,12 +61,13 @@ See [Regex Blocking](/ftldns/regex/overview/) for more information about using R
* Each domain is validated using regex (except when using `-regex`), to ensure invalid domains and IDNs are not added
* A whitelisted domain gets added or removed from `/etc/pihole/whitelist.txt`
* A blacklisted domain gets added or removed from `/etc/pihole/blacklist.txt`
* On either list type, `gravity.sh` is then called to consolidate an updated copy of `gravity.list`, and the DNS server is reloaded
* On either list type, `gravity.sh` is then called to consolidate an updated copy of `gravity.list`, and the DNS server is reloaded
* A regex blacklisted domain gets added or removed from `/etc/pihole/regex.list`
* A wildcard domain gets converted into regex and added or removed from `/etc/pihole/regex.list`
* For both regex-based commands, `gravity.sh` is then called to restart the DNS server
* For both regex-based commands, `gravity.sh` is then called to restart the DNS server
### Debugger
| | |
-------------- | --------------
Help Command | N/A
@@ -72,6 +77,7 @@ Example Usage | [`pihole debug`](https://discourse.pi-hole.net/t/the-pihole-co
The Pi-hole debugger will attempt to diagnose any issues, and link to an FAQ with instructions as to how an admin can rectify the issue. Once the debugger has finished, the admin has the option to upload the generated log to the [Pi-hole developers](https://github.com/orgs/pi-hole/teams/debug/members), who can help with diagnosing and rectifying persistent issues.
### Log Flush
| | |
-------------- | --------------
Help Command | N/A
@@ -81,6 +87,7 @@ Example Usage | [`pihole flush`](https://discourse.pi-hole.net/t/the-pihole-co
When invoked manually, this command will allow you to empty Pi-hole's log, which is located at `/var/log/pihole.log`. The command also serves to rotate the log daily, if the `logrotate` application is installed.
### Reconfigure
| | |
-------------- | --------------
Help Command | N/A
@@ -92,11 +99,12 @@ There are times where the administrator will need to repair or reconfigure the P
**Basic Script Process**:
* [`basic-install.sh`](https://github.com/pi-hole/pi-hole/blob/master/automated%20install/basic-install.sh) will be run
* **Reconfigure** will run through the first-time installation prompts, asking for upstream DNS provider, IP protocols, etc
* **Repair** will retain your existing settings, and will attempt to repair any scripts or dependencies as necessary
* **Reconfigure** will run through the first-time installation prompts, asking for upstream DNS provider, IP protocols, etc
* **Repair** will retain your existing settings, and will attempt to repair any scripts or dependencies as necessary
* The rest of `basic-install.sh` will then run as appropriate
### Tail
| | |
-------------- | --------------
Help Command | N/A
@@ -106,6 +114,7 @@ Example Usage | [`pihole tail`](https://discourse.pi-hole.net/t/the-pihole-com
Since Pi-hole will log DNS queries by default, using this command to watch the log in real-time can be useful for debugging a problematic site, or even just for sheer curiosities sake.
### Admin
| | |
-------------- | --------------
Help Command | `pihole -a --help`
@@ -115,6 +124,7 @@ Example Usage | `pihole -a -p secretpassword`
Detailed information on this is [found here](#web-script).
### Chronometer
| | |
-------------- | --------------
Help Command | `pihole -c --help`
@@ -127,6 +137,7 @@ Chronometer is a console dashboard of real-time stats, which can be displayed vi
<br/><sub><a href="https://www.reddit.com/r/pihole/comments/6ldjna/pihole_setup_went_so_well_at_home_for_the_1st/">Image courtesy of /u/super_nicktendo22</a></sub>
### Gravity
| | |
-------------- | --------------
Help Command | N/A
@@ -140,7 +151,7 @@ Gravity is one of the most important scripts of Pi-hole. Its main purpose is to
* It will determine Internet connectivity, and give time for `dnsmasq` to be resolvable on low-end systems if has just been restarted
* It extracts all URLs and domains from `/etc/pihole/adlists.list`
* It runs through each URL, downloading it if necessary
* `curl` checks the servers `Last-Modified` header to ensure it is getting a newer version
* `curl` checks the servers `Last-Modified` header to ensure it is getting a newer version
* It will attempt to parse the file into a domains-only format if necessary
* Lists are merged, comments removed, sorted uniquely and stored as `list.preEventHorizon`
* Whitelisted entries within `/etc/pihole/whitelist.txt` are removed from `list.preEventHorizon` and saved into a temporary file
@@ -148,19 +159,21 @@ Gravity is one of the most important scripts of Pi-hole. Its main purpose is to
* Gravity cleans up temporary content and reloads the DNS server
### Logging
| | |
-------------- | --------------
Help Command | `pihole logging --help`
Script Location | [`/usr/local/bin/pihole`](https://github.com/pi-hole/pi-hole/blob/master/pihole)
Script Location | [`/usr/local/bin/pihole`](https://github.com/pi-hole/pi-hole/blob/master/pihole)
Example Usage | [`pihole logging off`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#logging)
This command specifies whether the Pi-hole log should be used, by commenting out `log-queries` within `/etc/dnsmasq.d/01-pihole.conf` and flushing the log.
### Query
| | |
--------------- | ---------------
Help Command | `pihole query --help`
Script Location | [`/usr/local/bin/pihole`](https://github.com/pi-hole/pi-hole/blob/master/pihole)
Script Location | [`/usr/local/bin/pihole`](https://github.com/pi-hole/pi-hole/blob/master/pihole)
Example Usage | [`pihole -q -exact -adlist example.domain.com`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#adlist-query)
This command will query your whitelist, blacklist, wildcards and adlists for a specified domain.
@@ -175,6 +188,7 @@ This command will query your whitelist, blacklist, wildcards and adlists for a s
* Output is determined by the specified options, ensuring that a file name is only printed once
### Update
| | |
-------------- | --------------
Help Command | `pihole update`
@@ -190,6 +204,7 @@ Check Pi-hole Core, Web Interface and FTL repositories to determine what upgrade
* [`basic-install.sh`](https://github.com/pi-hole/pi-hole/blob/master/automated%20install/basic-install.sh) is run
### Version
| | |
--------------- | ---------------
Help Command | `pihole version`
@@ -199,6 +214,7 @@ Example Usage | `pihole -v -c`
Shows installed versions of Pi-hole, Web Interface & FTL. Also provides options to configure which details will be printed, such as current version, latest version, hash and subsystem.
### Uninstall
| | |
-------------- | --------------
Help Command | N/A
@@ -208,6 +224,7 @@ Example Usage | [`pihole uninstall`](https://discourse.pi-hole.net/t/the-pihol
Uninstall Pi-hole from your system, giving the option to remove each dependency individually.
### Status
| | |
-------------- | --------------
Help Command | N/A
@@ -217,6 +234,7 @@ Example Usage | [`pihole status`](https://discourse.pi-hole.net/t/the-pihole-c
Display the running status of Pi-hole's DNS and blocking services.
### Enable & Disable
| | |
-------------- | --------------
Help Command | `pihole disable --help`
@@ -226,6 +244,7 @@ Example Usage | [`pihole disable 5m`](https://discourse.pi-hole.net/t/the-piho
Toggle Pi-hole's ability to block unwanted domains. The disable option has the option to set a specified time before blocking is automatically re-enabled.
### Restart DNS
| | |
-------------- | --------------
Help Command | N/A
@@ -235,10 +254,11 @@ Example Usage | [`pihole restartdns`](https://discourse.pi-hole.net/t/the-piho
Restart Pi-hole's DNS service.
### Checkout
| | |
-------------- | --------------
Help Command | `pihole checkout --help`
Script Location | [`/opt/pihole/piholeCheckout.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/piholeCheckout.sh)
Script Location | [`/opt/pihole/piholeCheckout.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/piholeCheckout.sh)
Example Usage | [`pihole checkout dev`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#checkout)
Switch Pi-hole subsystems to a different GitHub branch. An admin can specify repositories as well as branches.
@@ -257,6 +277,7 @@ Switch Pi-hole subsystems to a different GitHub branch. An admin can specify rep
[Interface](#interface) | `pihole -a interface`
### Web Script
| | |
-------------- | --------------
Help Command | `pihole -a --help`
@@ -266,6 +287,7 @@ Example Usage | `pihole -a -p secretpassword`
Set options for the Web Interface. This script is used to tie in all Web Interface features which are not already covered by the [Core Script](#core-script).
### Password
| | |
-------------- | --------------
Help Command | N/A
@@ -275,6 +297,7 @@ Example Usage | [`pihole -a -p secretpassword`](https://discourse.pi-hole.net/
Set Web Interface password. Password can be entered as an option (e.g: `pihole -a -p secretpassword`), or separately as to not display on screen (e.g: `pihole -a -p`).
### Temperature Unit
| | |
-------------- | --------------
Help Command | N/A
@@ -284,6 +307,7 @@ Example Usage | [`pihole -a -c`](https://discourse.pi-hole.net/t/the-pihole-co
Set specified temperature unit as preferred type. This preference will affect the Web Interface, as well as Chronometer.
### Host Record
| | |
-------------- | --------------
Help Command | `pihole -a hostrecord --help`
@@ -293,6 +317,7 @@ Example Usage | `pihole -a hostrecord home.domain.com 192.168.1.1`
Add A & AAAA records to the DNS, to be associated with an IPv4/IPv6 address.
### Email Address
| | |
-------------- | --------------
Help Command | N/A
@@ -302,6 +327,7 @@ Example Usage | `pihole -a email admin@domain.com`
Set an administrative contact address for the Block Page. This will create a hyperlink on the Block Page to the specified email address.
### Interface
| | |
-------------- | --------------
Help Command | `pihole -a interface --help`
docs/ftldns/blockingmode.md
+26 -3
View File
@@ -3,12 +3,15 @@ Pi-hole *FTL*DNS supports two different methods for blocking queries. Both have
This setting can be updated by sending `SIGHUP` to `pihole-FTL` (`sudo killall -SIGHUP pihole-FTL`).
## Pi-hole's unspecified IP blocking (default)
`/etc/pihole/pihole-FTL.conf` setting:
```
BLOCKINGMODE=NULL
```
Blocked queries will be answered with the unspecified address
```
;; QUESTION SECTION:
;doubleclick.net. IN ANY
@@ -23,22 +26,26 @@ doubleclick.net. 2 IN AAAA ::
Following [RFC 3513, Internet Protocol Version 6 (IPv6) Addressing Architecture, section 2.5.2](https://tools.ietf.org/html/rfc3513#section-2.5.2), the address `0:0:0:0:0:0:0:0` (or `::` for short) is the unspecified address. It must never be assigned to any node and indicates the absence of an address. Following [RFC1122, section 3.2](https://tools.ietf.org/html/rfc1122#section-3.2), the address `0.0.0.0` can be understood as the IPv4 equivalent of `::`.
##### Advantages
- The client does not even try to establish a connection for the requested website
- Speedup and less traffic
- Solves potential HTTPS timeouts as requests are never performed
- No need to run a webserver on your Pi-hole (reduces complexity when running other web services on the same machine)
##### Disadvantage
- Blocking page cannot be shown and whitelisting has to be performed from the dashboard or CLI
## Pi-hole's IP (IPv6 NODATA) blocking
`/etc/pihole/pihole-FTL.conf` setting:
```
BLOCKINGMODE=IP-NODATA-AAAA
```
Blocked queries will be answered with the local IPv4 addresses of your Pi-hole (as configured in your `setupVars.conf` file). Blocked AAAA queries will answered with `NODATA-IPV6` and clients will only try to reach your Pi-hole over its static IPv4 address
```
;; QUESTION SECTION:
;doubleclick.net. IN ANY
@@ -48,21 +55,25 @@ doubleclick.net. 2 IN A 192.168.2.11
```
##### Advantage
- Shows blocking page from which blocked domains can be whitelisted
- Serves IPv4-only replies and hence mitigates issues with rotating IPv6 prefixes
##### Disadvantages
- Requires a webserver to run on your Pi-hole
- May cause time-outs for HTTPS content even with properly configured firewall rules
## Pi-hole's full IP blocking
`/etc/pihole/pihole-FTL.conf` setting:
```
BLOCKINGMODE=IP
```
Blocked queries will be answered with the local IP addresses of your Pi-hole (as configured in your `setupVars.conf` file)
```
;; QUESTION SECTION:
;doubleclick.net. IN ANY
@@ -71,41 +82,53 @@ Blocked queries will be answered with the local IP addresses of your Pi-hole (as
doubleclick.net. 2 IN A 192.168.2.11
doubleclick.net. 2 IN AAAA fda2:2001:4756:0:ab27:beff:ef37:4242
```
##### Advantage
- Shows blocking page from which blocked domains can be whitelisted
##### Disadvantages
- Requires a webserver to run on your Pi-hole
- May cause time-outs for HTTPS content even with properly configured firewall rules
- May cause problems with alternating prefixes on IPv6 addresses (see `IP-AAAA-NODATA`)
## Pi-hole's NXDOMAIN blocking
`/etc/pihole/pihole-FTL.conf` setting:
```
BLOCKINGMODE=NXDOMAIN
```
Blocked queries will be answered with an empty response (no answer section) and status `NXDOMAIN` (*no such domain*)
```
;; QUESTION SECTION:
;doubleclick.net. IN ANY
```
##### Advantages & Disadvantages
Similar to `NULL` blocking, but experiments suggest that clients may try to resolve blocked domains more often compared to `NULL` blocking.
## Pi-hole's NODATA blocking
`/etc/pihole/pihole-FTL.conf` setting:
```
BLOCKINGMODE=NODATA
```
Blocked queries will be answered with an empty response (no answer section) and status `NODATA` (domain exists but there is no record for the requested query type)
```
;; QUESTION SECTION:
;doubleclick.net. IN ANY
```
##### Advantages & Disadvantages
Similar to `NXDOMAIN` blocking. Clients might have a better acceptance of `NODATA` replies compared to `NXDOMAIN` replies.
{!abbreviations.md!}
docs/ftldns/compile.md
+14 -4
View File
@@ -1,13 +1,18 @@
We pre-compile *FTL*DNS for you to save you the trouble of compiling anything yourself. However, sometimes you may want to make your own modifications. To test them, you have to compile *FTL*DNS from source. Luckily, you don't have to be a programmer to build *FTL*DNS from source and install it on your system; you only have to know the basics we provide in here. With just a few commands, you can build *FTL*DNS from source like a pro.
#### Installing the Required Software
First, we'll install the basic software you'll need to compile from source, like the GCC compiler and other utilities.
Install them by running the following command in a terminal:
###### Debian / Ubuntu / Raspbian
```bash
sudo apt install build-essential libgmp-dev m4
```
###### Fedora
```bash
sudo dnf install gcc gmp-devel gmp-static m4
```
@@ -15,7 +20,8 @@ sudo dnf install gcc gmp-devel gmp-static m4
---
You'll also need to compile `nettle` as *FTL*DNS uses `libnettle` for handling DNSSEC. Compile and install a recent version of `nettle` (we tested 3.4):
```
```bash
wget https://ftp.gnu.org/gnu/nettle/nettle-3.4.tar.gz
tar -xvzf nettle-3.4.tar.gz
cd nettle-3.4
@@ -25,8 +31,10 @@ sudo make install
```
#### Get the *FTL*DNS source
Now, clone the *FTL*DNS repo (or your own fork) to get the source code of *FTL*DNS:
```
```bash
git clone https://github.com/pi-hole/FTL.git
cd FTL
```
@@ -34,13 +42,15 @@ cd FTL
If you want to build another branch and not `master`, use checkout to get to this branch (e.g. `git checkout development`).
*FTL*DNS can now be compiled and installed:
```
```bash
make -j 4
sudo make install
```
Finally, restart *FTL*DNS to use the new binary:
```
```bash
sudo service pihole-FTL restart
```
docs/ftldns/configfile.md
+141 -61
View File
@@ -1,131 +1,211 @@
You can create a file `/etc/pihole/pihole-FTL.conf` that will be read by *FTL*DNS on startup.
Possible settings (**the option shown first is the default**):
### DNS settings
#### `BLOCKINGMODE=NULL|IP-NODATA-AAAA|IP|NXDOMAIN` {#blocking_mode data-toc-label='Blocking Mode'}
How should `FTL` reply to blocked queries?<br>
**[More details](blockingmode.md)**
### Statistics settings
#### `MAXLOGAGE=24.0` {#maxlogage data-toc-label='Max Log Age'}
Up to how many hours of queries should be imported from the database and logs? Maximum is 24.0
<hr/>
Up to how many hours of queries should be imported from the database and logs? Maximum is 24.0
---
#### `PRIVACYLEVEL=0|1|2|3|4` {#privacylevel data-toc-label='Privacy Level'}
Which privacy level is used?<br>
Which privacy level is used?<br>
**[More details](privacylevels.md)**
<hr/>
---
#### `IGNORE_LOCALHOST=no|yes` {#ignore_localhost data-toc-label='Ignore localhost'}
Should `FTL` ignore queries coming from the local machine?
<hr/>
Should `FTL` ignore queries coming from the local machine?
---
#### `AAAA_QUERY_ANALYSIS=yes|no` {#aaaa_query_analysis data-toc-label='AAAA Query Analysis'}
Allow `FTL` to analyze AAAA queries from pihole.log?
<hr/>
Allow `FTL` to analyze AAAA queries from pihole.log?
---
#### `ANALYZE_ONLY_A_AND_AAAA=false|true` {#analyze_only_a_and_aaaa data-toc-label='Analyze A and AAAA Only'}
Should `FTL` only analyze A and AAAA queries?
Should `FTL` only analyze A and AAAA queries?
### Socket settings
#### `SOCKET_LISTENING=localonly|all` {#socket_listening data-toc-label='Socket Listening'}
Listen only for local socket connections or permit all connections
<hr/>
Listen only for local socket connections or permit all connections
---
#### `FTLPORT=4711` {#ftlport data-toc-label='FTLDNS Port'}
On which port should FTL be listening?
On which port should FTL be listening?
### Host name resolution
#### `RESOLVE_IPV6=yes|no` {#resolve_ipv6 data-toc-label='Resolve IPV6'}
Should `FTL` try to resolve IPv6 addresses to host names?
<hr/>
Should `FTL` try to resolve IPv6 addresses to host names?
---
#### `RESOLVE_IPV4=yes|no` {#resolve_ipv4 data-toc-label='Resolve IPV4'}
Should `FTL` try to resolve IPv4 addresses to host names?
Should `FTL` try to resolve IPv4 addresses to host names?
### Database settings
**[Further details concerning the database](database.md)**
#### `DBIMPORT=yes|no` {#dbimport data-toc-label='DB Import'}
Should `FTL` load information from the database on startup to be aware of the most recent history?
<hr/>
Should `FTL` load information from the database on startup to be aware of the most recent history?
---
#### `MAXDBDAYS=365` {#maxdbdays data-toc-label='Max DB Days'}
How long should queries be stored in the database? Setting this to `0` disables the database
<hr/>
How long should queries be stored in the database? Setting this to `0` disables the database
---
#### `DBINTERVAL=1.0` {#dbinterval data-toc-label='DB Interval'}
How often do we store queries in FTL's database [minutes]?
<hr/>
How often do we store queries in FTL's database [minutes]?
---
#### `DBFILE=/etc/pihole/pihole-FTL.db` {#dbfile data-toc-label='DB File'}
Specify path and filename of FTL's SQLite3 long-term database. Setting this to `DBFILE=` disables the database altogether
Specify path and filename of FTL's SQLite3 long-term database. Setting this to `DBFILE=` disables the database altogether
### File options
#### `LOGFILE=/var/log/pihole-FTL.log` {#file_LOGFILE data-toc-label='Log file'}
Location of FTL's log file. If you want to move the log file to a different place, also consider [this FAQ article](https://discourse.pi-hole.net/t/moving-the-pi-hole-log-to-another-location-device/2041).
Location of FTL's log file. If you want to move the log file to a different place, also consider [this FAQ article](https://discourse.pi-hole.net/t/moving-the-pi-hole-log-to-another-location-device/2041).
#### `PIDFILE=/var/run/pihole-FTL.pid` {#file_PIDFILE data-toc-label='Process identifier file'}
File which contains the PID of FTL's main process.
File which contains the PID of FTL's main process.
#### `PORTFILE=/var/run/pihole-FTL.port` {#file_PORTFILE data-toc-label='Port file'}
File containing the port FTL's API is listening on.
File containing the port FTL's API is listening on.
#### `SOCKETFILE=/var/run/pihole/FTL.sock` {#file_SOCKETFILE data-toc-label='Socket file'}
File containing the socket FTL's API is listening on.
File containing the socket FTL's API is listening on.
#### `SETUPVARSFILE=/etc/pihole/setupVars.conf` {#file_SETUPVARSFILE data-toc-label='setupVars file'}
Config file of Pi-hole containing, e.g., the current blocking status (do not change).
Config file of Pi-hole containing, e.g., the current blocking status (do not change).
#### `AUDITLISTFILE=/etc/pihole/auditlog.list` {#file_AUDITLISTFILE data-toc-label='Audit list file'}
List containing the audited domains.
List containing the audited domains.
#### `MACVENDORDB=/etc/pihole/macvendor.db` {#file_MACVENDORDB data-toc-label='MacVendor database file'}
Database containing MAC -> Vendor information for the network table.
Database containing MAC -> Vendor information for the network table.
### Debugging options
#### `DEBUG_ALL=false|true` {#debug_all data-toc-label='Debug All'}
Enable all debug flags. If this is set to true, all other debug config options are ignored.
<hr/>
Enable all debug flags. If this is set to true, all other debug config options are ignored.
---
#### `DEBUG_DATABASE=false|true` {#debug_database data-toc-label='Debug Database'}
Print debugging information about database actions. This prints performed SQL statements as well as some general information such as the time it took to store the queries and how many have been saved to the database.
<hr/>
Print debugging information about database actions. This prints performed SQL statements as well as some general information such as the time it took to store the queries and how many have been saved to the database.
---
#### `DEBUG_NETWORKING=false|true` {#debug_networking data-toc-label='Debug networking'}
Prints a list of the detected interfaces on startup of `pihole-FTL`. Also prints whether these interfaces are IPv4 or IPv6 interfaces.
<hr/>
Prints a list of the detected interfaces on startup of `pihole-FTL`. Also prints whether these interfaces are IPv4 or IPv6 interfaces.
---
#### `DEBUG_LOCKS=false|true` {#debug_locks data-toc-label='Debug Locks'}
Print information about shared memory locks. Messages will be generated when waiting, obtaining, and releasing a lock.
<hr/>
Print information about shared memory locks. Messages will be generated when waiting, obtaining, and releasing a lock.
---
#### `DEBUG_QUERIES=false|true` {#debug_queries data-toc-label='Debug Queries'}
Print extensive query information (domains, types, replies, etc.). This has always been part of the legacy `debug` mode of `pihole-FTL`.
<hr/>
Print extensive query information (domains, types, replies, etc.). This has always been part of the legacy `debug` mode of `pihole-FTL`.
---
#### `DEBUG_FLAGS=false|true` {#debug_flags data-toc-label='Debug Flags'}
Print flags of queries received by the DNS hooks. Only effective when `DEBUG_QUERIES` is enabled as well.
<hr/>
Print flags of queries received by the DNS hooks. Only effective when `DEBUG_QUERIES` is enabled as well.
---
#### `DEBUG_SHMEM=false|true` {#debug_shmem data-toc-label='Debug Shared Memory'}
Print information about shared memory buffers. Messages are either about creating or enlarging shmem objects or string injections.
<hr/>
Print information about shared memory buffers. Messages are either about creating or enlarging shmem objects or string injections.
---
#### `DEBUG_GC=false|true` {#debug_gc data-toc-label='Debug GC'}
Print information about garbage collection (GC): What is to be removed, how many have been removed and how long did GC take.
<hr/>
Print information about garbage collection (GC): What is to be removed, how many have been removed and how long did GC take.
---
#### `DEBUG_ARP=false|true` {#debug_arp data-toc-label='Debug ARP'}
Print information about ARP table processing: How long did parsing take, whether read MAC addresses are valid, and if the `macvendor.db` file exists.
<hr/>
Print information about ARP table processing: How long did parsing take, whether read MAC addresses are valid, and if the `macvendor.db` file exists.
---
#### `DEBUG_REGEX=false|true` {#debug_regex data-toc-label='Debug REGEX'}
Controls if *FTL*DNS should print extended details about regex matching into `pihole-FTL.log`.<br>
Due to legacy reasons, we also support the following setting to be used for enabling the same functionality:<br>
`REGEX_DEBUGMODE=false|true`
Note that if one of them is set to `true`, the other one cannot be used to disable this setting again.<br>
**[More details](regex/overview.md)**
<hr/>
Controls if *FTL*DNS should print extended details about regex matching into `pihole-FTL.log`.<br>
Due to legacy reasons, we also support the following setting to be used for enabling the same functionality:<br>
`REGEX_DEBUGMODE=false|true`
Note that if one of them is set to `true`, the other one cannot be used to disable this setting again.<br>
**[More details](regex/overview.md)**
---
#### `DEBUG_API=false|true` {#debug_api data-toc-label='Debug Telnet'}
Print extra debugging information during telnet API calls. Currently only used to send extra information when getting all queries.
<hr/>
Print extra debugging information during telnet API calls. Currently only used to send extra information when getting all queries.
---
#### `DEBUG_OVERTIME=false|true` {#debug_overtime data-toc-label='Debug overTime'}
Print information about overTime memory operations, such as initializing or moving overTime slots.
<hr/>
Print information about overTime memory operations, such as initializing or moving overTime slots.
---
#### `DEBUG_EXTBLOCKED=false|true` {#debug_extblocked data-toc-label='Debug externally blocked'}
Print information about why FTL decided that certain queries were recognized as being externally blocked.
<hr/>
Print information about why FTL decided that certain queries were recognized as being externally blocked.
---
#### `DEBUG_CAPS=false|true` {#debug_caps data-toc-label='Debug Linux capabilities'}
Print information about capabilities granted to the pihole-FTL process. The current capabilities are printed on receipt of `SIGHUP`, i.e., the current set of capabilities can be queried without restarting `pihole-FTL` (by setting `DEBUG_CAPS=true` and thereafter sending `killall -HUP pihole-FTL`).
Print information about capabilities granted to the pihole-FTL process. The current capabilities are printed on receipt of `SIGHUP`, i.e., the current set of capabilities can be queried without restarting `pihole-FTL` (by setting `DEBUG_CAPS=true` and thereafter sending `killall -HUP pihole-FTL`).
{!abbreviations.md!}
docs/ftldns/database.md
+24 -8
View File
@@ -9,25 +9,29 @@ Another way of controlling the size of the long-term database is setting a maxim
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:
```
```bash
sudo service pihole-FTL stop
sudo mv /etc/pihole/pihole-FTL.db /media/backup/pihole-FTL_$(date +"%m-%y").db
sudo service pihole-FTL start
```
Note that DNS resolution will not be available as long as `pihole-FTL` is stopped.
### Backup database
The database can be backed up while FTL is running when using the SQLite3 Online backup method, e.g.,
```
```bash
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.
will create `/home/pi/pihole-FTL.db.backup` which is a copy of your long-term database.
---
@@ -46,12 +50,14 @@ Label | Type | Allowed to by empty | Content
`forward` | text | Yes | Forward destination used for this query (only set if `status == 2`)
SQLite3 syntax used to create this table:
```
```sql
CREATE TABLE queries ( id INTEGER PRIMARY KEY AUTOINCREMENT, timestamp INTEGER NOT NULL, type INTEGER NOT NULL, status INTEGER NOT NULL, domain TEXT NOT NULL, client TEXT NOT NULL, forward TEXT );
CREATE INDEX idx_queries_timestamps ON queries (timestamp);
```
### Counters table
This table contains counter values integrated over the entire lifetime of the table
Label | Type | Allowed to by empty | Content
@@ -65,19 +71,23 @@ Counter ID | Interpretation
1 | Total number of blocked queries (Query `status` 1, 4 or 5)
SQLite3 syntax used to create this table:
```
```sql
CREATE TABLE counters ( id INTEGER PRIMARY KEY NOT NULL, value INTEGER NOT NULL );
```
### FTL table
The FTL tables contains some data used by *FTL*DNS for determining which queries to save to the database. This table does not contain any entries of general interest.
SQLite3 syntax used to create this table:
```
```sql
CREATE TABLE ftl ( id INTEGER PRIMARY KEY NOT NULL, value BLOB NOT NULL );
```
### Supported query types
ID | Query Type
--- | ---
1 | A
@@ -93,6 +103,7 @@ ID | Query Type
<!-- Query | A | AAAA | ANY | SRV | SOA | PTR | TXT -->
### Supported status types
ID | Query Type
--- | ---
0 | Unknown status (was not answered by forward destination)
@@ -106,16 +117,21 @@ ID | Query Type
8 | Blocked by upstream server (`NXDOMAIN` with `RA` bit unset)
### Example for interaction with the FTL long-term database
In addition to the interactions the Pi-hole database API offers, you can also run your own SQL commands against the database. If you want to obtain the three most queries domains for all time, you could use
```
```bash
sqlite3 "/etc/pihole/pihole-FTL.db" "SELECT domain,count(domain) FROM queries WHERE (STATUS == 2 OR STATUS == 3) GROUP by domain order by count(domain) desc limit 3"
```
which would return something like
```
```text
discourse.pi-hole.net|421095
www.pi-hole.net|132483
posteo.de|130243
```
showing the domain and the number of times it was found in the long-term database. Note that such a request might take very long for computation as the entire history of queries have to be processed for this.
{!abbreviations.md!}
docs/ftldns/debugging.md
+1 -1
View File
@@ -2,7 +2,7 @@ Once you are used to it, you can skip most of the steps. Debugging *FTL*DNS is a
1. Install `screen` and `gdb` using `sudo apt-get install screen gdb`
2. Start a screen session (it will allow you to come back even if the SSH connection died)
* If you don't know about `screen`, then read about it (you *will* love it!)
* If you don't know about `screen`, then read about it (you *will* love it!)
3. Start a screen session using `screen`
4. Use `sudo gdb -p $(pidof pihole-FTL)` to attach the debugger to the already running `pihole-FTL` process
5. Once loading of the symbols has finished (the `(gdb)` input prompt is shown), run `handle SIGHUP nostop SIGPIPE nostop`
docs/ftldns/dns-cache.md
+3
View File
@@ -5,16 +5,19 @@
The Settings page (System panel, FTL table) gives live information about the cache usage. It obtains its information from `http://pi.hole/admin/api.php?getCacheInfo`.
#### DNS cache size
Size of the DNS domain cache, defaulting to 10,000 entries. You typically specify this number directly in `/etc/dnsmasq.d/01-pihole.conf`. It is the number of entries that can be actively cached at the same time. There is no benefit in enlarging this number *except* if the DNS cache evictions count is larger than zero.
This information may also be queried using `dig +short chaos txt cachesize.bind`
#### DNS cache insertions
Number of total insertions into the cache. This number can be substantially larger than DNS cache size as expiring cache entries naturally make room for new insertions over time. Each lookup with a non-zero TTL will be cached.
This information may also be queried using `dig +short chaos txt insertions.bind`
#### DNS cache evictions
Number of cache entries that had to be removed although the corresponding entries were **not** expired. Old cache entries get removed if the cache is full to make space for more recent domains. The cache size should be increased when this number is larger than zero.
This information may also be queried using `dig +short chaos txt evictions.bind`
docs/ftldns/dns-resolver.md
+3
View File
@@ -11,12 +11,15 @@ If we would start to modify the resolver code in too many places, then this woul
### Implemented modifications in `dnsmasq`'s source code
#### FTL hooks
We place hooks in a lot of places in the resolver that branch out into `FTL` code to process queries and responses. By this, we keep the resolver code itself clean.
#### Remove limit on maximum cache size
Users are able to configure the size of the resolvers name cache. The default is 150 names. Setting the cache size to zero disables caching. We think users should be allowed to set the cache size to any value they find appropriate. However, `dnsmasq`'s source code contains a condition that limits the maximum size of the cache to 10,000 names. We removed this hard-coded upper limit in [option.c](https://github.com/pi-hole/FTL/commit/ea3309e7b1991f50d40555b9a18f39894c237b29#diff-733116077302620357dcd8252f41449dR2582R258) and submitted a patch to remove this hard-coded limit in the upstream version of `dnsmasq`.
#### Improve detection algorithm for determining the "best" forward destination
The DNS forward destination determination algorithm in *FTL*DNS's is modified to be much less restrictive than the original algorithm in `dnsmasq`. We keep using the fastest responding server now for 1000 queries or 10 minutes (whatever happens earlier) instead of 50 queries or 10 seconds (default values in `dnsmasq`).
We keep the exceptions, i.e., we try all possible forward destinations if `SERVFAIL` or `REFUSED` is received or if a timeout occurs.
Overall, this change has proven to greatly reduce the number of actually performed queries in typical Pi-hole environments. It may even be understood as being preferential in terms of privacy (as we send queries much less often to all servers).
docs/ftldns/in-depth.md
+3 -1
View File
@@ -17,16 +17,18 @@ Pi-hole stats can be accessed via a standard Unix socket (`var/run/pihole/FTL.so
Command line arguments can be arbitrarily combined, e.g. `pihole-FTL debug test`
## File locations
- `/var/log/pihole-FTL.log` log file
- `/var/run/pihole-FTL.pid` PID file
- `/var/run/pihole-FTL.port` file containing port on which `FTL` is listening
- `/var/run/pihole/FTL.sock` Unix socket
## Domain lists format
Since Pi-hole v4.0, we use a simpler domain list format for the two important block list files `gravity.list` and `black.list`. In contrast to the traditional HOSTS format (which caused a lot of overhead), the domain list format is the minimal possible solution for saving memory while still using plain text lists for your convenience. When *FTL*DNS imports these two files, they are walked by our improved list parser speeding up the loading of block lists significantly. Regardless which blocking mode (`IP` or `NXDOMAIN`) is selected, *FTL*DNS will always load the lists into its internal hashed cache to be able to determine the blocking status within a few milliseconds, even when you're using huge blocking lists on low-end devices. With everything we do, we design *FTL*DNS for maximum efficiency also on low-performance devices.
## Linux capabilities
Capabilities (POSIX 1003.1e, [capabilities(7)](http://man7.org/linux/man-pages/man7/capabilities.7.html)) provide fine-grained control over superuser permissions, allowing use of the `root` user to be avoided.
For the purpose of performing permission checks, traditional UNIX implementations distinguish two categories of processes: *privileged processes* (superuser or `root`), and *unprivileged processes*. Privileged processes bypass all kernel permission checks, while unprivileged processes are subject to full permission checking based on the process's credentials (user and group permissions and supplementary process capabilities). Capabilities are implemented on Linux using extended attributes ([xattr(7)](http://man7.org/linux/man-pages/man5/attr.5.html)) in the `security` namespace. Extended attributes are supported by all major Linux file systems, including Ext2, Ext3, Ext4, Btrfs, JFS, XFS, and ReiserFS.
docs/ftldns/privacylevels.md
+5
View File
@@ -3,9 +3,11 @@ Using privacy levels you can specify which level of detail you want to see in yo
The available options are
### Level 0 - show everything
Doesn't hide anything, all statistics are available
### Level 1 - hide domains
Show and store all domains as `hidden`
This setting disables
@@ -14,6 +16,7 @@ This setting disables
- Top Ads
### Level 2 - hide domains and clients
Show and store all domains as `hidden` and clients as `0.0.0.0`
This setting disables
@@ -24,6 +27,7 @@ This setting disables
- Clients over time
### Level 3 - anonymous mode (anonymize everything)
Disable all details except the most anonymous statistics
This setting disables
@@ -36,6 +40,7 @@ This setting disables
- Long-term database logging
### Level 4 - disabled statistics (v4.1+)
Disables all statistics processing. Even the query counters will not be available.
Additionally, you can disable logging to the file `/var/log/pihole.log` using `sudo pihole logging off`.
docs/ftldns/regex/index.md
-1
View File
@@ -4,4 +4,3 @@ description: This url changed from page to subsection, must redirect from other
last_updated: Mon Jan 14 11:47:02 2019 UTC
redirect: /ftldns/regex/overview/
---
docs/ftldns/regex/overview.md
+7 -1
View File
@@ -4,6 +4,7 @@ We implement the POSIX Extended Regular Expressions similar to the one used by t
Our implementation is light and fast as each domain is only checked once for a match (if you query `google.com`, it will be checked against your RegEx. Any subsequent query to the same domain will not be checked again until you restart `pihole-FTL`).
## How to use regular expressions for blocking
*FTL*DNS reads in regular expression filters from `/etc/pihole/regex.list` (one expression per line, lines starting with `#` will be skipped).
To tell *FTL*DNS to reload the list, either:
@@ -12,16 +13,21 @@ To tell *FTL*DNS to reload the list, either:
- Restart the service (`sudo service pihole-FTL restart`)
## Pi-hole Regex debugging mode
To ease the usage of regular expression filters in *FTL*DNS, we offer a regex debugging mode. Set
```
DEBUG_REGEX=true
```
in your `/etc/pihole/pihole-FTL.conf` and restart `pihole-FTL` to enable or disable this mode.
Once the debugging mode is enabled, each match will be logged to `/var/log/pihole-FTL.log` in the following format:
```
```text
[2018-07-17 17:40:51.304] Regex in line 2 "((^)|(\.))twitter\." matches "whatever.twitter.com"
```
The given line number corresponds to the line in the file `/etc/pihole/regex.list`.
Note that validation is only done on the first occurrence of a domain to increase the computational efficiency of *FTL*DNS.
docs/ftldns/regex/tutorial.md
+13
View File
@@ -1,7 +1,9 @@
# Pi-hole regular expressions tutorial
We provide a short but thorough introduction to our regular expressions implementation. This may come in handy if you are designing blocking rules (see also our cheat sheet below!). In our implementation, all characters match themselves except for the following special characters: `.[{}()\*+?|^$`. If you want to match those, you need to escape them like `\.` for a literal period, but no rule without exception (see character groups below for further details).
### Anchors (`^` and `$`)
First of all, we look at anchors which can be used to indicate the start or the end of a domain, respectively. If you don't specify anchors, the match may be partial (see examples below).
Example | Interpretation
@@ -12,6 +14,7 @@ Example | Interpretation
`com$` | matches any domain **ending** (`$`) in "com" such as `domain.com` but not `domain.com.co.uk`
### Wildcard (`.`)
An unescaped period stands for any *single* character.
Example | Interpretation
@@ -19,6 +22,7 @@ Example | Interpretation
`^domain.$` | matches `domaina`, `domainb`, `domainc`, but not `domain`
### Bounds and multipliers (`{}`, `*`, `+`, and `?`)
With bounds, one can denote the number of times something has to occur:
Bound | Meaning
@@ -45,6 +49,7 @@ Example | Interpretation
`^a?b+` | matches domains like `abbbb.com` (zero or one `a` at the beginning followed by one or more `b`)
### Character groups (`[]`)
With character groups, a set of characters can be matched:
Character group | Interpretation
@@ -61,6 +66,7 @@ Character group | Interpretation
Bracket expressions are an exception to the character escape rule. Inside them, all special characters, including the backslash (`\`), lose their special powers, i.e. they match themselves exactly. Furthermore, to include a literal `]` in the list, make it the first character (like `[]]` or `[^]]` if negated). To include a literal `-`, make it the first or last character, or the second endpoint of a range (e.g. `[a-z-]` to match `a` to `z` and `-`).
### Groups (`()`)
Using groups, we can enclose regular expressions, they are most powerful when combined with bounds or multipliers (see also alternations below).
Example | Interpretation
@@ -70,6 +76,7 @@ Example | Interpretation
`(abc){1,3}` | matches one, two or three copies of `abc`: `abc`, `abcabc`, `abcabcabc` but nothing else
### Alternations (`|`)
Alternations can be used as an "or" operator in regular expressions.
Example | Interpretation
@@ -79,6 +86,7 @@ Example | Interpretation
`domain(a|b)*\.com` | matches `domain.com`, `domainaaaa.com` `domainbbb.com` but not `domainab.com` (any number of `a` or `b` in between `domain` and `.com`)
### Character classes (`[:class:]`)
In addition to character groups, there are also some special character classes available, such as
Character class | Group equivalent | Interpretation
@@ -90,18 +98,23 @@ Character class | Group equivalent | Interpretation
`[:alnum:]` | `[A-Za-z0-9]` | matches alphabetic characters and digits
## Advanced examples
After going through our quick tutorial, we provide some more advances examples so you can test your knowledge.
### Block domain with only numbers
```
^[0-9][^a-z]+\.((com)|(edu))$
```
Blocks domains containing only numbers (no letters) and ending in `.com` or `.edu`. Blocks `555661.com`, and `456.edu`, but not `555g555.com`
### Block domains without subdomains
```
^[a-z0-9]+([\-]{1}[a-z0-9]+)*\.[a-z]{2,7}$
```
A domain name shall not start or end with a dash but can contain any number of them. It must be followed by a TLD (we assume a valid TLD length of two to seven characters)
## Cheatsheet
docs/ftldns/telnet-api.md
+126 -106
View File
@@ -3,136 +3,156 @@ Connect via e.g. `telnet 127.0.0.1 4711` or use `echo ">command" | nc 127.0.0.1
- `>quit`: Closes connection to client
- `>stats` : Get current statistics
```
domains_being_blocked 116007
dns_queries_today 30163
ads_blocked_today 5650
ads_percentage_today 18.731558
unique_domains 1056
queries_forwarded 4275
queries_cached 20238
clients_ever_seen 11
unique_clients 9
status enabled
```
```text
domains_being_blocked 116007
dns_queries_today 30163
ads_blocked_today 5650
ads_percentage_today 18.731558
unique_domains 1056
queries_forwarded 4275
queries_cached 20238
clients_ever_seen 11
unique_clients 9
status enabled
```
- `>overTime` : over time data (10 min intervals)
```
1525546500 163 0
1525547100 154 1
1525547700 164 0
1525548300 167 0
1525548900 151 0
1525549500 143 0
[...]
```
```text
1525546500 163 0
1525547100 154 1
1525547700 164 0
1525548300 167 0
1525548900 151 0
1525549500 143 0
[...]
```
- `>top-domains` : get top domains
```
0 8462 x.y.z.de
1 236 safebrowsing-cache.google.com
2 116 pi.hole
3 109 z.y.x.de
4 93 safebrowsing.google.com
5 96 plus.google.com
[...]
```
Variant: `>top-domains (15)` to show (up to) 15 entries
```text
0 8462 x.y.z.de
1 236 safebrowsing-cache.google.com
2 116 pi.hole
3 109 z.y.x.de
4 93 safebrowsing.google.com
5 96 plus.google.com
[...]
```
Variant: `>top-domains (15)` to show (up to) 15 entries
- `>top-ads` : get top ad domains
```
0 8 googleads.g.doubleclick.net
1 6 www.googleadservices.com
2 1 cdn.mxpnl.com
3 1 collector.githubapp.com
4 1 www.googletagmanager.com
5 1 s.zkcdn.net
[...]
```
Variant: `>top-ads (14)` to show (up to) 14 entries
```text
0 8 googleads.g.doubleclick.net
1 6 www.googleadservices.com
2 1 cdn.mxpnl.com
3 1 collector.githubapp.com
4 1 www.googletagmanager.com
5 1 s.zkcdn.net
[...]
```
Variant: `>top-ads (14)` to show (up to) 14 entries
- `top-clients` : get recently active top clients (IP addresses + host names (if available))
```
0 9373 192.168.2.1 router
1 484 192.168.2.2 work-machine
2 8 127.0.0.1 localhost
```
Variant: `>top-clients (9)` to show (up to) 9 client entries or `>top-clients withzero (15)` to show (up to) 15 clients even if they have not been active recently (see PR #124 for further details)
```text
0 9373 192.168.2.1 router
1 484 192.168.2.2 work-machine
2 8 127.0.0.1 localhost
```
Variant: `>top-clients (9)` to show (up to) 9 client entries or `>top-clients withzero (15)` to show (up to) 15 clients even if they have not been active recently (see PR #124 for further details)
- `>forward-dest` : get forward destinations (IP addresses + host names (if available)) along with the percentage. The first result (ID -2) will always be the percentage of domains answered from blocklists, whereas the second result (ID -1) will be the queries answered from cache
```
-2 18.70 blocklist blocklist
-1 67.10 cache cache
0 14.20 127.0.0.1 localhost
```
Variant: `>forward-dest unsorted` to show forward destinations in unsorted order (equivalent to using `>forward-names`)
```text
-2 18.70 blocklist blocklist
-1 67.10 cache cache
0 14.20 127.0.0.1 localhost
```
Variant: `>forward-dest unsorted` to show forward destinations in unsorted order (equivalent to using `>forward-names`)
- `>querytypes` : get collected query types percentage
```
A (IPv4): 53.45
AAAA (IPv6): 45.32
ANY: 0.00
SRV: 0.64
SOA: 0.05
PTR: 0.54
TXT: 0.00
```
```text
A (IPv4): 53.45
AAAA (IPv6): 45.32
ANY: 0.00
SRV: 0.64
SOA: 0.05
PTR: 0.54
TXT: 0.00
```
- `>getallqueries` : get all queries that FTL has in memory
```
1525554586 A fonts.googleapis.com 192.168.2.100 3 0 4 6
1525554586 AAAA fonts.googleapis.com 192.168.2.100 3 0 4 5
1525554586 A www.mkdocs.org 192.168.2.100 3 0 4 7
1525554586 AAAA www.mkdocs.org 192.168.2.100 2 0 3 21
1525554586 A squidfunk.github.io 192.168.2.100 2 0 3 20
1525554586 A pi-hole.net 192.168.2.100 3 0 4 5
1525554586 AAAA squidfunk.github.io 192.168.2.100 3 0 1 6
1525554586 AAAA pi-hole.net 192.168.2.100 2 0 1 18
1525554586 A github.com 192.168.2.100 3 0 4 5
1525554586 AAAA github.com 192.168.2.100 2 0 1 18
```
Variants: `>getallqueries (37)` show (up to) 37 latest entries, `>getallqueries-time 1483964295 1483964312` gets all queries that FTL has in its database in a limited time interval, `>getallqueries-time 1483964295 1483964312 (17)` show matches in the (up to) 17 latest entries, `>getallqueries-domain www.google.com` gets all queries that FTL has in its database for a specific domain name, `>getallqueries-client 2.3.4.5` : gets all queries that FTL has in its database for a specific client name *or* IP
```text
1525554586 A fonts.googleapis.com 192.168.2.100 3 0 4 6
1525554586 AAAA fonts.googleapis.com 192.168.2.100 3 0 4 5
1525554586 A www.mkdocs.org 192.168.2.100 3 0 4 7
1525554586 AAAA www.mkdocs.org 192.168.2.100 2 0 3 21
1525554586 A squidfunk.github.io 192.168.2.100 2 0 3 20
1525554586 A pi-hole.net 192.168.2.100 3 0 4 5
1525554586 AAAA squidfunk.github.io 192.168.2.100 3 0 1 6
1525554586 AAAA pi-hole.net 192.168.2.100 2 0 1 18
1525554586 A github.com 192.168.2.100 3 0 4 5
1525554586 AAAA github.com 192.168.2.100 2 0 1 18
```
Variants: `>getallqueries (37)` show (up to) 37 latest entries, `>getallqueries-time 1483964295 1483964312` gets all queries that FTL has in its database in a limited time interval, `>getallqueries-time 1483964295 1483964312 (17)` show matches in the (up to) 17 latest entries, `>getallqueries-domain www.google.com` gets all queries that FTL has in its database for a specific domain name, `>getallqueries-client 2.3.4.5` : gets all queries that FTL has in its database for a specific client name *or* IP
- `>recentBlocked` : get most recently pi-holed domain name
```
www.googleadservices.com
```
Variant: `>recentBlocked (4)` show the four most recent blocked domains
```text
www.googleadservices.com
```
Variant: `>recentBlocked (4)` show the four most recent blocked domains
- `>clientID` : Get ID of currently connected client
```
6
```
```text
6
```
- `>version` : Get version information of the currently running FTL instance
```
version v1.6-3-g106498d-dirty
tag v1.6
branch master
hash 106498d
date 2017-03-26 13:10:43 +0200
```
```text
version v1.6-3-g106498d-dirty
tag v1.6
branch master
hash 106498d
date 2017-03-26 13:10:43 +0200
```
- `>dbstats` : Get some statistics about `FTL`'s' long-term storage database (this request may take some time for processing in case of a large database file)
```
queries in database: 2700304
database filesize: 199.20 MB
SQLite version: 3.23.1
```
```text
queries in database: 2700304
database filesize: 199.20 MB
SQLite version: 3.23.1
```
- `>domain pi-hole.net`: Get detailed information about domain (if available)
```
Domain "pi-hole.net", ID: 254
Total: 179
Blocked: 0
Wildcard blocked: false
```
- `>cacheinfo`: Get DNS server cache size and usage information
```
cache-size: 500000
cache-live-freed: 0
cache-inserted: 15529
```
```text
Domain "pi-hole.net", ID: 254
Total: 179
Blocked: 0
Wildcard blocked: false
```
- `>cacheinfo`: Get DNS server cache size and usage information
```text
cache-size: 500000
cache-live-freed: 0
cache-inserted: 15529
```
{!abbreviations.md!}
docs/guides/benchmark.md
+15 -3
View File
@@ -1,38 +1,50 @@
# Realistic benchmarking of your Pi-hole
If you want to know how many queries - using the given hardware - your Pi-hole can handle to, e.g., estimate how many clients could be served, you could mass query domains from your long-term database.
As the domains in the long-term database reflect **your particular** real-life usage, a benchmark on these domains should give you a good feeling for the performance of your Pi-hole.
## 1. Extract the domains from the long-term database
You can extract the domains using, e.g.,
```
```bash
sqlite3 /etc/pihole/pihole-FTL.db "SELECT domain FROM queries LIMIT 100000;" > domains.list
```
This will generate a list file with (up to) 100,000 domains. You can increase the upper limit of domains, however, I'd suggest to start from not too much data for getting realistic results in a reasonable period of time.
They are extracted into the list file as they are recorded in the database. There will be lots of frequently queried domains (maybe `google.com` or similar) as well as some blocked ad domains. This list will serve you as an individualized testing bench for realistic DNS queries as typically seen in **your particular environment**.
## 2. Optimize Pi-hole setting for benchmarking
### 2.1 Disable logging
We suggest disabling both logging as well as the long-term database during the benchmark run as both the log file and the database would otherwise unnecessarily grow (maybe be several hundreds of megabytes). Not only your statistics would be distorted by the artificial mass querying, the benchmark could also negatively be affected by the writing speed of your SD card.
Logging can be disabled using `sudo pihole logging off`.
The long-term database can disabled by setting
```
DBFILE=
```
in `/etc/pihole/pihole-FTL.conf` and running `sudo pihole restartdns` (see also [here](https://docs.pi-hole.net/ftldns/configfile/#dbfile)).
in `/etc/pihole/pihole-FTL.conf` and running `sudo pihole restartdns` (see also [here](/ftldns/configfile/#dbfile)).
### 2.2 Increase DNS cache size
We also suggest to increase the DNS cache for benchmarking. The rather low value is fine for typical use cases. Domains will expire at some point and make room for new domains. As the benchmark will artificially increase the querying rate, there will be no time for the domains to expire naturally. This would dramatically hit the caching performance while you would never see such performance penalties in real use cases.
Set `cache-size` to a rather high value (maybe 25,000 - by guess roughly one-eight to one-fourth number of the domains you extracted from the database in step 1) in `/etc/dnsmasq.d/01-pihole.conf` and run `sudo pihole restartdns` afterwards.
## 3. Query domains from the list
Use
```
```bash
time dig -f domains.list +noall +answer > /dev/null
```
for mass querying the domains from your list. This will show you how much time it takes to query the number of domains you extracted from the database.
{!abbreviations.md!}
docs/guides/caddy-configuration.md
+26 -12
View File
@@ -3,22 +3,32 @@
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.
## Modifying lighttpd configuration
First, change the listen port in this file:
`/etc/lighttpd/lighttpd.conf:`
```
server.port = 1080
First, change the listen port in this file: `/etc/lighttpd/lighttpd.conf:`
```lighttpd
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.`
```bash
sudo systemctl restart lighttpd
```
or
```bash
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
@@ -33,18 +43,20 @@ blackhole:80, pi.hole:80, 0.0.0.0:80 {
}
}
```
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`
Finally, restart your Caddy server: `sudo service caddy restart`
## Verifying your setup
## 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
```bash
$ curl -H "Host: badhost" pi.hole/
<html>
<head>
@@ -54,10 +66,12 @@ $ curl -H "Host: badhost" pi.hole/
</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
```bash
curl -H "Host: badhost" pi.hole/malicious.js
var x = "Pi-hole: A black hole for Internet advertisements."
```
docs/guides/dns-over-https.md
+8 -9
View File
@@ -21,7 +21,7 @@ The installation is fairly straightforward, however be aware of what architectur
Download the installer package, then use `apt-get` to install the package along with any dependencies. Proceed to run the binary with the `-v` flag to check it is all working:
```sh
```bash
# For Debian/Ubuntu
wget https://bin.equinox.io/c/VdrWdbjqyF/cloudflared-stable-linux-amd64.deb
sudo apt-get install ./cloudflared-stable-linux-amd64.deb
@@ -33,13 +33,13 @@ sudo yum install ./cloudflared-stable-linux-amd64.rpm
cloudflared -v
```
**Note:** Binaries for other operating systems can be found here: https://developers.cloudflare.com/argo-tunnel/downloads/
**Note:** Binaries for other operating systems can be found here: <https://developers.cloudflare.com/argo-tunnel/downloads/>
#### ARM architecture (Raspberry Pi)
Here we are downloading the precompiled binary and copying it to the `/usr/local/bin/` directory to allow execution by the cloudflared user. Proceed to run the binary with the `-v` flag to check it is all working:
```sh
```bash
wget https://bin.equinox.io/c/VdrWdbjqyF/cloudflared-stable-linux-arm.tgz
tar -xvzf cloudflared-stable-linux-arm.tgz
sudo cp ./cloudflared /usr/local/bin
@@ -51,20 +51,20 @@ cloudflared -v
Create a cloudflared user to run the daemon:
```sh
```bash
sudo useradd -s /usr/sbin/nologin -r -M cloudflared
```
Proceed to create a configuration file for `cloudflared` by copying the following in to `/etc/default/cloudflared`. This file contains the command-line options that get passed to cloudflared on startup:
```sh
```bash
# Commandline args for cloudflared
CLOUDFLARED_OPTS=--port 5053 --upstream https://1.1.1.1/dns-query --upstream https://1.0.0.1/dns-query
```
Update the permissions for the configuration file and `cloudflared` binary to allow access for the cloudflared user:
```sh
```bash
sudo chown cloudflared:cloudflared /etc/default/cloudflared
sudo chown cloudflared:cloudflared /usr/local/bin/cloudflared
```
@@ -91,7 +91,7 @@ WantedBy=multi-user.target
Enable the `systemd` service to run on startup, then start the service and check its status:
```sh
```bash
sudo systemctl enable cloudflared
sudo systemctl start cloudflared
sudo systemctl status cloudflared
@@ -99,7 +99,7 @@ sudo systemctl status cloudflared
Now test that it is working! Run the following `dig` command, a response should be returned similar to the one below:
```sh
```bash
dig @127.0.0.1 -p 5053 google.com
@@ -131,5 +131,4 @@ Finally, configure Pi-hole to use the local `cloudflared` service as the upstrea
(don't forget to hit Return or click on `Save`)
[^guide]: Based on [this guide by Ben Dews | bendews.com](https://bendews.com/posts/implement-dns-over-https/)
docs/guides/github/contributing.md
+4 -5
View File
@@ -3,18 +3,17 @@ Pi-hole enforces the Developer Certificate of Origin (DCO) on Pull Requests. It
The Developer Certificate of Origin (DCO) is a lightweight way for contributors to certify that they wrote or otherwise have the right to submit the code they are contributing to the project. Here is the full text of the DCO, reformatted for readability:
> By making a contribution to this project, I certify that:
>
> 1. The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or
>
> 2. The contribution is based upon previous work that, to the best of my knowledge, is covered under an > appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or
>
> 3. The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.
>
> 4. I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.
Contributors *sign-off* that they adhere to these requirements by adding a Signed-off-by line to commit messages. See [this guide for how to sign-off correctly](./how-to-signoff.md).
#### DCO Failures
The Pi-hole project uses a DCO bot for all GitHub pulls to verify that each commit is signed off. When you create your pull request, it will automaticaly be verified by this bot. An example of what to expect is below.
docs/guides/github/how-to-signoff.md
+23 -9
View File
@@ -1,33 +1,47 @@
Pi-hole requires a sign-off message in the following format appear on each commit in the pull request:
```
```text
This is my commit message
Signed-off-by: Random J Developer <random@developer.example.org>
```
The text can either be manually added to your commit body, or you can add either `-s` or `--signoff` to your usual git commit commands.
The text can either be manually added to your commit body, or you can add either `-s` or `--signoff` to your usual git commit commands.
#### Creating your signoff
Git has a `-s | --signoff` command line option to append this automatically to your commit message:
```$ git commit --signoff --message 'This is my commit message'```
```bash
git commit --signoff --message 'This is my commit message'
```
```$ git commit -s -m "This is my commit message"```
```bash
git commit -s -m "This is my commit message"
```
This will use your default git configuration which is found in `.git/config` and usually it is the `username systemaddress` of the machine which you are using.
To change this, you can use the following commands (Note these only change the current repo settings, you will need to add `--global` for these commands to change the installation default).
Your name:
```$ git config user.name "FIRST_NAME LAST_NAME"```
Your name:
Your email:
```$ git config user.email "MY_NAME@example.com"```
```bash
git config user.name "FIRST_NAME LAST_NAME"
```
Your email:
```bash
git config user.email "MY_NAME@example.com"
```
#### How to amend a sign-off
If you have authored a commit that is missing the signed-off-by line, you can amend your commits and push them to GitHub
```$ git commit --amend --signoff```
```bash
git commit --amend --signoff
```
If you've pushed your changes to Github already you'll need to force push your branch after this with `git push -f`.
docs/guides/nginx-configuration.md
+91 -51
View File
@@ -1,22 +1,44 @@
### 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:
```nginx
server {
1. Stop default lighttpd
```bash
service lighttpd stop
```
2. Install necessary packages
```bash
apt-get -y install nginx php7.0-fpm php7.0-zip apache2-utils
```
3. Disable lighttpd at startup
```bash
systemctl disable lighttpd
```
4. Enable php7.0-fpm at startup
```bash
systemctl enable php7.0-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;
@@ -27,64 +49,82 @@ server {
index pihole/index.php index.php index.html index.htm;
location / {
expires max;
try_files $uri $uri/ =404;
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
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
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
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;
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`
7. Create username for authentication for the admin - we don't want other people in our network change our black and whitelist ;)
8. Change ownership of html directory to nginx user
`chown -R www-data:www-data /var/www/html`
```bash
htpasswd -c /etc/nginx/.htpasswd exampleuser
```
9. Make sure html directory is writable
`chmod -R 755 /var/www/html`
8. Change ownership of html directory to nginx user
10. Start php7.0-fpm daemon
`service php7.0-fpm start`
```bash
chown -R www-data:www-data /var/www/html
```
11. Start nginx webserver
`service nginx start`
9. Make sure html directory is writable
```bash
chmod -R 755 /var/www/html
```
10. Start php7.0-fpm daemon
```bash
service php7.0-fpm start
```
11. Start nginx webserver
```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;`
- 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:
```nginx
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.
```bash
add-apt-repository ppa:certbot/certbot
apt-get install certbot python-certbot-nginx
- 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;`
certbot --nginx -m "$email" -d "$domain" -n --agree-tos --no-eff-email
```
- 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:
```nginx
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.
```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/tor/dnssec.md
+7 -7
View File
@@ -1,15 +1,15 @@
**This is an unsupported configuration created by the community**
A lot of the Exit Nodes configure their DNS Server to support DNSSEC. You can [test here](https://dnssec.vs.uni-due.de/) whether DNSSEC is enabled for your current DNS Servers.
If you want to test again by refreshing the site, please be aware of the notes on the site:
To re-run the above test, you also need to:
If you want to test again by refreshing the site, please be aware of the notes on the site:
1. Flush the DNS cache of your OS (Windows: ipconfig /flushdns)
2. Restart browser or clear browser cache
To re-run the above test, you also need to:
Note: Flushing Browser/DNS Cache here means restarting Pi-hole (DNS Server), restarting the browser and ideally opening the site in private/incognito mode.
1. Flush the DNS cache of your OS (Windows: `ipconfig /flushdns`)
2. Restart browser or clear browser cache
Note: Flushing Browser/DNS Cache here means restarting Pi-hole (DNS Server), restarting the browser and ideally opening the site in private/incognito mode.
#### Alternatives
* An alternative would be using [DNSCrypt](https://github.com/pi-hole/pi-hole/wiki/DNSCrypt), but this leaves you in a position where you have to trust the [DNSCrypt resolver](https://www.dnscrypt.org/dnscrypt-resolvers.html) since your IP is not anonymized - [unless you configure DNSCrypt to route over Tor](https://github.com/DNSCrypt/dnscrypt-proxy/issues/399#issuecomment-214329222).
* An alternative would be using [DNSCrypt](https://github.com/pi-hole/pi-hole/wiki/DNSCrypt), but this leaves you in a position where you have to trust the [DNSCrypt resolver](https://www.dnscrypt.org/dnscrypt-resolvers.html) since your IP is not anonymized - [unless you configure DNSCrypt to route over Tor](https://github.com/DNSCrypt/dnscrypt-proxy/issues/399#issuecomment-214329222).
docs/guides/tor/overview.md
+19 -16
View File
@@ -2,34 +2,37 @@
If you want to protect your - unencrypted by default - DNS requests from easily being collected by your ISP or another Adversary between you and your DNS server, you can easily setup Pi-hole to use [Tor](https://www.torproject.org) for hostname resolving. Using DNS over Tor anonymizes your IP by using [Onion-Routing](https://en.wikipedia.org/wiki/Onion_routing).
#### Contribute to the Tor project
If you got spare resources consider [running a Tor Relay](https://www.torproject.org/docs/tor-doc-relay.html.en) (or [Exit](https://blog.torproject.org/tips-running-exit-node)) Node to contribute back to the Tor Network. The default installation doesn't do either of these. And/Or consider [donating](https://donate.torproject.org).
#### Contribute to the Tor project
If you got spare resources consider [running a Tor Relay](https://www.torproject.org/docs/tor-doc-relay.html.en) (or [Exit](https://blog.torproject.org/tips-running-exit-node)) Node to contribute back to the Tor Network. The default installation doesn't do either of these. And/Or consider [donating](https://donate.torproject.org).
***
***
### ⚠️ Warnings & Considerations
#### Tracking
#### Tracking
Please be aware that **your ISP or an Adversary still can collect what Websites you visit by capturing HTTP (plaintext) or HTTPS ([SNI](https://en.wikipedia.org/wiki/Server_Name_Indication)) packets or by trying to [reverse lookup](https://en.wikipedia.org/wiki/Reverse_DNS_lookup) or [whois](https://en.wikipedia.org/wiki/WHOIS) the IPs you're connecting to**. To avoid that you might want to consider to additionally [route your Browser traffic over Tor](#route-browser-traffic-over-tor).
Also keep in mind that even Tor can't provide 100% anonymity, for example [correlation](https://www.extremetech.com/extreme/211169-mit-researchers-figure-out-how-to-break-tor-anonymity-without-cracking-encryption) [attacks](https://nakedsecurity.sophos.com/2016/10/05/unmasking-tor-users-with-dns/) are possible. Although it's almost impossible to execute such an attack for e.g. your ISP or a random service on the internet - you might need to [change some of your habits](https://www.torproject.org/download/download.html.en#warning) to get the most out of Tor.
#### Bad Relays, Phishing, Scam
Tor has the concept of [Bad Relays](https://trac.torproject.org/projects/tor/wiki/doc/ReportingBadRelays) and tries to avoid that Tor Relays become Bad Exit Nodes (which are a form of Relay) by monitoring their behavior before declaring them as Exit Node. But it still can happen and since anyone can run a Tor Relay as Exit Node on the Tor Network, this means that an Exit Node owner could fake the answer to a DNS request and redirect you to a malicious website/IP.
If you're in a recent Browser and only visit encrypted (HTTPS) sites, that isn't too bad, since the Browser would warn you with an invalid certificate warning (unless someone would hack a [Certificate authority](https://en.wikipedia.org/wiki/Certificate_authority) or get a CA to issue a certificate without validation - which is both [highly unlikely](https://www.reddit.com/r/TOR/comments/5b416x/malicious_tor_exit_node_can_provide_fakephishing/d9lskni/)). But other apps on your network that resolve DNS queries via DNS over Tor might either communicate unencrypted or don't validate certificates properly.
Such apps could get malicious data injected and/or phish your data without your knowledge.
Tor has the concept of [Bad Relays](https://trac.torproject.org/projects/tor/wiki/doc/ReportingBadRelays) and tries to avoid that Tor Relays become Bad Exit Nodes (which are a form of Relay) by monitoring their behavior before declaring them as Exit Node. But it still can happen and since anyone can run a Tor Relay as Exit Node on the Tor Network, this means that an Exit Node owner could fake the answer to a DNS request and redirect you to a malicious website/IP.
If you're in a recent Browser and only visit encrypted (HTTPS) sites, that isn't too bad, since the Browser would warn you with an invalid certificate warning (unless someone would hack a [Certificate authority](https://en.wikipedia.org/wiki/Certificate_authority) or get a CA to issue a certificate without validation - which is both [highly unlikely](https://www.reddit.com/r/TOR/comments/5b416x/malicious_tor_exit_node_can_provide_fakephishing/d9lskni/)). But other apps on your network that resolve DNS queries via DNS over Tor might either communicate unencrypted or don't validate certificates properly.
Such apps could get malicious data injected and/or phish your data without your knowledge.
**So, ideally, only use DNS over Tor if you know for a fact that the apps in your network communicate over a secure connection and properly validate certificates.**
That being said, if you use DNS over Tor in the default configuration (meaning no custom `ExitNodes` in the torrc), this kind of attack requires a big portion of luck for the attacker (owner of a Bad Exit Node), because you would have to get a circuit routing over the Bad Exit Node in the same moment when using an insecure app (Tor switches the circuit at least every 10minutes in the default configuration). On top of that an attacker must first find an app that has this kind of vulnerability and has valuable data or attack vectors. This is unlikely since most apps out there that handle sensitive data at least communicate over encrypted connections that validate certificates based on system or manual root certs.
That being said, if you use DNS over Tor in the default configuration (meaning no custom `ExitNodes` in the torrc), this kind of attack requires a big portion of luck for the attacker (owner of a Bad Exit Node), because you would have to get a circuit routing over the Bad Exit Node in the same moment when using an insecure app (Tor switches the circuit at least every 10minutes in the default configuration). On top of that an attacker must first find an app that has this kind of vulnerability and has valuable data or attack vectors. This is unlikely since most apps out there that handle sensitive data at least communicate over encrypted connections that validate certificates based on system or manual root certs.
To lower the chances of Bad Exit Nodes you could restrict `ExitNodes` to trusted ones ([country](#solution-1---only-use-exit-nodes-from-specific-countries) and/or [specific](#solution-2---only-use-specific-exit-nodes)). Choosing specific Exit Nodes would basically be the same as e.g. trusting specific [DNSCrypt resolvers](#alternatives) or [Alternative DNS Servers](https://wikileaks.org/wiki/Alternative_DNS). They might be good, they might be bad, you can't know for sure (unless the DNS answers are [DNSSEC](#dnssec) signed - but that's most likely not the case for the kinds of app that might get affected by this).
To lower the chances of Bad Exit Nodes you could restrict `ExitNodes` to trusted ones ([country](#solution-1---only-use-exit-nodes-from-specific-countries) and/or [specific](#solution-2---only-use-specific-exit-nodes)). Choosing specific Exit Nodes would basically be the same as e.g. trusting specific [DNSCrypt resolvers](#alternatives) or [Alternative DNS Servers](https://wikileaks.org/wiki/Alternative_DNS). They might be good, they might be bad, you can't know for sure (unless the DNS answers are [DNSSEC](#dnssec) signed - but that's most likely not the case for the kinds of app that might get affected by this).
So in the end it boils down to one of the following use cases.
So in the end it boils down to one of the following use cases.
- Encrypt your DNS traffic using Tor so your ISP can't collect it (but still is able to [collect what Websites/IPs you visit](#%EF%B8%8F-attention-%EF%B8%8F) unless you route that traffic also over Tor) and the DNS Server won't see your real IP for the price of maybe getting a Bad Exit Node that fakes answers to DNS queries.
- Encrypt your DNS traffic using Tor so your ISP can't collect it (but still is able to [collect what Websites/IPs you visit](#%EF%B8%8F-attention-%EF%B8%8F) unless you route that traffic also over Tor) and the DNS Server won't see your real IP for the price of maybe getting a Bad Exit Node that fakes answers to DNS queries.
- Use [DNSCrypt](#alternatives) so your ISP can't collect DNS traffic (but still can collect the websites/IPs you visit unless you route that traffic over Tor), but you have to accept that the DNSCrypt resolver you've chosen might store your DNS queries together with your IP (unless you [modify DNSCrypt to route over Tor](https://github.com/DNSCrypt/dnscrypt-proxy/issues/399#issuecomment-214329222)) and could also turn out to send faked answers to DNS queries. I guess you would call that a Bad DNSCrypt resolver then.
docs/guides/tor/performance-issues.md
+57 -47
View File
@@ -1,68 +1,78 @@
**This is an unsupported configuration created by the community**
You're constantly using new DNS Servers that are located all over the world, so it might happen that sometimes hostname resolving is slow or might not work at all for certain domains. In this cases you have to wait some minutes until you switch to another Tor circuit or configure Tor to accept control connections and send a command that tells Tor to [switch circuits immediately](https://superuser.com/a/139018).
You're constantly using new DNS Servers that are located all over the world, so it might happen that sometimes hostname resolving is slow or might not work at all for certain domains. In this cases you have to wait some minutes until you switch to another Tor circuit or configure Tor to accept control connections and send a command that tells Tor to [switch circuits immediately](https://superuser.com/a/139018).
You could set `ExitNodes` in your torrc to a specific set of Exit nodes that are reliable for you or use only Exit nodes in a [specific country](https://b3rn3d.herokuapp.com/blog/2014/03/05/tor-country-codes/) (on Debian derivatives you need to have the `tor-geoipdb` package installed for that to work) and thus avoid problems with DNS lookups to some extend.
You could set `ExitNodes` in your torrc to a specific set of Exit nodes that are reliable for you or use only Exit nodes in a [specific country](https://b3rn3d.herokuapp.com/blog/2014/03/05/tor-country-codes/) (on Debian derivatives you need to have the `tor-geoipdb` package installed for that to work) and thus avoid problems with DNS lookups to some extend.
Keep in mind that this approach increases the correlation attack vulnerability if you only have a small amount of `ExitNodes` set or your selected country/s has/have few Exit nodes. If your goal is only to slightly increase security and maintain performance and reliability, this approach might be for you. It is not recommended.
**Ok, but please just tell me how to avoid timeouts**
So you've read about [Performance, Reliability and Timeouts](#performance-reliability-and-timeouts) and just want a quick solution.
So you've read about [Performance, Reliability and Timeouts](#performance-reliability-and-timeouts) and just want a quick solution.
This is not recommended, but here are some things you can do:
##### Solution 1 - Only use Exit Nodes from specific countries
* Install the necessary geoip db for Tor to use, on Debian derivatives (raspbian, Ubuntu) that means
```
sudo apt install tor-geoipdb
```
* Pick the Country Codes you want to use as ExitNodes from the "List of country codes for Tor" list on [this page](http://www.b3rn3d.com/blog/2014/03/05/tor-country-codes/).
Edit `/etc/tor/torrc` as root and, add the following lines to the end and replace `CountryCodeN` (keep the `{` and `}`) with the country code you've chosen (you can also use only one country code, in this case it would be just on `{CountryCode1}` without a comma).
```
ExitNodes {CountryCode1},{CountryCode2},{CountryCode3}
StrictNodes 1
```
* Save the changes, restart Tor
```
sudo service tor restart
```
**Note:** Using this approach you put strain on Tor Relays in the selected countries only and increase your security vulnerability. It's not nice and not recommended. Also be aware that this change also affects which Exit Nodes are used if you [Route Your Browser Traffic](#your-browser) over the Pi-hole host Tor SocksPort.
* Install the necessary geoip db for Tor to use, on Debian derivatives (raspbian, Ubuntu) that means
```bash
sudo apt install tor-geoipdb
```
* Pick the Country Codes you want to use as ExitNodes from the "List of country codes for Tor" list on [this page](http://www.b3rn3d.com/blog/2014/03/05/tor-country-codes/).
Edit `/etc/tor/torrc` as root and, add the following lines to the end and replace `CountryCodeN` (keep the `{` and `}`) with the country code you've chosen (you can also use only one country code, in this case it would be just on `{CountryCode1}` without a comma).
```
ExitNodes {CountryCode1},{CountryCode2},{CountryCode3}
StrictNodes 1
```
* Save the changes, restart Tor
```bash
sudo service tor restart
```
**Note:** Using this approach you put strain on Tor Relays in the selected countries only and increase your security vulnerability. It's not nice and not recommended. Also be aware that this change also affects which Exit Nodes are used if you [Route Your Browser Traffic](#your-browser) over the Pi-hole host Tor SocksPort.
##### Solution 2 - Only use specific Exit Nodes
1. Navigate to [atlas.torproject.org Top Relays](https://atlas.torproject.org/#toprelays).
2. Click on two Relays out of the list.
3. Make sure the relay allows Port `53` in his `IPv4 Exit Policy Summary` (and/or `IPv6 Exit Policy Summary` if you want to resolve IPv6 AAAA queries).
1. Navigate to [atlas.torproject.org Top Relays](https://atlas.torproject.org/#toprelays).
2. Click on two Relays out of the list.
3. Make sure the relay allows Port `53` in his `IPv4 Exit Policy Summary` (and/or `IPv6 Exit Policy Summary` if you want to resolve IPv6 AAAA queries).
4. As root copy the `Fingerprint` (Top Right under Relay Details) of those two Relays to the end of your `/etc/tor/torrc` file on the Pi-hole host in the following format:
```
ExitNodes Fingerprint1,Fingerprint2
StrictNodes 1
```
* Save the changes, restart Tor
```
sudo service tor restart
```
If DNS requests stop resolving at all, you might need to repeat this procedure because the Relays you chosen might've went down.
**Note:** Using this approach you put strain on single Tor Relays and increase your security vulnerability. It's not nice and not recommended. Also be aware that this change also affects which Exit Nodes are used if you [Route Your Browser Traffic](#your-browser) over the Pi-hole host Tor SocksPort.
```
ExitNodes Fingerprint1,Fingerprint2
StrictNodes 1
```
**Hint:** You can combine both Solutions and have country codes and fingerprints as `ExitNodes`.
5. Save the changes, restart Tor
```bash
sudo service tor restart
```
6. If DNS requests stop resolving at all, you might need to repeat this procedure because the Relays you chosen might've went down.
**Note:** Using this approach you put strain on single Tor Relays and increase your security vulnerability. It's not nice and not recommended. Also be aware that this change also affects which Exit Nodes are used if you [Route Your Browser Traffic](#your-browser) over the Pi-hole host Tor SocksPort.
**Hint:** You can combine both Solutions and have country codes and fingerprints as `ExitNodes`.
#### IPv6
DNS over Tor only partially supports IPv6 as of now. This is only a problem if your Router or your ISP don't support IPv4 or you want only IPv6 traffic for another reason - if you have both IPv4 and IPv6 available and you don't plan to visit a IPv6 only service, this is no problem at all.
In general, [if you made sure that you configured your Pi-hole to support IPv6](https://www.reddit.com/r/pihole/comments/7e0jg9/dns_over_tor/dq4wbry/), resolving IPv6 addresses will sometimes work and sometimes not. The reason for this is that Tor Exit nodes only resolve IPv6 queries if they have `IPv6Exit 1` set in their configuration. Tor is [working on a fix](https://trac.torproject.org/projects/tor/ticket/21311) for that - but until that is done and the Tor exit nodes switched to the fixed version, you will run into situations where IPv6 addresses aren't resolvable despite being available in the responsible nameserver. To check whether your current Exit node resolves IPv6 correctly you can run `dig example.com aaaa` (Linux) or `nslookup -q=aaaa example.com` (Windows) on your client.
DNS over Tor only partially supports IPv6 as of now. This is only a problem if your Router or your ISP don't support IPv4 or you want only IPv6 traffic for another reason - if you have both IPv4 and IPv6 available and you don't plan to visit a IPv6 only service, this is no problem at all.
In general, [if you made sure that you configured your Pi-hole to support IPv6](https://www.reddit.com/r/pihole/comments/7e0jg9/dns_over_tor/dq4wbry/), resolving IPv6 addresses will sometimes work and sometimes not. The reason for this is that Tor Exit nodes only resolve IPv6 queries if they have `IPv6Exit 1` set in their configuration. Tor is [working on a fix](https://trac.torproject.org/projects/tor/ticket/21311) for that - but until that is done and the Tor exit nodes switched to the fixed version, you will run into situations where IPv6 addresses aren't resolvable despite being available in the responsible nameserver. To check whether your current Exit node resolves IPv6 correctly you can run `dig example.com aaaa` (Linux) or `nslookup -q=aaaa example.com` (Windows) on your client.
If you're dependent on IPv6 and can't use IPv4 at all, your only chance is to configure `ExitNodes` in your torrc to only point to Exit nodes that resolve IPv6 correctly. But keep in mind that this approach increases the correlation attack vulnerability if you only have a small amount of `ExitNodes` set.
Also you can't (afaik) change the internal IPv4 Tor DNS address on the Pi-hole host to an IPv6 one since `DNSPort` doesn't support that - so you need at least internal IPv4 on your Pi-hole host, which is the default on most host systems.
#### Exit node fingerprints
To get the fingerprint of your current Exit node, you can configure `SocksPort 0.0.0.0:9050` in your torrc, restart tor, point your Browser to use your Pi-holes IP and port 9050 as Socks5 proxy, visit e.g. [check.torproject.org](https://check.torproject.org/) to get your Exit Node IP, search for that IP on [atlas.torproject.org](https://atlas.torproject.org), click on one of the results and it will show the Fingerprint top right under details.
These fingerprints can be set as comma separated value for `ExitNodes`. Don't forget to remove the `SocksPort` option and restart tor if you don't need it anymore. Also it should be noted that the Exit node you get over `SocksPort` is not necessarily the same as the one you get when issuing DNS requests over the `DNSPort`, since Tor internally keeps multiple circuits open. Again, setting `ExitNodes` manually is not recommended.
To get the fingerprint of your current Exit node, you can configure `SocksPort 0.0.0.0:9050` in your torrc, restart tor, point your Browser to use your Pi-holes IP and port 9050 as Socks5 proxy, visit e.g. [check.torproject.org](https://check.torproject.org/) to get your Exit Node IP, search for that IP on [atlas.torproject.org](https://atlas.torproject.org), click on one of the results and it will show the Fingerprint top right under details.
These fingerprints can be set as comma separated value for `ExitNodes`. Don't forget to remove the `SocksPort` option and restart tor if you don't need it anymore. Also it should be noted that the Exit node you get over `SocksPort` is not necessarily the same as the one you get when issuing DNS requests over the `DNSPort`, since Tor internally keeps multiple circuits open. Again, setting `ExitNodes` manually is not recommended.
docs/guides/tor/setup.md
+24 -13
View File
@@ -1,11 +1,13 @@
**This is an unsupported configuration created by the community**
This guide should work for most recent Debian derivatives (raspbian, Ubuntu). Alternatively you can follow a Tor Installation Guide for your Host System.
```
```bash
sudo apt install tor
```
Edit `/etc/tor/torrc` as root, include the following line at the end and save the changes
```
DNSPort 127.0.10.1:53
```
@@ -17,28 +19,37 @@ Change your Pi-hole upstream DNS server to use `127.0.10.1` in the Pi-hole WebGU
**Note:** It's currently not possible to change the Upstream DNS Server directly in the `/etc/pihole/setupVars.conf` file, the Pi-hole DNS Server won't pick up the change.
If you want a recognizable hostname for the Tor DNS in your Pi-hole GUI statistics, edit `/etc/hosts` as root, include the following line at the end and save the changes
```
127.0.10.1 tor.dns.local
```
Restart Pi-hole DNS Server for the `/etc/hosts` changes to take effect
```
Restart Pi-hole DNS Server for the `/etc/hosts` changes to take effect
```bash
sudo pihole restartdns
```
## Testing your configuration
To see which DNS servers you're using, you can use a DNS Server Leak Test. Some of them don't work with DNS over Tor, [this one](https://dns-leak.com/) does work tho. It should show random DNS Servers. Tor rotates the circuit approximately every 10minutes in default configuration, so it might take 10minutes for you to see a new set of random DNS servers in the Leak Test.
To see which DNS servers you're using, you can use a DNS Server Leak Test. Some of them don't work with DNS over Tor, [this one](https://dns-leak.com/) does work tho. It should show random DNS Servers. Tor rotates the circuit approximately every 10minutes in default configuration, so it might take 10minutes for you to see a new set of random DNS servers in the Leak Test.
You can also check the "Forward Destinations over Time" Graph (enabled per default) in your Pi-hole WebGUI - the latest Forward Destinations should only include "local" and "tor.dns.local" (if you updated the `/etc/hosts` file).
To absolutely make sure that you always use the Pi-hole as DNS Server and to make sure that it handles IPv4 and/or IPv6 blocking if you configured it to do so, you should check which DNS Servers your client is using: `nmcli device show <interface> | grep .DNS` (Linux) or `ipconfig /all` (Windows, and look for **DNS Servers** on your **LAN Adapter**). You should then issue a IPv4 (A) and/or IPv6 (AAAA) DNS query to every IPv4 and/or IPv6 DNS Server that shows up:
You can also check the "Forward Destinations over Time" Graph (enabled per default) in your Pi-hole WebGUI - the latest Forward Destinations should only include "local" and "tor.dns.local" (if you updated the `/etc/hosts` file).
For Linux:
```dig @<IPv4/6-dns-server-address> api.mixpanel.com <A/AAAA>```
To absolutely make sure that you always use the Pi-hole as DNS Server and to make sure that it handles IPv4 and/or IPv6 blocking if you configured it to do so, you should check which DNS Servers your client is using: `nmcli device show <interface> | grep .DNS` (Linux) or `ipconfig /all` (Windows, and look for **DNS Servers** on your **LAN Adapter**). You should then issue a IPv4 (A) and/or IPv6 (AAAA) DNS query to every IPv4 and/or IPv6 DNS Server that shows up:
For Windows:
```nslookup -server=<IPv4/6-dns-server-address> -q=<A/AAAA> api.mixpanel.com```
For Linux:
That should give you the Pi-hole IPv4 and/or IPv6 address as Answer and show up as "Pi-holed" in the WebGUI Query Log (assuming you have the default blocklist, otherwise replace `api.mixpanel.com` with any domain on your blocklist).
```bash
dig @<IPv4/6-dns-server-address> api.mixpanel.com <A/AAAA>
```
For Windows:
```shell
nslookup -server=<IPv4/6-dns-server-address> -q=<A/AAAA> api.mixpanel.com
```
That should give you the Pi-hole IPv4 and/or IPv6 address as Answer and show up as "Pi-holed" in the WebGUI Query Log (assuming you have the default blocklist, otherwise replace `api.mixpanel.com` with any domain on your blocklist).
If any of the queries doesn't show up in the Query Log you should make sure to configure your Pi-hole/network setup properly ([this thread might help](https://www.reddit.com/r/pihole/comments/7e0jg9/dns_over_tor/dq4kkvg/)).
docs/guides/tor/using-tor.md
+26 -13
View File
@@ -1,30 +1,43 @@
**This is an unsupported configuration created by the community**
To enhance your privacy you might want to route all or part of your Browser Traffic over Tor.
To enhance your privacy you might want to route all or part of your Browser Traffic over Tor.
### Tor Browser
The easiest and most reliable solution would be to use the [Tor Browser](https://www.torproject.org/projects/torbrowser.html.en). Though that won't use your Pi-hole DNS Server out of the box. You can however disable `Proxy DNS when using SOCKS v5` in Tor Browsers Preferences -> Advanced -> Network -> Settings and [make sure](#make-sure-it-works) to point your system to use Pi-hole with DNS over Tor activated.
### Your Browser
Edit `/etc/tor/torrc` on your Pi-hole as root, include the following line at the end and save the changes
```
SocksPort 0.0.0.0:9050
```
**Note:** You should make sure that only your LAN devices are able to access your Pi-hole on port 9050.
Restart Tor
```
**Note:** You should make sure that only your LAN devices are able to access your Pi-hole on port 9050.
Restart Tor
```bash
sudo service tor restart
```
Point your browser to use your Pi-hole IP or Hostname (e.g. `pi.hole`) and `Port 9050` as Socks5 Proxy. Do not enable `Proxy DNS when using SOCKS v5` and [make sure](#make-sure-it-works) to point your system to use Pi-hole with DNS over Tor activated.
* For Chrome you can either use e.g. the [Proxy SwitchyOmega Extension](https://chrome.google.com/webstore/detail/proxy-switchyomega/padekgcemlokbadohgkifijomclgjgif) or start Chrome with [command-line parameters](https://www.chromium.org/developers/design-documents/network-stack/socks-proxy).
Point your browser to use your Pi-hole IP or Hostname (e.g. `pi.hole`) and `Port 9050` as Socks5 Proxy. Do not enable `Proxy DNS when using SOCKS v5` and [make sure](#make-sure-it-works) to point your system to use Pi-hole with DNS over Tor activated.
* For Firefox you can either use e.g. the [FoxyProxy Add-on](https://addons.mozilla.org/en-US/firefox/addon/foxyproxy-standard/) or configure the Socks5 Proxy directly in the Firefox Preferences.
* For Chrome you can either use e.g. the [Proxy SwitchyOmega Extension](https://chrome.google.com/webstore/detail/proxy-switchyomega/padekgcemlokbadohgkifijomclgjgif) or start Chrome with [command-line parameters](https://www.chromium.org/developers/design-documents/network-stack/socks-proxy).
* For Firefox you can either use e.g. the [FoxyProxy Add-on](https://addons.mozilla.org/en-US/firefox/addon/foxyproxy-standard/) or configure the Socks5 Proxy directly in the Firefox Preferences.
If you use a Proxy Add-on/Extension you can also e.g. route everything per default over Tor and only whitelist some sites that you need to perform really good.
#### Accessing .onion addresses
If you want to access .onion addresses with this kind of setup you have to activate [Transparent Access to Tor Hidden Services](https://www.grepular.com/Transparent_Access_to_Tor_Hidden_Services) on the Pi-hole host.
If you want to access .onion addresses with this kind of setup you have to activate [Transparent Access to Tor Hidden Services](https://www.grepular.com/Transparent_Access_to_Tor_Hidden_Services) on the Pi-hole host.
***
#### Notes
* Don't define other regular Upstream DNS Servers than the Tor one if you want to avoid that your Pi-hole makes plaintext DNS requests.
* From the [Tor Manual](https://www.torproject.org/docs/tor-manual.html.en) regarding `DNSPort`:
```
This port only handles A, AAAA, and PTR requests
```
* Don't define other regular Upstream DNS Servers than the Tor one if you want to avoid that your Pi-hole makes plaintext DNS requests.
* From the [Tor Manual](https://www.torproject.org/docs/tor-manual.html.en) regarding `DNSPort`:
> This port only handles A, AAAA, and PTR requests
docs/guides/traefik-configuration-nodocker.md
+59 -55
View File
@@ -1,73 +1,77 @@
### Notes & Warnings
- **This is an unsupported configuration created by the community**
- This describes on how to use traefik on a (possibly remote) machine to serve pi-hole via https and a different domain, not how to to 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)
```
debug = false
checkNewVersion = true
logLevel = "INFO"
defaultEntryPoints = ["https","http"]
[entryPoints]
[entryPoints.http]
address = ":80"
[entryPoints.http.redirect]
```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"
[entryPoints.https]
address = ":443"
[entryPoints.https.tls]
# Optional Security Settings
[retry]
OnHostRule = true
[acme.tlsChallenge]
[[acme.domains]]
main = "pihole.domain.tld"
[docker]
endpoint = "unix:///var/run/docker.sock"
domain = "domain.tld"
watch = true
exposedbydefault = false
[file]
watch = true
[acme]
email = "emailForLetsEncryptACME"
storage = "acme.json"
storageFile = "/etc/traefik/acme/acme.json"
entryPoint = "https"
OnHostRule = true
[acme.tlsChallenge]
[[acme.domains]]
main = "pihole.domain.tld"
[backends]
[backends.pihole]
[backends.pihole.servers.server1]
url = "http://IP-Of-Pihole:80"
[file]
watch = true
[frontends]
[frontends.pihole]
backend = "pihole"
passHostHeader = true
[frontends.pihole.headers]
STSSeconds = 31536000
[frontends.pihole.routes.route1]
rule = "Host:pihole.domain.tld"
```
[backends]
[backends.pihole]
[backends.pihole.servers.server1]
url = "http://IP-Of-Pihole:80"
3. Edit your /etc/lighthttpd/external.conf to
[frontends]
[frontends.pihole]
backend = "pihole"
passHostHeader = true
[frontends.pihole.headers]
STSSeconds = 31536000
[frontends.pihole.routes.route1]
rule = "Host:pihole.domain.tld"
```
7. Edit your /etc/lighthttpd/external.conf to
```
$SERVER["socket"] == ":80" {
# Ensure the Pi-hole Block Page knows that this is not a blocked domain
setenv.add-environment = ("fqdn" => "true")
```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")
}
}
```
$HTTP["host"] =~ "^pi\.hole" {
url.redirect = ("^/(.*)" => "https://pihole.domain.tld/$1")
}
}
```
8. Restart pi-holes lighthttpd and traefik, then you should be able to access your pihole via ```https://pihole.domain.tld/```
4. Restart pi-hole's lighttpd and traefik, then you should be able to access your pihole via `https://pihole.domain.tld/`
docs/guides/unbound.md
+4 -3
View File
@@ -59,7 +59,7 @@ sudo apt install unbound
**Important**: Download the current root hints file (the list of primary root servers which are serving the domain "." - the root domain). Update it roughly every six months. Note that this file changes infrequently.
```
```bash
wget -O root.hints https://www.internic.net/domain/named.root
sudo mv root.hints /var/lib/unbound/
```
@@ -127,17 +127,18 @@ server:
Start your local recursive server and test that it's operational:
```
```bash
sudo service unbound start
dig pi-hole.net @127.0.0.1 -p 5353
```
The first query may be quite slow, but subsequent queries, also to other domains under the same TLD, should be fairly quick.
### Test validation
You can test DNSSEC validation using
```
```bash
dig sigfail.verteiltesysteme.net @127.0.0.1 -p 5353
dig sigok.verteiltesysteme.net @127.0.0.1 -p 5353
```
docs/guides/upstream-dns-providers.md
+14 -5
View File
@@ -1,5 +1,6 @@
The Pi-hole setup offers 8 options for an upstream DNS Provider during the initial setup.
```
The Pi-hole setup offers 8 options for an upstream DNS Provider during the initial setup.
```text
Google
OpenDNS
Level3
@@ -13,6 +14,7 @@ Custom
During the pi-hole installation you select 1 of the 7 preset providers or enter one of your own. Below you can find more information on each of the DNS Providers, along with some additional providers which have different kinds of extra filtering options (spam, phishing, adult content, etc).
### Google
Default upstream DNS provider on the Pi-hole.
- 8.8.8.8
@@ -21,6 +23,7 @@ Default upstream DNS provider on the Pi-hole.
[More information on Google Public DNS](https://developers.google.com/speed/public-dns/)
### OpenDNS Home (owned by Cisco)
Built-in features include a phishing filter, this is the OpenDNS version the Pi-hole would use if you select it during setup.
- 208.67.222.222
@@ -28,22 +31,24 @@ Built-in features include a phishing filter, this is the OpenDNS version the Pi-
[More information on OpenDNS Home](https://use.opendns.com/) + [OpenDNS Wiki Page](https://en.wikipedia.org/wiki/OpenDNS)
OpenDNS also provides the *OpenDNS FamilyShield (free)- option. The service blocks pornographic content, including our “Pornography,” “Tasteless,” and “Sexuality” categories, in addition to proxies and anonymizers (which can render filtering useless). It also blocks phishing and some malware.
OpenDNS also provides the OpenDNS FamilyShield (free)- option. The service blocks pornographic content, including our “Pornography,” “Tasteless,” and “Sexuality” categories, in addition to proxies and anonymizers (which can render filtering useless). It also blocks phishing and some malware.
- 208.67.222.123
- 208.67.220.123
- 0000:0000:0000:0000:0000:ffff:d043:de7b (ipv6)
- 0000:0000:0000:0000:0000:ffff:d043:dc7b (ipv6)
[More information on OpenDNS FamilyShield](https://store.opendns.com/setup/#/familyshield) + [OpenDNS FamilyShield introduction Blog](https://blog.opendns.com/2010/06/23/introducing-familyshield-parental-controls/)
### Level3 DNS
This DNS service does no filtering of itself, but redirects mistyped URL to Level 3 Web Search.
- 4.2.2.1
- 4.2.2.2
### Comodo Secure DNS
SecureDNS references a real-time block list (RBL) of harmful websites (i.e. phishing sites, malware sites, spyware sites, and parked domains that may contain excessive advertising including pop-up and/or pop-under advertisements, etc.) and will warn you whenever you attempt to access a site containing potentially threatening content.
- 8.26.56.26
@@ -52,6 +57,7 @@ SecureDNS references a real-time block list (RBL) of harmful websites (i.e. phis
[More information on Comodo Secure DNS](https://www.comodo.com/secure-dns/)
### DNS.WATCH
DNS.WATCH offers Fast, free and uncensored DNS resolution.
- 84.200.69.80
@@ -62,6 +68,7 @@ DNS.WATCH offers Fast, free and uncensored DNS resolution.
[More information on DNS.WATCH](https://dns.watch/)
### Quad9
Quad9 is a free, recursive, anycast DNS platform that provides end users robust security protections, high-performance, and privacy.
- 9.9.9.9
@@ -71,6 +78,7 @@ Quad9 is a free, recursive, anycast DNS platform that provides end users robust
[More information on Quad9](https://www.quad9.net/about/)
### CloudFlare DNS
CloudFlare will never log your IP address (the way other companies identify you). The independent DNS monitor DNSPerf ranks 1.1.1.1 the fastest DNS service in the world.
- 1.1.1.1
@@ -79,9 +87,10 @@ CloudFlare will never log your IP address (the way other companies identify you)
[More information on Cloudflare DNS](https://cloudflare-dns.com/dns/#explanation)
### Custom
With custom, you'll choose your favorite DNS provider.
If you care about net independence and privacy I'll suggest you give a look at : [OpenNIC DNS Project](https://servers.opennic.org/)
### More information
### More information.
There are even more public DNS server, you can find many (with some extra information) on the [lifewire.com website](https://www.lifewire.com/free-and-public-dns-servers-2626062). A benchmark of these DNS servers (by Gibson Research Center) is available [here](https://www.grc.com/dns/Benchmark.htm)
docs/guides/vpn/android-client.md
+7 -7
View File
@@ -2,7 +2,7 @@
- Log into your OpenVPN server and use the road warrior installer to create a new certificate for your device:
```
```text
root@ubuntu-512mb-fra1-01:~# bash openvpn-install.sh
Looks like OpenVPN is already installed
@@ -36,18 +36,18 @@ Client android added, configuration is available at /root/android.ovpn
- Copy the mentioned file (`/root/android.ovpn`) to your Android device (e.g. SD card) and import it in the app:
![](Android-Import-1.png)
![](Android-Import-1.png)
![](Android-Import-2.png)
![](Android-Import-2.png)
![](Android-Import-3.png)
![](Android-Import-3.png)
![](Android-Import-4.png)
![](Android-Import-4.png)
- Connect to your OpenVPN server
![](Android-Connected.png)
![](Android-Connected.png)
- You are ready to go!
![](Android-Pi-hole.png)
![](Android-Pi-hole.png)
docs/guides/vpn/clients.md
+20 -11
View File
@@ -1,17 +1,18 @@
## Create a client config file (`.ovpn`)
Now that the server is configured, you'll want to connect some clients so you can make use of your Pi-hole wherever you are. Doing so requires the use of a certificate. You generate these and the resulting `.ovpn` file by running the installer and choosing `1) Add a new user` for each client that will connect to the VPN.
Now that the server is configured, you'll want to connect some clients so you can make use of your Pi-hole wherever you are. Doing so requires the use of a certificate. You generate these and the resulting `.ovpn` file by running the installer and choosing `1) Add a new user` for each client that will connect to the VPN.
You can repeat this process for as many clients as you need. In this example, we'll "Add a new user" by naming the `.ovpn` file the same as the client's hostname but you may want to adopt your own naming strategy.
Run the OpenVPN installer again
```
```bash
./openvpn-install.sh
```
Choose `1) Add a new user` and enter a client name
```
```text
Looks like OpenVPN is already installed
What do you want to do?
@@ -36,6 +37,7 @@ The OpenVPN documentation has some decent [guides on connecting desktop clients
2. connect a Linux machine
### iOS
First make sure the OpenVPN connect app is installed on your phone or mobile device.
Import the `.ovpn` file into iOS. There are several ways to do this, but be careful about transferring it over an insecure medium.
@@ -45,24 +47,28 @@ Import the `.ovpn` file into iOS. There are several ways to do this, but be car
3. Message the file to yourself (not recommended)
4. Email the file to yourself (not recommended)
>**WARNING** Anyone who gets his hands on this configuration/certificate file can obtain full access to your VPN. Make sure that you use only trusted paths for transferring the file (e.g. never send it via an un-encrypted channel, e.g. email or FTP). Best strategy is to use an USB thumb drive to avoid any network transport at all (when possible). Make sure to delete the certificate on the USB drive afterwards.
!!! WARNING
Anyone who gets his hands on this configuration/certificate file can obtain full access to your VPN. Make sure that you use only trusted paths for transferring the file (e.g. never send it via an un-encrypted channel, e.g. email or FTP). Best strategy is to use an USB thumb drive to avoid any network transport at all (when possible). Make sure to delete the certificate on the USB drive afterwards.
>**NOTICE** If one of your certificates has been compromised, remove it using option 2 when you run the installer and generate a new certificate. This will effectively lock out anyone who might have gotten access to the certificate.
!!! NOTICE
If one of your certificates has been compromised, remove it using option 2 when you run the installer and generate a new certificate. This will effectively lock out anyone who might have gotten access to the certificate.
Once you get it on your device, you can open the file in the OpenVPN app.
Once you get it on your device, you can open the file in the OpenVPN app.
Click the green plus to add the profile to your phone.
You can connect from within the app or you can connect from the Settings app once you grant it access to do so.
### Linux
We'll demonstrate the procedure here for Ubuntu Linux (which trivially extends to Linux Mint, etc.)
1. Install the necessary network-manager plugins
```
sudo apt-get install network-manager-openvpn network-manager-openvpn-gnome
sudo service network-manager restart
```
```bash
sudo apt-get install network-manager-openvpn network-manager-openvpn-gnome
sudo service network-manager restart
```
2. Securely copy the necessary certificates from your OpenVPN server to your client (e.g. using `sftp`). They are located in `/etc/openvpn/server/easy-rsa/pki`
@@ -75,14 +81,17 @@ You will need:
* TA Key: `/etc/openvpn/server/ta.key`
Further details can be found in the screenshots provided below:
![](NetworkManager3.png)
![](NetworkManager4.png)
![](NetworkManager5.png)
![](NetworkManager6.png)
![](NetworkManager7.png)
Your whole network traffic will now securely be transferred to your Pi-hole.
![](VPNclients.png)
### Windows
You will have to install additional software. See https://openvpn.net/community-downloads/
You will have to install additional software. See <https://openvpn.net/community-downloads/>
docs/guides/vpn/dual-VPN.md
+10 -7
View File
@@ -1,8 +1,10 @@
### Dual VPN Setup - Separate DNS and VPN Traffic
### Dual VPN Setup - Separate DNS and VPN Traffic
In order to separate VPN traffic from DNS queries you will need to run two VPN servers. One server routes the normal user traffic and the second routes only DNS requests. This can be done with two OpenVPN configurations.
#### Prerequisites and Configuration
You should have an existing OpenVPN server configured and running. We are going to use the original configuration file located at `/etc/openvpn/server/server.conf`.
You should have an existing OpenVPN server configured and running. We are going to use the original configuration file located at `/etc/openvpn/server/server.conf`.
First, copy the file:
@@ -18,7 +20,7 @@ sudo nano /etc/openvpn/server/server2.conf
We will need to change the port to one different from the original, so that it does not conflict with the first instance of OpenVPN. Assuming you used the default port configuration, you should have 1194 as the port. You need to change this to a different value, making sure the port is available - 1195 should be.
Next, if needed, port forward the newly configured port from your router to your device. You will also need to assign a different class of IP addresses that will serve this connection only.
Next, if needed, port forward the newly configured port from your router to your device. You will also need to assign a different class of IP addresses that will serve this connection only.
Your server line should look like this:
@@ -26,17 +28,17 @@ Your server line should look like this:
server 10.9.0.0 255.255.255.0
```
Make sure that the DNS requests go though the instance of OpenVPN:
Make sure that the DNS requests go though the instance of OpenVPN:
```
push "dhcp-option DNS 10.9.0.1"
```
One other setting that we need to change is to comment out the `bypass-dhcp` instruction so that it looks like:
One other setting that we need to change is to comment out the `bypass-dhcp` instruction so that it looks like:
```
# push "redirect-gateway def1 bypass-dhcp"`.
```
```
Commenting out this line ensures that no traffic is routed via the VPN server.
@@ -46,7 +48,7 @@ Save the file and start the second instance of OpenVPN:
systemctl start openvpn@server2.service
```
*If your distribution does not have `systemctl` you may use the command below to start an OpenVPN daemon with your second configuration:*
*If your distribution does not have `systemctl` you may use the command below to start an OpenVPN daemon with your second configuration:*
```bash
/usr/sbin/openvpn --daemon --writepid /var/run/openvpn/server2.pid --cd /etc/openvpn --config server2.conf --script-security 2
@@ -55,6 +57,7 @@ systemctl start openvpn@server2.service
Finally, edit the existing `.ovpn` file used for the client connection. Update the port from the previous value to the port you used for the second instance of OpenVPN.
#### Testing
Before testing, make sure that:
1. Port forwarding is configured for the second instance of OpenVPN.
docs/guides/vpn/dual-operation.md
+8 -8
View File
@@ -22,32 +22,32 @@ Afterwards, we change the interface of `Pi-hole` to `eth0` (your local network a
After a restart of the OpenVPN server, all clients should be able to see all devices within your (at home) local network. This is an example running on a distant server, which is connected through the VPN and can successfully communicate with all internal devices:
```
```bash
me@client ~ $ ifconfig
eth0 Link encap:Ethernet HWaddr e0:xx:xx:xx:xx:xx
eth0 Link encap:Ethernet HWaddr e0:xx:xx:xx:xx:xx
inet addr:134.x.x.x Bcast:134.x.x.x Mask:255.x.x.x
inet6 addr: X:X:X:X::X/64 Scope:Link
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:3623911 errors:0 dropped:0 overruns:0 frame:0
TX packets:2803670 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:1000
collisions:0 txqueuelen:1000
RX bytes:1921375471 (1.9 GB) TX bytes:1227835028 (1.2 GB)
lo Link encap:Local Loopback
lo Link encap:Local Loopback
inet addr:127.0.0.1 Mask:255.0.0.0
inet6 addr: ::1/128 Scope:Host
UP LOOPBACK RUNNING MTU:65536 Metric:1
RX packets:553426 errors:0 dropped:0 overruns:0 frame:0
TX packets:553426 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:1
collisions:0 txqueuelen:1
RX bytes:113417383 (113.4 MB) TX bytes:113417383 (113.4 MB)
tun0 Link encap:UNSPEC HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00
tun0 Link encap:UNSPEC HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00
inet addr:10.8.0.2 P-t-P:10.8.0.2 Mask:255.255.255.0
UP POINTOPOINT RUNNING NOARP MULTICAST MTU:1500 Metric:1
RX packets:274676 errors:0 dropped:0 overruns:0 frame:0
TX packets:331178 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:100
collisions:0 txqueuelen:100
RX bytes:43745313 (43.7 MB) TX bytes:43956250 (43.9 MB)
me@client ~ $ ping 192.168.2.123
@@ -64,8 +64,8 @@ PING 192.168.2.123 (192.168.2.123) 56(84) bytes of data.
rtt min/avg/max/mdev = 18.740/18.894/19.017/0.189 ms
```
### Important last step
The undocumented `pihole -a -i all` command is simply what runs when you choose _Listen on all interfaces, permit all origins (make sure your Pi-hole is firewalled)_, which if you've read this far in the tutorial, you should understand that we don't want you to knowingly or unknowing set up an open resolver.
![screenshot](listening-behavior.png)
docs/guides/vpn/dynDNS.md
+23 -12
View File
@@ -1,12 +1,12 @@
If you operate your Pi-hole + OpenVPN at home, it is very likely that you are sitting behind a NAT / dynamically changing IP address. In this case, you should set up a dynamic DNS record, which allows you to reach your server. You can exchange the address that has been configured during the setup of OpenVPN like this:
```
```bash
vim /etc/openvpn/server/client-common.txt
```
Look for the `remote` line and adjust it accordingly (remove IP address, add host name), e.g.
```
```text
remote home.mydomain.de 1194
```
@@ -14,7 +14,7 @@ This change has to be repeated in each client config file (`*.conf`) that you ha
If you have set up a DDNS domain for your IP address, you will likely need to add a host-record to Pi-hole's settings.
```
```bash
pihole -a hostrecord home.mydomain.de 192.168.1.10
```
@@ -23,12 +23,14 @@ If you don't do this, clients (like the Android OpenVPN client) will not able to
## Setting up DynDNS update
If your router cannot update the dynamic DNS record, you can use for example `ddclient`.
```
```bash
sudo apt install ddclient
```
This configuration file resides in `/etc/ddclient.conf`. During installation, `apt` probably already asked you some questions and prepared a useful config file. In general, configuration files look like:
```
```bash
# /etc/ddclient.conf
#
protocol=dyndns2
@@ -39,7 +41,8 @@ myhost.dyndns.org
```
If you want to have `ddclient` running as daemon (recommended!), change also your `/etc/defaults/ddclient` to:
```
```bash
# Configuration for ddclient scripts
# generated from debconf on Do 9. Feb 22:29:13 CET 2017
#
@@ -63,15 +66,22 @@ daemon_interval="300"
```
### Example: Strato DynDNS
In the following, we give an example of how to setup `ddclient` using the German Internet hosting provider Strato. First, you need to create a subdomain. Then you need to enable DnyDNS for this domain:
> ![](Strato-DynDNS-Domain.png)
> <hr>
> ![](Strato-DynDNS-Enable.png)
> <hr>
> ![](Strato-DynDNS-Password.png)
![](Strato-DynDNS-Domain.png)
---
![](Strato-DynDNS-Enable.png)
---
![](Strato-DynDNS-Password.png)
Afterwards, modify your `ddclient` config file to look like:
```
```bash
protocol=dyndns2
use=if, if=eth0
use=web, web=checkip.dyndns.org
@@ -81,4 +91,5 @@ password='password1234'
meine.domain.de
```
where you replace `strato-login-name` by your Strato login name (most likely your domain name, like `maxmustermann.de`), `password1234` by the password you configured above (see third screenshot), and `meine.domain.de` by the subdomain you created and enabled dynamic DNS for.
docs/guides/vpn/firewall.md
+14 -13
View File
@@ -12,7 +12,7 @@ It's recommended that you [clear out your entire firewall](https://serverfault.c
Enter this command, which will allow all traffic through the VPN `tun0` interface.
```
```bash
iptables -I INPUT -i tun0 -j ACCEPT
```
@@ -20,7 +20,7 @@ iptables -I INPUT -i tun0 -j ACCEPT
These commands will allow DNS and HTTP needed for name resolution (using Pi-hole as a resolver) and accessing the Web interface, respectively.
```
```bash
iptables -A INPUT -i tun0 -p tcp --destination-port 53 -j ACCEPT
iptables -A INPUT -i tun0 -p udp --destination-port 53 -j ACCEPT
iptables -A INPUT -i tun0 -p tcp --destination-port 80 -j ACCEPT
@@ -28,7 +28,7 @@ iptables -A INPUT -i tun0 -p tcp --destination-port 80 -j ACCEPT
You will also want to enable SSH and VPN access from anywhere.
```
```bash
iptables -A INPUT -p tcp --destination-port 22 -j ACCEPT
iptables -A INPUT -p tcp --destination-port 1194 -j ACCEPT
iptables -A INPUT -p udp --destination-port 1194 -j ACCEPT
@@ -36,19 +36,19 @@ iptables -A INPUT -p udp --destination-port 1194 -j ACCEPT
The next crucial setting is to explicitly allow TCP/IP to do "three way handshakes":
```
```bash
iptables -I INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT
```
Also, we want to allow any loopback traffic, i.e. the server is allowed to talk to itself without any limitations using 127.0.0.0/8:
```
```bash
iptables -I INPUT -i lo -j ACCEPT
```
Finally, reject access from anywhere else (i.e. if no rule has matched up to this point):
```
```bash
iptables -P INPUT DROP
```
@@ -58,7 +58,7 @@ Since you're `:head-desk:`ing with `iptables`, you can also use this opportunity
> Why doesn't Pi-hole just use a certificate to prevent this? The answer is [here](https://discourse.pi-hole.net/t/slow-loading-websites/3408/12).
```
```bash
iptables -A INPUT -p udp --dport 80 -j REJECT --reject-with icmp-port-unreachable
iptables -A INPUT -p tcp --dport 443 -j REJECT --reject-with tcp-reset
iptables -A INPUT -p udp --dport 443 -j REJECT --reject-with icmp-port-unreachable
@@ -70,7 +70,7 @@ Depending on the systems you have connecting, you may benefit from appending `--
If your server is reachable via IPv6, you'll need to run the same commands but using `ip6tables`:
```
```bash
ip6tables -A INPUT -i tun0 -p tcp --destination-port 53 -j ACCEPT
ip6tables -A INPUT -i tun0 -p udp --destination-port 53 -j ACCEPT
ip6tables -A INPUT -i tun0 -p tcp --destination-port 80 -j ACCEPT
@@ -84,15 +84,16 @@ ip6tables -A INPUT -p tcp --dport 443 -j REJECT --reject-with tcp-reset
ip6tables -A INPUT -p udp --dport 443 -j REJECT --reject-with icmp6-port-unreachable
ip6tables -P INPUT DROP
```
View the rules you just created
```
```bash
iptables -L --line-numbers
```
and they should look something like this:
```
```text
Chain INPUT (policy DROP)
num target prot opt source destination
1 ACCEPT all -- anywhere anywhere
@@ -124,7 +125,7 @@ num target prot opt source destination
Similarly, `ip6tables -L --line-numbers` should look like this:
```
```text
Chain INPUT (policy DROP)
num target prot opt source destination
1 ACCEPT all anywhere anywhere
@@ -153,14 +154,14 @@ Connect to the VPN as a client and verify you can resolve DNS names as well as a
If things look good, you may want to save your rules so you can revert to them if you ever make changes to the firewall. Save them with these commands:
```
```bash
iptables-save > /etc/pihole/rules.v4
ip6tables-save > /etc/pihole/rules.v6
```
Similarly, you can restore these rules:
```
```bash
iptables-restore < /etc/pihole/rules.v4
ip6tables-restore < /etc/pihole/rules.v6
```
docs/guides/vpn/installation.md
+10 -5
View File
@@ -10,17 +10,19 @@ For security purposes, it is recommended that the CA machine should be separate
This is less convenient, so many users will simply decide to install Pi-hole and OpenVPN on a single machine, which is what this guide will walkthrough.
### Install the OpenVPN server
First, download the OpenVPN installer; make it executable, and then run it:
```
```bash
wget https://git.io/vpn -O openvpn-install.sh
chmod 755 openvpn-install.sh
./openvpn-install.sh
```
Enter your server's IP address and accept all the defaults, unless you require special needs:
```
```text
Welcome to this quick OpenVPN "road warrior" installer
I need to ask you a few questions before starting the setup
@@ -54,17 +56,20 @@ Client name: pihole
Okay, that was all I needed. We are ready to setup your OpenVPN server now
Press any key to continue...
```
Let the installer run...
```
```text
Finished!
Your client configuration is available at /root/pihole.ovpn
If you want to add more clients, you simply need to run this script again!
```
### Install Pi-hole
Next, install Pi-hole and choose `tun0` as the interface and `10.8.0.1/24` as the IP address. You can accept the rest of the defaults, or configure Pi-hole to your liking. The interface selection is the most important step; if you don't choose `tun0` (at least to begin with), it will not work properly.
```
```bash
curl -sSL https://install.pi-hole.net | bash
```
docs/guides/vpn/only-dns-via-vpn.md
+13 -6
View File
@@ -4,7 +4,7 @@ With this setup, you will force connected clients to use **only the DNS provided
Edit your `/etc/openvpn/server/server.conf` and remove (comment out) the following line:
```
```ini
# push "redirect-gateway def1 bypass-dhcp"
```
@@ -23,11 +23,14 @@ When using the Network Manager, you will have to do some additional setting on t
#### Alternative 1: Disable Network Manager's internal DNS server
Edit `/etc/NetworkManager/NetworkManager.conf`:
```
```ini
# dns=dnsmasq
```
and restart the Network Manager:
```
```bash
sudo restart network-manager
```
@@ -40,7 +43,8 @@ You can also set the address of the DNS server manually (use the device which ac
![](NetworkManager2.png)
After doing either alternative, you should see:
```
```text
pi.hole has address W.X.Y.Z (outside address of your VPN server)
pi.hole has IPv6 address A:B:C:D:E:F (outside address of your VPN server)
```
@@ -50,16 +54,19 @@ The web interface of your Pi-hole will be visible at `http://pi.hole/admin/` (ev
![](VPNdashboard.png)
---
## Troubleshooting
If your new DNS server configuration has not been activated (try restarting the interface / system) you will see
```
```text
host pi.hole
Host pi.hole not found: 3(NXDOMAIN)
```
If you are not connected to your VPN network you will see
```
```text
host pi.hole
;; connection timed out; no servers could be reached
```
docs/guides/vpn/overview.md
+2
View File
@@ -1,6 +1,7 @@
>This tutorial is tailored for setting up OpenVPN on a cloud-hosted virtual server (such as [Digital Ocean](https://www.digitalocean.com/?refcode=344d234950e1)). If you wish to have this working on your home network, you will need to tailor Pi-hole to listen on `eth0` (or similar), which we explain in [this section of the tutorial](dual-operation.md).
### High-level Overview
Using a VPN is a responsible, respectful, and safe way to access your Pi-hole's capabilities remotely. Setting up a DNS server has become a simple task with Pi-hole's automated installer, which has resulted in many people knowingly--or unknowingly--creating an open resolver, which aids in DNS Amplification Attacks.
We do not encourage open resolvers but there are always people wanting access to their ad-blocking capabilities outside of their home network, whether it's on their cellular network or on an unsecured wireless network. This article aims to provide a step-by-step walk-through on setting up a server running Pi-hole and OpenVPN so you can connect to your Pi-hole's DNS from anywhere. This guide should work for a private server installed on your private network, but it will also work for cloud servers, such as those created on [Digital Ocean](https://www.digitalocean.com/?refcode=344d234950e1).
@@ -18,4 +19,5 @@ If you don't want a full-tunnel, we provide a wiki of how to [set up your server
In the end, you will have access to a VPN that uses Pi-hole for DNS and tunnels some or all of your network traffic
---
This manual is partially based on this [HowTo](https://discourse.pi-hole.net/t/pi-hole-with-openvpn-vps-debian/861) on [Discourse](https://discourse.pi-hole.net).
docs/guides/vpn/setup-openvpn-server.md
+12 -6
View File
@@ -3,17 +3,20 @@
First, find the IP of your `tun0` interface:
On Jessie
```
```bash
ifconfig tun0 | grep 'inet addr'
```
On Stretch
```
```bash
ip a
```
Edit the OpenVPN config file:
```
```bash
vim /etc/openvpn/server/server.conf
```
@@ -29,6 +32,7 @@ This `push` directive is setting a [DHCP option](https://www.incognito.com/tutor
It's [suggested to have Pi-hole be the only resolver](https://discourse.pi-hole.net/t/why-should-pi-hole-be-my-only-dns-server/3376) as it defines the upstream servers. Setting a non-Pi-hole resolver here [may have adverse effects on ad blocking](https://discourse.pi-hole.net/t/why-should-pi-hole-be-my-only-dns-server/3376) but it _can_ provide failover connectivity in the case of Pi-hole not working if that is something you are concerned about.
Furthermore, you might want to enable logging for your OpenVPN server. In this case, add the following lines to your server's config file:
```
log /var/log/openvpn.log
verb 3
@@ -37,7 +41,8 @@ verb 3
### Restart OpenVPN to apply the changes
Depending on your operating system, one of these commands should work to restart the service.
```
```bash
systemctl restart openvpn-server@server
service openvpn-server@server restart
```
@@ -50,12 +55,13 @@ You can repeat this process for as many clients as you need. In this example, w
Run the OpenVPN installer again
```
```bash
./openvpn-install.sh
```
Choose `1) Add a new user` and enter a client name
```
```text
Looks like OpenVPN is already installed
What do you want to do?
docs/guides/vpn/troubleshooting.md
+7
View File
@@ -1,15 +1,20 @@
### CRL expired
OpenVPN 2.4 and newer check the validity of the Certificate Revocation List (CRL). This can result in a sudden malfunction of `openvpn` after an update even though no configuration files have changed. This error manifests in the following, not very helpful, error on the client side:
```
Wed Apr 24 11:19:07 2019 VERIFY OK: depth=0, CN=server
Wed Apr 24 11:19:07 2019 Connection reset, restarting [0]
Wed Apr 24 11:19:07 2019 SIGUSR1[soft,connection-reset] received, process restarting
Wed Apr 24 11:19:07 2019 Restart pause, 5 second(s)
```
Android clients simply report: "Transport error, trying to reconnect..."
> ![](Android-Transport-Error.png)
On the OpenVPN server, the following messages are logged:
```
Wed Apr 24 11:19:07 2019 aaa.bbb.ccc.ddd:pppp TLS: Initial packet from [AF_INET]aaa.bbb.ccc.ddd:pppp, sid=57719cb8 77945ae9
Wed Apr 24 11:19:07 2019 aaa.bbb.ccc.ddd:pppp VERIFY ERROR: depth=0, error=CRL has expired: CN=client1
@@ -20,7 +25,9 @@ Wed Apr 24 11:19:07 2019 aaa.bbb.ccc.ddd:pppp TLS Error: TLS handshake failed
Wed Apr 24 11:19:07 2019 aaa.bbb.ccc.ddd:pppp Fatal TLS error (check_tls_errors_co), restarting
Wed Apr 24 11:19:07 2019 aaa.bbb.ccc.ddd:pppp SIGUSR1[soft,tls-error] received, client-instance restarting
```
The error is `CRL has expired` and can be solved using the following commands:
```
sudo -s
cd /etc/openvpn
docs/guides/whitelist-blacklist.md
+10 -13
View File
@@ -2,10 +2,9 @@
[This extension for Google Chrome](https://chrome.google.com/webstore/detail/adamone-assistant/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.
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.
@@ -16,11 +15,11 @@ Each script accepts the following parameters:
<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>
<tr>
<th><code>-d</code></th>
<td>Removal mode. Domains will be removed from the list, rather than added</td>
</tr>
</tr>
<tr>
<th><code>-nr</code></th>
<td>Update blacklist without refreshing dnsmasq</td>
@@ -38,19 +37,18 @@ Each script accepts the following parameters:
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
#### 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>
<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>
<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>
@@ -61,19 +59,18 @@ Domains passed are parsed by the script to ensure they are valid domains. If a d
To remove domains from the whitelist:
Add `-d` as an additional argument (e.g `pihole -w -d domain1 [domain2...]`)
##### Example `pihole -b` usages
#### 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>
<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>
<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>
@@ -82,4 +79,4 @@ Add `-d` as an additional argument (e.g `pihole -w -d domain1 [domain2...]`)
</table>
To remove domains from the blacklist:
Add `-d` as an additional argument (e.g `pihole -b -d domain1 [domain2...]`)
Add `-d` as an additional argument (e.g `pihole -b -d domain1 [domain2...]`)
docs/index.md
+6 -1
View File
@@ -3,6 +3,7 @@ title: Overview of Pi-hole
description: Brief overview of Pi-hole
last_updated: Thur May 02 01:00:00 2019 UTC
---
<p align="center">
<a href="https://pi-hole.net"><img src="https://pi-hole.github.io/graphics/Vortex/Vortex_with_text.png" width="150" height="255" alt="Pi-hole"></a><br/>
<b>Network-wide ad blocking via your own Linux hardware</b><br/>
@@ -24,17 +25,20 @@ The Pi-hole[®](https://pi-hole.net/trademark-rules-and-brand-guidelines/) is a
-----
## Pi-hole is free, but powered by your support
There are many reoccurring costs involved with maintaining free, open source, and privacy respecting software; expenses which [our volunteer developers](https://github.com/orgs/pi-hole/people) pitch in to cover out-of-pocket. This is just one example of how strongly we feel about our software, as well as the importance of keeping it maintained.
Make no mistake: **your support is absolutely vital to help keep us innovating!**
### Donations
Sending a donation using our links below is **extremely helpful** in offsetting a portion of our monthly expenses:
- <a href="https://pi-hole.net/donate/">Donate via PayPal or Stripe</a>
- [Donate via PayPal or Stripe](https://pi-hole.net/donate/)
- [Bitcoin, Bitcoin Cash, Ethereum, Litecoin](https://commerce.coinbase.com/checkout/dd304d04-f324-4a77-931b-0db61c77a41b)
### Alternative support
If you'd rather not donate (_which is okay!_), there are other ways you can help support us:
- [Pi-hole Swag Store](https://pi-hole.net/shop/)
@@ -44,6 +48,7 @@ If you'd rather not donate (_which is okay!_), there are other ways you can help
- Spreading the word about our software, and how you have benefited from it
### Contributing via GitHub
We welcome _everyone_ to contribute to issue reports, suggest new features, and create pull requests.
If you have something to add - anything from a typo through to a whole new feature, we're happy to check it out! Just make sure to fill out our template when submitting your request; the questions that it asks will help the volunteers quickly understand what you're aiming to achieve.
docs/main/basic-install.md
+6 -3
View File
@@ -1,7 +1,8 @@
## One-Step Automated Install
Those who want to get started quickly and conveniently, may install Pi-hole using the following command:
```BASH
```bash
curl -sSL https://install.pi-hole.net | bash
```
@@ -11,14 +12,16 @@ curl -sSL https://install.pi-hole.net | bash
If you would prefer to review the code before installation, we provide these alternative installation methods.
#### Alternative 1: Clone our repository and run
```BASH
```bash
git clone --depth 1 https://github.com/pi-hole/pi-hole.git Pi-hole
cd "Pi-hole/automated install/"
sudo bash basic-install.sh
```
#### Alternative 2: Manually download the installer and run
```BASH
```bash
wget -O basic-install.sh https://install.pi-hole.net
sudo bash basic-install.sh
```
docs/main/contact.md
+2 -4
View File
@@ -4,9 +4,7 @@ description: Pi-hole contacts and social media
last_updated: Sun Jan 13 18:33:27 2019 UTC
---
While we are primarily reachable on our <a href="https://discourse.pi-hole.net/">Discourse User Forum</a>, we can also be found on a variety of social media outlets. **Please be sure to check the FAQ's** before starting a new discussion, as we do not have the spare time to reply to every request for assistance.
While we are primarily reachable on our [Discourse User Forum](https://discourse.pi-hole.net/), we can also be found on a variety of social media outlets. **Please be sure to check the FAQ's** before starting a new discussion, as we do not have the spare time to reply to every request for assistance.
- [Frequently Asked Questions](https://discourse.pi-hole.net/c/faqs)
- [Feature Requests](https://discourse.pi-hole.net/c/feature-requests?order=votes)
@@ -17,4 +15,4 @@ While we are primarily reachable on our <a href="https://discourse.pi-hole.net/"
- [Twitter](https://twitter.com/The_Pi_Hole)
- [Gitter](https://gitter.im/pi-hole/pi-hole)
- [YouTube](https://www.youtube.com/channel/UCT5kq9w0wSjogzJb81C9U0w)
- [Facebook](https://www.facebook.com/ThePiHole/)
- [Facebook](https://www.facebook.com/ThePiHole/)
docs/main/coverage.md
-3
View File
@@ -4,8 +4,6 @@ description: Sites and articles about Pi-hole
last_updated: Sun Jan 13 19:20:35 2019 UTC
---
### YouTube/Twit/Video
- [Security Now Netcast: Pi-hole](https://www.youtube.com/watch?v=p7-osq_y8i8&t=100m26s) _Oct 13, 2015_
@@ -34,4 +32,3 @@ last_updated: Sun Jan 13 19:20:35 2019 UTC
- [Bloomberg: Inside the Brotherhood of the Ad Blockers](https://www.bloomberg.com/news/features/2018-05-10/inside-the-brotherhood-of-pi-hole-ad-blockers) _May 10, 2018_
- [How a Single Raspberry PI made my Home Network Faster](https://brianchristner.io/how-a-single-raspberry-pi-made-my-home-network-faster/) _March 1, 2019_
- [Coding Horror: An Exercise Program for the Fat Web](https://blog.codinghorror.com/an-exercise-program-for-the-fat-web/) _May 30, 2019_
docs/main/origins.md
+1 -3
View File
@@ -4,8 +4,6 @@ description: Software packages used in Pi-hole
last_updated: Sun Jan 13 18:35:14 2019 UTC
---
Pi-hole being a **advertising-aware DNS/Web server**, makes use of the following technologies:
- [`dnsmasq`](http://www.thekelleys.org.uk/dnsmasq/doc.html) - a lightweight DNS and DHCP server
@@ -16,4 +14,4 @@ Pi-hole being a **advertising-aware DNS/Web server**, makes use of the following
While quite outdated at this point, [this original blog post about Pi-hole](https://jacobsalmela.com/2015/06/16/block-millions-ads-network-wide-with-a-raspberry-pi-hole-2-0/) goes into **great detail** about how Pi-hole was originally setup and how it works. Syntactically, it's no longer accurate, but the same basic principles and logic still apply to Pi-hole's current state.
{!abbreviations.md!}
{!abbreviations.md!}
docs/main/prerequesites.md
+9 -2
View File
@@ -3,7 +3,9 @@ title: Prerequisites
description: Operating system and network requirements
last_updated: Fri September 20 2019
---
### Hardware
Pi-hole is very lightweight, and does not require much processing power
- ~52MB of free space
@@ -18,7 +20,7 @@ The following operating systems are **officially** supported:
| Distribution | Release | Architecture |
| ------------ | ---------------- | ------------------- |
| Raspbian | Jessie / Stretch / Buster | ARM |
| Raspbian | Jessie / Stretch / Buster | ARM |
| Ubuntu | 16.x / 18.x | ARM / x86_64 |
| Debian | 8 / 9 | ARM / x86_64 / i386 |
| Fedora | 28 / 29 | ARM / x86_64 |
@@ -42,7 +44,7 @@ Due to the complexity of different ways of setting an IP address across differen
| dnsmasq | 67 (DHCP) | IPv4 UDP | The DHCP server is an optional feature that requires additional ports. |
| dnsmasq | 547 (DHCPv6) | IPv6 UDP | The DHCP server is an optional feature that requires additional ports. |
| lighttpd | 80 (HTTP) | TCP | If you have another Web server already running, such as Apache, Pi-hole's Web server will not work. You can either disable the other Web server or change the port on which `lighttpd` listens, which allows you keep both Web servers running. |
| pihole-FTL | 4711 | TCP | FTL is our API engine and uses port 4711 on the localhost interface. This port should not be accessible from any other interface.|
| pihole-FTL | 4711 | TCP | FTL is our API engine and uses port 4711 on the localhost interface. This port should not be accessible from any other interface.|
!!! info
The use of lighttpd on port _80_ is optional if you decide not to install the Web dashboard during installation.
@@ -66,11 +68,13 @@ iptables -I INPUT 1 -p tcp -m tcp --dport 67 -j ACCEPT
iptables -I INPUT 1 -p udp -m udp --dport 67 -j ACCEPT
iptables -I INPUT 1 -p tcp -m tcp --dport 4711 -i lo -j ACCEPT
```
IP6Tables (IPv6)
```bash
ip6tables -I INPUT -p udp -m udp --sport 546:547 --dport 546:547 -j ACCEPT
```
#### FirewallD
Using the `--permanent` argument will ensure the firewall rules persist reboots. If only IPv4 blocking is used for the Pi-hole installation, the `dhcpv6` service can be removed from the commands below. Create a new zone for the local interface (`lo`) for the pihole-FTL ports to ensure the API is only accessible locally. Finally `--reload` to have the new firewall configuration take effect immediately.
@@ -88,6 +92,7 @@ firewall-cmd --reload
ufw stores all rules persistent, so you just need to execute the commands below.
IPv4:
```bash
ufw allow 80/tcp
ufw allow 53/tcp
@@ -97,7 +102,9 @@ ufw allow 67/udp
```
IPv6 (include above IPv4 rules):
```bash
ufw allow 546:547/udp
```
{!abbreviations.md!}
docs/main/presentations.md
+1 -3
View File
@@ -4,8 +4,6 @@ description: Support for presenters
last_updated: Sun Jan 13 18:37:35 2019 UTC
---
Word-of-mouth continues to help our project grow immensely, and so we are helping make this easier for people.
If you are going to be presenting Pi-hole at a conference, meetup or even a school project, [get in touch with us](https://pi-hole.net/2017/05/17/giving-a-presentation-on-pi-hole-contact-us-first-for-some-goodies-and-support/) so we can hook you up with free swag to hand out to your audience!
If you are going to be presenting Pi-hole at a conference, meetup or even a school project, [get in touch with us](https://pi-hole.net/2017/05/17/giving-a-presentation-on-pi-hole-contact-us-first-for-some-goodies-and-support/) so we can hook you up with free swag to hand out to your audience!
docs/main/projects.md
-1
View File
@@ -20,4 +20,3 @@ last_updated: Sun Jan 13 19:45:40 2019 UTC
- [Pi-hole Droid: Android client](https://github.com/friimaind/pi-hole-droid)
- [Windows DNS Swapper](https://github.com/tryallthethings/DNS-Swapper), see [#1400](https://github.com/pi-hole/pi-hole/issues/1400)
- [Pi-hole Visualizer](https://www.reddit.com/r/pihole/comments/82ikgb/pihole_visualizer_update/)