Updating README

This commit is contained in:
Steve Jenkins
2019-07-10 13:57:22 -07:00
parent f5b7091526
commit 71f920624f

View File

@ -3,34 +3,34 @@ A script to help synchronize <a target="_blank"
href="https://pi-hole.net/">Pi-hole</a> blocklist, blacklist, whitelist, and regex files across multiple Pi-holes using a Git repository.
# Why pihole-cloudsync?
I run six Pi-holes on three different networks at three different physical locations. I wanted all six Pi-holes to share the same blocklists, blacklists, whitelists, and regex files, but it was time-consuming to manually synchronize all of them.
I run six Pi-holes on three different networks at three different physical locations. I wanted all six Pi-holes to share the same blocklists, blacklists, whitelists, and regex files, but it was time-consuming to manually synchronize all of them (modify the local Pi-holes, VPN into the second network and modify those, then VPN into the third network and modify those).
I wanted to use Pi-hole's built-in web UI to manage only *one* set of lists on *one* Pi-hole -- and then securely synchronize an unlimited number of additional Pi-holes. I couldn't find an existing script that did exactly what I wanted... so I wrote `pihole-cloudsync`.
Feedback, suggestions, bug fixes, and code contributions are welcome.
# How pihole-cloudsync Works
`pihole-cloudsync` allows you to use any Pi-hole on any network to act as the "Master" or "Primary." This is the only Pi-hole whose list settings you will need to manage using Pi-hole's web UI. The Primary Pi-hole then uses `pihole-cloudsync` in **Push** mode to *upload* its blocklist, blacklist, whitelist, and regex files to a private Git repository that you control (such as GitHub).
`pihole-cloudsync` allows you to designate any Pi-hole on any network to act as your "Master" or "Primary." This is the only Pi-hole whose list settings you will need to manage using Pi-hole's built-in web UI. The Primary Pi-hole then uses `pihole-cloudsync` in **Push** mode to *upload* its blocklist, blacklist, whitelist, and regex files to a private Git repository that you control (such as GitHub).
All other Pi-holes that you wish to keep synchronized use `pihole-cloudsync` in **Pull** mode to *download* the Primary Pi-hole's blocklist, blacklist, whitelist, and regex files from your private Git repository.
All other Pi-holes that you wish to keep synchronized use `pihole-cloudsync` in **Pull** mode to *download* your Primary Pi-hole's blocklist, blacklist, whitelist, and regex files from your private Git repository.
The script is designed to work with any Git repo that your Pi-holes have access to, but I have only personally tested it with GitHub.
The script is designed to work with any Git repo that your Pi-holes can access, but I have only personally tested it with GitHub.
# Setup
Prior to running `pihole-cloudsync`, you must first create a new dedicated Git respository to store your lists, then clone that new repository to all Pi-holes (both Primary and Secondary) that you wish to keep in sync. The easiest way to do that is to fork my own `my-pihole-lists` GitHub repository. Don't worry if my personal lists in that repo are different than yours. You'll overwrite your forked version of the repo with your own Pi-hole lists the first time you run `pihole-cloudsync` in **Push** mode.
**On GitHub**
1. Sign into GitHub
2. Go to https://github.com/stevejenkins/my-pihole-lists
3. Press **Fork**
1. Sign into GitHub.
2. Go to https://github.com/stevejenkins/my-pihole-lists.
3. Press **Fork**.
4. Optional: If you wish to make your forked version of the repo private, press **Settings**, scroll down to the **Danger Zone**, then press **Make private**.
4. On your new repo's main page, press the **Clone or download** button and copy the **Clone with HTTPS** link to your clipboard.
**On your Primary Pi-hole device**
1. Install Git (on Raspbian/Debian do `sudo apt-get install git`)
2. Do `cd /usr/local/bin`
3. Install `pihole-cloudsync` with 'clone https://github.com/stevejenkins/pihole-cloudsync.git`
4. Create your private local Git repo with `clone https://github.com/<yourusername>/my-pihole-lists` (paste the URL you copied from GitHub)
1. Install Git (on Raspbian/Debian do `sudo apt-get install git`).
2. Do `cd /usr/local/bin`.
3. Install `pihole-cloudsync` with 'clone https://github.com/stevejenkins/pihole-cloudsync.git`.
4. Create your private local Git repo with `clone https://github.com/<yourusername>/my-pihole-lists` (paste the URL you copied from GitHub).
5. If you're using a repo name other than `my-pihole-lists`, edit `/usr/local/bin/pihole-cloudsync.sh` and edit the `personal_git_dir` variable to match your local Git repo location.
6. Run `/usr/local/bin/pihole-cloudsync --init` to copy your Primary Pi-hole's list files from `/etc/pihole` and add them to your new local Git repo. You only need to use the `--init` option on your Primary, since it's the only one that will "push" your lists to the remote Git repo.
7. Run `/usr/local/bin/pihole-cloudsync --push` to push/upload your Primary Pi-hole's list from your local Git repo to your remote Git repo. You will have to manually enter your GitHub email address and password the first time you do this, but read below for how to save your login credentials so you can run this script unattended.
@ -53,11 +53,11 @@ The SSH key approach is for more advanced users who don't need me to explain how
`cd /usr/local/bin/my-pihole-lists`
`git config --global credential.helper store`
`sudo git config --global credential.helper store`
The next time you pull from or push to the remote repository, you'll be prompted for your username and password. But you won't have to re-enter them after that. So do a simple:
`git pull`
`sudo git pull`
to enter and save your credentials. Now you can run `pihole-cloudsync` unattended on this Pi-hole device.