@ -4,8 +4,8 @@ Please read and understand the contribution guide before creating an issue or pu
## Etiquette
## 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.
- 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.
- 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.
- 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.
- Respect our decision(s), and do not be upset or abusive if your submission is not used.
@ -26,7 +26,7 @@ When requesting or submitting new features, first consider whether it might be u
- Check the codebase to ensure that your feature doesn't already exist.
- 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.
- 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.
- Read and understand the [DCO guidelines](https://docs.pi-hole.net/guides/github/contributing/) for the project.
## Technical Requirements
## Technical Requirements
@ -36,3 +36,77 @@ When requesting or submitting new features, first consider whether it might be u
- Commit Unix line endings.
- 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)
- 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.
- (Optional fun) keep to the theme of Star Trek/black holes/gravity.
## Forking and Cloning from GitHub to GitHub
1. Fork <https://github.com/pi-hole/pi-hole/> to a repo under a namespace you control, or have permission to use, for example: `https://github.com/<your_namespace>/<your_repo_name>/`. You can do this from the github.com website.
2. Clone `https://github.com/<your_namespace>/<your_repo_name>/` with the tool of you choice.
3. To keep your fork in sync with our repo, add an upstream remote for pi-hole/pi-hole to your repo.
4. Checkout the `development` branch from your fork `https://github.com/<your_namespace>/<your_repo_name>/`.
5. Create a topic/branch, based on the `development` branch code. *Bonus fun to keep to the theme of Star Trek/black holes/gravity.*
6. Make your changes and commit to your topic branch in your repo.
7. Rebase your commits and squash any insignificant commits. See the notes below for an example.
8. Merge `development` your branch and fix any conflicts.
9. Open a Pull Request to merge your topic branch into our repo's `development` branch.
- Keep in mind the technical requirements from above.
## Forking and Cloning from GitHub to other code hosting sites
- Forking is a GitHub concept and cannot be done from GitHub to other git-based code hosting sites. However, those sites may be able to mirror a GitHub repo.
1. To contribute from another code hosting site, you must first complete the steps above to fork our repo to a GitHub namespace you have permission to use, for example: `https://github.com/<your_namespace>/<your_repo_name>/`.
2. Create a repo in your code hosting site, for example: `https://gitlab.com/<your_namespace>/<your_repo_name>/`
3. Follow the instructions from your code hosting site to create a mirror between `https://github.com/<your_namespace>/<your_repo_name>/` and `https://gitlab.com/<your_namespace>/<your_repo_name>/`.
4. When you are ready to create a Pull Request (PR), follow the steps `(starting at step #6)` from [Forking and Cloning from GitHub to GitHub](#forking-and-cloning-from-github-to-github) and create the PR from `https://github.com/<your_namespace>/<your_repo_name>/`.
## Notes for squashing commits with rebase
- To rebase your commits and squash previous commits, you can use:
```bash
git rebase -i your_topic_branch~(number of commits to combine)
```
- For more details visit [gitready.com](http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html)
1. The following would combine the last four commits in the branch `mytopic`.
```bash
git rebase -i mytopic~4
```
2. An editor window opens with the most recent commits indicated: (edit the commands to the left of the commit ID)
```gitattributes
pick 9dff55b2 existing commit comments
squash ebb1a730 existing commit comments
squash 07cc5b50 existing commit comments
reword 9dff55b2 existing commit comments
```
3. Save and close the editor. The next editor window opens: (edit the new commit message). *If you select reword for a commit, an additional editor window will open for you to edit the comment.*
```bash
new commit comments
Signed-off-by: yourname <youremailaddress>
```
4. Save and close the editor for the rebase process to execute. The terminal output should say something like the following:
```bash
Successfully rebased and updated refs/heads/mytopic.
```
5. Once you have a successful rebase, and before you sync your local clone, you have to force push origin to update your repo:
```bash
git push -f origin
```
6. Continue on from step #7 from [Forking and Cloning from GitHub to GitHub](#forking-and-cloning-from-github-to-github)
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 sinkhole](https://en.wikipedia.org/wiki/DNS_Sinkhole) that protects your devices from unwanted content, without installing any client-side software.
- **Easy-to-install**: our versatile installer walks you through the process, and [takes less than ten minutes](https://www.youtube.com/watch?v=vKWjx1AQYgs)
- **Easy-to-install**: our versatile installer walks you through the process, and takes less than ten minutes
- **Resolute**: content is blocked in _non-browser locations_, such as ad-laden mobile apps and smart TVs
- **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
- **Responsive**: seamlessly speeds up the feel of everyday browsing by caching DNS queries
- **Lightweight**: runs smoothly with [minimal hardware and software requirements](https://docs.pi-hole.net/main/prerequisites/)
- **Lightweight**: runs smoothly with [minimal hardware and software requirements](https://docs.pi-hole.net/main/prerequisites/)
@ -162,4 +162,4 @@ Some of the statistics you can integrate include:
- Queries cached
- Queries cached
- Unique clients
- 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 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 find out [more details over here](https://discourse.pi-hole.net/t/pi-hole-api/1863).
log_write "${CROSS} Error: ${COL_RED}${detected_os} is supported but version ${detected_version} is currently unsupported (${FAQ_HARDWARE_REQUIREMENTS})${COL_NC}"
log_write "${CROSS} Error: ${COL_RED}${detected_os^} is supported but version ${detected_version} is currently unsupported (${FAQ_HARDWARE_REQUIREMENTS})${COL_NC}"
echo_current_diagnostic "Discovering active DHCP servers (takes 10 seconds)"
OLD_IFS="$IFS"
IFS=$'\n'
localentries=()
mapfile -t entries < <(pihole-FTL dhcp-discover)
for line in "${entries[@]}";do
log_write "${line}"
done
IFS="$OLD_IFS"
}
show_groups(){
show_groups(){
show_db_entries "Groups""SELECT id,CASE enabled WHEN '0' THEN ' 0' WHEN '1' THEN ' 1' ELSE enabled END enabled,name,datetime(date_added,'unixepoch','localtime') date_added,datetime(date_modified,'unixepoch','localtime') date_modified,description FROM \"group\"""4 7 50 19 19 50"
show_db_entries "Groups""SELECT id,CASE enabled WHEN '0' THEN ' 0' WHEN '1' THEN ' 1' ELSE enabled END enabled,name,datetime(date_added,'unixepoch','localtime') date_added,datetime(date_modified,'unixepoch','localtime') date_modified,description FROM \"group\"""4 7 50 19 19 50"
printf" (In this case, your previous run of pihole -up will have already updated the local repository)\\n"
printf" (In this case, your previous run of pihole -up will have already updated the local repository)\\n"
printf"\\n"
printf"\\n"
printf" It is possible that the installation will still fail at this stage due to an unsupported configuration.\\n"
printf" If that is the case, you can feel free to ask the community on Discourse with the %bCommunity Help%b category:\\n""${COL_LIGHT_RED}""${COL_NC}"
printf" If that is the case, you can feel free to ask the community on Discourse with the %bCommunity Help%b category:\\n""${COL_LIGHT_RED}""${COL_NC}"
In the next section, you can choose to use your current network settings (DHCP) or to manually edit them." "${r}" "${c}"
In the next section, you can choose to use your current network settings (DHCP) or to manually edit them." "${r}" "${c}"
}
}
# We need to make sure there is enough space before installing, so there is a function to check this
verifyFreeDiskSpace(){
# 50MB is the minimum space needed (45MB install (includes web admin bootstrap/jquery libraries etc) + 5MB one day of logs.)
# - Fourdee: Local ensures the variable is only created, and accessible within this function/void. Generally considered a "good" coding practice for non-global variables.
# A function that let's the user pick an interface to use with Pi-hole
# A function that let's the user pick an interface to use with Pi-hole
chooseInterface(){
chooseInterface(){
# Turn the available interfaces into an array so it can be used with a whiptail dialog
# Turn the available interfaces into an array so it can be used with a whiptail dialog
@ -1231,7 +1213,6 @@ setPrivacyLevel() {
"1""Hide domains" off
"1""Hide domains" off
"2""Hide domains and clients" off
"2""Hide domains and clients" off
"3""Anonymous mode" off
"3""Anonymous mode" off
"4""Disabled statistics" off
)
)
# Get the user's choice
# Get the user's choice
@ -1264,13 +1245,18 @@ setAdminFlag() {
printf" %b Web Interface Off\\n""${INFO}"
printf" %b Web Interface Off\\n""${INFO}"
# or false
# or false
INSTALL_WEB_INTERFACE=false
INSTALL_WEB_INTERFACE=false
# Deselect the web server as well, since it is obsolete then
INSTALL_WEB_SERVER=false
;;
;;
esac
esac
# Request user to install web server, if --disable-install-webserver has not been used (INSTALL_WEB_SERVER=true is default).
# Request user to install web server, if it has not been deselected before (INSTALL_WEB_SERVER=true is default).
if[["${INSTALL_WEB_SERVER}"==true]];then
if[["${INSTALL_WEB_SERVER}"==true]];then
WebToggleCommand=(whiptail --separate-output --radiolist "Do you wish to install the web server (lighttpd)?\\n\\nNB: If you disable this, and, do not have an existing webserver installed, the web interface will not function.""${r}""${c}" 6)
# Get list of required PHP modules, excluding base package (common) and handler (cgi)
# with the default being enabled
local i php_modules
for i in "${PIHOLE_WEB_DEPS[@]}";do[[$i=='php'* &&$i != *'-common'&&$i != *'-cgi']]&&php_modules+="${i#*-}";done
WebToggleCommand=(whiptail --separate-output --radiolist "Do you wish to install the web server (lighttpd) and required PHP modules?\\n\\nNB: If you disable this, and, do not have an existing web server and required PHP modules (${php_modules# }) installed, the web interface will not function. Additionally the web server user needs to be member of the \"pihole\" group for full functionality.""${r}""${c}" 6)
# Enable as default and recommended option
WebChooseOptions=("On (Recommended)""" on
WebChooseOptions=("On (Recommended)""" on
Off "" off)
Off "" off)
WebChoices=$("${WebToggleCommand[@]}""${WebChooseOptions[@]}" 2>&1 >/dev/tty)||(printf" %bCancel was selected, exiting installer%b\\n""${COL_LIGHT_RED}""${COL_NC}"&&exit 1)
WebChoices=$("${WebToggleCommand[@]}""${WebChooseOptions[@]}" 2>&1 >/dev/tty)||(printf" %bCancel was selected, exiting installer%b\\n""${COL_LIGHT_RED}""${COL_NC}"&&exit 1)
@ -1304,9 +1290,7 @@ chooseBlocklists() {
# In a variable, show the choices available; exit if Cancel is selected
# In a variable, show the choices available; exit if Cancel is selected
if ! install -o root -m 644 /dev/null "${PI_HOLE_CONFIG_DIR}/custom.list"&>/dev/null;then
printf" %bError: Unable to initialize configuration file %s/custom.list\\n""${COL_LIGHT_RED}""${PI_HOLE_CONFIG_DIR}"
return1
fi
fi
# If the user chose to install the dashboard,
# If the user chose to install the dashboard,
if[["${INSTALL_WEB_SERVER}"==true]];then
if[["${INSTALL_WEB_SERVER}"==true]];then
# and if the Web server conf directory does not exist,
# and if the Web server conf directory does not exist,
@ -1919,7 +1913,7 @@ finalExports() {
# If the setup variable file exists,
# If the setup variable file exists,
if[[ -e "${setupVars}"]];then
if[[ -e "${setupVars}"]];then
# update the variables in the file
# update the variables in the file
sed -i.update.bak '/PIHOLE_INTERFACE/d;/IPV4_ADDRESS/d;/IPV6_ADDRESS/d;/PIHOLE_DNS_1/d;/PIHOLE_DNS_2/d;/QUERY_LOGGING/d;/INSTALL_WEB_SERVER/d;/INSTALL_WEB_INTERFACE/d;/LIGHTTPD_ENABLED/d;' "${setupVars}"
sed -i.update.bak '/PIHOLE_INTERFACE/d;/IPV4_ADDRESS/d;/IPV6_ADDRESS/d;/PIHOLE_DNS_1/d;/PIHOLE_DNS_2/d;/QUERY_LOGGING/d;/INSTALL_WEB_SERVER/d;/INSTALL_WEB_INTERFACE/d;/LIGHTTPD_ENABLED/d;/CACHE_SIZE/d;' "${setupVars}"
printf" Pi-hole does not provide an SELinux policy as the required changes modify the security of your system.\\n"
printf" Pi-hole does not provide an SELinux policy as the required changes modify the security of your system.\\n"
printf" Please refer to https://wiki.centos.org/HowTos/SELinux if SELinux is required for your deployment.\\n"
printf" Please refer to https://wiki.centos.org/HowTos/SELinux if SELinux is required for your deployment.\\n"
printf" This check can be skipped by setting the environment variable %bPIHOLE_SELINUX%b to %btrue%b\\n""${COL_LIGHT_RED}""${COL_NC}""${COL_LIGHT_RED}""${COL_NC}"
printf" e.g: export PIHOLE_SELINUX=true\\n"
printf" By setting this variable to true you acknowledge there may be issues with Pi-hole during or after the install\\n"
# Update timestamp of last update of this list. We store this in the "old" database as all values in the new database will later be overwritten
database_adlist_updated(){
output=$({printf".timeout 30000\\nUPDATE adlist SET date_updated = (cast(strftime('%%s', 'now') as int)) WHERE id = %i;\\n""${1}"| sqlite3 "${gravityDBfile}";} 2>&1)
status="$?"
if[["${status}" -ne 0]];then
echo -e "\\n ${CROSS} Unable to update timestamp of adlist with ID ${1} in database ${gravityDBfile}\\n ${output}"
gravity_Cleanup "error"
fi
}
# Migrate pre-v5.0 list files to database-based Pi-hole versions
# Migrate pre-v5.0 list files to database-based Pi-hole versions
migrate_to_database(){
migrate_to_database(){
# Create database file only if not present
# Create database file only if not present
@ -334,7 +344,7 @@ gravity_DownloadBlocklists() {
return1
return1
fi
fi
local url domain agent cmd_ext str target
local url domain agent cmd_ext str target compression
Grégory Sanchez
4 years ago