mirror of
https://github.com/pi-hole/pi-hole.git
synced 2024-12-25 14:20:18 +00:00
190 lines
14 KiB
Markdown
190 lines
14 KiB
Markdown
<p align="center">
|
|
<a href="https://pi-hole.net"><img src="https://camo.githubusercontent.com/578cfb146b0bb867e3609c5581761cf0b845b527/68747470733a2f2f66697265626f672e6e65742f566f72746578322e706e67" width="150" height="255"></a><br/>
|
|
<b>Network-wide ad blocking via your own Linux hardware</b>
|
|
</p>
|
|
|
|
The Pi-hole blocks ads via a [DNS sinkhole](https://en.wikipedia.org/wiki/DNS_Sinkhole), so all your devices are protected without the need to install 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**: ads are blocked in _non-browser locations_ such as ad-laden mobile apps and smart TVs
|
|
- **Fast**: speeds up the feel of everyday browsing by caching DNS queries, saving bandwidth
|
|
- **Lightweight**: runs smoothly and requires [minimal resources](https://discourse.pi-hole.net/t/hardware-software-requirements/273)
|
|
- **Robust**: a command line interface for those preferring CLI, and/or wanting to automate tasks
|
|
- **Informative**: a beautiful and secure Web Interface dashboard to control your Pi-hole
|
|
- **Versatile**: can optionally function as a DHCP server, ensuring your devices will not need configuring individually
|
|
- **Scalable**: [capable of handling hundreds of millions of queries](https://pi-hole.net/2017/05/24/how-much-traffic-can-pi-hole-handle/) when installed on powerful hardware
|
|
- **Modern**: blocks ads over both IPv4 and IPv6
|
|
- **Free**: open source software which helps ensure _you_ are the sole person in control of your privacy
|
|
|
|
-----
|
|
<a href="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"><img src="https://api.codacy.com/project/badge/Grade/c558a0f8d7124c99b02b84f0f5564238"/></a>
|
|
<a href="https://travis-ci.org/pi-hole/pi-hole"><img src="https://travis-ci.org/pi-hole/pi-hole.svg?branch=development"/></a>
|
|
<a href="https://www.bountysource.com/trackers/3011939-pi-hole-pi-hole?utm_source=3011939&utm_medium=shield&utm_campaign=TRACKER_BADGE"><img src="https://www.bountysource.com/badge/tracker?tracker_id=3011939"/></a>
|
|
|
|
## One-Step Automated Install
|
|
1. Install a [supported operating system](https://discourse.pi-hole.net/t/hardware-software-requirements/273/1)
|
|
2. Run the following command
|
|
|
|
#### `curl -sSL https://install.pi-hole.net | bash`
|
|
|
|
## Alternative Install Methods
|
|
[Piping to `bash` _can_ be dangerous](https://pi-hole.net/2016/07/25/curling-and-piping-to-bash/), so we understand the importance of giving people the option to review our code! Our installer is [found here](https://github.com/pi-hole/pi-hole/blob/master/automated%20install/basic-install.sh), if you wish to read it before running.
|
|
|
|
You can install Pi-hole via one of the two alternative methods:
|
|
|
|
### Clone our repository and run the automated installer from your device
|
|
```
|
|
git clone --depth 1 https://github.com/pi-hole/pi-hole.git Pi-hole
|
|
cd "Pi-hole/automated install/"
|
|
bash basic-install.sh
|
|
```
|
|
|
|
### Manually download and execute the install file
|
|
```
|
|
wget -O basic-install.sh https://install.pi-hole.net
|
|
bash basic-install.sh
|
|
```
|
|
|
|
## Post-install: Make your network take advantage of Pi-hole
|
|
|
|
Once the installer has been run, you will need to [configure your router to have **DHCP clients use the 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) so that any device that connects to your network will have ads blocked without any further intervention.
|
|
|
|
If your router does not support setting the DNS server, you can [use Pi-hole's built in 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); just be sure to disable DHCP on your router first (if it has that feature available).
|
|
|
|
As a last resort, you can always manually set each device to use Pi-hole as their DNS server.
|
|
|
|
-----
|
|
|
|
## 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 volunteers](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:
|
|
|
|
-  [Donate via PayPal](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=3J2L3Z4DHW9UY)
|
|
-  1GKnevUnVaQM2pQieMyeHkpr8DXfkpfAtL
|
|
|
|
### Alternative support
|
|
If you'd rather not donate (_which is okay!_), there are other ways you can help support us:
|
|
|
|
- [Digital Ocean](http://www.digitalocean.com/?refcode=344d234950e1) affiliate link
|
|
- [Vultr](http://www.vultr.com/?ref=7190426) affiliate link
|
|
- [UNIXstickers.com](http://unixstickers.refr.cc/jacobs) affiliate link
|
|
- [Pi-hole Swag Store](https://pi-hole.net/shop/)
|
|
- 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.
|
|
|
|
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 we'd like to help those who are going to be presenting Pi-hole at a conference, meetup or even a school project. If you'd like some free swag to hand out to your audience, [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/).
|
|
|
|
-----
|
|
|
|
## Getting in touch with us
|
|
- [Users Forum](https://discourse.pi-hole.net/)
|
|
- [Feature requests](https://discourse.pi-hole.net/c/feature-requests?order=votes)
|
|
- [FAQs](https://discourse.pi-hole.net/c/faqs)
|
|
- [Wiki](https://github.com/pi-hole/pi-hole/wiki)
|
|
- [/r/pihole on Reddit](https://www.reddit.com/r/pihole/)
|
|
- [@The_Pi_Hole on Twitter](https://twitter.com/The_Pi_Hole)
|
|
- [Pi-hole on YouTube](https://www.youtube.com/channel/UCT5kq9w0wSjogzJb81C9U0w)
|
|
- [ThePiHole on Facebook](https://www.facebook.com/ThePiHole/)
|
|
- [Chat on Gitter](https://gitter.im/pi-hole/pi-hole)
|
|
|
|
-----
|
|
|
|
## Breakdown Of Features
|
|
### The Command Line Interface
|
|
The `pihole` command has all the functionality necessary to be able to fully administer the Pi-hole.
|
|
|
|
<a href="https://assets.pi-hole.net/static/ASCII-Vortex.png"><img src="https://camo.githubusercontent.com/822cc9cac2a7b6b9eacc0874e098119186db10ec/68747470733a2f2f66697265626f672e6e65742f41534349492d4c6f676f2e706e67" width="200" height="280" alt="Pi-hole ASCII Logo"/></a>
|
|
|
|
Some of the 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](https://www.amazon.com/gp/product/B01HN0LL2A/ref=as_li_qf_sp_asin_il_tl?ie=UTF8&tag=pihole09-20&camp=1789&creative=9325&linkCode=as2&creativeASIN=B01HN0LL2A&linkId=fb33e9efb10c1daba0dd1dd9fea72b1a)
|
|
* [Updating Ad Lists](https://github.com/pi-hole/pi-hole/wiki/Core-Function-Breakdown#gravity)
|
|
* [Querying Ad Lists for matching 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!
|
|
|
|
<a href="https://assets.pi-hole.net/static/dashboard.png"><img src="https://camo.githubusercontent.com/313742e96fc7dee581e77b8c7eff1e4c078024ee/68747470733a2f2f66697265626f672e6e65742f44617368626f6172642e706e67" width="888" height="522" alt="Pi-hole Dashboard"/></a>
|
|
|
|
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://<IP_ADDPRESS_OF_YOUR_PI_HOLE>/admin/`
|
|
2. `http:/pi.hole/admin/` (when using Pi-hole as your DNS server)
|
|
3. `http://pi.hole/` (when using Pi-hole as your DNS server)
|
|
|
|
## The Faster-Than-Light Engine
|
|
The [FTL Engine](https://github.com/pi-hole/FTL) 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, FTL 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 (served by Pi-hole)
|
|
* Unique Pi-hole 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`). [More details are found here](https://discourse.pi-hole.net/t/pi-hole-api/1863).
|
|
|
|
-----
|
|
|
|
## The Origin Of Pi-hole
|
|
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 setup 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.
|
|
|
|
-----
|
|
|
|
## Pi-hole Projects
|
|
- [Docker Pi-hole container (x86 and ARM)](https://hub.docker.com/r/diginc/pi-hole/)
|
|
- [Pi-Hole in the cloud](http://blog.codybunch.com/2015/07/28/Pi-Hole-in-the-cloud/)
|
|
- [Pie in the Sky-Hole [A Pi-Hole in the cloud for ad-blocking via DNS]](https://dlaa.me/blog/post/skyhole)
|
|
- [Pi-hole Enable/Disable Button](http://thetimmy.silvernight.org/pages/endisbutton/)
|
|
- [Minibian Pi-hole](https://munkjensen.net/wiki/index.php/See_my_Pi-Hole#Minibian_Pi-hole)
|
|
- [CHiP-hole: Network-wide Ad-blocker](https://www.hackster.io/jacobsalmela/chip-hole-network-wide-ad-blocker-98e037)
|
|
- [Chrome Extension: Pi-Hole List Editor](https://chrome.google.com/webstore/detail/pi-hole-list-editor/hlnoeoejkllgkjbnnnhfolapllcnaglh) ([Source Code](https://github.com/packtloss/pihole-extension))
|
|
- [Splunk: Pi-hole Visualiser](https://splunkbase.splunk.com/app/3023/)
|
|
- [Adblocking with P-hole and Ubuntu 14.04 on VirtualBox](https://hbalagtas.blogspot.com.au/2016/02/adblocking-with-pi-hole-and-ubuntu-1404.html)
|
|
- [Pi-hole stats in your Mac's menu bar](https://getbitbar.com/plugins/Network/pi-hole.1m.py)
|
|
- [Pi-hole unRAID Template](https://forums.lime-technology.com/topic/36810-support-spants-nodered-mqtt-dashing-couchdb/)
|
|
- [Copernicus: Windows Tray Application](https://github.com/goldbattle/copernicus)
|
|
- [Let your blink1 device blink when Pi-hole filters ads](https://gist.github.com/elpatron68/ec0b4c582e5abf604885ac1e068d233f)
|
|
- [Pi-hole metrics](https://github.com/nlamirault/pihole_exporter) exporter for [Prometheus](https://prometheus.io/)
|
|
- [Magic Mirror with DNS Filtering](https://zonksec.com/blog/magic-mirror-dns-filtering/#dnssoftware)
|
|
- [Pi-hole Droid: Android client](https://github.com/friimaind/pi-hole-droid)
|
|
|
|
-----
|
|
|
|
## Coverage
|
|
- [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/)
|
|
- [MakeUseOf: Adblock Everywhere: The Raspberry Pi-Hole Way](http://www.makeuseof.com/tag/adblock-everywhere-raspberry-pi-hole-way/)
|
|
- [Catchpoint: Ad-Blocking on Apple iOS9: Valuing the End User Experience](http://blog.catchpoint.com/2015/09/14/ad-blocking-apple/)
|
|
- [Security Now Netcast: Pi-hole](https://www.youtube.com/watch?v=p7-osq_y8i8&t=100m26s)
|
|
- [TekThing: Raspberry Pi-Hole Makes Ads Disappear!](https://youtu.be/8Co59HU2gY0?t=2m)
|
|
- [Foolish Tech Show](https://youtu.be/bYyena0I9yc?t=2m4s)
|
|
- [Block Ads on All Home Devices for $53.18](https://medium.com/@robleathern/block-ads-on-all-home-devices-for-53-18-a5f1ec139693#.gj1xpgr5d)
|
|
- [Pi-Hole for Ubuntu 14.04](http://www.boyter.org/2015/12/pi-hole-ubuntu-14-04/)
|
|
- [MacObserver Podcast 585](https://www.macobserver.com/tmo/podcast/macgeekgab-585)
|
|
- [The Defrag Show: Endoscope USB Camera, The Final [HoloLens] Vote, Adblock Pi and more](https://channel9.msdn.com/Shows/The-Defrag-Show/Defrag-Endoscope-USB-Camera-The-Final-HoloLens-Vote-Adblock-Pi-and-more?WT.mc_id=dlvr_twitter_ch9#time=20m39s)
|
|
- [Adafruit: Pi-hole is a black hole for internet ads](https://blog.adafruit.com/2016/03/04/pi-hole-is-a-black-hole-for-internet-ads-piday-raspberrypi-raspberry_pi/)
|
|
- [Digital Trends: 5 Fun, Easy Projects You Can Try With a $35 Raspberry Pi](https://youtu.be/QwrKlyC2kdM?t=1m42s)
|
|
- [Adafruit: Raspberry Pi Quick Look at Pi Hole ad blocking server with Tony D](https://www.youtube.com/watch?v=eg4u2j1HYlI)
|
|
- [Devacron: OrangePi Zero as an Ad-Block server with Pi-Hole](http://www.devacron.com/orangepi-zero-as-an-ad-block-server-with-pi-hole/)
|
|
- [CryptoAUSTRALIA Blog: How We Tried 5 Privacy Focused Raspberry Pi Projects](https://blog.cryptoaustralia.org.au/2017/10/05/5-privacy-focused-raspberry-pi-projects/)
|
|
- [CryptoAUSTRALIA Pi-hole Workshop](https://blog.cryptoaustralia.org.au/2017/11/02/pi-hole-network-wide-ad-blocker/)
|