diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index aa8fbb6..0c5fa5f 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -31,7 +31,7 @@ jobs: run: python3 -m pip install -r requirements.txt - name: Build docs - run: mkdocs build --clean --verbose + run: mkdocs build --clean - name: Upload docs uses: actions/upload-artifact@v1 diff --git a/.markdownlint.json b/.markdownlint.json index 6326377..5883b5b 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -24,8 +24,7 @@ "img", "strong", "p", - "sub", - "table", "tbody", "th", "tr", "td" + "sub" ] }, "MD035": { diff --git a/README.md b/README.md index b13e46d..49c68bb 100644 --- a/README.md +++ b/README.md @@ -71,3 +71,5 @@ Please make sure you fork the repo and change the clone URL in the example below ``` After these commands, the current branch is accessible through your favorite browser at + +[![Deploys by Netlify](https://www.netlify.com/img/global/badges/netlify-color-bg.svg)](https://www.netlify.com/) diff --git a/docs/core/pihole-command.md b/docs/core/pihole-command.md index 1f99656..86d34db 100644 --- a/docs/core/pihole-command.md +++ b/docs/core/pihole-command.md @@ -54,17 +54,13 @@ Example Usage | [`pihole -regex '^example.com$' '.*\.example2.net'`](https://d Administrators need to be able to manually add and remove domains for various purposes, and these commands serve that purpose. -See [Regex Blocking](/ftldns/regex/overview/) for more information about using Regex. +See [Regex Blocking](../ftldns/regex/overview.md) for more information about using Regex. **Basic Script Process**: * 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 -* 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 +* A domain gets added to or removed from the `domainlist` table in [`/etc/pihole/gravity.db`](../database/gravity/index.md) +* The DNS server is then reloaded ### Debugger @@ -153,14 +149,12 @@ Gravity is one of the most important scripts of Pi-hole. Its main purpose is to **Basic Script Process**: -* 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 will determine Internet connectivity, and give time for `pihole-FTL` to be resolvable on low-end systems if has just been restarted +* It extracts all URLs and domains from the `adlists` table in [`/etc/pihole/gravity.db`](../database/gravity/index.md) * It runs through each URL, downloading it if necessary * `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 -* Blacklisted, "localhost" and temporary file entries are added as separate `.list` files +* Lists are merged, comments removed, sorted uniquely and stored in the `gravity` table of [`/etc/pihole/gravity.db`](../database/gravity/index.md) * Gravity cleans up temporary content and reloads the DNS server ### Logging @@ -187,10 +181,7 @@ This command will query your whitelist, blacklist, wildcards and adlists for a s * User-specified options are handled * Using `idn`, it will convert [Internationalized domain names](https://en.wikipedia.org/wiki/Internationalized_domain_name) into [punycode](https://en.wikipedia.org/wiki/Punycode) -* The whitelist and the blacklist are searched -* The possible wildcard matches are then searched (`/etc/dnsmasq.d/03-pihole-wildcard.conf`) -* The adlists are then searched (`/etc/pihole/list.*.domains`) -* Output is determined by the specified options, ensuring that a file name is only printed once +* Database at [`/etc/pihole/gravity.db`](../database/gravity/index.md) is queried to return a list of adlists in which the queried domain exists. ### Update @@ -311,16 +302,6 @@ Example Usage | [`pihole -a -c`](https://discourse.pi-hole.net/t/the-pihole-co Set the specified temperature unit as the preferred type. This preference will affect the Web Interface, as well as Chronometer. -### Host Record - -| | | - -------------- | -------------- -Help Command | `pihole -a hostrecord --help` -Script Location | [`/opt/pihole/webpage.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/webpage.sh) -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 | | | @@ -339,4 +320,4 @@ Help Command | `pihole -a interface --help` Script Location | [`/opt/pihole/webpage.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/webpage.sh) Example Usage | [`pihole -a interface local`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#interface) -Specify interface listening behavior for `dnsmasq`. When using `pihole -a interface all`, please ensure you use a firewall to prevent your Pi-hole from becoming an unwitting host to [DNS amplification attackers](https://duckduckgo.com/?q=dns+amplification+attack). You may want to consider running [OpenVPN](https://github.com/pi-hole/pi-hole/wiki/Pi-hole---OpenVPN-server) to grant your mobile devices access to the Pi-hole. +Specify interface listening behavior for `pihole-FTL`. When using `pihole -a interface all`, please ensure you use a firewall to prevent your Pi-hole from becoming an unwitting host to [DNS amplification attackers](https://duckduckgo.com/?q=dns+amplification+attack). You may want to consider running [OpenVPN](../guides/vpn/overview.md) to grant your mobile devices access to the Pi-hole. diff --git a/docs/extra.css b/docs/extra.css index eabe03b..c2c63d7 100644 --- a/docs/extra.css +++ b/docs/extra.css @@ -19,23 +19,6 @@ input { color: #532ba8; } -.md-logo img { - width: 48px; - height: 48px; -} - -@media only screen and (min-width: 76.25em) { - .md-logo img { - width: 24px; - height: 24px; - } -} - .text-center { text-align: center !important; } - -/* needed because images have `max-width: 100%` in the theme */ -img { - height: auto; -} diff --git a/docs/guides/benchmark.md b/docs/guides/benchmark.md index c1d4ec1..4560e3f 100644 --- a/docs/guides/benchmark.md +++ b/docs/guides/benchmark.md @@ -29,7 +29,7 @@ The long-term database can be disabled by setting DBFILE= ``` -in `/etc/pihole/pihole-FTL.conf` and running `sudo pihole restartdns` (see also [here](/ftldns/configfile/#dbfile)). +in `/etc/pihole/pihole-FTL.conf` and running `sudo pihole restartdns` (see also [here](../ftldns/configfile.md#dbfile)). ### 2.2 Increase DNS cache size diff --git a/docs/guides/dns-over-https.md b/docs/guides/dns-over-https.md index 793d9ba..52c439f 100644 --- a/docs/guides/dns-over-https.md +++ b/docs/guides/dns-over-https.md @@ -57,7 +57,13 @@ Create a `cloudflared` user to run the daemon: 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: +Proceed to create a configuration file for `cloudflared`: + +```bash +sudo nano /etc/default/cloudflared +``` + +Edit configuration file by copying the following in to `/etc/default/cloudflared`. This file contains the command-line options that get passed to cloudflared on startup: ```bash # Commandline args for cloudflared diff --git a/docs/guides/vpn/dual-operation.md b/docs/guides/vpn/dual-operation.md index f1df699..b0a81da 100644 --- a/docs/guides/vpn/dual-operation.md +++ b/docs/guides/vpn/dual-operation.md @@ -1,6 +1,6 @@ **Up until now, this wiki has been about a server set up on a cloud host, available on the public Internet. This section is aimed at a server set up in a private network like on a Raspberry Pi.** -So if blocking works using `eth0` but stops working for `tun0`, as described [here](https://github.com/pi-hole/pi-hole/issues/1553), you may want to run this command `pihole -a -i all`, which should get the behavior you want by opening dnsmasq up to listen on all ports. This is not recommended for cloud servers as they should _not_ be listening on `eth0`. +So if blocking works using `eth0` but stops working for `tun0`, as described [here](https://github.com/pi-hole/pi-hole/issues/1553), you may want to run this command `pihole -a -i all`, which should get the behavior you want by opening pihole-FTL up to listen on all ports. This is not recommended for cloud servers as they should _not_ be listening on `eth0`. If you want to set up your Pi-hole + OpenVPN such that you can use from both internal ((W)LAN) and external (VPN) networks, you have to apply some small changes. As an additional benefit, you will be able to reach all devices in the internal network (e.g. computers, networking-aware printers, etc.) through the VPN. diff --git a/docs/guides/vpn/overview.md b/docs/guides/vpn/overview.md index b7e0184..aee7c87 100644 --- a/docs/guides/vpn/overview.md +++ b/docs/guides/vpn/overview.md @@ -14,7 +14,7 @@ Via this VPN, you can: - access your admin interface remotely - encrypt your Internet traffic -If you don't want a full-tunnel, we provide a wiki of how to [set up your server to exclusively route DNS traffic, but nothing else via the VPN](only-dns-via-vpn.md). On another optional page, we describe how to set up Pi-hole + VPN in such a way that it is [usable both locally (no VPN) and from remote (through VPN)](dual-operation.md) while preserving full functionality. +If you don't want a full-tunnel, we provide a page of how to [set up your server to exclusively route DNS traffic, but nothing else via the VPN](only-dns-via-vpn.md). On another optional page, we describe how to set up Pi-hole + VPN in such a way that it is [usable both locally (no VPN) and from remote (through VPN)](dual-operation.md) while preserving full functionality. 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 diff --git a/docs/guides/whitelist-blacklist.md b/docs/guides/whitelist-blacklist.md index 58c7eab..80728c2 100644 --- a/docs/guides/whitelist-blacklist.md +++ b/docs/guides/whitelist-blacklist.md @@ -4,79 +4,68 @@ ### How to Whitelist or Blacklist -There are scripts to aid users in adding or removing domains to the whitelist or blacklist. - -The scripts will first parse `whitelist.txt` or `blacklist.txt` for any changes, and if any additions or deletions are detected, it will reload `dnsmasq` so that they are effective immediately. +There are scripts to aid users in adding or removing domains to the whitelist or blacklist from the CLI Each script accepts the following parameters: - - - - - - - - - - - - - - - - - - - - - - - -
[domain]Fully qualified domain name you wish to add or remove. You can pass any number of domains.
-dRemoval mode. Domains will be removed from the list, rather than added
-nrUpdate blacklist without refreshing dnsmasq
-fForce delete cached blocklist content
-qQuiet mode. Console output is minimal. Useful for calling from another script (see gravity.sh)
+| Parameter | Description | +|------------|--------------------------------------------------------------------------------------------------| +| `[domain]` | Fully qualified domain name you wish to add or remove. You can pass any number of domains. | +| `-d` | Removal mode. Domains will be removed from the list, rather than added | +| `-nr` | Update blacklist without refreshing pihole-FTL | +| `-f` | Force delete cached blocklist content | +| `-q` | Quiet mode. Console output is minimal. Useful for calling from another script (see `gravity.sh`) | 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 - - - - - - - - - - - - - - - -
pihole -w domain1 [domain2...]Attempt to add one or more domains to the whitelist and reload dnsmasq.
pihole -w -nr domain1 [domain2...]Attempt to add one or more domains to the whitelist, but do not reload dnsmasq.
pihole -w -f domain1 [domain2...]Attempt to add one or more domains to the whitelist and force dnsmasq to reload
+* Attempt to add one or more domains to the whitelist and reload pihole-FTL: -To remove domains from the whitelist: -Add `-d` as an additional argument (e.g `pihole -w -d domain1 [domain2...]`) + ```bash + pihole -w domain1 [domain2...] + ``` + +* Attempt to add one or more domains to the whitelist, but do not reload pihole-FTL: + + ```bash + pihole -w -nr domain1 [domain2...] + ``` + +* Attempt to add one or more domains to the whitelist and force pihole-FTL to reload: + + ```bash + pihole -w -f domain1 [domain2...] + ``` + +To remove domains from the whitelist add `-d` as an additional argument, e.g: + +```bash +pihole -w -d domain1 [domain2...] +``` #### Example `pihole -b` usages - - - - - - - - - - - - - - - -
pihole -b domain1 [domain2...]Attempt to add one or more domains to the blacklist and reload dnsmasq.
pihole -b -nr domain1 [domain2...]Attempt to add one or more domains to the blacklist, but do not reload dnsmasq.
pihole -b -f domain1 [domain2...]Attempt to add one or more domains to the blacklist and force dnsmasq to reload
+* Attempt to add one or more domains to the blacklist and reload pihole-FTL: -To remove domains from the blacklist: -Add `-d` as an additional argument (e.g `pihole -b -d domain1 [domain2...]`) + ```bash + pihole -b domain1 [domain2...] + ``` + +* Attempt to add one or more domains to the blacklist, but do not reload pihole-FTL: + + ```bash + pihole -b -nr domain1 [domain2...] + ``` + +* Attempt to add one or more domains to the blacklist and force pihole-FTL to reload: + + ```bash + pihole -b -f domain1 [domain2...] + ``` + +To remove domains from the blacklist add `-d` as an additional argument, e.g: + +```bash +pihole -b -d domain1 [domain2...] +``` diff --git a/docs/index.md b/docs/index.md index b3be7d5..6b236d0 100755 --- a/docs/index.md +++ b/docs/index.md @@ -46,7 +46,6 @@ If you'd rather not donate (_which is okay!_), there are other ways you can help - [Digital Ocean](https://www.digitalocean.com/?refcode=344d234950e1) _new account credits with our affiliate link_ - [Amazon](https://www.amazon.com/exec/obidos/redirect-home/pihole09-20) _affiliate link_ -- [Vultr](https://www.vultr.com/?ref=7190426) _affiliate link_ - Spreading the word about our software, and how you have benefited from it ### Contributing via GitHub diff --git a/docs/main/origins.md b/docs/main/origins.md index 45a7e06..5663768 100755 --- a/docs/main/origins.md +++ b/docs/main/origins.md @@ -11,6 +11,7 @@ Pi-hole being a **advertising-aware DNS/Web server**, makes use of the following - [`lighttpd`](https://www.lighttpd.net/) - web server designed and optimized for high performance - [`php`](https://www.php.net/) - a popular general-purpose web scripting language - [AdminLTE Dashboard](https://github.com/ColorlibHQ/AdminLTE) - premium admin control panel based on Bootstrap 3.x +- [`sqlite3`](https://www.sqlite.org/index.html) - SQL Database engine 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 set up 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. diff --git a/docs/main/prerequesites.md b/docs/main/prerequesites.md index 0c53307..93d16bf 100644 --- a/docs/main/prerequesites.md +++ b/docs/main/prerequesites.md @@ -20,11 +20,11 @@ The following operating systems are **officially** supported: | Distribution | Release | Architecture | | ------------ | ---------------- | ------------------- | -| Raspbian | Stretch / Buster | ARM | +| Raspbian | Stretch / Buster | ARM | | Ubuntu | 16.x / 18.x | ARM / x86_64 | | Debian | 9 / 10 | ARM / x86_64 / i386 | -| Fedora | 28 / 29 | ARM / x86_64 | -| CentOS | 7 | x86_64 | +| Fedora | 31 / 32 | ARM / x86_64 | +| CentOS | 7 / 8 | x86_64 | ### IP Addressing @@ -40,15 +40,15 @@ Due to the complexity of different ways of setting an IP address across differen | Service | Port | Protocol | Notes | | --------------------|:-------------|:---------| --------------------| -| dnsmasq | 53 (DNS) | TCP/UDP | If you happen to have another DNS server running, such as BIND, you will need to turn it off in order for Pi-hole to respond to DNS queries. | -| 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. | +| pihole-FTL | 53 (DNS) | TCP/UDP | If you happen to have another DNS server running, such as BIND, you will need to turn it off in order for Pi-hole to respond to DNS queries. | +| pihole-FTL | 67 (DHCP) | IPv4 UDP | The DHCP server is an optional feature that requires additional ports. | +| pihole-FTL | 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-4720 | 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. - The use of dnsmasq on ports _67_ or _547_ is optional, but required if you use the DHCP functions of Pi-hole. + The use of pihole-FTL on ports _67_ or _547_ is optional, but required if you use the DHCP functions of Pi-hole. ### Firewalls diff --git a/mkdocs.yml b/mkdocs.yml index 722cb52..8289fa1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,6 +6,7 @@ copyright: 'Copyright © 2020 Pi-hole LLC' remote_branch: gh-pages theme: name: 'material' + custom_dir: overrides # icon: # repo: fontawesome/brands/github-alt favicon: 'images/favicon.ico' diff --git a/overrides/partials/footer.html b/overrides/partials/footer.html new file mode 100644 index 0000000..dd4036f --- /dev/null +++ b/overrides/partials/footer.html @@ -0,0 +1,59 @@ +{% import "partials/language.html" as lang with context %} + diff --git a/package-lock.json b/package-lock.json index 92fcac2..3ad97b7 100644 --- a/package-lock.json +++ b/package-lock.json @@ -51,9 +51,9 @@ "dev": true }, "entities": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/entities/-/entities-2.0.0.tgz", - "integrity": "sha512-D9f7V0JSRwIxlRI2mjMqufDrRDnx8p+eEOz7aUM9SuvF8gsBzra0/6tbjl1m8eQHrZlYj6PxqE00hZ1SAIKPLw==", + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/entities/-/entities-2.0.2.tgz", + "integrity": "sha512-dmD3AvJQBUjKpcNkoqr+x+IF0SdRtPz9Vk0uTy4yWqga9ibB6s4v++QFWNohjiUGoMlF552ZvNyXDxz5iW0qmw==", "dev": true }, "esprima": { @@ -133,9 +133,9 @@ } }, "jsonc-parser": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-2.2.0.tgz", - "integrity": "sha512-4fLQxW1j/5fWj6p78vAlAafoCKtuBm6ghv+Ij5W2DrDx0qE+ZdEl2c6Ko1mgJNF5ftX1iEWQQ4Ap7+3GlhjkOA==", + "version": "2.2.1", + "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-2.2.1.tgz", + "integrity": "sha512-o6/yDBYccGvTz1+QFevz6l6OBZ2+fMVu2JZ9CIhzsYRX4mjaK5IyX9eldUdCmga16zlgQxyrj5pt9kzuj2C02w==", "dev": true }, "linkify-it": { @@ -173,18 +173,18 @@ } }, "markdownlint": { - "version": "0.19.0", - "resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.19.0.tgz", - "integrity": "sha512-+MsWOnYVUH4klcKM7iRx5cno9FQMDAb6FC6mWlZkeXPwIaK6Z5Vd9VkXkykPidRqmLHU2wI+MNyfUMnUCBw3pQ==", + "version": "0.20.3", + "resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.20.3.tgz", + "integrity": "sha512-J93s59tGvSFvAPWVUtEgxqPI0CHayTx1Z8poj1/4UJAquHGPIruWRMurkRldiNbgBiaQ4OOt15rHZbFfU6u05A==", "dev": true, "requires": { "markdown-it": "10.0.0" } }, "markdownlint-cli": { - "version": "0.22.0", - "resolved": "https://registry.npmjs.org/markdownlint-cli/-/markdownlint-cli-0.22.0.tgz", - "integrity": "sha512-qRg6tK5dXWqkaFvEstz9YSQal1ECMgofrSZgdBOaPWG8cD50pk8Hs0ZpBCJ6SCHPKF71pCdtuSL2u82sIx2XWA==", + "version": "0.23.1", + "resolved": "https://registry.npmjs.org/markdownlint-cli/-/markdownlint-cli-0.23.1.tgz", + "integrity": "sha512-UARWuPILksAcVLTosUv1F1tLognNYQ/qjLRIgWwQAYqdl3QQrTPurU/X9Z2jrdAJYlOim868QsufxjYJpH0K7Q==", "dev": true, "requires": { "commander": "~2.9.0", @@ -196,16 +196,17 @@ "jsonc-parser": "~2.2.0", "lodash.differencewith": "~4.5.0", "lodash.flatten": "~4.4.0", - "markdownlint": "~0.19.0", - "markdownlint-rule-helpers": "~0.7.0", + "markdownlint": "~0.20.3", + "markdownlint-rule-helpers": "~0.10.0", "minimatch": "~3.0.4", + "minimist": "~1.2.5", "rc": "~1.2.7" } }, "markdownlint-rule-helpers": { - "version": "0.7.0", - "resolved": "https://registry.npmjs.org/markdownlint-rule-helpers/-/markdownlint-rule-helpers-0.7.0.tgz", - "integrity": "sha512-xZByWJNBaCMHo7nYPv/5aO8Jt68YcMvyouFXhuXmJzbqCsQy8rfCj0kYcv22kdK5PwAgMdbHg0hyTdURbUZtJw==", + "version": "0.10.0", + "resolved": "https://registry.npmjs.org/markdownlint-rule-helpers/-/markdownlint-rule-helpers-0.10.0.tgz", + "integrity": "sha512-0e8VUTjNdQwS7hTyNan9oOLsy4a7KEsXo3fxKMDRFRk6Jn+pLB3iKZ3mj/m6ECrlOUCxPYYmgOmmyk3bSdbIvw==", "dev": true }, "mdurl": { diff --git a/package.json b/package.json index 1589c62..4c49f65 100644 --- a/package.json +++ b/package.json @@ -20,6 +20,6 @@ "test": "npm run markdownlint" }, "devDependencies": { - "markdownlint-cli": "^0.22.0" + "markdownlint-cli": "^0.23.1" } } diff --git a/requirements.txt b/requirements.txt index 2327a21..8b1e8b7 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ markdown-include==0.5.1 -mkdocs==1.1 +mkdocs==1.1.2 mkdocs-git-revision-date-localized-plugin==0.5.2 -mkdocs-material==5.1.6 +mkdocs-material==5.2.1