diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e32b500e..6992cce5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,7 +32,7 @@ When requesting or submitting new features, first consider whether it might be u - Submit Pull Requests to the **development branch only**. - Before Submitting your Pull Request, merge `development` with your new branch and fix any conflicts. (Make sure you don't break anything in development!) -- Please use the [Google Style Guide for Shell](https://google.github.io/styleguide/shell.xml) for your code submission styles. +- Please use the [Google Style Guide for Shell](https://google.github.io/styleguide/shell.xml) for your code submission styles. - Commit Unix line endings. - Please use the Pi-hole brand: **Pi-hole** (Take a special look at the capitalized 'P' and a low 'h' with a hyphen) - (Optional fun) keep to the theme of Star Trek/black holes/gravity. diff --git a/README.md b/README.md index 3613321f..92bb76ea 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,9 @@

-Pi-hole
-Network-wide ad blocking via your own Linux hardware
+ + Pi-hole + +
+ 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. @@ -17,27 +20,34 @@ The Pi-hole[®](https://pi-hole.net/trademark-rules-and-brand-guidelines/) is a - **Free**: open source software which helps ensure _you_ are the sole person in control of your privacy ----- + [![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) ## One-Step Automated Install + Those who want to get started quickly and conveniently may install Pi-hole using the following command: -#### `curl -sSL https://install.pi-hole.net | bash` +```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: ### Method 1: Clone our repository and run -``` + +```bash git clone --depth 1 https://github.com/pi-hole/pi-hole.git Pi-hole cd "Pi-hole/automated install/" sudo bash basic-install.sh ``` ### Method 2: Manually download the installer and run -``` + +```bash wget -O basic-install.sh https://install.pi-hole.net sudo bash basic-install.sh ``` @@ -53,18 +63,22 @@ As a last resort, you can always manually set each device to use Pi-hole as thei ----- ## Pi-hole is free, but powered by your support + There are many reoccurring costs involved with maintaining free, open source, and privacy-respecting software; expenses which [our volunteer developers](https://github.com/orgs/pi-hole/people) pitch in to cover out-of-pocket. This is just one example of how strongly we feel about our software, as well as the importance of keeping it maintained. Make no mistake: **your support is absolutely vital to help keep us innovating!** ### Donations + Sending a donation using our links below is **extremely helpful** in offsetting a portion of our monthly expenses: -- PP Donate via PayPal
-- BTC [Bitcoin, Bitcoin Cash, Ethereum, Litecoin](https://commerce.coinbase.com/checkout/dd304d04-f324-4a77-931b-0db61c77a41b) +- 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) ### 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: + - [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_ @@ -73,6 +87,7 @@ If you'd rather not [donate](https://pi-hole.net/donate/) (_which is okay!_), th - Spreading the word about our software, and how you have benefited from it ### Contributing via GitHub + We welcome _everyone_ to contribute to issue reports, suggest new features, and create pull requests. If you have something to add - anything from a typo through to a whole new feature, we're happy to check it out! Just make sure to fill out our template when submitting your request; the questions that it asks will help the volunteers quickly understand what you're aiming to achieve. @@ -80,6 +95,7 @@ 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! @@ -87,53 +103,57 @@ If you are going to be presenting Pi-hole at a conference, meetup or even a scho ----- ## Getting in touch with us -While we are primarily reachable on our Discourse User Forum, we can also be found on a variety of social media outlets. **Please be sure to check the FAQ's** before starting a new discussion, as we do not have the spare time to reply to every request for assistance. - +While we are primarily reachable on our [Discourse User Forum](https://discourse.pi-hole.net/), we can also be found on a variety of social media outlets. **Please be sure to check the FAQ's** before starting a new discussion, as we do not have the spare time to reply to every request for assistance. + +- [Frequently Asked Questions](https://discourse.pi-hole.net/c/faqs) +- [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/) ----- ## Breakdown of Features + ### 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`. -Pi-hole Blacklist Demo +[![Pi-hole Blacklist Demo](https://pi-hole.github.io/graphics/Screenshots/blacklist-cli.gif)](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) -* ... and *many* more! + +- [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) +- ... 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. ### The Web Interface Dashboard + This [optional dashboard](https://github.com/pi-hole/AdminLTE) allows you to view stats, change settings, and configure your Pi-hole. It's the power of the Command Line Interface, with none of the learning curve! -Pi-hole Dashboard +![Pi-hole Dashboard](https://pi-hole.github.io/graphics/Screenshots/pihole-dashboard.png) Some notable features include: -* Mobile friendly interface -* Password protection -* Detailed graphs and doughnut charts -* Top lists of domains and clients -* A filterable and sortable query log -* Long Term Statistics to view data over user-defined time ranges -* The ability to easily manage and configure Pi-hole features -* ... and all the main features of the Command Line Interface! + +- Mobile friendly interface +- Password protection +- Detailed graphs and doughnut charts +- Top lists of domains and clients +- A filterable and sortable query log +- Long Term Statistics to view data over user-defined time ranges +- The ability to easily manage and configure Pi-hole features +- ... and all the main features of the Command Line Interface! There are several ways to [access the dashboard](https://discourse.pi-hole.net/t/how-do-i-access-pi-holes-dashboard-admin-interface/3168): @@ -142,30 +162,33 @@ There are several ways to [access the dashboard](https://discourse.pi-hole.net/t 3. `http://pi.hole/` (when using Pi-hole as your DNS server) ## Faster-than-light Engine + FTLDNS is a lightweight, purpose-built daemon used to provide statistics needed for the Web Interface, and its API can be easily integrated into your own projects. As the name implies, FTLDNS does this all *very quickly*! Some of the statistics you can integrate include: -* Total number of domains being blocked -* Total number of DNS queries today -* Total number of ads blocked today -* Percentage of ads blocked -* Unique domains -* Queries forwarded (to your chosen upstream DNS server) -* Queries cached -* Unique clients + +- Total number of domains being blocked +- Total number of DNS queries today +- Total number of ads blocked today +- Percentage of ads blocked +- Unique domains +- Queries forwarded (to your chosen upstream DNS server) +- Queries cached +- 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 +- [`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.