mirror of
https://github.com/vmstan/gravity-sync.git
synced 2024-08-30 18:22:11 +00:00
Start work on automation function
This commit is contained in:
Michael Stanclift
parent
905651ea71
commit
4f08472a6c
26
README.md
26
README.md
@ -1,7 +1,5 @@
|
||||
# Gravity Sync
|
||||
|
||||
## Background
|
||||
|
||||
What is better than a [Pi-hole](https://github.com/pi-hole/pi-hole) blocking ads via DNS on your network? That's right, Two Pi-hole! But if you have more than one Pi-hole (PH) in your network you'll want a simple way to keep the list configurations identical between the two.
|
||||
|
||||
That's Gravity Sync.
|
||||
@ -11,7 +9,6 @@ That's Gravity Sync.
|
||||
Gravity Sync will **not** overwrite device specific settings such as local network configuration, admin/API passwords/keys, local hostfiles, upstream DNS resolvers, etc. It will also **not** keep DHCP settings or device leases synchronized.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Gravity Sync **requires** Pi-hole 5.0 or higher.
|
||||
|
||||
You will need to designate one Pi-Hole as primary and one as secondary. This is where you'll make all your configuration changes through the Web UI, doing things such as; manual whitelisting, adding blocklists, device/group management, and other list settings. Gravity Sync will pull the configuration of the primary PH to the secondary. It will also bring over the downloaded blocklist files after a `pihole -g` update on the primary, so you do not need to reach out to all your blocklist hosts for updates after syncing.
|
||||
@ -24,13 +21,11 @@ Additionally, some things to consider:
|
||||
- Gravity Sync has not been tested with Docker container deployments of Pi-hole, and is not expected to work there without major modifications. You will need Pi-hole setup with a "traditional" install directly in the base operating system.
|
||||
|
||||
## Installation
|
||||
|
||||
The main purpose of this script is my own personal use, but if you find it helpful then I encourage you to use it and if you'd like provide feedback or contribute. As such, I'll lay out two ways to consume it. The first is more bleeding edge in that you'll download and run whatever the latest version of the script is on GitHub.
|
||||
|
||||
If this is too aggressive for you, maybe because you want to make changes to the script that are specific to your environment, or you're worried it'll blow something up, then please proceed to option 2.
|
||||
|
||||
### Option 1
|
||||
|
||||
Login to your *secondary* PH, and while in your users home directory, use `git` to clone the script to your server and keep the latest copy of the script on your server.
|
||||
|
||||
```
|
||||
@ -42,7 +37,6 @@ cd gravity-sync
|
||||
Proceed to the Configuration section.
|
||||
|
||||
### Option 2
|
||||
|
||||
So a life on the wildside of file sync isn't for you? That's fine.
|
||||
|
||||
Download the latest release from [GitHub](https://github.com/vmstan/gravity-sync/releases) and extract the files to your *secondary* PH server.
|
||||
@ -50,18 +44,16 @@ Download the latest release from [GitHub](https://github.com/vmstan/gravity-sync
|
||||
|
||||
```
|
||||
cd ~
|
||||
wget https://github.com/vmstan/gravity-sync/archive/v1.4.3.zip
|
||||
unzip v1.4.3.zip
|
||||
mv ~/gravity-sync-1.4.3 ~/gravity-sync
|
||||
wget https://github.com/vmstan/gravity-sync/archive/v1.4.4.zip
|
||||
unzip v1.4.4.zip
|
||||
mv ~/gravity-sync-1.4.4 ~/gravity-sync
|
||||
cd gravity-sync
|
||||
```
|
||||
|
||||
Please note the script **must** be run from a folder in your user home directory (ex: /home/USER/gravity-sync) -- I wouldn't suggest deviating from the gravity-sync folder name. If you do you'll need to also change the configuration settings defined in the `gravity-sync.sh` script, which can be a little tedious to do everytime you upgrade the script.
|
||||
|
||||
## Configuration
|
||||
|
||||
### The Easy Way
|
||||
|
||||
After you install Gravity Sync to your server (reguardless of the option you selected above) you will need to create a configuration file called `gravity-sync.conf` in the same folder as the script.
|
||||
|
||||
```
|
||||
@ -78,7 +70,6 @@ This will guide you through the process of:
|
||||
After you've completed your configuration, proceed to the Execution phase. Unless you feel like making this (slightly) harder on yourself.
|
||||
|
||||
### The Less Easy Way
|
||||
|
||||
There will be a file called `gravity-sync.conf.example` that you can use as the basis for your own `gravity-sync.conf` file. Make a copy of the example file and modify it with your site specific settings.
|
||||
|
||||
```
|
||||
@ -98,11 +89,9 @@ REMOTE_USER='pi'
|
||||
Do not set the `REMOTE_PASS` variable until you've read the next section on SSH.
|
||||
|
||||
### SSH Configuration
|
||||
|
||||
Gravity Sync uses SSH to run commands on the primary Pi-hole, and sync the two systems by performing file copies. There are two methods available for authenticating with SSH.
|
||||
|
||||
#### Key-Pair Authentication
|
||||
|
||||
This is the preferred option, as it's more reliable and less dependant on third party plugins.
|
||||
|
||||
You'll need to generate an SSH key for your secondary PH user and copy it to your primary PH. This will allow you to connect to and copy the gravity.db file without needing a password each time. When generating the SSH key, accept all the defaults and do not put a passphrase on your key file.
|
||||
@ -119,7 +108,6 @@ Subsitute REMOTE_USER for the account on the primary PH with sudo permissions, a
|
||||
Make sure to leave the `REMOTE_PASS` variable set to nothing in `gravity-sync.conf` if you want to use key-pair authentication.
|
||||
|
||||
#### Password Authentication
|
||||
|
||||
This is the non-preferred option, as it depends on an non-standard utility called `sshpass` which must be installed on your secondary PH. Install it using your package manage or choice. The example below is for Raspbian or Ubuntu.
|
||||
|
||||
```
|
||||
@ -137,7 +125,6 @@ Gravity Sync will validate that the `sshpass` utility is installed on your syste
|
||||
Save. Keep calm, carry on.
|
||||
|
||||
## Execution
|
||||
|
||||
Now test the script. You can run a comparison between the two which will be non-distruptive and see if everything has been configured correctly.
|
||||
|
||||
```
|
||||
@ -159,7 +146,6 @@ Finally, a file called `gravity-sync.log` will be created in the `gravity-sync`
|
||||
You can check for successful pull attempts by running: `./gravity-sync.sh logs`
|
||||
|
||||
## Failover
|
||||
|
||||
Gravity Sync includes the ability to `push` from the secondary PH back to the primary. This would be useful in a situation where your primary PH is down for an extended period of time, and you have made list changes on the secondary PH that you want to force back to the primary, when it comes online.
|
||||
|
||||
```
|
||||
@ -171,7 +157,6 @@ Before executing, this will make a copy of the remote database under `backup/gra
|
||||
This function purposefuly asks for user interaction to avoid being accidentally automated.
|
||||
|
||||
## Updates
|
||||
|
||||
If you installed via Option 1, you can run the built-in updater to get the latest version of all the files.
|
||||
|
||||
```
|
||||
@ -185,7 +170,6 @@ If you installed via Option 2, download and overwrite the `gravity-sync.sh` file
|
||||
The goal of Gravity Sync is to be simple, so any additional requirements should also be called out when it's executed. After updating, be sure to manually run a `./gravity-sync.sh compare` or `./gravity-sync.sh pull` to validate things are still working as expected. You can run a `./gravity-sync.sh config` at any time to generate a new configuration file.
|
||||
|
||||
## Automation
|
||||
|
||||
I've automated my synchronization using Crontab. If you'd like to keep this a manual process then ignore this section. By default my script will run at the top and bottom of every hour (1:00 PM, 1:30 PM, 2:00 PM, etc) but you are free to dial this back if you feel this is too aggressive by adjusting your cron timer.
|
||||
|
||||
As Gravity Sync won't make any changes if it doesn't detect a difference to sync, then it's impact should be minor to your systems.
|
||||
@ -208,7 +192,6 @@ If you'd like to see the log of what was run the last crontab, you can view that
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you are just straight up unable to run the `gravity-sync.sh` file, make sure it's marked as an executable by Linux.
|
||||
|
||||
```
|
||||
@ -219,5 +202,4 @@ chmod +x gravity-sync.sh
|
||||
- If you use a non-standard SSH port to connect to your primary Pi-hole, you can add `SSH_PORT='123'` to the bottom of your `gravity-sync.conf` file. (Subsitute 123 for your non-standard port.) This will overwrite the `SSH_PORT=22` at the top of the script as it is imported later in the execution.
|
||||
- If you'd like to know what version of the script you have running by running `./gravity-sync.sh version`
|
||||
- If the update script fails, make sure you did your original deployment via `git clone` and not a manual install.
|
||||
- If it doesn't kick off, you can manually execute a `git pull` while in the `gravity-sync` directory.
|
||||
|
||||
- If it doesn't kick off, you can manually execute a `git pull` while in the `gravity-sync` directory.
|
||||
@ -2,10 +2,10 @@
|
||||
|
||||
# GRAVITY SYNC BY VMSTAN #####################
|
||||
PROGRAM='Gravity Sync'
|
||||
VERSION='1.4.3'
|
||||
VERSION='1.4.4'
|
||||
|
||||
# Execute from the home folder of the user who own's it (ex: 'cd ~/gravity-sync')
|
||||
# For documentation or download updates visit https://github.com/vmstan/gravity-sync
|
||||
# Execute from the home folder of the user who owns it (ex: 'cd ~/gravity-sync')
|
||||
# For documentation or downloading updates visit https://github.com/vmstan/gravity-sync
|
||||
|
||||
# REQUIRED SETTINGS ##########################
|
||||
|
||||
@ -369,7 +369,6 @@ function validate_os_sshpass {
|
||||
echo -en "${STAT} ${MESSAGE}"
|
||||
timeout 5 ${SSHPASSWORD} ssh -p ${SSH_PORT} -i '$HOME/${SSH_PKIF}' -o StrictHostKeyChecking=no ${REMOTE_USER}@${REMOTE_HOST} 'exit' >/dev/null 2>&1
|
||||
error_validate
|
||||
|
||||
}
|
||||
|
||||
## Error Validation
|
||||
@ -403,7 +402,6 @@ function md5_compare {
|
||||
else
|
||||
echo -e "${INFO} Changes Detected in ${GRAVITY_FI}"
|
||||
fi
|
||||
|
||||
}
|
||||
|
||||
# Configuration Management
|
||||
@ -521,11 +519,7 @@ function config_delete {
|
||||
echo -e "${WARN} ${MESSAGE}"
|
||||
|
||||
echo -e "========================================================"
|
||||
echo -e "========================================================"
|
||||
echo -e ""
|
||||
cat $HOME/${LOCAL_FOLDR}/${CONFIG_FILE}
|
||||
echo -e ""
|
||||
echo -e "========================================================"
|
||||
echo -e "========================================================"
|
||||
|
||||
MESSAGE="Are you sure you want to erase this configuration?"
|
||||
@ -593,6 +587,18 @@ function show_version {
|
||||
echo -e "${INFO} ${PROGRAM} ${VERSION}"
|
||||
}
|
||||
|
||||
# Task Stack
|
||||
## Automate Task
|
||||
function task_automate {
|
||||
TASKTYPE='AUTOMATE'
|
||||
echo -e "\r${GOOD} ${MESSAGE}"
|
||||
|
||||
import_gs
|
||||
|
||||
|
||||
|
||||
}
|
||||
|
||||
# SCRIPT EXECUTION ###########################
|
||||
SCRIPT_START=$SECONDS
|
||||
|
||||
@ -694,7 +700,7 @@ case $# in
|
||||
;;
|
||||
|
||||
config)
|
||||
TASKTYPE='CONFIG'
|
||||
TASKTYPE='CONFIGURE'
|
||||
echo -e "\r${GOOD} ${MESSAGE}"
|
||||
echo -e "${INFO} Entering ${TASKTYPE} Mode"
|
||||
|
||||
@ -708,9 +714,15 @@ case $# in
|
||||
|
||||
config_generate
|
||||
fi
|
||||
|
||||
;;
|
||||
|
||||
|
||||
auto)
|
||||
task_automate
|
||||
;;
|
||||
|
||||
automate)
|
||||
task_automate
|
||||
;;
|
||||
|
||||
*)
|
||||
echo -e "\r${FAIL} ${MESSAGE}"
|
||||
|
||||
Loading…
Reference in New Issue
Block a user