mirror of
https://github.com/pi-hole/pi-hole.git
synced 2024-12-23 21:30:17 +00:00
Update README.md
Signed-off-by: Dan Schaper <dan.schaper@pi-hole.net>
This commit is contained in:
Dan Schaper
parent
6ff0926f4a
commit
a99eac9d10
1 changed files with 27 additions and 69 deletions
96
README.md
96
README.md
|
|
@ -1,3 +1,5 @@
|
|||
<!-- markdownlint-configure-file { "MD004": { "style": "consistent" } } -->
|
||||
<!-- markdownlint-disable MD033 -->
|
||||
<p align="center">
|
||||
<a href="https://pi-hole.net/">
|
||||
<img src="https://pi-hole.github.io/graphics/Vortex/Vortex_with_Wordmark.svg" width="150" height="260" alt="Pi-hole">
|
||||
|
|
@ -5,13 +7,16 @@
|
|||
<br>
|
||||
<strong>Network-wide ad blocking via your own Linux hardware</strong>
|
||||
</p>
|
||||
<!-- markdownlint-enable MD033 -->
|
||||
|
||||
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
|
|||
|
||||
-----
|
||||
|
||||
[](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)
|
||||
[](https://travis-ci.org/pi-hole/pi-hole)
|
||||
[](https://www.bountysource.com/trackers/3011939-pi-hole-pi-hole?utm_source=3011939&utm_medium=shield&utm_campaign=TRACKER_BADGE)
|
||||
Master [](https://travis-ci.com/pi-hole/pi-hole) 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:
|
||||
|
||||
- <img src="https://pi-hole.github.io/graphics/Badges/paypal-badge-black.svg" width="24" height="24" alt="PP"> [Donate via PayPal](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=3J2L3Z4DHW9UY)
|
||||
- <img src="https://pi-hole.github.io/graphics/Badges/bitcoin-badge-black.svg" width="24" height="24" alt="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`.
|
||||
|
||||
[](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://<IP_ADDPRESS_OF_YOUR_PI_HOLE>/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://<IP_ADDPRESS_OF_YOUR_PI_HOLE>/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)
|
||||
|
|
|
|||
Loading…
Reference in a new issue