From d7dc00efb8ed2a0dd8fa0d9d637c5ca18f99f7bf Mon Sep 17 00:00:00 2001 From: Adam Warner Date: Mon, 1 Oct 2018 09:10:39 +0100 Subject: [PATCH 01/14] Port core-functions from wiki Signed-off-by: Adam Warner --- docs/main/core-functions.md | 301 ++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 302 insertions(+) create mode 100644 docs/main/core-functions.md diff --git a/docs/main/core-functions.md b/docs/main/core-functions.md new file mode 100644 index 0000000..17453fe --- /dev/null +++ b/docs/main/core-functions.md @@ -0,0 +1,301 @@ +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` +[Web Script](#pi-hole-web) | `pihole -a` + +--- + +## Pi-hole Core + +| Feature | Invocation | + -------------- | -------------- +[Core](#core-script) | `pihole` +[Whitelisting, Blacklisting and Wildcards](#whitelisting-blacklisting-and-wildcards) | `pihole -w`, `pihole -b`, `pihole -wild` +[Debugger](#debugger) | `pihole debug` +[Log Flush](#log-flush) | `pihole flush` +[Reconfigure](#reconfigure) | `pihole reconfigure` +[Tail](#tail) | `pihole tail` +[Admin](#admin) | `pihole -a` +[Chronometer](#chronometer) | `pihole chronometer` +[Gravity](#gravity) | `pihole updateGravity` +[Logging](#logging) | `pihole logging` +[Query](#query) | `pihole query` +[Update](#update) | `pihole updatePihole` +[Version](#version) | `pihole version` +[Uninstall](#uninstall) | `pihole uninstall` +[Status](#status) | `pihole status` +[Enable & Disable](#enable--disable) | `pihole enable` +[Restart DNS](#restart-dns) | `pihole restartdns` +[Checkout](#checkout) | `pihole checkout` + +### Core Script +| | | + -------------- | -------------- +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` + +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 Wildcards +| | | + -------------- | -------------- +Help Command | `pihole -w --help`, `pihole -b --help`, `pihole -wild --help` +Script Location | [`/opt/pihole/list.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/list.sh) +Example Usage | [`pihole -wild 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. + +**Basic Script Process**: +* Each domain is validated 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 wildcard domain gets added or removed from `/etc/dnsmasq.d/03-pihole-wildcard.conf` + * `gravity.sh` is then called to restart the DNS server + +### Debugger +| | | + -------------- | -------------- +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) + +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 +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) + +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 +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 reconfigure` + +There are times where the administrator will need to repair or reconfigure the Pi-hole installation, which is performed via this command. + +**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 +* The rest of `basic-install.sh` will then run as appropriate + +### Tail +| | | + -------------- | -------------- +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) + +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` +Script Location | [`/opt/pihole/webpage.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/webpage.sh) +Example Usage | `pihole -a -p secretpassword` + +Detailed information on this is [found here](#web-script). + +### Chronometer +| | | + -------------- | -------------- +Help Command | `pihole -c --help` +Script Location | [`/opt/pihole/chronometer.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/chronometer.sh) +Example Usage | [`pihole -c -e`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#chronometer) + +Chronometer is a console dashboard of real-time stats, which can be displayed via `ssh` or on an LCD screen attached directly to your hardware. The script is capable of detecting the size of your screen, and adjusting output to try and best suit it. + + +
Image courtesy of /u/super_nicktendo22 + +### Gravity +| | | + -------------- | -------------- +Help Command | N/A +Script Location | [`/opt/pihole/gravity.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/gravity.sh) +Example Usage | [`pihole -g`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#gravity) + +Gravity is one of the most important scripts of Pi-hole. Its main purpose is to retrieve blocklists, and then consolidate them into one unique list for the built-in DNS server to use, but it also serves to complete the process of manual whitelisting, blacklisting and wildcard update. It is run automatically each week, but it can be invoked manually at any time. + +**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 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 seperate `.list` files +* 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) +Example Usage | [`pihole loggging 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` + +### Query +| | | + --------------- | --------------- +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) + +This command will query your whitelist, blacklist, wildcards and adlists for a specified domain. + +**Basic Script Process**: +* 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 (`/etc/pihole/*list`) +* 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 + +### Update +| | | + -------------- | -------------- +Help Command | `pihole update` +Script Location | [`/opt/pihole/update.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/update.sh) +Example Usage | `pihole -up` + +Check Pi-hole Core, Web Interface and FTL repositories to determine what upgrade (if any) is required. It will then automatically update and reinstall if necessary. + +**Basic Script Process**: +* Script determines if updates are available by querying GitHub +* Updated files are downloaded to the local filesystem using `git` +* [`basic-install.sh`](https://github.com/pi-hole/pi-hole/blob/master/automated%20install/basic-install.sh) is run + +### 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 -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 +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) + +Uninstall Pi-hole from your system, giving the option to remove each dependency individually. + +### Status +| | | + -------------- | -------------- +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) + +Display the running status of Pi-hole's DNS and blocking services. + +### Enable & Disable +| | | + -------------- | -------------- +Help Command | `pihole disable --help` +Script Location | [`/usr/local/bin/pihole`](https://github.com/pi-hole/pi-hole/blob/master/pihole) +Example Usage | [`pihole disable 5m`](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. + +### Restart DNS +| | | + -------------- | -------------- +Help Command | N/A +Script Location | [`/usr/local/bin/pihole`](https://github.com/pi-hole/pi-hole/blob/master/pihole) +Example Usage | [`pihole restartdns`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#restartdns) + +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) +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. + +--- + +## Pi-hole Web + +| Feature | Invocation | + -------------- | -------------- +[Web Script](#web-script) | `pihole -a` +[Password](#password) | `pihole -a password` +[Temperature Unit](#temperature-unit) | `pihole -a celsius`, `pihole -a fahrenheit`, `pihole -a kelvin` +[Host Record](#host-record) | `pihole -a hostrecord` +[Email Address](#email-address) | `pihole -a email` +[Interface](#interface) | `pihole -a interface` + +### Web Script +| | | + -------------- | -------------- +Help Command | `pihole -a --help` +Script Location | [`/opt/pihole/webpage.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/webpage.sh) +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 +Script Location | [`/opt/pihole/webpage.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/webpage.sh) +Example Usage | [`pihole -a -p secretpassword`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#web-password) + +Set Web Interface password. Password can be entered as an option (e.g: `pihole -a -p secretpassword`), or seperately as to not display on screen (e.g: `pihole -a -p`). + +### Temperature Unit +| | | + -------------- | -------------- +Help Command | N/A +Script Location | [`/opt/pihole/webpage.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/webpage.sh) +Example Usage | [`pihole -a -c`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#temp-unit) + +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` +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 +| | | + -------------- | -------------- +Help Command | N/A +Script Location | [`/opt/pihole/webpage.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/webpage.sh) +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` +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. diff --git a/mkdocs.yml b/mkdocs.yml index 445d1f7..a7c8266 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,6 +43,7 @@ pages: - 'Prerequisites': 'main/prerequesites.md' - 'Installation': 'main/basic-install.md' - 'Post-Install': 'main/post-install.md' + - 'Core Functions': 'main/core-functions.md' - 'Updating': 'main/update.md' - 'FTLDNS': - 'Overview': "ftldns/index.md" From c54cdb632b957657bfdc72c4cf5937f34746f7a3 Mon Sep 17 00:00:00 2001 From: Adam Warner Date: Fri, 5 Oct 2018 11:16:19 +0100 Subject: [PATCH 02/14] Move Core Functions menu item up one level. Signed-off-by: Adam Warner --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index a7c8266..7db3275 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,8 +43,8 @@ pages: - 'Prerequisites': 'main/prerequesites.md' - 'Installation': 'main/basic-install.md' - 'Post-Install': 'main/post-install.md' - - 'Core Functions': 'main/core-functions.md' - 'Updating': 'main/update.md' +- 'Core Functions': 'main/core-functions.md' - 'FTLDNS': - 'Overview': "ftldns/index.md" - 'Configuration': "ftldns/configfile.md" From e11a30515f90219fd010bb002fca5508355f3604 Mon Sep 17 00:00:00 2001 From: Adam Warner Date: Sat, 6 Oct 2018 11:20:21 +0100 Subject: [PATCH 03/14] rename core-functions to pihole-command, put it under the core subheading Signed-off-by: Adam Warner --- .../core-functions.md => core/pihole-command.md} | 12 ++++++------ mkdocs.yml | 3 ++- 2 files changed, 8 insertions(+), 7 deletions(-) rename docs/{main/core-functions.md => core/pihole-command.md} (98%) diff --git a/docs/main/core-functions.md b/docs/core/pihole-command.md similarity index 98% rename from docs/main/core-functions.md rename to docs/core/pihole-command.md index 17453fe..1ed84d0 100644 --- a/docs/main/core-functions.md +++ b/docs/core/pihole-command.md @@ -12,7 +12,7 @@ Pi-hole makes use of many commands, and here we will break down those required t | Feature | Invocation | -------------- | -------------- [Core](#core-script) | `pihole` -[Whitelisting, Blacklisting and Wildcards](#whitelisting-blacklisting-and-wildcards) | `pihole -w`, `pihole -b`, `pihole -wild` +[Whitelisting, Blacklisting and Wildcards](#whitelisting-blacklisting-and-wildcards) | `pihole -w`, `pihole -b`, `pihole -wild` [Debugger](#debugger) | `pihole debug` [Log Flush](#log-flush) | `pihole flush` [Reconfigure](#reconfigure) | `pihole reconfigure` @@ -34,7 +34,7 @@ Pi-hole makes use of many commands, and here we will break down those required t | | | -------------- | -------------- Help Command | `pihole --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 -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. @@ -201,7 +201,7 @@ Uninstall Pi-hole from your system, giving the option to remove each dependency | | | -------------- | -------------- Help Command | N/A -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 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. @@ -210,7 +210,7 @@ Display the running status of Pi-hole's DNS and blocking services. | | | -------------- | -------------- Help Command | `pihole disable --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 disable 5m`](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. @@ -219,7 +219,7 @@ Toggle Pi-hole's ability to block unwanted domains. The disable option has the o | | | -------------- | -------------- Help Command | N/A -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 restartdns`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#restartdns) Restart Pi-hole's DNS service. @@ -240,7 +240,7 @@ Switch Pi-hole subsystems to a different GitHub branch. An admin can specify rep | Feature | Invocation | -------------- | -------------- [Web Script](#web-script) | `pihole -a` -[Password](#password) | `pihole -a password` +[Password](#password) | `pihole -a password` [Temperature Unit](#temperature-unit) | `pihole -a celsius`, `pihole -a fahrenheit`, `pihole -a kelvin` [Host Record](#host-record) | `pihole -a hostrecord` [Email Address](#email-address) | `pihole -a email` diff --git a/mkdocs.yml b/mkdocs.yml index 7db3275..44e6ebd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -44,7 +44,8 @@ pages: - 'Installation': 'main/basic-install.md' - 'Post-Install': 'main/post-install.md' - 'Updating': 'main/update.md' -- 'Core Functions': 'main/core-functions.md' +- 'Pi-hole Core' + - '`pihole` command': 'main/pihole-command.md' - 'FTLDNS': - 'Overview': "ftldns/index.md" - 'Configuration': "ftldns/configfile.md" From 4ff402bdc75354838591fbdc399f84abcd71f536 Mon Sep 17 00:00:00 2001 From: Adam Warner Date: Sat, 6 Oct 2018 11:24:26 +0100 Subject: [PATCH 04/14] Accidentally a :1 Signed-off-by: Adam Warner --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 44e6ebd..0ff5587 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -44,7 +44,7 @@ pages: - 'Installation': 'main/basic-install.md' - 'Post-Install': 'main/post-install.md' - 'Updating': 'main/update.md' -- 'Pi-hole Core' +- 'Pi-hole Core': - '`pihole` command': 'main/pihole-command.md' - 'FTLDNS': - 'Overview': "ftldns/index.md" From 41a9cba74ec5e2044b2322ddb840c6e860abcfbe Mon Sep 17 00:00:00 2001 From: Mcat12 Date: Wed, 10 Oct 2018 21:52:39 -0400 Subject: [PATCH 05/14] Fix file path and title for the pihole command Signed-off-by: Mcat12 --- docs/core/pihole-command.md | 2 ++ mkdocs.yml | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/core/pihole-command.md b/docs/core/pihole-command.md index 1ed84d0..2da8a8c 100644 --- a/docs/core/pihole-command.md +++ b/docs/core/pihole-command.md @@ -1,3 +1,5 @@ +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. | Index | Invocation | diff --git a/mkdocs.yml b/mkdocs.yml index 72ce029..9538902 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -45,7 +45,7 @@ pages: - 'Post-Install': 'main/post-install.md' - 'Updating': 'main/update.md' - 'Pi-hole Core': - - '`pihole` command': 'main/pihole-command.md' + - 'The pihole command': 'core/pihole-command.md' - 'FTLDNS': - 'Overview': "ftldns/index.md" - 'Configuration': "ftldns/configfile.md" From 8cbcb391982b1adc18905319b37c6961de38c09e Mon Sep 17 00:00:00 2001 From: Mcat12 Date: Wed, 10 Oct 2018 21:54:01 -0400 Subject: [PATCH 06/14] Fix enable/disable link Signed-off-by: Mcat12 --- docs/core/pihole-command.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/pihole-command.md b/docs/core/pihole-command.md index 2da8a8c..cbef354 100644 --- a/docs/core/pihole-command.md +++ b/docs/core/pihole-command.md @@ -28,7 +28,7 @@ Pi-hole makes use of many commands, and here we will break down those required t [Version](#version) | `pihole version` [Uninstall](#uninstall) | `pihole uninstall` [Status](#status) | `pihole status` -[Enable & Disable](#enable--disable) | `pihole enable` +[Enable & Disable](#enable-disable) | `pihole enable` [Restart DNS](#restart-dns) | `pihole restartdns` [Checkout](#checkout) | `pihole checkout` From 8eb1122ade29d989299a260a96108de09d119e2f Mon Sep 17 00:00:00 2001 From: Mcat12 Date: Wed, 10 Oct 2018 22:04:27 -0400 Subject: [PATCH 07/14] Add regex info to list.sh section Signed-off-by: Mcat12 --- docs/core/pihole-command.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/core/pihole-command.md b/docs/core/pihole-command.md index cbef354..6d0309d 100644 --- a/docs/core/pihole-command.md +++ b/docs/core/pihole-command.md @@ -14,7 +14,7 @@ Pi-hole makes use of many commands, and here we will break down those required t | Feature | Invocation | -------------- | -------------- [Core](#core-script) | `pihole` -[Whitelisting, Blacklisting and Wildcards](#whitelisting-blacklisting-and-wildcards) | `pihole -w`, `pihole -b`, `pihole -wild` +[Whitelisting, Blacklisting and Regex](#whitelisting-blacklisting-and-regex) | `pihole -w`, `pihole -b`, `pihole -regex`, `pihole -wild` [Debugger](#debugger) | `pihole debug` [Log Flush](#log-flush) | `pihole flush` [Reconfigure](#reconfigure) | `pihole reconfigure` @@ -41,22 +41,26 @@ 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 Wildcards +### Whitelisting, Blacklisting and Regex | | | -------------- | -------------- -Help Command | `pihole -w --help`, `pihole -b --help`, `pihole -wild --help` +Help Command | `pihole -w --help`, `pihole -b --help`, `pihole -regex --help`, `pihole -wild --help` Script Location | [`/opt/pihole/list.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/list.sh) -Example Usage | [`pihole -wild 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. +See [Regex Blocking](/ftldns/regex/overview/) for more information about using Regex. + **Basic Script Process**: -* Each domain is validated using regex, to ensure invalid domains and IDNs are not added + +* 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 wildcard domain gets added or removed from `/etc/dnsmasq.d/03-pihole-wildcard.conf` - * `gravity.sh` is then called to restart the DNS server +* 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 ### Debugger | | | From 80398473e0d02a2309100ec019693123831664c5 Mon Sep 17 00:00:00 2001 From: Mcat12 Date: Wed, 10 Oct 2018 22:08:57 -0400 Subject: [PATCH 08/14] Fix Basic Script Process lists Signed-off-by: Mcat12 --- docs/core/pihole-command.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/core/pihole-command.md b/docs/core/pihole-command.md index 6d0309d..cb094dc 100644 --- a/docs/core/pihole-command.md +++ b/docs/core/pihole-command.md @@ -90,6 +90,7 @@ Example Usage | `pihole reconfigure` There are times where the administrator will need to repair or reconfigure the Pi-hole installation, which is performed via this command. **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 @@ -135,6 +136,7 @@ Example Usage | [`pihole -g`](https://discourse.pi-hole.net/t/the-pihole-comma Gravity is one of the most important scripts of Pi-hole. Its main purpose is to retrieve blocklists, and then consolidate them into one unique list for the built-in DNS server to use, but it also serves to complete the process of manual whitelisting, blacklisting and wildcard update. It is run automatically each week, but it can be invoked manually at any time. **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 runs through each URL, downloading it if necessary @@ -164,6 +166,7 @@ Example Usage | [`pihole -q -exact -adlist example.domain.com`](https://discou This command will query your whitelist, blacklist, wildcards and adlists for a specified domain. **Basic Script Process**: + * 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 (`/etc/pihole/*list`) @@ -181,6 +184,7 @@ Example Usage | `pihole -up` Check Pi-hole Core, Web Interface and FTL repositories to determine what upgrade (if any) is required. It will then automatically update and reinstall if necessary. **Basic Script Process**: + * Script determines if updates are available by querying GitHub * Updated files are downloaded to the local filesystem using `git` * [`basic-install.sh`](https://github.com/pi-hole/pi-hole/blob/master/automated%20install/basic-install.sh) is run From 247d142e05a9a6736f7dd871bdcadfd06cfcd757 Mon Sep 17 00:00:00 2001 From: Mcat12 Date: Wed, 10 Oct 2018 22:09:31 -0400 Subject: [PATCH 09/14] Fix "loggging" Signed-off-by: Mcat12 --- docs/core/pihole-command.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/pihole-command.md b/docs/core/pihole-command.md index cb094dc..b0efcad 100644 --- a/docs/core/pihole-command.md +++ b/docs/core/pihole-command.md @@ -152,7 +152,7 @@ Gravity is one of the most important scripts of Pi-hole. Its main purpose is to -------------- | -------------- Help Command | `pihole logging --help` Script Location | [`/usr/local/bin/pihole`](https://github.com/pi-hole/pi-hole/blob/master/pihole) -Example Usage | [`pihole loggging 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, by commenting out `log-queries` within `/etc/dnsmasq.d/01-pihole.conf` From 0e7f327bf5b63ab3e6627a48d338d2472b109ef1 Mon Sep 17 00:00:00 2001 From: Mcat12 Date: Wed, 10 Oct 2018 22:11:12 -0400 Subject: [PATCH 10/14] Clarify that logging off flushes the log Signed-off-by: Mcat12 --- docs/core/pihole-command.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/pihole-command.md b/docs/core/pihole-command.md index b0efcad..1ba5e7d 100644 --- a/docs/core/pihole-command.md +++ b/docs/core/pihole-command.md @@ -154,7 +154,7 @@ 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) -This command specifies whether the Pi-hole log should be used, by commenting out `log-queries` within `/etc/dnsmasq.d/01-pihole.conf` +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 | | | From 54f68608fcfe5e0b202ecca58c0e5b6edb49fa4b Mon Sep 17 00:00:00 2001 From: Mcat12 Date: Wed, 10 Oct 2018 22:13:53 -0400 Subject: [PATCH 11/14] Tweak a line in query explanation Signed-off-by: Mcat12 --- docs/core/pihole-command.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/pihole-command.md b/docs/core/pihole-command.md index 1ba5e7d..bbb9fe8 100644 --- a/docs/core/pihole-command.md +++ b/docs/core/pihole-command.md @@ -169,7 +169,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 (`/etc/pihole/*list`) +* 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 From 5b0e856e796f4d28ec121806dc1632b5933c47f5 Mon Sep 17 00:00:00 2001 From: Tom Daykin Date: Fri, 12 Oct 2018 09:15:52 +0000 Subject: [PATCH 12/14] Revised repo Readme] Signed-off-by: Tom Daykin --- README.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 8dd03f0..e4b25ca 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,23 @@ -If you want to work on this repo, you can preview the site as you work. +## Documentation & User Guides + +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 `REPO/docs/guides` +- Create the file using a URL friendly filename. + 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 commiting them. This can be done by using the `mkdocs serve` command. Linux Mint / Ubuntu instructions: - ``` git clone git@github.com:pi-hole/docs.git cd docs @@ -10,9 +26,9 @@ sudo pip install mkdocs-material markdown-include mkdocs serve --dev-addr 0.0.0.0:8000 ``` -Deploying to GitHub pages: +#### Deploying to GitHub pages: ``` mkdocs gh-deploy ``` MkDocs will build the docs and use the `ghp-import` tool to commit them to our `gh-pages` branch and also automatically push the `gh-pages` branch to GitHub. -Warning: Be aware that you will not be able to review the built site before it is pushed to GitHub! Therefore, you **must** verify any changes you make to the docs beforehand by using the `mkdocs serve` command and reviewing the built files locally. + From 6774634c3c93358b4c72e5b410e849a0d791ae66 Mon Sep 17 00:00:00 2001 From: Tom Daykin Date: Sat, 13 Oct 2018 14:55:19 +0000 Subject: [PATCH 13/14] Added recommendations Signed-off-by: Tom Daykin --- README.md | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index e4b25ca..3cf032d 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -## Documentation & User Guides + ## Documentation & User Guides This repo is the source for the official [Pi-hole documentation](https://docs.pi-hole.net/). @@ -8,27 +8,21 @@ To add a new link on the navigation panel you need to edit the `mkdocs.yml` file To add a new document or guide. - Navigate to the directory where it will be hosted. - EG. guides are in `REPO/docs/guides` + EG. guides are in `docs/guides` - Create the file using a URL friendly filename. 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 commiting them. This can be done by using the `mkdocs serve` command. +Whilst working on this repo, it is advised that you review your own changes locally before commiting them. This can be done by using the `mkdocs serve` command. -Linux Mint / Ubuntu instructions: -``` -git clone git@github.com:pi-hole/docs.git +Please make sure you fork the repo and change the clone URL in the example below for your fork: + +```bash +git clone https://github.com/YOUR-USERNAME/docs cd docs sudo pip install mkdocs sudo pip install mkdocs-material markdown-include mkdocs serve --dev-addr 0.0.0.0:8000 ``` - -#### Deploying to GitHub pages: -``` -mkdocs gh-deploy -``` -MkDocs will build the docs and use the `ghp-import` tool to commit them to our `gh-pages` branch and also automatically push the `gh-pages` branch to GitHub. - From 5f50c95af71bdaf48ca84d6f591fad545c7e598e Mon Sep 17 00:00:00 2001 From: Tom Daykin Date: Mon, 15 Oct 2018 11:47:11 +0000 Subject: [PATCH 14/14] Fixed spacing problems Signed-off-by: Tom Daykin --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 3cf032d..d31023f 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,21 @@ - ## Documentation & User Guides +## Documentation & User Guides This repo is the source for the official [Pi-hole documentation](https://docs.pi-hole.net/). -#### How to contribute. +### 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. +To add a new document or guide. -- Navigate to the directory where it will be hosted. +- Navigate to the directory where it will be hosted. EG. guides are in `docs/guides` -- Create the file using a URL friendly filename. +- Create the file using a URL friendly filename. 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 commiting them. This can be done by using the `mkdocs serve` command. +### Testing your changes. +Whilst working on this repo, it is advised that you review your own changes locally before commiting them. This can be done by using the `mkdocs serve` command. Please make sure you fork the repo and change the clone URL in the example below for your fork: