With a very minor code change, individuals can now implement restrictions on dangers, disturbing, or otherwise adult oriented content without the need for managed restrictions.
This is a fairly non-invasive change and will benefit users who intend to use VPN for home or small business uses where access to such material may be undesirable.
Signed-off-by: Vasilis Gerakaris <vgerak@gmail.com>
**By submitting this pull request, I confirm the following:**
`{please fill any appropriate checkboxes, e.g: [X]}`
- [x] I have read and understood the [contributors guide](https://github.com/pi-hole/pi-hole/blob/master/CONTRIBUTING.md), as well as this entire template.
- [x] I have made only one major change in my proposed changes.
- [] I have commented my proposed changes within the code.
- [] I have tested my proposed changes, and have included unit tests where possible.
- [] I am willing to help maintain this change if there are issues with it later.
- [x] I give this submission freely and claim no ownership.
- [x] It is compatible with the [EUPL 1.2 license](https://opensource.org/licenses/EUPL-1.1)
- [x] I have squashed any insignificant commits. ([`git rebase`](http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html))
This change makes pihole more friendly to the non-existence of the pihole.log file. This can help with systems that are configured to mount /var/log as a tmpfs volume. It may also help with systems where the pihole.log file is accidentally/unintentionally removed.
Further discussion around the details of this change are in https://github.com/pi-hole/pi-hole/issues/1798
* Running as sudo/root prevents script from being re-downloaded, unintentionally side-stepping manual code review by end user
Signed off by WaLLy3K <wally3k@pi-hole.net>
* Round $cpu_mhz to 1 decimal place
* Remove ".0" from $cpu_freq
* Silence non-numeric domains_being_blocked output
* Use "Core" and "Web" as appropriate
Signed off by WaLLy3K <wally3k@pi-hole.net>
* Core shows a list of common commands, linking to the new Core Function Breakdown wiki article
* Core also now shows the ASCII Vortex
* Web has had its preview image size reduced
* FTL's functions are elaborated upon more
* Move Codacy/Build/BountySource badges underneath the H1 header
* Use updated vector logo (Matches the new Pi-hole stickers!)
* Tweak wording for Versatile
* Quote `cd` path instead of escaping string
* Order Projects and Coverage in order of publish date
* Use the current published title for Projects/Coverage links
* Change Projects/Coverage links to use HTTPS if the server supports TLS
Signed off by WaLLy3K <wally3k@pi-hole.net>
* Use inverse if statement, instead of IF/ELSE when checking setupVars.conf
* Remove $svFQDN
* Add or elaborate on more comments
* Add $serverName to $authorizedHosts if admin has specified `setenv.add-environment = ("fqdn" => "true")` within lighttpd's external.conf
* e.g: `$HTTP["host"] == "pihole.domain.com" { setenv.add-environment = ("fqdn" => "true") }`
* Move "No exact results" check to top of exception handling
* Remove unnecessary IF/ELSE when handling $queryAds error
Signed off by WaLLy3K <wally3k@pi-hole.net>
* Redirect `grep` correctly to $sources (instead of using `awk`)
* Redirect $sourceDomains correctly
* Replace use of ${COL_LIGHT_BLUE}
* Add numeric count informing user of unique source domains being whitelisted
* Add 504 status (Gateway connection timed out)
* Add text for non-standard list parsing
* Improve adblock parsing
* Ensure adblock exception rules are removed from file
* Ensure "www." is not treated as a URL-format list
* Corrected typo
* Ensure script does not fail if "-f" is used when there are no blocklists generated
Signed off by WaLLy3K <wally3k@pi-hole.net>
* Validate modified code using Shellcheck & Strict Bash
* Added and/or elaborated more comments
* scanlist() should exit if /etc/pihole is not available
* Add `export LC_CTYPE=C` to prevent extreme grep slowdown
* Consider "domain.com#comment" an exact match
* Add specialised wildcard searching grep
* Optimise and simplify queryFunc() for readability
* Replace IDN `python` parsing with `idn2`, as `python` is not guaranteed to be available
* Use ${COL_BOLD} when printing filenames
If Pi-Hole is behind a reverse proxy that uses SSL, then the block page will not load resources such as `blockingpage.css` and `jquery.min.js` as the insecure `http://` is hard coded. Browsers will block attempts to load insecure resources if the page is loaded of SSL.
The fix is acheived by checking `$_SERVER['HTTPS']` and setting the variable `$proto` to either `http` or `https`. The harcoded `http` is replaced by the contents of this variable.
* Remove WHITELIST_COMMAND
* Place IPv4/IPv6 availability test underneath setupVars.conf source
* Improved clarity on comments
* Define default lookupDomain on local line
* Use `getent hosts` instead of nslookup (faster)
* Make gravity_DNSLookup() function more readable
* Use bold on "Neutrino emissions detected"
* Swap conditionals around on adlists file handling
* Add comments to both gravity_Collapse() `awk`s
* Removed unnecessary "${str}" from gravity_Pull()
* Merge function variables into local line
* Place .phgbp suffice on mktemp, so patternbuffers can be cleaned up all at once in gravity_Cleanup()
* Removed success="false" from $httpCode case, placed empty success var in local
* Reordered $httpCode case numerically because I can
* Provide error if Dnsmasq format list is being parsed
* Remove IPv4 check when determining URL list (too slow on large lists)
* Check ${#sources[@]} to ensure we're checking the number of entries and not the character count
* Define empty plural in local line, removing unnecessary plural=;
* Optimised readability of gravity_Whitelist()
* Removed uninformative "Nothing to blacklist"/"No wildcards used" text
* Optimised parsing of domains into hosts format on IPv6 enabled servers
* Ensure /etc/hostname is non-zero
* Use `: >` instead of `rm` as consistent with the rest of the script
* Ensured that gravity_Cleanup() removes ${localList}.tmp
* Optimised readability of gravity_ParseUserDomains()
* Moved dnsRestart to ${var} case statement, renaming it to dnsRestartType for readability
* Set default $listType to ensure script passes "bash strict mode"
* Shift default dnsRestart value into unset default parameter expansion value
* Change nslookup timeout to 5 seconds
* Use &> instead of >
* Standardise plural code
* Update some comments
* Add "000" when connection is refused
* Condense adblock detection logic
* Add Dnsmasq format detection and parsing logic
* Removed unnecessary echo
* Add dnsWasOffline variable to ensure that if DNS service has been stopped, that it doesn't start and also get reloaded
* Merge development OpenVPN code
* Determine which domain to resolve depending on existence of $localList
* Re-add code to remove $localList, preventing duplicate local entries
* Minor shellcheck validation fix
Domains with caps pass off as unique. It is necessary for proper duplicate removal.
Example:
::: /etc/pihole/list.preEventHorizon (2 results)
adsatt.abcnews.starwave.com
Adsatt.ABCNews.starwave.com
* Comment file for review-ability
* Add BOLD and UNDERLINE options
* Select most readable colours out of LIGHT/DARK options
* Provide empty variables for `set -u`
* Deprecate unnecessary variables
* Correct colours for TICK/CROSS/DONE
* Escape r twice and add ESC to OVER
* Make colfile readonly, and use path of PI_HOLE_SCRIPT_DIR
* Rename piholeStatus function to statusFunc for function name consistency
* Replace superseded netstat command with nc
* Perform addn-hosts check using a single grep subshell
* Add/update code comments
* Change resolver check to test for pi.hole
* Make resolver check timeout after 10 seconds
* Use > instead of &> where appropriate
* Make resolver check sleep for 30 seconds (effectively waiting up to 50s for dnsmasq to be resolvable)
* Provide confirmation upon success of resolver check availability
* Quotes and Braced remaining variables as appropriate
* Removed duplicate local
* Changed supernova/eventHorizon variables to match their purpose
* Add gravity_DNSLookup() function
* Ensure all comments are clear and relevant
* Use && instead of || in gravity_Collapse()
* Renamed existing functions, and placed them in order of script execution
* Use \t instead of literal tab in gravity_ParseFileIntoDomains()
* Replace instances of "truncate" with : > (e.g: gravity_Schwarzschild())
* Ensure correct variables are local'd
* Use phrase "Cleaning up stray matter" when gravity_Cleanup() is called
* Add black/white/wildcard switches for list.sh
* Ensure necessary functions are called when modifying black/white/wildcards
Signed-off-by: WaLLy3K <wally3k@pi-hole.net>
* Optimise $validDomain function by using bashism and `grep`
* Add black/white/wildcard variables to pass to Reload()
* Revert reload variable behaviour
* Ensure Reload() function passes correct options to gravity.sh
Signed-off-by: WaLLy3K <wally3k@pi-hole.net>
* Print newline on error message
* Output last three lines of error if update fails
* Consistent error messages & housekeeping
* Add shellcheck directive to ignore COL_TABLE
* Quoted and braced variables for codebase consistency
* Escaped newlines correctly
* Made error messages consistent (indenting and wording)
* Removed consecutive echos
* Conditional formatting consistency
* Braced, quoted and used [[ on conditionals
* Fix specific ShellCheck issues
* Fixed issues that could be safely changed without extensive testing
* Update SELinux whiptail behaviour & more
* Colourised some strings
* Fixed multiple line string indenting
* Made output consistent with existing codebase
* Removed sequential echos
* Make SELinux whiptail use "--defaultno", and change text wording
* Add help text for hostrecord, and colourise output
* this should fix the tests...
Signed-off-by: Adam Warner <adamw@rner.email>
* revert changes to `update_package_cache()` to prove tests
Signed-off-by: Adam Warner <adamw@rner.email>
* Always process DNS and DHCP settings in installer
* Make sure dnsmasq config exists before modifying it
Signed-off-by: Mcat12 <newtoncat12@yahoo.com>
* Make sure the dnsmasq config directory exists
Signed-off-by: Mcat12 <newtoncat12@yahoo.com>
* Only remove the DHCP config if it exists (fixes tests, hopefully)
Signed-off-by: Mcat12 <newtoncat12@yahoo.com>
* Always process DNS and DHCP settings in installer
* change where finalExports is called and where LIGHTTPD_ENABLED is set.
Signed-off-by: Adam Warner <adamw@rner.email>
* this may or may not work. If it does, can be functionised to reduce code duping
Signed-off-by: Adam Warner <adamw@rner.email>
* This will fix the tests, but break the patch
Signed-off-by: Adam Warner <adamw@rner.email>
* Fix queryFunc if adlists URLs have been removed
* Allow for -adlists command line switch (where the "s" is a typo)
* Add error message when unable to find associated adlists URL
* Provide PR fix on current dev version
* Add blResult variable for white/black match
* Supporting Block Page queryFunc fixes
* Re-add unmerged lines
* Provide correct FTL stats
* Use the correct lines in the array when displaying FTL stats
* Treat ads_blocked_today/dns_queries_today as currency, like domains_being_blocked is on large screens
* Chronometer Shellcheck validation
* Remove unnecessary \ from CPU usage readout
* Add "--blacklist-only" to only run essential gravity functions
* Pass "--wildcard" option to `gravity.sh` to ensure dnsmasq is restarted
Signed-off-by: WaLLy3K <wally3k@pi-hole.net>
* Shellcheck validation
* Made variable names, function names, comments and output clearer to understand
* Quoted and braced variables and conditionals
* Fix adlists.list handling logic, and remove any CR line endings
* Make CP/MV/RM provide user-friendly output upon failure
* Change adlists.list retrieval logic
* Moved and fixed adlists.list domain parsing logic
* Create gravity_ParseFileAsDomains() function to handle parsing of source files
* If no changes to a list is detected, print no output
* Ensure each source blocklist has a final newline
* Format number output as currency
* Make array of adlists domain sources unique to prevent redundant whitelisting
* Merged bash IPv4/IPv6 hosts formatting IF statement into an awk one-liner
* Trap Ctrl-C cancellations and run gravity_Cleanup()
* Use new gravity_Cleanup() function on errors and script completion
* Ensure that dnsmasq uses force-reload when gravity is invoked
* Add --wildcard option to ensure dnsmasq is restarted upon b/wlisting of a wildcard
Signed-off-by: WaLLy3K <wally3k@pi-hole.net>
* Do not activate disabled lighttpd upon update
* Fixes#1362
* Use systemctl when available
* Move `finalexports` to the very end of the install script
set value of LIGHTTPD_ENABLED to 1 or 0 depending on whether or not lighttpd is enabled or disabled.
actually save LIGHTTPD_ENABLED value to setupvars.conf
Signed-off-by: Adam Warner <adamw@rner.email>
* add [[ -z "${LIGHTTPD_ENABLED}" ]] back in!
Signed-off-by: Adam Warner <adamw@rner.email>
* Ensure "Loaded:" is the line being checked
* Colourise disabled lighttpd message
* Prevent disabled lighttpd triggering error
* change of plan, don't need that [[ -z "${LIGHTTPD_ENABLED}" ]]
Signed-off-by: Adam Warner <adamw@rner.email>
* Only attempt to install FTL if branch was found
* ~~corebranches~~ webbranches (web branches now actually listed)
Signed-off-by: Adam Warner <adamw@rner.email>
* User-friendly queryFunc() output
* Silence grep errors
* Provide 'pihole -q -h' help output
* Rewrite option handling
* Loop through grep stdout to make query output user friendly
* Add -adlist option to show block list URL instead of internal file name
* Limit general searches to 10 matches per block list
* Add -all option to override 10 match limit
* Fixed 'pihole -h' wording
* Further query optimisations
* Optimised scanList() output by switching folder
* Re-added processWildcards() function
* Added "-bp" exact matching option for use with block page
* Standardised query output
* Separated wildcard search from blacklist/whitelist search
* Optimised sorting by sorting glob output and not scanList() output
* Fixed result skipping
* Add text for wildcard result on exact query
* Fix wildcard result output
* Multiple wildcard matches on exact query could cause unexpected output
* Remove unnecessary replacement
* Make grep only output matching text
* HOSTS format lists will also output the IP address
* That substitution was necessary
* Remove IP address from HOSTS format lists
* Filter unwanted content
* Add /dev/null to grep, to always print file name (even when searching only one block list)
* Use three seds to remove unwanted content from block lists
* Merge with development
* Simplify queryFunc code
`shellcheck -x` for following files.
Do not test for included files SC1091
Signed-off-by: Dan Schaper <dan.schaper@pi-hole.net>
Signed-off-by: Adam Warner <adamw@rner.email>
# Conflicts:
# advanced/Scripts/update.sh
* check for CIDR notation when comparing IPv6 address to that found in setupVars.conf
* highlight bad address entries in pihole.log and reference a corresponding FAQ
* show header output if Pi-holes x-header does not match
* fix automated mode when running from the dashboard. It would previously not automatically upload and generate a token.
* show disclaimer message
* undocumented feature for now: obfuscate domains in pihole.log so they are not visible when sent to the Pi-hole developers. We need to make an additonal flag for this in the pihole command. if the variable OBFUSCATE has a value, it will replace the domain in the log with a placeholder value
* fix small typo in the disclaimer
This will probably break some tests. I'll work that out in a bit
Signed-off-by: Adam Warner <adamw@rner.email>
Signed-off-by: Adam Warner <adamw@rner.email>
* Colourise tailFunc
* Strip month, day number and dnsmasq[PID]
* Blocked domains show as light red
* Queries show as standard colour
* Everything else as dark gray
* Change tailFunc highlighted lines
* Highlight Blocked/Blacklist/Wildcard lines as red
* Make DHCP lines default colour
* Make sure tailFunc doesn't match on domain names
* Define colours within COL_TABLE
* Do not output colours for non-terminal instances
* Removed ":::"
* Fixed indenting & spacing
* Made output consistent throughout project
* Reworded text to fit on standard 80 char wide Terminal screen
* Made 'sudo raspi-config' warning (insufficient disk space) only show on RPi
* Make "Installation/Update Complete" the final msg
* Remove redundant messages
* Simplify update available message
* Confirm user would like to begin uninstall
* If "git pull" string says "Already up-to-date.", place [i] before it
* Colour Temp/Interface output
* Made `pihole disable 5z` invalid
* Added error fallback if invalid argument (not s/m) is detected
* Quoted "$2" for consistency
* Updated help text
* L185/286: Replaced echo with redirect
* User agents for adblock.mahakala.is/adaway.org unnecessary
* Print newline on confirmation of repository reset
* Add output to admin-related dnsmasq restarts
* Return error message for "pihole -q"
* Imply default checkout behaviour with y/N
* Fix uninstall failing to remove pihole user
* Print checkout 'git remote show origin' STDERR on new line
* Replaced checkout "AdminLTE" wording with "Web Admin"
* Fix handling of wildcard help text
* Rewrite help text for better handling of params
* Replace misleading letter variable
* stash changes on branch switch, else it fails if any changes have been made.
* Make changes according to comment in #1384
* Update queryFunc()
* Allow scanList() to search files using a wildcard by removing quotes wrapped around `${list}`
* scanList() will not provide a domain ouput on each string if exact is specified (`grep -l`)
* Remove unused processWildcards() function
* Return a message if no domain is specified
* IDN domains are converted to punycode when running a `pihole -q` search if the `python` package is available, otherwise will revert to current behaviour
* Scan Blacklist & Wildcards first, exiting from search if a match is found (Fixes#1330)
* Use one `grep` subshell to search for all "*.domains" lists at once (opposed to looping to get every matching file name, and then spawning a `grep` instance for every matching file)
* queryFunc() will not return "(0 results)" output from files where no match is found
* Sort results based off list number
* Return a message if no results are found
* Update basic-install.sh
* Update block page. Allow for setupVars setting of CUSTOMBLOCKPAGE (bool) to prevent it being overwritten
* simplify
* further simplify
* fix inteliJ IDEA complaints
* even further simplify
* tidy up output
* revert line, looks tidyer
* clarify
* Revert "Ensure any changes to blocking page are updated."
* We test for dpkg lock on line 830 directly, no need for the check also
in the template section.
Signed-off-by: Dan Schaper <dan.schaper@pi-hole.net>
* Display FTL version & version.sh rewrite
While testing to make sure `pihole -v` would output `pihole-FTL version`, I noticed some options didn't work how I expected them to. For example, if I use `pihole -v -p`, I would expect to see the version output of Pi-hole Core. Instead, I'm informed that it's an invalid option.
I've had the following things in mind while rewriting this:
* I'm operating under the assumption that FTL is only installed if the Admin Console is (Line 113 exit 0)
* I have modified the help text to only output with `pihole -v --help`
* I have modified all output to be more similar to the output style of `grep` and `curl` (Ditching ":::")
Testing output:
```
w3k@MCT:~$ pihole -v
Pi-hole version is v3.0.1-14-ga928cd3 (Latest: v3.0.1)
Admin Console version is v3.0-9-g3760482 (Latest: v3.0.1)
FTL version is v2.6.2 (Latest: v2.6.2)
w3k@MCT:~$ pihole -v -c
Current Pi-hole version is v3.0.1-14-ga928cd3
Current Admin Console version is v3.0-9-g3760482
Current FTL version is v2.6.2
w3k@MCT:~$ pihole -v -l
Latest Pi-hole version is v3.0.1
Latest Admin Console version is v3.0.1
Latest FTL version is v2.6.2
w3k@MCT:~$ pihole -v -p --hash
Current Pi-hole hash is a928cd3
w3k@MCT:~$ pihole -v -a --hash
Current Admin Console hash is 3760482
w3k@MCT:~$ pihole -v --help
Usage: pihole -v [REPO | OPTION] [OPTION]
Show Pi-hole, Web Admin & FTL versions
<Shows all Repositories and Options>
w3k@MCT:~$ pihole -v -foo
Invalid Option!
```
* Update -h to work as --hash
Also provide error output as per https://github.com/pi-hole/pi-hole/pull/1447#issuecomment-300600093
* Perform EXACT searches on HOSTS lists correctly
`\s` on the end may be overkill, but it is the existing scanList() behaviour.
* Fixed indentation
* Minimise string duplication & other minor changes
Instead of duplicating output strings, rewrite core/web/ftlOutput() into one neat versionOutput().
* Modified syntax to be valid for Shellcheck
* Log and echo gateway responses
* Update queryFunc() to search Whitelist
If there is a match in Whitelist/Blacklist/Wildcards, `[ ! -t 1 ]` will cause the search to end if the terminal is closed when the script is called. This has the intended effect of allowing a user to search for a W/B/W domain (as well as all the adlists it's found in) using `pihole -q` via Terminal, but the script will stop searching after a W/B/W match when called by the block page.
* Wrap in double brackets
* Provide remote hashes for version.sh
* Provide remote hashes for comparison
* Use double braces for all conditions (for consistency)
* Suppress potential "cd" error output
* Provide "not applicable" output upon any hash request for FTL
* whitelist on website blocked doesnt work (#1452)
Since Pi-hole redirects ad domains to itself, accessing the script via de.ign.com is the same as pi.hole in this case. The fix should be as simple as adding a / before admin on this line.
* Solve piholeLogFlush.sh having to be issued 2 x to clear logs (#1460)
Simplified the command -v syntax, and added a sleep 3 timer to the first execution of the log rotation. The second execution was being issued while the first was still running, thus it would fail and you would have to issue the "Flush Logs" command a second time.
* Use `echo "ABC" | pihole tricorder` to upload to Pi-hole's medical tricorder. Uses SSL if available.
* Update list.sh
I believe this has feature parity with `sed /foo/ Id` but also supports busybox, and my alpine docker ;)
* Document `sed` substitution for user readability
Comment the oneliner with explanations of what each step does.
* Update Help Output (#1467)
* File consistency
* Tabs to 2 spaces
* Corrected indenting
* Double braced conditionals
* Quoted variables within conditionals
* Standardise core help text
* Added help text for disable command
* Added help text for logging command
* Clean up
* Fixed certain new lines and spaces
* Sync with development branch
* Formatting consistency
* Tabs to 2 spaces
* Corrected indenting
* Double braced conditionals
* Quoted variables within conditionals
* Fixed certain newlines and spaces
* Admin help text
* Added help text for interface command
* Sync with development branch
* Formatting consistency
* Tabs to 2 spaces
* Fixed some wording
* Fixed certain spaces
* Formatting consistency
* Minor wording changes
* Tabs to 2 spaces
* Corrected indenting
* Double braced conditionals
* Quoted variables within conditionals
* Fixed certain newlines and spaces
* Blacklist help text
* Formatting consistency
* Tabs to 2 spaces
* Corrected indenting
* Cronometer help text
* Formatting consistency
* Fixed certain newlines and spaces
* Corrected indenting
* Checkout warning alteration
* Add checkout help text
* Corrected help output
* Show help for "pihole -a -i --help"
* Fix "pihole disable --help" and "pihole -l --help"
* Show help for "pihole -v -h"
* Indent output text
* Minor help text change
* Show help for "pihole checkout --help"
* Tricorder: Insecure Opt-out
* Check to see if Tricorder is being called directly
* Provide opt-out for insecure transmission of debug log
* Remove mention of internal function from help menu
* 🌮 is the new :shipit: squirrel
* Wording changes and bug fix
* Fix wildcard help text
* -wild is not a valid option since we're already using -wild
* Fix logrotation: manual flushing should be done twice, but automated rotation at midnight should only be done *once*!
* Print echos only when manual flushing is requested
* Add "quiet" mode + update comments in the cron file
* Confirm Tricorder is online
* Scan port 9998 to confirm the availability of "tricorder.pi-hole.net"
* Exit codes for upload process
* Formatting consistency
* Add link to Windows DNS Swapper
See #1400
* Install loopback firewall rules for FTL (#1419)
* Install loopback firewall rules for FTL
* FirewallD FTL ports
Signed-off-by: Dan Schaper <dan.schaper@pi-hole.net>
* Remove firewallD FTL local rules.
Local rules should not be blocked in firewallD, not requred for internal service FTD>
* Reinstate https rules, and delete FTL rules
Fixes earlier commit.
* Retrieve local repos on repair (#1481)
* Retrieve local repos on repair
* Change conditional to check for repair
* Change wording of Update/Reconfigure message
* Fixed indenting
* Perform "git reset --hard" on reconfigure
* Change directory before trying to reset repository. Fixes#1489
* No need to `cd $PWD` as it doesn't affect flow of caller script.
Signed-off-by: Dan Schaper <dan.schaper@pi-hole.net>
* Refine output of password status in basic-install.sh:displayFinalMessage(). Fixes#1488 (#1490)
* Rewrite Chronometer to output more stats
* Fix output IPv4 addr when removing CIDR notation (#1498)
* Move wildcards file if blocking is disabled (#1495)
* Move wildcards file if blocking is diabled
* Delete newline
* Roll back merge #1417 (#1494)
* Update ISSUE_TEMPLATE.md
* Remove Question option
* Prefer ULA over GUA addresses [IPv6] (#1508)
* On installs with GUA and ULA's we should prefer ULA's as it's been demonstrated that GUA's can and often are rotated by ISPs. Fixes#1473
* Add test for link-local address detection
* Add ULA-only and GUA-only tests
* Add test_IPv6_GUA_ULA_test and test_IPv6_ULA_GUA_test
* Add ""
* Add mock_command_2 command that can mock a command with more than one argument (as "ip -6 address") and result multiple lines of results
* Make mock_command_2 more similar to the original mock_command
* Correct comments
* Fixed remaining comments
* Fixed one last comment...
* Fixed a comment...
* Add weekly logrotation of FTL's log (#1509)
* Update LICENSE of the project to EUPL v1.2
* Make clear that NO is the default if the user just hits return (#1514)
* Add tricorderFunc back as usable function (#1515)
As per #1464
* Don't update FTL when there is a core update (as this will update FTL a second time). Fixes#1516
* Add FTL tests to the test suite (#1510)
* Add first version of FTL tests
* Wait one second to allow FTL to start up and analyze our mock log
* Add test_FTL_telnet_statistics
* Added test_FTL_telnet_top_clients
* Add test_FTL_telnet_top_domains
* Revert "Add FTL tests to the test suite (#1510)" (#1519)
This reverts commit cf6a1ac9ad.
* Trim version output when update is successful (#1527)
* Change ownership of /etc/pihole to user/group pihole. Fixes#1529 (#1530)
* Delete temporary files after installing the FTL binary. Fixes#1525
* Change from admin to approvers teams
* Introduce new file black.list for blacklist content
* Add "pihole -g -b" to *only* update black.list (saves a bunch of time when adding/changing only blacklisted files - won'tdownload lal lists, but only processes the blacklist and restars dnsmasq)
* Remove useless cat
* Improve displayed messages and overall logic
* Disable black.list on "pihole disable"
* cp + rm === mv (well, almost)
* Add first version of FTL tests
* Wait one second to allow FTL to start up and analyze our mock log
* Add test_FTL_telnet_statistics
* Added test_FTL_telnet_top_clients
* Add test_FTL_telnet_top_domains
* On installs with GUA and ULA's we should prefer ULA's as it's been demonstrated that GUA's can and often are rotated by ISPs. Fixes#1473
* Add test for link-local address detection
* Add ULA-only and GUA-only tests
* Add test_IPv6_GUA_ULA_test and test_IPv6_ULA_GUA_test
* Add ""
* Add mock_command_2 command that can mock a command with more than one argument (as "ip -6 address") and result multiple lines of results
* Make mock_command_2 more similar to the original mock_command
* Correct comments
* Fixed remaining comments
* Fixed one last comment...
* Fixed a comment...
* Retrieve local repos on repair
* Change conditional to check for repair
* Change wording of Update/Reconfigure message
* Fixed indenting
* Perform "git reset --hard" on reconfigure
* Install loopback firewall rules for FTL
* FirewallD FTL ports
Signed-off-by: Dan Schaper <dan.schaper@pi-hole.net>
* Remove firewallD FTL local rules.
Local rules should not be blocked in firewallD, not requred for internal service FTD>
* Reinstate https rules, and delete FTL rules
Fixes earlier commit.
* Check to see if Tricorder is being called directly
* Provide opt-out for insecure transmission of debug log
* Remove mention of internal function from help menu
* File consistency
* Tabs to 2 spaces
* Corrected indenting
* Double braced conditionals
* Quoted variables within conditionals
* Standardise core help text
* Added help text for disable command
* Added help text for logging command
* Clean up
* Fixed certain new lines and spaces
* Sync with development branch
* Formatting consistency
* Tabs to 2 spaces
* Corrected indenting
* Double braced conditionals
* Quoted variables within conditionals
* Fixed certain newlines and spaces
* Admin help text
* Added help text for interface command
* Sync with development branch
* Formatting consistency
* Tabs to 2 spaces
* Fixed some wording
* Fixed certain spaces
* Formatting consistency
* Minor wording changes
* Tabs to 2 spaces
* Corrected indenting
* Double braced conditionals
* Quoted variables within conditionals
* Fixed certain newlines and spaces
* Blacklist help text
* Formatting consistency
* Tabs to 2 spaces
* Corrected indenting
* Cronometer help text
* Formatting consistency
* Fixed certain newlines and spaces
* Corrected indenting
* Checkout warning alteration
* Add checkout help text
* Corrected help output
Simplified the command -v syntax, and added a sleep 3 timer to the first execution of the log rotation. The second execution was being issued while the first was still running, thus it would fail and you would have to issue the "Flush Logs" command a second time.
Since Pi-hole redirects ad domains to itself, accessing the script via de.ign.com is the same as pi.hole in this case. The fix should be as simple as adding a / before admin on this line.
* Provide remote hashes for comparison
* Use double braces for all conditions (for consistency)
* Suppress potential "cd" error output
* Provide "not applicable" output upon any hash request for FTL
If there is a match in Whitelist/Blacklist/Wildcards, `[ ! -t 1 ]` will cause the search to end if the terminal is closed when the script is called. This has the intended effect of allowing a user to search for a W/B/W domain (as well as all the adlists it's found in) using `pihole -q` via Terminal, but the script will stop searching after a W/B/W match when called by the block page.
While testing to make sure `pihole -v` would output `pihole-FTL version`, I noticed some options didn't work how I expected them to. For example, if I use `pihole -v -p`, I would expect to see the version output of Pi-hole Core. Instead, I'm informed that it's an invalid option.
I've had the following things in mind while rewriting this:
* I'm operating under the assumption that FTL is only installed if the Admin Console is (Line 113 exit 0)
* I have modified the help text to only output with `pihole -v --help`
* I have modified all output to be more similar to the output style of `grep` and `curl` (Ditching ":::")
Testing output:
```
w3k@MCT:~$ pihole -v
Pi-hole version is v3.0.1-14-ga928cd3 (Latest: v3.0.1)
Admin Console version is v3.0-9-g3760482 (Latest: v3.0.1)
FTL version is v2.6.2 (Latest: v2.6.2)
w3k@MCT:~$ pihole -v -c
Current Pi-hole version is v3.0.1-14-ga928cd3
Current Admin Console version is v3.0-9-g3760482
Current FTL version is v2.6.2
w3k@MCT:~$ pihole -v -l
Latest Pi-hole version is v3.0.1
Latest Admin Console version is v3.0.1
Latest FTL version is v2.6.2
w3k@MCT:~$ pihole -v -p --hash
Current Pi-hole hash is a928cd3
w3k@MCT:~$ pihole -v -a --hash
Current Admin Console hash is 3760482
w3k@MCT:~$ pihole -v --help
Usage: pihole -v [REPO | OPTION] [OPTION]
Show Pi-hole, Web Admin & FTL versions
<Shows all Repositories and Options>
w3k@MCT:~$ pihole -v -foo
Invalid Option!
```
* Disable `include-conf-enabled.pl`, as blindly enabling HTTPS (as Let's Encrypt does by having a file in that folder) creates Block Page inefficiencies
* Make Block page handle JS request rewrite, allowing users to better utilise their `lighttpd` service
* Make Block page handle debugging Pi-hole header
* Make Block page redirect users from `pi.hole` to `http://pi.hole/admin`
* Allow scanList() to search files using a wildcard by removing quotes wrapped around `${list}`
* scanList() will not provide a domain ouput on each string if exact is specified (`grep -l`)
* Remove unused processWildcards() function
* Return a message if no domain is specified
* IDN domains are converted to punycode when running a `pihole -q` search if the `python` package is available, otherwise will revert to current behaviour
* Scan Blacklist & Wildcards first, exiting from search if a match is found (Fixes#1330)
* Use one `grep` subshell to search for all "*.domains" lists at once (opposed to looping to get every matching file name, and then spawning a `grep` instance for every matching file)
* queryFunc() will not return "(0 results)" output from files where no match is found
* Sort results based off list number
* Return a message if no results are found
* An "About Pi-hole" link on the block page provides an ELI5 explanation to those not familiar with Pi-hole
* An email contact link on the block page provides users of your Pi-hole with a means to easily get in touch with you
* Browsing to your Pi-hole's address will show a simple "landing page", which can be replaced by adding "landing.php" within "/var/www/html"
* Users manually browsing to file/image based content (i.e: non HTML based content) on blocked sites will be greeted with a small "Blocked by Pi-hole" image
* Sites that are manually blacklisted will display a notice of this on the block page
* Sites that aren't directly blocked, but have a CNAME record, will show a notification on the block page (e.g: If raw.githubusercontent.com is not blocked, but github.map.fastly.net is)
* On the block page, "Back to Safety" now directs the user to "about:home" if Javascript is disabled
* Whitelisting is disabled for installs without a password, or if a client does not have Javascript
* Known issues:
* Admin Console needs a text field under "Web User Interface" where the admin can enter a preferred contact email when a site needs to be whitelisted, to be saved to setupVars.conf with the key "ADMIN_EMAIL"
* Admin Console needs a text field under "Networking" where the admin can enter their Pi-hole's externally contactable FQDN, allowing access to their landing page when browsing to mypi.duckdns.org, to be saved to setupVars.conf with the key "FQDN"
* I am not aware of expected output of `$_SERVER["VIRTUAL_HOST"]`, so I have assumed it should be filtered as if it's a domain
* Block page UI overhaul to replicate the style of the Admin Console
* Block page UI is now mobile friendly
* Users can safely customise text in order to make the block page more friendly for their household
Implement "Halt system" button, next to "Restart system" button, on
admin/settings page. Useful for doing clean shutdown before powering off.
(This affects 4 files, 3 for the web content, 1 for backend script.)
Gilbert Detillieux <gedetil> 2017-04-11
If someone tries to access 'http://pi.hole/', it will take them to the "Website blocked" page. Very confusing if you don't know to go to 'http://pi.hole/admin/'. This just redirects them to the admin panel.
Test aarch64 detection
Arm v6/v7 little endian.
x86_64 native
Test aarch64 detection
Unknown platform detection.
Signed-off-by: Dan Schaper <dan.schaper@pi-hole.net>
Added text block from 01-pihole.conf to warn user that manual changes to lighttpd config will be overwritten.
Slight cosmetic adjustments (tabs -> spaces).
Added text block from dns config file to warn user that manual changes to lighttpd config will be overwritten.
Slight cosmetic adjustments (tabs -> spaces).
mock commands for iptables check.
Test setting IPTables ruleset.
Test setting IPTables ruleset.
Test for already configured IPTables rules.
Test for addition of iptables rules.
Can only mock so deep in the commands.
Compare local and remote hashes. Update is available if current remote hash is different from current local hash since we assume that local should never be newer than remote for user
default rule DROP or REJECT as last rule.
Regex the conditions to make sure we are getting the right conditions.
Reframe the logic to simplify the chains and rules
Reframe the logic to simplify the chains and rules
Signed-off-by: Dan Schaper <dan.schaper@pi-hole.net>
Signed-off-by: Dan Schaper <dan.schaper@pi-hole.net>
Modify Fedora dependency installer
Signed-off-by: Dan Schaper <dan.schaper@pi-hole.net>
Fedora now installs and arrays only non-installed packages. Fedora also noops the cache update, since it updates at every dnf call anyays.
Signed-off-by: Dan Schaper <dan.schaper@pi-hole.net>
root@raspberrypi:/etc/.pihole# grep 'query' /var/log/pihole.log | grep -v 'query\['
Dec 22 16:29:50 dnsmasq[30801]: forwarded code.jquery.com to 208.67.222.222
Dec 22 16:29:50 dnsmasq[30801]: reply code.jquery.com is <CNAME>
Dec 22 16:29:50 dnsmasq[30801]: reply code.jquery.netdna-cdn.com is 94.31.29.54
Dec 22 16:29:50 dnsmasq[30801]: reply code.jquery.netdna-cdn.com is 23.111.11.3
Dec 22 16:29:50 dnsmasq[30801]: reply code.jquery.netdna-cdn.com is 198.232.125.113
Signed-off-by: Dan Schaper <dan.schaper@pi-hole.net>
Modify Fedora dependency installer
Signed-off-by: Dan Schaper <dan.schaper@pi-hole.net>
Fedora now installs and arrays only non-installed packages. Fedora also noops the cache update, since it updates at every dnf call anyays.
Signed-off-by: Dan Schaper <dan.schaper@pi-hole.net>
Move some bits around.
Start adding in logos to media links
More logos
Add BC logo
Change static images to use Asset server
Add and center control panel image
Remove extra break
Center Badges and move DO Slug
Bump Vortex up a bit.
Last change for now.
Move things around a bit.
Pull overlay off black hole image
Not sure if I should have created a variable for the username or if the echo is necessary. And this is my first time doing a pull request, hopefully it works out lol.
PA will tag PR to Master with -1 approval in the next release. That will deny any PR's against Master from users and changing branches after the PR is started does not appear to modify the PA actions.
* Comments to clarify some of the existing tests
* mock_command to allow recording of calls and mocking return calls in bash
* new configureFirewall test (only the first one of it's many paths)
Mish-mash of tabs and spaces used for indentation. Mostly tabs though,
so going with those. Also indenting blocks and enforcing the
loop statement; do
done
style over the newline for do since it seemed to be more common.
There were no fewer than three styles of function declaration going
on in these files, so I attempted to standardize them to the typical
myfucn() {
}
style.
epel-release installs the EPEL package repository (Extra Packages for Enterprise Linux)
Dependencies from this repository should available by default on Fedora
Removed a few checkboxes. I really don't want to deter people from
submitting issue because of a wall of text, but some of this
information we really can use to be more helpful.
- Test if /etc/hostname exists before attempting to cat the file.
- Add alternative hostname discovery via hostname command
- Add an error message to stdout if unable to determine host fqdn
* adding links to optimal.com
Also added image of Pi-hole's stats from Optimal.com and a bitcoin donation address per some user requests.
* simplified and new additions
I tried to simplify the readme page a bit. I also added some new links to some helper videos and added some screenshots of the whitelist editor.
* updated dashboard pic
* Update README.md
* simplified donation section
* forgot to remove the old donation stuff
* Hosts-file.net moved to https
* removed pihole berry from images
also added adafruit livestream video
* Update README.md
update "How does it work" video
The hosts-blocklist is a semi-automatically updated list, based on various well known public sources, for more details read: https://github.com/notracking/hosts-blocklists/
Please be aware that one file is for domain blocking and the other file for hostname based blocking, these lists are complimentary and should therefore be used simultaneously.
* Change dummy domain
Allows users to access Pi-hole console with my.pi-hole.net instead of the IP address
* Cleaned up formatting
* Put device hostname at the top of the list
Changed my.pi-hole.net to pi.hole and placed it under the device hostname. This way, ping will return the device hostname but you still can access the web interface with pi.hole/admin
Removed symlink of scripts to u/l/b
Added copy for setupLCD to /opt/pihole/
New spinner added to gravity.sh to reflect new spinner in basic-install.sh and uninstall.sh
Syntax of uninstall script now matches basic-install.sh.
More error handling of missing default files.
Force user prompt for removing packages when uninstalling.
Added links to where code was borrowed from
added reboot at the end
also added a few things commented out that might be useful for some
people to learn.
addresses #322. Will now check free space on the first file system output by 'df- lkP`, as opposed to `/` to make pi-hole more compatible with other distros.
Do not stop dnsmasq when installing. Instead run `service dnsmasq restart` once installation is complete.
This may have been the cause of issues outlined in #218
Give the user the ability to choose between Google and DynDNS upstream
servers. Then insert the chosen DNS servers in to
/etc/dnsmasq.d/01-pihole.conf. Todo: extend choices to include manually
entered DNS servers.
Prep for using sed to insert user selected DNSs into 01-pihole.conf.
Selections will come from dialog during install script containing the
following choices: Google, DynDNS, and eventually 2 custom DNS servers.
Check if /etc/dnsmasq.conf is from pihole. If so, replace with an
original and install new in .d directory. Add and unmolested version of
dnsmasq.conf to the ./advanced directory.
This puts sudo in a variable if run as a regular user. If already
running as root, the script proceeds as normal. Not a perfect fix, but
should help for install on other systems.
- removed most of the video images to reduce clutter
- converged the "coverage" and "video" sections into a bulleted list of links
- added a new project link (pi-hole on/off button)
- moved projects up in the page so it's easier to find and see what people are doing with Pi-hole
- removed custom conf section since it will be suited better in the wiki or FAQs
- added a help section
Failed to be populated if /tmp/piholeIP does not exist. This may happen under
the following conditions:
- was not generated during install
- gravity.sh being run again after the original install (the file is deleted
during the installation process)
- Rob's post on medium.com
- TekThing video
Also posting about plans to partner up with Rob for his new service that can help reduce the flame war surrounding ad blocking
I wanted the whitelist feature to keep the user on the same page
without having to reload it. I'm sure someone better versed in PHP
could eliminate the need for this hack. Nonetheless, it works.
www-data runs the script if executed from the Web interface. www-data
also needs access to write to /etc/pihole/gravity.list to actually
remove the domain. So a few more things need to happen before this
will fully work.
The changes in this script won't change what is displayed if run from
the terminal, but will help when it needs to be run from the Web
interface, so I am just committing this now.
The only other thing I would like to see would be a progress spinner,
but my Web skills still need some work...
Updated piholeIP because if there are multiple network adapters, the gravity list will populate incorrectly with both IP addresses. Only one address should be used.
Temporary hack for /etc/pihole directory and file permissions to pull out sudo requirement. (Irony is that is requires sudo.) This will be fixed later, but for now it's needed for existing installs so they don't break.
Updated piholeIP because if there are multiple network adapters, the gravity list will populate incorrectly with both IP addresses. Only one address should be used.
The changes to the gravity script check for a temp file containing the
static address set during the install. I need to verify it works so I
have to change the URL. I will change it back before merging with
master.
Created a function to set a static IP address.
I also sent STDOUT and STDERR to /dev/null so it doesn't mangle the
progress bar. When the device reboots, it still gets mangled a bit
(via ssh).
The ellipses cause errors, so they were removed.
I was on the right track with the associate array, but it would
previously execute the commands out of order. Following directions
from the URL in the comments, I made another array that helps keep the
array in the order.
This is a large update that helps users install the Pi-hole a bit
easier by using some dialog windows and also letting the user set a
static IP (I still need to figure out how to actually set the address
in the system, but everything else having to do with the install script
works).
This seems to be the more appropriate URL:
http://hosts-file.net/ad_servers.txt.
I compared it to the original URL using opendiff and they are exactly
the same.
lighttpd in Jessie uses /var/www/html for the root folder, so in order
to only edit one lightpd.conf file, the installer will create the
correct directory even if not being run on Jessie.
Match domain exactly instead of partially.
Gather list of domains to minimize number of times that hosts file must be enumerated.
Only add domain to whitelist if it isn't already present.
In my case there had been no whitespace in piholeIP (I configured it statically because 'hostname -I' returns multiple IP addresses, which ends in errornous hosts file), so it's more safe to add one between IP and hostname.
Further, I removed the obsolete latentBlacklist variable.
This adds in some back end improvements for better debugging. It also
allows you to access the Web interface, while you are connected to the
Pi-hole, which resolves#31
Since the version of lighted in Jessie moved the default folder to
/var/www/html, I am going to make it the same for wheezy for better
compatibility.
Also removed spaces
Due to so many users having issues with this list blocking legitimate
domains such as microsoft.com, apple.com, xkcd.com and more, I am
turning it off by default. While this drastically reduces the amount
of domains blocked, ad-blocking performance still seems to function
quite well.
Long-time users can simply uncomment the list, but this will make it so
new users have a more pleasant experience.
If you already have the mahakala list, you will need to remove it first
with this command:
sudo rm /etc/pihole/list.2.adblock.mahakala.is.domains
There are a few other lists I am looking at including, but this will
provide an immediate fix.
I'm not 100% sure if you can add multiple IP addresses to one domain on
a single line, so I just broke it up into two. It makes the file
bigger and longer, but I'll have to see how it works
Due to users having issues with the IP not being entered properly, I am restoring the original way to store `piholeIP` until a better solution can be formed.
This will increase the swap file to 500MB before downloading the lists.
Most of the issue comes from the mahakala list, which is so large. If
no swap file is found, one is created.
Prepend "^" to start of latentWhitelist.txt lines.
The -x switch requires a full line match of the regexp, where as -w
will try to find the match somewhere in the line, looking for work
breaks. Combined with turning the whitelist lines into full regexps,
this results in significantly faster parsing.
Having "^" prepended to the lines also keeps false whitelisting from
occuring, such as the following example:
If whitelist.txt contains "google.com" it would whitelist many other
sites that end in "google.com" as long as there is a non-word
character preceeding the google (such as "-", or ".").
manually running gravity.sh
This will print "Getting $domain list... " for each domain, followed
by either "Done" if data was received and validated, or "Skipping
list because it does not have any new entries" if no updates were
needed.
I also wanted to replace the for loop iterating over indices with
something like:
`for url in $sources[@]}`
It made the use of `$i` in the save location more annoying though.
**In raising this issue, I confirm the following:** `{please fill the checkboxes, e.g: [X]}`
- [] I have read and understood the [contributors guide](https://github.com/pi-hole/pi-hole/blob/master/CONTRIBUTING.md).
- [] The issue I am reporting can be *replicated*.
- [] The issue I am reporting isn't a duplicate (see [FAQs](https://github.com/pi-hole/pi-hole/wiki/FAQs), [closed issues](https://github.com/pi-hole/pi-hole/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aclosed%20), and [open issues](https://github.com/pi-hole/pi-hole/issues)).
**How familiar are you with the the source code relevant to this issue?:**
`{Replace this with a number from 1 to 10. 1 being not familiar, and 10 being very familiar}`
---
**Expected behaviour:**
`{A detailed description of what you expect to see}`
**Actual behaviour:**
`{A detailed description and/or screenshots of what you do see}`
**Steps to reproduce:**
`{Detailed steps of how we can reproduce this}`
**Debug token provided by [uploading `pihole -d` log](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#debug):**
`{Alphanumeric token}`
**Troubleshooting undertaken, and/or other relevant information:**
`{Steps of what you have done to fix this}`
> * `{Please delete this quoted section when opening your issue}`
> * You must follow the template instructions. Failure to do so will result in your issue being closed.
> * Please [submit any feature requests here](https://discourse.pi-hole.net/c/feature-requests), so it is votable and trackable by the community.
> * Please respect that Pi-hole is developed by volunteers, who can only reply in their spare time.
> * Detail helps us understand and resolve an issue quicker, but please ensure it's relevant.
> * _This template was created based on the work of [`udemy-dl`](https://github.com/nishad/udemy-dl/blob/master/LICENSE)._
**By submitting this pull request, I confirm the following:**
*please fill any appropriate checkboxes, e.g: [X]*
- [ ] I have read and understood the [contributors guide](https://github.com/pi-hole/pi-hole/blob/master/CONTRIBUTING.md), as well as this entire template.
- [ ] I have made only one major change in my proposed changes.
- [ ] I have commented my proposed changes within the code.
- [ ] I have tested my proposed changes, and have included unit tests where possible.
- [ ] I am willing to help maintain this change if there are issues with it later.
- [ ] I give this submission freely and claim no ownership.
- [ ] It is compatible with the [EUPL 1.2 license](https://opensource.org/licenses/EUPL-1.1)
- [ ] I have squashed any insignificant commits. ([`git rebase`](http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html))
Please make sure you [Sign Off](https://github.com/pi-hole/pi-hole/wiki/How-to-signoff-your-commits.) all commits. Pi-hole enforces the [DCO](https://github.com/pi-hole/pi-hole/wiki/Contributing-to-the-project).
---
**What does this PR aim to accomplish?:**
*A detailed description, screenshots (if necessary), as well as links to any relevant GitHub issues*
**How does this PR accomplish the above?:**
*A detailed description (such as a changelog) and screenshots (if necessary) of the implemented fix*
**What documentation changes (if any) are needed to support this PR?:**
*A detailed list of any necessary changes*
---
* You must follow the template instructions. Failure to do so will result in your pull request being closed.
* Please respect that Pi-hole is developed by volunteers, who can only reply in their spare time.
_This template was created based on the work of [`udemy-dl`](https://github.com/nishad/udemy-dl/blob/master/LICENSE)._
# Contributors Guide
Please read and understand the contribution guide before creating an issue or pull request.
## Etiquette
- Our goal for Pi-hole is **stability before features**. This means we focus on squashing critical bugs before adding new features. Often, we can do both in tandem, but bugs will take priority over a new feature.
- Pi-hole is open source and [powered by donations](https://pi-hole.net/donate/), and as such, we give our **free time** to build, maintain, and **provide user support** for this project. It would be extremely unfair for us to suffer abuse or anger for our hard work, so please take a moment to consider that.
- Please be considerate towards the developers and other users when raising issues or presenting pull requests.
- Respect our decision(s), and do not be upset or abusive if your submission is not used.
## Viability
When requesting or submitting new features, first consider whether it might be useful to others. Open source projects are used by many people, who may have entirely different needs to your own. Think about whether or not your feature is likely to be used by other users of the project.
## Procedure
**Before filing an issue:**
- Attempt to replicate and **document** the problem, to ensure that it wasn't a coincidental incident.
- Check to make sure your feature suggestion isn't already present within the project.
- Check the pull requests tab to ensure that the bug doesn't have a fix in progress.
- Check the pull requests tab to ensure that the feature isn't already in progress.
**Before submitting a pull request:**
- Check the codebase to ensure that your feature doesn't already exist.
- Check the pull requests to ensure that another person hasn't already submitted the feature or fix.
- Read and understand the [DCO guidelines](https://github.com/pi-hole/pi-hole/wiki/Contributing-to-the-project) for the project.
## Technical Requirements
- 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.
- 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.
We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.
This European Union Public Licence (the EUPL) applies to the Work (as defined below) which is provided under the terms of this Licence. Any use of the Work, other than as authorised under this Licence is prohibited (to the extent such use is covered by a right of the copyright holder of the Work).
The Work is provided under the terms of this Licence when the Licensor (as defined below) has placed the following notice immediately following the copyright notice for the Work:
Licensed under the EUPL
or has expressed by any other means his willingness to license under the EUPL.
Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software. If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.
1. Definitions
Finally, any free program is threatened constantly by software
patents. We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary. To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.
In this Licence, the following terms have the following meaning:
The precise terms and conditions for copying, distribution and
modification follow.
- The Licence: this Licence.
- The Original Work: the work or software distributed or communicated by the Licensor under this Licence, available as Source Code and also as Executable Code as the case may be.
- Derivative Works: the works or software that could be created by the Licensee, based upon the Original Work or modifications thereof. This Licence does not define the extent of modification or dependence on the Original Work required in order to classify a work as a Derivative Work; this extent is determined by copyright law applicable in the country mentioned in Article 15.
- The Work: the Original Work or its Derivative Works.
- The Source Code: the human-readable form of the Work which is the most convenient for people to study and modify.
- The Executable Code: any code which has generally been compiled and which is meant to be interpreted by a computer as a program.
- The Licensor: the natural or legal person that distributes or communicates the Work under the Licence.
- Contributor(s): any natural or legal person who modifies the Work under the Licence, or otherwise contributes to the creation of a Derivative Work.
- The Licensee or You: any natural or legal person who makes any usage of the Work under the terms of the Licence.
- Distribution or Communication: any act of selling, giving, lending, renting, distributing, communicating, transmitting, or otherwise making available, online or offline, copies of the Work or providing access to its essential functionalities at the disposal of any other natural or legal person.
GNU GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
2. Scope of the rights granted by the Licence
0. This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License. The "Program", below,
refers to any such program or work, and a "work based on the Program"
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language. (Hereinafter, translation is included without limitation in
the term "modification".) Each licensee is addressed as "you".
The Licensor hereby grants You a worldwide, royalty-free, non-exclusive, sublicensable licence to do the following, for the duration of copyright vested in the Original Work:
- use the Work in any circumstance and for all usage,
- reproduce the Work,
- modify the Work, and make Derivative Works based upon the Work,
- communicate to the public, including the right to make available or display the Work or copies thereof to the public and perform publicly, as the case may be, the Work,
- distribute the Work or copies thereof,
- lend and rent the Work or copies thereof,
- sublicense rights in the Work or copies thereof.
Those rights can be exercised on any media, supports and formats, whether now known or later invented, as far as the applicable law permits so.
In the countries where moral rights apply, the Licensor waives his right to exercise his moral right to the extent allowed by law in order to make effective the licence of the economic rights here above listed.
The Licensor grants to the Licensee royalty-free, non-exclusive usage rights to any patents held by the Licensor, to the extent necessary to make use of the rights granted on the Work under this Licence.
Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.
3. Communication of the Source Code
1. You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.
The Licensor may provide the Work either in its Source Code form, or as Executable Code. If the Work is provided as Executable Code, the Licensor provides in addition a machine-readable copy of the Source Code of the Work along with each copy of the Work that the Licensor distributes or indicates, in a notice following the copyright notice attached to the Work, a repository where the Source Code is easily and freely accessible for as long as the Licensor continues to distribute or communicate the Work.
You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.
4. Limitations on copyright
2. You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
Nothing in this Licence is intended to deprive the Licensee of the benefits from any exception or limitation to the exclusive rights of the rights owners in the Work, of the exhaustion of those rights or of other applicable limitations thereto.
a) You must cause the modified files to carry prominent notices
stating that you changed the files and the date of any change.
5. Obligations of the Licensee
b) You must cause any work that you distribute or publish, that in
whole or in part contains or is derived from the Program or any
part thereof, to be licensed as a whole at no charge to all third
parties under the terms of this License.
The grant of the rights mentioned above is subject to some restrictions and obligations imposed on the Licensee. Those obligations are the following:
c) If the modified program normally reads commands interactively
when run, you must cause it, when started running for such
interactive use in the most ordinary way, to print or display an
announcement including an appropriate copyright notice and a
notice that there is no warranty (or else, saying that you provide
a warranty) and that users may redistribute the program under
these conditions, and telling the user how to view a copy of this
License. (Exception: if the Program itself is interactive but
does not normally print such an announcement, your work based on
the Program is not required to print an announcement.)
Attribution right: The Licensee shall keep intact all copyright, patent or trademarks notices and all notices that refer to the Licence and to the disclaimer of warranties. The Licensee must include a copy of such notices and a copy of the Licence with every copy of the Work he/she distributes or communicates. The Licensee must cause any Derivative Work to carry prominent notices stating that the Work has been modified and the date of modification.
These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.
Copyleft clause: If the Licensee distributes or communicates copies of the Original Works or Derivative Works, this Distribution or Communication will be done under the terms of this Licence or of a later version of this Licence unless the Original Work is expressly distributed only under this version of the Licence - for example by communicating EUPL v. 1.2 only. The Licensee (becoming Licensor) cannot offer or impose any additional terms or conditions on the Work or Derivative Work that alter or restrict the terms of the Licence.
Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.
Compatibility clause: If the Licensee Distributes or Communicates Derivative Works or copies thereof based upon both the Work and another work licensed under a Compatible Licence, this Distribution or Communication can be done under the terms of this Compatible Licence. For the sake of this clause, Compatible Licence refers to the licences listed in the appendix attached to this Licence. Should the Licensee's obligations under the Compatible Licence conflict with his/her obligations under this Licence, the obligations of the Compatible Licence shall prevail.
In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.
Provision of Source Code: When distributing or communicating copies of the Work, the Licensee will provide a machine-readable copy of the Source Code or indicate a repository where this Source will be easily and freely available for as long as the Licensee continues to distribute or communicate the Work.
3. You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:
Legal Protection: This Licence does not grant permission to use the trade names, trademarks, service marks, or names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the copyright notice.
a) Accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of Sections
1 and 2 above on a medium customarily used for software interchange; or,
6. Chain of Authorship
b) Accompany it with a written offer, valid for at least three
years, to give any third party, for a charge no more than your
cost of physically performing source distribution, a complete
machine-readable copy of the corresponding source code, to be
distributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,
The original Licensor warrants that the copyright in the Original Work granted hereunder is owned by him/her or licensed to him/her and that he/she has the power and authority to grant the Licence.
c) Accompany it with the information you received as to the offer
to distribute corresponding source code. (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form with such
an offer, in accord with Subsection b above.)
Each Contributor warrants that the copyright in the modifications he/she brings to the Work are owned by him/her or licensed to him/her and that he/she has the power and authority to grant the Licence.
The source code for a work means the preferred form of the work for
making modifications to it. For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable. However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.
Each time You accept the Licence, the original Licensor and subsequent Contributors grant You a licence to their contributions to the Work, under the terms of this Licence.
If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.
7. Disclaimer of Warranty
4. You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.
The Work is a work in progress, which is continuously improved by numerous Contributors. It is not a finished work and may therefore contain defects or bugs inherent to this type of development.
For the above reason, the Work is provided under the Licence on an as is basis and without warranties of any kind concerning the Work, including without limitation merchantability, fitness for a particular purpose, absence of defects or errors, accuracy, non-infringement of intellectual property rights other than copyright as stated in Article 6 of this Licence.
This disclaimer of warranty is an essential part of the Licence and a condition for the grant of any rights to the Work.
5. You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Program or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.
8. Disclaimer of Liability
6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions. You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.
Except in the cases of wilful misconduct or damages directly caused to natural persons, the Licensor will in no event be liable for any direct or indirect, material or moral, damages of any kind, arising out of the Licence or of the use of the Work, including without limitation, damages for loss of goodwill, work stoppage, computer failure or malfunction, loss of data or any commercial damage, even if the Licensor has been advised of the possibility of such damage. However, the Licensor will be liable under statutory product liability laws as far such laws apply to the Work.
7. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all. For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.
9. Additional agreements
If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.
While distributing the Work, You may choose to conclude an additional agreement, defining obligations or services consistent with this Licence. However, if accepting obligations, You may act only on your own behalf and on your sole responsibility, not on behalf of the original Licensor or any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against such Contributor by the fact You have accepted any warranty or additional liability.
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
10. Acceptance of the Licence
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
The provisions of this Licence can be accepted by clicking on an icon I agree placed under the bottom of a window displaying the text of this Licence or by affirming consent in any other similar way, in accordance with the rules of applicable law. Clicking on that icon indicates your clear and irrevocable acceptance of this Licence and all of its terms and conditions.
Similarly, you irrevocably accept this Licence and all of its terms and conditions by exercising any rights granted to You by Article 2 of this Licence, such as the use of the Work, the creation by You of a Derivative Work or the Distribution or Communication by You of the Work or copies thereof.
8. If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded. In such case, this License incorporates
the limitation as if written in the body of this License.
11. Information to the public
9. The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
In case of any Distribution or Communication of the Work by means of electronic communication by You (for example, by offering to download the Work from a remote location) the distribution channel or media (for example, a website) must at least provide to the public the information requested by the applicable law regarding the Licensor, the Licence and the way it may be accessible, concluded, stored and reproduced by the Licensee.
Each version is given a distinguishing version number. If the Program
specifies a version number of this License which applies to it and "any
later version", you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation. If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.
12. Termination of the Licence
10. If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission. For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this. Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.
The Licence and the rights granted hereunder will terminate automatically upon any breach by the Licensee of the terms of the Licence.
Such a termination will not terminate the licences of any person who has received the Work from the Licensee under the Licence, provided such persons remain in full compliance with the Licence.
NO WARRANTY
13. Miscellaneous
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.
Without prejudice of Article 9 above, the Licence represents the complete agreement between the Parties as to the Work.
If any provision of the Licence is invalid or unenforceable under applicable law, this will not affect the validity or enforceability of the Licence as a whole. Such provision will be construed or reformed so as necessary to make it valid and enforceable.
The European Commission may publish other linguistic versions or new versions of this Licence or updated versions of the Appendix, so far this is required and reasonable, without reducing the scope of the rights granted by the Licence. New versions of the Licence will be published with a unique version number.
All linguistic versions of this Licence, approved by the European Commission, have identical value. Parties can take advantage of the linguistic version of their choice.
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
14. Jurisdiction
END OF TERMS AND CONDITIONS
Without prejudice to specific agreement between parties,
- any litigation resulting from the interpretation of this License, arising between the European Union institutions, bodies, offices or agencies, as a Licensor, and any Licensee, will be subject to the jurisdiction of the Court of Justice of the European Union, as laid down in article 272 of the Treaty on the Functioning of the European Union,
- any litigation arising between other parties and resulting from the interpretation of this License, will be subject to the exclusive jurisdiction of the competent court where the Licensor resides or conducts its primary business.
How to Apply These Terms to Your New Programs
15. Applicable Law
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.
Without prejudice to specific agreement between parties,
- this Licence shall be governed by the law of the European Union Member State where the Licensor has his seat, resides or has his registered office,
- this licence shall be governed by Belgian law if the Licensor has no seat, residence or registered office inside a European Union Member State.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
===
{description}
Copyright (C) {year} {fullname}
Appendix
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) year name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License. Of course, the commands you use may
be called something other than `show w' and `show c'; they could even be
mouse-clicks or menu items--whatever suits your program.
You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the program, if
necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the program
`Gnomovision' (which makes passes at compilers) written by James Hacker.
{signature of Ty Coon}, 1 April 1989
Ty Coon, President of Vice
This General Public License does not permit incorporating your program into
proprietary programs. If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library. If this is what you want to do, use the GNU Lesser General
Public License instead of this License.
Compatible Licences according to Article 5 EUPL are:
- GNU General Public License (GPL) v. 2, v. 3
- GNU Affero General Public License (AGPL) v. 3
- Open Software License (OSL) v. 2.1, v. 3.0
- Eclipse Public License (EPL) v. 1.0
- CeCILL v. 2.0, v. 2.1
- Mozilla Public Licence (MPL) v. 2
- GNU Lesser General Public Licence (LGPL) v. 2.1, v. 3
- Creative Commons Attribution-ShareAlike v. 3.0 Unported (CC BY-SA 3.0) for works other than software
- European Union Public Licence (EUPL) v. 1.1, v. 1.2
- Québec Free and Open-Source Licence - Reciprocity (LiLiQ-R) or Strong Reciprocity (LiLiQ-R+)
- The European Commission may update this Appendix to later versions of the above licences without producing a new version of the EUPL, as long as they provide the rights granted in Article 2 of this Licence and protect the covered Source Code from exclusive appropriation.
-All other changes or additions to this Appendix require the production of a new EUPL version.
<b>Network-wide ad blocking via your own Linux hardware</b><br/>
</p>
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.
The Pi-hole is a DNS/Web server that will **block ads for any device on your network**.
- **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)
- **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
- **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 server-grade 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
[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:
## 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 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.
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 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:
<imgsrc="https://pi-hole.github.io/graphics/Badges/paypal-badge-black.svg"width="24"height="24"alt="PP"/><ahref="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=3J2L3Z4DHW9UY">Donate via PayPal</a><br/>
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 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
While we are primarily reachable on our <ahref="https://discourse.pi-hole.net/">Discourse User Forum</a>, 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.
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 understanding of `bash`.
* [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!
* 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):
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
* 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 a **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) - webserver designed and optimized for high performance
* [`php`](https://secure.php.net) - a popular general-purpose web scripting language
* [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)
- [Windows DNS Swapper](https://github.com/roots84/DNS-Swapper), see [#1400](https://github.com/pi-hole/pi-hole/issues/1400)
-----
## Coverage
Featured on [MakeUseOf](http://www.makeuseof.com/tag/adblock-everywhere-raspberry-pi-hole-way/) and [Lifehacker](http://lifehacker.com/turn-a-raspberry-pi-into-an-ad-blocker-with-a-single-co-1686093533)!
Once installed, **configure any device to use the Raspberry Pi as its DNS server and the ads will be blocked**. You can also configure your router's DHCP options to assign the Pi as clients DNS server so they do not need to do it manually.
A more detailed explanation of the installation can be found [here](http://jacobsalmela.com/block-millions-ads-network-wide-with-a-raspberry-pi-hole-2-0).
The [gravity.sh](https://github.com/jacobsalmela/pi-hole/blob/master/gravity.sh) does most of the magic. The script pulls in ad domains from many sources and compiles them into a single list of [over 900,000 entries](http://jacobsalmela.com/block-millions-ads-network-wide-with-a-raspberry-pi-hole-2-0).
## Whitelist and blacklist
You can add a `whitelist.txt` or `blacklist.txt` in `/etc/pihole/` and the script will apply those files automatically.
## Web Interface
I am also working on a [Web interface](https://github.com/jacobsalmela/AdminLTE#pi-hole-admin-dashboard) so you can view stats and change settings.
## Custom Config File
If you want to use your own variables for the gravity script (i.e. storing the files in a different location) and don't want to have to change them every time there is an update to the script, create a file called `/etc/pihole/pihole.conf`. In it, you should add your own variables in a similar fashion as shown below:
```
origin=/var/run/pihole
adList=/etc/dnsmasq.d/adList
```
See [this PR](https://github.com/jacobsalmela/pi-hole/pull/20) for more details.
### How It Works
A technical and detailed description can be found [here](http://jacobsalmela.com/block-millions-ads-network-wide-with-a-raspberry-pi-hole-2-0)!
## Other Operating Systems
This script will work for other UNIX-like systems with some slight **modifications**. As long as you can install `dnsmasq` and a Webserver, it should work OK. The automated install only works for a clean install of Raspiban right now since that is how the project originated.
- [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)
- [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/)
- [Linux Pro: The Hole Truth](http://www.linuxpromagazine.com/Issues/2017/200/The-sysadmin-s-daily-grind-Pi-hole)
- [CryptoAUSTRALIA: How We Tried 5 Privacy Focused Raspberry Pi Projects](https://blog.cryptoaustralia.org.au/2017/10/05/5-privacy-focused-raspberry-pi-projects/)
#bpOutput.unhandled:after{content:"An unhandled exception occured. This may happen when your browser is unable to load jQuery, or when the webserver is denying access to the Pi-hole API.";}
#bpOutput.success:before{content:"Success";}
#bpOutput.success:after{content:"Website has been whitelisted! You may need to flush your DNS cache";}
.recentwl:before{content:"This site has been whitelisted. Please flush your DNS cache and/or restart your browser.";}
.unknown:before{content:"This website is not found in any of Pi-hole's blacklists. The reason you have arrived here is unknown.";}
.cname:before{content:"This site is an alias for ";}/* <a href="http://cname.com">cname.com</a> */
.cname:after{content:", which may be blocked by Pi-hole.";}
// Determine if at least one block list has been generated
if(empty(glob("/etc/pihole/list.0.*.domains")))
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>.");
// Set location of adlists file
if(is_file("/etc/pihole/adlists.list")){
$adLists="/etc/pihole/adlists.list";
}elseif(is_file("/etc/pihole/adlists.default")){
$adLists="/etc/pihole/adlists.default";
}else{
die("[ERROR] File not found: <code>/etc/pihole/adlists.list</code>");
}
// Get all URLs starting with "http" or "www" from adlists and re-index array numerically
<footer><span><?=date("l g:i A, F dS"); ?>.</span> Pi-hole <?=$phVersion ?> (<?=gethostname()."/".$_SERVER["SERVER_ADDR"]; if (isset($execTime)) printf("/%.2fs", $execTime); ?>)</footer>
''' Make sure shellcheck does not find anything wrong with our shell scripts '''
shellcheck="find . -type f -name 'update.sh' | while read file; do shellcheck -x \"$file\" -e SC1090,SC1091; done;"
results=run_local(shellcheck)
printresults.stdout
assert''==results.stdout
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
