@ -178,32 +174,13 @@ Pi-hole being a **advertising-aware DNS/Web server**, makes use of the following
* [AdminLTE Dashboard](https://github.com/almasaeed2010/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 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
- [The Big Blocklist Collection](https://wally3k.github.io)
- [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)
- [Software Engineering Daily: Interview with the creator of Pi-hole](https://softwareengineeringdaily.com/2018/05/29/pi-hole-ad-blocker-hardware-with-jacob-salmela/)
- [Bloomberg Business Week: Brotherhood of the Ad blockers](https://www.bloomberg.com/news/features/2018-05-10/inside-the-brotherhood-of-pi-hole-ad-blockers)
- [Securing DNS across all of my devices with Pi-Hole + DNS-over-HTTPS + 1.1.1.1](https://scotthelme.co.uk/securing-dns-across-all-of-my-devices-with-pihole-dns-over-https-1-1-1-1/)
- [Adafruit: installing Pi-hole on a Pi Zero W](https://learn.adafruit.com/pi-hole-ad-blocker-with-pi-zero-w/install-pi-hole)
- [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/)
@ -222,3 +199,12 @@ While quite outdated at this point, [this original blog post about Pi-hole](http
- [CryptoAUSTRALIA: How We Tried 5 Privacy Focused Raspberry Pi Projects](https://blog.cryptoaustralia.org.au/2017/10/05/5-privacy-focused-raspberry-pi-projects/)
echo -e "${INFO} FTL:\\t\\t${COL_LIGHT_GREEN}up to date${COL_NC}"
;;
2)
echo -e "${INFO} FTL:\\t\\t${COL_LIGHT_RED}Branch is not available.${COL_NC}\\n\\t\\t\\tUse ${COL_LIGHT_GREEN}pihole checkout ftl [branchname]${COL_NC} to switch to a valid branch."
;;
*)
echo -e "${INFO} FTL:\\t\\t${COL_LIGHT_RED}Something has gone wrong, contact support${COL_NC}"
echo -e "${INFO} FTL:\\t\\t${COL_LIGHT_GREEN}up to date${COL_NC}"
;;
2)
echo -e "${INFO} FTL:\\t\\t${COL_LIGHT_RED}Branch is not available.${COL_NC}\\n\\t\\t\\tUse ${COL_LIGHT_GREEN}pihole checkout ftl [branchname]${COL_NC} to switch to a valid branch."
;;
*)
echo -e "${INFO} FTL:\\t\\t${COL_LIGHT_RED}Something has gone wrong, contact support${COL_NC}"
esac
FTL_update=false
fi
if[["${core_update}"==true]];then
echo""
echo -e "${INFO} Pi-hole core files out of date, updating local repo."
die("[ERROR] There are no domain lists generated lists within <code>/etc/pihole/</code>! Please update gravity by running <code>pihole -g</code>, or repair Pi-hole using <code>pihole -r</code>.");
Pi-hole : The Faster-Than-Light (FTL) Engine is a lightweight, purpose-built daemon used to provide statistics needed for the Pi-hole Web Interface, and its API can be easily integrated into your own projects. Although it is an optional component of the Pi-hole ecosystem, it will be installed by default to provide statistics. As the name implies, FTL does its work \fIvery\fR\fIquickly\fR!
.br
Usage
.br
\fBservice pihole-FTL start\fR
.br
Start the pihole-FTL daemon
.br
\fBservice pihole-FTL stop\fR
.br
Stop the pihole-FTL daemon
.br
\fBservice pihole-FTL restart\fR
.br
If the pihole-FTP daemon is running, stop and then start, otherwise start.
.br
Command line arguments
.br
\fBdebug\fR
.br
Don't go into daemon mode (stay in foreground) + more verbose logging
.br
\fBtest\fR
.br
Start FTL and process everything, but shut down immediately afterwards
.br
\fB-v, version\fR
.br
Don't start FTL, show only version
.br
\fB-t, tag\fR
.br
Don't start FTL, show only git tag
.br
\fB-b, branch\fR
.br
Don't start FTL, show only git branch FTL was compiled from
.br
\fB-f, no-daemon\fR
.br
Don't go into background (daemon mode)
.br
\fB-h, help\fR
.br
Don't start FTL, show help
.br
\fBdnsmasq-test\fR
.br
Test resolver config file syntax
.br
\fB--\fR (options)
.br
Pass options to internal dnsmasq resolver
.br
.SH"EXAMPLE"
Command line arguments can be arbitrarily combined, e.g:
.br
\fBpihole-FTL debug test\fR
.br
Start ftl in foreground with more verbose logging, process everything and shutdown immediately
.br
.SH"SEE ALSO"
\fBpihole\fR(8), \fBpihole-FTL.conf\fR(5)
.br
.SH"COLOPHON"
Get sucked into the latest news and community activity by entering Pi-hole's orbit. Information about Pi-hole, and the latest version of the software can be found at https://pi-hole.net
For each setting, the option shown first is the default.
.br
.SH"SEE ALSO"
\fBpihole\fR(8), \fBpihole-FTL\fR(8)
.br
.SH"COLOPHON"
Pi-hole : The Faster-Than-Light (FTL) Engine is a lightweight, purpose-built daemon used to provide statistics needed for the Pi-hole Web Interface, and its API can be easily integrated into your own projects. Although it is an optional component of the Pi-hole ecosystem, it will be installed by default to provide statistics. As the name implies, FTL does its work \fIvery quickly\fR!
.br
Get sucked into the latest news and community activity by entering Pi-hole's orbit. Information about Pi-hole, and the latest version of the software can be found at https://pi-hole.net
-e, --exit Output stats and exit witout refreshing
.br
\fB-g, updateGravity\fR
.br
Update the list of ad-serving domains
.br
\fB-q, query\fR [option]
.br
Query the adlists for a specified domain
.br
(Query options):
.br
-adlist Print the name of the block list URL
.br
-exact Search the block lists for exact domain matches
.br
-all Return all query matches within a block list
.br
\fB-h, --help, help\fR
.br
Show a help dialog
.br
\fB-l, logging\fR [on|off|off noflush]
.br
Specify whether the Pi-hole log should be used
.br
(Logging options):
.br
on Enable the Pi-hole log at /var/log/pihole.log
.br
off Disable and flush the Pi-hole log at /var/log/pihole.log
.br
off noflush Disable the Pi-hole log at /var/log/pihole.log
.br
\fB-up, updatePihole\fR [--check-only]
.br
Update Pi-hole subsystems
.br
--check-only Exit script before update is performed.
.br
\fB-v, version\fR [repo] [options]
.br
Show installed versions of Pi-hole, Web Interface & FTL
.br
.br
(repo options):
.br
-p, --pihole Only retrieve info regarding Pi-hole repository
.br
-a, --admin Only retrieve info regarding AdminLTE repository
.br
-f, --ftl Only retrieve info regarding FTL repository
.br
(version options):
.br
-c, --current Return the current version
.br
-l, --latest Return the latest version
.br
--hash Return the Github hash from your local repositories
.br
\fBuninstall\fR
.br
Uninstall Pi-hole from your system
.br
\fBstatus\fR
.br
Display the running status of Pi-hole subsystems
.br
\fBenable\fR
.br
Enable Pi-hole subsystems
.br
\fBdisable\fR [time]
.br
Disable Pi-hole subsystems, optionally for a set duration
.br
(time options):
.br
#s Disable Pi-hole functionality for # second(s)
.br
#m Disable Pi-hole functionality for # minute(s)
.br
\fBrestartdns\fR
.br
Restart Pi-hole subsystems
.br
\fBcheckout\fR [repo] [branch]
.br
Switch Pi-hole subsystems to a different Github branch
.br
(repo options):
.br
core Change the branch of Pi-hole's core subsystem
.br
web Change the branch of Admin Console subsystem
.br
ftl Change the branch of Pi-hole's FTL subsystem
.br
(branch options):
.br
master Update subsystems to the latest stable release
.br
dev Update subsystems to the latest development release
.br
branchname Update subsystems to the specified branchname
.br
.SH"EXAMPLE"
Some usage examples
.br
Whitelist/blacklist manipulation
.br
\fBpihole -w iloveads.example.com\fR Add "iloveads.example.com" to whitelist
.br
\fBpihole -b -d noads.example.com\fR Remove "noads.example.com" from blacklist
.br
\fBpihole --wild example.com\fR Add example.com as a wildcard - would
block all subdomains of example.com, including example.com itself.
.br
\fBpihole --regex "ad.*\.example\.com$"\fR Add "ad.*\.example\.com$" to the regex
blacklist - would block all subdomains of example.com which start with "ad"
.br
Changing the Web Interface password
.br
\fBpihole -a -p ExamplePassword\fR Change the password to "ExamplePassword"
.br
Updating lists from internet sources
.br
\fBpihole -g\fR Update the list of ad-serving domains
.br
Displaying version information
.br
\fBpihole -v -a -c\fR Display the current version of AdminLTE
.br
Temporarily disabling Pi-hole
.br
\fBpihole disable 5m\fR Disable Pi-hole functionality for five minutes
.br
Switching Pi-hole subsystem branches
.br
\fBpihole checkout master\fR Switch to master branch
.br
\fBpihole checkout core dev\fR Switch to core development branch
.br
.SH"SEE ALSO"
\fBlighttpd\fR(8), \fBpihole-FTL\fR(8)
.br
.SH"COLOPHON"
Get sucked into the latest news and community activity by entering Pi-hole's orbit. Information about Pi-hole, and the latest version of the software can be found at https://pi-hole.net.
Make sure you have Docker and Python w/pip package manager.
From command line all you need to do is:
- `pip install tox`
- `tox`
Tox handles setting up a virtual environment for python dependancies, installing dependancies, building the docker images used by tests, and finally running tests. It's an easy way to have travis-ci like build behavior locally.
## Alternative py.test method of running tests
You're responsible for setting up your virtual env and dependancies in this situation.
```
py.test -vv -n auto -m "build_stage"
py.test -vv -n auto -m "not build_stage"
```
The build_stage tests have to run first to create the docker images, followed by the actual tests which utilize said images. Unless you're changing your dockerfiles you shouldn't have to run the build_stage every time - but it's a good idea to rebuild at least once a day in case the base Docker images or packages change.
# How do I debug python?
Highly recommended: Setup PyCharm on a **Docker enabled** machine. Having a python debugger like PyCharm changes your life if you've never used it :)