Pi-Hole/docs
1
0
Fork 0
mirror of https://github.com/pi-hole/docs.git synced 2025-12-19 18:58:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1308 from pi-hole/dependabot/npm_and_yarn/master/npm-dependencies-2587637d0c

Browse Source 
Bump markdownlint-cli2 from 0.18.1 to 0.19.0 in the npm-dependencies group
This commit is contained in:
yubiuser
2025-11-17 12:57:06 +01:00
committed by GitHub
parent 378e5804c2 cc078749eb
commit e9fb359896
13 changed files with 196 additions and 186 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
.devcontainer/Dockerfile
View File

@@ -4,7 +4,8 @@ RUN apk add --no-cache \
git \
nano \
openssh \
py3-pip
py3-pip \
tzdata
ENV USER node
USER ${USER}

5
.markdownlint.json
View File

@@ -37,5 +37,8 @@
"MD046": {
"style": "fenced"
},
"MD059": false
"MD059": false,
"MD060": {
"style": "any"
}
}

20
docs/api/tls.md
View File

@@ -23,9 +23,9 @@ It is worth noting that the certificate is only valid for the domain that you ha
### Firefox (tested with Firefox 121.0)
Before | After
:-----:|:-----:
![Firefox Untrusted](../images/api/firefox-pihole-untrusted.png) | ![Firefox Trusted](../images/api/firefox-pihole-trusted.png)
| Before | After |
| :-----: | :-----: |
| ![Firefox Untrusted](../images/api/firefox-pihole-untrusted.png) | ![Firefox Trusted](../images/api/firefox-pihole-trusted.png) |
1. Open the settings page of Firefox at [about:preferences#privacy](about:preferences#privacy)
2. Search for "Certificates"
@@ -44,9 +44,9 @@ If the last step did not work, make sure that you have generated the certificate
### Chrome (tested with Chrome 120.0)
Before | After
:-----:|:-----:
![Chrome Untrusted](../images/api/chrome-pihole-untrusted.png) | ![Chrome Trusted](../images/api/chrome-pihole-trusted.png)
| Before | After |
| :-----: | :-----: |
| ![Chrome Untrusted](../images/api/chrome-pihole-untrusted.png) | ![Chrome Trusted](../images/api/chrome-pihole-trusted.png) |
1. Open the settings page of Chrome at [chrome://settings/privacy](chrome://settings/privacy)
2. Navigate to "Manage certificates" in the "Security" submenu of "Privacy and security" or use the search bar
@@ -64,10 +64,10 @@ If the last step did not work, see the remark below the Firefox instructions abo
### Android (tested with Android 11 and Firefox Mobile 121.1.0)
Before | After
:-----:|:-----:
![Android Firefox Untrusted](../images/api/android-pihole-untrusted.png) | ![Android Firefox Trusted](../images/api/android-pihole-trusted.png)
![Android Chrome Untrusted](../images/api/android-chrome-untrusted.png) | ![Android Chrome Trusted](../images/api/android-chrome-trusted.png)
| Before | After |
| :-----: | :-----: |
| ![Android Firefox Untrusted](../images/api/android-pihole-untrusted.png) | ![Android Firefox Trusted](../images/api/android-pihole-trusted.png) |
| ![Android Chrome Untrusted](../images/api/android-chrome-untrusted.png) | ![Android Chrome Trusted](../images/api/android-chrome-trusted.png) |
1. Go to your device's settings
2. Navigate to "System Security" or "Security & location" (depending on your device)

18
docs/docker/upgrading/v5-v6.md
View File

@@ -9,7 +9,7 @@ Nearly all environment variables from previous versions have been removed, but f
### Misc
| Old Variable | New Variable |
|Old Variable|New Variable|
|:-------------|:-------------|
|`CUSTOM_CACHE_SIZE`|`FTLCONF_dns_cache_size`|
|`DNS_BOGUS_PRIV`|`FTLCONF_dns_bogusPriv`|
@@ -28,14 +28,14 @@ Nearly all environment variables from previous versions have been removed, but f
|Old|New|
|:--|:--|
|`DHCP_ACTIVE`| `FTLCONF_dhcp_active`|
|`DHCP_START`| `FTLCONF_dhcp_start`|
|`DHCP_END`| `FTLCONF_dhcp_end`|
|`DHCP_ROUTER`| `FTLCONF_dhcp_router`|
|`DHCP_LEASETIME`| `FTLCONF_dhcp_leaseTime`|
|`PIHOLE_DOMAIN`| `FTLCONF_dns_domain`|
|`DHCP_IPv6`| `FTLCONF_dhcp_ipv6`|
|`DHCP_rapid_commit`| `FTLCONF_dhcp_rapidCommit`|
|`DHCP_ACTIVE`|`FTLCONF_dhcp_active`|
|`DHCP_START`|`FTLCONF_dhcp_start`|
|`DHCP_END`|`FTLCONF_dhcp_end`|
|`DHCP_ROUTER`|`FTLCONF_dhcp_router`|
|`DHCP_LEASETIME`|`FTLCONF_dhcp_leaseTime`|
|`PIHOLE_DOMAIN`|`FTLCONF_dns_domain`|
|`DHCP_IPv6`|`FTLCONF_dhcp_ipv6`|
|`DHCP_rapid_commit`|`FTLCONF_dhcp_rapidCommit`|
### Conditional Forwarding Variables

38
docs/ftldns/cache_dump.md
View File

@@ -115,28 +115,28 @@ Self-explanatory: Queries sent, retried, and failed to the individual upstream s
The first character of the flags describes the query type:
Character | Record type
----------|------------
`4` | `A` (IPv4 address)
`6` | `AAAA` (IPv6 address)
`C` | `CNAME`
`V` | `SRV`
`S` | `DS`
`K` | `DNSKEY`
`(empty)` | something else
| Character | Record type |
| ---------- | ------------ |
| `4` | `A` (IPv4 address) |
| `6` | `AAAA` (IPv6 address) |
| `C` | `CNAME` |
| `V` | `SRV` |
| `S` | `DS` |
| `K` | `DNSKEY` |
| `(empty)` | something else |
The rest of the flags can be almost any combination of the following bits:
Bit | Interpretation
-------|---------------
`F` | Forward entry (domain-to-address record)
`R` | Reverse entry (address-to-domain, typically combined with `D` or `H`)
`I` | Immortal cache entry (no expiry, typically from local configuration)
`D` | DHCP-provided record
`N` | Negative record (This record does not exist)
`X` | NXDOMAIN (No record exists at all for this domain)
`H` | From HOSTS file (always combined with `I`)
`V` | DNSSEC verified
| Bit | Interpretation |
| ------- | --------------- |
| `F` | Forward entry (domain-to-address record) |
| `R` | Reverse entry (address-to-domain, typically combined with `D` or `H`) |
| `I` | Immortal cache entry (no expiry, typically from local configuration) |
| `D` | DHCP-provided record |
| `N` | Negative record (This record does not exist) |
| `X` | NXDOMAIN (No record exists at all for this domain) |
| `H` | From HOSTS file (always combined with `I`) |
| `V` | DNSSEC verified |
The `V` flag in negative DS records has a different meaning. Only validated `DS` records are every cached, and the `V` bit is used to store information about the presence of an `NS` record for the domain, i.e., if there's a zone cut at that point.

96
docs/group_management/example.md
View File

@@ -62,12 +62,12 @@ after your database modifications to have FTL flush its internal domain-blocking
**Result**
Client | Group membership | Domain | Blocked
------------- | ----- | ------ | -------
*all other* | Default | doubleclick.net | Yes
192.168.0.101 | Group 1 | doubleclick.net | **No**
192.168.0.102 | Group 2 + Default | doubleclick.net | Yes
192.168.0.103 | Group 3 + Default | doubleclick.net | Yes
| Client | Group membership | Domain | Blocked |
| ------------- | ----- | ------ | ------- |
| *all other* | Default | doubleclick.net | Yes |
| 192.168.0.101 | Group 1 | doubleclick.net | **No** |
| 192.168.0.102 | Group 2 + Default | doubleclick.net | Yes |
| 192.168.0.103 | Group 3 + Default | doubleclick.net | Yes |
All three clients got automatically assigned to the default (`Default`) group when they were added. The default group includes all subscribed lists and list domains (if not already changed by the user). When we remove the default group for client `192.168.0.101`, we effectively remove all associations to any subscribed lists and domains. This leaves this client completely unblocked.
@@ -84,12 +84,12 @@ All three clients got automatically assigned to the default (`Default`) group wh
**Result**
Client | Group membership | Domain | Blocked
------------- | ----- | ------ | -------
*all other* | Default | doubleclick.net | Yes
192.168.0.101 | Group 1 | doubleclick.net | **Yes**
192.168.0.102 | Group 2 + Default | doubleclick.net | Yes
192.168.0.103 | Group 3 + Default | doubleclick.net | Yes
| Client | Group membership | Domain | Blocked |
| ------------- | ----- | ------ | ------- |
| *all other* | Default | doubleclick.net | Yes |
| 192.168.0.101 | Group 1 | doubleclick.net | **Yes** |
| 192.168.0.102 | Group 2 + Default | doubleclick.net | Yes |
| 192.168.0.103 | Group 3 + Default | doubleclick.net | Yes |
`192.168.0.101` gets `doubleclick.net` blocked as it uses a subscribed list including this domain. All other clients stay unchanged.
@@ -112,12 +112,12 @@ Add the domain to be blocked
**Result**
Client | Group membership | Domain | Blocked
------------- | ----- | ------ | -------
*all other* | Default | denylisted.com | **Yes**
192.168.0.101 | Group 1 | denylisted.com | No
192.168.0.102 | Group 2 + Default | denylisted.com | **Yes**
192.168.0.103 | Group 3 + Default | denylisted.com | **Yes**
| Client | Group membership | Domain | Blocked |
| ------------- | ----- | ------ | ------- |
| *all other* | Default | denylisted.com | **Yes** |
| 192.168.0.101 | Group 1 | denylisted.com | No |
| 192.168.0.102 | Group 2 + Default | denylisted.com | **Yes** |
| 192.168.0.103 | Group 3 + Default | denylisted.com | **Yes** |
Note that Pi-hole is *not* blocking this domain for client `192.168.0.101` as we removed the default assignment through group 0 above. All remaining clients are linked through the Default group to this domain and see it as being blocked.
@@ -135,12 +135,12 @@ Assign this domain to group 1
**Result**
Client | Group membership | Domain | Blocked
------------- | ----- | ------ | -------
*all other* | Default | denylisted.com | Yes
192.168.0.101 | Group 1 | denylisted.com | **Yes**
192.168.0.102 | Group 2 + Default | denylisted.com | Yes
192.168.0.103 | Group 3 + Default | denylisted.com | Yes
| Client | Group membership | Domain | Blocked |
| ------------- | ----- | ------ | ------- |
| *all other* | Default | denylisted.com | Yes |
| 192.168.0.101 | Group 1 | denylisted.com | **Yes** |
| 192.168.0.102 | Group 2 + Default | denylisted.com | Yes |
| 192.168.0.103 | Group 3 + Default | denylisted.com | Yes |
All clients see this domain as being blocked: Client 1 due to a direct assignment through group 1, all remaining clients through the default group 0 (unchanged).
@@ -158,12 +158,12 @@ Remove default assignment to all clients not belonging to a group
**Result**
Client | Group membership | Domain | Blocked
------------- | ----- | ------ | -------
*all other* | Default | denylisted.com | **No**
192.168.0.101 | Group 1 | denylisted.com | Yes
192.168.0.102 | Group 2 + Default | denylisted.com | **No**
192.168.0.103 | Group 3 + Default | denylisted.com | **No**
| Client | Group membership | Domain | Blocked |
| ------------- | ----- | ------ | ------- |
| *all other* | Default | denylisted.com | **No** |
| 192.168.0.101 | Group 1 | denylisted.com | Yes |
| 192.168.0.102 | Group 2 + Default | denylisted.com | **No** |
| 192.168.0.103 | Group 3 + Default | denylisted.com | **No** |
While client 1 keeps its explicit assignment through group 1, the remaining clients lost their unassignments when we removed group 0 from the assignment.
@@ -186,12 +186,12 @@ Add the domain to be allowlisted
**Result**
Client | Group membership | Domain | Blocked
------------- | ----- | ------ | -------
*all other* | Default | doubleclick.net | **No**
192.168.0.101 | Group 1 | doubleclick.net | Yes
192.168.0.102 | Group 2 + Default | doubleclick.net | **No**
192.168.0.103 | Group 3 + Default | doubleclick.net | **No**
| Client | Group membership | Domain | Blocked |
| ------------- | ----- | ------ | ------- |
| *all other* | Default | doubleclick.net | **No** |
| 192.168.0.101 | Group 1 | doubleclick.net | Yes |
| 192.168.0.102 | Group 2 + Default | doubleclick.net | **No** |
| 192.168.0.103 | Group 3 + Default | doubleclick.net | **No** |
Client `192.168.0.101` is not allowlisting this domain as we removed the default assignment through group 0 above. All remaining clients are linked through the default group to this domain and see it as being allowlisted. Note that this is completely analog to step 1 of [example 3](#example-3-denylisting).
@@ -208,12 +208,12 @@ Remove default group assignment
**Result**
Client | Group membership | Domain | Blocked
------------- | ----- | ------ | -------
*all other* | Default | doubleclick.net | **Yes**
192.168.0.101 | Group 1 | doubleclick.net | Yes
192.168.0.102 | Group 2 + Default | doubleclick.net | **Yes**
192.168.0.103 | Group 3 + Default | doubleclick.net | **Yes**
| Client | Group membership | Domain | Blocked |
| ------------- | ----- | ------ | ------- |
| *all other* | Default | doubleclick.net | **Yes** |
| 192.168.0.101 | Group 1 | doubleclick.net | Yes |
| 192.168.0.102 | Group 2 + Default | doubleclick.net | **Yes** |
| 192.168.0.103 | Group 3 + Default | doubleclick.net | **Yes** |
Requests from all clients are blocked as the new allowlist entry is not associated with any group and, hence, is not used by any client.
@@ -231,11 +231,11 @@ Assign this domain to group 2
**Result**
Client | Group membership | Domain | Blocked
------------- | ----- | ------ | -------
*all other* | Default | doubleclick.net | Yes
192.168.0.101 | Group 1 | doubleclick.net | Yes
192.168.0.102 | Group 2 + Default | doubleclick.net | **No**
192.168.0.103 | Group 3 + Default | doubleclick.net | Yes
| Client | Group membership | Domain | Blocked |
| ------------- | ----- | ------ | ------- |
| *all other* | Default | doubleclick.net | Yes |
| 192.168.0.101 | Group 1 | doubleclick.net | Yes |
| 192.168.0.102 | Group 2 + Default | doubleclick.net | **No** |
| 192.168.0.103 | Group 3 + Default | doubleclick.net | Yes |
Client 2 got the allowlist entry explicitly assigned to. Accordingly, client 2 does not get the domain blocked whereas all remaining clients still see this domain as blocked.

2
docs/guides/misc/allowlist-denylist.md
View File

@@ -11,7 +11,7 @@ Each script accepts the following parameters:
| Parameter | Description |
|------------|--------------------------------------------------------------------------------------------------|
| `[domain]` | Fully qualified domain name you wish to add or remove. You can pass any number of domains. |
| `remove` | Removal mode. Domains will be removed from the list, rather than added |
| `remove` | Removal mode. Domains will be removed from the list, rather than added |
| `-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.

6
docs/main/coverage.md
View File

@@ -4,7 +4,7 @@ description: Sites and articles about Pi-hole
last_updated: Sun Jan 13 19:20:35 2019 UTC
---
### YouTube/Twit/Video
## YouTube/Twit/Video
- [Security Now Netcast: Pi-hole](https://www.youtube.com/watch?v=p7-osq_y8i8&t=100m26s) _Oct 13, 2015_
- [TekThing: Raspberry Pi-Hole Makes Ads Disappear!](https://www.youtube.com/watch?v=8Co59HU2gY0&t=2m) _Dec 18, 2015_
@@ -15,11 +15,11 @@ last_updated: Sun Jan 13 19:20:35 2019 UTC
- [Know How 355: Killing ads with a Raspberry Pi-Hole!](https://www.twit.tv/shows/know-how/episodes/355) _Nov 9, 2017_
- [Linus Tech Tips: Block EVERY Online Ad with THIS](https://www.youtube.com/watch?v=KBXTnrD_Zs4) _Aug 28, 2019_
### Podcasts
## Podcasts
- [MacObserver Podcast 585](https://www.macobserver.com/tmo/podcast/macgeekgab-585) _Dec 27, 2015_
### Blogs
## Blogs
- [Lifehacker: Turn A Raspberry Pi Into An Ad Blocker With A Single Command](https://www.lifehacker.com.au/2015/02/turn-a-raspberry-pi-into-an-ad-blocker-with-a-single-command/) _Feb 17, 2015_
- [MakeUseOf: Adblock Everywhere: The Raspberry Pi-Hole Way](https://www.makeuseof.com/tag/adblock-everywhere-raspberry-pi-hole-way/) _Mar 25, 2015_

78
docs/main/pihole-command.md
View File

@@ -1,14 +1,14 @@
Pi-hole makes use of many commands, and here we will break down those required to administer the program via the command-line Interface.
| Index | Invocation |
| -------------- | -------------- |
| -------------- | -------------- |
| [Core Script](#pi-hole-core) | `pihole` |
---
## Pi-hole Core
| Feature | Invocation |
| Feature | Invocation |
| -------------- | -------------- |
| [Core](#core-script) | `pihole` |
| [Allowlisting, Denylisting and Regex](#allowlisting-denylisting-and-regex) | `pihole allow`, `pihole deny`, `pihole --regex`, `pihole --wild`, `pihole --allow-regex`, `pihole --allow-wild` |
@@ -31,19 +31,19 @@ Pi-hole makes use of many commands, and here we will break down those required t
| | |
| -------------- | -------------- |
| Help Command | `pihole --help` |
| Help Command | `pihole --help` |
| Script Location | [`/usr/local/bin/pihole`](https://github.com/pi-hole/pi-hole/blob/master/pihole) |
| Example Usage | `pihole -b advertiser.example.com` |
| 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 minimize 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.
### Allowlisting, Denylisting and Regex
| | |
| -------------- | -------------- |
| Help Command | `pihole allow --help`, `pihole deny --help`, `pihole --regex --help`, `pihole --wild --help`, `pihole --allow-regex --help`, `pihole --allow-wild --help` |
| | |
| -------------- | -------------- |
| Help Command | `pihole allow --help`, `pihole deny --help`, `pihole --regex --help`, `pihole --wild --help`, `pihole --allow-regex --help`, `pihole --allow-wild --help` |
| Script Location | [`/opt/pihole/list.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/list.sh) |
| Example Usage | [`pihole --regex '^example.com$' '.*\.example2.net'`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#white-black-list) |
| Example Usage | [`pihole --regex '^example.com$' '.*\.example2.net'`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#white-black-list) |
Administrators need to be able to manually add and remove domains for various purposes, and these commands serve that purpose.
@@ -58,10 +58,10 @@ See [Regex Blocking](../regex/index.md) for more information about using Regex.
### Debugger
| | |
| -------------- | -------------- |
| Help Command | N/A |
| -------------- | -------------- |
| Help Command | N/A |
| Script Location | [`/opt/pihole/piholeDebug.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/piholeDebug.sh) |
| Example Usage | [`pihole debug`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#debug) |
| Example Usage | [`pihole debug`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#debug) |
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, who can help with diagnosing and rectifying persistent issues.
@@ -69,9 +69,9 @@ The Pi-hole debugger will attempt to diagnose any issues, and link to an FAQ wit
| | |
| -------------- | -------------- |
| Help Command | N/A |
| Help Command | N/A |
| Script Location | [`/opt/pihole/piholeLogFlush.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/piholeLogFlush.sh) |
| Example Usage | [`pihole flush`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#flushing-the-log) |
| Example Usage | [`pihole flush`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#flushing-the-log) |
When invoked manually, this command will allow you to empty Pi-hole's log, which is located at `/var/log/pihole/pihole.log`. The command also serves to rotate the log daily, if the `logrotate` application is installed.
@@ -79,9 +79,9 @@ When invoked manually, this command will allow you to empty Pi-hole's log, which
| | |
| -------------- | -------------- |
| Help Command | N/A |
| Help Command | N/A |
| Script Location | [`/etc/.pihole/automated install/basic-install.sh`](https://github.com/pi-hole/pi-hole/blob/master/automated%20install/basic-install.sh) |
| Example Usage | `pihole repair` |
| Example Usage | `pihole repair` |
There are times where the administrator will need to repair the Pi-hole installation, which is performed via this command.
@@ -93,9 +93,9 @@ There are times where the administrator will need to repair the Pi-hole installa
| | |
| -------------- | -------------- |
| Help Command | N/A |
| Help Command | N/A |
| Script Location | [`/usr/local/bin/pihole`](https://github.com/pi-hole/pi-hole/blob/master/pihole) |
| Example Usage | [`pihole tail`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#tailing-the-log) |
| Example Usage | [`pihole tail`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#tailing-the-log) |
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.
@@ -123,9 +123,9 @@ Gravity is one of the most important scripts of Pi-hole. Its main purpose is to
| | |
| -------------- | -------------- |
| Help Command | `pihole logging --help` |
| Help Command | `pihole logging --help` |
| 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) |
| 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.
@@ -133,9 +133,9 @@ This command specifies whether the Pi-hole log should be used.
| | |
| --------------- | --------------- |
| Help Command | `pihole query --help` |
| Help Command | `pihole query --help` |
| 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) |
| 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 allowlist, denylist, wildcards and subscribed lists for a specified domain.
@@ -149,9 +149,9 @@ This command will query your allowlist, denylist, wildcards and subscribed lists
| | |
| -------------- | -------------- |
| Help Command | `pihole updatePihole` |
| Help Command | `pihole updatePihole` |
| Script Location | [`/opt/pihole/update.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/update.sh) |
| Example Usage | `pihole -up` |
| Example Usage | `pihole -up` |
Check Pi-hole Core, Web Interface and FTL repositories to determine what upgrades (if any) are required. It will then automatically update and reinstall if necessary.
@@ -165,9 +165,9 @@ Check Pi-hole Core, Web Interface and FTL repositories to determine what upgrade
| | |
| --------------- | --------------- |
| Help Command | `pihole version` |
| Help Command | `pihole version` |
| Script Location | [`/opt/pihole/version.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/version.sh) |
| Example Usage | `pihole -v` |
| Example Usage | `pihole -v` |
Shows installed versions of Pi-hole, Web Interface & FTL.
@@ -175,9 +175,9 @@ Shows installed versions of Pi-hole, Web Interface & FTL.
| | |
| -------------- | -------------- |
| Help Command | N/A |
| Help Command | N/A |
| Script Location | [`/etc/.pihole/automated install/uninstall.sh`](https://github.com/pi-hole/pi-hole/blob/master/automated%20install/uninstall.sh) |
| Example Usage | [`pihole uninstall`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#uninstall) |
| Example Usage | [`pihole uninstall`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#uninstall) |
Uninstall Pi-hole from your system, giving the option to remove each dependency individually.
@@ -185,9 +185,9 @@ Uninstall Pi-hole from your system, giving the option to remove each dependency
| | |
| -------------- | -------------- |
| Help Command | N/A |
| Help Command | N/A |
| Script Location | [`/usr/local/bin/pihole`](https://github.com/pi-hole/pi-hole/blob/master/pihole) |
| Example Usage | [`pihole status`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#status) |
| Example Usage | [`pihole status`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#status) |
Display the running status of Pi-hole's DNS and blocking services.
@@ -195,9 +195,9 @@ Display the running status of Pi-hole's DNS and blocking services.
| | |
| -------------- | -------------- |
| Help Command | `pihole disable --help`/`pihole enable --help` |
| Help Command | `pihole disable --help`/`pihole enable --help` |
| Script Location | [`/usr/local/bin/pihole`](https://github.com/pi-hole/pi-hole/blob/master/pihole) |
| Example Usage | [`pihole disable 5m`/`pihole enable`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#toggle) |
| Example Usage | [`pihole disable 5m`/`pihole enable`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#toggle) |
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.
@@ -205,9 +205,9 @@ Toggle Pi-hole's ability to block unwanted domains. The disable option has the o
| | |
| -------------- | -------------- |
| Help Command | `pihole checkout --help` |
| Help Command | `pihole checkout --help` |
| 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) |
| 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.
@@ -217,9 +217,9 @@ Switch Pi-hole subsystems to a different GitHub branch. An admin can specify rep
| | |
| -------------- | -------------- |
| Help Command | N/A |
| Help Command | N/A |
| Script Location | [`/usr/local/bin/pihole`](https://github.com/pi-hole/pi-hole/blob/master/pihole) |
| Example Usage | `pihole setpassword` |
| Example Usage | `pihole setpassword` |
Set the Web Interface an API password. Password can be entered as an option (e.g: `pihole setpassword secretpassword`), or separately as to not display on the screen (e.g: `pihole setpassword`).
@@ -227,9 +227,9 @@ Set the Web Interface an API password. Password can be entered as an option (e.g
| | |
| -------------- | -------------- |
| Help Command | N/A |
| Help Command | N/A |
| Script Location | [`/usr/local/bin/pihole`](https://github.com/pi-hole/pi-hole/blob/master/pihole) |
| Example Usage | `pihole reloadlists` |
| Example Usage | `pihole reloadlists` |
Reload DNS lists. Note: This will NOT re-read any *.conf files
@@ -237,9 +237,9 @@ Reload DNS lists. Note: This will NOT re-read any *.conf files
| | |
| -------------- | -------------- |
| Help Command | N/A |
| Help Command | N/A |
| Script Location | [`/usr/local/bin/pihole`](https://github.com/pi-hole/pi-hole/blob/master/pihole) |
| Example Usage | `pihole reloaddns` |
| Example Usage | `pihole reloaddns` |
Flush and reload the pihole-FTL DNS cache. Note: This will NOT re-read any *.conf files

32
docs/main/prerequisites.md
View File

@@ -4,7 +4,7 @@ description: Operating system and network requirements
last_updated: May 25 2020
---
### Hardware
## Hardware
Pi-hole is very lightweight and does not require much processing power
@@ -17,11 +17,11 @@ Pi-hole is very lightweight and does not require much processing power
Despite the name, you are not limited to running Pi-hole on a Raspberry Pi.
Any hardware that runs one of the supported operating systems will do!
### Software
## Software
Pi-hole is supported on distributions utilizing [systemd](https://systemd.io/) or [sysvinit](https://www.nongnu.org/sysvinit/)!
#### Supported Operating Systems
### Supported Operating Systems
The following operating systems are **officially** supported:
@@ -44,32 +44,32 @@ Pi-hole only supports actively maintained versions of these systems.
<!-- markdownlint-enable code-block-style -->
### IP Addressing
## IP Addressing
Pi-hole needs a static IP address to properly function (a DHCP reservation is just fine).
### Ports
## Ports
| Service | Port | Protocol | Notes |
| --------------------|:-------------|:---------| --------------------|
| 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. |
| pihole-FTL | 80 (HTTP)<br/>443 (HTTPS) | TCP | If you have another webserver already listening on port `80`/`443`, then `pihole-FTL` will attempt to bind to `8080`/`8443` instead. If neither of these ports are available, `pihole-FTL`'s webserver will be unavailable until ports are configured manually (see configuration option `webserver.port`) |
| pihole-FTL | 123 (NTP) | UDP | The NTP server is an optional feature that requires an additional port. |
| Service | Port | Protocol | Notes |
| -------------------- | ------------- | --------- | -------------------- |
| 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. |
| pihole-FTL | 80 (HTTP)<br/>443 (HTTPS) | TCP | If you have another webserver already listening on port `80`/`443`, then `pihole-FTL` will attempt to bind to `8080`/`8443` instead. If neither of these ports are available, `pihole-FTL`'s webserver will be unavailable until ports are configured manually (see configuration option `webserver.port`) |
| pihole-FTL | 123 (NTP) | UDP | The NTP server is an optional feature that requires an additional port. |
!!! info
The use of pihole-FTL on ports _67_ or _547_ is optional, but required if you use the DHCP functions of Pi-hole.
The use of port _123_ is required when using pihole-FTL as NTP-Server.
### Firewalls
## Firewalls
Below are some examples of firewall rules that will need to be set on your Pi-hole server in order to use the functions available. These are only shown as guides, the actual commands used will be found with your distribution's documentation.
Because Pi-hole was designed to work inside a local network, the following rules will block the traffic from the Internet for security reasons. `192.168.0.0/16` is the most common local network IP range for home users but it can be different in your case, for example other common local network IPs are `10.0.0.0/8` and `172.16.0.0/12`.
**Check your local network settings before applying these rules.**
#### IPTables
### IPTables
IPTables uses two sets of tables. One set is for IPv4 chains, and the second is for IPv6 chains. If only IPv4 blocking is used for the Pi-hole installation, only apply the rules for IP4Tables. Full Stack (IPv4 and IPv6) require both sets of rules to be applied. _Note: These examples insert the rules at the front of the chain. Please see your distribution's documentation for the exact proper command to use._
@@ -94,7 +94,7 @@ ip6tables -I INPUT -p udp -m udp --sport 546:547 --dport 546:547 -j ACCEPT
ip6tables -I INPUT -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
```
#### FirewallD
### 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. Finally `--reload` to have the new firewall configuration take effect immediately.
@@ -103,7 +103,7 @@ firewall-cmd --permanent --add-service=http --add-service=https --add-service=dn
firewall-cmd --reload
```
#### ufw
### ufw
ufw stores all rules persistently, so you just need to execute the commands below.

4
docs/regex/tutorial.md
View File

@@ -79,12 +79,14 @@ Example | Interpretation
Alternations can be used as an "or" operator in regular expressions.
<!-- markdownlint-disable MD056 -->
<!-- markdownlint-disable MD060 -->
Example | Interpretation
--- | ---
`(abc)|(def)` | matches `abc` *and* `def`
`domain(a|b)\.com` | matches `domaina.com` and `domainb.com` but not `domain.com` or `domainx.com`
`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`)
<!-- markdownlint-enable MD056 -->
<!-- markdownlint-enable MD060 -->
## Character classes (`[:class:]`)
In addition to character groups, there are also some special character classes available, such as
@@ -132,6 +134,7 @@ A domain name shall not start or end with a dash but can contain any number of t
# Cheatsheet
<!-- markdownlint-disable MD056 -->
<!-- markdownlint-disable MD060 -->
Expression | Meaning | Example
------------ | ------------- | -----------
`^` | Beginning of string | `^client` matches strings that begin with `client`, such as `client.server.com` but not `more.client.server.com` (exception: within a character range (`[]`) `^` means negation)
@@ -147,3 +150,4 @@ Expression | Meaning | Example
`{ }` | Matches a specified number of occurrences of the previous | `[0-9]{3}` matches any three-digit number like `315` but not `31`;<br>`[0-9]{2,4}` matches two- to four-digit numbers like `12`, `123`, and `1234` but not `1` or `12345`;<br>`[0-9]{2,}` matches any number with two or more digits like `1234567`, `123456789`, but not `1`
`\` | Used to escape a special character not inside `[]` | `google\.com` matches `google.com`
<!-- markdownlint-enable MD056 -->
<!-- markdownlint-enable MD060 -->

78
package-lock.json generated
View File

@@ -10,7 +10,7 @@
"license": "CC-BY-SA-4.0",
"devDependencies": {
"linkinator": "^7.5.0",
"markdownlint-cli2": "0.18.1"
"markdownlint-cli2": "0.19.0"
}
},
"node_modules/@isaacs/cliui": {
@@ -81,9 +81,9 @@
}
},
"node_modules/@sindresorhus/merge-streams": {
"version": "2.3.0",
"resolved": "https://registry.npmjs.org/@sindresorhus/merge-streams/-/merge-streams-2.3.0.tgz",
"integrity": "sha512-LtoMMhxAlorcGhmFYI+LhPgbPZCkgP6ra1YL604EeF6U98pLlQ3iWIGMdWSC+vWmPBWBNgmDBAhnAobLROJmwg==",
"version": "4.0.0",
"resolved": "https://registry.npmjs.org/@sindresorhus/merge-streams/-/merge-streams-4.0.0.tgz",
"integrity": "sha512-tlqY9xq5ukxTUZBmoOp+m61cqwQD5pHJtFY3Mn8CA8ps6yghLH/Hw8UPdqg4OLmFW3IFlcXnQNmo/dh8HzXYIQ==",
"dev": true,
"license": "MIT",
"engines": {
@@ -279,9 +279,9 @@
}
},
"node_modules/debug": {
"version": "4.4.0",
"resolved": "https://registry.npmjs.org/debug/-/debug-4.4.0.tgz",
"integrity": "sha512-6WTZ/IxCY/T6BALoZHaE4ctp9xm+Z5kY/pzYaCHRFeyVhojxlrm+46y68HA6hr0TcwEssoxNiDEUJQjfPZ/RYA==",
"version": "4.4.3",
"resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
"integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
"dev": true,
"license": "MIT",
"dependencies": {
@@ -297,9 +297,9 @@
}
},
"node_modules/decode-named-character-reference": {
"version": "1.1.0",
"resolved": "https://registry.npmjs.org/decode-named-character-reference/-/decode-named-character-reference-1.1.0.tgz",
"integrity": "sha512-Wy+JTSbFThEOXQIR2L6mxJvEs+veIzpmqD7ynWxMXGpnk3smkHQOp6forLdHsKpAMW9iJpaBBIxz285t1n1C3w==",
"version": "1.2.0",
"resolved": "https://registry.npmjs.org/decode-named-character-reference/-/decode-named-character-reference-1.2.0.tgz",
"integrity": "sha512-c6fcElNV6ShtZXmsgNgFFV5tVX2PaV4g+MOAkb8eXHvn6sryJBrZa9r0zV6+dtTyoCKxtDy5tyQ5ZwQuidtd+Q==",
"dev": true,
"license": "MIT",
"dependencies": {
@@ -526,21 +526,21 @@
}
},
"node_modules/globby": {
"version": "14.1.0",
"resolved": "https://registry.npmjs.org/globby/-/globby-14.1.0.tgz",
"integrity": "sha512-0Ia46fDOaT7k4og1PDW4YbodWWr3scS2vAr2lTbsplOt2WkKp0vQbkI9wKis/T5LV/dqPjO3bpS/z6GTJB82LA==",
"version": "15.0.0",
"resolved": "https://registry.npmjs.org/globby/-/globby-15.0.0.tgz",
"integrity": "sha512-oB4vkQGqlMl682wL1IlWd02tXCbquGWM4voPEI85QmNKCaw8zGTm1f1rubFgkg3Eli2PtKlFgrnmUqasbQWlkw==",
"dev": true,
"license": "MIT",
"dependencies": {
"@sindresorhus/merge-streams": "^2.1.0",
"@sindresorhus/merge-streams": "^4.0.0",
"fast-glob": "^3.3.3",
"ignore": "^7.0.3",
"ignore": "^7.0.5",
"path-type": "^6.0.0",
"slash": "^5.1.0",
"unicorn-magic": "^0.3.0"
},
"engines": {
"node": ">=18"
"node": ">=20"
},
"funding": {
"url": "https://github.com/sponsors/sindresorhus"
@@ -580,9 +580,9 @@
}
},
"node_modules/ignore": {
"version": "7.0.4",
"resolved": "https://registry.npmjs.org/ignore/-/ignore-7.0.4.tgz",
"integrity": "sha512-gJzzk+PQNznz8ysRrC0aOkBNVRBDtE1n53IqyqEf3PXrYwomFs5q4pGMizBMJF+ykh03insJ27hB8gSrD2Hn8A==",
"version": "7.0.5",
"resolved": "https://registry.npmjs.org/ignore/-/ignore-7.0.5.tgz",
"integrity": "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg==",
"dev": true,
"license": "MIT",
"engines": {
@@ -704,9 +704,9 @@
}
},
"node_modules/js-yaml": {
"version": "4.1.0",
"resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz",
"integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==",
"version": "4.1.1",
"resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz",
"integrity": "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==",
"dev": true,
"license": "MIT",
"dependencies": {
@@ -724,9 +724,9 @@
"license": "MIT"
},
"node_modules/katex": {
"version": "0.16.22",
"resolved": "https://registry.npmjs.org/katex/-/katex-0.16.22.tgz",
"integrity": "sha512-XCHRdUw4lf3SKBaJe4EvgqIuWwkPSo9XoeO8GjQW94Bp7TWv9hNhzZjZ+OH9yf1UmLygb7DIT5GSFQiyt16zYg==",
"version": "0.16.25",
"resolved": "https://registry.npmjs.org/katex/-/katex-0.16.25.tgz",
"integrity": "sha512-woHRUZ/iF23GBP1dkDQMh1QBad9dmr8/PAwNA54VrSOVYgI12MAcE14TqnDdQOdzyEonGzMepYnqBMYdsoAr8Q==",
"dev": true,
"funding": [
"https://opencollective.com/katex",
@@ -802,9 +802,9 @@
}
},
"node_modules/markdownlint": {
"version": "0.38.0",
"resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.38.0.tgz",
"integrity": "sha512-xaSxkaU7wY/0852zGApM8LdlIfGCW8ETZ0Rr62IQtAnUMlMuifsg09vWJcNYeL4f0anvr8Vo4ZQar8jGpV0btQ==",
"version": "0.39.0",
"resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.39.0.tgz",
"integrity": "sha512-Xt/oY7bAiHwukL1iru2np5LIkhwD19Y7frlsiDILK62v3jucXCD6JXlZlwMG12HZOR+roHIVuJZrfCkOhp6k3g==",
"dev": true,
"license": "MIT",
"dependencies": {
@@ -825,18 +825,19 @@
}
},
"node_modules/markdownlint-cli2": {
"version": "0.18.1",
"resolved": "https://registry.npmjs.org/markdownlint-cli2/-/markdownlint-cli2-0.18.1.tgz",
"integrity": "sha512-/4Osri9QFGCZOCTkfA8qJF+XGjKYERSHkXzxSyS1hd3ZERJGjvsUao2h4wdnvpHp6Tu2Jh/bPHM0FE9JJza6ng==",
"version": "0.19.0",
"resolved": "https://registry.npmjs.org/markdownlint-cli2/-/markdownlint-cli2-0.19.0.tgz",
"integrity": "sha512-0+g7Fi/Y3qfvwfhJr77CpC/dEEoc4k7SvumlnL1tb68O+7fjKtIUG7aKzNUQIMXTVi8x63jcfXg4swz/ZYKyCw==",
"dev": true,
"license": "MIT",
"peer": true,
"dependencies": {
"globby": "14.1.0",
"js-yaml": "4.1.0",
"globby": "15.0.0",
"js-yaml": "4.1.1",
"jsonc-parser": "3.3.1",
"markdown-it": "14.1.0",
"markdownlint": "0.38.0",
"markdownlint-cli2-formatter-default": "0.0.5",
"markdownlint": "0.39.0",
"markdownlint-cli2-formatter-default": "0.0.6",
"micromatch": "4.0.8"
},
"bin": {
@@ -850,9 +851,9 @@
}
},
"node_modules/markdownlint-cli2-formatter-default": {
"version": "0.0.5",
"resolved": "https://registry.npmjs.org/markdownlint-cli2-formatter-default/-/markdownlint-cli2-formatter-default-0.0.5.tgz",
"integrity": "sha512-4XKTwQ5m1+Txo2kuQ3Jgpo/KmnG+X90dWt4acufg6HVGadTUG5hzHF/wssp9b5MBYOMCnZ9RMPaU//uHsszF8Q==",
"version": "0.0.6",
"resolved": "https://registry.npmjs.org/markdownlint-cli2-formatter-default/-/markdownlint-cli2-formatter-default-0.0.6.tgz",
"integrity": "sha512-VVDGKsq9sgzu378swJ0fcHfSicUnMxnL8gnLm/Q4J/xsNJ4e5bA6lvAz7PCzIl0/No0lHyaWdqVD2jotxOSFMQ==",
"dev": true,
"license": "MIT",
"funding": {
@@ -868,6 +869,7 @@
"integrity": "sha512-CTPAcRBq57cn3R8n3hwc2REddc28hjR7RzDXQ+lXLmMJYqn20BaI2cGw6QjgZGIgVfp2Wdfw4aMzgNteQ6qJgQ==",
"dev": true,
"license": "MIT",
"peer": true,
"bin": {
"marked": "bin/marked.js"
},

2
package.json
View File

@@ -26,6 +26,6 @@
},
"devDependencies": {
"linkinator": "^7.5.0",
"markdownlint-cli2": "0.18.1"
"markdownlint-cli2": "0.19.0"
}
}