diff --git a/README.md b/README.md index 92bb76ea..68d7c09f 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ + +

Pi-hole @@ -5,13 +7,16 @@
Network-wide ad blocking via your own Linux hardware

+ -The Pi-hole[®](https://pi-hole.net/trademark-rules-and-brand-guidelines/) is a [DNS sinkhole](https://en.wikipedia.org/wiki/DNS_Sinkhole) that protects your devices from unwanted content, without installing any client-side software. +# + +The Pi-hole® is a [DNS sinkhole](https://en.wikipedia.org/wiki/DNS_Sinkhole) that protects your devices from unwanted content, without installing any client-side software. - **Easy-to-install**: our versatile installer walks you through the process, and [takes less than ten minutes](https://www.youtube.com/watch?v=vKWjx1AQYgs) - **Resolute**: content is blocked in _non-browser locations_, such as ad-laden mobile apps and smart TVs - **Responsive**: seamlessly speeds up the feel of everyday browsing by caching DNS queries -- **Lightweight**: runs smoothly with [minimal hardware and software requirements](https://discourse.pi-hole.net/t/hardware-software-requirements/273) +- **Lightweight**: runs smoothly with [minimal hardware and software requirements](https://docs.pi-hole.net/main/prerequisites/) - **Robust**: a command line interface that is quality assured for interoperability - **Insightful**: a beautiful responsive Web Interface dashboard to view and control your Pi-hole - **Versatile**: can optionally function as a [DHCP server](https://discourse.pi-hole.net/t/how-do-i-use-pi-holes-built-in-dhcp-server-and-why-would-i-want-to/3026), ensuring *all* your devices are protected automatically @@ -21,21 +26,17 @@ The Pi-hole[®](https://pi-hole.net/trademark-rules-and-brand-guidelines/) is a ----- -[![Codacy Badge](https://api.codacy.com/project/badge/Grade/c558a0f8d7124c99b02b84f0f5564238)](https://www.codacy.com/app/Pi-hole/pi-hole?utm_source=github.com&utm_medium=referral&utm_content=pi-hole/pi-hole&utm_campaign=Badge_Grade) -[![Build Status](https://travis-ci.org/pi-hole/pi-hole.svg?branch=development)](https://travis-ci.org/pi-hole/pi-hole) -[![BountySource](https://www.bountysource.com/badge/tracker?tracker_id=3011939)](https://www.bountysource.com/trackers/3011939-pi-hole-pi-hole?utm_source=3011939&utm_medium=shield&utm_campaign=TRACKER_BADGE) +Master [![Build Status](https://travis-ci.com/pi-hole/pi-hole.svg?branch=master)](https://travis-ci.com/pi-hole/pi-hole) Development [![Build Status](https://travis-ci.com/pi-hole/pi-hole.svg?branch=development)](https://travis-ci.com/pi-hole/pi-hole) ## One-Step Automated Install Those who want to get started quickly and conveniently may install Pi-hole using the following command: -```bash -curl -sSL https://install.pi-hole.net | bash -``` +### `curl -sSL https://install.pi-hole.net | bash` ## Alternative Install Methods -[Piping to `bash` is controversial](https://pi-hole.net/2016/07/25/curling-and-piping-to-bash), as it prevents you from [reading code that is about to run](https://github.com/pi-hole/pi-hole/blob/master/automated%20install/basic-install.sh) on your system. Therefore, we provide these alternative installation methods which allow code review before installation: +Piping to `bash` is [controversial](https://pi-hole.net/2016/07/25/curling-and-piping-to-bash), as it prevents you from [reading code that is about to run](https://github.com/pi-hole/pi-hole/blob/master/automated%20install/basic-install.sh) on your system. Therefore, we provide these alternative installation methods which allow code review before installation: ### Method 1: Clone our repository and run @@ -52,7 +53,7 @@ wget -O basic-install.sh https://install.pi-hole.net sudo bash basic-install.sh ``` -## Post-install: Make your network take advantage of Pi-hole +## [Post-install: Make your network take advantage of Pi-hole](https://docs.pi-hole.net/main/post-install/) Once the installer has been run, you will need to [configure your router to have **DHCP clients use Pi-hole as their DNS server**](https://discourse.pi-hole.net/t/how-do-i-configure-my-devices-to-use-pi-hole-as-their-dns-server/245) which ensures that all devices connecting to your network will have content blocked without any further intervention. @@ -68,22 +69,18 @@ There are many reoccurring costs involved with maintaining free, open source, an Make no mistake: **your support is absolutely vital to help keep us innovating!** -### Donations +### [Donations](https://pi-hole.net/donate) -Sending a donation using our links below is **extremely helpful** in offsetting a portion of our monthly expenses: - -- PP [Donate via PayPal](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=3J2L3Z4DHW9UY) -- BTC [Bitcoin, Bitcoin Cash, Ethereum, Litecoin](https://commerce.coinbase.com/checkout/dd304d04-f324-4a77-931b-0db61c77a41b) +Sending a donation using our Sponsor Button is **extremely helpful** in offsetting a portion of our monthly expenses: ### Alternative support -If you'd rather not [donate](https://pi-hole.net/donate/) (_which is okay!_), there are other ways you can help support us: +If you'd rather not donate (_which is okay!_), there are other ways you can help support us: - [Patreon](https://patreon.com/pihole) _Become a patron for rewards_ - [Digital Ocean](https://www.digitalocean.com/?refcode=344d234950e1) _affiliate link_ - [Stickermule](https://www.stickermule.com/unlock?ref_id=9127301701&utm_medium=link&utm_source=invite) _earn a $10 credit after your first purchase_ -- [Amazon](https://www.amazon.com/exec/obidos/redirect-home/pihole09-20) _affiliate link_ -- [DNS Made Easy](https://cp.dnsmadeeasy.com/u/133706) _affiliate link_ +- [Amazon](http://www.amazon.com/exec/obidos/redirect-home/pihole09-20) _affiliate link_ - Spreading the word about our software, and how you have benefited from it ### Contributing via GitHub @@ -94,12 +91,6 @@ If you have something to add - anything from a typo through to a whole new featu You'll find that the [install script](https://github.com/pi-hole/pi-hole/blob/master/automated%20install/basic-install.sh) and the [debug script](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/piholeDebug.sh) have an abundance of comments, which will help you better understand how Pi-hole works. They're also a valuable resource to those who want to learn how to write scripts or code a program! We encourage anyone who likes to tinker to read through it and submit a pull request for us to review. -### Presentations about Pi-hole - -Word-of-mouth continues to help our project grow immensely, and so we are helping make this easier for people. - -If you are going to be presenting Pi-hole at a conference, meetup or even a school project, [get in touch with us](https://pi-hole.net/2017/05/17/giving-a-presentation-on-pi-hole-contact-us-first-for-some-goodies-and-support/) so we can hook you up with free swag to hand out to your audience! - ----- ## Getting in touch with us @@ -107,13 +98,9 @@ If you are going to be presenting Pi-hole at a conference, meetup or even a scho While we are primarily reachable on our [Discourse User Forum](https://discourse.pi-hole.net/), we can also be found on a variety of social media outlets. **Please be sure to check the FAQ's** before starting a new discussion, as we do not have the spare time to reply to every request for assistance. - [Frequently Asked Questions](https://discourse.pi-hole.net/c/faqs) -- [Pi-hole Wiki](https://github.com/pi-hole/pi-hole/wiki) - [Feature Requests](https://discourse.pi-hole.net/c/feature-requests?order=votes) -- [Discourse User Forum](https://discourse.pi-hole.net/) - [Reddit](https://www.reddit.com/r/pihole/) -- [Twitter](https://twitter.com/The_Pi_Hole) -- [YouTube](https://www.youtube.com/channel/UCT5kq9w0wSjogzJb81C9U0w) -- [Facebook](https://www.facebook.com/ThePiHole/) +- [Twitter](https://twitter.com/The_Pi_hole) ----- @@ -121,22 +108,21 @@ While we are primarily reachable on our [Discourse User Forum](https://discourse ### The Command Line Interface -The `pihole` command has all the functionality necessary to be able to fully administer the Pi-hole, without the need of the Web Interface. It's fast, user-friendly, and auditable by anyone with an understanding of `bash`. +The [pihole](https://docs.pi-hole.net/core/pihole-command/) command has all the functionality necessary to be able to fully administer the Pi-hole, without the need of the Web Interface. It's fast, user-friendly, and auditable by anyone with an understanding of `bash`. -[![Pi-hole Blacklist Demo](https://pi-hole.github.io/graphics/Screenshots/blacklist-cli.gif)](https://pi-hole.github.io/graphics/Screenshots/blacklist-cli.gif) +![Pi-hole Blacklist Demo](https://pi-hole.github.io/graphics/Screenshots/blacklist-cli.gif) Some notable features include: -- [Whitelisting, Blacklisting and Wildcards](https://github.com/pi-hole/pi-hole/wiki/Core-Function-Breakdown#whitelisting-blacklisting-and-wildcards) -- [Debugging utility](https://github.com/pi-hole/pi-hole/wiki/Core-Function-Breakdown#debugger) -- [Viewing the live log file](https://github.com/pi-hole/pi-hole/wiki/Core-Function-Breakdown#tail) -- [Real-time Statistics via `ssh`](https://github.com/pi-hole/pi-hole/wiki/Core-Function-Breakdown#chronometer) or [your TFT LCD screen](http://www.amazon.com/exec/obidos/ASIN/B00ID39LM4/pihole09-20) -- [Updating Ad Lists](https://github.com/pi-hole/pi-hole/wiki/Core-Function-Breakdown#gravity) -- [Querying Ad Lists for blocked domains](https://github.com/pi-hole/pi-hole/wiki/Core-Function-Breakdown#query) -- [Enabling and Disabling Pi-hole](https://github.com/pi-hole/pi-hole/wiki/Core-Function-Breakdown#enable--disable) +- [Whitelisting, Blacklisting and Regex](https://docs.pi-hole.net/core/pihole-command/#whitelisting-blacklisting-and-regex) +- [Debugging utility](https://docs.pi-hole.net/core/pihole-command/#debugger) +- [Viewing the live log file](https://docs.pi-hole.net/core/pihole-command/#tail) +- [Updating Ad Lists](https://docs.pi-hole.net/core/pihole-command/#gravity) +- [Querying Ad Lists for blocked domains](https://docs.pi-hole.net/core/pihole-command/#query) +- [Enabling and Disabling Pi-hole](https://docs.pi-hole.net/core/pihole-command/#enable-disable) - ... and *many* more! -You can read our [Core Feature Breakdown](https://github.com/pi-hole/pi-hole/wiki/Core-Function-Breakdown), as well as read up on [example usage](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738) for more information. +You can read our [Core Feature Breakdown](https://docs.pi-hole.net/core/pihole-command/#pi-hole-core) for more information. ### The Web Interface Dashboard @@ -157,8 +143,8 @@ Some notable features include: There are several ways to [access the dashboard](https://discourse.pi-hole.net/t/how-do-i-access-pi-holes-dashboard-admin-interface/3168): -1. `http:///admin/` -2. `http://pi.hole/admin/` (when using Pi-hole as your DNS server) +1. `http://pi.hole/admin/` (when using Pi-hole as your DNS server) +2. `http:///admin/` 3. `http://pi.hole/` (when using Pi-hole as your DNS server) ## Faster-than-light Engine @@ -177,31 +163,3 @@ Some of the statistics you can integrate include: - Unique clients The API can be accessed via [`telnet`](https://github.com/pi-hole/FTL), the Web (`admin/api.php`) and Command Line (`pihole -c -j`). You can out find [more details over here](https://discourse.pi-hole.net/t/pi-hole-api/1863). - ------ - -## The Origin Of Pi-hole - -Pi-hole being an **advertising-aware DNS/Web server**, makes use of the following technologies: - -- [`dnsmasq`](http://www.thekelleys.org.uk/dnsmasq/doc.html) - a lightweight DNS and DHCP server -- [`curl`](https://curl.haxx.se/) - A command line tool for transferring data with URL syntax -- [`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 - -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. - ------ - -## [Coverage](https://docs.pi-hole.net/main/coverage/) - ------ - -## Pi-hole Projects - -- [The Big Blocklist Collection](https://firebog.net/) -- [Pie in the Sky-Hole](https://dlaa.me/blog/post/skyhole) -- [Copernicus: Windows Tray Application](https://github.com/goldbattle/copernicus) -- [Magic Mirror with DNS Filtering](https://zonksec.com/blog/magic-mirror-dns-filtering/#dnssoftware) -- [Windows DNS Swapper](https://github.com/roots84/DNS-Swapper) diff --git a/advanced/Scripts/pihole-reenable.sh b/advanced/Scripts/pihole-reenable.sh new file mode 100755 index 00000000..93ec3b95 --- /dev/null +++ b/advanced/Scripts/pihole-reenable.sh @@ -0,0 +1,23 @@ +#!/bin/bash +# Pi-hole: A black hole for Internet advertisements +# (c) 2020 Pi-hole, LLC (https://pi-hole.net) +# Network-wide ad blocking via your own hardware. +# +# This file is copyright under the latest version of the EUPL. +# Please see LICENSE file for your rights under this license. +# +# +# The pihole disable command has the option to set a specified time before +# blocking is automatically re-enabled. +# +# Present script is responsible for the sleep & re-enable part of the job and +# is automatically terminated if it is still running when pihole is enabled by +# other means. +# +# This ensures that pihole ends up in the correct state after a sequence of +# commands suchs as: `pihole disable 30s; pihole enable; pihole disable` + +readonly PI_HOLE_BIN_DIR="/usr/local/bin" + +sleep "${1}" +"${PI_HOLE_BIN_DIR}"/pihole enable diff --git a/advanced/Scripts/piholeDebug.sh b/advanced/Scripts/piholeDebug.sh index b88ac528..d5da57ae 100755 --- a/advanced/Scripts/piholeDebug.sh +++ b/advanced/Scripts/piholeDebug.sh @@ -1215,6 +1215,11 @@ tricorder_use_nc_or_curl() { log_write " * Using ${COL_GREEN}curl${COL_NC} for transmission." # transmit he log via TLS and store the token returned in a variable tricorder_token=$(curl --silent --upload-file ${PIHOLE_DEBUG_LOG} https://tricorder.pi-hole.net:${TRICORDER_SSL_PORT_NUMBER}) + if [ -z "${tricorder_token}" ]; then + # curl failed, fallback to nc + log_write " * ${COL_GREEN}curl${COL_NC} failed, falling back to ${COL_YELLOW}netcat${COL_NC} for transmission." + tricorder_token=$(< ${PIHOLE_DEBUG_LOG} nc tricorder.pi-hole.net ${TRICORDER_NC_PORT_NUMBER}) + fi # Otherwise, else # use net cat @@ -1257,7 +1262,7 @@ upload_to_tricorder() { # If they say yes, run our function for uploading the log [yY][eE][sS]|[yY]) tricorder_use_nc_or_curl;; # If they choose no, just exit out of the script - *) log_write " * Log will ${COL_GREEN}NOT${COL_NC} be uploaded to tricorder.";exit; + *) log_write " * Log will ${COL_GREEN}NOT${COL_NC} be uploaded to tricorder.\\n * A local copy of the debug log can be found at: ${COL_CYAN}${PIHOLE_DEBUG_LOG}${COL_NC}\\n";exit; esac fi # Check if tricorder.pi-hole.net is reachable and provide token diff --git a/automated install/basic-install.sh b/automated install/basic-install.sh index 28001831..5aa20187 100755 --- a/automated install/basic-install.sh +++ b/automated install/basic-install.sh @@ -72,8 +72,8 @@ useUpdateVars=false adlistFile="/etc/pihole/adlists.list" # Pi-hole needs an IP address; to begin, these variables are empty since we don't know what the IP is until # this script can run -IPV4_ADDRESS="" -IPV6_ADDRESS="" +IPV4_ADDRESS=${IPV4_ADDRESS} +IPV6_ADDRESS=${IPV6_ADDRESS} # By default, query logging is enabled and the dashboard is set to be installed QUERY_LOGGING=true INSTALL_WEB_INTERFACE=true diff --git a/pihole b/pihole index 065fb385..b0ba8473 100755 --- a/pihole +++ b/pihole @@ -164,7 +164,7 @@ Time: local str="Disabling blocking for ${tt} seconds" echo -e " ${INFO} ${str}..." local str="Blocking will be re-enabled in ${tt} seconds" - nohup bash -c "sleep ${tt}; ${PI_HOLE_BIN_DIR}/pihole enable" /dev/null & + nohup "${PI_HOLE_SCRIPT_DIR}"/pihole-reenable.sh ${tt} /dev/null & else local error=true fi @@ -175,7 +175,7 @@ Time: echo -e " ${INFO} ${str}..." local str="Blocking will be re-enabled in ${tt} minutes" tt=$((${tt}*60)) - nohup bash -c "sleep ${tt}; ${PI_HOLE_BIN_DIR}/pihole enable" /dev/null & + nohup "${PI_HOLE_SCRIPT_DIR}"/pihole-reenable.sh ${tt} /dev/null & else local error=true fi @@ -197,6 +197,7 @@ Time: fi else # Enable Pi-hole + killall -q pihole-reenable if grep -cq "BLOCKING_ENABLED=true" "${setupVars}"; then echo -e " ${INFO} Blocking already enabled, nothing to do" exit 0 diff --git a/supportedos.txt b/supportedos.txt index ce4986bc..1eb1fde6 100644 --- a/supportedos.txt +++ b/supportedos.txt @@ -1,5 +1,5 @@ Raspbian=9,10 -Ubuntu=16,18 +Ubuntu=16,18,20 Debian=9,10 Fedora=31,32 CentOS=7,8 \ No newline at end of file